Skip to content

Commit

Permalink
Fix nasa#1155, clean up zero copy API
Browse files Browse the repository at this point in the history 
The separate zero copy handle type is removed.

Adds two new simplified functions CFE_SB_AllocateMessageBuffer
and CFE_SB_ReleaseMessageBuffer to replace CFE_SB_ZeroCopyGetPtr
and CFE_SB_ZeroCopyGetPtr.  These new functions do not use
a separate Handle.

Updates the CFE_SB_TransmitBuffer() API to also remove the handle.
  • Loading branch information
@jphickey
jphickey committed Mar 23, 2021
1 parent 98bc158 commit 410447e
Show file tree
Hide file tree
Showing 7 changed files with 118 additions and 304 deletions.
134 changes: 20 additions & 114 deletions modules/core_api/fsw/inc/cfe_sb.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -552,31 +552,26 @@ CFE_Status_t CFE_SB_RcvMsg(CFE_SB_Buffer_t **BufPtr, CFE_SB_PipeId_t PipeId, int
** This routine can be used to get a pointer to one of the software bus'
** internal memory buffers that are used for sending messages. The caller
** can use this memory buffer to build an SB message, then send it using
** the #CFE_SB_TransmitBuffer function. This interface is more complicated
** than the normal #CFE_SB_TransmitMsg interface, but it avoids an extra
** the CFE_SB_TransmitBuffer() function. This interface avoids an extra
** copy of the message from the user's memory buffer to the software bus
** internal buffer. The "zero copy" interface can be used to improve
** performance in high-rate, high-volume software bus traffic.
** internal buffer.
**
** \par Assumptions, External Events, and Notes:
** -# The pointer returned by #CFE_SB_ZeroCopyGetPtr is only good for one
** call to #CFE_SB_TransmitBuffer.
** -# Applications should be written as if #CFE_SB_ZeroCopyGetPtr is
** equivalent to a \c malloc() and #CFE_SB_TransmitBuffer is equivalent to
** a \c free().
** -# The pointer returned by CFE_SB_AllocateMessageBuffer() is only good for one
** call to CFE_SB_TransmitBuffer().
** -# Once a buffer has been successfully transmitted (as indicated by a successful
** return from CFE_SB_TransmitBuffer()) the buffer becomes owned by the SB application.
** It will automatically be freed by SB once all recipients have finished reading it.
** -# Applications must not de-reference the message pointer (for reading
** or writing) after the call to #CFE_SB_TransmitBuffer.
** or writing) after the call to CFE_SB_TransmitBuffer().
**
** \param[in] MsgSize The size of the SB message buffer the caller wants
** (including the SB message header).
**
** \param[out] BufferHandle A handle that must be supplied when sending or releasing
** in zero copy mode.
**
** \return A pointer to a memory buffer that message data can be written to
** for use with #CFE_SB_TransmitBuffer.
** for use with CFE_SB_TransmitBuffer().
**/
CFE_SB_Buffer_t *CFE_SB_ZeroCopyGetPtr(size_t MsgSize, CFE_SB_ZeroCopyHandle_t *BufferHandle);
CFE_SB_Buffer_t *CFE_SB_AllocateMessageBuffer(size_t MsgSize);

/*****************************************************************************/
/**
Expand All @@ -589,21 +584,18 @@ CFE_SB_Buffer_t *CFE_SB_ZeroCopyGetPtr(size_t MsgSize, CFE_SB_ZeroCopyHandle_t *
** \par Assumptions, External Events, and Notes:
** -# This function is not needed for normal "zero copy" transfers. It
** is needed only for cleanup when an application gets a pointer using
** #CFE_SB_ZeroCopyGetPtr, but (due to some error condition) never uses
** that pointer for a #CFE_SB_TransmitBuffer
**
** \param[in] Ptr2Release A pointer to the SB internal buffer. This must be a
** pointer returned by a call to #CFE_SB_ZeroCopyGetPtr,
** but never used in a call to #CFE_SB_TransmitBuffer.
** CFE_SB_AllocateMessageBuffer(), but (due to some error condition) never
** uses that pointer in a call to CFE_SB_TransmitBuffer().
**
** \param[in] ZeroCopyHandle This must be the handle supplied with the pointer
** when #CFE_SB_ZeroCopyGetPtr was called.
** \param[in] BufPtr A pointer to the SB internal buffer. This must be a
** pointer returned by a call to CFE_SB_AllocateMessageBuffer(),
** but never used in a call to CFE_SB_TransmitBuffer().
**
** \return Execution status, see \ref CFEReturnCodes
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID
**/
CFE_Status_t CFE_SB_ZeroCopyReleasePtr(CFE_SB_Buffer_t *Ptr2Release, CFE_SB_ZeroCopyHandle_t ZeroCopyHandle);
CFE_Status_t CFE_SB_ReleaseMessageBuffer(CFE_SB_Buffer_t *BufPtr);

/*****************************************************************************/
/**
Expand All @@ -612,22 +604,22 @@ CFE_Status_t CFE_SB_ZeroCopyReleasePtr(CFE_SB_Buffer_t *Ptr2Release, CFE_SB_Zero
** \par Description
** This routine sends a message that has been created directly in an
** internal SB message buffer by an application (after a call to
** #CFE_SB_ZeroCopyGetPtr). This interface is more complicated than
** #CFE_SB_AllocateMessageBuffer). This interface is more complicated than
** the normal #CFE_SB_TransmitMsg interface, but it avoids an extra copy of
** the message from the user's memory buffer to the software bus
** internal buffer. The "zero copy" interface can be used to improve
** performance in high-rate, high-volume software bus traffic.
**
** \par Assumptions, External Events, and Notes:
** -# A handle returned by #CFE_SB_ZeroCopyGetPtr is "consumed" by
** -# A handle returned by #CFE_SB_AllocateMessageBuffer is "consumed" by
** a _successful_ call to #CFE_SB_TransmitBuffer.
** -# If this function returns CFE_SUCCESS, this indicates the zero copy handle is
** now owned by software bus, and is no longer owned by the calling application,
** and should not be re-used.
** -# Howver if this function fails (returns any error status) it does not change
** the state of the buffer at all, meaning the calling application still owns it.
** (a failure means the buffer is left in the same state it was before the call).
** -# Applications should be written as if #CFE_SB_ZeroCopyGetPtr is
** -# Applications should be written as if #CFE_SB_AllocateMessageBuffer is
** equivalent to a \c malloc() and a successful call to #CFE_SB_TransmitBuffer
** is equivalent to a \c free().
** -# Applications must not de-reference the message pointer (for reading
Expand All @@ -636,7 +628,6 @@ CFE_Status_t CFE_SB_ZeroCopyReleasePtr(CFE_SB_Buffer_t *Ptr2Release, CFE_SB_Zero
** sequence counter if set to do so.
**
** \param[in] BufPtr A pointer to the buffer to be sent.
** \param[in] ZeroCopyHandle The handle supplied by the #CFE_SB_ZeroCopyGetPtr call
** \param[in] IncrementSequenceCount Boolean to increment the internally tracked
** sequence count and update the message if the
** buffer contains a telemetry message
Expand All @@ -645,93 +636,8 @@ CFE_Status_t CFE_SB_ZeroCopyReleasePtr(CFE_SB_Buffer_t *Ptr2Release, CFE_SB_Zero
** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS
** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT
** \retval #CFE_SB_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG
** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR
**/
CFE_Status_t CFE_SB_TransmitBuffer(CFE_SB_Buffer_t *BufPtr, CFE_SB_ZeroCopyHandle_t ZeroCopyHandle,
bool IncrementSequenceCount);

#ifndef CFE_OMIT_DEPRECATED_6_8
/*****************************************************************************/
/**
** \brief DEPRECATED: Send an SB message in "zero copy" mode.
** \deprecated use CFE_SB_TransmitBuffer
**
** \par Description
** This routine sends a message that has been created directly in an
** internal SB message buffer by an application (after a call to
** #CFE_SB_ZeroCopyGetPtr). This interface is more complicated than
** the normal #CFE_SB_TransmitMsg interface, but it avoids an extra copy of
** the message from the user's memory buffer to the software bus
** internal buffer. The "zero copy" interface can be used to improve
** performance in high-rate, high-volume software bus traffic.
**
** \par Assumptions, External Events, and Notes:
** -# The pointer returned by #CFE_SB_ZeroCopyGetPtr is only good for
** one call to #CFE_SB_TransmitBuffer.
** -# Callers must not use the same SB message buffer for multiple sends.
** -# Applications should be written as if #CFE_SB_ZeroCopyGetPtr is
** equivalent to a \c malloc() and #CFE_SB_TransmitBuffer is equivalent
** to a \c free().
** -# Applications must not de-reference the message pointer (for reading
** or writing) after the call to #CFE_SB_TransmitBuffer.
** -# This function tracks and increments the source sequence counter
** of a telemetry message.
**
** \param[in] BufPtr A pointer to the SB buffer to be sent.
**
** \param[in] BufferHandle The handle supplied with the #CFE_SB_ZeroCopyGetPtr call.
**
** \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_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG
** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR
** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID
**/
CFE_Status_t CFE_SB_ZeroCopySend(CFE_SB_Buffer_t *BufPtr, CFE_SB_ZeroCopyHandle_t BufferHandle);

/*****************************************************************************/
/**
** \brief DEPRECATED: Pass an SB message in "zero copy" mode.
** \deprecated use CFE_SB_TransmitBuffer
**
** \par Description
** This routine sends a message that has been created directly in an
** internal SB message buffer by an application (after a call to
** #CFE_SB_ZeroCopyGetPtr). This interface is more complicated than
** the normal #CFE_SB_TransmitMsg interface, but it avoids an extra copy of
** the message from the user's memory buffer to the software bus
** internal buffer. The "zero copy" interface can be used to improve
** performance in high-rate, high-volume software bus traffic. This
** version is intended to pass messages not generated by the caller
** (to preserve the source sequence count).
**
** \par Assumptions, External Events, and Notes:
** -# The pointer returned by #CFE_SB_ZeroCopyGetPtr is only good for
** one call to #CFE_SB_TransmitBuffer or #CFE_SB_ZeroCopyPass.
** -# Callers must not use the same SB message buffer for multiple sends.
** -# Applications should be written as if #CFE_SB_ZeroCopyGetPtr is
** equivalent to a \c malloc() and #CFE_SB_ZeroCopyPass is equivalent
** to a \c free().
** -# Applications must not de-reference the message pointer (for reading
** or writing) after the call to #CFE_SB_ZeroCopyPass.
** -# This routine will not modify the sequence counter in a telemetry
** message
**
** \param[in] BufPtr A pointer to the SB buffer to be sent.
**
** \param[in] BufferHandle The handle supplied with the #CFE_SB_ZeroCopyGetPtr call.
**
** \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_MSG_TOO_BIG \copybrief CFE_SB_MSG_TOO_BIG
** \retval #CFE_SB_BUF_ALOC_ERR \copybrief CFE_SB_BUF_ALOC_ERR
** \retval #CFE_SB_BUFFER_INVALID \copybrief CFE_SB_BUFFER_INVALID
**/
CFE_Status_t CFE_SB_ZeroCopyPass(CFE_SB_Buffer_t *BufPtr, CFE_SB_ZeroCopyHandle_t BufferHandle);
/**@}*/
#endif
CFE_Status_t CFE_SB_TransmitBuffer(CFE_SB_Buffer_t *BufPtr, bool IncrementSequenceCount);

/** @defgroup CFEAPISBSetMessage cFE Setting Message Characteristics APIs
* @{
Expand Down
13 changes: 0 additions & 13 deletions modules/core_api/fsw/inc/cfe_sb_api_typedefs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,19 +162,6 @@ typedef CFE_MSG_Message_t *CFE_SB_MsgPtr_t;
/** \brief CFE_SB_MsgPayloadPtr_t defined as an opaque pointer to a message Payload portion */
typedef uint8 *CFE_SB_MsgPayloadPtr_t;

#endif /* CFE_OMIT_DEPRECATED_6_8 */

/** \brief CFE_SB_ZeroCopyHandle_t to primitive type definition
**
** Software Zero Copy handle used in many SB APIs
*/
typedef struct
{
struct CFE_SB_BufferD *BufDscPtr; /* abstract descriptor reference (internal use) */
} CFE_SB_ZeroCopyHandle_t;

#ifndef CFE_OMIT_DEPRECATED_6_8

#define CFE_SB_Default_Qos CFE_SB_DEFAULT_QOS /**< \deprecated use CFE_SB_DEFAULT_QOS */

#define CFE_SB_CMD_HDR_SIZE (sizeof(CFE_MSG_CommandHeader_t)) /**< \brief Size of command header */
Expand Down
50 changes: 9 additions & 41 deletions modules/core_api/ut-stubs/src/ut_sb_stubs.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -510,11 +510,9 @@ int32 CFE_SB_TransmitMsg(CFE_MSG_Message_t *MsgPtr, bool IncrementSequenceCount)
** Returns CFE_SUCCESS or overridden unit test value
**
******************************************************************************/
int32 CFE_SB_TransmitBuffer(CFE_SB_Buffer_t *BufPtr, CFE_SB_ZeroCopyHandle_t ZeroCopyHandle,
bool IncrementSequenceCount)
int32 CFE_SB_TransmitBuffer(CFE_SB_Buffer_t *BufPtr, bool IncrementSequenceCount)
{
UT_Stub_RegisterContext(UT_KEY(CFE_SB_TransmitBuffer), BufPtr);
UT_Stub_RegisterContextGenericArg(UT_KEY(CFE_SB_TransmitBuffer), ZeroCopyHandle);
UT_Stub_RegisterContextGenericArg(UT_KEY(CFE_SB_TransmitBuffer), BufPtr);
UT_Stub_RegisterContextGenericArg(UT_KEY(CFE_SB_TransmitBuffer), IncrementSequenceCount);

int32 status = CFE_SUCCESS;
Expand Down Expand Up @@ -1159,60 +1157,30 @@ int32 CFE_SB_UnsubscribeLocal(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeId)
return status;
}

CFE_SB_Buffer_t *CFE_SB_ZeroCopyGetPtr(size_t MsgSize, CFE_SB_ZeroCopyHandle_t *BufferHandle)
CFE_SB_Buffer_t *CFE_SB_AllocateMessageBuffer(size_t MsgSize)
{
UT_Stub_RegisterContextGenericArg(UT_KEY(CFE_SB_ZeroCopyGetPtr), MsgSize);
UT_Stub_RegisterContext(UT_KEY(CFE_SB_ZeroCopyGetPtr), BufferHandle);
UT_Stub_RegisterContextGenericArg(UT_KEY(CFE_SB_AllocateMessageBuffer), MsgSize);

int32 status;
CFE_SB_Buffer_t *SBBufPtr = NULL;

status = UT_DEFAULT_IMPL(CFE_SB_ZeroCopyGetPtr);
status = UT_DEFAULT_IMPL(CFE_SB_AllocateMessageBuffer);

if (status == CFE_SUCCESS)
{
UT_Stub_CopyToLocal(UT_KEY(CFE_SB_ZeroCopyGetPtr), &SBBufPtr, sizeof(SBBufPtr));
UT_Stub_CopyToLocal(UT_KEY(CFE_SB_AllocateMessageBuffer), &SBBufPtr, sizeof(SBBufPtr));
}

return SBBufPtr;
}

#ifndef CFE_OMIT_DEPRECATED_6_8
int32 CFE_SB_ZeroCopyPass(CFE_SB_Buffer_t *BufPtr, CFE_SB_ZeroCopyHandle_t BufferHandle)
{
UT_Stub_RegisterContext(UT_KEY(CFE_SB_ZeroCopyPass), BufPtr);
UT_Stub_RegisterContextGenericArg(UT_KEY(CFE_SB_ZeroCopyPass), BufferHandle);

int32 status;

status = UT_DEFAULT_IMPL(CFE_SB_ZeroCopyPass);

return status;
}
#endif

int32 CFE_SB_ZeroCopyReleasePtr(CFE_SB_Buffer_t *Ptr2Release, CFE_SB_ZeroCopyHandle_t BufferHandle)
{
UT_Stub_RegisterContext(UT_KEY(CFE_SB_ZeroCopyReleasePtr), Ptr2Release);
UT_Stub_RegisterContextGenericArg(UT_KEY(CFE_SB_ZeroCopyReleasePtr), BufferHandle);

int32 status;

status = UT_DEFAULT_IMPL(CFE_SB_ZeroCopyReleasePtr);

return status;
}

#ifndef CFE_OMIT_DEPRECATED_6_8
int32 CFE_SB_ZeroCopySend(CFE_SB_Buffer_t *BufPtr, CFE_SB_ZeroCopyHandle_t BufferHandle)
int32 CFE_SB_ReleaseMessageBuffer(CFE_SB_Buffer_t *BufPtr)
{
UT_Stub_RegisterContext(UT_KEY(CFE_SB_ZeroCopySend), BufPtr);
UT_Stub_RegisterContextGenericArg(UT_KEY(CFE_SB_ZeroCopySend), BufferHandle);
UT_Stub_RegisterContextGenericArg(UT_KEY(CFE_SB_ReleaseMessageBuffer), BufPtr);

int32 status;

status = UT_DEFAULT_IMPL(CFE_SB_ZeroCopySend);
status = UT_DEFAULT_IMPL(CFE_SB_ReleaseMessageBuffer);

return status;
}
#endif
Loading

0 comments on commit 410447e

Please sign in to comment.