Skip to content

Commit

Permalink
Fix #777, Use MSG APIs - Docs
Browse files Browse the repository at this point in the history 
Update documentation to replace deprecated SB
APIs with MSG APIs
  • Loading branch information
@skliper
skliper committed Nov 4, 2020
1 parent 8514efa commit 1da6b3c
Show file tree
Hide file tree
Showing 3 changed files with 85 additions and 80 deletions.
138 changes: 71 additions & 67 deletions docs/cFE Application Developers Guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1216,7 +1216,7 @@ FILE: xx_app.c
void XX_AppMain(void)
{
uint32 RunStatus = CFE_ES_RunStatus_APP_RUN;
CFE_SB_MsgPtr_t MsgPtr;
CFE_MSG_Message_t *MsgPtr;
int32 Result = CFE_SUCCESS;
/* Register application */
Expand Down Expand Up @@ -1319,18 +1319,18 @@ SB Messages by allocating sufficient memory, calling the SB API to
initialize the contents of the SB Message and then storing any
appropriate data into the structure.

The Software Bus API hides the details of the message structure,
providing routines such as CFE_SB_GetMsgTime and CFE_SB_SetMsgTime
The Message API hides the details of the message structure,
providing routines such as CFE_MSG_GetMsgTime and CFE_MSG_SetMsgTime
in order to get and set a message time. The current version of the cFE
supports only CCSDS, however, the implementation of the message
structure can be changed without affecting cFS Applications.

In the CCSDS implementation of the Software Bus, the upper 3 most
significant bits of the 16 bit Message ID Number **shall be zero
(b'000').** The Software Bus ignores the upper 3 most significant bits
defined by CCSDS as the Version Number. A non-zero value in the Version
Number (3 bits) could result in duplicate Message IDs being defined. For
example, x01FF and x81FF are the same Message ID to the Software Bus.
See the implementation documentation for specific formats,
fields, and bit values. The message ID (MsgId) is an abstract
concept that is implementation depended, used for routing messages
on the Software Bus. Depending on the implementation, different
ranges and values are supported, and the values effect the message
header differently.

##### 6.1.2 Pipes

Expand Down Expand Up @@ -1646,10 +1646,9 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
int32 Status;
...
Status = CFE_SB_InitMsg(&SAMPLE_AppData.HkPacket, /* Address of SB Message Data Buffer */
SAMPLE_HK_TLM_MID, /* SB Message ID associated with Data */
sizeof(SAMPLE_HkPacket_t), /* Size of Buffer */
CFE_SB_CLEAR_DATA); /* Buffer should be cleared by cFE */
Status = CFE_MSG_Init(&SAMPLE_AppData.HkPacket, /* Address of SB Message Data Buffer */
SAMPLE_HK_TLM_MID, /* SB Message ID associated with Data */
sizeof(SAMPLE_HkPacket_t)); /* Size of Buffer */
...
}
```
Expand All @@ -1660,7 +1659,7 @@ the SB Message was to be a command message, it would have been important
for the Developer to have used the CFE_SB_CMD_HDR_SIZE macro
instead.

The CFE_SB_InitMsg API call formats the SB Message Header
The CFE_MSG_Init API call formats the Message Header
appropriately with the given SB Message ID, size and, in this case,
clears the data portion of the SB Message (CFE_SB_CLEAR_DATA).
Another option for the fourth parameter is CFE_SB_NO_CLEAR which
Expand Down Expand Up @@ -1706,74 +1705,80 @@ It is important to note that some SB API calls assume the presence of a
particular header type and will not work properly if the other header type
is present instead. The following section provides more detail.

##### 6.5.2 Modifying Software Bus Message Header Information
##### 6.5.2 Setting Message Header Information

Before sending an SB Message to the SB, the Application can update the
SB Message Header. The following table summarizes the functions that
can be used to modify SB Message Header fields. Note that some of these
Before sending a Message to the SB, the Application can set fields in the
Message Header. The following table summarizes the functions that
can be used to modify Message Header fields. Note that some of these
functions are only applicable to a specific header type. Additional
information on modifying specific header types is provided in the following
subsections.

| **SB Message Header Field** | **SB API for Modifying the Header Field** | **Applicability** |
| ---------------------------:| -----------------------------------------:| -------------------:|
| Message ID | CFE_SB_SetMsgId | Command & Telemetry |
| Total Message Length | CFE_SB_SetTotalMsgLength | Command & Telemetry |
| User Data Message Length | CFE_SB_SetUserDataLength | Command & Telemetry |
| Command Code | CFE_SB_SetCmdCode | Command Only |
| Checksum | CFE_SB_GenerateChecksum | Command Only |
| Time | CFE_SB_TimeStampMsg | Telemetry Only |
| Time | CFE_SB_SetMsgTime | Telemetry Only |

Applications shall always use these functions to manipulate the SB
Message Header. The structure of the SB Message Header may change from
| **SB Message Header Field** | **API for Modifying the Header Field** | **Applicability** |
| ---------------------------:| --------------------------------------:| -------------------:|
| Message ID | CFE_MSG_SetMsgId | Command & Telemetry |
| Total Message Length | CFE_MSG_SetSize | Command & Telemetry |
| Command Code | CFE_MSG_SetFcnCode | Command Only |
| Checksum | CFE_MSG_GenerateChecksum | Command Only |
| Time | CFE_SB_TimeStampMsg | Telemetry Only |
| Time | CFE_MSG_SetMsgTime | Telemetry Only |

Applications shall always use these functions to manipulate the
Message Header. The structure of the Message Header may change from
one deployment to the next. By using these functions, Applications are
guaranteed to work regardless of the structure of the SB Message Header.
guaranteed to work regardless of the structure of the Message Header.

##### 6.5.2.1 Modifying SB Command Message Header Information
Although CFE_SB_SetUserDataLength APIs is available,
it is based on assumptions about the defintion of "User Data" and is
really just a best guess since the packet structure is dependent on implementation.
The preference is to use CFE_MSG_SetSize and actual packet structure
information when available.

##### 6.5.2.1 Modifying Command Message Header Information
The most common update for command messages is to set the command code.
This is done through the CFE_SB_SetCmdCode() API call. This code is used
This is done through the CFE_MSG_SetFcnCode() API call. This code is used
to distinguish between multiple commands that share a Message ID. It is
common practice for an application to have a single "CMD_MID" to capture
all commands and then to differentiate those commands using a command code.

##### 6.5.2.2 Modifying SB Telemetry Message Header Information
##### 6.5.2.2 Modifying Telemetry Message Header Information
The most common update for telemetry messages is to put the current time in
the SB Message. This is accomplished with one of two SB API functions. The
the Message. This is accomplished with one of two API functions. The
most commonly used function would be CFE_SB_TimeStampMsg(). This API would
insert the current time, in the mission defined format with the mission
defined epoch, into the SB Message Header. The other SB API that can modify
the SB Message Header time is CFE_SB_SetMsgTime(). This API call sets the
time in the SB Message Header to the time specified during the call. This is
useful when the Application wishes to time tag a series of SB Messages with
defined epoch, into the Message Header. The other API that can modify
the Message Header time is CFE_MSG_SetMsgTime(). This API call sets the
time in the Message Header to the time specified during the call. This is
useful when the Application wishes to time tag a series of Messages with
the same time.

##### 6.5.3 Reading Software Bus Message Header Information
##### 6.5.3 Reading Message Header Information

There are several SB APIs available for extracting the SB Message Header
There are several APIs available for extracting the Message Header
Fields. These APIs shall always be used by Applications to ensure the
Applications are portable to future missions. The following table
identifies the fields of the SB Message Header and the appropriate API
identifies the fields of the Message Header and the appropriate API
for extracting that field from the header:

| **SB Message Header Field** | **SB API for Reading the Header Field** | **Applicability** |
|:----------------------------|:----------------------------------------|:--------------------|
| Message ID | CFE_SB_GetMsgId | Command & Telemetry |
| Message Time | CFE_SB_GetMsgTime | Telemetry Only |
| Total Message Length | CFE_SB_GetTotalMsgLength | Command & Telemetry |
| User Data Message Length | CFE_SB_GetUserDataLength | Command & Telemetry |
| Command Code | CFE_SB_GetCmdCode | Command Only |
| Checksum | CFE_SB_GetChecksum | Command Only |

In addition to the function for reading the checksum field, there is
another API that automatically calculates the checksum for the packet
| **SB Message Header Field** | **API for Reading the Header Field** | **Applicability** |
|:----------------------------|:-------------------------------------|:--------------------|
| Message ID | CFE_MSG_GetMsgId | Command & Telemetry |
| Message Time | CFE_MSG_GetTime | Imp. Dependent |
| Total Message Length | CFE_MSG_GetSize | Command & Telemetry |
| Command Code | CFE_MSG_GetFcnCode | Command Only |

There are other APIs based on selected implementation. The full list is
available in the user's guide.

There is another API that automatically calculates the checksum for the packet
and compares it to the checksum in the header. The API is called
CFE_SB_ValidateChecksum() and it simply returns a success or failure
CFE_MSG_ValidateChecksum() and it simply returns a success or failure
indication.

If the Application's data structure definitions don't include the header
information, then the CFE_SB_GetUserData API could be used to obtain
the start address of the SB Message data.
Although CFE_SB_GetUserDataLength and CFE_SB_GetUserData APIs are available,
they are based on assumptions about the defintion of "User Data" and are
really just a best guess since the packet structure is dependent on implementation.
The preference is to use the actual packet structure when available.

#### 6.6 Sending Software Bus Messages

Expand All @@ -1799,8 +1804,8 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
/*
** Send housekeeping SB Message after time tagging it with current time
*/
CFE_SB_TimeStampMsg((CFE_SB_Msg_t *) &SAMPLE_AppData.HkPacket);
CFE_SB_SendMsg((CFE_SB_Msg_t *) &SAMPLE_AppData.HkPacket);
CFE_SB_TimeStampMsg((CFE_MSG_Message_t *) &SAMPLE_AppData.HkPacket);
CFE_SB_SendMsg((CFE_MSG_Message_t *) &SAMPLE_AppData.HkPacket);
...
}
```
Expand All @@ -1816,8 +1821,8 @@ FILE: sample_app.h
typedef struct
{
...
CFE_SB_MsgPtr_t MsgPtr;
CFE_SB_PipeId_t CmdPipe;
CFE_MSG_Message_t *MsgPtr;
CFE_SB_PipeId_t CmdPipe;
...
} SAMPLE_AppData_t;
```
Expand Down Expand Up @@ -1945,10 +1950,9 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
** Get a SB Message block of memory and initialize it
*/
SAMPLE_AppData.BigPktPtr = (SAMPLE_BigPkt_t *)CFE_SB_ZeroCopyGetPtr(SAMPLE_BIGPKT_MSGLEN);
CFE_SB_InitMsg((CFE_SB_Msg_t *) SAMPLE_AppData.BigPktPtr,
SAMPLE_BIG_TLM_MID,
SAMPLE_BIGPKT_MSGLEN,
CFE_SB_CLEAR_DATA);
CFE_MSG_Init((CFE_MSG_Message_t *) SAMPLE_AppData.BigPktPtr,
SAMPLE_BIG_TLM_MID,
SAMPLE_BIGPKT_MSGLEN);
/*
** ...Fill Packet with Data...
Expand All @@ -1957,8 +1961,8 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
/*
** Send SB Message after time tagging it with current time
*/
CFE_SB_TimeStampMsg((CFE_SB_Msg_t *) SAMPLE_AppData.BigPktPtr);
CFE_SB_ZeroCopySend((CFE_SB_Msg_t *) SAMPLE_AppData.BigPktPtr);
CFE_SB_TimeStampMsg((CFE_MSG_Message_t *) SAMPLE_AppData.BigPktPtr);
CFE_SB_ZeroCopySend((CFE_MSG_Message_t *) SAMPLE_AppData.BigPktPtr);
/* SAMPLE_AppData.BigPktPtr is no longer a valid pointer */
...
}
Expand Down
25 changes: 13 additions & 12 deletions docs/src/cfe_api.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -146,30 +146,31 @@
</UL>
<LI> \ref CFEAPISBSetMessage
<UL>
<LI> #CFE_SB_InitMsg - \copybrief CFE_SB_InitMsg
<LI> #CFE_SB_SetMsgId - \copybrief CFE_SB_SetMsgId
<LI> #CFE_MSG_Init - \copybrief CFE_MSG_Init
<LI> #CFE_MSG_SetMsgId - \copybrief CFE_MSG_SetMsgId
<LI> #CFE_SB_SetUserDataLength - \copybrief CFE_SB_SetUserDataLength
<LI> #CFE_SB_SetTotalMsgLength - \copybrief CFE_SB_SetTotalMsgLength
<LI> #CFE_SB_SetMsgTime - \copybrief CFE_SB_SetMsgTime
<LI> #CFE_MSG_SetSize - \copybrief CFE_MSG_SetSize
<LI> #CFE_MSG_SetMsgTime - \copybrief CFE_MSG_SetMsgTime
<LI> #CFE_SB_TimeStampMsg - \copybrief CFE_SB_TimeStampMsg
<LI> #CFE_SB_SetCmdCode - \copybrief CFE_SB_SetCmdCode
<LI> #CFE_MSG_SetFcnCode - \copybrief CFE_MSG_SetFcnCode
<LI> #CFE_MSG_SetSequenceCount - \copybrief CFE_MSG_SetSequenceCount
<LI> #CFE_SB_MessageStringSet - \copybrief CFE_SB_MessageStringSet
</UL>
<LI> \ref CFEAPIGetMessage
<UL>
<LI> #CFE_SB_GetUserData - \copybrief CFE_SB_GetUserData
<LI> #CFE_SB_GetMsgId - \copybrief CFE_SB_GetMsgId
<LI> #CFE_MSG_GetMsgId - \copybrief CFE_MSG_GetMsgId
<LI> #CFE_SB_GetUserDataLength - \copybrief CFE_SB_GetUserDataLength
<LI> #CFE_SB_GetTotalMsgLength - \copybrief CFE_SB_GetTotalMsgLength
<LI> #CFE_SB_GetMsgTime - \copybrief CFE_SB_GetMsgTime
<LI> #CFE_SB_GetCmdCode - \copybrief CFE_SB_GetCmdCode
<LI> #CFE_MSG_GetSize - \copybrief CFE_MSG_GetSize
<LI> #CFE_MSG_GetMsgTime - \copybrief CFE_MSG_GetMsgTime
<LI> #CFE_MSG_GetFcnCode - \copybrief CFE_MSG_GetFcnCode
<LI> #CFE_MSG_GetTypeFromMsgId - \copybrief CFE_MSG_GetTypeFromMsgId
<LI> #CFE_SB_MessageStringGet - \copybrief CFE_SB_MessageStringGet
</UL>
<LI> \ref CFEAPISBChecksum
<UL>
<LI> #CFE_SB_GenerateChecksum - \copybrief CFE_SB_GenerateChecksum
<LI> #CFE_SB_GetChecksum - \copybrief CFE_SB_GetChecksum
<LI> #CFE_SB_ValidateChecksum - \copybrief CFE_SB_ValidateChecksum
<LI> #CFE_MSG_GenerateChecksum - \copybrief CFE_MSG_GenerateChecksum
<LI> #CFE_MSG_ValidateChecksum - \copybrief CFE_MSG_ValidateChecksum
</UL>
<LI> \ref CFEAPISBMessageID
<UL>
Expand Down
2 changes: 1 addition & 1 deletion docs/src/cfe_sb.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -529,7 +529,7 @@
can get confusing. How can I be sure that the correct address is given for this
parameter.
</B><TR><TD WIDTH="5%"> &nbsp; <TD WIDTH="95%">
Typically a caller declares a ptr of type CFE_SB_Msg_t (i.e. CFE_SB_Msg_t *Ptr)
Typically a caller declares a ptr of type CFE_MSG_Message_t (i.e. CFE_MSG_Message_t *Ptr)
then gives the address of that pointer (&Ptr) as this parameter. After a successful
call to #CFE_SB_RcvMsg, Ptr will point to the first byte of the software bus message
header. This should be used as a read-only pointer. In systems with an MMU, writes
Expand Down

0 comments on commit 1da6b3c

Please sign in to comment.