Remote Procedure Call

Remote Procedure Call (RPC) is the method of executing a functionality on a peer core. The core sending the request is called client and the core providing the procedure is called server.

RPC is an upper layer function of Micro Core to Core (MCTC) used to exchange low priority or non-time-critical data.

GOAL fragments big data automatically and observes the exchange of packets by sequence counter. Missing fragments are retransmitted multiple times to ensure that the peer core receives the complete message.

Description of RPC example application

GOAL provides a simple RPC application located in appl/00410_goal/rpc. It shows the basic handling of initialization, transmission and receiving. The application merges the client and server side of a communication.

For demonstration, the variable varA and variable varB are transmitted to the server for multiplication. The client receives the result as variable varC and checks it.

The code examples of the following sections refer to this simple RPC application.

RPC as client

First of all, the client creates a RPC channel handle by goal_rpcSetupChannel during e.g. appl_şetup().

/* setup a channel for RPC init */
res = goal_rpcSetupChannel(&pHdlRpcChn, GOAL_ID_DEFAULT);

Afterwards a new RPC (transmission) handle can be requested by GOAL_RPC_NEW. It contains an empty RPC stack, which can be pushed with data by GOAL_RPC_PUSH. GOAL_RPC_USER_CALL calls the procedure at the server side by transfers the complete RPC stack to the peer core. After receiving a response, relevant data can to be poped from the RPC stack by GOAL_RPC_POP.

Finally, the requested RPC handle has to be closed by GOAL_RPC_CLOSE.

These steps are summary in goal_rpcUserFunction().

static GOAL_STATUS_T goal_rpcUserFunction(
    uint32_t *pVarC,                            /**< sum C */
    uint16_t varA,                              /**< variable A */
    uint16_t varB                               /**< variable B */
)
{
    GOAL_STATUS_T res = GOAL_OK;                /* result */
    GOAL_RPC_HDL_T *pHdlRpc = GOAL_RPC_HDL_NONE; /* call handle */

    /* get a new rpc handle */
    GOAL_RPC_NEW();

    /* push the value of Var A */
    GOAL_RPC_PUSH(varA);

    /* push the value of Var B */
    GOAL_RPC_PUSH(varB);

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

    /* pop the value of Var B */
    GOAL_RPC_POP(*pVarC, uint32_t);

    /* rpc is done successfully */
    GOAL_RPC_CLOSE();

    return res;
}

RPC as server

The server registers a callback to an user function ID by GOAL_RPC_USER_REGISTER_SERVICE.

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

All received RPC messages are compared to the function ID and a module ID, triggering the callback on a match. The server has to pop the arguments from the RPC handle and calls the requested function afterwards. Ensure, that the arguments has to be poped in reversed from the RPC handle as the client has pushed them.

Pointer arguments expecting a return value, like exemplary variable varC, have to be pushed to the RPC handle for response.

The return value of the server callback function is the return value of GOAL_RPC_USER_CALL on the client side, on a successful response transfer. Otherwise, the return value on the client side is a GOAL_STATUS_T error.

Defines and prototypes of RPC

The defines are located on GOAL Media Interface MCTC header at goal_media/goal_mi_mctc.h.

Table: RPC defines

define	description	default value
GOAL_MI_MCTC_HDL_CNT	RPC transmission handle count	4
GOAL_MI_MCTC_XFER_SIZE	RPC transfer size	32
GOAL_MI_MCTC_RPC_MAX_SEQ	maximum sequence	10
GOAL_MI_MCTC_RPC_CNT_RESEND	resend buffer count	1
GOAL_MI_MCTC_RPC_RECV_TOUT	receive timeout (in ms)	10

1 Description of RPC example application
- 1.1 RPC as client
- 1.2 RPC as server
2 Defines and prototypes of RPC