WIP #1009, CFE_SB_RcvMsg -> CFE_SB_ReceiveBuffer

docs/cFE Application Developers Guide.md

@@ -1080,7 +1080,7 @@ void SAMPLE_TaskMain(void)
         /*
         ** Wait for the next Software Bus message
         */
-        Status = CFE_SB_RcvMsg(&SBBufPtr, SAMPLE_TaskData.CmdPipe, CFE_SB_PEND_FOREVER);
+        Status = CFE_SB_ReceiveBuffer(&SBBufPtr, SAMPLE_TaskData.CmdPipe, CFE_SB_PEND_FOREVER);
 
         if (Status == CFE_SUCCESS)
         {
@@ -1246,7 +1246,7 @@ void XX_AppMain(void)
         CFE_ES_PerfLogExit(XX_APPMAIN_PERF_ID);
 
         /* Wait for the next Software Bus message */
-        Result = CFE_SB_RcvMsg(&SBBufPtr, XX_GlobalData.CmdPipe, CFE_SB_PEND_FOREVER);
+        Result = CFE_SB_ReceiveBuffer(&SBBufPtr, XX_GlobalData.CmdPipe, CFE_SB_PEND_FOREVER);
 
         /* Performance Log (start time counter) */
         CFE_ES_PerfLogEntry(XX_APPMAIN_PERF_ID);
@@ -1812,7 +1812,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_RcvMsg.  Since most
+To receive a SB 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.
 
@@ -1838,7 +1838,7 @@ FILE: sample_app.c
        /*
        ** Wait for the next Software Bus message...
        */
-        SB_Status = CFE_SB_RcvMsg(&SBBufPtr,
+        SB_Status = CFE_SB_ReceiveBuffer(&SBBufPtr,
                                    SAMPLE_AppData.CmdPipe,
                                    CFE_SB_PEND_FOREVER);
 
@@ -1864,7 +1864,7 @@ CFE_SB_PEND_FOREVER).
 
 If a SB 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_RcvMsg API is called, the cFE will return
+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

docs/src/cfe_api.dox

@@ -134,7 +134,7 @@
     <LI> \ref CFEAPISBMessage
     <UL>
       <LI> #CFE_SB_TransmitMsg - \copybrief CFE_SB_TransmitMsg
-      <LI> #CFE_SB_RcvMsg - \copybrief CFE_SB_RcvMsg
+      <LI> #CFE_SB_ReceiveBuffer - \copybrief CFE_SB_ReceiveBuffer
     </UL>
     <LI> \ref CFEAPISBZeroCopy
     <UL>

docs/src/cfe_sb.dox

@@ -166,7 +166,7 @@
   buffer descriptor (CFE_SB_BufferD_t) and one for the size of the packet. Both buffers
   are returned to the pool when the message has been received by all recipients. More
   precisely, if there is one recipient for a message, the message buffers will be released
-  on the following call to cFE_SB_RcvMsg for the pipe that received the message.
+  on the following call to CFE_SB_ReceiveBuffer for the pipe that received the buffer.
 
   Also when subscriptions are received through the subscribe API's, the software bus
   allocates a subscription block (CFE_SB_DestinationD_t) from the pool. The subscription
@@ -509,30 +509,28 @@
         </B><TR><TD WIDTH="5%"> &nbsp; <TD WIDTH="95%">
            There is a single copy of the message performed during a typical delivery.
            When transmitting a message, the software bus copies the message from the
-           callers memory space to the software bus memory space. The #CFE_SB_RcvMsg API
-           gives the user a pointer to the message in the software bus memory space. This
+           callers memory space into a buffer in the software bus memory space.
+           The #CFE_SB_ReceiveBuffer API gives the user back a pointer to the buffer. This
            is equivalent to the copy mode send and pointer mode receive in the heritage
            software bus used on WMAP, ST5, SDO etc.
         <TR><TD COLSPAN=2 WIDTH="100%"> <B>(Q)
-           When does the software bus free the message buffer during a typical message
-           delivery process? Or how long is the message, and the pointer to the message
-           in the #CFE_SB_RcvMsg valid?
+           When does the software bus free the buffer during a typical message
+           delivery process? Or how long is the message, and the pointer to the buffer
+           in the #CFE_SB_ReceiveBuffer valid?
         </B><TR><TD WIDTH="5%"> &nbsp; <TD WIDTH="95%">
-           After receiving a message by calling #CFE_SB_RcvMsg, the message received stays
-           in the software bus memory until the next call to #CFE_SB_RcvMsg with the same
-           Pipe Id. This means that the message pointer given by the software bus to the
-           caller of #CFE_SB_RcvMsg is valid until the next call to #CFE_SB_RcvMsg with the
-           same pipe id. If the caller needs the message longer than the next call to
-           #CFE_SB_RcvMsg, the caller must copy the message to its memory space.
+           After receiving a buffer by calling #CFE_SB_ReceiveBuffer, the buffer received is valid
+           until the next call to #CFE_SB_ReceiveBuffer with the same Pipe Id.
+           If the caller needs the message longer than the next call to
+           #CFE_SB_ReceiveBuffer, the caller must copy the message to its memory space.
         <TR><TD COLSPAN=2 WIDTH="100%"> <B>(Q)
-           The first parameter in the #CFE_SB_RcvMsg API is a pointer to a pointer which
+           The first parameter in the #CFE_SB_ReceiveBuffer API is a pointer to a pointer which
            can get confusing. How can I be sure that the correct address is given for this
            parameter.
         </B><TR><TD WIDTH="5%"> &nbsp; <TD WIDTH="95%">
-           Typically a caller declares a ptr of type CFE_MSG_Message_t (i.e. CFE_MSG_Message_t *Ptr)
+           Typically a caller declares a ptr of type CFE_SB_Buffer_t (i.e. CFE_SB_Buffer_t *Ptr)
            then gives the address of that pointer (&Ptr) as this parameter. After a successful
-           call to #CFE_SB_RcvMsg, Ptr 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
+           call to #CFE_SB_ReceiveBuffer, Ptr will point to the first byte of the software bus
+           buffer. This should be used as a read-only pointer. In systems with an MMU, writes
            to this pointer may cause a memory protection fault.
         <TR><TD COLSPAN=2 WIDTH="100%"> <B>(Q)
            Why am I not seeing expected Message Limit error events or Pipe Overflow events?
@@ -569,7 +567,7 @@
            will ensure seamless integration when the software bus is expanded to support
            inter-processor communication.
         <TR><TD COLSPAN=2 WIDTH="100%"> <B>(Q)
-           Can I confirm my software bus message was delivered?
+           Can I confirm my software bus buffer was delivered?
         </B><TR><TD WIDTH="5%"> &nbsp; <TD WIDTH="95%">
            There is no built in mechanism for confirming delivery (it could span systems).
            This could be accomplished by generating a response message from the receiver.

fsw/cfe-core/src/es/cfe_es_task.c

@@ -136,7 +136,7 @@ void CFE_ES_TaskMain(void)
         /*
         ** Wait for the next Software Bus message.
         */
-        Status = CFE_SB_RcvMsg(&SBBufPtr, CFE_ES_TaskData.CmdPipe, CFE_SB_PEND_FOREVER);
+        Status = CFE_SB_ReceiveBuffer(&SBBufPtr, CFE_ES_TaskData.CmdPipe, CFE_SB_PEND_FOREVER);
 
         /*
         ** Performance Time Stamp Entry

fsw/cfe-core/src/evs/cfe_evs_task.c

@@ -244,7 +244,7 @@ void CFE_EVS_TaskMain(void)
         CFE_ES_PerfLogExit(CFE_MISSION_EVS_MAIN_PERF_ID);
 
         /* Pend on receipt of packet */
-        Status = CFE_SB_RcvMsg(&SBBufPtr,
+        Status = CFE_SB_ReceiveBuffer(&SBBufPtr,
                                CFE_EVS_GlobalData.EVS_CommandPipe, 
                                CFE_SB_PEND_FOREVER);
 
@@ -260,7 +260,7 @@ void CFE_EVS_TaskMain(void)
 
     }/* end while */
 
-    /* while loop exits only if CFE_SB_RcvMsg returns error */
+    /* while loop exits only if CFE_SB_ReceiveBuffer returns error */
     CFE_ES_ExitApp(CFE_ES_RunStatus_CORE_APP_RUNTIME_ERROR);
 
 } /* end CFE_EVS_TaskMain */

fsw/cfe-core/src/inc/cfe_error.h

@@ -717,7 +717,7 @@ typedef int32 CFE_Status_t;
 /**
  * @brief Time Out
  *
- *  In #CFE_SB_RcvMsg, this return value indicates that a packet has not 
+ *  In #CFE_SB_ReceiveBuffer, this return value indicates that a packet has not 
  *  been received in the time given in the "timeout" parameter.
  *
  */
@@ -727,7 +727,7 @@ typedef int32 CFE_Status_t;
 /**
  * @brief No Message
  *
- *  When "Polling" a pipe for a message in #CFE_SB_RcvMsg, this return 
+ *  When "Polling" a pipe for a message in #CFE_SB_ReceiveBuffer, this return 
  *  value indicates that there was not a message on the pipe.
  *
  */

fsw/cfe-core/src/inc/cfe_sb.h

@@ -48,8 +48,8 @@
 /*
 ** Defines
 */
-#define CFE_SB_POLL                     0      /**< \brief Option used with #CFE_SB_RcvMsg to request immediate pipe status */
-#define CFE_SB_PEND_FOREVER            -1      /**< \brief Option used with #CFE_SB_RcvMsg to force a wait for next message */
+#define CFE_SB_POLL                     0      /**< \brief Option used with #CFE_SB_ReceiveBuffer to request immediate pipe status */
+#define CFE_SB_PEND_FOREVER            -1      /**< \brief Option used with #CFE_SB_ReceiveBuffer to force a wait for next message */
 #define CFE_SB_SUB_ENTRIES_PER_PKT      20     /**< \brief Configuration parameter used by SBN App */
 #define CFE_SB_SUBSCRIPTION             0      /**< \brief Subtype specifier used in #CFE_SB_SingleSubscriptionTlm_t by SBN App */
 #define CFE_SB_UNSUBSCRIPTION           1      /**< \brief Subtype specified used in #CFE_SB_SingleSubscriptionTlm_t by SBN App */
@@ -154,7 +154,7 @@ typedef CFE_MSG_TelemetryHeader_t CFE_SB_TlmHdr_t;
 
 /** \brief  CFE_SB_TimeOut_t to primitive type definition
 **
-** Internally used by SB in the #CFE_SB_RcvMsg API. Translated from the
+** Internally used by SB in the #CFE_SB_ReceiveBuffer API. Translated from the
 ** input parmater named TimeOut which specifies the maximum time in
 ** milliseconds that the caller wants to wait for a message.
 */
@@ -619,18 +619,16 @@ CFE_Status_t  CFE_SB_PassMsg(CFE_MSG_Message_t *MsgPtr);
 **          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 message pointer.
+** \param[in, out] BufPtr   A pointer to the software bus buffer to receive to.
 **                          Typically a caller declares a ptr of type CFE_SB_Buffer_t
 **                          (i.e. CFE_SB_Buffer_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
+**                          byte of the software bus buffer. 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.
+**                          CFE_SB_ReceiveBuffer for the same pipe.
 **
 ** \param[in]  PipeId       The pipe ID of the pipe containing the message to be obtained.
 **
@@ -646,7 +644,15 @@ CFE_Status_t  CFE_SB_PassMsg(CFE_MSG_Message_t *MsgPtr);
 ** \retval #CFE_SB_PIPE_RD_ERR  \copybrief CFE_SB_PIPE_RD_ERR
 ** \retval #CFE_SB_NO_MESSAGE   \copybrief CFE_SB_NO_MESSAGE
 **/
-CFE_Status_t  CFE_SB_RcvMsg(CFE_SB_Buffer_t **BufPtr, CFE_SB_PipeId_t PipeId, int32 TimeOut);
+CFE_Status_t CFE_SB_ReceiveBuffer(CFE_SB_Buffer_t **BufPtr, CFE_SB_PipeId_t PipeId, int32 TimeOut);
+
+#if CFE_OMIT_DEPRECATED_6_8
+/**
+ * \brief DEPRECATED: receive buffer
+ * \deprecated use CFE_SB_ReceiveBuffer
+ */
+CFE_Status_t CFE_SB_RcvMsg(CFE_SB_Buffer_t **BufPtr, CFE_SB_PipeId_t PipeId, int32 TimeOut);
+#endif /* CFE_OMIT_DEPRECATED_6_8 */
 /**@}*/
 
 /** @defgroup CFEAPISBZeroCopy cFE Zero Copy APIs

fsw/cfe-core/src/inc/cfe_sb_events.h

@@ -439,7 +439,7 @@
 **  \par Cause:
 **
 **  This error event message is issued when an invalid paramter is passed into the
-**  #CFE_SB_RcvMsg API. Two possibile problems would be the first parameter (*BufPtr)
+**  #CFE_SB_ReceiveBuffer API. Two possibile problems would be the first parameter (*BufPtr)
 **  being NULL or the third paramter (TimeOut) being less than -1.
 **/
 #define CFE_SB_RCV_BAD_ARG_EID          18
@@ -452,7 +452,7 @@
 **  \par Cause:
 **
 **  This error event message is issued when an invalid PipeId is passed into the
-**  #CFE_SB_RcvMsg API. The SB Pipe Table shows all valid PipeIds and may be viewed
+**  #CFE_SB_ReceiveBuffer API. The SB Pipe Table shows all valid PipeIds and may be viewed
 **  for verification.
 **/
 #define CFE_SB_BAD_PIPEID_EID           19

fsw/cfe-core/src/sb/cfe_sb_api.c

@@ -346,7 +346,7 @@ int32 CFE_SB_DeletePipeFull(CFE_SB_PipeId_t PipeId,CFE_ES_ResourceID_t AppId)
     /* this step will free the memory used to store the message */
     do{
       CFE_SB_UnlockSharedData(__func__,__LINE__);
-      Stat = CFE_SB_RcvMsg(&BufPtr,PipeId,CFE_SB_POLL);
+      Stat = CFE_SB_ReceiveBuffer(&BufPtr,PipeId,CFE_SB_POLL);
       CFE_SB_LockSharedData(__func__,__LINE__);
     }while(Stat == CFE_SUCCESS);
 
@@ -1455,12 +1455,21 @@ int32  CFE_SB_TransmitBufferFull(CFE_SB_BufferD_t *BufDscPtr,
 
 }
 
+#if CFE_OMIT_DEPRECATED_6_8
+int32 CFE_SB_RcvMsg(CFE_SB_Buffer_t **BufPtr,
+                    CFE_SB_PipeId_t   PipeId,
+                    int32             TimeOut)
+{
+    return CFE_SB_ReceiveBuffer(BufPtr, PipeId, TimeOut);
+}
+#endif /* CFE_OMIT_DEPRECATED_6_8 */
+
 /*
- * Function: CFE_SB_RcvMsg - See API and header file for details
+ * Function: CFE_SB_ReceiveBuffer - See API and header file for details
  */
-int32  CFE_SB_RcvMsg(CFE_SB_Buffer_t **BufPtr,
-                     CFE_SB_PipeId_t   PipeId,
-                     int32             TimeOut)
+int32  CFE_SB_ReceiveBuffer(CFE_SB_Buffer_t **BufPtr,
+                            CFE_SB_PipeId_t   PipeId,
+                            int32             TimeOut)
 {
     int32                  Status;
     CFE_SB_BufferD_t       *Message;
@@ -1530,7 +1539,7 @@ int32  CFE_SB_RcvMsg(CFE_SB_Buffer_t **BufPtr,
         /*
         ** Load the pipe tables 'CurrentBuff' with the buffer descriptor
         ** ptr corresponding to the message just read. This is done so that
-        ** the buffer can be released on the next RcvMsg call for this pipe.
+        ** the buffer can be released on the next receive call for this pipe.
         */
         PipeDscPtr->CurrentBuff = Message;
 
@@ -1577,7 +1586,7 @@ int32  CFE_SB_RcvMsg(CFE_SB_Buffer_t **BufPtr,
     */
     return Status;
 
-}/* end CFE_SB_RcvMsg */
+}
 
 
 /*

fsw/cfe-core/src/sb/cfe_sb_task.c

@@ -104,7 +104,7 @@ void CFE_SB_TaskMain(void)
         CFE_ES_PerfLogExit(CFE_MISSION_SB_MAIN_PERF_ID);
 
         /* Pend on receipt of packet */
-        Status = CFE_SB_RcvMsg(&SBBufPtr,
+        Status = CFE_SB_ReceiveBuffer(&SBBufPtr,
                                 CFE_SB.CmdPipe,
                                 CFE_SB_PEND_FOREVER);
 
@@ -120,7 +120,7 @@ void CFE_SB_TaskMain(void)
 
     }/* end while */
 
-    /* while loop exits only if CFE_SB_RcvMsg returns error */
+    /* while loop exits only if CFE_SB_ReceiveBuffer returns error */
     CFE_ES_ExitApp(CFE_ES_RunStatus_CORE_APP_RUNTIME_ERROR);
 
 }/* end CFE_SB_TaskMain */

fsw/cfe-core/src/tbl/cfe_tbl_task.c

@@ -123,7 +123,7 @@ void CFE_TBL_TaskMain(void)
         CFE_ES_PerfLogExit(CFE_MISSION_TBL_MAIN_PERF_ID);
 
         /* Pend on receipt of packet */
-        Status = CFE_SB_RcvMsg( &SBBufPtr,
+        Status = CFE_SB_ReceiveBuffer( &SBBufPtr,
                                 CFE_TBL_TaskData.CmdPipe,
                                 CFE_SB_PEND_FOREVER);
 
@@ -139,7 +139,7 @@ void CFE_TBL_TaskMain(void)
 
     }/* end while */
 
-    /* while loop exits only if CFE_SB_RcvMsg returns error */
+    /* while loop exits only if CFE_SB_ReceiveBuffer returns error */
     CFE_ES_ExitApp(CFE_ES_RunStatus_CORE_APP_RUNTIME_ERROR);
 
 } /* end CFE_TBL_TaskMain() */

fsw/cfe-core/src/time/cfe_time_task.c

@@ -168,7 +168,7 @@ void CFE_TIME_TaskMain(void)
       CFE_ES_PerfLogExit(CFE_MISSION_TIME_MAIN_PERF_ID);
 
       /* Pend on receipt of packet */
-      Status = CFE_SB_RcvMsg(&SBBufPtr,
+      Status = CFE_SB_ReceiveBuffer(&SBBufPtr,
                               CFE_TIME_TaskData.CmdPipe,
                               CFE_SB_PEND_FOREVER);
 
@@ -184,7 +184,7 @@ void CFE_TIME_TaskMain(void)
 
     }/* end while */
 
-    /* while loop exits only if CFE_SB_RcvMsg returns error */
+    /* while loop exits only if CFE_SB_ReceiveBuffer returns error */
     CFE_ES_ExitApp(CFE_ES_RunStatus_CORE_APP_RUNTIME_ERROR);
 
 } /* end CFE_TIME_TaskMain */