Index: firmware/App/Services/CommBuffers.c =================================================================== diff -u -r52ded7b22d4b413aa8182f1343e4fbb78e8c3b0a -r090cfb22a7c0b4738299c3fb411ca77aaba8d968 --- firmware/App/Services/CommBuffers.c (.../CommBuffers.c) (revision 52ded7b22d4b413aa8182f1343e4fbb78e8c3b0a) +++ firmware/App/Services/CommBuffers.c (.../CommBuffers.c) (revision 090cfb22a7c0b4738299c3fb411ca77aaba8d968) @@ -48,8 +48,8 @@ /*********************************************************************//** * @brief * The initCommBuffers function initializes the CommBuffers module. - * @details Inputs: none - * @details Outputs: CommBuffers module initialized. + * @details \b Inputs: none + * @details \b Outputs: CommBuffers module initialized. * @return none *************************************************************************/ void initCommBuffers( void ) @@ -65,11 +65,12 @@ /*********************************************************************//** * @brief - * 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 - * @details Outputs: given buffer is cleared - * @param buffer the buffer to clear + * The clearBuffer function clears (empties) a given buffer. + * @details \b Inputs: none + * @details \b Outputs: given buffer is cleared + * @param buffer the buffer to clear + * @warning Caller should ensure buffer won't be used while this function + * is clearing the buffer. * @return none *************************************************************************/ void clearBuffer( COMM_BUFFER_T buffer ) @@ -96,14 +97,16 @@ /*********************************************************************//** * @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. - * @details Inputs: commBufferByteCount[], activeDoubleBuffer[] - * @details Outputs: commBuffers[], commBufferByteCount[] + * communication buffer. This function will always add to the active double buffer. + * @details \b Inputs: commBufferByteCount[], activeDoubleBuffer[] + * @details \b Outputs: commBuffers[], commBufferByteCount[] + * @details \b Alarm: ALARM_ID_DD_SOFTWARE_FAULT when buffer too full to add data and/or + * when invalid buffer given. * @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 len length of data (in bytes) + * @warning This function should only be called + * from the background, general, or priority tasks (BG or IRQ) for thread safety. * @return TRUE if data added to buffer successfully, FALSE if not *************************************************************************/ BOOL addToCommBuffer( COMM_BUFFER_T buffer, U08* data, U32 len ) @@ -187,14 +190,15 @@ * 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[] - * @details Outputs: commBuffers[], commBufferByteCount[], activeDoubleBuffer[], + * if needed, switch double buffers to draw the rest of the requested data. + * @details \b Inputs: commBuffers[], commBufferByteCount[], activeDoubleBuffer[] + * @details \b 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 len number of bytes to retrieve into given data array + * @warning Only one function in one thread should be calling this function for + * a given buffer. * @return the number of bytes retrieved. *************************************************************************/ U32 getFromCommBuffer( COMM_BUFFER_T buffer, U08* data, U32 len ) @@ -247,8 +251,8 @@ * 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[] - * @details Outputs: given array populated with requested number of bytes from the buffer. + * @details \b Inputs: commBuffers[], commBufferByteCount[], activeDoubleBuffer[] + * @details \b 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. @@ -300,8 +304,8 @@ * @brief * 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[] - * @details Outputs: none + * @details \b Inputs: activeDoubleBuffer[], commBufferByteCount[] + * @details \b Outputs: none * @param buffer which comm buffer to get byte count for * @return the number of bytes in the given comm buffer. *************************************************************************/ @@ -330,8 +334,8 @@ * 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[] - * @details Outputs: activeDoubleBuffer[], commBufferByteCount[] + * @details \b Inputs: activeDoubleBuffer[] + * @details \b Outputs: activeDoubleBuffer[], commBufferByteCount[] * @param buffer which comm buffer to switch double buffers on * @return the new active buffer for the given buffer. *************************************************************************/ @@ -354,8 +358,8 @@ * 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[] - * @details Outputs: commBuffers[], activeDoubleBuffer[], commBufferByteCount[] + * @details \b Inputs: commBuffers[], activeDoubleBuffer[], commBufferByteCount[] + * @details \b 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