Application Programming Interface of cyclic data

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

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

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

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

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

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().

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

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

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

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

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

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_miDmSingleWrite - Single Write

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

Returns a GOAL_STATUS_T status.

Table: goal_miDmSingleWrite arguments

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

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

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

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

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

goal_miDmSingleReadBufGet - Retrieve Direct Read Buffer

This function retrieve direct read buffer for access.

Returns a GOAL_STATUS_T status.

Table: goal_miDmSingleReadBufGet arguments

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

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

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

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

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

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

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

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