espressif/arduino-esp32
1
0
Fork 1
mirror of https://github.com/0xFEEDC0DE64/arduino-esp32.git synced 2025-07-06 07:16:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

IDF release/v4.0 08219f3cf

Browse Source
This commit is contained in:
me-no-dev
2020-01-25 14:51:58 +00:00
parent 8c723be135
commit 41ba143063
858 changed files with 37940 additions and 49396 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
tools/sdk/include/esp_ringbuf/freertos/ringbuf.h
View File

@ -1,9 +1,9 @@
// Copyright 2015-2018 Espressif Systems (Shanghai) PTE LTD
// Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
@ -16,7 +16,7 @@
#define FREERTOS_RINGBUF_H
#ifndef INC_FREERTOS_H
#error "include FreeRTOS.h" must appear in source files before "include ringbuf.h"
#error "include FreeRTOS.h" must appear in source files before "include ringbuf.h"
#endif
#ifdef __cplusplus
@ -33,27 +33,52 @@ extern "C" {
typedef void * RingbufHandle_t;
typedef enum {
/**
* No-split buffers will only store an item in contiguous memory and will
* never split an item. Each item requires an 8 byte overhead for a header
* and will always internally occupy a 32-bit aligned size of space.
*/
RINGBUF_TYPE_NOSPLIT = 0,
/**
* Allow-split buffers will split an item into two parts if necessary in
* order to store it. Each item requires an 8 byte overhead for a header,
* splitting incurs an extra header. Each item will always internally occupy
* a 32-bit aligned size of space.
*/
RINGBUF_TYPE_ALLOWSPLIT,
/**
* Byte buffers store data as a sequence of bytes and do not maintain separate
* items, therefore byte buffers have no overhead. All data is stored as a
* sequence of byte and any number of bytes can be sent or retrieved each
* time.
*/
RINGBUF_TYPE_BYTEBUF
} ringbuf_type_t;
/**
* No-split buffers will only store an item in contiguous memory and will
* never split an item. Each item requires an 8 byte overhead for a header
* and will always internally occupy a 32-bit aligned size of space.
*/
RINGBUF_TYPE_NOSPLIT = 0,
/**
* Allow-split buffers will split an item into two parts if necessary in
* order to store it. Each item requires an 8 byte overhead for a header,
* splitting incurs an extra header. Each item will always internally occupy
* a 32-bit aligned size of space.
*/
RINGBUF_TYPE_ALLOWSPLIT,
/**
* Byte buffers store data as a sequence of bytes and do not maintain separate
* items, therefore byte buffers have no overhead. All data is stored as a
* sequence of byte and any number of bytes can be sent or retrieved each
* time.
*/
RINGBUF_TYPE_BYTEBUF,
RINGBUF_TYPE_MAX,
} RingbufferType_t;
/**
* @brief Struct that is equivalent in size to the ring buffer's data structure
*
* The contents of this struct are not meant to be used directly. This
* structure is meant to be used when creating a statically allocated ring
* buffer where this struct is of the exact size required to store a ring
* buffer's control data structure.
*
* @note The CONFIG_FREERTOS_SUPPORT_STATIC_ALLOCATION option must be enabled for
* this structure to be available.
*/
#if ( configSUPPORT_STATIC_ALLOCATION == 1)
typedef struct xSTATIC_RINGBUFFER {
/** @cond */ //Doxygen command to hide this structure from API Reference
size_t xDummy1[2];
UBaseType_t uxDummy2;
BaseType_t xDummy3;
void *pvDummy4[11];
StaticSemaphore_t xDummy5[2];
portMUX_TYPE muxDummy;
/** @endcond */
} StaticRingbuffer_t;
#endif
/**
* @brief Create a ring buffer
@ -66,7 +91,7 @@ typedef enum {
*
* @return A handle to the created ring buffer, or NULL in case of error.
*/
RingbufHandle_t xRingbufferCreate(size_t xBufferSize, ringbuf_type_t xBufferType);
RingbufHandle_t xRingbufferCreate(size_t xBufferSize, RingbufferType_t xBufferType);
/**
* @brief Create a ring buffer of type RINGBUF_TYPE_NOSPLIT for a fixed item_size
@ -81,11 +106,36 @@ RingbufHandle_t xRingbufferCreate(size_t xBufferSize, ringbuf_type_t xBufferType
*/
RingbufHandle_t xRingbufferCreateNoSplit(size_t xItemSize, size_t xItemNum);
/**
* @brief Create a ring buffer but manually provide the required memory
*
* @param[in] xBufferSize Size of the buffer in bytes.
* @param[in] xBufferType Type of ring buffer, see documentation
* @param[in] pucRingbufferStorage Pointer to the ring buffer's storage area.
* Storage area must of the same size as specified by xBufferSize
* @param[in] pxStaticRingbuffer Pointed to a struct of type StaticRingbuffer_t
* which will be used to hold the ring buffer's data structure
*
* @note The CONFIG_FREERTOS_SUPPORT_STATIC_ALLOCATION option must be enabled
* for this to be available
*
* @note xBufferSize of no-split/allow-split buffers MUST be 32-bit aligned.
*
* @return A handle to the created ring buffer
*/
#if ( configSUPPORT_STATIC_ALLOCATION == 1)
RingbufHandle_t xRingbufferCreateStatic(size_t xBufferSize,
RingbufferType_t xBufferType,
uint8_t *pucRingbufferStorage,
StaticRingbuffer_t *pxStaticRingbuffer);
#endif
/**
* @brief Insert an item into the ring buffer
*
* Attempt to insert an item into the ring buffer. This function will block until
* enough free space is available or until it timesout.
* enough free space is available or until it times out.
*
* @param[in] xRingbuffer Ring buffer to insert the item into
* @param[in] pvItem Pointer to data to insert. NULL is allowed if xItemSize is 0.
@ -101,7 +151,10 @@ RingbufHandle_t xRingbufferCreateNoSplit(size_t xItemSize, size_t xItemNum);
* - pdTRUE if succeeded
* - pdFALSE on time-out or when the data is larger than the maximum permissible size of the buffer
*/
BaseType_t xRingbufferSend(RingbufHandle_t xRingbuffer, const void *pvItem, size_t xItemSize, TickType_t xTicksToWait);
BaseType_t xRingbufferSend(RingbufHandle_t xRingbuffer,
const void *pvItem,
size_t xItemSize,
TickType_t xTicksToWait);
/**
* @brief Insert an item into the ring buffer in an ISR
@ -123,13 +176,60 @@ BaseType_t xRingbufferSend(RingbufHandle_t xRingbuffer, const void *pvItem, size
* - pdTRUE if succeeded
* - pdFALSE when the ring buffer does not have space.
*/
BaseType_t xRingbufferSendFromISR(RingbufHandle_t xRingbuffer, const void *pvItem, size_t xItemSize, BaseType_t *pxHigherPriorityTaskWoken);
BaseType_t xRingbufferSendFromISR(RingbufHandle_t xRingbuffer,
const void *pvItem,
size_t xItemSize,
BaseType_t *pxHigherPriorityTaskWoken);
/**
* @brief Acquire memory from the ring buffer to be written to by an external
* source and to be sent later.
*
* Attempt to allocate buffer for an item to be sent into the ring buffer. This
* function will block until enough free space is available or until it
* timesout.
*
* The item, as well as the following items ``SendAcquire`` or ``Send`` after it,
* will not be able to be read from the ring buffer until this item is actually
* sent into the ring buffer.
*
* @param[in] xRingbuffer Ring buffer to allocate the memory
* @param[out] ppvItem Double pointer to memory acquired (set to NULL if no memory were retrieved)
* @param[in] xItemSize Size of item to acquire.
* @param[in] xTicksToWait Ticks to wait for room in the ring buffer.
*
* @note Only applicable for no-split ring buffers now, the actual size of
* memory that the item will occupy will be rounded up to the nearest 32-bit
* aligned size. This is done to ensure all items are always stored in 32-bit
* aligned fashion.
*
* @return
* - pdTRUE if succeeded
* - pdFALSE on time-out or when the data is larger than the maximum permissible size of the buffer
*/
BaseType_t xRingbufferSendAcquire(RingbufHandle_t xRingbuffer, void **ppvItem, size_t xItemSize, TickType_t xTicksToWait);
/**
* @brief Actually send an item into the ring buffer allocated before by
* ``xRingbufferSendAcquire``.
*
* @param[in] xRingbuffer Ring buffer to insert the item into
* @param[in] pvItem Pointer to item in allocated memory to insert.
*
* @note Only applicable for no-split ring buffers. Only call for items
* allocated by ``xRingbufferSendAcquire``.
*
* @return
* - pdTRUE if succeeded
* - pdFALSE if fail for some reason.
*/
BaseType_t xRingbufferSendComplete(RingbufHandle_t xRingbuffer, void *pvItem);
/**
* @brief Retrieve an item from the ring buffer
*
* Attempt to retrieve an item from the ring buffer. This function will block
* until an item is available or until it timesout.
* until an item is available or until it times out.
*
* @param[in] xRingbuffer Ring buffer to retrieve the item from
* @param[out] pxItemSize Pointer to a variable to which the size of the retrieved item will be written.
@ -168,7 +268,7 @@ void *xRingbufferReceiveFromISR(RingbufHandle_t xRingbuffer, size_t *pxItemSize)
* Attempt to retrieve a split item from an allow-split ring buffer. If the item
* is not split, only a single item is retried. If the item is split, both parts
* will be retrieved. This function will block until an item is available or
* until it timesout.
* until it times out.
*
* @param[in] xRingbuffer Ring buffer to retrieve the item from
* @param[out] ppvHeadItem Double pointer to first part (set to NULL if no items were retrieved)
@ -184,7 +284,12 @@ void *xRingbufferReceiveFromISR(RingbufHandle_t xRingbuffer, size_t *pxItemSize)
* - pdTRUE if an item (split or unsplit) was retrieved
* - pdFALSE when no item was retrieved
*/
BaseType_t xRingbufferReceiveSplit(RingbufHandle_t xRingbuffer, void **ppvHeadItem, void **ppvTailItem, size_t *pxHeadItemSize, size_t *pxTailItemSize, TickType_t xTicksToWait);
BaseType_t xRingbufferReceiveSplit(RingbufHandle_t xRingbuffer,
void **ppvHeadItem,
void **ppvTailItem,
size_t *pxHeadItemSize,
size_t *pxTailItemSize,
TickType_t xTicksToWait);
/**
* @brief Retrieve a split item from an allow-split ring buffer in an ISR
@ -207,14 +312,18 @@ BaseType_t xRingbufferReceiveSplit(RingbufHandle_t xRingbuffer, void **ppvHeadIt
* - pdTRUE if an item (split or unsplit) was retrieved
* - pdFALSE when no item was retrieved
*/
BaseType_t xRingbufferReceiveSplitFromISR(RingbufHandle_t xRingbuffer, void **ppvHeadItem, void **ppvTailItem, size_t *pxHeadItemSize, size_t *pxTailItemSize);
BaseType_t xRingbufferReceiveSplitFromISR(RingbufHandle_t xRingbuffer,
void **ppvHeadItem,
void **ppvTailItem,
size_t *pxHeadItemSize,
size_t *pxTailItemSize);
/**
* @brief Retrieve bytes from a byte buffer, specifying the maximum amount of bytes to retrieve
*
* Attempt to retrieve data from a byte buffer whilst specifying a maximum number
* of bytes to retrieve. This function will block until there is data available
* for retrieval or until it timesout.
* for retrieval or until it times out.
*
* @param[in] xRingbuffer Ring buffer to retrieve the item from
* @param[out] pxItemSize Pointer to a variable to which the size of the retrieved item will be written.
@ -230,7 +339,10 @@ BaseType_t xRingbufferReceiveSplitFromISR(RingbufHandle_t xRingbuffer, void **pp
* the length of the item.
* - NULL on timeout, *pxItemSize is untouched in that case.
*/
void *xRingbufferReceiveUpTo(RingbufHandle_t xRingbuffer, size_t *pxItemSize, TickType_t xTicksToWait, size_t xMaxSize);
void *xRingbufferReceiveUpTo(RingbufHandle_t xRingbuffer,
size_t *pxItemSize,
TickType_t xTicksToWait,
size_t xMaxSize);
/**
* @brief Retrieve bytes from a byte buffer, specifying the maximum amount of
@ -281,6 +393,10 @@ void vRingbufferReturnItemFromISR(RingbufHandle_t xRingbuffer, void *pvItem, Bas
* @brief Delete a ring buffer
*
* @param[in] xRingbuffer Ring buffer to delete
*
* @note This function will not deallocate any memory if the ring buffer was
* created using xRingbufferCreateStatic(). Deallocation must be done
* manually be the user.
*/
void vRingbufferDelete(RingbufHandle_t xRingbuffer);
@ -292,6 +408,12 @@ void vRingbufferDelete(RingbufHandle_t xRingbuffer);
*
* @param[in] xRingbuffer Ring buffer to query
*
* @note The max item size for a no-split buffer is limited to
* ((buffer_size/2)-header_size). This limit is imposed so that an item
* of max item size can always be sent to the an empty no-split buffer
* regardless of the internal positions of the buffer's read/write/free
* pointers.
*
* @return Maximum size, in bytes, of an item that can be placed in a ring buffer.
*/
size_t xRingbufferGetMaxItemSize(RingbufHandle_t xRingbuffer);
@ -307,6 +429,10 @@ size_t xRingbufferGetMaxItemSize(RingbufHandle_t xRingbuffer);
* the same ring buffer, it is the application's responsibility to
* ensure atomic access to this API and the subsequent Send
*
* @note An empty no-split buffer has a max current free size for an item
* that is limited to ((buffer_size/2)-header_size). See API reference
* for xRingbufferGetMaxItemSize().
*
* @param[in] xRingbuffer Ring buffer to query
*
* @return Current free size, in bytes, available for an entry
@ -371,9 +497,15 @@ BaseType_t xRingbufferRemoveFromQueueSetRead(RingbufHandle_t xRingbuffer, QueueS
* @param[out] uxFree Pointer use to store free pointer position
* @param[out] uxRead Pointer use to store read pointer position
* @param[out] uxWrite Pointer use to store write pointer position
* @param[out] uxAcquire Pointer use to store acquire pointer position
* @param[out] uxItemsWaiting Pointer use to store number of items (bytes for byte buffer) waiting to be retrieved
*/
void vRingbufferGetInfo(RingbufHandle_t xRingbuffer, UBaseType_t *uxFree, UBaseType_t *uxRead, UBaseType_t *uxWrite, UBaseType_t *uxItemsWaiting);
void vRingbufferGetInfo(RingbufHandle_t xRingbuffer,
UBaseType_t *uxFree,
UBaseType_t *uxRead,
UBaseType_t *uxWrite,
UBaseType_t *uxAcquire,
UBaseType_t *uxItemsWaiting);
/**
* @brief Debugging function to print the internal pointers in the ring buffer
@ -382,31 +514,6 @@ void vRingbufferGetInfo(RingbufHandle_t xRingbuffer, UBaseType_t *uxFree, UBaseT
*/
void xRingbufferPrintInfo(RingbufHandle_t xRingbuffer);
/* -------------------------------- Deprecated Functions --------------------------- */
/** @cond */ //Doxygen command to hide deprecated function from API Reference
/*
* Deprecated as function is not thread safe and does not check if an item is
* actually available for retrieval. Use xRingbufferReceiveSplit() instead for
* thread safe method of retrieve a split item.
*/
bool xRingbufferIsNextItemWrapped(RingbufHandle_t xRingbuffer) __attribute__((deprecated));
/*
* Deprecated as queue sets are not meant to be used for writing to buffers. Adding
* the ring buffer write semaphore to a queue set will break queue set usage rules,
* as every read of a semaphore must be preceded by a call to xQueueSelectFromSet().
* QueueSetWrite no longer supported.
*/
BaseType_t xRingbufferAddToQueueSetWrite(RingbufHandle_t xRingbuffer, QueueSetHandle_t xQueueSet) __attribute__((deprecated));
/*
* Deprecated as queue sets are not meant to be used for writing to buffers.
* QueueSetWrite no longer supported.
*/
BaseType_t xRingbufferRemoveFromQueueSetWrite(RingbufHandle_t xRingbuffer, QueueSetHandle_t xQueueSet) __attribute__((deprecated));
/** @endcond */
#ifdef __cplusplus
}
#endif