Skip to content

Commit

Permalink
Fix nasa#800 nasa#961, Update dev guide for MSG and SBR
Browse files Browse the repository at this point in the history
  • Loading branch information
@skliper
skliper committed Sep 7, 2021
1 parent e5d4ed9 commit 134c97d
Showing 1 changed file with 61 additions and 41 deletions.
102 changes: 61 additions & 41 deletions docs/cFE Application Developers Guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1389,29 +1389,35 @@ with timeout as well.

### 6.1.1 Software Bus Messages

A Software Bus Message (SB Message) is a collection of data treated as a
single entity. The format and the definition of the content is uniquely
identified with a 16 bit Message ID. The Message ID is used to identify
what the data is and who would like to receive it. Applications create
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 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.

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.
A Software Bus Message is a collection of data treated as a single entity.
Messages are identified and routed on the Software Bus using an abstracted
Message ID. Applications create SB Messages by allocating sufficient memory,
initializing the message contents and filling in user data.

If you are using the default, MsgID maps directly to the CCSDS Stream ID.
When using the default, for commands use 0x18xx and telemetry use 0x08xx
The Message API abstracts the details of the message header,
and most importantly the Message ID. The current version of the cFE
supports only CCSDS, however, the implementation of the message
structure can be changed without affecting the rest of cFS as long
as the APIs meet the required behavior identified in the related
documentation.

See the message module implementation documentation for specific formats,
fields, and bit values. The message module provides a selection of two
different implementations for Message ID (MISSION_MSG_V1 and MISSION_MSG_V2),
which use different header information to interpret the Message ID.
Applications and cFE services should always use the message module APIs
for getting or setting information in the message headers to support
portability between formats. Message ID should always be treated as opaque,
although they do need to be defined for applications to subscribe to messages.
Message ID definition is typically managed by external database management
systems and MUST match the implementation selected.

If you are using the default (MISSION_MSG_V1), MsgID maps directly to the CCSDS Stream ID.
It is important enough to repeat, applications should NOT directly interpret
the Message ID value since for different implementations the bits may have
different meanings. For example, default Message ID values for commands are of
the format 0x18xx and telemetry is 0x08xx, whereas for MISSION_MSG_V2
those bits have different meaning.

### 6.1.2 Pipes

Expand Down Expand Up @@ -1458,6 +1464,21 @@ performs the operations necessary to transfer the SB Message to the
target pipe(s). Applications call the SB API to request specified SB
Message IDs to be routed to their previously created pipes.

Note there are two routing implementations provide by the
Software Bus Routing (SBR) module. If the MISSION_MSGMAP_IMPLEMENTATION
is unset (the default) or set to DIRECT, a message map of size
CFE_PLATFORM_SB_HIGHEST_VALID_MSGID is used to relate Message ID to routes.
If set to HASH, a message map of size (4 * CFE_PLATFORM_SB_MAX_MSG_IDS)
is used and a hash is performed on Message IDs to relate to routes. Note
the impact on memory footprint can be significant, since
CFE_PLATFORM_SB_HIGHEST_VALID_MSGID is the maximum number of possible
Message IDs, whereas CFE_PLATFORM_SB_MAX_MSG_IDS is the maximum number of
routes supported (**used** Message IDs). Hash collisions are reported
during subscription and can be avoided by predetermining Message
IDs that won't collide. Note advanced users can replace SBR with a custom
routing implementation (possibly sorting or a smart hash) to adapt to unique
mission requirements/constraints.

#### 6.1.3.1 Sending Applications

Any software application is capable of sending SB Messages. However,
Expand Down Expand Up @@ -1579,7 +1600,7 @@ FILE: sample_msgids.h

...
/* Define Message IDs */
#define SAMPLE_CMDID_1 (0x0123)
#define SAMPLE_CMDID_1 (0x0123) /* CAUTION!!! This value depends on selected implementation */
...
```
```c
Expand Down Expand Up @@ -1739,15 +1760,14 @@ for the Developer to have used the CFE_MSG_CommandHeader_t macro
instead.

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
would have retained the contents of the data structure and only updated
the SB Message Header.
appropriately with the given Message ID, size and clears the rest
of the message. Note this call is implementation dependent, in that
bits in the Message ID may have additional meaning and may impact
actual header fields in different ways.

NOTE: SB Message IDs are defined in a separate header file from the rest
NOTE: Message IDs are defined in a separate header file from the rest
of the Application's interface. This makes it much simpler to port the
Application to another mission where SB Message IDs may need to be
Application to another mission where Message IDs may need to be
renumbered.

### 6.5.1 Message Header Types
Expand Down Expand Up @@ -1799,7 +1819,7 @@ 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** | **API for Modifying the Header Field** |
| **Message Header Field** | **API for Modifying the Header Field** |
| ---------------------------:| --------------------------------------:|
| Message ID | CFE_MSG_SetMsgId |
| Total Message Length | CFE_MSG_SetSize |
Expand Down Expand Up @@ -1845,7 +1865,7 @@ Applications are portable to future missions. The following table
identifies the fields of the Message Header and the appropriate API
for extracting that field from the header:

| **SB Message Header Field** | **API for Reading the Header Field** |
| **Message Header Field** | **API for Reading the Header Field** |
|:----------------------------|:-------------------------------------|
| Message ID | CFE_MSG_GetMsgId |
| Message Time | CFE_MSG_GetTime |
Expand Down Expand Up @@ -1896,7 +1916,7 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */

## 6.7 Receiving Software Bus Messages

To receive a SB Message, an application calls CFE_SB_ReceiveBuffer. Since most
To receive a Message, an application calls CFE_SB_ReceiveBuffer. Since most
applications are message-driven, this typically occurs in an application's
main execution loop. An example of this is shown below.

Expand Down Expand Up @@ -1938,20 +1958,20 @@ FILE: sample_app.c
```

In the above example, the Application will pend on the
SAMPLE_AppData.CmdPipe until an SB Message arrives. A pointer to the next SB
SAMPLE_AppData.CmdPipe until a Message arrives. A pointer to the next SB
message in the Pipe will be returned in SBBufPtr.

Alternatively, the Application could have chosen to pend with a timeout (by
providing a numerical argument in place of CFE_SB_PEND_FOREVER) or to quickly
poll the pipe to check for a message (by using CFE_SB_POLL in place of
CFE_SB_PEND_FOREVER).

If a SB Message fails to arrive within the specified timeout period, the
If a Message fails to arrive within the specified timeout period, the
cFE will return the CFE_SB_TIME_OUT status code. If the Pipe does not have
any data present when the CFE_SB_ReceiveBuffer API is called, the cFE will return
a CFE_SB_NO_MESSAGE status code.

After a message is received, the SB Message Header accessor functions (as
After a message is received, the Message Header accessor functions (as
described in Section 6.5.3) should be used to identify the message so that
the application can react to it appropriately.

Expand Down Expand Up @@ -1980,7 +2000,7 @@ assume the SB Buffer pointer is accessible once the buffer
has been sent.

If an Application has called the `CFE_SB_AllocateMessageBuffer` API call and
then later determines that it is not going to send the SB Message, it
then later determines that it is not going to send the Message, it
shall free the allocated buffer by calling the
`CFE_SB_ReleaseMessageBuffer` API.

Expand All @@ -1990,7 +2010,7 @@ An example of the "Zero Copy" protocol is shown below:
FILE: app_msgids.h

...
#define SAMPLE_BIG_TLM_MID (0x0231) /* Define SB Message ID for SAMPLE’s Big Pkt */
#define SAMPLE_BIG_TLM_MID (0x0231) /* Define Message ID for SAMPLE’s Big Pkt */
...

FILE: sample_app.h
Expand Down Expand Up @@ -2033,7 +2053,7 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
{
...
/*
** Get a SB Message block of memory and initialize it
** Get a Message block of memory and initialize it
*/
SAMPLE_AppData.BigPktBuf = (SAMPLE_BigPkt_Buffer_t *)CFE_SB_AllocateMessageBuffer(sizeof(SAMPLE_BigPkt_t));

Expand All @@ -2045,7 +2065,7 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */
*/

/*
** Send SB Message after time tagging it with current time
** Send Message after time tagging it with current time
*/
CFE_SB_TimeStampMsg(&SAMPLE_AppData.BigPktBuf->Pkt.TlmHeader.Msg);
CFE_SB_TransmitBuffer(SAMPLE_AppData.BigPktBuf, BufferHandle, true);
Expand All @@ -2062,7 +2082,7 @@ The following are recommended "best practices" for applications using SB.
2. Pipe depth and message limits are dependent on the entire software system.
Consider both the receiving application and any sending application(s) when
choosing those limits.
3. Applications shall always use AB API functions to read or manipulate the SB
3. Applications shall always use API functions to read or manipulate the
Message Header.
4. Applications should maintain a command counter and a command error counter
in housekeeping telemetry.
Expand Down

0 comments on commit 134c97d

Please sign in to comment.