Skip to content

Commit

Permalink
WIP #777, last round
Browse files Browse the repository at this point in the history
  • Loading branch information
skliper committed Nov 4, 2020
1 parent fbc3925 commit 146fa01
Show file tree
Hide file tree
Showing 23 changed files with 154 additions and 1,257 deletions.
81 changes: 43 additions & 38 deletions docs/cFE Application Developers Guide.md
Original file line number Diff line number Diff line change
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 @@ -1705,54 +1705,59 @@ 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** | **API for Reading the Header Field** | **Applicability** |
Expand All @@ -1762,12 +1767,12 @@ for extracting that field from the header:
| Total Message Length | CFE_MSG_GetSize | Command & Telemetry |
| Command Code | CFE_MSG_GetFcnCode | Command Only |

There are other APIs based on selected implementation, and the full list is
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.

Although CFE_SB_GetUserDataLength and CFE_SB_GetUserData APIs are available,
Expand Down
4 changes: 2 additions & 2 deletions fsw/cfe-core/src/evs/cfe_evs_utils.c
Original file line number Diff line number Diff line change
Expand Up @@ -428,7 +428,7 @@ void EVS_GenerateEventTelemetry(EVS_AppData_t *AppDataPtr, uint16 EventID, uint1
LongEventTlm.Payload.PacketID.ProcessorID = CFE_PSP_GetProcessorId();

/* Set the packet timestamp */
CFE_SB_SetMsgTime((CFE_MSG_Message_t *) &LongEventTlm, *TimeStamp);
CFE_MSG_SetMsgTime((CFE_MSG_Message_t *) &LongEventTlm, *TimeStamp);

/* Write event to the event log */
EVS_AddLog(&LongEventTlm);
Expand All @@ -451,7 +451,7 @@ void EVS_GenerateEventTelemetry(EVS_AppData_t *AppDataPtr, uint16 EventID, uint1
*/
CFE_MSG_Init(&ShortEventTlm.TlmHeader.BaseMsg, CFE_SB_ValueToMsgId(CFE_EVS_SHORT_EVENT_MSG_MID),
sizeof(ShortEventTlm));
CFE_SB_SetMsgTime((CFE_MSG_Message_t *) &ShortEventTlm, *TimeStamp);
CFE_MSG_SetMsgTime((CFE_MSG_Message_t *) &ShortEventTlm, *TimeStamp);
ShortEventTlm.Payload.PacketID = LongEventTlm.Payload.PacketID;
CFE_SB_SendMsg((CFE_MSG_Message_t *) &ShortEventTlm);
}
Expand Down
2 changes: 1 addition & 1 deletion fsw/cfe-core/src/inc/cfe_error.h
Original file line number Diff line number Diff line change
Expand Up @@ -856,7 +856,7 @@ typedef int32 CFE_Status_t;
/**
* @brief Wrong Message Type
*
* This error code will be returned when a request such as #CFE_SB_SetMsgTime
* This error code will be returned when a request such as #CFE_MSG_SetMsgTime
* is made on a packet that does not include a field for msg time.
*
*/
Expand Down
Loading

0 comments on commit 146fa01

Please sign in to comment.