From ee135b8e28c288a24c60a55ab83b238f7084e290 Mon Sep 17 00:00:00 2001 From: Wang Fang Date: Mon, 10 Aug 2020 18:25:51 +0800 Subject: [PATCH] Add a note to specify that two calls to RingbufferReceive are required in wrap mode --- components/esp_ringbuf/include/freertos/ringbuf.h | 2 ++ docs/en/api-reference/system/freertos_additions.rst | 3 +++ 2 files changed, 5 insertions(+) diff --git a/components/esp_ringbuf/include/freertos/ringbuf.h b/components/esp_ringbuf/include/freertos/ringbuf.h index 1312723ade..ef9c532291 100644 --- a/components/esp_ringbuf/include/freertos/ringbuf.h +++ b/components/esp_ringbuf/include/freertos/ringbuf.h @@ -255,6 +255,7 @@ void *xRingbufferReceive(RingbufHandle_t xRingbuffer, size_t *pxItemSize, TickTy * * @note A call to vRingbufferReturnItemFromISR() is required after this to free the item retrieved. * @note Byte buffers do not allow multiple retrievals before returning an item + * @note Two calls to RingbufferReceiveFromISR() are required if the bytes wrap around the end of the ring buffer. * * @return * - Pointer to the retrieved item on success; *pxItemSize filled with the length of the item. @@ -333,6 +334,7 @@ BaseType_t xRingbufferReceiveSplitFromISR(RingbufHandle_t xRingbuffer, * @note A call to vRingbufferReturnItem() is required after this to free up the data retrieved. * @note This function should only be called on byte buffers * @note Byte buffers do not allow multiple retrievals before returning an item + * @note Two calls to RingbufferReceiveUpTo() are required if the bytes wrap around the end of the ring buffer. * * @return * - Pointer to the retrieved item on success; *pxItemSize filled with diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index 1b0fc4e4bd..6a40a6331f 100644 --- a/docs/en/api-reference/system/freertos_additions.rst +++ b/docs/en/api-reference/system/freertos_additions.rst @@ -210,6 +210,9 @@ using :cpp:func:`xRingbufferReceiveUpTo` and :cpp:func:`vRingbufferReturnItem` For ISR safe versions of the functions used above, call :cpp:func:`xRingbufferSendFromISR`, :cpp:func:`xRingbufferReceiveFromISR`, :cpp:func:`xRingbufferReceiveSplitFromISR`, :cpp:func:`xRingbufferReceiveUpToFromISR`, and :cpp:func:`vRingbufferReturnItemFromISR` +.. note:: + + Two calls to RingbufferReceive[UpTo][FromISR]() are required if the bytes wraps around the end of the ring buffer. Sending to Ring Buffer ^^^^^^^^^^^^^^^^^^^^^^