Index: firmware/App/Services/CommBuffers.c =================================================================== diff -u -rf688e0f8bded1f0a687437e3136cfba8b14f87b6 -r3518e8a088c32e75c0c8960d5e629a7401095feb --- firmware/App/Services/CommBuffers.c (.../CommBuffers.c) (revision f688e0f8bded1f0a687437e3136cfba8b14f87b6) +++ firmware/App/Services/CommBuffers.c (.../CommBuffers.c) (revision 3518e8a088c32e75c0c8960d5e629a7401095feb) @@ -15,11 +15,10 @@ * ***************************************************************************/ -#include -#include #include // For memcpy() #include "CommBuffers.h" +#include "Messaging.h" #include "SystemCommTD.h" #include "Timers.h" @@ -30,16 +29,16 @@ // ********** private definitions ********** -#define COMM_BUFFER_LENGTH 768 ///< Max bytes in each comm buffer (each side of double buffer is this size) -#define DOUBLE_BUFFERS 2 ///< Need 2 buffers for double buffering -#define BUFFER_OVERFLOW_PERSISTENCE_MS 5000 ///< How many ms buffer overflows must persist before fault +#define COMM_BUFFER_LENGTH 768 ///< Max bytes in each comm buffer (each side of double buffer is this size) +#define DOUBLE_BUFFERS 2 ///< Need 2 buffers for double buffering +#define BUFFER_OVERFLOW_PERSISTENCE_MS 5000 ///< How many ms buffer overflows must persist before fault // ********** private data ********** -static volatile U32 commBufferByteCount[ NUM_OF_COMM_BUFFERS ][ DOUBLE_BUFFERS ]; ///< For each buffer, how many bytes does it contain? (also index to next available) -static volatile U32 activeDoubleBuffer[ NUM_OF_COMM_BUFFERS ]; ///< For each buffer, which double buffer is being fed right now? -static U08 commBuffers[ NUM_OF_COMM_BUFFERS ][ DOUBLE_BUFFERS ][ COMM_BUFFER_LENGTH ]; ///< Each is double buffered to avoid thread contention -static U32 firstBufferOverflowTimeStamp = 0; ///< Time stamp of a prior overflow event - allows for an overflow persistence check +static volatile U32 commBufferByteCount[ NUM_OF_COMM_BUFFERS ][ DOUBLE_BUFFERS ]; ///< For each buffer, how many bytes does it contain? (also index to next available) +static volatile U32 activeDoubleBuffer[ NUM_OF_COMM_BUFFERS ]; ///< For each buffer, which double buffer is being fed right now? +static U08 commBuffers[ NUM_OF_COMM_BUFFERS ][ DOUBLE_BUFFERS ][ COMM_BUFFER_LENGTH ]; ///< Each is double buffered to avoid thread contention +static U32 firstBufferOverflowTimeStamp = 0; ///< Time stamp of a prior overflow event - allows for an overflow persistence check // ********** private function prototypes ********** @@ -48,9 +47,9 @@ /*********************************************************************//** * @brief - * The initCommBuffers function initializes the CommBuffers module. + * The initCommBuffers function initializes the CommBuffers unit. * @details Inputs: none - * @details Outputs: CommBuffers module initialized. + * @details Outputs: CommBuffers unit initialized. * @return none *************************************************************************/ void initCommBuffers( void ) @@ -67,11 +66,11 @@ /*********************************************************************//** * @brief * The clearBuffer function clears (empties) a given buffer. - * Caller should ensure buffer won't be used while this function is clearing - * the buffer. + * @note This function is thread safe. IRQ interrupts are disabled while + * buffers are being cleared. * @details Inputs: none * @details Outputs: given buffer is cleared. - * @param buffer the buffer to clear + * @param buffer ID of the buffer to clear * @return none *************************************************************************/ void clearBuffer( COMM_BUFFER_T buffer ) @@ -97,16 +96,18 @@ /*********************************************************************//** * @brief - * The addToCommBuffer function adds data of specified length to a specified - * communication buffer. S/W fault if buffer too full to add data. - * This function will always add to the active double buffer. - * This function should only be called from the background, general, or - * priority tasks (BG or IRQ) for thread safety. + * The addToCommBuffer function adds data of specified length to a given + * communication buffer. + * @note This function will add to the active side of the double buffer. + * @note This function is thread safe. IRQ interrupts are disabled during + * buffer operations. + * @details Alarm: ALARM_ID_TD_SOFTWARE_FAULT if given buffer is invalid or + * it is full. * @details Inputs: commBufferByteCount[], activeDoubleBuffer[] * @details Outputs: commBuffers[], commBufferByteCount[] - * @param buffer which comm buffer to add data to - * @param data pointer to byte array containing data to add - * @param len length of data (in bytes) + * @param buffer ID of buffer to add data to + * @param data Pointer to byte array containing data to add to buffer + * @param len Length of data (in bytes) * @return TRUE if data added to buffer successfully, FALSE if not *************************************************************************/ BOOL addToCommBuffer( COMM_BUFFER_T buffer, U08* data, U32 len ) @@ -186,19 +187,20 @@ /*********************************************************************//** * @brief - * The getFromCommBuffer function fills a given byte array with a given + * The getFromCommBuffer function fills a given byte array with a specified * number of bytes from a given buffer and returns the number of bytes - * retrieved from the buffer. This function will draw from the inactive - * double buffer first and, if needed, switch double buffers to draw the - * rest of the requested data. - * Only one function in one thread should be calling this function for a given - * buffer. + * retrieved from the buffer. + * @note This function will draw from the inactive side of the double buffer + * and, if needed, switch double buffers to draw the rest of the requested data. + * @note This function is thread safe. IRQ interrupts are disabled during buffer + * operations. + * @details Alarm: ALARM_ID_TD_SOFTWARE_FAULT if given buffer is invalid. * @details Inputs: commBuffers[], commBufferByteCount[], activeDoubleBuffer[] * @details Outputs: commBuffers[], commBufferByteCount[], activeDoubleBuffer[], * and the given data array is populated with data from the buffer. - * @param buffer which comm buffer to retrieve data from - * @param data pointer to byte array to stuff data into - * @param len number of bytes to retrieve into given data array. + * @param buffer ID of buffer to retrieve data from + * @param data Pointer to byte array to populate with buffer data + * @param len Number of bytes to retrieve from buffer into given byte array. * @return the number of bytes retrieved. *************************************************************************/ U32 getFromCommBuffer( COMM_BUFFER_T buffer, U08* data, U32 len ) @@ -247,16 +249,17 @@ /*********************************************************************//** * @brief * The peekFromCommBuffer function fills a given byte array with a given - * number of bytes from a given buffer. This function does NOT consume - * the bytes - it only peeks at them. A call to numberOfBytesInCommBuffer() - * should be made before calling this function to determine how many bytes - * are currently in the buffer. Do not call this function with a "len" - * longer than what is currently in the buffer. + * number of bytes from a given buffer. + * @note This function does NOT consume the bytes - it only peeks at them. + * A call to numberOfBytesInCommBuffer() should be made prior to calling + * this function to determine how many bytes are currently in the buffer. + * @warning Do not call this function with a "len" greater than the number + * of bytes currently in the buffer. * @details Inputs: commBuffers[], commBufferByteCount[], activeDoubleBuffer[] * @details Outputs: given array populated with requested number of bytes from the buffer. - * @param buffer which comm buffer to retrieve data from - * @param data pointer to byte array to stuff data into - * @param len number of bytes to retrieve into given data array. + * @param buffer ID of buffer to retrieve data from + * @param data Pointer to byte array to populate with buffer data + * @param len Number of bytes to retrieve from the given buffer. * @return the number of bytes retrieved. *************************************************************************/ U32 peekFromCommBuffer( COMM_BUFFER_T buffer, U08 *data, U32 len ) @@ -304,12 +307,13 @@ /*********************************************************************//** * @brief * The numberOfBytesInCommBuffer function determines how many bytes - * are currently contained in a given comm buffer. Both double buffers - * are considered for this. + * are currently contained in a given comm buffer. Both sides of the + * double buffers are considered for this. + * @details Alarm: ALARM_ID_TD_SOFTWARE_FAULT if given buffer is invalid. * @details Inputs: activeDoubleBuffer[], commBufferByteCount[] * @details Outputs: none - * @param buffer which comm buffer to get byte count for - * @return the number of bytes in the given comm buffer. + * @param buffer ID of buffer to get byte count for + * @return the number of bytes currently in the given comm buffer. *************************************************************************/ U32 numberOfBytesInCommBuffer( COMM_BUFFER_T buffer ) { @@ -333,14 +337,15 @@ /*********************************************************************//** * @brief - * The switchDoubleBuffer function switches the active and inactive buffers - * for the given buffer. - * This function should only be called when the current inactive buffer has - * been emptied. Any unconsumed data in inactive buffer will be lost. + * The switchDoubleBuffer function switches the active and inactive sides + * of the given buffer. + * @warning This function should only be called when the current inactive + * buffer has been emptied. Any unconsumed data in inactive buffer will be + * lost. * @details Inputs: activeDoubleBuffer[] * @details Outputs: activeDoubleBuffer[], commBufferByteCount[] - * @param buffer which comm buffer to switch double buffers on - * @return the new active buffer for the given buffer. + * @param buffer ID of buffer to switch double buffers + * @return the new active side of the given double buffer (0 or 1) *************************************************************************/ static U32 switchDoubleBuffer( COMM_BUFFER_T buffer ) { @@ -359,13 +364,15 @@ /*********************************************************************//** * @brief * The getDataFromInactiveBuffer function retrieves a given number of bytes - * from the inactive buffer of a given buffer. This function should only be - * called by getFromCommBuffer(). Params will be pre-validated there. + * from the inactive side of a given buffer. + * @warning This function should only be called by getFromCommBuffer(). + * Parameters will be pre-validated there. * @details Inputs: commBuffers[], activeDoubleBuffer[], commBufferByteCount[] * @details Outputs: commBuffers[], activeDoubleBuffer[], commBufferByteCount[] - * @param buffer which comm buffer get data from - * @param data pointer to byte array to populate with data - * @param len number of bytes to get from comm buffer + * @param buffer ID of buffer to get data from inactive side of + * @param data Pointer to byte array to populate with data from inactive + * side of buffer + * @param len Number of bytes to get from the buffer * @return none *************************************************************************/ static void getDataFromInactiveBuffer( COMM_BUFFER_T buffer, U08 *data, U32 len )