fprime.h File Reference

#include <Fw/Deprecate.hpp>
#include <Fw/FPrimeBasicTypes.h>

Go to the source code of this file.

Macros
#define	WASM_IMPORT(module, name)
#define	WASM_MODULE_NAME   ("fprime_v1")

Enumerations
enum	FprimeTlmValid { FPRIME_TLM_VALID = 0, FPRIME_TLM_INVALID = 1 }
enum	FprimeParamValid { FPRIME_PARAM_UNINIT = 0, FPRIME_PARAM_VALID = 1, FPRIME_PARAM_INVALID = 2, FPRIME_PARAM_DEFAULT = 3 }
enum	FprimeCmdResponse {   FPRIME_CMD_OK = 0, FPRIME_CMD_INVALID_OPCODE = 1, FPRIME_CMD_VALIDATION_ERROR = 2, FPRIME_CMD_FORMAT_ERROR = 3,   FPRIME_CMD_EXECUTION_ERROR = 4, FPRIME_CMD_BUSY = 5, FPRIME_CMD_CLEARED = 6, FPRIME_CMD_DISPATCHED_UNTRACKED = 7 }
	Command response. Fw::CmdResponse in Fw/Cmd/Cmd.fpp. More...
enum	FprimeEventSeverity : I32 {   FPRIME_EVENT_FATAL = 1, FPRIME_EVENT_WARNING_HI = 2, FPRIME_EVENT_WARNING_LO = 3, FPRIME_EVENT_COMMAND = 4,   FPRIME_EVENT_ACTIVITY_HI = 5, FPRIME_EVENT_ACTIVITY_LO = 6, FPRIME_EVENT_DIAGNOSTIC = 7 }
enum	FprimeBlockingType { FPRIME_BLOCK_BLOCKING = 0, FPRIME_BLOCK_NONBLOCKING = 1 }
enum	FprimeQueueStatus { FPRIME_QUEUE_OK = 0, FPRIME_QUEUE_EMPTY = 1 }

Functions
void	fprime_wasm_exit (I32 code)
	Exit the current Wasm program with a return code. This function does not return. More...
void	fprime_wasm_panic (I32 code)
	Exit the current Wasm program with a failure. This function does not return. More...
U32	DEPRECATED (fprime_wasm_get_args(U32 destination_ptr, U32 destination_size), "args always returns 0. Pass inputs through the sequence's exported function signature instead")
	Deprecated no-op retained for binary compatibility with older guests. More...
void	fprime_wasm_get_time (U32 time_ptr, U32 time_size)
	Read the current F´ system time into guest memory. More...
FprimeTlmValid	fprime_wasm_read_telemetry (I64 id, U32 time_ptr, U32 time_size, U32 value_ptr, U32 value_size)
	Read a telemetry channel value and write it to the specified memory addresses. More...
FprimeParamValid	fprime_wasm_read_parameter (I64 id, U32 value_ptr, U32 value_size)
	Read a parameter value and write it to the specified memory addresses. More...
FprimeCmdResponse	fprime_wasm_command (U32 buf_ptr, U32 buf_size)
	Dispatch a command, blocking call. More...
void	fprime_wasm_event (FprimeEventSeverity severity, U32 msg_ptr, U32 msg_size)
	Emit an event from the current WasmSequencer component at a given severity level. More...
void	fprime_wasm_rsleep (U64 us)
	Pause the runtime for a specified time. More...
void	fprime_wasm_asleep (U64 us)
	Pause the runtime until a specified time. More...
void	fprime_wasm_serial_out (I32 index, U32 data_ptr, U32 data_size)
	Invoke a serial port If the port is not connected, the module will panic/trap. More...
FprimeQueueStatus	fprime_wasm_serial_receive (I32 index, U32 data_ptr, U32 data_size, U32 actual_size_ptr, FprimeBlockingType block_type)
	Receive a message from a serial input queue. More...

Macro Definition Documentation

WASM_IMPORT

#define WASM_IMPORT	(		module,
			name
	)

Definition at line 21 of file fprime.h.

WASM_MODULE_NAME

#define WASM_MODULE_NAME   ("fprime_v1")

Definition at line 24 of file fprime.h.

Enumeration Type Documentation

FprimeBlockingType

enum FprimeBlockingType

Enumerator
FPRIME_BLOCK_BLOCKING	Block the wasm execution until a message is received (subject to timeouts)
FPRIME_BLOCK_NONBLOCKING	If there are no messages in the queue, return immediately.

Definition at line 169 of file fprime.h.

FprimeCmdResponse

enum FprimeCmdResponse

Command response. Fw::CmdResponse in Fw/Cmd/Cmd.fpp.

Enumerator
FPRIME_CMD_OK	Command successfully executed.
FPRIME_CMD_INVALID_OPCODE	Invalid opcode dispatched.
FPRIME_CMD_VALIDATION_ERROR	Command failed validation.
FPRIME_CMD_FORMAT_ERROR	Command failed to deserialize.
FPRIME_CMD_EXECUTION_ERROR	Command had execution error.
FPRIME_CMD_BUSY	Component busy.
FPRIME_CMD_CLEARED	Command tracking was cleared before the command completed.
FPRIME_CMD_DISPATCHED_UNTRACKED	Command was dispatched but the response tracking failed, indicating unknown state.

Definition at line 101 of file fprime.h.

FprimeEventSeverity

enum FprimeEventSeverity : I32

Enumerator
FPRIME_EVENT_FATAL	A fatal non-recoverable event.
FPRIME_EVENT_WARNING_HI	A serious but recoverable event.
FPRIME_EVENT_WARNING_LO	A less serious but recoverable event.
FPRIME_EVENT_COMMAND	An activity related to commanding.
FPRIME_EVENT_ACTIVITY_HI	Important informational events.
FPRIME_EVENT_ACTIVITY_LO	Less important informational events.
FPRIME_EVENT_DIAGNOSTIC	Software diagnostic events.

Definition at line 130 of file fprime.h.

FprimeParamValid

enum FprimeParamValid

Parameter validity, mirroring Fw::ParamValid. Unlike telemetry (FprimeTlmValid, a two-state VALID/INVALID enum), a parameter read distinguishes four states, so it uses its own encoding. Note FPRIME_PARAM_VALID is 1, not 0.

Enumerator
FPRIME_PARAM_UNINIT	Parameter storage has not been initialized.
FPRIME_PARAM_VALID	Parameter has a valid value from the parameter database.
FPRIME_PARAM_INVALID	Parameter value is invalid (e.g. not found)
FPRIME_PARAM_DEFAULT	Parameter is serving its compiled-in default value.

Definition at line 82 of file fprime.h.

FprimeQueueStatus

enum FprimeQueueStatus

Enumerator
FPRIME_QUEUE_OK	Message was received and copied into the destination memory.
FPRIME_QUEUE_EMPTY	Empty queue with a NONBLOCKING request.

Definition at line 174 of file fprime.h.

FprimeTlmValid

enum FprimeTlmValid

Enumerator
FPRIME_TLM_VALID
FPRIME_TLM_INVALID

Definition at line 64 of file fprime.h.

Function Documentation

DEPRECATED()

U32 DEPRECATED	(	fprime_wasm_get_args(U32 destination_ptr, U32 destination_size)	,
		"args always returns 0. Pass inputs through the sequence's exported function signature instead"
	)

Deprecated no-op retained for binary compatibility with older guests.

The sequencer no longer passes arguments to a sequence. This import writes nothing to [destination_ptr] and always reports 0 bytes. A sequence that needs inputs should take them through its exported function signature instead.

Parameters

destination_ptr	Ignored
destination_size	Ignored

Returns

Always 0

fprime_wasm_asleep()

void fprime_wasm_asleep

(

U64

us

)

Pause the runtime until a specified time.

Parameters

us	Microseconds from system epoch to pause until

fprime_wasm_command()

FprimeCmdResponse fprime_wasm_command	(	U32	buf_ptr,
		U32	buf_size
	)

Dispatch a command, blocking call.

Command must be encoded with the FwOpcodeType + arguments. A FORMAT_ERROR will be returned if the format is not valid!

Parameters

buf_ptr	Guest memory address to encoded command
buf_size	Size allocated for value_ptr

fprime_wasm_event()

void fprime_wasm_event	(	FprimeEventSeverity	severity,
		U32	msg_ptr,
		U32	msg_size
	)

Emit an event from the current WasmSequencer component at a given severity level.

Parameters

severity	Event severity level to emit
msg_ptr	Guest memory address to event message string
msg_size	Size allocated for value_ptr

fprime_wasm_exit()

void fprime_wasm_exit

(

I32

code

)

Exit the current Wasm program with a return code. This function does not return.

Parameters

code	0 indicates success, any non-zero exit code will

fprime_wasm_get_time()

void fprime_wasm_get_time	(	U32	time_ptr,
		U32	time_size
	)

Read the current F´ system time into guest memory.

The host serializes an Fw::Time into the guest buffer.

Parameters

time_ptr	Guest memory address to write the serialized time
time_size	Size allocated for time_ptr, must equal Fw::Time::SERIALIZED_SIZE

fprime_wasm_panic()

void fprime_wasm_panic

(

I32

code

)

Exit the current Wasm program with a failure. This function does not return.

Parameters

code	Aribtrary code to indicate source of the panic

fprime_wasm_read_parameter()

FprimeParamValid fprime_wasm_read_parameter	(	I64	id,
		U32	value_ptr,
		U32	value_size
	)

Read a parameter value and write it to the specified memory addresses.

Parameters

id	Parameter ID to read
value_ptr	Guest memory address to parameters's value
value_size	Size allocated for value_ptr

Returns

Parameter validity (FprimeParamValid); value bytes are written when the parameter is present. This differs from the telemetry validity enum: FPRIME_PARAM_VALID is 1, not 0.

fprime_wasm_read_telemetry()

FprimeTlmValid fprime_wasm_read_telemetry	(	I64	id,
		U32	time_ptr,
		U32	time_size,
		U32	value_ptr,
		U32	value_size
	)

Read a telemetry channel value and write it to the specified memory addresses.

Parameters

id	Channel ID to read
time_ptr	Guest memory address to write channel update time
time_size	Size allocated for time_ptr, should be Fw::Time::SERIALIZED_SIZE
value_ptr	Guest memory address to channel's value
value_size	Size allocated for value_ptr

fprime_wasm_rsleep()

void fprime_wasm_rsleep

(

U64

us

)

Pause the runtime for a specified time.

Parameters

us	Microseconds to pause the runtime for

fprime_wasm_serial_out()

void fprime_wasm_serial_out	(	I32	index,
		U32	data_ptr,
		U32	data_size
	)

Invoke a serial port If the port is not connected, the module will panic/trap.

Parameters

index	Port index to emit on the serialOut on
data_ptr	Pointer to the data to send on the output port
data_size	Length of the data to send on the output port

fprime_wasm_serial_receive()

FprimeQueueStatus fprime_wasm_serial_receive	(	I32	index,
		U32	data_ptr,
		U32	data_size,
		U32	actual_size_ptr,
		FprimeBlockingType	block_type
	)

Receive a message from a serial input queue.

Parameters

index	Port number/queue index to receive message from
data_ptr	Pointer to the destination to write serial messages into
data_size	Size of the data_ptr memory. If a message is larger than this size, trap the wasm module
actual_size_ptr	(U32*). On message receive, number of bytes received will be written here (little endian)
block_type	Whether or not to block for a message when the queue on this index is empty

Returns

Status on whether or not we received a message (blocking will always return OK)