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

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

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

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

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

The following example shows the usage of goal_rpcNew.

/* get a new rpc handle */
res = goal_rpcNew(&pHdlRpc, pHdlRpcChn);

The following example shows the usage of the macro GOAL_RPC_NEW.

/* get a new rpc handle */
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

The following example shows the usage of goal_rpcClose.

goal_rpcClose(pHdlRpc);

The following example shows the usage of the macro GOAL_RPC_CLOSE.

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.

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

Table: RPC response header

Returns a GOAL_STATUS_T status.

Table: goal_rpcCall arguments

The following example shows the usage of goal_rpcClall.

res = goal_rpcCall(pHdlRpc, GOAL_ID_APPL, GOAL_RPC_FUNC_TEST);

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.

/* call the procedure at the server */
GOAL_RPC_USER_CALL(GOAL_RPC_FUNC_TEST);

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

The following example shows the usage of goal_rpcRegisterService.

res = goal_rpcRegisterService(GOAL_ID_APPL, GOAL_RPC_FUNC_TEST,
        &goal_rpcUserFunctionServer);

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.

/* setup the service function */
    GOAL_RPC_USER_REGISTER_SERVICE(GOAL_RPC_FUNC_TEST,
        &goal_rpcUserFunctionServer);

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

The following example shows the usage of goal_rpcSetupChannel.

res = goal_rpcSetupChannel(&pHdlRpcChn, GOAL_ID_APPL);

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

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

uint16_t var = 1234;
res = goal_rpcArgPush(pHdlRpc, &var, sizeof(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.

uint16_t var = 1234;
GOAL_RPC_PUSH(var);

The macro GOAL_RPC_PUSH_PTR pushes len data to the RPC stack.

uint8_t buffer[len];

/* fill buffer with data */
GOAL_RPC_PUSH_PTR(buffer, len);
if (GOAL_RES_ERR(res)) {
    goal_logErr("Unable to push the complete buffer");
}

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

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

uint16_t var = 0;
res = goal_rpcArgPop(pHdlRpc, (uint8_t *) &var, sizeof(var));

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.

uint16_t var = 1234;
GOAL_RPC_POP(var, uint16_t);

The macro GOAL_RPC_POP_PTR pops len data from the RPC stack.

uint16_t len = 12;
uint8_t buffer[len];

/* pop data from stack */

GOAL_RPC_POP_PTR(buffer, len);
if (GOAL_RES_ERR(res)) {
    goal_logErr("Unable to pop data");
}