Index: firmware/App/Services/CommBuffers.c =================================================================== diff -u -rdc0d9b087c609e71cacdb7f0395cccf29d749c00 -r5e0cd9b5be11ff4b2acaadbdcafc4ffe05172aa1 --- firmware/App/Services/CommBuffers.c (.../CommBuffers.c) (revision dc0d9b087c609e71cacdb7f0395cccf29d749c00) +++ firmware/App/Services/CommBuffers.c (.../CommBuffers.c) (revision 5e0cd9b5be11ff4b2acaadbdcafc4ffe05172aa1) @@ -21,26 +21,31 @@ #include "SystemComm.h" #include "SystemCommMessages.h" #include "Timers.h" + +/** + * @addtogroup CommBuffers + * @{ + */ // ********** private definitions ********** -#define COMM_BUFFER_LENGTH 512 // max bytes in each comm buffer (double if you count double buffers) -#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 512 ///< Comm buffer length in bytes (double if you count double buffers). +#define DOUBLE_BUFFERS 2 ///< Two buffers for double buffering. +#define BUFFER_OVERFLOW_PERSISTENCE_MS 5000 ///< Interval which 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 ]; ///< Comm buffer byte count. +static volatile U32 activeDoubleBuffer[ NUM_OF_COMM_BUFFERS ]; ///< Active buffer that being fed to. +static U08 commBuffers[ NUM_OF_COMM_BUFFERS ][ DOUBLE_BUFFERS ][ COMM_BUFFER_LENGTH ]; ///< Double buffered comm buffer to avoid thread contention. +static U32 firstBufferOverflowTimeStamp = 0; ///< Time stamp of a prior overflow event - allows for an overflow persistence check. // ********** private function prototypes ********** static U32 switchDoubleBuffer( COMM_BUFFER_T buffer ); static void getDataFromInactiveBuffer( COMM_BUFFER_T buffer, U08 *data, U32 len ); -/************************************************************************* +/*********************************************************************//** * @brief * The initCommBuffers function initializes the CommBuffers module. * @details @@ -58,15 +63,14 @@ clearBuffer( (COMM_BUFFER_T)b ); } } - -/************************************************************************* + +/*********************************************************************//** * @brief - * The clearBuffer function clears (empties) a given buffer. \n - * Caller should ensure buffer won't be used while this function is clearing \n - * the buffer. + * The clearBuffer function clears (empties) a given buffer. Caller should + * ensure buffer won't be used while this function is clearing the buffer. * @details * Inputs : none - * Outputs : given buffer is cleared. + * Outputs : given buffer is cleared * @param buffer the buffer to clear * @return none *************************************************************************/ @@ -90,14 +94,13 @@ _enable_IRQ(); } } - -/************************************************************************* + +/*********************************************************************//** * @brief - * The addToCommBuffer function adds data of specified length to a specified \n - * communication buffer. S/W fault if buffer too full to add data. \n - * This function will always add to the active double buffer. \n - * This function should only be called from the background, general, or \n - * priority tasks (BG or IRQ) for thread safety. + * 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. * @details * Inputs : commBufferByteCount[], activeDoubleBuffer[] * Outputs : commBuffers[], commBufferByteCount[] @@ -188,23 +191,21 @@ return result; } - -/************************************************************************* + +/*********************************************************************//** * @brief - * The getFromCommBuffer function fills a given byte array with a given \n - * number of bytes from a given buffer and returns the number of bytes \n - * retrieved from the buffer. This function will draw from the inactive \n - * double buffer first and, if needed, switch double buffers to draw the \n - * rest of the requested data. - * Only one function in one thread should be calling this function for a given \n - * buffer. + * The getFromCommBuffer function fills a given byte array with a given 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. * @details * Inputs : commBuffers[], commBufferByteCount[], activeDoubleBuffer[] - * Outputs : commBuffers[], commBufferByteCount[], activeDoubleBuffer[], \n - * and the given data array is populated with data from the buffer. + * 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 # of bytes to retrieve into given data array. + * @param len number of bytes to retrieve into given data array * @return the number of bytes retrieved. *************************************************************************/ U32 getFromCommBuffer( COMM_BUFFER_T buffer, U08* data, U32 len ) @@ -249,21 +250,20 @@ return result; } - -/************************************************************************* + +/*********************************************************************//** * @brief - * The peekFromCommBuffer function fills a given byte array with a given \n - * number of bytes from a given buffer. This function does NOT consume \n - * the bytes - it only peeks at them. A call to numberOfBytesInCommBuffer() \n - * should be made before calling this function to determine how many bytes \n - * are currently in the buffer. Do not call this function with a "len" \n - * longer than what is currently in the buffer. + * 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. * @details * Inputs : commBuffers[], commBufferByteCount[], activeDoubleBuffer[] * Outputs : given array populated with requested # 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 # of bytes to retrieve into given data array. + * @param len number of bytes to retrieve into given data array. * @return the number of bytes retrieved. *************************************************************************/ U32 peekFromCommBuffer( COMM_BUFFER_T buffer, U08 *data, U32 len ) @@ -307,12 +307,11 @@ return numOfBytesPeeked; } - -/************************************************************************* + +/*********************************************************************//** * @brief - * The numberOfBytesInCommBuffer function determines how many bytes \n - * are currently contained in a given comm buffer. Both double buffers \n - * are considered for this. + * The numberOfBytesInCommBuffer function determines how many bytes are currently + * contained in a given comm buffer. Both double buffers are considered for this. * @details * Inputs : activeDoubleBuffer[], commBufferByteCount[] * Outputs : none @@ -338,13 +337,12 @@ return result; } - -/************************************************************************* + +/*********************************************************************//** * @brief - * The switchDoubleBuffer function switches the active and inactive buffers \n - * for the given buffer. \n - * This function should only be called when the current inactive buffer has \n - * been emptied. Any unconsumed data in inactive buffer will be lost. + * 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. * @details * Inputs : activeDoubleBuffer[] * Outputs : activeDoubleBuffer[], commBufferByteCount[] @@ -364,18 +362,18 @@ // return the new active buffer (was just inactive) return inactiveBuffer; } - -/************************************************************************* + +/*********************************************************************//** * @brief - * The getDataFromInactiveBuffer function retrieves a given number of bytes \n - * from the inactive buffer of a given buffer. This function should only be \n + * 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. * @details * Inputs : commBuffers[], activeDoubleBuffer[], commBufferByteCount[] * Outputs : commBuffers[], activeDoubleBuffer[], commBufferByteCount[] * @param buffer which comm buffer get data from * @param data pointer to byte array to populate with data - * @param len # of bytes to get from comm buffer + * @param len number of bytes to get from comm buffer * @return none *************************************************************************/ static void getDataFromInactiveBuffer( COMM_BUFFER_T buffer, U08 *data, U32 len ) @@ -402,4 +400,5 @@ switchDoubleBuffer( buffer ); // switch will zero count off inactive buffer } } - + +/**@}*/