Page Comparison

This chapter lists the API functions that are provided by GOAL’s MCTC. Next to a short description and the presentation of the function arguments additional notes are given.

Handling these arguments is simplified in the code examples.

MCTC API

goal_miMctcOpen - Open and activate mctc instance

This function opens an mctc instance. This enables sending and receiving.

Returns a GOAL_STATUS_T status.

Table: goal_miMctcOpen arguments

res = goal_miMctcOpen(&pInst, GOAL_ID_DEFAULT);

Remark: For compatibity reasons this function is also available as goal_rpcSetupChannel as part of the RPC api.

goal_miMctcCbRegReset - Register Reset Callback

This function registers a callback, triggered by MCTC when a reset is required. Multiple callbacks can be set, called one by another in order of registration.

Returns a GOAL_STATUS_T status.

Table: goal_miMctcCbRegReset arguments

res = goal_miMctcCbRegToutRx(appl_syncReset);

goal_miMctcCbRegToutRx - Register RX Timeout Callback

This function registers a callback, triggered by MCTC on receive timeout. Multiple callbacks can be set, called one by another in order of registration.

Returns a GOAL_STATUS_T status.

Table: goal_miMctcCbRegToutRx arguments

res = goal_miMctcCbRegToutRx(appl_syncTimeout);

goal_miMctcStatusGet - get the MCTC status

This function gets the status of the MCTC instance.

Returns GOAL_OK if MCTC is ready.

Table: goal_miMctcStatusGet arguments

res = goal_miMctcStatusGet(GOAL_ID_DEFAULT);
if (GOAL_RES_ERR(res)){
    return;
}

goal_miMctcInstGetById - Instance Get By Id

Based on the instance ID, this function returns the assigned MCTC handle.

Returns a GOAL_STATUS_T status.

Table: goal_miMctcInstGetById arguments

res = goal_miMctcInstGetById(&pMiMctcInst, GOAL_ID_DEFAULT);

goal_miMctcCfgTout - configure RPC timeout

This function sets the RPC timeout before creating a MCTC instance.

Returns a GOAL_STATUS_T status.

Table: goal_miMctcCfgTout arguments

A value of 0 disables the RPC timeout. This should only be uses for debugging. This function needs to be called before goal_miMctcOpen().

/* disable RPC timeout */
res = goal_miMctcCfgTout(0);

DM API

goal_miDmNew - New Instance

Creates a new GOAL MI DM instance. If ppMiDm isn't NULL the handle is returned.

Returns a GOAL_STATUS_T status.

Table: goal_miDmNew arguments

/* create a DM handle */
res = goal_miDmNew(&pMiDm, APPL_DM_ID, APPL_DM_BUFFER_LEN, "appl_dm");

goal_miDmGroupNew - Create a DM group

Creates a new group within DM handle. A group is used to keep partitions. If ppGroup is NULL no handle is returned.

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupNew arguments

/* create a DM handle */
 res = goal_miDmGroupNew(&pMiDmGroup, APPL_DM_ID, APPL_DM_ID_GROUP);

goal_miDmPartReg - Register Data Partition

This function attaches a new partition to existing one on the data buffer, named by DM handle ID. The partition is assigned to the named group.

GOAL logs the start position and length of a new partition to facilitate a review of data buffer configuration.

Note: Groups can only be created in the setup phase. If the memory allocation is already closed the call to goal_miDmGroupNew will fail if the group doesn’t exist.

Returns a GOAL_STATUS_T status.

Table: goal_miDmPartReg arguments

/* register MI DM partitions */
res = goal_miDmPartReg(GOAL_MI_MCTC_DIR_PEER_FROM, GOAL_ID_APPL,
                                        &mMiDmRead, sizeof(APPL_MSG_T));

goal_miDmPartIdxReg - Register Data Partition

This function occupies a partition on the data buffer, at the index position. If it is already in use, an error is raised. The partition is assigned to the named group.

GOAL logs the start position and length of a new partition to facilitate a review of data buffer configuration.

Note: Groups can only be created in the setup phase. If the memory allocation is already closed the call to goal_miDmGroupNew() will fail if the group doesn’t exist.

Returns a GOAL_STATUS_T status.

Table: goal_miDmPartIdxReg arguments

/* register MI DM partitions */
res = goal_miDmPartIdxReg(GOAL_MI_MCTC_DIR_PEER_FROM, GOAL_ID_APPL,
                                        &mMiDmRead, sizeof(APPL_MSG_T), 0);

goal_miDmPartSizeGet - Get Partition Size

This function returns the size of a registered partition. If the partition handle is invalid or not active, 0 is returned.

Table: goal_miDmPartSizeGet arguments

res = goal_miDmPartSizeGet(&mMiDmRead);

goal_miDmPartStatusGet - Get Partition Status

This function returns the status of a registered partition. If the partition handle is valid and active, GOAL_TRUE is returned.

Table: goal_miDmPartStatusGet arguments

GOAL_BOOL_T status;                             /* partition status */
status = goal_miDmPartStatusGet(&mMiDmRead);

goal_miDmSingleWrite - Single Write

Writing data to a single partition is done by this function.

Returns a GOAL_STATUS_T status.

Table: goal_miDmSingleWrite arguments

res = goal_miDmSingleWrite(&mMiDmWrite, (uint8_t *) &msgData,
    sizeof(APPL_MSG_T));

goal_miDmGroupPartWrite - Partition Write

Writing data to a partition is done by this function. The group has to be locked by goal_miDmGroupWriteStart() before and released by goal_miDmGroupWriteEnd() afterwards.

Warning: Writing to a single partitions write buffer isn’t thread safe if not locked by goal_miDmGroupWriteStart() and goal_miDmGroupWriteEnd().

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupPartWrite arguments

res = goal_miDmGroupPartWrite(&mMiDmWrite[cnt], &pData[cnt], len);

goal_miDmGroupWriteBufGet - Retrieve Direct Write Buffer

This function retrieve direct write buffer for access. The group has to be locked by goal_miDmGroupWriteStart() before and released by goal_miDmGroupWriteEnd() afterwards.

Warning: Writing to a single partitions write buffer isn’t thread safe if not locked by goal_miDmGroupWriteStart() and goal_miDmGroupWriteEnd().

The content of provided pointer is uncertain. It is neither empty nor holding old data. Ensure to write the complete buffer, invalid data will be exchanged otherwise.

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupWriteBufGet arguments

res = goal_miDmGroupWriteBufGet(&pBuf, &len, mMiDmWrite);

goal_miDmGroupWriteStart - Group Write Start

This function locks a group of partitions on the data buffer for updating them. Unlocking the group is done by goal_miDmGroupWriteEnd().

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupWriteStart arguments

res = goal_miDmGroupWriteStart(pMiMctc->pGroup);

goal_miDmGroupWriteEnd - Group Write Start

This function unlocks a group of partitions on the data buffer. Locking the group is done by goal_miDmGroupWriteStart.

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupWriteEnd arguments

res = goal_miDmGroupWriteEnd(pMiMctc->pGroup);

goal_miDmSingleRead - Single Read

Reading the data of a single partition is done by this function.

Returns a GOAL_STATUS_T status.

Table: goal_miDmSingleRead arguments

res = goal_miDmSingleRead(&mMiDmRead, (uint8_t *) &msgData);

goal_miDmSingleReadBufGet - Retrieve Direct Read Buffer

This function retrieve direct read buffer for access.

Returns a GOAL_STATUS_T status.

Table: goal_miDmSingleReadBufGet arguments

res = goal_miDmSingleReadBufGet(&pBuf, &len, &mMiDmRead);

goal_miDmGroupPartRead - Get Group Handle by Index

Reading data from a partition is done by this function. The group has to be locked by goal_miDmGroupReadStart() before and released by goal_miDmGroupReadEnd() afterwards.

Warning: Reading from a single partition isn’t thread safe if not locked by goal_miDmGroupReadStart() and goal_miDmGroupReadEnd().

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupPartRead arguments

res = goal_miDmGroupPartRead(&pGroup, &pData[cnt]);

goal_miDmGroupReadBufGet - Retrieve Direct Read Buffer

This function retrieve direct read buffer for access. The group has to be locked by goal_miDmGroupReadStart() before and released by goal_miDmGroupReadEnd() afterwards.

Warning: Reading from a single partition buffer isn’t thread safe if not locked by goal_miDmGroupReadStart() and goal_miDmGroupReadEnd().

Multiple calls of goal_miDmGroupReadBufGet() between the same goal_miDmGroupReadStart() and goal_miDmGroupReadEnd() correspond to the same process data image, i.e. the read data are consistent more than one read operations.

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupReadBufGet arguments

res = goal_miDmGroupReadBufGet(&pBuf, &len, mMiDmRead);

goal_miDmGroupReadStart - Group Read Start

This function locks a group of partitions on the data buffer for reading them. Unlocking the group is done by goal_miDmGroupReadEnd().

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupReadStart arguments

res = goal_miDmGroupReadStart(pMiMctc->pGroup);

goal_miDmGroupReadEnd - Group Read Start

This function unlocks a group of partitions on the data buffer. Locking the group is done by goal_miDmGroupReadStart().

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupReadEnd arguments

res = goal_miDmGroupReadEnd(pMiMctc->pGroup);

goal_miDmGroupGetByIdx - Get Group Handle by Index

This function is used to get the handle of a group.

Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupGetByIdx arguments

res = goal_miDmGroupGetByIdx(&pGroup, GOAL_MI_MCTC_DIR_PEER_FROM
    , GOAL_ID_APPL);

goal_miDmInstGetByPart - Get Instance By Part Handle

This function is used to get the DM handle of a partition handle.

Returns a GOAL_STATUS_T status.

Table: goal_miDmInstGetByPart arguments

res = goal_miDmInstGetByPart(&pDm, mMiDmRead);

goal_miDmCbReg - Register Callback

This function is used to register a callback, informing the application about any new incoming or outgoing data. Setting a MI DM handle callback is preferred over setting group callbacks. By keeping the MI DM handle as NULL, the callback is registered for a group.

Returns a GOAL_STATUS_T status.

Table: goal_miDmCbReg arguments

res = goal_miDmCbReg(NULL, pMiMctc->pGroup, GOAL_MI_DM_CB_READ,
    appl_dmCbCyclicRd, NULL);

goal_miDmGroupPartsRemove - Remove all mapped partitions

This function removes the mapped partitions of a named group. Returns a GOAL_STATUS_T status.

Table: goal_miDmGroupPartsRemove arguments

/* remove all partitions from group */
res = goal_miDmGroupPartsRemove(APPL_DM_ID, APPL_DM_ID_GROUP);