Skip to content

Commit

Permalink
fix nasa#759 - removes CFE_SB_GetLastSenderId() and adds CFE_SB_RcvMs…
Browse files Browse the repository at this point in the history 
…gSenderId()
  • Loading branch information
@CDKnightNASA
CDKnightNASA committed Jun 25, 2020
1 parent 1df042b commit 064aa33
Show file tree
Hide file tree
Showing 7 changed files with 159 additions and 354 deletions.
29 changes: 19 additions & 10 deletions docs/cFE Application Developers Guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1769,7 +1769,6 @@ for extracting that field from the header:
| Total Message Length | CFE_SB_GetTotalMsgLength | Command & Telemetry |
| User Data Message Length | CFE_SB_GetUserDataLength | Command & Telemetry |
| Command Code | CFE_SB_GetCmdCode | Command Only |
| Sender ID | CFE_SB_GetLastSenderId | Command & Telemetry |
| Checksum | CFE_SB_GetChecksum | Command Only |

In addition to the function for reading the checksum field, there is
Expand All @@ -1778,15 +1777,6 @@ and compares it to the checksum in the header. The API is called
CFE_SB_ValidateChecksum() and it simply returns a success or failure
indication.

It should be noted that the function, CFE_SB_GetLastSendId, is ideal
for verifying that critical commands are arriving from a legitimate
source. This function allows the Developer(s) to define a strict ICD
between two or more Applications to ensure that an erroneous Application
does not accidentally issue a critical command. However, its use for
routine command verification is discouraged since it would increase the
cross-coupling between Applications and require multiple Applications to
be modified if a command's source changes.

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.
Expand Down Expand Up @@ -1880,6 +1870,25 @@ After a message is received, the SB 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.

An enhanced method `CFE_SB_RcvMsgSenderId` will also return the ID of the
application that sent the message. For example:

```
uint32 SenderAppId;
SB_Status = CFE_SB_RcvMsgSenderId(&SAMPLE_AppData.MsgPtr, &SenderAppId,
SAMPLE_AppData.CmdPipe, CFE_SB_PEND_FOREVER);
```

It should be noted that the variant is ideal
for verifying that critical commands are arriving from a legitimate
source. This function allows the Developer(s) to define a strict ICD
between two or more Applications to ensure that an erroneous Application
does not accidentally issue a critical command. However, its use for
routine command verification is discouraged since it would increase the
cross-coupling between Applications and require multiple Applications to
be modified if a command's source changes.


#### 6.8 Improving Message Transfer Performance for Large SB Messages

Expand Down
2 changes: 1 addition & 1 deletion docs/src/cfe_api.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,7 @@
<LI> #CFE_SB_SendMsg - \copybrief CFE_SB_SendMsg
<LI> #CFE_SB_PassMsg - \copybrief CFE_SB_PassMsg
<LI> #CFE_SB_RcvMsg - \copybrief CFE_SB_RcvMsg
<LI> #CFE_SB_RcvMsgSenderId - \copybrief CFE_SB_RcvMsgSenderId
</UL>
<LI> \ref CFEAPISBZeroCopy
<UL>
Expand Down Expand Up @@ -169,7 +170,6 @@
<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_SB_GetLastSenderId - \copybrief CFE_SB_GetLastSenderId
<LI> #CFE_SB_MessageStringGet - \copybrief CFE_SB_MessageStringGet
</UL>
<LI> \ref CFEAPISBChecksum
Expand Down
100 changes: 55 additions & 45 deletions fsw/cfe-core/src/inc/cfe_sb.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -208,16 +208,6 @@ typedef struct {
extern CFE_SB_Qos_t CFE_SB_Default_Qos;/**< \brief Defines a default priority and reliabilty for off-board routing */


/** \brief Message Sender Identification Type Definition
**
** Parameter used in #CFE_SB_GetLastSenderId API which allows the receiver of a message
** to validate the sender of the message.
**/
typedef struct {
uint32 ProcessorId;/**< \brief Processor Id from which the message was sent */
char AppName[OS_MAX_API_NAME];/**< \brief Application that sent the message */
} CFE_SB_SenderId_t;

/****************** Function Prototypes **********************/

/** @defgroup CFEAPISBPipe cFE Pipe Management APIs
Expand Down Expand Up @@ -574,7 +564,7 @@ int32 CFE_SB_UnsubscribeLocal(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId);
** \retval #CFE_SB_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG
** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR
**
** \sa #CFE_SB_RcvMsg, #CFE_SB_ZeroCopySend, #CFE_SB_PassMsg
** \sa #CFE_SB_RcvMsg, #CFE_SB_RcvMsgSenderId, #CFE_SB_ZeroCopySend, #CFE_SB_PassMsg
**/
int32 CFE_SB_SendMsg(CFE_SB_Msg_t *MsgPtr);

Expand Down Expand Up @@ -607,7 +597,7 @@ int32 CFE_SB_SendMsg(CFE_SB_Msg_t *MsgPtr);
** \retval #CFE_SB_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG
** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR
**
** \sa #CFE_SB_RcvMsg, #CFE_SB_ZeroCopySend, #CFE_SB_SendMsg
** \sa #CFE_SB_RcvMsg, #CFE_SB_RcvMsgSenderId, #CFE_SB_ZeroCopySend, #CFE_SB_SendMsg
**/
int32 CFE_SB_PassMsg(CFE_SB_Msg_t *MsgPtr);

Expand Down Expand Up @@ -651,11 +641,62 @@ int32 CFE_SB_PassMsg(CFE_SB_Msg_t *MsgPtr);
** \retval #CFE_SB_PIPE_RD_ERR \copybrief CFE_SB_PIPE_RD_ERR
** \retval #CFE_SB_NO_MESSAGE \copybrief CFE_SB_NO_MESSAGE
**
** \sa #CFE_SB_SendMsg, #CFE_SB_ZeroCopySend
** \sa #CFE_SB_SendMsg, #CFE_SB_RcvMsgSenderId, #CFE_SB_ZeroCopySend
**/
int32 CFE_SB_RcvMsg(CFE_SB_MsgPtr_t *BufPtr,
CFE_SB_PipeId_t PipeId,
int32 TimeOut);

/*****************************************************************************/
/**
** \brief Receive a message from a software bus pipe and return the sending AppId
**
** \par Description
** This routine retrieves the next message from the specified pipe.
** If the pipe is empty, this routine will block until either a new
** message comes in or the timeout value is reached.
**
** \par Assumptions, External Events, and Notes:
** Note - If an error occurs in this API, the *BufPtr value may be NULL or
** random. Therefore, it is recommended that the return code be tested
** for CFE_SUCCESS before processing the message.
**
** \param[in, out] BufPtr A pointer to a local variable of type #CFE_SB_MsgPtr_t.
** Typically a caller declares a ptr of type CFE_SB_Msg_t
** (i.e. CFE_SB_Msg_t *Ptr) then gives the address of that
** pointer (&Ptr) as this parmeter. After a successful
** receipt of a message, *BufPtr 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 to this pointer may cause a memory protection fault).
** The *BufPtr is valid only until the next call to
** CFE_SB_RcvMsg for the same pipe. \n *BufPtr is a pointer to
** the message obtained from the pipe. Valid
** only until the next call to CFE_SB_RcvMsg for the same pipe.
**
** \param[out] SenderId The AppId of the application that sent the message received
** in this call.
**
** \param[in] PipeId The pipe ID of the pipe containing the message to be obtained.
**
** \param[in] TimeOut The number of milliseconds to wait for a new message if the
** pipe is empty at the time of the call. This can also be set
** to #CFE_SB_POLL for a non-blocking receive or
** #CFE_SB_PEND_FOREVER to wait forever for a message to arrive.
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
** \retval #CFE_SB_TIME_OUT \copybrief CFE_SB_TIME_OUT
** \retval #CFE_SB_PIPE_RD_ERR \copybrief CFE_SB_PIPE_RD_ERR
** \retval #CFE_SB_NO_MESSAGE \copybrief CFE_SB_NO_MESSAGE
**
** \sa #CFE_SB_SendMsg, #CFE_SB_RcvMsg, #CFE_SB_RcvMsgSenderId, #CFE_SB_ZeroCopySend
**/
int32 CFE_SB_RcvMsgSenderId(CFE_SB_MsgPtr_t *BufPtr,
uint32 *SenderId,
CFE_SB_PipeId_t PipeId,
int32 TimeOut);
/**@}*/

/** @defgroup CFEAPISBZeroCopy cFE Zero Copy Message APIs
Expand Down Expand Up @@ -765,7 +806,7 @@ int32 CFE_SB_ZeroCopyReleasePtr(CFE_SB_Msg_t *Ptr2Release,
** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR
** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID
**
** \sa #CFE_SB_SendMsg, #CFE_SB_RcvMsg, #CFE_SB_ZeroCopyReleasePtr, #CFE_SB_ZeroCopyGetPtr
** \sa #CFE_SB_SendMsg, #CFE_SB_RcvMsg, #CFE_SB_RcvMsgSenderId, #CFE_SB_ZeroCopyReleasePtr, #CFE_SB_ZeroCopyGetPtr
**/
int32 CFE_SB_ZeroCopySend(CFE_SB_Msg_t *MsgPtr,
CFE_SB_ZeroCopyHandle_t BufferHandle);
Expand Down Expand Up @@ -1173,37 +1214,6 @@ uint16 CFE_SB_GetCmdCode(CFE_SB_MsgPtr_t MsgPtr);
**/
CFE_TIME_SysTime_t CFE_SB_GetMsgTime(CFE_SB_MsgPtr_t MsgPtr);

/*****************************************************************************/
/**
** \brief Retrieve the application Info of the sender for the last message.
**
** \par Description
** This routine can be used after a successful #CFE_SB_RcvMsg call
** to find out which application sent the message that was received.
**
** \par Assumptions, External Events, and Notes:
** Note - If an error occurs in this API, the *Ptr value may be NULL or
** random. Therefore, it is recommended that the return code be tested
** for CFE_SUCCESS before reading the sender information.
**
** \param[in] Ptr A pointer to a local variable of type #CFE_SB_SenderId_t.
** Typically a caller declares a ptr of type CFE_SB_SenderId_t
** (i.e. CFE_SB_SenderId_t *Ptr) then gives the address of that
** pointer (&Ptr) for this parameter. After a successful call
** to this API, *Ptr will point to the first byte of the
** CFE_SB_SenderId_t structure containing the sender information
** for the last message received on the given pipe. This should
** be used as a read-only pointer (in systems with an MMU, writes
** to this pointer may cause a memory protection fault). The *Ptr
** is valid only until the next call to CFE_SB_RcvMsg for the
** same pipe.
**
** \param[in] PipeId The pipe ID of the pipe the message was taken from.
**
** \return The last sender's application ID
**/
uint32 CFE_SB_GetLastSenderId(CFE_SB_SenderId_t **Ptr,CFE_SB_PipeId_t PipeId);

/******************************************************************************/
/**
** \brief Copies a string out of a software bus message
Expand Down
92 changes: 19 additions & 73 deletions fsw/cfe-core/src/sb/cfe_sb_api.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1320,12 +1320,7 @@ int32 CFE_SB_SendMsgFull(CFE_SB_Msg_t *MsgPtr,
RtgTblPtr->SeqCnt);
}/* end if */

/* store the sender information */
if(CFE_SB.SenderReporting != 0)
{
BufDscPtr->Sender.ProcessorId = CFE_PSP_GetProcessorId();
strncpy(&BufDscPtr->Sender.AppName[0],CFE_SB_GetAppTskName(TskId,FullName),OS_MAX_API_NAME);
}
BufDscPtr->SenderId = CFE_SB.AppId;

/* At this point there must be at least one destination for pkt */

Expand Down Expand Up @@ -1503,6 +1498,20 @@ int32 CFE_SB_SendMsgFull(CFE_SB_Msg_t *MsgPtr,
int32 CFE_SB_RcvMsg(CFE_SB_MsgPtr_t *BufPtr,
CFE_SB_PipeId_t PipeId,
int32 TimeOut)
{
uint32 SenderId;
return CFE_SB_RcvMsgSenderId(BufPtr, &SenderId, PipeId, TimeOut);

}/* end CFE_SB_RcvMsg */


/*
* Function: CFE_SB_RcvMsgSenderId - See API and header file for details
*/
int32 CFE_SB_RcvMsgSenderId(CFE_SB_MsgPtr_t *BufPtr,
uint32 *SenderId,
CFE_SB_PipeId_t PipeId,
int32 TimeOut)
{
int32 Status;
CFE_SB_BufferD_t *Message;
Expand Down Expand Up @@ -1574,6 +1583,9 @@ int32 CFE_SB_RcvMsg(CFE_SB_MsgPtr_t *BufPtr,
** the buffer can be released on the next RcvMsg call for this pipe.
*/
PipeDscPtr->CurrentBuff = Message;
if (SenderId != NULL) {
*SenderId = Message->SenderId;
}

/* Set the Receivers pointer to the address of the actual message */
*BufPtr = (CFE_SB_MsgPtr_t) Message->Buffer;
Expand Down Expand Up @@ -1617,73 +1629,7 @@ int32 CFE_SB_RcvMsg(CFE_SB_MsgPtr_t *BufPtr,
*/
return Status;

}/* end CFE_SB_RcvMsg */


/*
* Function: CFE_SB_GetLastSenderId - See API and header file for details
*/
uint32 CFE_SB_GetLastSenderId(CFE_SB_SenderId_t **Ptr,CFE_SB_PipeId_t PipeId)
{

CFE_SB_BufferD_t *Ptr2BufDescriptor;
uint32 TskId = 0;
uint32 AppId = 0xFFFFFFFF;
char FullName[(OS_MAX_API_NAME * 2)];

TskId = OS_TaskGetId();

/* validate ptr - note: must validate ptr before pipe id validation */
/* because an invalid pipe id sets the callers pointer to NULL */
if(Ptr == NULL){
CFE_EVS_SendEventWithAppID(CFE_SB_LSTSNDER_ERR1_EID,CFE_EVS_EventType_ERROR,CFE_SB.AppId,
"SB GetLastSender Err:Rcvd Null Ptr,Pipe=%d,App=%s",
(int)PipeId,CFE_SB_GetAppTskName(TskId,FullName));
return CFE_SB_BAD_ARGUMENT;
}/* end if */

/* validate pipe id */
if(CFE_SB_ValidatePipeId(PipeId)!=CFE_SUCCESS){
*Ptr = NULL;
CFE_EVS_SendEventWithAppID(CFE_SB_LSTSNDER_ERR2_EID,CFE_EVS_EventType_ERROR,CFE_SB.AppId,
"SB GetLastSender Err:Rcvd Invalid Pipe=%d,App=%s",
(int)PipeId,CFE_SB_GetAppTskName(TskId,FullName));
return CFE_SB_BAD_ARGUMENT;
}/* end if */

CFE_ES_GetAppID(&AppId);

CFE_SB_LockSharedData(__func__,__LINE__);

/* verify requestor is owner of pipe */
if(CFE_SB.PipeTbl[PipeId].AppId != AppId){
*Ptr = NULL;
CFE_SB_UnlockSharedData(__func__,__LINE__);
CFE_EVS_SendEventWithAppID(CFE_SB_GLS_INV_CALLER_EID,CFE_EVS_EventType_ERROR,CFE_SB.AppId,
"SB GetLastSender Err:Caller(%s) is not the owner of pipe %d",
CFE_SB_GetAppTskName(TskId,FullName),(int)PipeId);
return CFE_SB_BAD_ARGUMENT;
}/* end if */

/* Get ptr to buffer descriptor for the last msg received on the given pipe */
Ptr2BufDescriptor = CFE_SB.PipeTbl[PipeId].CurrentBuff;

if ( Ptr2BufDescriptor == NULL )
{
*Ptr = NULL;
CFE_SB.PipeTbl[PipeId].LastSender = CFE_SB_INVALID_MSG_ID;
CFE_SB_UnlockSharedData(__func__,__LINE__);
return CFE_SB_NO_MSG_RECV;
}
else
{
/* Set the receivers pointer to the adr of 'Sender' struct in buf descriptor */
*Ptr = (CFE_SB_SenderId_t *) &Ptr2BufDescriptor -> Sender;
CFE_SB_UnlockSharedData(__func__,__LINE__);
return CFE_SUCCESS;
}

}/* end CFE_SB_GetLastSenderId */
}/* end CFE_SB_RcvMsgSenderId */


/*
Expand Down
2 changes: 1 addition & 1 deletion fsw/cfe-core/src/sb/cfe_sb_priv.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ typedef struct {
uint16 UseCount;
uint32 Size;
void *Buffer;
CFE_SB_SenderId_t Sender;
uint32 SenderId;
} CFE_SB_BufferD_t;


Expand Down
Loading

0 comments on commit 064aa33

Please sign in to comment.