Espressif ESP32-S2 Programming Manual page 971

Chapter 2. API Reference
No-Split buffers will only store an item in continuous free space and will not split an item under any circum-
stances. When the free space at the tail of the buffer is insufficient to completely store the item and its header, the
free space at the tail will be marked as dummy data. The buffer will then wrap around and store the item in the
free space at the head of the buffer.
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to store the 28 byte
item. Therefore, the 16 bytes is marked as dummy data and the item is written to the free space at the head of the
buffer instead.
Fig. 34: Wrap around in Allow-Split buffers
Allow-Split buffers will attempt to split the item into two parts when the free space at the tail of the buffer is
insufficient to store the item data and its header. Both parts of the split item will have their own headers (therefore
incurring an extra 8 bytes of overhead).
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to store the 28 byte
item. Therefore, the item is split into two parts (8 and 20 bytes) and written as two parts to the buffer.
Note: Allow-Split buffers treat both parts of the split item as two separate items, therefore call xRingbuffer-
ReceiveSplit() instead of xRingbufferReceive() to receive both parts of a split item in a thread safe
manner.
Fig. 35: Wrap around in byte buffers
Byte buffers will store as much data as possible into the free space at the tail of buffer. The remaining data will
then be stored in the free space at the head of the buffer. No overhead is incurred when wrapping around in byte
buffers.
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to completely store
the 28 bytes of data. Therefore, the 16 bytes of free space is filled with data, and the remaining 12 bytes are written
to the free space at the head of the buffer. The buffer now contains data in two separate continuous parts, and each
continuous part will be treated as a separate item by the byte buffer.
Retrieving/Returning The following diagrams illustrate the differences between No-Split and Allow-Split buffers
as compared to byte buffers in retrieving and returning data.
Items in No-Split buffers and Allow-Split buffers are retrieved in strict FIFO order and must be returned for the
occupied space to be freed. Multiple items can be retrieved before returning, and the items do not necessarily need
to be returned in the order they were retrieved. However, the freeing of space must occur in FIFO order, therefore
not returning the earliest retrieved item will prevent the space of subsequent items from being freed.
Espressif Systems 960 Release v4.4
Submit Document Feedback