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()));
}