From 34e42106b4ed9f94fddcdd2e16c847ec81d39538 Mon Sep 17 00:00:00 2001 From: Djordje Nedic Date: Thu, 4 Jan 2024 02:36:30 +0100 Subject: [PATCH 1/2] feat(docs): Add 'How it works' section for BipartiteBuf --- docs/spsc/bipartite_buf.md | 49 +++++++++++++++++++ ...partite_buf_unwrapped_after_invalidate.svg | 21 ++++++++ ...e_buf_unwrapped_after_invalidate_read1.svg | 21 ++++++++ ...e_buf_unwrapped_after_invalidate_read2.svg | 21 ++++++++ ...e_buf_unwrapped_after_invalidate_write.svg | 21 ++++++++ ...ite_buf_unwrapped_after_wrapping_write.svg | 21 ++++++++ docs/spsc/images/ring_buf_has_space.svg | 21 ++++++++ .../images/ring_buf_unwrapped_has_space.svg | 21 ++++++++ 8 files changed, 196 insertions(+) create mode 100644 docs/spsc/images/bipartite_buf_unwrapped_after_invalidate.svg create mode 100644 docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read1.svg create mode 100644 docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read2.svg create mode 100644 docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_write.svg create mode 100644 docs/spsc/images/bipartite_buf_unwrapped_after_wrapping_write.svg create mode 100644 docs/spsc/images/ring_buf_has_space.svg create mode 100644 docs/spsc/images/ring_buf_unwrapped_has_space.svg diff --git a/docs/spsc/bipartite_buf.md b/docs/spsc/bipartite_buf.md index 0ea2f89..a7aa4cf 100644 --- a/docs/spsc/bipartite_buf.md +++ b/docs/spsc/bipartite_buf.md @@ -71,6 +71,55 @@ if (!write_started) { } ``` +## How it works +The Bipartite Buffer uses the same base principle as the [ring buffer data structure](https://en.wikipedia.org/wiki/Circular_buffer), however its ability to provide contiguous space for writing and reading requires modifying the approach slightly. + +Let's consider a typical usage scenario, we want to acquire 4 slots for writing in the following buffer: + +

+ +

+ +We have 7 free slots, so this would work fine for a regular ring buffer. +However when we unroll the buffer we can notice the issue: + +

+ +

+ +We cannot acquire 4 slots from the start of the free space, as there is not enough contiguous space until the end of the buffer, and the only solution is to acquire 4 slots from the beginning. + +After acquiring those slots, we have a gap in available data caused by the skip and we must somehow tell the buffer to avoid reading from that region: + +

+ +

+ +This is where we introduce another index - the **invalidate index** ``i``. +We can set it to the start of the region we want to skip, and next time we are reading the data, we only consider data until the invalidate index. + +

+ +

+ +Now the first time we acquire data for reading, we will get the region from `r` to `i`: + +

+ +

+ +And the next time we will acquire the region from `0` to `w`: + +

+ +

+ +Lastly, when writing, we can write over invalidated parts of the buffer as it doesn't contain anything useful, but also have to move the invalidate index: + +

+ +

+ ## Dealing with caches on embedded systems When using the library with DMA or asymmetric multicore on embedded systems with cache it is necessary to perform manual cache synchronization in one of the following ways: * Using platform specific data synchronization barriers (```DSB``` on ARM) diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate.svg new file mode 100644 index 0000000..7a46854 --- /dev/null +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate.svg @@ -0,0 +1,21 @@ + + + + + + + + rwavailableavailableinvalidi \ No newline at end of file diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read1.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read1.svg new file mode 100644 index 0000000..943007c --- /dev/null +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read1.svg @@ -0,0 +1,21 @@ + + + + + + + + rwfreeavailableinvalidi \ No newline at end of file diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read2.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read2.svg new file mode 100644 index 0000000..c0c1064 --- /dev/null +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read2.svg @@ -0,0 +1,21 @@ + + + + + + + + rwfreeinvalidi \ No newline at end of file diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_write.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_write.svg new file mode 100644 index 0000000..185db57 --- /dev/null +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_write.svg @@ -0,0 +1,21 @@ + + + + + + + + rwfreeinvalidiavailable \ No newline at end of file diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_wrapping_write.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_wrapping_write.svg new file mode 100644 index 0000000..0bf3614 --- /dev/null +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_wrapping_write.svg @@ -0,0 +1,21 @@ + + + + + + + + rwavailableavailablefree \ No newline at end of file diff --git a/docs/spsc/images/ring_buf_has_space.svg b/docs/spsc/images/ring_buf_has_space.svg new file mode 100644 index 0000000..4a14719 --- /dev/null +++ b/docs/spsc/images/ring_buf_has_space.svg @@ -0,0 +1,21 @@ + + + + + + + + 0wr \ No newline at end of file diff --git a/docs/spsc/images/ring_buf_unwrapped_has_space.svg b/docs/spsc/images/ring_buf_unwrapped_has_space.svg new file mode 100644 index 0000000..a82e94a --- /dev/null +++ b/docs/spsc/images/ring_buf_unwrapped_has_space.svg @@ -0,0 +1,21 @@ + + + + + + + + rwavailablefreefree \ No newline at end of file From 61f60ad8aaa72926809dd93a15f42601217a81f1 Mon Sep 17 00:00:00 2001 From: Djordje Nedic Date: Thu, 4 Jan 2024 12:05:48 +0100 Subject: [PATCH 2/2] fix(docs): Embed fonts for 'How it works' Bipartite Buffer section --- .../bipartite_buf_unwrapped_after_invalidate.svg | 10 +--------- .../bipartite_buf_unwrapped_after_invalidate_read1.svg | 10 +--------- .../bipartite_buf_unwrapped_after_invalidate_read2.svg | 10 +--------- .../bipartite_buf_unwrapped_after_invalidate_write.svg | 10 +--------- .../bipartite_buf_unwrapped_after_wrapping_write.svg | 10 +--------- docs/spsc/images/ring_buf_has_space.svg | 10 +--------- docs/spsc/images/ring_buf_unwrapped_has_space.svg | 10 +--------- 7 files changed, 7 insertions(+), 63 deletions(-) diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate.svg index 7a46854..277660e 100644 --- a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate.svg +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate.svg @@ -5,15 +5,7 @@ diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read1.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read1.svg index 943007c..9ba513d 100644 --- a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read1.svg +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read1.svg @@ -5,15 +5,7 @@ diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read2.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read2.svg index c0c1064..8a974d5 100644 --- a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read2.svg +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_read2.svg @@ -5,15 +5,7 @@ diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_write.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_write.svg index 185db57..081a58c 100644 --- a/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_write.svg +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_invalidate_write.svg @@ -5,15 +5,7 @@ diff --git a/docs/spsc/images/bipartite_buf_unwrapped_after_wrapping_write.svg b/docs/spsc/images/bipartite_buf_unwrapped_after_wrapping_write.svg index 0bf3614..cb4852b 100644 --- a/docs/spsc/images/bipartite_buf_unwrapped_after_wrapping_write.svg +++ b/docs/spsc/images/bipartite_buf_unwrapped_after_wrapping_write.svg @@ -5,15 +5,7 @@ diff --git a/docs/spsc/images/ring_buf_has_space.svg b/docs/spsc/images/ring_buf_has_space.svg index 4a14719..d049cbd 100644 --- a/docs/spsc/images/ring_buf_has_space.svg +++ b/docs/spsc/images/ring_buf_has_space.svg @@ -5,15 +5,7 @@ diff --git a/docs/spsc/images/ring_buf_unwrapped_has_space.svg b/docs/spsc/images/ring_buf_unwrapped_has_space.svg index a82e94a..7d9411c 100644 --- a/docs/spsc/images/ring_buf_unwrapped_has_space.svg +++ b/docs/spsc/images/ring_buf_unwrapped_has_space.svg @@ -5,15 +5,7 @@