This fixes multiple bugs with ring buffers and re-factors the code. The public
API has not changed, however the underlying implementation have various private
functions have been changed. The following behavioral changes have been made
- Size of ring buffers for No-Split/Allow-Split buffers will not be rounded
up to the nearest 32-bit aligned size. This was done to simplify the
implementation
- Item size for No-Split/Allow-Split buffers will also be rounded up to the
nearest 32-bit aligned size.
The following bugs have been fixed
- In copyItemToRingbufAllowSplit(), when copying an item where the aligned
size is smaller than the remaining length, the function does not consider
the case where the true size of the item is less than 4 bytes.
- The copy functions will automatically wrap around the write pointers when
the remaining length of the buffer is not large enough to fit a header, but
does not consider if wrapping around will cause an overlap with the read
pointer. This will make a full buffer be mistaken for an empty buffer
closes#1711
- xRingbufferSend() can get stuck in a infinite loop when the size of the
free memory is larger than the needed_size, but too small to fit in the ring
buffer due to alignment and extra overhead of wrapping around.
closes#1846
- Fixed documentation with ring buffer queue set API
- Adding and removing from queue set does not consider the case where the
read/write semaphores actually hold a value.
The following functions have been deprecated
- xRingbufferIsNextItemWrapped() due to lack of thread safety
- xRingbufferAddToQueueSetWrite() and xRingbufferRemoveFromQueueSetWrite()
as adding the queue sets only work under receive operations.
The following functions have been added
- xRingbufferReceiveSplit() and xRingbufferReceiveSplitFromISR() as a thread
safe way to receive from allow-split buffers
- vRingbufferGetInfo()
Documentation for ring buffers has also been added.
Add function xRingbufferCanRead & xRingbufferCanWrite
to be able use queue sets. Without it is not possible
to check to which ringbuffer returned semaphore belongs.
In situations where idle task runs a lot of idle hooks or cleanup code
(due to pthread local storage, etc) it can use more than 1KB of stack.
(I think the trigger is if a context switch happens at the right point
in the TLS cleanup).
Also removes an sdkconfig.default which accidentally set all config items,
including this stack size.
Bugfix to prevent a self deleting no affinity task's memory from being freed by the
idle task of the other core before the self deleting no affinity task is able to context
switch out. prvCheckTasksWaitingTermination now checks if the task is still on
pxCurrentTCB before freeing task memory.
This is a wrapper API for creating a Ring Buffer, which ensures that
the ringbuffer can hold the given number of items, each item being of the
same given length.
Signed-off-by: Piyush Shah <piyush@espressif.com>
Useful to check if the next item to receive is wrapped or not.
This is valid only if the ring buffer is initialised with type
RINGBUF_TYPE_ALLOWSPLIT.
This is as per the feature request here:
https://github.com/espressif/esp-idf/issues/806
Signed-off-by: Piyush Shah <piyush@espressif.com>
The earlier available API (xRingbufferGetMaxItemSize())just gives
a static max entry value possible for given ring buffer.
There was a feature request for an API which could provide
a real time available buffer size. See below:
https://github.com/espressif/esp-idf/issues/806
Signed-off-by: Piyush Shah <piyush@espressif.com>
- Use `code` tags instead of a mix of `<pre></pre>` and
`@verbatim .. @endverbatim`
- Remove manually added function prototypes from comment blocks
- Remove of grouping (`\defgroup`) — some extra work is needed
to make groups compatible with the way we auto-generate API
reference from Doxygen XML files. It's pretty easy to add the
grouping directives back if/when we implement support for
Doxygen groups in the later stages of documentation build
process.
- Hide private APIs under `@cond .. @endcond`
- Convert some comments into Doxygen-compatible ones
- Fix various documentation issues: missing documentation for
some parameters, mismatch between parameter names in comment
block and in function prototype.
- Add doxygen comments for functions which didn't have them
(thread local storage).
- Add [out] param tags where necessary
- Redefine `xTaskCreate` and `xTaskCreateStatic` as inline
functions instead of macros.
This commit backports vTaskDelete() behavior from FreeRTOS v9.0.0 which
allows for the immediate freeing of task memory if the task being deleted
is not currently running and not pinned to the other core. This commit also
fixes a bug in prvCheckTasksWaitingTermination which prevented the
Idle Task from cleaning up all tasks awaiting deletion. Each iteration of the Idle
Task should traverse the xTasksWaitingTermination list and clean up all tasks
not pinned to the other core. The previous implementation would cause
prvCheckTasksWaitingTermination to return when encountering a task
pinned to the other core whilst traversing the xTasksWaitingTermination list.
The test case for vTaskDelete() has been updated to test for the bugfix and
backported deletion behavior.
This commit backports the following features from FreeRTOS v9.0.0
- uxSemaphoreGetCount()
- vTimerSetTimerId(), xTimerGetPeriod(), xTimerGetExpiryTime()
- xTimerCreateStatic()
- xEventGroupCreateStatic()
- uxSemaphoreGetCount()
Functions backported previously
- xTaskCreateStatic()
- xQueueCreateStatic()
- xSemaphoreCreateBinaryStatic(), xSemaphoreCreateCountingStatic()
- xSemaphoreCreateMutexStatic(), xSemaphoreCreateRecursiveMutexStatic()
- pcQueueGetName()
- vTaskSetThreadLocalStoragePointer()
- pvTaskGetThreadLocalStoragePointer()
Unit tests were also written for the functions above (except for pcQueueGetName
which is tested in a separate Queue Registry MR). The original tlsp and del cb test case
was deleted and integrated into the test cases of this MR.
When using CPP and C combination this particular file threw error on linking.
Merges https://github.com/espressif/esp-idf/pull/1249
(Amended to add INC_FREERTOS_H guard, comment on #endif)
1. Usage of this module required applications to include additional
files. What files to include is not very intuitive. Instead, it is
better for the header file itself to include other files as required.
2. Even though it may seem logical, it is better to explicitly mention
that an item needs to be "Returned" after a Receive
Signed-off-by: Piyush Shah <piyush@espressif.com>
It was observed that if the ring buffer size provided by application
is not a multiple of 4, some checks were failing (as read_ptr and write_ptr
could shoot beyond the ring buffer boundary), thereby causing asserts.
Simply wrapping around the pointers for such cases fixes the issue.
Moreover, because of the logic for maintaining 4-byte boundary,
it was also possible that a wrap-around occurred for some data,
even when the actual size remaining was sufficient for it.
Eg. Buffer available: 34, data size: 34, 4-byte aligned size: 36
Since the logic compares against 36, it writes 34 bytes and does a
wraparound. But since all 34 bytes are already written, there is
nothing to write after wrapping. It is better to just re-set the
write pointer to the dtart of ring buffer in such cases.
Tested send/receive for various arbitrary sizes of data and for
arbitrary sizes of ring buffer.
Alternative Solutions:
1) Allow only sizes which are multiples of 4, and return error otherwise.
Appropriate code and documentation change would be required
2) Allow arbitrary sizes, but internally add upto 3 bytes to make
the total size a multiple of 4
Signed-off-by: Piyush Shah <piyush@espressif.com>
