Skip to content

Commit 7b9db48

Browse files
jphickeyastrogeco
jphickey
authored and
astrogeco
committed
Merge pull request nasa#1028 from nasa/fix777-deprecate-sb
Fix nasa#777, Use MSG APIs - Core software Fix nasa#777, Use MSG APIs - Docs Fix nasa#777, Use MSG APIs - Unit tests See nasa/cFE#998 for more details
2 parents 5ae7613 + 34e5510 commit 7b9db48

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+918
-2004
lines changed

‎docs/cFE Application Developers Guide.md‎

Lines changed: 71 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1216,7 +1216,7 @@ FILE: xx_app.c
12161216
void XX_AppMain(void)
12171217
{
12181218
uint32 RunStatus = CFE_ES_RunStatus_APP_RUN;
1219-
CFE_SB_MsgPtr_t MsgPtr;
1219+
CFE_MSG_Message_t *MsgPtr;
12201220
int32 Result = CFE_SUCCESS;
12211221
12221222
/* Register application */
@@ -1319,18 +1319,18 @@ SB Messages by allocating sufficient memory, calling the SB API to
13191319
initialize the contents of the SB Message and then storing any
13201320
appropriate data into the structure.
13211321

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

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

13351335
##### 6.1.2 Pipes
13361336

@@ -1646,10 +1646,9 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
16461646
int32 Status;
16471647
16481648
...
1649-
Status = CFE_SB_InitMsg(&SAMPLE_AppData.HkPacket, /* Address of SB Message Data Buffer */
1650-
SAMPLE_HK_TLM_MID, /* SB Message ID associated with Data */
1651-
sizeof(SAMPLE_HkPacket_t), /* Size of Buffer */
1652-
CFE_SB_CLEAR_DATA); /* Buffer should be cleared by cFE */
1649+
Status = CFE_MSG_Init(&SAMPLE_AppData.HkPacket, /* Address of SB Message Data Buffer */
1650+
SAMPLE_HK_TLM_MID, /* SB Message ID associated with Data */
1651+
sizeof(SAMPLE_HkPacket_t)); /* Size of Buffer */
16531652
...
16541653
}
16551654
```
@@ -1660,7 +1659,7 @@ the SB Message was to be a command message, it would have been important
16601659
for the Developer to have used the CFE_SB_CMD_HDR_SIZE macro
16611660
instead.
16621661

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

1709-
##### 6.5.2 Modifying Software Bus Message Header Information
1708+
##### 6.5.2 Setting Message Header Information
17101709

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

1718-
| **SB Message Header Field** | **SB API for Modifying the Header Field** | **Applicability** |
1719-
| ---------------------------:| -----------------------------------------:| -------------------:|
1720-
| Message ID | CFE_SB_SetMsgId | Command & Telemetry |
1721-
| Total Message Length | CFE_SB_SetTotalMsgLength | Command & Telemetry |
1722-
| User Data Message Length | CFE_SB_SetUserDataLength | Command & Telemetry |
1723-
| Command Code | CFE_SB_SetCmdCode | Command Only |
1724-
| Checksum | CFE_SB_GenerateChecksum | Command Only |
1725-
| Time | CFE_SB_TimeStampMsg | Telemetry Only |
1726-
| Time | CFE_SB_SetMsgTime | Telemetry Only |
1727-
1728-
Applications shall always use these functions to manipulate the SB
1729-
Message Header. The structure of the SB Message Header may change from
1717+
| **SB Message Header Field** | **API for Modifying the Header Field** | **Applicability** |
1718+
| ---------------------------:| --------------------------------------:| -------------------:|
1719+
| Message ID | CFE_MSG_SetMsgId | Command & Telemetry |
1720+
| Total Message Length | CFE_MSG_SetSize | Command & Telemetry |
1721+
| Command Code | CFE_MSG_SetFcnCode | Command Only |
1722+
| Checksum | CFE_MSG_GenerateChecksum | Command Only |
1723+
| Time | CFE_SB_TimeStampMsg | Telemetry Only |
1724+
| Time | CFE_MSG_SetMsgTime | Telemetry Only |
1725+
1726+
Applications shall always use these functions to manipulate the
1727+
Message Header. The structure of the Message Header may change from
17301728
one deployment to the next. By using these functions, Applications are
1731-
guaranteed to work regardless of the structure of the SB Message Header.
1729+
guaranteed to work regardless of the structure of the Message Header.
17321730

1733-
##### 6.5.2.1 Modifying SB Command Message Header Information
1731+
Although CFE_SB_SetUserDataLength APIs is available,
1732+
it is based on assumptions about the defintion of "User Data" and is
1733+
really just a best guess since the packet structure is dependent on implementation.
1734+
The preference is to use CFE_MSG_SetSize and actual packet structure
1735+
information when available.
1736+
1737+
##### 6.5.2.1 Modifying Command Message Header Information
17341738
The most common update for command messages is to set the command code.
1735-
This is done through the CFE_SB_SetCmdCode() API call. This code is used
1739+
This is done through the CFE_MSG_SetFcnCode() API call. This code is used
17361740
to distinguish between multiple commands that share a Message ID. It is
17371741
common practice for an application to have a single "CMD_MID" to capture
17381742
all commands and then to differentiate those commands using a command code.
17391743

1740-
##### 6.5.2.2 Modifying SB Telemetry Message Header Information
1744+
##### 6.5.2.2 Modifying Telemetry Message Header Information
17411745
The most common update for telemetry messages is to put the current time in
1742-
the SB Message. This is accomplished with one of two SB API functions. The
1746+
the Message. This is accomplished with one of two API functions. The
17431747
most commonly used function would be CFE_SB_TimeStampMsg(). This API would
17441748
insert the current time, in the mission defined format with the mission
1745-
defined epoch, into the SB Message Header. The other SB API that can modify
1746-
the SB Message Header time is CFE_SB_SetMsgTime(). This API call sets the
1747-
time in the SB Message Header to the time specified during the call. This is
1748-
useful when the Application wishes to time tag a series of SB Messages with
1749+
defined epoch, into the Message Header. The other API that can modify
1750+
the Message Header time is CFE_MSG_SetMsgTime(). This API call sets the
1751+
time in the Message Header to the time specified during the call. This is
1752+
useful when the Application wishes to time tag a series of Messages with
17491753
the same time.
17501754

1751-
##### 6.5.3 Reading Software Bus Message Header Information
1755+
##### 6.5.3 Reading Message Header Information
17521756

1753-
There are several SB APIs available for extracting the SB Message Header
1757+
There are several APIs available for extracting the Message Header
17541758
Fields. These APIs shall always be used by Applications to ensure the
17551759
Applications are portable to future missions. The following table
1756-
identifies the fields of the SB Message Header and the appropriate API
1760+
identifies the fields of the Message Header and the appropriate API
17571761
for extracting that field from the header:
17581762

1759-
| **SB Message Header Field** | **SB API for Reading the Header Field** | **Applicability** |
1760-
|:----------------------------|:----------------------------------------|:--------------------|
1761-
| Message ID | CFE_SB_GetMsgId | Command & Telemetry |
1762-
| Message Time | CFE_SB_GetMsgTime | Telemetry Only |
1763-
| Total Message Length | CFE_SB_GetTotalMsgLength | Command & Telemetry |
1764-
| User Data Message Length | CFE_SB_GetUserDataLength | Command & Telemetry |
1765-
| Command Code | CFE_SB_GetCmdCode | Command Only |
1766-
| Checksum | CFE_SB_GetChecksum | Command Only |
1767-
1768-
In addition to the function for reading the checksum field, there is
1769-
another API that automatically calculates the checksum for the packet
1763+
| **SB Message Header Field** | **API for Reading the Header Field** | **Applicability** |
1764+
|:----------------------------|:-------------------------------------|:--------------------|
1765+
| Message ID | CFE_MSG_GetMsgId | Command & Telemetry |
1766+
| Message Time | CFE_MSG_GetTime | Imp. Dependent |
1767+
| Total Message Length | CFE_MSG_GetSize | Command & Telemetry |
1768+
| Command Code | CFE_MSG_GetFcnCode | Command Only |
1769+
1770+
There are other APIs based on selected implementation. The full list is
1771+
available in the user's guide.
1772+
1773+
There is another API that automatically calculates the checksum for the packet
17701774
and compares it to the checksum in the header. The API is called
1771-
CFE_SB_ValidateChecksum() and it simply returns a success or failure
1775+
CFE_MSG_ValidateChecksum() and it simply returns a success or failure
17721776
indication.
17731777

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

17781783
#### 6.6 Sending Software Bus Messages
17791784

@@ -1799,8 +1804,8 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
17991804
/*
18001805
** Send housekeeping SB Message after time tagging it with current time
18011806
*/
1802-
CFE_SB_TimeStampMsg((CFE_SB_Msg_t *) &SAMPLE_AppData.HkPacket);
1803-
CFE_SB_SendMsg((CFE_SB_Msg_t *) &SAMPLE_AppData.HkPacket);
1807+
CFE_SB_TimeStampMsg((CFE_MSG_Message_t *) &SAMPLE_AppData.HkPacket);
1808+
CFE_SB_SendMsg((CFE_MSG_Message_t *) &SAMPLE_AppData.HkPacket);
18041809
...
18051810
}
18061811
```
@@ -1816,8 +1821,8 @@ FILE: sample_app.h
18161821
typedef struct
18171822
{
18181823
...
1819-
CFE_SB_MsgPtr_t MsgPtr;
1820-
CFE_SB_PipeId_t CmdPipe;
1824+
CFE_MSG_Message_t *MsgPtr;
1825+
CFE_SB_PipeId_t CmdPipe;
18211826
...
18221827
} SAMPLE_AppData_t;
18231828
```
@@ -1945,10 +1950,9 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
19451950
** Get a SB Message block of memory and initialize it
19461951
*/
19471952
SAMPLE_AppData.BigPktPtr = (SAMPLE_BigPkt_t *)CFE_SB_ZeroCopyGetPtr(SAMPLE_BIGPKT_MSGLEN);
1948-
CFE_SB_InitMsg((CFE_SB_Msg_t *) SAMPLE_AppData.BigPktPtr,
1949-
SAMPLE_BIG_TLM_MID,
1950-
SAMPLE_BIGPKT_MSGLEN,
1951-
CFE_SB_CLEAR_DATA);
1953+
CFE_MSG_Init((CFE_MSG_Message_t *) SAMPLE_AppData.BigPktPtr,
1954+
SAMPLE_BIG_TLM_MID,
1955+
SAMPLE_BIGPKT_MSGLEN);
19521956
19531957
/*
19541958
** ...Fill Packet with Data...
@@ -1957,8 +1961,8 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
19571961
/*
19581962
** Send SB Message after time tagging it with current time
19591963
*/
1960-
CFE_SB_TimeStampMsg((CFE_SB_Msg_t *) SAMPLE_AppData.BigPktPtr);
1961-
CFE_SB_ZeroCopySend((CFE_SB_Msg_t *) SAMPLE_AppData.BigPktPtr);
1964+
CFE_SB_TimeStampMsg((CFE_MSG_Message_t *) SAMPLE_AppData.BigPktPtr);
1965+
CFE_SB_ZeroCopySend((CFE_MSG_Message_t *) SAMPLE_AppData.BigPktPtr);
19621966
/* SAMPLE_AppData.BigPktPtr is no longer a valid pointer */
19631967
...
19641968
}

‎docs/src/cfe_api.dox‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -146,30 +146,31 @@
146146
</UL>
147147
<LI> \ref CFEAPISBSetMessage
148148
<UL>
149-
<LI> #CFE_SB_InitMsg - \copybrief CFE_SB_InitMsg
150-
<LI> #CFE_SB_SetMsgId - \copybrief CFE_SB_SetMsgId
149+
<LI> #CFE_MSG_Init - \copybrief CFE_MSG_Init
150+
<LI> #CFE_MSG_SetMsgId - \copybrief CFE_MSG_SetMsgId
151151
<LI> #CFE_SB_SetUserDataLength - \copybrief CFE_SB_SetUserDataLength
152-
<LI> #CFE_SB_SetTotalMsgLength - \copybrief CFE_SB_SetTotalMsgLength
153-
<LI> #CFE_SB_SetMsgTime - \copybrief CFE_SB_SetMsgTime
152+
<LI> #CFE_MSG_SetSize - \copybrief CFE_MSG_SetSize
153+
<LI> #CFE_MSG_SetMsgTime - \copybrief CFE_MSG_SetMsgTime
154154
<LI> #CFE_SB_TimeStampMsg - \copybrief CFE_SB_TimeStampMsg
155-
<LI> #CFE_SB_SetCmdCode - \copybrief CFE_SB_SetCmdCode
155+
<LI> #CFE_MSG_SetFcnCode - \copybrief CFE_MSG_SetFcnCode
156+
<LI> #CFE_MSG_SetSequenceCount - \copybrief CFE_MSG_SetSequenceCount
156157
<LI> #CFE_SB_MessageStringSet - \copybrief CFE_SB_MessageStringSet
157158
</UL>
158159
<LI> \ref CFEAPIGetMessage
159160
<UL>
160161
<LI> #CFE_SB_GetUserData - \copybrief CFE_SB_GetUserData
161-
<LI> #CFE_SB_GetMsgId - \copybrief CFE_SB_GetMsgId
162+
<LI> #CFE_MSG_GetMsgId - \copybrief CFE_MSG_GetMsgId
162163
<LI> #CFE_SB_GetUserDataLength - \copybrief CFE_SB_GetUserDataLength
163-
<LI> #CFE_SB_GetTotalMsgLength - \copybrief CFE_SB_GetTotalMsgLength
164-
<LI> #CFE_SB_GetMsgTime - \copybrief CFE_SB_GetMsgTime
165-
<LI> #CFE_SB_GetCmdCode - \copybrief CFE_SB_GetCmdCode
164+
<LI> #CFE_MSG_GetSize - \copybrief CFE_MSG_GetSize
165+
<LI> #CFE_MSG_GetMsgTime - \copybrief CFE_MSG_GetMsgTime
166+
<LI> #CFE_MSG_GetFcnCode - \copybrief CFE_MSG_GetFcnCode
167+
<LI> #CFE_MSG_GetTypeFromMsgId - \copybrief CFE_MSG_GetTypeFromMsgId
166168
<LI> #CFE_SB_MessageStringGet - \copybrief CFE_SB_MessageStringGet
167169
</UL>
168170
<LI> \ref CFEAPISBChecksum
169171
<UL>
170-
<LI> #CFE_SB_GenerateChecksum - \copybrief CFE_SB_GenerateChecksum
171-
<LI> #CFE_SB_GetChecksum - \copybrief CFE_SB_GetChecksum
172-
<LI> #CFE_SB_ValidateChecksum - \copybrief CFE_SB_ValidateChecksum
172+
<LI> #CFE_MSG_GenerateChecksum - \copybrief CFE_MSG_GenerateChecksum
173+
<LI> #CFE_MSG_ValidateChecksum - \copybrief CFE_MSG_ValidateChecksum
173174
</UL>
174175
<LI> \ref CFEAPISBMessageID
175176
<UL>

‎docs/src/cfe_sb.dox‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -529,7 +529,7 @@
529529
can get confusing. How can I be sure that the correct address is given for this
530530
parameter.
531531
</B><TR><TD WIDTH="5%"> &nbsp; <TD WIDTH="95%">
532-
Typically a caller declares a ptr of type CFE_SB_Msg_t (i.e. CFE_SB_Msg_t *Ptr)
532+
Typically a caller declares a ptr of type CFE_MSG_Message_t (i.e. CFE_MSG_Message_t *Ptr)
533533
then gives the address of that pointer (&Ptr) as this parameter. After a successful
534534
call to #CFE_SB_RcvMsg, Ptr will point to the first byte of the software bus message
535535
header. This should be used as a read-only pointer. In systems with an MMU, writes

0 commit comments

Comments
 (0)