[dpdk-dev] [PATCH 1/2] lib/ring: fix documentation for rte_ring_xxx_elem apis

[dpdk-dev] [PATCH 1/2] lib/ring: fix documentation for rte_ring_xxx_elem apis

[Honnappa Nagarahalli]

Correct the documentation for obj_table in rte_ring_xxx_elem APIs.

Fixes: cc4b218790f6 ("ring: support configurable element size")

Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
Reviewed-by: Gavin Hu <gavin.hu@arm.com>
---
 lib/librte_ring/rte_ring_elem.h | 34 ++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/lib/librte_ring/rte_ring_elem.h b/lib/librte_ring/rte_ring_elem.h
index 15d79bf2a..50ecc9c3d 100644
--- a/lib/librte_ring/rte_ring_elem.h
+++ b/lib/librte_ring/rte_ring_elem.h
@@ -392,7 +392,7 @@ dequeue_elems(struct rte_ring *r, uint32_t cons_head, void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects).
+ *   A pointer to a table of objects.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -439,7 +439,7 @@ __rte_ring_do_enqueue_elem(struct rte_ring *r, const void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects).
+ *   A pointer to a table of objects.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -490,7 +490,7 @@ __rte_ring_do_dequeue_elem(struct rte_ring *r, void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects).
+ *   A pointer to a table of objects.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -519,7 +519,7 @@ rte_ring_mp_enqueue_bulk_elem(struct rte_ring *r, const void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects).
+ *   A pointer to a table of objects.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -550,7 +550,7 @@ rte_ring_sp_enqueue_bulk_elem(struct rte_ring *r, const void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects).
+ *   A pointer to a table of objects.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -655,7 +655,7 @@ rte_ring_enqueue_elem(struct rte_ring *r, void *obj, unsigned int esize)
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects) that will be filled.
+ *   A pointer to a table of objects that will be filled.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -682,7 +682,7 @@ rte_ring_mc_dequeue_bulk_elem(struct rte_ring *r, void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects) that will be filled.
+ *   A pointer to a table of objects that will be filled.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -714,7 +714,7 @@ rte_ring_sc_dequeue_bulk_elem(struct rte_ring *r, void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects) that will be filled.
+ *   A pointer to a table of objects that will be filled.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -744,7 +744,7 @@ rte_ring_dequeue_bulk_elem(struct rte_ring *r, void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_p
- *   A pointer to a void * pointer (object) that will be filled.
+ *   A pointer to the object that will be filled.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -768,7 +768,7 @@ rte_ring_mc_dequeue_elem(struct rte_ring *r, void *obj_p,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_p
- *   A pointer to a void * pointer (object) that will be filled.
+ *   A pointer to the object that will be filled.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -796,7 +796,7 @@ rte_ring_sc_dequeue_elem(struct rte_ring *r, void *obj_p,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_p
- *   A pointer to a void * pointer (object) that will be filled.
+ *   A pointer to the object that will be filled.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -822,7 +822,7 @@ rte_ring_dequeue_elem(struct rte_ring *r, void *obj_p, unsigned int esize)
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects).
+ *   A pointer to a table of objects.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -851,7 +851,7 @@ rte_ring_mp_enqueue_burst_elem(struct rte_ring *r, const void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects).
+ *   A pointer to a table of objects.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -882,7 +882,7 @@ rte_ring_sp_enqueue_burst_elem(struct rte_ring *r, const void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects).
+ *   A pointer to a table of objects.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -914,7 +914,7 @@ rte_ring_enqueue_burst_elem(struct rte_ring *r, const void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects) that will be filled.
+ *   A pointer to a table of objects that will be filled.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -943,7 +943,7 @@ rte_ring_mc_dequeue_burst_elem(struct rte_ring *r, void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects) that will be filled.
+ *   A pointer to a table of objects that will be filled.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
@@ -974,7 +974,7 @@ rte_ring_sc_dequeue_burst_elem(struct rte_ring *r, void *obj_table,
  * @param r
  *   A pointer to the ring structure.
  * @param obj_table
- *   A pointer to a table of void * pointers (objects) that will be filled.
+ *   A pointer to a table of objects that will be filled.
  * @param esize
  *   The size of ring element, in bytes. It must be a multiple of 4.
  *   This must be the same value used while creating the ring. Otherwise
-- 
2.17.1

[dpdk-dev] [PATCH 2/2] doc: change prog guide to reflect rte_ring_xxx_elem apis

[Honnappa Nagarahalli]

Changed the rte_ring chapter in programmer's guide to reflect
the addition of rte_ring_xxx_elem APIs. References to pointers
as ring elements is changed to generic term 'objects'.

Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
Reviewed-by: Gavin Hu <gavin.hu@arm.com>
---
 doc/guides/prog_guide/ring_lib.rst | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/doc/guides/prog_guide/ring_lib.rst b/doc/guides/prog_guide/ring_lib.rst
index 5a9b6137e..8cb2b2dd4 100644
--- a/doc/guides/prog_guide/ring_lib.rst
+++ b/doc/guides/prog_guide/ring_lib.rst
@@ -11,7 +11,9 @@ Instead of having a linked list of infinite size, the rte_ring has the following
 
 *   FIFO
 
-*   Maximum size is fixed, the pointers are stored in a table
+*   Maximum size is fixed, the objects are stored in a table
+
+*   Objects can be pointers or elements of multiple of 4 byte size
 
 *   Lockless implementation
 
@@ -29,19 +31,19 @@ Instead of having a linked list of infinite size, the rte_ring has the following
 
 The advantages of this data structure over a linked list queue are as follows:
 
-*   Faster; only requires a single Compare-And-Swap instruction of sizeof(void \*) instead of several double-Compare-And-Swap instructions.
+*   Faster; only requires a single 32 bit Compare-And-Swap instruction instead of several pointer size Compare-And-Swap instructions.
 
 *   Simpler than a full lockless queue.
 
 *   Adapted to bulk enqueue/dequeue operations.
-    As pointers are stored in a table, a dequeue of several objects will not produce as many cache misses as in a linked queue.
+    As objects are stored in a table, a dequeue of several objects will not produce as many cache misses as in a linked queue.
     Also, a bulk dequeue of many objects does not cost more than a dequeue of a simple object.
 
 The disadvantages:
 
 *   Size is fixed
 
-*   Having many rings costs more in terms of memory than a linked list queue. An empty ring contains at least N pointers.
+*   Having many rings costs more in terms of memory than a linked list queue. An empty ring contains at least N objects.
 
 A simplified representation of a Ring is shown in with consumer and producer head and tail pointers to objects stored in the data structure.
 
@@ -125,7 +127,7 @@ Enqueue Second Step
 
 The second step is to modify *ring->prod_head* in ring structure to point to the same location as prod_next.
 
-A pointer to the added object is copied in the ring (obj4).
+The added object is copied in the ring (obj4).
 
 
 .. _figure_ring-enqueue2:
@@ -178,7 +180,7 @@ Dequeue Second Step
 
 The second step is to modify ring->cons_head in the ring structure to point to the same location as cons_next.
 
-The pointer to the dequeued object (obj1) is copied in the pointer given by the user.
+The dequeued object (obj1) is copied in the pointer given by the user.
 
 
 .. _figure_ring-dequeue2:
@@ -298,7 +300,7 @@ Modulo 32-bit Indexes
 
 In the preceding figures, the prod_head, prod_tail, cons_head and cons_tail indexes are represented by arrows.
 In the actual implementation, these values are not between 0 and size(ring)-1 as would be assumed.
-The indexes are between 0 and 2^32 -1, and we mask their value when we access the pointer table (the ring itself).
+The indexes are between 0 and 2^32 -1, and we mask their value when we access the object table (the ring itself).
 32-bit modulo also implies that operations on indexes (such as, add/subtract) will automatically do 2^32 modulo
 if the result overflows the 32-bit number range.
 
-- 
2.17.1

Re: [dpdk-dev] [PATCH 2/2] doc: change prog guide to reflect rte_ring_xxx_elem apis

[Thomas Monjalon]

31/01/2020 04:59, Honnappa Nagarahalli:
> Changed the rte_ring chapter in programmer's guide to reflect
> the addition of rte_ring_xxx_elem APIs. References to pointers
> as ring elements is changed to generic term 'objects'.
> 
> Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
> Reviewed-by: Gavin Hu <gavin.hu@arm.com>

Series applied, thanks