Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Code Block
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

Code Block
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

Code Block
languagec
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.

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

The following example shows the usage of the macro GOAL_RPC_NEW.

Code Block
languagec
/* 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

Arguments

Description

GOAL_RPC_HDL_T *pHdlRpc

RPC handle

The following example shows the usage of goal_rpcClose.

Code Block
goal_rpcClose(pHdlRpc);

The following example shows the usage of the macro GOAL_RPC_CLOSE.

Code Block
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.

Code Block
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.

Code Block
/* 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

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.

Code Block
languagec
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.

Code Block
languagec
/* 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

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.

Code Block
languagec
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

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.

Code Block
languagec
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.

Code Block
languagec
uint16_t var = 1234;
GOAL_RPC_PUSH(var);

The macro GOAL_RPC_PUSH_PTR pushes len data to the RPC stack.

Code Block
languagec
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

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.

Code Block
languagec
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.

Code Block
languagec
uint16_t var = 1234;
GOAL_RPC_POP(var, uint16_t);

The macro GOAL_RPC_POP_PTR pops len data from the RPC stack.

Code Block
languagec
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");
}
Table of Contents