@CHIP-RTOS C Library - RTOS API

RTX_Publish

Post a tagged entry in the global data registry.

int far RTX_Publish ( const void *data, const char *nameTag );

Parameters

data: Pointer to global data to store under provided name tag. Set to NULL to remove an existing entry by this name tag. Alternatively, the SYSTEM_PUBLIC_OBJ(size) macro can be used here to allocate a new global data object owned by the system (See below).
nameTag: A zero terminated ASCII string (23 characters maximum length) to use as a unique identifier for the data.

Return Value

Zero on success, else error code:

RTX_EC_LOW_MEMORY (-9) - Memory allocation failed.

RTX_EC_NAME_NOT_FOUND (-57) - An attempt to delete an entry (i.e. data parameter was NULL) failed due to no entry with this name tag was found.

RTX_EC_CALL_ILLEGAL (-58) - Illegal call made from inside an ISR. (This API may only be called at task level.)

RTX_EC_NAME_IN_USE (-59) - Attempt to install data failed due to that the provided name tag is already in use by some previously published data.

Comments

This API allows you to record a pointer that will be held inside the @CHIP-RTOS-x86 with an associated name tag.   This pointer can then be retrieved by name from this registry by any program, thereby providing a form of communication between programs.

The data parameter has been declared const assuming other programs treat this object as read-only memory.   However programs are free to cast the return value from RTX_GetPublication() as they please.

A named publication can later be removed by calling this API with the name of the item to be removed and a NULL data argument.   When a task is deleted from the system, any global data entries which that task had installed will automatically be removed from the registry unless that data entry was installed using the SYSTEM_PUBLIC_OBJ macro technique explained below under the heading "System Global Data".

The name tag match is done in a case sensitive manner.   The maximum name length is 23 characters, not counting the terminating zero.   Any characters after this length will be ignored.   The system makes a copy of the nameTag string, so this string need not persist in your program after this API returns.

The MEM console command will list to the console the pointer, name tag and owner for each entry in the global data registry.

System Global Data

As mentioned above, when a task is removed from the system any global data registry entries made by that task will be automatically removed from the system's global data registry.   An exception to this rule is when the SYSTEM_PUBLIC_OBJ macro is used for the data argument.

In this case, the location of the global data object to be shared is not specified by the data argument.   Instead, this argument specifies the size of an object which the system should allocate for this new shared data object.   The object's size may range up to 0xFFC0 bytes.   The size is passed to this API in the offset portion of the far data pointer, as should be evident by inspecting the SYSTEM_PUBLIC_OBJ macro.   The segment portion of the data far pointer must be zero in order to trigger an allocation of the new shared data object by this API.

The usage of the SYSTEM_PUBLIC_OBJ macro would look something like as follows:

void *shared_data = NULL ;
if (RTX_Publish( SYSTEM_PUBLIC_OBJ( sizeof(struct MyStructType)), "MyName")
     == 0)
{
     shared_data = (struct MyStructType *)
               RTX_GetPublication( "MyName" ) ;
}

This newly allocated object will be initialized to all zero bytes by the system.   A pointer to this new object will then be stored in the registry under the specified name.   The user will need to follow a successful call to this API with a call to RTX_GetPublication() to discover where the new tagged object resides.

This new registry entry will be marked as owned by the system (specifically, the MTSK task) instead of the calling task.   This will cause the entry to persists until it is explicitly removed by some application program, or a system reset.

Peer to Peer Example:

When two programs want to share data and it is not clear which will be executing first, the while loop in example code below could be used to either install public data or retrieve the peer's public data for read/write access.

This while loop in the example attempts to cover for race conditions where the peer program has made an exit between the RTX_Publish() attempt and the RTX_GetPublication() call.   In this case both API's would fail on their first attempt.   But note that the issue of programs closing after clients have gained access to their public data can still lead to problems.   This would leave the client program with a reference to system memory which no longer is allocated (or has been reassigned to a subsequent program or system usage).   Defining the shared objects with the SYSTEM_PUBLIC_OBJ macro, as was discussed above is one way around this data persistence problem.

RTX_Publish() and RTX_GetPublication() are fully reentrant, so only one program will win a race to post data under the same name.


struct SharedDataT   // Only for an example
{
    int data ;
    // ... and more user defined contents can go here ...
} ;

struct SharedDataT *negotiatePublics(struct SharedDataT *myData,
                                     const char         *nameTag)
{
    while(1)
    {
        RTX_EC error = RTX_Publish(myData, nameTag) ;
        if (error == 0)
        {
            break ;             // We got here first.
        }
        else if (error == RTX_EC_NAME_IN_USE)
        {
            // Our peer program has already published.
            struct SharedDataT *peerData = (struct SharedDataT *)
                RTX_GetPublication(nameTag) ;
            if (peerData != NULL)
            {
                myData = peerData ;
                break ;
            }
            // Reach here under race condition, peer removed their data.
            // Will loop for another go.
        }
        else
        {
            printf("RTX_Publish() unepected error %d\r\n", error) ;
            myData = NULL ;     // Failure.
            break ;
        }
    }
    return myData ;
}

RTOS API

This library function invokes a RTOS software interrupt to install a dynamic link into the RTOS. Refer to this RTOS API function's documentation for more details.

Supported since or modified in @CHIP-RTOS version

SC12 SC13 SC11 SC1x3 SC2x n/a n/a n/a V1.35 V1.35

This API List
List of C Libraries
@CHIP-RTOS Main Index

End of document