From: Paul Szczepanek <paul.szczepanek@arm.com>
To: dev@dpdk.org
Cc: mb@smartsharesystems.com,
Paul Szczepanek <paul.szczepanek@arm.com>,
Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>,
Nathan Brown <nathan.brown@arm.com>,
Jack Bond-Preston <jack.bond-preston@arm.com>
Subject: [PATCH v11 5/6] docs: add pointer compression guide
Date: Fri, 24 May 2024 08:36:50 +0000 [thread overview]
Message-ID: <20240524083651.482541-6-paul.szczepanek@arm.com> (raw)
In-Reply-To: <20240524083651.482541-1-paul.szczepanek@arm.com>
Documentation added in the prog guide for the new
utility functions for pointer compression
showing example code and potential usecases.
Signed-off-by: Paul Szczepanek <paul.szczepanek@arm.com>
Reviewed-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
Reviewed-by: Nathan Brown <nathan.brown@arm.com>
Reviewed-by: Jack Bond-Preston <jack.bond-preston@arm.com>
---
MAINTAINERS | 1 +
doc/guides/prog_guide/index.rst | 1 +
doc/guides/prog_guide/ptr_compress_lib.rst | 160 +++++++++++++++++++++
3 files changed, 162 insertions(+)
create mode 100644 doc/guides/prog_guide/ptr_compress_lib.rst
diff --git a/MAINTAINERS b/MAINTAINERS
index 27b2f03e6c..ed50121bd2 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1697,6 +1697,7 @@ F: lib/pci/
Pointer Compression
M: Paul Szczepanek <paul.szczepanek@arm.com>
F: lib/ptr_compress/
+F: doc/guides/prog_guide/ptr_compress_lib.rst
Power management
M: Anatoly Burakov <anatoly.burakov@intel.com>
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index d09d958e6c..6366849eb0 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -73,6 +73,7 @@ Programmer's Guide
telemetry_lib
bpf_lib
graph_lib
+ ptr_compress_lib
build-sdk-meson
meson_ut
build_app
diff --git a/doc/guides/prog_guide/ptr_compress_lib.rst b/doc/guides/prog_guide/ptr_compress_lib.rst
new file mode 100644
index 0000000000..349da2695e
--- /dev/null
+++ b/doc/guides/prog_guide/ptr_compress_lib.rst
@@ -0,0 +1,160 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2024 Arm Limited.
+
+Pointer Compression Library
+===========================
+
+Use ``rte_ptr_compress_16_shift()`` and ``rte_ptr_decompress_16_shift()`` to
+compress and decompress pointers into 16-bit offsets.
+Use ``rte_ptr_compress_32_shift()`` and ``rte_ptr_decompress_32_shift()`` to
+compress and decompress pointers into 32-bit offsets.
+
+Compression takes advantage of the fact that pointers are usually located in a
+limited memory region (like a mempool). By converting them to offsets from a
+base memory address they can be stored in fewer bytes. How many bytes are needed
+to store the offset is dictated by the memory region size and alignment of
+objects the pointers point to.
+
+For example, a pointer which is part of a 4GB memory pool can be stored as 32
+bit offset. If the pointer points to memory that is 8 bytes aligned then 3 bits
+can be dropped from the offset and a 32GB memory pool can now fit in 32 bits.
+
+For performance reasons these requirements are not enforced programmatically.
+The programmer is responsible for ensuring that the combination of distance
+from the base pointer and memory alignment allow for storing of the offset in
+the number of bits indicated by the function name (16 or 32). Start of mempool
+memory would be a good candidate for the base pointer. Otherwise any pointer
+that precedes all pointers, is close enough and has the same alignment as the
+pointers being compressed will work.
+
+Macros present in the rte_ptr_compress.h header may be used to evaluate whether
+compression is possible:
+
+* BITS_REQUIRED_TO_STORE_VALUE
+
+* BIT_SHIFT_FROM_ALIGNMENT
+
+* CAN_USE_RTE_PTR_compress_16_shift
+
+* CAN_USE_RTE_PTR_compress_32_shift
+
+These will help you calculate compression parameters and whether these are
+legal for particular compression function.
+
+If using an rte_mempool you can get the parameters you need to use in the
+compression macros and functions by using ``rte_mempool_get_mem_range()``
+and ``rte_mempool_get_obj_alignment()``.
+
+.. note::
+
+ Performance gains depend on the batch size of pointers and CPU capabilities
+ such as vector extensions. It's important to measure the performance
+ increase on target hardware. A test called ``ring_perf_autotest`` in
+ ``dpdk-test`` can provide the measurements.
+
+Example usage
+~~~~~~~~~~~~~
+
+In this example we send pointers between two cores through a ring. While this
+is a realistic use case the code is simplified for demonstration purposes and
+does not have error handling.
+
+.. code-block:: c
+
+ #include <rte_launch.h>
+ #include <rte_ring.h>
+ #include <rte_ring_elem.h>
+ #include <rte_ptr_compress.h>
+
+ #define ITEMS_ARRAY_SIZE (1024)
+ #define BATCH_SIZE (128)
+ #define ALIGN_EXPONENT (3)
+ #define ITEM_ALIGN (1<<ALIGN_EXPONENT)
+ #define CORE_SEND (1)
+ #define CORE_RECV (2)
+
+ struct item {
+ alignas(ITEM_ALIGN) int a;
+ };
+
+ static struct item items[ITEMS_ARRAY_SIZE] = {0};
+ static struct rte_ring *ring = NULL;
+
+ static int
+ send_compressed(void *args)
+ {
+ struct item *ptrs_send[BATCH_SIZE] = {0};
+ unsigned int n_send = 0;
+ struct rte_ring_zc_data zcd = {0};
+
+ /* in this example we only fill the ptrs_send once and reuse */
+ for (;n_send < BATCH_SIZE; n_send++)
+ ptrs_send[n_send] = &items[n_send];
+
+ for(;;) {
+ n_send = rte_ring_enqueue_zc_burst_elem_start(
+ ring, sizeof(uint32_t), BATCH_SIZE, &zcd, NULL);
+
+ /* compress ptrs_send into offsets */
+ rte_ptr_compress_32_shift(items, /* base pointer */
+ ptrs_send, /* source array to be compressed */
+ zcd.ptr1, /* destination array to store offsets */
+ zcd.n1, /* how many pointers to compress */
+ ALIGN_EXPONENT /* how many bits can we drop from the offset */);
+
+ if (zcd.ptr2 != NULL)
+ rte_ptr_compress_32_shift(items, ptrs_send + zcd.n1,
+ zcd.ptr2, n_send - zcd.n1, ALIGN_EXPONENT);
+
+ rte_ring_enqueue_zc_finish(ring, n_send);
+ }
+ return 1;
+ }
+
+ static int
+ recv_compressed(void *args)
+ {
+ struct item *ptrs_recv[BATCH_SIZE] = {0};
+ unsigned int n_recv;
+ struct rte_ring_zc_data zcd = {0};
+
+ for(;;) {
+ /* receive compressed pointers from the ring */
+ n_recv = rte_ring_dequeue_zc_burst_elem_start(
+ ring, sizeof(uint32_t), BATCH_SIZE, &zcd, NULL);
+
+ rte_ptr_decompress_32_shift(items, /* base pointer */
+ zcd.ptr1, /* source array to decompress */
+ ptrs_recv, /* destination array to store pointers */
+ zcd.n1, /* how many pointers to decompress */
+ ALIGN_EXPONENT /* how many bits were dropped from the offset */);
+
+ /* handle the potential secondary buffer (caused by ring boundary) */
+ if (zcd.ptr2 != NULL)
+ rte_ptr_decompress_32_shift(items,
+ zcd.ptr2,
+ ptrs_recv + zcd.n1,
+ n_recv - zcd.n1,
+ ALIGN_EXPONENT);
+
+ rte_ring_dequeue_zc_finish(ring, n_recv);
+
+ /* ptrs_recv contains what ptrs_send contained in the other thread */
+ /* (...) */
+ }
+ return 1;
+ }
+
+ void
+ compression_example(void)
+ {
+ ring = rte_ring_create_elem(
+ "COMPR_PTRS", sizeof(uint32_t),
+ 1024, rte_socket_id(),
+ RING_F_SP_ENQ | RING_F_SC_DEQ);
+
+ rte_eal_remote_launch(send_compressed, NULL, CORE_SEND);
+ rte_eal_remote_launch(recv_compressed, NULL, CORE_RECV);
+
+ for(;;) {}
+ }
--
2.25.1
next prev parent reply other threads:[~2024-05-24 8:37 UTC|newest]
Thread overview: 141+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-09-27 15:08 [RFC 0/2] add pointer compression API Paul Szczepanek
2023-09-27 15:08 ` [RFC 1/2] eal: add pointer compression functions Paul Szczepanek
2023-10-09 15:54 ` Thomas Monjalon
2023-10-11 13:36 ` Honnappa Nagarahalli
2023-10-11 16:43 ` Paul Szczepanek
2023-10-11 12:43 ` [RFC v2 0/2] add pointer compression API Paul Szczepanek
2023-10-11 12:43 ` [RFC v2 1/2] eal: add pointer compression functions Paul Szczepanek
2023-10-11 12:43 ` [RFC v2 2/2] test: add pointer compress tests to ring perf test Paul Szczepanek
2023-10-31 18:10 ` [PATCH v3 0/3] add pointer compression API Paul Szczepanek
2023-10-31 18:10 ` [PATCH v3 1/3] eal: add pointer compression functions Paul Szczepanek
2023-10-31 18:10 ` [PATCH v3 2/3] test: add pointer compress tests to ring perf test Paul Szczepanek
2023-10-31 18:10 ` [PATCH v3 3/3] docs: add pointer compression to the EAL guide Paul Szczepanek
2023-11-01 7:42 ` [PATCH v3 0/3] add pointer compression API Morten Brørup
2023-11-01 12:52 ` Paul Szczepanek
2023-11-01 12:46 ` [PATCH v4 0/4] " Paul Szczepanek
2023-11-01 12:46 ` [PATCH v4 1/4] eal: add pointer compression functions Paul Szczepanek
2023-11-01 12:46 ` [PATCH v4 2/4] test: add pointer compress tests to ring perf test Paul Szczepanek
2023-11-01 12:46 ` [PATCH v4 3/4] docs: add pointer compression to the EAL guide Paul Szczepanek
2023-11-01 12:46 ` [PATCH v4 4/4] test: add unit test for ptr compression Paul Szczepanek
2023-11-01 18:12 ` [PATCH v5 0/4] add pointer compression API Paul Szczepanek
2023-11-01 18:12 ` [PATCH v5 1/4] eal: add pointer compression functions Paul Szczepanek
2024-02-11 15:32 ` Konstantin Ananyev
2023-11-01 18:12 ` [PATCH v5 2/4] test: add pointer compress tests to ring perf test Paul Szczepanek
2023-11-01 18:13 ` [PATCH v5 3/4] docs: add pointer compression to the EAL guide Paul Szczepanek
2023-11-01 18:13 ` [PATCH v5 4/4] test: add unit test for ptr compression Paul Szczepanek
2024-02-22 8:15 ` [PATCH v5 0/4] add pointer compression API Paul Szczepanek
2024-02-22 16:16 ` Konstantin Ananyev
2024-03-01 11:16 ` Morten Brørup
2024-03-01 16:12 ` Patrick Robb
2024-03-01 19:57 ` Honnappa Nagarahalli
2024-03-02 10:33 ` Morten Brørup
2024-03-06 22:31 ` Paul Szczepanek
2024-03-07 2:13 ` Honnappa Nagarahalli
2024-03-04 14:44 ` Konstantin Ananyev
2024-05-15 17:00 ` Paul Szczepanek
2024-05-15 22:34 ` Morten Brørup
2024-05-16 8:25 ` Paul Szczepanek
2024-05-16 8:40 ` Konstantin Ananyev
2024-05-24 8:33 ` Paul Szczepanek
2024-05-24 9:09 ` Konstantin Ananyev
2024-05-28 19:29 ` Paul Szczepanek
2024-05-29 10:28 ` Paul Szczepanek
2024-06-06 13:33 ` Konstantin Ananyev
2024-02-29 16:03 ` [PATCH v6 " Paul Szczepanek
2024-02-29 16:03 ` [PATCH v6 1/4] eal: add pointer compression functions Paul Szczepanek
2024-02-29 16:03 ` [PATCH v6 2/4] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-02-29 16:03 ` [PATCH v6 3/4] docs: add pointer compression to the EAL guide Paul Szczepanek
2024-02-29 16:03 ` [PATCH v6 4/4] test: add unit test for ptr compression Paul Szczepanek
2024-03-01 10:21 ` [PATCH v7 0/4] add pointer compression API Paul Szczepanek
2024-03-01 10:21 ` [PATCH v7 1/4] eal: add pointer compression functions Paul Szczepanek
2024-03-07 11:22 ` David Marchand
2024-03-01 10:21 ` [PATCH v7 2/4] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-03-07 11:27 ` David Marchand
2024-03-01 10:21 ` [PATCH v7 3/4] docs: add pointer compression to the EAL guide Paul Szczepanek
2024-03-01 10:21 ` [PATCH v7 4/4] test: add unit test for ptr compression Paul Szczepanek
2024-03-07 11:30 ` David Marchand
2024-03-07 20:39 ` [PATCH v7 0/4] add pointer compression API Paul Szczepanek
2024-03-07 20:39 ` [PATCH v8 1/4] ptr_compress: add pointer compression library Paul Szczepanek
2024-03-07 20:39 ` [PATCH v8 2/4] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-03-07 20:39 ` [PATCH v8 3/4] docs: add pointer compression guide Paul Szczepanek
2024-03-07 20:39 ` [PATCH v8 4/4] test: add unit test for ptr compression Paul Szczepanek
2024-03-08 8:27 ` [PATCH v7 0/4] add pointer compression API David Marchand
2024-03-10 19:34 ` Honnappa Nagarahalli
2024-03-11 7:44 ` David Marchand
2024-03-11 14:47 ` [PATCH v9 0/5] " Paul Szczepanek
2024-03-11 14:47 ` [PATCH v9 1/5] lib: allow libraries with no sources Paul Szczepanek
2024-03-11 15:23 ` Bruce Richardson
2024-03-15 8:33 ` Paul Szczepanek
2024-03-11 14:47 ` [PATCH v9 2/5] ptr_compress: add pointer compression library Paul Szczepanek
2024-03-11 14:47 ` [PATCH v9 3/5] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-03-11 14:47 ` [PATCH v9 4/5] docs: add pointer compression guide Paul Szczepanek
2024-03-11 14:47 ` [PATCH v9 5/5] test: add unit test for ptr compression Paul Szczepanek
2024-03-11 20:31 ` [PATCH v10 0/5] add pointer compression API Paul Szczepanek
2024-03-11 20:31 ` [PATCH v10 1/5] lib: allow libraries with no sources Paul Szczepanek
2024-03-15 9:14 ` Bruce Richardson
2024-03-11 20:31 ` [PATCH v10 2/5] ptr_compress: add pointer compression library Paul Szczepanek
2024-03-11 20:31 ` [PATCH v10 3/5] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-03-11 20:31 ` [PATCH v10 4/5] docs: add pointer compression guide Paul Szczepanek
2024-03-11 20:31 ` [PATCH v10 5/5] test: add unit test for ptr compression Paul Szczepanek
2024-05-24 8:36 ` [PATCH v11 0/6] add pointer compression API Paul Szczepanek
2024-05-24 8:36 ` [PATCH v11 1/6] lib: allow libraries with no sources Paul Szczepanek
2024-05-24 8:36 ` [PATCH v11 2/6] mempool: add functions to get extra mempool info Paul Szczepanek
2024-05-24 12:20 ` Morten Brørup
2024-05-28 19:33 ` Paul Szczepanek
2024-05-24 8:36 ` [PATCH v11 3/6] ptr_compress: add pointer compression library Paul Szczepanek
2024-05-24 12:50 ` Morten Brørup
2024-06-06 13:22 ` Konstantin Ananyev
2024-05-24 8:36 ` [PATCH v11 4/6] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-05-24 8:36 ` Paul Szczepanek [this message]
2024-05-24 8:36 ` [PATCH v11 6/6] test: add unit test for ptr compression Paul Szczepanek
2024-05-29 10:22 ` [PATCH v12 0/6] add pointer compression API Paul Szczepanek
2024-05-29 10:22 ` [PATCH v12 1/6] lib: allow libraries with no sources Paul Szczepanek
2024-05-29 10:22 ` [PATCH v12 2/6] mempool: add functions to get extra mempool info Paul Szczepanek
2024-05-29 11:47 ` Morten Brørup
2024-05-29 13:56 ` Morten Brørup
2024-05-29 16:18 ` Paul Szczepanek
2024-05-30 0:56 ` Du, Frank
2024-05-29 10:22 ` [PATCH v12 3/6] ptr_compress: add pointer compression library Paul Szczepanek
2024-05-29 11:52 ` Morten Brørup
2024-05-29 10:22 ` [PATCH v12 4/6] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-05-29 10:22 ` [PATCH v12 5/6] docs: add pointer compression guide Paul Szczepanek
2024-05-29 10:22 ` [PATCH v12 6/6] test: add unit test for ptr compression Paul Szczepanek
2024-05-30 9:40 ` [PATCH v13 0/6] add pointer compression API Paul Szczepanek
2024-05-30 9:40 ` [PATCH v13 1/6] lib: allow libraries with no sources Paul Szczepanek
2024-05-30 9:40 ` [PATCH v13 2/6] mempool: add functions to get extra mempool info Paul Szczepanek
2024-05-31 9:32 ` Morten Brørup
2024-06-06 12:28 ` Konstantin Ananyev
2024-06-07 15:12 ` Paul Szczepanek
2024-05-30 9:40 ` [PATCH v13 3/6] ptr_compress: add pointer compression library Paul Szczepanek
2024-05-30 9:40 ` [PATCH v13 4/6] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-05-30 9:40 ` [PATCH v13 5/6] docs: add pointer compression guide Paul Szczepanek
2024-05-30 9:40 ` [PATCH v13 6/6] test: add unit test for ptr compression Paul Szczepanek
2024-06-04 9:06 ` Paul Szczepanek
2024-06-04 9:07 ` Paul Szczepanek
2024-05-30 13:35 ` [PATCH v13 0/6] add pointer compression API Paul Szczepanek
2024-06-04 9:04 ` Paul Szczepanek
2023-09-27 15:08 ` [RFC 2/2] test: add pointer compress tests to ring perf test Paul Szczepanek
2023-10-09 15:48 ` Thomas Monjalon
2024-06-07 15:09 ` [PATCH v14 0/6] add pointer compression API Paul Szczepanek
2024-06-07 15:09 ` [PATCH v14 1/6] lib: allow libraries with no sources Paul Szczepanek
2024-06-07 15:09 ` [PATCH v14 2/6] mempool: add functions to get extra mempool info Paul Szczepanek
2024-06-10 14:24 ` Konstantin Ananyev
2024-06-11 13:06 ` Paul Szczepanek
2024-06-07 15:09 ` [PATCH v14 3/6] ptr_compress: add pointer compression library Paul Szczepanek
2024-06-10 15:18 ` David Marchand
2024-06-10 15:37 ` Morten Brørup
2024-06-11 13:16 ` Paul Szczepanek
2024-06-07 15:09 ` [PATCH v14 4/6] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-06-07 15:09 ` [PATCH v14 5/6] docs: add pointer compression guide Paul Szczepanek
2024-06-07 15:10 ` [PATCH v14 6/6] test: add unit test for ptr compression Paul Szczepanek
2024-06-11 12:59 ` [PATCH v15 0/6] add pointer compression API Paul Szczepanek
2024-06-11 12:59 ` [PATCH v15 1/6] lib: allow libraries with no sources Paul Szczepanek
2024-06-11 12:59 ` [PATCH v15 2/6] mempool: add functions to get extra mempool info Paul Szczepanek
2024-06-11 12:59 ` [PATCH v15 3/6] ptr_compress: add pointer compression library Paul Szczepanek
2024-06-11 12:59 ` [PATCH v15 4/6] test: add pointer compress tests to ring perf test Paul Szczepanek
2024-06-11 12:59 ` [PATCH v15 5/6] docs: add pointer compression guide Paul Szczepanek
2024-06-11 12:59 ` [PATCH v15 6/6] test: add unit test for ptr compression Paul Szczepanek
2024-06-14 10:28 ` [PATCH v15 0/6] add pointer compression API David Marchand
2024-06-17 10:02 ` David Marchand
2024-06-17 13:46 ` Paul Szczepanek
2024-06-17 13:57 ` David Marchand
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240524083651.482541-6-paul.szczepanek@arm.com \
--to=paul.szczepanek@arm.com \
--cc=dev@dpdk.org \
--cc=honnappa.nagarahalli@arm.com \
--cc=jack.bond-preston@arm.com \
--cc=mb@smartsharesystems.com \
--cc=nathan.brown@arm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).