A C++ template library for embedded applications
MIT licensed
Designed and
maintained by
John Wellbelove
Support the development
of the ETL
buffer_descriptors

A set of descriptors to a collection of buffers.
STL equivalent: none

template <typename TBuffer,      // The type to store in the buffer.
          TSize    BUFFER_SIZE// The size of each buffer.
          size_t   N_BUFFERS,    // The total number of buffers.
          typename TFlag = bool> // The 'in use' flag type.
class buffer_descriptors

The type used for the 'in use' flag depends on how the buffer descriptors class is used.
For interrupts and multi-threaded code, either the flag  type must force a fence (by using an atomic type) or the calls to
allocate and release must ensure that they are not re-ordered by the compiler or processor.
____________________________________________________________________________________________________
Member types

value_type      TBuffer      The type that is stored in the buffers
size_type       size_t       Must be an unsigned integral type
flag_type       TFlag
pointer         value_type*
descriptor      A nested class that encapsulates the details of an individual buffer.
notification    A nested class that is sent to the user defined callback function.
callback_type   etl::delegate<void(notification)>
____________________________________________________________________________________________________
Static Constants

N_BUFFERS    The number of buffers that the buffer descriptor controls.
BUFFER_SIZE  The number of elements in each buffer.
____________________________________________________________________________________________________
Constructors

buffer_descriptors(pointer pbuffers)
Construct with a pointer to the start of the buffers to control.
This storage should be contiguous and large enough to hold N_BUFFERS.
____________________________________________________________________________________________________
buffer_descriptors(pointer pbuffers, const callback_type& callback)
Construct with a pointer to the start of the buffers to control and the callback.
____________________________________________________________________________________________________
Member functions
void set_callback(const callback_type& callback)
Set the callback for notification.
____________________________________________________________________________________________________
bool is_valid() const
Returns true if class contains valid buffers.
____________________________________________________________________________________________________
void notify(notification n)
Calls the user defined callback with the descriptor and buffer size.
Used when the buffer has been filled and is ready for processing via the callback.
____________________________________________________________________________________________________
descriptor allocate()
Returns a new descriptor.
If all descriptors are in use then the descriptor will be 'invalid'.
____________________________________________________________________________________________________
descriptor allocate(value_type fill)
Returns a new descriptor and fills the buffer with fill.
If all descriptors are in use then the descriptor will be 'invalid'.
____________________________________________________________________________________________________
void clear()
Clears by releasing all allocated descriptors.
____________________________________________________________________________________________________
descriptor
A nested class that encapsulates the details of an individual buffer.

const size_type MAX_SIZE
The maximum size of the buffer.
____________________________________________________________________________________________________
descriptor()
Default constructor.
____________________________________________________________________________________________________
ETL_CONSTEXPR pointer data() const
Returns a pointer to the start of the buffer.
____________________________________________________________________________________________________
ETL_CONSTEXPR size_type max_size() const
Returns the maximum size of the buffer.
____________________________________________________________________________________________________
bool is_valid() const
Returns true if the descriptor points to a valid buffer.
____________________________________________________________________________________________________
bool is_allocated() const
Returns true if the descriptor has been allocated.
____________________________________________________________________________________________________
bool is_released() const
Returns true if the descriptor has been released.
____________________________________________________________________________________________________
void release()
Releases the descriptor.
____________________________________________________________________________________________________
notification
A nested class that is sent to the user defined callback function.

notification()
Default contructor.
Initialises to a default constructed descriptor and a count of zero.
____________________________________________________________________________________________________
notification(descriptor desc, size_t count)
Construct with the supplied parameters.
____________________________________________________________________________________________________
descriptor get_descriptor() const
Gets the descriptor.
____________________________________________________________________________________________________
size_t get_count() const
Gets the count.
____________________________________________________________________________________________________
Example
Very simplified. Assumes that there is a DMA driver class called DMA.
In the real world the descriptor would be queued in the callback and handled in a foreground thread.
The handler in the thread would release the descriptor.

constexpr size_t BUFFER_SIZE = 256U;
constexpr size_t N_BUFFERS   = 8U;

// Define the buffer descriptors type.
using BD = etl::buffer_descriptors<char, BUFFER_SIZE, N_BUFFERS, std::atomic_char>;

// The buffers to use with it.
char buffers[N_BUFFERS][BUFFER_SIZE];
____________________________________________________________________________________________________

// The function to call when a buffer is ready.
void Callback(BD::notification notification)
{
  // Process the buffer in the descriptor here.
  ProcessData(notification.get_descriptor().data(), notification.get_count());

  // Finished with the descriptor now, so release it back.
  notification.get_descriptor().release();
}
____________________________________________________________________________________________________

// Create the buffer_descriptors.
BD bd(&buffers[0][0], BD::callback_type::create<Callback>());

// The current dma descriptor.
BD::descriptor dma_descriptor;

// An object that controls the DMA.
DMA dma;
____________________________________________________________________________________________________

// Call to start the DMA.
void DMAStart()
{
  // Get a new descriptor.
  dma_descriptor = bd.allocate();

  if (dma_descriptor.is_valid())
  {
    // Link the buffer to the DMA channel.
    dma.Start(dma_descriptor.data());
  }
  else
  {
    // No valid descriptors available.
    LogError("No Descriptor Available");
  }
}
____________________________________________________________________________________________________

// Called when the DMA has completed (usually an interrupt).
void DMAComplete()
{
  // DMA is complete. Notify the callback.
  bd.notify(BD::notification(dma_descriptor, dma.GetTransferredSize()));
}

buffer_descriptors.h