diff options
Diffstat (limited to 'utils/ringbuf.c')
| -rw-r--r-- | utils/ringbuf.c | 712 |
1 files changed, 712 insertions, 0 deletions
diff --git a/utils/ringbuf.c b/utils/ringbuf.c new file mode 100644 index 0000000..f489239 --- /dev/null +++ b/utils/ringbuf.c @@ -0,0 +1,712 @@ +//*****************************************************************************
+//
+// ringbuf.c - Ring buffer management utilities.
+//
+// Copyright (c) 2008-2014 Texas Instruments Incorporated. All rights reserved.
+// Software License Agreement
+//
+// Texas Instruments (TI) is supplying this software for use solely and
+// exclusively on TI's microcontroller products. The software is owned by
+// TI and/or its suppliers, and is protected under applicable copyright
+// laws. You may not combine this software with "viral" open-source
+// software in order to form a larger program.
+//
+// THIS SOFTWARE IS PROVIDED "AS IS" AND WITH ALL FAULTS.
+// NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT
+// NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. TI SHALL NOT, UNDER ANY
+// CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
+// DAMAGES, FOR ANY REASON WHATSOEVER.
+//
+// This is part of revision 2.1.0.12573 of the Tiva Utility Library.
+//
+//*****************************************************************************
+
+#include <stdbool.h>
+#include <stdint.h>
+#include "inc/hw_types.h"
+#include "driverlib/debug.h"
+#include "driverlib/interrupt.h"
+#include "utils/ringbuf.h"
+
+//*****************************************************************************
+//
+//! \addtogroup ringbuf_api
+//! @{
+//
+//*****************************************************************************
+
+//*****************************************************************************
+//
+// Define NULL, if not already defined.
+//
+//*****************************************************************************
+#ifndef NULL
+#define NULL ((void *)0)
+#endif
+
+//*****************************************************************************
+//
+// Change the value of a variable atomically.
+//
+// \param pui32Val points to the index whose value is to be modified.
+// \param ui32Delta is the number of bytes to increment the index by.
+// \param ui32Size is the size of the buffer the index refers to.
+//
+// This function is used to increment a read or write buffer index that may be
+// written in various different contexts. It ensures that the
+// read/modify/write sequence is not interrupted and, hence, guards against
+// corruption of the variable. The new value is adjusted for buffer wrap.
+//
+// \return None.
+//
+//*****************************************************************************
+static void
+UpdateIndexAtomic(volatile uint32_t *pui32Val, uint32_t ui32Delta,
+ uint32_t ui32Size)
+{
+ bool bIntsOff;
+
+ //
+ // Turn interrupts off temporarily.
+ //
+ bIntsOff = IntMasterDisable();
+
+ //
+ // Update the variable value.
+ //
+ *pui32Val += ui32Delta;
+
+ //
+ // Correct for wrap. We use a loop here since we don't want to use a
+ // modulus operation with interrupts off but we don't want to fail in
+ // case ui32Delta is greater than ui32Size (which is extremely unlikely
+ // but...)
+ //
+ while(*pui32Val >= ui32Size)
+ {
+ *pui32Val -= ui32Size;
+ }
+
+ //
+ // Restore the interrupt state
+ //
+ if(!bIntsOff)
+ {
+ IntMasterEnable();
+ }
+}
+
+//*****************************************************************************
+//
+//! Determines whether the ring buffer whose pointers and size are provided
+//! is full or not.
+//!
+//! \param psRingBuf is the ring buffer object to empty.
+//!
+//! This function is used to determine whether or not a given ring buffer is
+//! full. The structure is specifically to ensure that we do not see
+//! warnings from the compiler related to the order of volatile accesses
+//! being undefined.
+//!
+//! \return Returns \b true if the buffer is full or \b false otherwise.
+//
+//*****************************************************************************
+bool
+RingBufFull(tRingBufObject *psRingBuf)
+{
+ uint32_t ui32Write;
+ uint32_t ui32Read;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Copy the Read/Write indices for calculation.
+ //
+ ui32Write = psRingBuf->ui32WriteIndex;
+ ui32Read = psRingBuf->ui32ReadIndex;
+
+ //
+ // Return the full status of the buffer.
+ //
+ return((((ui32Write + 1) % psRingBuf->ui32Size) == ui32Read) ? true :
+ false);
+}
+
+//*****************************************************************************
+//
+//! Determines whether the ring buffer whose pointers and size are provided
+//! is empty or not.
+//!
+//! \param psRingBuf is the ring buffer object to empty.
+//!
+//! This function is used to determine whether or not a given ring buffer is
+//! empty. The structure is specifically to ensure that we do not see
+//! warnings from the compiler related to the order of volatile accesses
+//! being undefined.
+//!
+//! \return Returns \b true if the buffer is empty or \b false otherwise.
+//
+//*****************************************************************************
+bool
+RingBufEmpty(tRingBufObject *psRingBuf)
+{
+ uint32_t ui32Write;
+ uint32_t ui32Read;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Copy the Read/Write indices for calculation.
+ //
+ ui32Write = psRingBuf->ui32WriteIndex;
+ ui32Read = psRingBuf->ui32ReadIndex;
+
+ //
+ // Return the empty status of the buffer.
+ //
+ return((ui32Write == ui32Read) ? true : false);
+}
+
+//*****************************************************************************
+//
+//! Empties the ring buffer.
+//!
+//! \param psRingBuf is the ring buffer object to empty.
+//!
+//! Discards all data from the ring buffer.
+//!
+//! \return None.
+//
+//*****************************************************************************
+void
+RingBufFlush(tRingBufObject *psRingBuf)
+{
+ bool bIntsOff;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Set the Read/Write pointers to be the same. Do this with interrupts
+ // disabled to prevent the possibility of corruption of the read index.
+ //
+ bIntsOff = IntMasterDisable();
+ psRingBuf->ui32ReadIndex = psRingBuf->ui32WriteIndex;
+ if(!bIntsOff)
+ {
+ IntMasterEnable();
+ }
+}
+
+//*****************************************************************************
+//
+//! Returns number of bytes stored in ring buffer.
+//!
+//! \param psRingBuf is the ring buffer object to check.
+//!
+//! This function returns the number of bytes stored in the ring buffer.
+//!
+//! \return Returns the number of bytes stored in the ring buffer.
+//
+//*****************************************************************************
+uint32_t
+RingBufUsed(tRingBufObject *psRingBuf)
+{
+ uint32_t ui32Write;
+ uint32_t ui32Read;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Copy the Read/Write indices for calculation.
+ //
+ ui32Write = psRingBuf->ui32WriteIndex;
+ ui32Read = psRingBuf->ui32ReadIndex;
+
+ //
+ // Return the number of bytes contained in the ring buffer.
+ //
+ return((ui32Write >= ui32Read) ? (ui32Write - ui32Read) :
+ (psRingBuf->ui32Size - (ui32Read - ui32Write)));
+}
+
+//*****************************************************************************
+//
+//! Returns number of bytes available in a ring buffer.
+//!
+//! \param psRingBuf is the ring buffer object to check.
+//!
+//! This function returns the number of bytes available in the ring buffer.
+//!
+//! \return Returns the number of bytes available in the ring buffer.
+//
+//*****************************************************************************
+uint32_t
+RingBufFree(tRingBufObject *psRingBuf)
+{
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Return the number of bytes available in the ring buffer.
+ //
+ return((psRingBuf->ui32Size - 1) - RingBufUsed(psRingBuf));
+}
+
+//*****************************************************************************
+//
+//! Returns number of contiguous bytes of data stored in ring buffer ahead of
+//! the current read pointer.
+//!
+//! \param psRingBuf is the ring buffer object to check.
+//!
+//! This function returns the number of contiguous bytes of data available in
+//! the ring buffer ahead of the current read pointer. This represents the
+//! largest block of data which does not straddle the buffer wrap.
+//!
+//! \return Returns the number of contiguous bytes available.
+//
+//*****************************************************************************
+uint32_t
+RingBufContigUsed(tRingBufObject *psRingBuf)
+{
+ uint32_t ui32Write;
+ uint32_t ui32Read;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Copy the Read/Write indices for calculation.
+ //
+ ui32Write = psRingBuf->ui32WriteIndex;
+ ui32Read = psRingBuf->ui32ReadIndex;
+
+ //
+ // Return the number of contiguous bytes available.
+ //
+ return((ui32Write >= ui32Read) ? (ui32Write - ui32Read) :
+ (psRingBuf->ui32Size - ui32Read));
+}
+
+//*****************************************************************************
+//
+//! Returns number of contiguous free bytes available in a ring buffer.
+//!
+//! \param psRingBuf is the ring buffer object to check.
+//!
+//! This function returns the number of contiguous free bytes ahead of the
+//! current write pointer in the ring buffer.
+//!
+//! \return Returns the number of contiguous bytes available in the ring
+//! buffer.
+//
+//*****************************************************************************
+uint32_t
+RingBufContigFree(tRingBufObject *psRingBuf)
+{
+ uint32_t ui32Write;
+ uint32_t ui32Read;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Copy the Read/Write indices for calculation.
+ //
+ ui32Write = psRingBuf->ui32WriteIndex;
+ ui32Read = psRingBuf->ui32ReadIndex;
+
+ //
+ // Return the number of contiguous bytes available.
+ //
+ if(ui32Read > ui32Write)
+ {
+ //
+ // The read pointer is above the write pointer so the amount of free
+ // space is the difference between the two indices minus 1 to account
+ // for the buffer full condition (write index one behind read index).
+ //
+ return((ui32Read - ui32Write) - 1);
+ }
+ else
+ {
+ //
+ // If the write pointer is above the read pointer, the amount of free
+ // space is the size of the buffer minus the write index. We need to
+ // add a special-case adjustment if the read index is 0 since we need
+ // to leave 1 byte empty to ensure we can tell the difference between
+ // the buffer being full and empty.
+ //
+ return(psRingBuf->ui32Size - ui32Write - ((ui32Read == 0) ? 1 : 0));
+ }
+}
+
+//*****************************************************************************
+//
+//! Return size in bytes of a ring buffer.
+//!
+//! \param psRingBuf is the ring buffer object to check.
+//!
+//! This function returns the size of the ring buffer.
+//!
+//! \return Returns the size in bytes of the ring buffer.
+//
+//*****************************************************************************
+uint32_t
+RingBufSize(tRingBufObject *psRingBuf)
+{
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Return the number of bytes available in the ring buffer.
+ //
+ return(psRingBuf->ui32Size);
+}
+
+//*****************************************************************************
+//
+//! Reads a single byte of data from a ring buffer.
+//!
+//! \param psRingBuf points to the ring buffer to be written to.
+//!
+//! This function reads a single byte of data from a ring buffer.
+//!
+//! \return The byte read from the ring buffer.
+//
+//*****************************************************************************
+uint8_t
+RingBufReadOne(tRingBufObject *psRingBuf)
+{
+ uint8_t ui8Temp;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Verify that space is available in the buffer.
+ //
+ ASSERT(RingBufUsed(psRingBuf) != 0);
+
+ //
+ // Write the data byte.
+ //
+ ui8Temp = psRingBuf->pui8Buf[psRingBuf->ui32ReadIndex];
+
+ //
+ // Increment the read index.
+ //
+ UpdateIndexAtomic(&psRingBuf->ui32ReadIndex, 1, psRingBuf->ui32Size);
+
+ //
+ // Return the character read.
+ //
+ return(ui8Temp);
+}
+
+//*****************************************************************************
+//
+//! Reads data from a ring buffer.
+//!
+//! \param psRingBuf points to the ring buffer to be read from.
+//! \param pui8Data points to where the data should be stored.
+//! \param ui32Length is the number of bytes to be read.
+//!
+//! This function reads a sequence of bytes from a ring buffer.
+//!
+//! \return None.
+//
+//*****************************************************************************
+void
+RingBufRead(tRingBufObject *psRingBuf, uint8_t *pui8Data, uint32_t ui32Length)
+{
+ uint32_t ui32Temp;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+ ASSERT(pui8Data != NULL);
+ ASSERT(ui32Length != 0);
+
+ //
+ // Verify that data is available in the buffer.
+ //
+ ASSERT(ui32Length <= RingBufUsed(psRingBuf));
+
+ //
+ // Read the data from the ring buffer.
+ //
+ for(ui32Temp = 0; ui32Temp < ui32Length; ui32Temp++)
+ {
+ pui8Data[ui32Temp] = RingBufReadOne(psRingBuf);
+ }
+}
+
+//*****************************************************************************
+//
+//! Remove bytes from the ring buffer by advancing the read index.
+//!
+//! \param psRingBuf points to the ring buffer from which bytes are to be
+//! removed.
+//! \param ui32NumBytes is the number of bytes to be removed from the buffer.
+//!
+//! This function advances the ring buffer read index by a given number of
+//! bytes, removing that number of bytes of data from the buffer. If
+//! \e ui32NumBytes is larger than the number of bytes currently in the buffer,
+//! the buffer is emptied.
+//!
+//! \return None.
+//
+//*****************************************************************************
+void
+RingBufAdvanceRead(tRingBufObject *psRingBuf, uint32_t ui32NumBytes)
+{
+ uint32_t ui32Count;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Make sure that we are not being asked to remove more data than is
+ // there to be removed.
+ //
+ ui32Count = RingBufUsed(psRingBuf);
+ ui32Count = (ui32Count < ui32NumBytes) ? ui32Count : ui32NumBytes;
+
+ //
+ // Advance the buffer read index by the required number of bytes.
+ //
+ UpdateIndexAtomic(&psRingBuf->ui32ReadIndex, ui32Count,
+ psRingBuf->ui32Size);
+}
+
+//*****************************************************************************
+//
+//! Add bytes to the ring buffer by advancing the write index.
+//!
+//! \param psRingBuf points to the ring buffer to which bytes have been added.
+//! \param ui32NumBytes is the number of bytes added to the buffer.
+//!
+//! This function should be used by clients who wish to add data to the buffer
+//! directly rather than via calls to RingBufWrite() or RingBufWriteOne(). It
+//! advances the write index by a given number of bytes. If the
+//! \e ui32NumBytes parameter is larger than the amount of free space in the
+//! buffer, the read pointer will be advanced to cater for the addition. Note
+//! that this will result in some of the oldest data in the buffer being
+//! discarded.
+//!
+//! \return None.
+//
+//*****************************************************************************
+void
+RingBufAdvanceWrite(tRingBufObject *psRingBuf,
+ uint32_t ui32NumBytes)
+{
+ uint32_t ui32Count;
+ bool bIntsOff;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Make sure we were not asked to add a silly number of bytes.
+ //
+ ASSERT(ui32NumBytes <= psRingBuf->ui32Size);
+
+ //
+ // Determine how much free space we currently think the buffer has.
+ //
+ ui32Count = RingBufFree(psRingBuf);
+
+ //
+ // Advance the buffer write index by the required number of bytes and
+ // check that we have not run past the read index. Note that we must do
+ // this within a critical section (interrupts disabled) to prevent
+ // race conditions that could corrupt one or other of the indices.
+ //
+ bIntsOff = IntMasterDisable();
+
+ //
+ // Update the write pointer.
+ //
+ psRingBuf->ui32WriteIndex += ui32NumBytes;
+
+ //
+ // Check and correct for wrap.
+ //
+ if(psRingBuf->ui32WriteIndex >= psRingBuf->ui32Size)
+ {
+ psRingBuf->ui32WriteIndex -= psRingBuf->ui32Size;
+ }
+
+ //
+ // Did the client add more bytes than the buffer had free space for?
+ //
+ if(ui32Count < ui32NumBytes)
+ {
+ //
+ // Yes - we need to advance the read pointer to ahead of the write
+ // pointer to discard some of the oldest data.
+ //
+ psRingBuf->ui32ReadIndex = psRingBuf->ui32WriteIndex + 1;
+
+ //
+ // Correct for buffer wrap if necessary.
+ //
+ if(psRingBuf->ui32ReadIndex >= psRingBuf->ui32Size)
+ {
+ psRingBuf->ui32ReadIndex -= psRingBuf->ui32Size;
+ }
+ }
+
+ //
+ // Restore interrupts if we turned them off earlier.
+ //
+ if(!bIntsOff)
+ {
+ IntMasterEnable();
+ }
+}
+
+//*****************************************************************************
+//
+//! Writes a single byte of data to a ring buffer.
+//!
+//! \param psRingBuf points to the ring buffer to be written to.
+//! \param ui8Data is the byte to be written.
+//!
+//! This function writes a single byte of data into a ring buffer.
+//!
+//! \return None.
+//
+//*****************************************************************************
+void
+RingBufWriteOne(tRingBufObject *psRingBuf, uint8_t ui8Data)
+{
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+
+ //
+ // Verify that space is available in the buffer.
+ //
+ ASSERT(RingBufFree(psRingBuf) != 0);
+
+ //
+ // Write the data byte.
+ //
+ psRingBuf->pui8Buf[psRingBuf->ui32WriteIndex] = ui8Data;
+
+ //
+ // Increment the write index.
+ //
+ UpdateIndexAtomic(&psRingBuf->ui32WriteIndex, 1, psRingBuf->ui32Size);
+}
+
+//*****************************************************************************
+//
+//! Writes data to a ring buffer.
+//!
+//! \param psRingBuf points to the ring buffer to be written to.
+//! \param pui8Data points to the data to be written.
+//! \param ui32Length is the number of bytes to be written.
+//!
+//! This function write a sequence of bytes into a ring buffer.
+//!
+//! \return None.
+//
+//*****************************************************************************
+void
+RingBufWrite(tRingBufObject *psRingBuf, uint8_t *pui8Data,
+ uint32_t ui32Length)
+{
+ uint32_t ui32Temp;
+
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+ ASSERT(pui8Data != NULL);
+ ASSERT(ui32Length != 0);
+
+ //
+ // Verify that space is available in the buffer.
+ //
+ ASSERT(ui32Length <= RingBufFree(psRingBuf));
+
+ //
+ // Write the data into the ring buffer.
+ //
+ for(ui32Temp = 0; ui32Temp < ui32Length; ui32Temp++)
+ {
+ RingBufWriteOne(psRingBuf, pui8Data[ui32Temp]);
+ }
+}
+
+//*****************************************************************************
+//
+//! Initialize a ring buffer object.
+//!
+//! \param psRingBuf points to the ring buffer to be initialized.
+//! \param pui8Buf points to the data buffer to be used for the ring buffer.
+//! \param ui32Size is the size of the buffer in bytes.
+//!
+//! This function initializes a ring buffer object, preparing it to store data.
+//!
+//! \return None.
+//
+//*****************************************************************************
+void
+RingBufInit(tRingBufObject *psRingBuf, uint8_t *pui8Buf,
+ uint32_t ui32Size)
+{
+ //
+ // Check the arguments.
+ //
+ ASSERT(psRingBuf != NULL);
+ ASSERT(pui8Buf != NULL);
+ ASSERT(ui32Size != 0);
+
+ //
+ // Initialize the ring buffer object.
+ //
+ psRingBuf->ui32Size = ui32Size;
+ psRingBuf->pui8Buf = pui8Buf;
+ psRingBuf->ui32WriteIndex = psRingBuf->ui32ReadIndex = 0;
+}
+
+//*****************************************************************************
+//
+// Close the Doxygen group.
+//! @}
+//
+//*****************************************************************************
|