Merge branch 'nasa:devel' into extern_params

Author: Brian Campuzano

.github/actions/spelling/expect.txt

@@ -48,6 +48,7 @@ ASTRING
 ATester
 ATL
 ATMs
+ATSAM
 atypes
 AUTOBRIEF
 autocode
@@ -86,9 +87,9 @@ BUFFERALLOCATIONFAILED
 BUFFERGETOUT
 BUFFERMANAGERCOMPONENTIMPLCFG
 BUFFERMGR
+BUFFERQUEUEIN
 BUFFERTOOSMALLFORDATA
 BUFFERTOOSMALLFORPACKET
-BUFFQUEUEIN
 buffsize
 BUGLIST
 bugprone
@@ -156,6 +157,7 @@ COMMANDDISPATCHERIMPLCFG
 commandline
 commasepitem
 COMPACKET
+COMPACKETQUEUEIN
 COMPONENTTESTERIMPL
 COMQUEUE
 COMQUEUEIN
@@ -435,6 +437,7 @@ hidecallgraph
 hideinitializer
 hlp
 HLTH
+HPSC
 htags
 HTH
 htmlfile
@@ -699,6 +702,7 @@ pbuild
 pcmake
 pcomp
 pdflatex
+PEB
 Peet
 penv
 PERLMOD
@@ -1070,6 +1074,7 @@ viewcontent
 viewforum
 vla
 vlist
+VOXL
 vtype
 vuejs
 vwong

.github/actions/spelling/patterns.txt

@@ -137,3 +137,12 @@ TeX/AMS
 
 # ignore long runs of a single character:
 \b([A-Za-z])\g{-1}{3,}\b
+
+
+##########################################
+###### F Prime specific patterns    ######
+##########################################
+
+# .get...() .set...() autocoded functions
+\.get\w+\(
+\.set\w+\(

Drv/ByteStreamDriverModel/ByteStreamDriverModel.fpp

@@ -1,40 +1,22 @@
 module Drv {
 
     @ Status returned by the send call
-    enum SendStatus {
-        SEND_OK = 0 @< Send worked as expected
-        SEND_RETRY = 1 @< Data send should be retried
-        SEND_ERROR = 2 @< Send error occurred retrying may succeed
+    enum ByteStreamStatus {
+        OP_OK         @< Operation worked as expected
+        SEND_RETRY    @< Data send should be retried
+        RECV_NO_DATA  @< Receive worked, but there was no data 
+        OTHER_ERROR   @< Error occurred, retrying may succeed
     }
 
-    @ Send data out through the byte stream
-    port ByteStreamSend(
-        ref sendBuffer: Fw.Buffer @< Data to send
-    ) -> SendStatus
-
-    @ Status associated with the received data
-    enum RecvStatus {
-        RECV_OK = 0 @< Receive worked as expected
-        RECV_NO_DATA = 1 @< Receive worked, but there was no data 
-        RECV_ERROR = 2 @< Receive error occurred retrying may succeed
-    }
-
-    @ Carries the received bytes stream driver
-    port ByteStreamRecv(
-        ref recvBuffer: Fw.Buffer
-        recvStatus: RecvStatus
+    @ Port to exchange buffer and status with the ByteStreamDriver model
+    @ This port is used for receiving data from the driver as well as on
+    @ callback of a send call
+    port ByteStreamData(
+        ref buffer: Fw.Buffer,
+        status: ByteStreamStatus
     )
 
-    enum PollStatus {
-        POLL_OK = 0 @< Poll successfully received data
-        POLL_RETRY = 1 @< No data available, retry later
-        POLL_ERROR = 2 @< Error received when polling
-    }
-
-    port ByteStreamPoll(
-        ref pollBuffer: Fw.Buffer
-    ) -> PollStatus
-
     @ Signal indicating the driver is ready to send and received data
     port ByteStreamReady()
+
 }

Drv/ByteStreamDriverModel/changed-symbols.txt

@@ -1,57 +1,40 @@
 # Drv::ByteStreamDriverModel Byte Stream Driver Model
 
-The byte stream driver is a generic model for drivers implementing a "stream of bytes" interface. Typically these
-drivers operate with an outgoing stream and an incoming stream. The outgoing stream is represented by the "send" port
-and the incoming stream is either polled using the "poll" port or return asynchronously via the "readCallback" port.
+The byte stream driver is a generic model for drivers implementing a "stream of bytes" interface. Typically these drivers operate with an outgoing stream and an incoming stream.  
+The outgoing stream is represented by the input `send` port; other components can invoke this port to send data through the driver. The incoming stream is represented by the output `recv` port; the driver will call this port to send data to the component that is receiving data from the driver.
 
 ## Design
 
-The manager component (typically the ground interface) initiates the transfer of send data by calling the "send" port.
-The caller will provide a `Fw::Buffer` containing the data to send and the port call will return a status of that send.
+### Send
+
+The manager component (for example a radio manager) initiates the transfer of send data by calling the "send" port.
+The caller will provide a `Fw::Buffer` containing the data to send. The driver component **must** perform a callback on its `dataReturnOut` port to return the status of that send as well as returning ownership of the `Fw::Buffer` to the caller.
 These responses are an enumeration whose values are described in the following table:
 
 | Value | Description | Buffer Ownership |
 |---|---|---|
-| Drv::SEND_OK    | Send functioned normally. | Ownership of the `Fw::Buffer` passes to the byte stream driver. |
-| Drv::SEND_RETRY | Send should be retried, but a subsequent send should return SEND_OK. | The caller retains ownership of the `Fw::Buffer`. |
-| Drv::SEND_ERROR | Send produced an error, future sends likely to fail. | Ownership of the `Fw::Buffer` passes to the byte stream driver. |
-
-**Note:** in either formation described below, send will operate as described here.
+| ByteStreamStatus::OP_OK    | Send functioned normally. | Ownership of the `Fw::Buffer` passes to the byte stream driver. |
+| ByteStreamStatus::SEND_RETRY | Send should be retried, but a subsequent send should return OP_OK. | The caller retains ownership of the `Fw::Buffer`. |
+| ByteStreamStatus::OTHER_ERROR | Send produced an error, future sends likely to fail. | Ownership of the `Fw::Buffer` passes to the byte stream driver. |
 
-### Callback Formation
+### Receive
 
 ![Callback](./img/canvas-callback.png)
 
 In the callback formation, the byte stream driver component initiates the transfer of received data by calling the
-"readCallback" output port. This port transfers any read data in a `Fw::Buffer` along with a status for the receive.
+"recv" output port. This port transfers any read data in a `Fw::Buffer` along with a status for the receive.
 This status is an enumeration whose values are described in the following table:
 
 | Value | Description |
 |---|---|
-| Drv::RECV_OK    | Receive functioned normally buffer contains valid data. |
-| Drv::RECV_ERROR | Receive produced an error and buffer contains no valid data. |
+| ByteStreamStatus::OP_OK    | Receive functioned normally and buffer contains valid data. |
+| ByteStreamStatus::RECV_NO_DATA    | Receive worked, but there was no data  |
+| ByteStreamStatus::OTHER_ERROR | Receive produced an error and buffer contains no valid data. |
 
 The following components implement the byte stream model using a callback formation:
-- `DrvTcpClient`: a F´ component wrapper of the tcp client
-- `DrvTcpServer`: a F´ component wrapper of the tcp server
-- `DrvUdp`: a F´ component wrapper of the udp
-
-### Polling Formation
-
-![Poll](./img/canvas-poll.png)
-
-In the polling formation, the manager component (typically the ground interface) initiates the transfer of received
-data by calling the "poll" input port. This port fills in the provided `Fw::Buffer` along with a status for the poll.
-This status is an enumeration whose values are described in the following table:
-
-| Value | Description |
-|---|---|
-| Drv::POLL_OK    | Poll functioned normally buffer contains valid data. |
-| Drv::POLL_RETRY | Poll should be retried and a subsequent send should return POLL_OK. |
-| Drv::POLL_ERROR | Poll produced an error and buffer contains no valid data. |
-
-**Note:**  there are no known implementers of the polling formation, although this formation is best suited for
-implementations running on baremetal machines.
+- [`Drv::TcpClient`](../../TcpClient/docs/sdd.md): a F´ component wrapper of the tcp client
+- [`Drv::TcpServer`](../../TcpServer/docs/sdd.md): a F´ component wrapper of the tcp server
+- [`Drv::Udp`](../../Udp/docs/sdd.md): a F´ component wrapper of the udp
 
 ## Class Diagram
 ![classdiagram](./img/class_diagram.png)
@@ -61,5 +44,4 @@ implementations running on baremetal machines.
 | Name | Description | Validation |
 |---|---|---|
 | BYTEDRV-001 | The ByteStreamDriverModel shall provide the capability to send bytes | inspection |
-| BYTEDRV-002 | The ByteStreamDriverModel shall provide the capability to poll for bytes | inspection |
-| BYTEDRV-003 | The ByteStreamDriverModel shall provide the capability to produce bytes | inspection |
+| BYTEDRV-002 | The ByteStreamDriverModel shall provide the capability to produce bytes | inspection |

Drv/ByteStreamDriverModel/docs/sdd.md

@@ -10,7 +10,6 @@ add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/LinuxGpioDriver/")
 add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/LinuxUartDriver/")
 add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/LinuxSpiDriver/")
 add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/LinuxI2cDriver/")
-add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/StreamCrossover/")
 
 add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/Ip/")
 add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/TcpClient/")

Drv/CMakeLists.txt

@@ -1,8 +1,11 @@
     @ Port invoked when the driver is ready to send/receive data
     output port ready: Drv.ByteStreamReady
 
-    @ Port invoked when driver has received data
-    output port $recv: Drv.ByteStreamRecv
+    @ Port invoked by the driver when it receives data
+    output port $recv: Drv.ByteStreamData
 
-    @ Port invoked to send data out the driver
-    guarded input port $send: Drv.ByteStreamSend
+    @ Invoke this port to send data out the driver
+    guarded input port $send: Fw.BufferSend
+
+    @ Port invoked to return ownership of sent data back to the sender
+    output port dataReturnOut: Drv.ByteStreamData

Drv/Interfaces/ByteStreamDriverInterface.fppi

@@ -292,10 +292,10 @@ LinuxUartDriver ::~LinuxUartDriver() {
 // Handler implementations for user-defined typed input ports
 // ----------------------------------------------------------------------
 
-Drv::SendStatus LinuxUartDriver ::send_handler(const FwIndexType portNum, Fw::Buffer& serBuffer) {
-    Drv::SendStatus status = Drv::SendStatus::SEND_OK;
+void LinuxUartDriver ::send_handler(const FwIndexType portNum, Fw::Buffer& serBuffer) {
+    Drv::ByteStreamStatus status = Drv::ByteStreamStatus::OP_OK;
     if (this->m_fd == -1 || serBuffer.getData() == nullptr || serBuffer.getSize() == 0) {
-        status = Drv::SendStatus::SEND_ERROR;
+        status = Drv::ByteStreamStatus::OTHER_ERROR;
     } else {
         unsigned char *data = serBuffer.getData();
         FW_ASSERT(static_cast<size_t>(serBuffer.getSize()) <= std::numeric_limits<size_t>::max(),
@@ -307,28 +307,25 @@ Drv::SendStatus LinuxUartDriver ::send_handler(const FwIndexType portNum, Fw::Bu
         if (-1 == stat || static_cast<size_t>(stat) != xferSize) {
           Fw::LogStringArg _arg = this->m_device;
           this->log_WARNING_HI_WriteError(_arg, static_cast<I32>(stat));
-          status = Drv::SendStatus::SEND_ERROR;
+          status = Drv::ByteStreamStatus::OTHER_ERROR;
         }
     }
-    // Deallocate when necessary
-    if (isConnected_deallocate_OutputPort(0)) {
-        deallocate_out(0, serBuffer);
-    }
-    return status;
+    // Return the buffer back to the caller
+    dataReturnOut_out(0, serBuffer, status);
 }
 
 void LinuxUartDriver ::serialReadTaskEntry(void* ptr) {
     FW_ASSERT(ptr != nullptr);
-    Drv::RecvStatus status = RecvStatus::RECV_ERROR;  // added by m.chase 03.06.2017
+    Drv::ByteStreamStatus status = ByteStreamStatus::OTHER_ERROR;  // added by m.chase 03.06.2017
     LinuxUartDriver* comp = reinterpret_cast<LinuxUartDriver*>(ptr);
     while (!comp->m_quitReadThread) {
         Fw::Buffer buff = comp->allocate_out(0,comp->m_allocationSize);
 
-        // On failed allocation, error and deallocate
+        // On failed allocation, error
         if (buff.getData() == nullptr) {
             Fw::LogStringArg _arg = comp->m_device;
             comp->log_WARNING_HI_NoBuffers(_arg);
-            status = RecvStatus::RECV_ERROR;
+            status = ByteStreamStatus::OTHER_ERROR;
             comp->recv_out(0, buff, status);
             // to avoid spinning, wait 50 ms
             Os::Task::delay(Fw::TimeInterval(0, 50000));
@@ -350,12 +347,12 @@ void LinuxUartDriver ::serialReadTaskEntry(void* ptr) {
         if (stat == -1) {
             Fw::LogStringArg _arg = comp->m_device;
             comp->log_WARNING_HI_ReadError(_arg, stat);
-            status = RecvStatus::RECV_ERROR;
+            status = ByteStreamStatus::OTHER_ERROR;
         } else if (stat > 0) {
             buff.setSize(static_cast<U32>(stat));
-            status = RecvStatus::RECV_OK;  // added by m.chase 03.06.2017
+            status = ByteStreamStatus::OP_OK;  // added by m.chase 03.06.2017
         } else {
-            status = RecvStatus::RECV_ERROR; // Simply to return the buffer
+            status = ByteStreamStatus::OTHER_ERROR; // Simply to return the buffer
         }
         comp->recv_out(0, buff, status);  // added by m.chase 03.06.2017
     }

Drv/LinuxUartDriver/LinuxUartDriver.cpp

@@ -11,9 +11,6 @@ module Drv {
     @ Allocation port used for allocating memory in the receive task
     output port allocate: Fw.BufferGet
 
-    @ Deallocates buffers passed to the "send" port
-    output port deallocate: Fw.BufferSend
-
     # ----------------------------------------------------------------------
     # Special ports
     # ----------------------------------------------------------------------

Drv/LinuxUartDriver/LinuxUartDriver.fpp

@@ -93,7 +93,7 @@ class LinuxUartDriver final : public LinuxUartDriverComponentBase {
 
     //! Handler implementation for serialSend
     //!
-    Drv::SendStatus send_handler(FwIndexType portNum, /*!< The port number*/
+    void send_handler(FwIndexType portNum, /*!< The port number*/
                                  Fw::Buffer& serBuffer);