mirror of
https://github.com/0xFEEDC0DE64/arduino-esp32.git
synced 2025-07-12 18:26:30 +02:00
Update IDF to 1c3dd23
* Update mDNS and LEDC * update toolchain * Update IDF to 1c3dd23 * Advertise the board variant for Arduino OTA * Add generic variant definition for mDNS
This commit is contained in:
Me No Dev
GitHub
@ -9,50 +9,58 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/*
|
||||
Header definitions for a FreeRTOS ringbuffer object
|
||||
|
||||
A ringbuffer instantiated by these functions essentially acts like a FreeRTOS queue, with the
|
||||
difference that it's strictly FIFO and with the main advantage that you can put in randomly-sized
|
||||
items. The capacity, accordingly, isn't measured in the amount of items, but the amount of memory
|
||||
that is used for storing the items. Dependent on the size of the items, more or less of them will
|
||||
fit in the ring buffer.
|
||||
|
||||
This ringbuffer tries to be efficient with memory: when inserting an item, the item data will
|
||||
be copied to the ringbuffer memory. When retrieving an item, however, a reference to ringbuffer
|
||||
memory will be returned. The returned memory is guaranteed to be 32-bit aligned and contiguous.
|
||||
The application can use this memory, but as long as it does, ringbuffer writes that would write
|
||||
to this bit of memory will block.
|
||||
|
||||
The requirement for items to be contiguous is slightly problematic when the only way to place
|
||||
the next item would involve a wraparound from the end to the beginning of the ringbuffer. This can
|
||||
be solved (or not) in a few ways:
|
||||
- type = RINGBUF_TYPE_ALLOWSPLIT: The insertion code will split the item in two items; one which fits
|
||||
in the space left at the end of the ringbuffer, one that contains the remaining data which is placed
|
||||
in the beginning. Two xRingbufferReceive calls will be needed to retrieve the data.
|
||||
- type = RINGBUF_TYPE_NOSPLIT: The insertion code will leave the room at the end of the ringbuffer
|
||||
unused and instead will put the entire item at the start of the ringbuffer, as soon as there is
|
||||
enough free space.
|
||||
- type = RINGBUF_TYPE_BYTEBUF: This is your conventional byte-based ringbuffer. It does have no
|
||||
overhead, but it has no item contiguousness either: a read will just give you the entire written
|
||||
buffer space, or the space up to the end of the buffer, and writes can be broken up in any way
|
||||
possible. Note that this type cannot do a 2nd read before returning the memory of the 1st.
|
||||
|
||||
The maximum size of an item will be affected by this decision. When split items are allowed, it's
|
||||
acceptable to push items of (buffer_size)-16 bytes into the buffer. When it's not allowed, the
|
||||
maximum size is (buffer_size/2)-8 bytes. The bytebuf can fill the entire buffer with data, it has
|
||||
no overhead.
|
||||
*/
|
||||
|
||||
#include <freertos/queue.h>
|
||||
|
||||
//An opaque handle for a ringbuff object.
|
||||
typedef void * RingbufHandle_t;
|
||||
|
||||
//The various types of buffer
|
||||
/**
|
||||
* @brief The various types of buffer
|
||||
*
|
||||
* A ringbuffer instantiated by these functions essentially acts like a
|
||||
* FreeRTOS queue, with the difference that it's strictly FIFO and with
|
||||
* the main advantage that you can put in randomly-sized items. The capacity,
|
||||
* accordingly, isn't measured in the amount of items, but the amount of
|
||||
* memory that is used for storing the items. Dependent on the size of
|
||||
* the items, more or less of them will fit in the ring buffer.
|
||||
*
|
||||
* This ringbuffer tries to be efficient with memory: when inserting an item,
|
||||
* the item data will be copied to the ringbuffer memory. When retrieving
|
||||
* an item, however, a reference to ringbuffer memory will be returned.
|
||||
* The returned memory is guaranteed to be 32-bit aligned and contiguous.
|
||||
* The application can use this memory, but as long as it does, ringbuffer
|
||||
* writes that would write to this bit of memory will block.
|
||||
*
|
||||
* The requirement for items to be contiguous is slightly problematic when
|
||||
* the only way to place the next item would involve a wraparound from the end
|
||||
* to the beginning of the ringbuffer. This can be solved (or not) in a few ways,
|
||||
* see descriptions of possible ringbuf_type_t types below.
|
||||
*
|
||||
* The maximum size of an item will be affected by ringbuffer type.
|
||||
* When split items are allowed, it is acceptable to push items of
|
||||
* (buffer_size)-16 bytes into the buffer.
|
||||
* When it's not allowed, the maximum size is (buffer_size/2)-8 bytes.
|
||||
* The bytebuf can fill the entire buffer with data, it has no overhead.
|
||||
*/
|
||||
typedef enum {
|
||||
/** The insertion code will leave the room at the end of the ringbuffer
|
||||
* unused and instead will put the entire item at the start of the ringbuffer,
|
||||
* as soon as there is enough free space.
|
||||
*/
|
||||
RINGBUF_TYPE_NOSPLIT = 0,
|
||||
/** The insertion code will split the item in two items; one which fits
|
||||
* in the space left at the end of the ringbuffer, one that contains
|
||||
* the remaining data which is placed in the beginning.
|
||||
* Two xRingbufferReceive calls will be needed to retrieve the data.
|
||||
*/
|
||||
RINGBUF_TYPE_ALLOWSPLIT,
|
||||
/** This is your conventional byte-based ringbuffer. It does have no
|
||||
* overhead, but it has no item contiguousness either: a read will just
|
||||
* give you the entire written buffer space, or the space up to the end
|
||||
* of the buffer, and writes can be broken up in any way possible.
|
||||
* Note that this type cannot do a 2nd read before returning the memory
|
||||
* of the 1st.
|
||||
*/
|
||||
RINGBUF_TYPE_BYTEBUF
|
||||
} ringbuf_type_t;
|
||||
|
||||
@ -60,22 +68,32 @@ typedef enum {
|
||||
/**
|
||||
* @brief Create a ring buffer
|
||||
*
|
||||
* @param buf_length : Length of circular buffer, in bytes. Each entry will take up its own length, plus a header
|
||||
* that at the moment is equal to sizeof(size_t).
|
||||
* @param allow_split_items : pdTRUE if it is acceptable that item data is inserted as two
|
||||
* items instead of one.
|
||||
* @param buf_length Length of circular buffer, in bytes. Each entry will
|
||||
* take up its own length, plus a header that at the moment
|
||||
* is equal to sizeof(size_t).
|
||||
* @param type Type of ring buffer, see ringbuf_type_t.
|
||||
*
|
||||
* @return A RingbufHandle_t handle to the created ringbuffer, or NULL in case of error.
|
||||
*/
|
||||
RingbufHandle_t xRingbufferCreate(size_t buf_length, ringbuf_type_t type);
|
||||
|
||||
/**
|
||||
* @brief Create a ring buffer of type RINGBUF_TYPE_NOSPLIT for a fixed item_size
|
||||
*
|
||||
* This API is similar to xRingbufferCreate(), but it will internally allocate
|
||||
* additional space for the headers.
|
||||
*
|
||||
* @param item_size Size of each item to be put into the ring buffer
|
||||
* @param num_item Maximum number of items the buffer needs to hold simultaneously
|
||||
*
|
||||
* @return A RingbufHandle_t handle to the created ringbuffer, or NULL in case of error.
|
||||
*/
|
||||
RingbufHandle_t xRingbufferCreateNoSplit(size_t item_size, size_t num_item);
|
||||
|
||||
/**
|
||||
* @brief Delete a ring buffer
|
||||
*
|
||||
* @param ringbuf - Ring buffer to delete
|
||||
*
|
||||
* @return void
|
||||
* @param ringbuf Ring buffer to delete
|
||||
*/
|
||||
void vRingbufferDelete(RingbufHandle_t ringbuf);
|
||||
|
||||
@ -83,23 +101,57 @@ void vRingbufferDelete(RingbufHandle_t ringbuf);
|
||||
/**
|
||||
* @brief Get maximum size of an item that can be placed in the ring buffer
|
||||
*
|
||||
* @param ringbuf - Ring buffer to query
|
||||
* @param ringbuf Ring buffer to query
|
||||
*
|
||||
* @return Maximum size, in bytes, of an item that can be placed in a ring buffer.
|
||||
*/
|
||||
size_t xRingbufferGetMaxItemSize(RingbufHandle_t ringbuf);
|
||||
|
||||
/**
|
||||
* @brief Get current free size available in the buffer
|
||||
*
|
||||
* This gives the real time free space available in the ring buffer. So basically,
|
||||
* this will be the maximum size of the entry that can be sent into the buffer.
|
||||
*
|
||||
* @note This API is not thread safe. So, if multiple threads are accessing the same
|
||||
* ring buffer, it is the application's responsibility to ensure atomic access to this
|
||||
* API and the subsequent Send
|
||||
*
|
||||
* @param ringbuf - Ring buffer to query
|
||||
*
|
||||
* @return Current free size, in bytes, available for an entry
|
||||
*/
|
||||
size_t xRingbufferGetCurFreeSize(RingbufHandle_t ringbuf);
|
||||
|
||||
/**
|
||||
* @brief Check if the next item is wrapped
|
||||
*
|
||||
* This API tells if the next item that is available for a Receive is wrapped
|
||||
* or not. This is valid only if the ring buffer type is RINGBUF_TYPE_ALLOWSPLIT
|
||||
*
|
||||
* @note This API is not thread safe. So, if multiple threads are accessing the same
|
||||
* ring buffer, it is the application's responsibility to ensure atomic access to this
|
||||
* API and the subsequent Receive
|
||||
*
|
||||
* @param ringbuf - Ring buffer to query
|
||||
*
|
||||
* @return true if the next item is wrapped around
|
||||
* @return false if the next item is not wrapped
|
||||
*/
|
||||
bool xRingbufferIsNextItemWrapped(RingbufHandle_t ringbuf);
|
||||
|
||||
/**
|
||||
* @brief Insert an item into the ring buffer
|
||||
*
|
||||
* @param ringbuf - Ring buffer to insert the item into
|
||||
* @param data - Pointer to data to insert. NULL is allowed if data_size is 0.
|
||||
* @param data_size - Size of data to insert. A value of 0 is allowed.
|
||||
* @param xTicksToWait - Ticks to wait for room in the ringbuffer.
|
||||
* @param ringbuf Ring buffer to insert the item into
|
||||
* @param data Pointer to data to insert. NULL is allowed if data_size is 0.
|
||||
* @param data_size Size of data to insert. A value of 0 is allowed.
|
||||
* @param ticks_to_wait Ticks to wait for room in the ringbuffer.
|
||||
*
|
||||
* @return pdTRUE if succeeded, pdFALSE on time-out or when the buffer is larger
|
||||
* than indicated by xRingbufferGetMaxItemSize(ringbuf).
|
||||
* @return
|
||||
* - pdTRUE if succeeded
|
||||
* - pdFALSE on time-out or when the buffer is larger than indicated
|
||||
* by xRingbufferGetMaxItemSize(ringbuf).
|
||||
*/
|
||||
BaseType_t xRingbufferSend(RingbufHandle_t ringbuf, void *data, size_t data_size, TickType_t ticks_to_wait);
|
||||
|
||||
@ -107,11 +159,11 @@ BaseType_t xRingbufferSend(RingbufHandle_t ringbuf, void *data, size_t data_size
|
||||
/**
|
||||
* @brief Insert an item into the ring buffer from an ISR
|
||||
*
|
||||
* @param ringbuf - Ring buffer to insert the item into
|
||||
* @param data - Pointer to data to insert. NULL is allowed if data_size is 0.
|
||||
* @param data_size - Size of data to insert. A value of 0 is allowed.
|
||||
* @param higher_prio_task_awoken - Value pointed to will be set to pdTRUE if the push woke up a higher
|
||||
* priority task.
|
||||
* @param ringbuf Ring buffer to insert the item into
|
||||
* @param data Pointer to data to insert. NULL is allowed if data_size is 0.
|
||||
* @param data_size Size of data to insert. A value of 0 is allowed.
|
||||
* @param[out] higher_prio_task_awoken Value pointed to will be set to pdTRUE
|
||||
* if the push woke up a higher priority task.
|
||||
*
|
||||
* @return pdTRUE if succeeded, pdFALSE when the ring buffer does not have space.
|
||||
*/
|
||||
@ -120,14 +172,18 @@ BaseType_t xRingbufferSendFromISR(RingbufHandle_t ringbuf, void *data, size_t da
|
||||
/**
|
||||
* @brief Retrieve an item from the ring buffer
|
||||
*
|
||||
* @note A call to vRingbufferReturnItem() is required after this to free up the data received.
|
||||
* @note A call to vRingbufferReturnItem() is required after this to free up
|
||||
* the data received.
|
||||
*
|
||||
* @param ringbuf - Ring buffer to retrieve the item from
|
||||
* @param item_size - Pointer to a variable to which the size of the retrieved item will be written.
|
||||
* @param xTicksToWait - Ticks to wait for items in the ringbuffer.
|
||||
* @param ringbuf Ring buffer to retrieve the item from
|
||||
* @param[out] item_size Pointer to a variable to which the size of the
|
||||
* retrieved item will be written.
|
||||
* @param ticks_to_wait Ticks to wait for items in the ringbuffer.
|
||||
*
|
||||
* @return Pointer to the retrieved item on success; *item_size filled with the length of the
|
||||
* item. NULL on timeout, *item_size is untouched in that case.
|
||||
* @return
|
||||
* - pointer to the retrieved item on success; *item_size filled with
|
||||
* the length of the item.
|
||||
* - NULL on timeout, *item_size is untouched in that case.
|
||||
*/
|
||||
void *xRingbufferReceive(RingbufHandle_t ringbuf, size_t *item_size, TickType_t ticks_to_wait);
|
||||
|
||||
@ -135,44 +191,58 @@ void *xRingbufferReceive(RingbufHandle_t ringbuf, size_t *item_size, TickType_t
|
||||
/**
|
||||
* @brief Retrieve an item from the ring buffer from an ISR
|
||||
*
|
||||
* @note A call to vRingbufferReturnItemFromISR() is required after this to free up the data received
|
||||
* @note A call to vRingbufferReturnItemFromISR() is required after this to
|
||||
* free up the data received
|
||||
*
|
||||
* @param ringbuf - Ring buffer to retrieve the item from
|
||||
* @param item_size - Pointer to a variable to which the size of the retrieved item will be written.
|
||||
* @param ringbuf Ring buffer to retrieve the item from
|
||||
* @param[out] item_size Pointer to a variable to which the size of the
|
||||
* retrieved item will be written.
|
||||
*
|
||||
* @return Pointer to the retrieved item on success; *item_size filled with the length of the
|
||||
* item. NULL when the ringbuffer is empty, *item_size is untouched in that case.
|
||||
* @return
|
||||
* - Pointer to the retrieved item on success; *item_size filled with
|
||||
* the length of the item.
|
||||
* - NULL when the ringbuffer is empty, *item_size is untouched in that case.
|
||||
*/
|
||||
void *xRingbufferReceiveFromISR(RingbufHandle_t ringbuf, size_t *item_size);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Retrieve bytes from a ByteBuf type of ring buffer, specifying the maximum amount of bytes
|
||||
* to return
|
||||
|
||||
* @note A call to vRingbufferReturnItem() is required after this to free up the data received.
|
||||
* @brief Retrieve bytes from a ByteBuf type of ring buffer,
|
||||
* specifying the maximum amount of bytes to return
|
||||
*
|
||||
* @param ringbuf - Ring buffer to retrieve the item from
|
||||
* @param item_size - Pointer to a variable to which the size of the retrieved item will be written.
|
||||
* @param xTicksToWait - Ticks to wait for items in the ringbuffer.
|
||||
* @note A call to vRingbufferReturnItem() is required after this to free up
|
||||
* the data received.
|
||||
*
|
||||
* @return Pointer to the retrieved item on success; *item_size filled with the length of the
|
||||
* item. NULL on timeout, *item_size is untouched in that case.
|
||||
* @param ringbuf Ring buffer to retrieve the item from
|
||||
* @param[out] item_size Pointer to a variable to which the size
|
||||
* of the retrieved item will be written.
|
||||
* @param ticks_to_wait Ticks to wait for items in the ringbuffer.
|
||||
* @param wanted_size Maximum number of bytes to return.
|
||||
*
|
||||
* @return
|
||||
* - Pointer to the retrieved item on success; *item_size filled with
|
||||
* the length of the item.
|
||||
* - NULL on timeout, *item_size is untouched in that case.
|
||||
*/
|
||||
void *xRingbufferReceiveUpTo(RingbufHandle_t ringbuf, size_t *item_size, TickType_t ticks_to_wait, size_t wanted_size);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Retrieve bytes from a ByteBuf type of ring buffer, specifying the maximum amount of bytes
|
||||
* to return. Call this from an ISR.
|
||||
* @brief Retrieve bytes from a ByteBuf type of ring buffer,
|
||||
* specifying the maximum amount of bytes to return. Call this from an ISR.
|
||||
*
|
||||
* @note A call to vRingbufferReturnItemFromISR() is required after this to free up the data received
|
||||
* @note A call to vRingbufferReturnItemFromISR() is required after this
|
||||
* to free up the data received.
|
||||
*
|
||||
* @param ringbuf - Ring buffer to retrieve the item from
|
||||
* @param item_size - Pointer to a variable to which the size of the retrieved item will be written.
|
||||
* @param ringbuf Ring buffer to retrieve the item from
|
||||
* @param[out] item_size Pointer to a variable to which the size of the
|
||||
* retrieved item will be written.
|
||||
* @param wanted_size Maximum number of bytes to return.
|
||||
*
|
||||
* @return Pointer to the retrieved item on success; *item_size filled with the length of the
|
||||
* item. NULL when the ringbuffer is empty, *item_size is untouched in that case.
|
||||
* @return
|
||||
* - Pointer to the retrieved item on success; *item_size filled with
|
||||
* the length of the item.
|
||||
* - NULL when the ringbuffer is empty, *item_size is untouched in that case.
|
||||
*/
|
||||
void *xRingbufferReceiveUpToFromISR(RingbufHandle_t ringbuf, size_t *item_size, size_t wanted_size);
|
||||
|
||||
@ -181,10 +251,8 @@ void *xRingbufferReceiveUpToFromISR(RingbufHandle_t ringbuf, size_t *item_size,
|
||||
/**
|
||||
* @brief Return a previously-retrieved item to the ringbuffer
|
||||
*
|
||||
* @param ringbuf - Ring buffer the item was retrieved from
|
||||
* @param item - Item that was received earlier
|
||||
*
|
||||
* @return void
|
||||
* @param ringbuf Ring buffer the item was retrieved from
|
||||
* @param item Item that was received earlier
|
||||
*/
|
||||
void vRingbufferReturnItem(RingbufHandle_t ringbuf, void *item);
|
||||
|
||||
@ -193,34 +261,37 @@ void vRingbufferReturnItem(RingbufHandle_t ringbuf, void *item);
|
||||
/**
|
||||
* @brief Return a previously-retrieved item to the ringbuffer from an ISR
|
||||
*
|
||||
* @param ringbuf - Ring buffer the item was retrieved from
|
||||
* @param item - Item that was received earlier
|
||||
* @param higher_prio_task_awoken - Value pointed to will be set to pdTRUE if the push woke up a higher
|
||||
* priority task.
|
||||
*
|
||||
* @return void
|
||||
* @param ringbuf Ring buffer the item was retrieved from
|
||||
* @param item Item that was received earlier
|
||||
* @param[out] higher_prio_task_awoken Value pointed to will be set to pdTRUE
|
||||
* if the push woke up a higher priority task.
|
||||
*/
|
||||
void vRingbufferReturnItemFromISR(RingbufHandle_t ringbuf, void *item, BaseType_t *higher_prio_task_awoken);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Add the ringbuffer to a queue set. This specifically adds the semaphore that indicates
|
||||
* more space has become available in the ringbuffer.
|
||||
* @brief Add the ringbuffer to a queue set.
|
||||
*
|
||||
* @param ringbuf - Ring buffer to add to the queue set
|
||||
* @param xQueueSet - Queue set to add the ringbuffer to
|
||||
* This specifically adds the semaphore that indicates more space
|
||||
* has become available in the ringbuffer.
|
||||
*
|
||||
* @return pdTRUE on success, pdFALSE otherwise
|
||||
* @param ringbuf Ring buffer to add to the queue set
|
||||
* @param xQueueSet Queue set to add the ringbuffer to
|
||||
*
|
||||
* @return
|
||||
* - pdTRUE on success, pdFALSE otherwise
|
||||
*/
|
||||
BaseType_t xRingbufferAddToQueueSetRead(RingbufHandle_t ringbuf, QueueSetHandle_t xQueueSet);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Add the ringbuffer to a queue set. This specifically adds the semaphore that indicates
|
||||
* something has been written into the ringbuffer.
|
||||
* @brief Add the ringbuffer to a queue set.
|
||||
*
|
||||
* @param ringbuf - Ring buffer to add to the queue set
|
||||
* @param xQueueSet - Queue set to add the ringbuffer to
|
||||
* This specifically adds the semaphore that indicates something has been
|
||||
* written into the ringbuffer.
|
||||
*
|
||||
* @param ringbuf Ring buffer to add to the queue set
|
||||
* @param xQueueSet Queue set to add the ringbuffer to
|
||||
*
|
||||
* @return pdTRUE on success, pdFALSE otherwise
|
||||
*/
|
||||
@ -228,11 +299,13 @@ BaseType_t xRingbufferAddToQueueSetWrite(RingbufHandle_t ringbuf, QueueSetHandle
|
||||
|
||||
|
||||
/**
|
||||
* @brief Remove the ringbuffer from a queue set. This specifically removes the semaphore that indicates
|
||||
* more space has become available in the ringbuffer.
|
||||
* @brief Remove the ringbuffer from a queue set.
|
||||
*
|
||||
* @param ringbuf - Ring buffer to remove from the queue set
|
||||
* @param xQueueSet - Queue set to remove the ringbuffer from
|
||||
* This specifically removes the semaphore that indicates more space
|
||||
* has become available in the ringbuffer.
|
||||
*
|
||||
* @param ringbuf Ring buffer to remove from the queue set
|
||||
* @param xQueueSet Queue set to remove the ringbuffer from
|
||||
*
|
||||
* @return pdTRUE on success, pdFALSE otherwise
|
||||
*/
|
||||
@ -240,11 +313,13 @@ BaseType_t xRingbufferRemoveFromQueueSetRead(RingbufHandle_t ringbuf, QueueSetHa
|
||||
|
||||
|
||||
/**
|
||||
* @brief Remove the ringbuffer from a queue set. This specifically removes the semaphore that indicates
|
||||
* something has been written to the ringbuffer.
|
||||
* @brief Remove the ringbuffer from a queue set.
|
||||
*
|
||||
* @param ringbuf - Ring buffer to remove from the queue set
|
||||
* @param xQueueSet - Queue set to remove the ringbuffer from
|
||||
* This specifically removes the semaphore that indicates something
|
||||
* has been written to the ringbuffer.
|
||||
*
|
||||
* @param ringbuf Ring buffer to remove from the queue set
|
||||
* @param xQueueSet Queue set to remove the ringbuffer from
|
||||
*
|
||||
* @return pdTRUE on success, pdFALSE otherwise
|
||||
*/
|
||||
@ -254,9 +329,7 @@ BaseType_t xRingbufferRemoveFromQueueSetWrite(RingbufHandle_t ringbuf, QueueSetH
|
||||
/**
|
||||
* @brief Debugging function to print the internal pointers in the ring buffer
|
||||
*
|
||||
* @param ringbuf - Ring buffer to show
|
||||
*
|
||||
* @return void
|
||||
* @param ringbuf Ring buffer to show
|
||||
*/
|
||||
void xRingbufferPrintInfo(RingbufHandle_t ringbuf);
|
||||
|
||||
|
||||
Reference in New Issue
Block a user