Application Programming Interface of acyclic data

This chapter lists the API functions that are provided by GOAL RPC. Next to a short description and the presentation of the function arguments, possible available macros are listed. They simplifying the RPC handling by e.g. error validation, but requires specific variables names.

Table: specific variable names of RPC macros

Name	Type	Description
res	GOAL_STATUS_T	result of GOAL functions
pHdlRpcChn	GOAL_RPC_HDL_CHN_T	RPC channel handle
pHdlRpc	GOAL_RPC_HDL_T	RPC handle

Handling these arguments is simplified in the code examples.

goal_rpcSetStackMax - Set the size of the RPC stack

This function configures the maximal size of the RPC stack in bytes.

As long as the RPC channel is not setup, this function can be called. The stack size can only be increased. If this function is not called, the stack size is set to GOAL_MI_MCTC_XFER_SIZE.

Returns a GOAL_STATUS_T status.

Table: goal_rpcSetStackMax arguments

Arguments	Description
unsigned int size	byte size of the RPC stack

res = goal_rpcSetStackMax(1000);

goal_rpcHdlMaxSet - Set maximum RPC handle count

This function configures the maximal count of RPC handles.

As long as the RPC channel is not setup, this function can be called. The stack size can only be increased. If this function is not called, the stack size is set to GOAL_MI_MCTC_HDL_CNT.

Returns a GOAL_STATUS_T status.

Table: goal_rpcHdlMaxSet arguments

Arguments	Description
unsigned int cntHdl	maximum handle count

res = goal_rpcHdlMaxSet(5);

goal_rpcStatus - Gets the status of RPC

This function checks, whether a suitable partner for communication was found and the exchange of data is possible.

Returns a GOAL_STATUS_T status.

Table: goal_rpcStatus arguments

Arguments	Description
unsigned int usageId	usage ID

res = goal_rpcStatus(GOAL_ID_MI_CTC_DEFAULT);
if (GOAL_RES_ERR(res)) {
    goal_logWarn("RPC is not ready.");
    return res;
}

goal_rpcNew - Gets a RPC handle

Get an empty RPC handle from the RPC channel handle and initialize it.

Returns a GOAL_STATUS_T status.

Notes: Its recommended to use the makro GOAL_RPC_NEW, because it simplify the call by an included failure check.

Table: goal_rpcNew arguments

Arguments	Description
GOAL_RPC_HDL_T **ppHdlRpc	[out] new RPC handle reference
GOAL_RPC_HDL_CHN_T *pHdlRpcChn	selected RPC channel handle

The following example shows the usage of goal_rpcNew.

The following example shows the usage of the macro GOAL_RPC_NEW.

goal_rpcClose - Close a RPC handle

This function closes the RPC handle.

The number of RPC handles is limited. Closing the handle is required by the client after he has received, and evaluated the response of the server. On server side, the handle is closed by GOAL automatically.

Returns a GOAL_STATUS_T status.

Table: goal_rpcClose arguments

Arguments	Description
GOAL_RPC_HDL_T *pHdlRpc	RPC handle

The following example shows the usage of goal_rpcClose.

The following example shows the usage of the macro GOAL_RPC_CLOSE.

goal_rpcCall - Calling the remote procedure

The RPC client calls the server by this function. It returns when receiving a response or a timeout occurs. Meanwhile, other GOAL tasks or loops are not block.

Possible RPC values has to be pushed to the RPC handle before calling this function.

The following 10 byte header is added automatically to the RPC transmission handle for a request.

Table: RPC request header.

4 byte	4 byte	2 byte	2 byte
function ID	RPC handle ID	MCTC message ID	flags

The following 8 byte header is added automatically to the RPC transmission handle for a response.

Table: RPC response header

4 byte	2 byte	2 byte
GOAL_STATUS_T of server	MCTC message ID	flags

Returns a GOAL_STATUS_T status.

Table: goal_rpcCall arguments

Arguments	Description
GOAL_RPC_HDL_T *pHdlRpc	RPC handle
uint32_t idGoal	GOAL ID
GOAL_RPC_FUNC_ID idFct	ID of the server function

The following example shows the usage of goal_rpcClall.

The following example shows the usage of the macro GOAL_RPC_USER_CALL. It is recommended to use this macro in user application. The remote function should be registered by GOAL_RPC_USER_REGISTER_SERVICE on server side.

goal_rpcRegisterService - Set a server function

Adds a the callback to the list of server functions. Incoming requests are compared by module ID and function ID selecting the correct entry. Registered functions can not be rewritten.

Returns a GOAL_STATUS_T status.

Table: goal_rpcRegisterService arguments

Arguments	Description
uint32_t idGoal	GOAL ID
GOAL_RPC_FUNC_ID idFct	ID of the selected function
GOAL_RPC_FUNC_T fctServer	pointer of the new server function

The following example shows the usage of goal_rpcRegisterService.

The following example shows the usage of the macro
GOAL_RPC_USER_REGISTER_SERVICE. It is recommended to use this macro in user application. The client request should be send by GOAL_RPC_USER_CALL.

goal_rpcSetupChannel - Setup a RPC channel

This function setups a RPC channel for transmission. The timeout of the RPC is defined by GOAL_MCTC_TIMEOUT_RX.

Returns a GOAL_STATUS_T status.

Table: goal_rpcSetupChannel arguments

Arguments	Description
GOAL_RPC_HDL_CHN_T **ppHdlRpcChn	[out] RPC channel handle
unsigned int usageId	usage ID

The following example shows the usage of goal_rpcSetupChannel.

goal_rpcArgPush - Push size x bytes to the stack

This function pushes size bytes to the transmission stack of the RPC handle. An error will be returned if the value doesn’t fit.

Pushing an argument by goal_rpcArgPush doesn’t care about the endianness. Please use GOAL_RPC_PUSH if uncertainties exist.

Returns a GOAL_STATUS_T status.

Notes:

The order of pushing arguments has to be vice versa of poping them.

The maximal argument size of the macro GOAL_RPC_PUSH is 32 bit.
Macros for pushing arrays are GOAL_RPC_PUSH_PTR or GOAL_RPC_PUSH_PTR_FGM. There will be no verification of endianness.
Pushing an array should be followed by push the length of the data. Thus, the foreign core can pop the length information and by the number of data afterwards.

Table: goal_rpcArgPush arguments

Arguments	Description
GOAL_RPC_HDL_T *pHdlRpc	RPC handle
const uint8 *pData	data
unsigned int len	data length

The following example shows the usage of goal_rpcArgPush by pushing the 16 bit variable var.

The following example shows the usage of the macro GOAL_RPC_PUSH by pushing the 16 bit variable var. The macro checks the status of res before transforming its argument to 32 bit big endianness and pushing it to the RPC stack.

The macro GOAL_RPC_PUSH_PTR pushes len data to the RPC stack.

goal_rpcArgPop - Pop size x bytes from the stack

This function pops size bytes from the receive stack of the RPC handle. An error will be returned if there are not enough bytes at the stack.

Poping an argument by goal_rpcArgPop doesn’t care about the endianness. Please use GOAL_RPC_POP if uncertainties exist.

Returns a GOAL_STATUS_T status.

Notes:

The order of poping arguments has to be vice versa of pushing them.

The maximal argument size of the macro GOAL_RPC_POP is 32 bit.

Pushing an array should be followed by push the length of the data. Thus, the foreign core can pop the length information and by the number of data afterwards.

Table: goal_rpcArgPop arguments

Arguments	Description
GOAL_RPC_HDL_T *pHdlRpc	RPC handle
uint8 *pData	[out] data
unsigned int len	data length

The following example shows the usage of goal_rpcArgPop by poping a 16 bit variable.

The following example shows the usage of the macro GOAL_RPC_POP by poping a 16 bit variable. The macro requires the data type as second argument.

It checks the status of res before poping 32 bit big endianness and transforming the endianness and type of the data.

The macro GOAL_RPC_POP_PTR pops len data from the RPC stack.

1 goal_rpcSetStackMax - Set the size of the RPC stack
2 goal_rpcHdlMaxSet - Set maximum RPC handle count
3 goal_rpcStatus - Gets the status of RPC
4 goal_rpcNew - Gets a RPC handle
5 goal_rpcClose - Close a RPC handle
6 goal_rpcCall - Calling the remote procedure
7 goal_rpcRegisterService - Set a server function
8 goal_rpcSetupChannel - Setup a RPC channel
9 goal_rpcArgPush - Push size x bytes to the stack
10 goal_rpcArgPop - Pop size x bytes from the stack