From 071c7fd345aa3da91390a5483bbbf5ad38c8ea38 Mon Sep 17 00:00:00 2001 From: Matias Elo Date: Wed, 23 Aug 2023 13:56:57 +0300 Subject: [PATCH] linux-gen: ring: improve documentation Improve ring documentation by adding additional example figures of ring operation. Signed-off-by: Matias Elo Reviewed-by: Petri Savolainen --- .../include/odp_ring_mpmc_internal.h | 31 +++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/platform/linux-generic/include/odp_ring_mpmc_internal.h b/platform/linux-generic/include/odp_ring_mpmc_internal.h index c03a8e9a0d..3526b3866c 100644 --- a/platform/linux-generic/include/odp_ring_mpmc_internal.h +++ b/platform/linux-generic/include/odp_ring_mpmc_internal.h @@ -22,20 +22,47 @@ extern "C" { #include -/* Ring of uint32_t data +/* Ring of uint32_t/uint64_t data * * Ring stores head and tail counters. Ring indexes are formed from these * counters with a mask (mask = ring_size - 1), which requires that ring size * must be a power of two. * + * The following figures depict an example where a ring is being simultaneously + * enqueued to and dequeued from. Ring slots containing data are marked with + * letter D, empty slots with E, and slots being modified with X. + * + * Ring status before enq/deq operations. + * * 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 * +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ - * | E | E | | | | | | | | | | E | E | E | E | E | + * | E | E | D | D | D | D | D | D | E | E | E | E | E | E | E | E | + * +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ + * ^ ^ + * | | + * r_head w_head + * r_tail w_tail + * + * Ring status while being enqueued and dequeued. + * + * 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 + * +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ + * | E | E | X | X | D | D | D | D | X | X | X | E | E | E | E | E | * +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ * ^ ^ ^ ^ * | | | | * r_tail r_head w_tail w_head * + * Ring status after enq/deq operations. + * + * 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 + * +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ + * | E | E | E | E | D | D | D | D | D | D | D | E | E | E | E | E | + * +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ + * ^ ^ + * | | + * r_head w_head + * r_tail w_tail */ struct ring_mpmc_common {