New helper function: FreeRTOS_get_tx_base (#544)

* IPv4/single: new function: FreeRTOS_get_tx_base

* Changed some code comments and repaired a typo.

* Attempt to repair utest

* Changes after CI checks

* utest: Added tests for get_tx_base

* Do not use const socket type in FreeRTOS_get_tx_base()

* Removed comments from cmake  file ut

* Repaired UT

* Removed a nested if/endif couple

---------

Co-authored-by: Hein Tibosch <hein@htibosch.net>

source/FreeRTOS_Sockets.c

@@ -4364,7 +4364,49 @@ void vSocketWakeUpUser( FreeRTOS_Socket_t * pxSocket )
 #if ( ipconfigUSE_TCP == 1 )
 
 /**
- * @brief Get a direct pointer to the circular transmit buffer.
+ * @brief Get a direct pointer to the beginning of the circular transmit buffer.
+ *
+ * @param[in] xSocket: The socket owning the buffer.
+ *
+ * @return Address the first byte in the circular transmit buffer if all checks pass.
+ *         Or else, NULL is returned.
+ */
+    uint8_t * FreeRTOS_get_tx_base( Socket_t xSocket )
+    {
+        uint8_t * pucReturn = NULL;
+        FreeRTOS_Socket_t * pxSocket = ( FreeRTOS_Socket_t * ) xSocket;
+
+        /* Confirm that this is a TCP socket before dereferencing structure
+         * member pointers. */
+        if( prvValidSocket( pxSocket, FREERTOS_IPPROTO_TCP, pdFALSE ) == pdTRUE )
+        {
+            StreamBuffer_t * pxBuffer = pxSocket->u.xTCP.txStream;
+
+            /* If the TX buffer hasn't been created yet,
+             * and if no malloc error has occurred on this socket yet. */
+            if( ( pxBuffer == NULL ) &&
+                ( pxSocket->u.xTCP.bits.bMallocError == pdFALSE_UNSIGNED ) )
+            {
+                /* Create the outgoing stream only when it is needed */
+                ( void ) prvTCPCreateStream( pxSocket, pdFALSE );
+                pxBuffer = pxSocket->u.xTCP.txStream;
+            }
+
+            if( pxBuffer != NULL )
+            {
+                pucReturn = pxBuffer->ucArray;
+            }
+        }
+
+        return pucReturn;
+    }
+#endif /* ipconfigUSE_TCP */
+/*-----------------------------------------------------------*/
+
+#if ( ipconfigUSE_TCP == 1 )
+
+/**
+ * @brief Get a direct pointer to the TX head of the circular transmit buffer.
  *
  * @param[in] xSocket The socket owning the buffer.
  * @param[in] pxLength This will contain the number of bytes that may be written.
@@ -4387,7 +4429,10 @@ void vSocketWakeUpUser( FreeRTOS_Socket_t * pxSocket )
         {
             pxBuffer = pxSocket->u.xTCP.txStream;
 
-            if( ( pxBuffer == NULL ) && ( pxSocket->u.xTCP.bits.bMallocError != pdTRUE_UNSIGNED ) )
+            /* If the TX buffer hasn't been created yet,
+             * and if no malloc error has occurred on this socket yet. */
+            if( ( pxBuffer == NULL ) &&
+                ( pxSocket->u.xTCP.bits.bMallocError == pdFALSE_UNSIGNED ) )
             {
                 /* Create the outgoing stream only when it is needed */
                 ( void ) prvTCPCreateStream( pxSocket, pdFALSE );

source/include/FreeRTOS_Sockets.h

@@ -325,15 +325,12 @@
         BaseType_t FreeRTOS_shutdown( Socket_t xSocket,
                                       BaseType_t xHow );
 
-        #if ( ipconfigUSE_TCP == 1 )
-
 /* Release a TCP payload buffer that was obtained by
  * calling FreeRTOS_recv() with the FREERTOS_ZERO_COPY flag,
  * and a pointer to a void pointer. */
-            BaseType_t FreeRTOS_ReleaseTCPPayloadBuffer( Socket_t xSocket,
-                                                         void const * pvBuffer,
-                                                         BaseType_t xByteCount );
-        #endif /* ( ipconfigUSE_TCP == 1 ) */
+        BaseType_t FreeRTOS_ReleaseTCPPayloadBuffer( Socket_t xSocket,
+                                                     void const * pvBuffer,
+                                                     BaseType_t xByteCount );
 
 /* Returns the number of bytes available in the Rx buffer. */
         BaseType_t FreeRTOS_rx_size( ConstSocket_t xSocket );
@@ -367,6 +364,13 @@
 /* For internal use only: return the connection status. */
         BaseType_t FreeRTOS_connstatus( ConstSocket_t xSocket );
 
+/* For advanced applications only:
+ * Get a direct pointer to the beginning of the circular transmit buffer.
+ * In case the buffer was not yet created, it will be created in
+ * this call.
+ */
+        uint8_t * FreeRTOS_get_tx_base( Socket_t xSocket );
+
 /* For advanced applications only:
  * Get a direct pointer to the circular transmit buffer.
  * '*pxLength' will contain the number of bytes that may be written. */

test/unit-test/FreeRTOS_Sockets/FreeRTOS_Sockets_TCP_API_utest.c

@@ -1826,3 +1826,66 @@ void test_prvTCPSendLoop_NullBuffer()
 
     TEST_ASSERT_EQUAL( uxDataLength, xReturn );
 }
+
+/**
+ * @brief Invalid parameters passed to the function.
+ */
+void test_FreeRTOS_get_tx_base_InvalidParams( void )
+{
+    uint8_t * pucReturn;
+    FreeRTOS_Socket_t xSocket;
+    BaseType_t xLength;
+    size_t uxLength = 128;
+    size_t uxMallocSize;
+    StreamBuffer_t * pxBuffer;
+
+    memset( &xSocket, 0, sizeof( xSocket ) );
+    xSocket.u.xTCP.uxTxStreamSize = uxLength;
+
+    /* Invalid Protocol. */
+    pucReturn = FreeRTOS_get_tx_base( &xSocket );
+    TEST_ASSERT_EQUAL( NULL, pucReturn );
+
+    /* NULL socket. */
+    pucReturn = FreeRTOS_get_tx_base( NULL );
+    TEST_ASSERT_EQUAL( NULL, pucReturn );
+
+/*  FAIL: Memory Mismatch. Byte 0 Expected 0xB0 Was 0xE0. */
+/*  Function pvPortMalloc Argument xSize. Function called with unexpected argument value. */
+
+    /* Add an extra 4 (or 8) bytes. */
+    uxLength += sizeof( size_t );
+
+    /* And make the length a multiple of sizeof( size_t ). */
+    uxLength &= ~( sizeof( size_t ) - 1U );
+
+    uxMallocSize = ( sizeof( *pxBuffer ) + uxLength ) - sizeof( pxBuffer->ucArray );
+
+    pvPortMalloc_ExpectAndReturn( uxMallocSize, NULL );
+
+    vTCPStateChange_Expect( &xSocket, eCLOSE_WAIT );
+
+    /* NULL stream. */
+    xSocket.ucProtocol = FREERTOS_IPPROTO_TCP;
+    pucReturn = FreeRTOS_get_tx_base( &xSocket );
+    TEST_ASSERT_EQUAL( NULL, pucReturn );
+}
+
+/**
+ * @brief All fields of the socket are NULL.
+ */
+void test_FreeRTOS_get_tx_base_AllNULL( void )
+{
+    uint8_t * pucReturn;
+    FreeRTOS_Socket_t xSocket;
+    uint8_t ucStream[ ipconfigTCP_MSS ];
+
+    memset( &xSocket, 0, sizeof( xSocket ) );
+    memset( ucStream, 0, ipconfigTCP_MSS );
+
+    xSocket.ucProtocol = FREERTOS_IPPROTO_TCP;
+    xSocket.u.xTCP.txStream = ( StreamBuffer_t * ) ucStream;
+
+    pucReturn = FreeRTOS_get_tx_base( &xSocket );
+    TEST_ASSERT_EQUAL_PTR( ( ( StreamBuffer_t * ) ucStream )->ucArray, pucReturn );
+}

test/unit-test/FreeRTOS_Sockets/ut.cmake

@@ -26,6 +26,20 @@ list(APPEND mock_list
             "${MODULE_ROOT_DIR}/test/unit-test/${project_name}/Sockets_list_macros.h"
         )
 
+#  Without 'FreeRTOS_Sockets.h':
+#
+#   1 - FreeRTOS_Sockets_GenericAPI_utest (Not Run)
+#   2 - FreeRTOS_Sockets_TCP_API_utest (Not Run)
+#   3 - FreeRTOS_Sockets_UDP_API_utest (Not Run)
+#   4 - FreeRTOS_Sockets_privates_utest (Not Run)
+#
+#  With 'FreeRTOS_Sockets.h':
+#
+#   3 - FreeRTOS_Sockets_UDP_API_utest (Failed)
+#
+#   FAIL:Function FreeRTOS_recvfrom.  Called more times than expected.
+#   FAIL:Function FreeRTOS_sendto.  Called more times than expected.
+
 set(mock_include_list "")
 # list the directories your mocks need
 list(APPEND mock_include_list