Differentiate sync/async ByteStreamDriver and update ComStub to work with both (#3987)

* Update ByteStream interface, interface implementations (and UTs) and ComStub

* Update ComStub UTs

* Fix RHEL8 static cast failure

* spelling

* Update Async driver to async port

* Make code more readable... part 1

* Refactor code for human readability

* Update docs

* Remove unused helper

Author: thomas-bc

Drv/ByteStreamDriverModel/ByteStreamDriverModel.fpp

@@ -10,12 +10,17 @@ module Drv {
 
     @ 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
+    @ callback of an asynchronous send call
     port ByteStreamData(
         ref buffer: Fw.Buffer,
         status: ByteStreamStatus
     )
 
+    @ Synchronous only - Send data out through the byte stream
+    port ByteStreamSend(
+        ref sendBuffer: Fw.Buffer @< Data to send
+    ) -> ByteStreamStatus
+
     @ Signal indicating the driver is ready to send and received data
     port ByteStreamReady()
 

Drv/ByteStreamDriverModel/docs/sdd.md

@@ -5,10 +5,15 @@ The outgoing stream is represented by the input `send` port; other components ca
 
 ## Design
 
+There are two versions for the ByteStreamDriver, a synchronous version (`Drv.ByteStreamDriver`) and an asynchronous version (`Drv.AsyncByteStreamDriver`). In the synchronous version, the (guarded) `send` port blocks and returns status. In the asynchronous version, the (async) `send` port calls back on the `sendReturnOut` port to return status and buffer ownership.
+
 ### 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 `sendReturnOut` port to return the status of that send as well as returning ownership of the `Fw::Buffer` to the caller.
+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. 
+
+1. Async case: The driver component **must** perform a callback on its `sendReturnOut` port to return the status of that send as well as returning ownership of the `Fw::Buffer` to the caller.
+2. Sync case: The driver component **must** return a status of the send operation and 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 |
@@ -19,8 +24,7 @@ These responses are an enumeration whose values are described in the following t
 
 ### Receive
 
-In the callback formation, the byte stream driver component initiates the transfer of received data by calling the
-"recv" output port. This port transfers any read data in a `Fw::Buffer` along with a status for the receive.
+The byte stream driver component initiates the transfer of received data by calling the "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 |
@@ -29,7 +33,7 @@ This status is an enumeration whose values are described in the following table:
 | 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:
+The following components implement the byte stream model using the synchronous interface:
 - [`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

Drv/Interfaces/AsyncByteStreamDriver.fpp

@@ -0,0 +1,23 @@
+module Drv {
+    # In the asynchronous ByteStreamDriver interface, the send operation is non-blocking,
+    # and returns status through the sendReturnOut callback
+
+    @ Asynchronous ByteStreamDriver interface
+    interface AsyncByteStreamDriver {
+        @ Port invoked when the driver is ready to send/receive data
+        output port ready: Drv.ByteStreamReady
+
+        @ Port invoked by the driver when it receives data
+        output port $recv: Drv.ByteStreamData
+
+        @ Invoke this port to send data out the driver (asynchronous)
+        @ Status and ownership of the buffer are returned through the sendReturnOut callback
+        async input port $send: Fw.BufferSend
+
+        @ Port returning ownership of data received on $send port
+        output port sendReturnOut: Drv.ByteStreamData
+
+        @ Port receiving back ownership of data sent out on $recv port
+        guarded input port recvReturnIn: Fw.BufferSend
+    }
+}

Drv/Interfaces/ByteStreamDriver.fpp

@@ -1,16 +1,18 @@
 module Drv {
+    # In the synchronous ByteStreamDriver interface, the send operation is blocking
+    # and returns a send status
+
+    @ Synchronous ByteStreamDriver interface
     interface ByteStreamDriver {
         @ Port invoked when the driver is ready to send/receive data
         output port ready: Drv.ByteStreamReady
 
         @ Port invoked by the driver when it receives data
         output port $recv: Drv.ByteStreamData
 
-        @ Invoke this port to send data out the driver
-        guarded input port $send: Fw.BufferSend
-
-        @ Port returning ownership of data received on $send port
-        output port sendReturnOut: Drv.ByteStreamData
+        @ Invoke this port to send data out the driver (synchronous)
+        @ Status is returned, and ownership of the buffer is retained by the caller
+        guarded input port $send: Drv.ByteStreamSend
 
         @ Port receiving back ownership of data sent out on $recv port
         guarded input port recvReturnIn: Fw.BufferSend

Drv/Interfaces/CMakeLists.txt

@@ -8,6 +8,7 @@
 register_fprime_module(
     Drv_Interfaces
   AUTOCODER_INPUTS
+    "${CMAKE_CURRENT_LIST_DIR}/AsyncByteStreamDriver.fpp"
     "${CMAKE_CURRENT_LIST_DIR}/ByteStreamDriver.fpp"
     "${CMAKE_CURRENT_LIST_DIR}/Gpio.fpp"
     "${CMAKE_CURRENT_LIST_DIR}/I2c.fpp"

Drv/LinuxUartDriver/LinuxUartDriver.cpp

@@ -300,7 +300,7 @@ void LinuxUartDriver ::run_handler(FwIndexType portNum, U32 context) {
     this->tlmWrite_BytesRecv(this->m_bytesReceived);
 }
 
-void LinuxUartDriver ::send_handler(const FwIndexType portNum, Fw::Buffer& serBuffer) {
+Drv::ByteStreamStatus 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::ByteStreamStatus::OTHER_ERROR;
@@ -319,8 +319,7 @@ void LinuxUartDriver ::send_handler(const FwIndexType portNum, Fw::Buffer& serBu
             this->m_bytesSent += static_cast<FwSizeType>(stat);
         }
     }
-    // Return the buffer back to the caller
-    sendReturnOut_out(0, serBuffer, status);
+    return status;
 }
 
 void LinuxUartDriver::recvReturnIn_handler(FwIndexType portNum, Fw::Buffer& fwBuffer) {

Drv/LinuxUartDriver/LinuxUartDriver.hpp

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

Drv/TcpClient/TcpClientComponentImpl.cpp

@@ -70,7 +70,7 @@ void TcpClientComponentImpl::connected() {
 // Handler implementations for user-defined typed input ports
 // ----------------------------------------------------------------------
 
-void TcpClientComponentImpl::send_handler(const FwIndexType portNum, Fw::Buffer& fwBuffer) {
+Drv::ByteStreamStatus TcpClientComponentImpl::send_handler(const FwIndexType portNum, Fw::Buffer& fwBuffer) {
     FW_ASSERT_NO_OVERFLOW(fwBuffer.getSize(), U32);
     Drv::SocketIpStatus status = send(fwBuffer.getData(), static_cast<U32>(fwBuffer.getSize()));
     Drv::ByteStreamStatus returnStatus;
@@ -85,8 +85,7 @@ void TcpClientComponentImpl::send_handler(const FwIndexType portNum, Fw::Buffer&
             returnStatus = ByteStreamStatus::OTHER_ERROR;
             break;
     }
-    // Return the buffer and status to the caller
-    this->sendReturnOut_out(0, fwBuffer, returnStatus);
+    return returnStatus;
 }
 
 void TcpClientComponentImpl::recvReturnIn_handler(FwIndexType portNum, Fw::Buffer& fwBuffer) {

Drv/TcpClient/TcpClientComponentImpl.hpp

@@ -124,7 +124,7 @@ class TcpClientComponentImpl final : public TcpClientComponentBase, public Socke
      * \param portNum: fprime port number of the incoming port call
      * \param fwBuffer: buffer containing data to be sent
      */
-    void send_handler(const FwIndexType portNum, Fw::Buffer& fwBuffer) override;
+    Drv::ByteStreamStatus send_handler(const FwIndexType portNum, Fw::Buffer& fwBuffer) override;
 
     //! Handler implementation for recvReturnIn
     //!

Drv/TcpClient/test/ut/TcpClientTester.cpp

@@ -80,9 +80,7 @@ void TcpClientTester ::test_with_loop(U32 iterations, bool recv_thread) {
             Drv::Test::force_recv_timeout(server_fd.serverFd, server);
             m_data_buffer.setSize(sizeof(m_data_storage));
             size = Drv::Test::fill_random_buffer(m_data_buffer);
-            invoke_to_send(0, m_data_buffer);
-            ASSERT_from_sendReturnOut_SIZE(i + 1);
-            Drv::ByteStreamStatus status = this->fromPortHistory_sendReturnOut->at(i).status;
+            Drv::ByteStreamStatus status = invoke_to_send(0, m_data_buffer);
             EXPECT_EQ(status, ByteStreamStatus::OP_OK);
             Drv::Test::receive_all(server, server_fd, buffer, size);
             Drv::Test::validate_random_buffer(m_data_buffer, buffer);