<div dir="ltr"><div>Signed-off-by: David Young <<a href="mailto:dave@youngcopy.com">dave@youngcopy.com</a>></div><div> </div><div><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>Thanks! David Young Professional Copywriter/Technical Writer Young Copy </div><div>+1 (678) 500-9550 </div><div><a href="https://www.youngcopy.com" target="_blank">https://www.youngcopy.com</a> </div></div></div></div></div></div> </div> <div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Dec 7, 2023 at 9:11 PM David Young <<a href="mailto:dave@youngcopy.com">dave@youngcopy.com</a>> wrote: </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">--- doc/guides/prog_guide/bpf_lib.rst | 4 +- doc/guides/prog_guide/dmadev.rst | 6 +- doc/guides/prog_guide/efd_lib.rst | 4 +- .../prog_guide/env_abstraction_layer.rst | 4 +- doc/guides/prog_guide/ethdev/index.rst | 12 ++ .../prog_guide/{ => ethdev}/poll_mode_drv.rst | 0 .../prog_guide/{ => ethdev}/qos_framework.rst | 0 .../prog_guide/{ => ethdev}/rte_flow.rst | 0 .../{ => ethdev}/switch_representation.rst | 0 .../{ => ethdev}/traffic_management.rst | 0 .../traffic_metering_and_policing.rst | 0 .../{ => eventdev}/event_crypto_adapter.rst | 0 .../event_ethernet_rx_adapter.rst | 0 .../event_ethernet_tx_adapter.rst | 0 .../{ => eventdev}/event_timer_adapter.rst | 0 .../prog_guide/{ => eventdev}/eventdev.rst | 2 +- doc/guides/prog_guide/eventdev/index.rst | 11 ++ doc/guides/prog_guide/fib_lib.rst | 4 +- .../generic_receive_offload_lib.rst | 4 +- .../generic_segmentation_offload_lib.rst | 4 +- doc/guides/prog_guide/gpudev.rst | 4 +- doc/guides/prog_guide/index.rst | 145 ++++++++++++------ doc/guides/prog_guide/lpm6_lib.rst | 4 +- doc/guides/prog_guide/lpm_lib.rst | 4 +- doc/guides/prog_guide/mbuf_lib.rst | 6 +- doc/guides/prog_guide/mempool_lib.rst | 4 +- doc/guides/prog_guide/mldev.rst | 6 +- .../prog_guide/packet_classif_access_ctrl.rst | 4 +- doc/guides/prog_guide/packet_framework.rst | 4 +- doc/guides/prog_guide/rawdev.rst | 4 +- doc/guides/prog_guide/regexdev.rst | 4 +- doc/guides/prog_guide/rib_lib.rst | 4 +- ...y_dpdk_functions.rst => thread_safety.rst} | 4 +- 33 files changed, 166 insertions(+), 86 deletions(-) create mode 100644 doc/guides/prog_guide/ethdev/index.rst rename doc/guides/prog_guide/{ => ethdev}/poll_mode_drv.rst (100%) rename doc/guides/prog_guide/{ => ethdev}/qos_framework.rst (100%) rename doc/guides/prog_guide/{ => ethdev}/rte_flow.rst (100%) rename doc/guides/prog_guide/{ => ethdev}/switch_representation.rst (100%) rename doc/guides/prog_guide/{ => ethdev}/traffic_management.rst (100%) rename doc/guides/prog_guide/{ => ethdev}/traffic_metering_and_policing.rst (100%) rename doc/guides/prog_guide/{ => eventdev}/event_crypto_adapter.rst (100%) rename doc/guides/prog_guide/{ => eventdev}/event_ethernet_rx_adapter.rst (100%) rename doc/guides/prog_guide/{ => eventdev}/event_ethernet_tx_adapter.rst (100%) rename doc/guides/prog_guide/{ => eventdev}/event_timer_adapter.rst (100%) rename doc/guides/prog_guide/{ => eventdev}/eventdev.rst (99%) create mode 100644 doc/guides/prog_guide/eventdev/index.rst rename doc/guides/prog_guide/{thread_safety_dpdk_functions.rst => thread_safety.rst} (98%) diff --git a/doc/guides/prog_guide/bpf_lib.rst b/doc/guides/prog_guide/bpf_lib.rst index 1cf2d59429..8c820328b9 100644 --- a/doc/guides/prog_guide/bpf_lib.rst +++ b/doc/guides/prog_guide/bpf_lib.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2018 Intel Corporation. -Berkeley Packet Filter Library -============================== +Berkeley Packet Filter (BPF) Library +==================================== The DPDK provides an BPF library that gives the ability to load and execute Enhanced Berkeley Packet Filter (eBPF) bytecode within diff --git a/doc/guides/prog_guide/dmadev.rst b/doc/guides/prog_guide/dmadev.rst index 2aa26d33b8..2b31dc904f 100644 --- a/doc/guides/prog_guide/dmadev.rst +++ b/doc/guides/prog_guide/dmadev.rst @@ -1,8 +1,10 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright 2021 HiSilicon Limited -DMA Device Library -================== +.. _direct_memory_access_dma: + +Direct Memory Access (DMA) Device Library +========================================= The DMA library provides a DMA device framework for management and provisioning of hardware and software DMA poll mode drivers, defining generic API which diff --git a/doc/guides/prog_guide/efd_lib.rst b/doc/guides/prog_guide/efd_lib.rst index 2b355ff2a6..4bee7237be 100644 --- a/doc/guides/prog_guide/efd_lib.rst +++ b/doc/guides/prog_guide/efd_lib.rst @@ -3,8 +3,8 @@ .. _Efd_Library: -Elastic Flow Distributor Library -================================ +Elastic Flow Distributor (EFD) Library +====================================== Introduction ------------ diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst index 6debf54efb..5ce80a4496 100644 --- a/doc/guides/prog_guide/env_abstraction_layer.rst +++ b/doc/guides/prog_guide/env_abstraction_layer.rst @@ -3,8 +3,8 @@ .. _Environment_Abstraction_Layer: -Environment Abstraction Layer -============================= +Environment Abstraction Layer (EAL) Library +=========================================== The Environment Abstraction Layer (EAL) is responsible for gaining access to low-level resources such as hardware and memory space. It provides a generic interface that hides the environment specifics from the applications and libraries. diff --git a/doc/guides/prog_guide/ethdev/index.rst b/doc/guides/prog_guide/ethdev/index.rst new file mode 100644 index 0000000000..c8e3b0d37b --- /dev/null +++ b/doc/guides/prog_guide/ethdev/index.rst @@ -0,0 +1,12 @@ +Ethernet Device Library +======================= + +.. toctree:: + :maxdepth: 1 + + poll_mode_drv + rte_flow + switch_representation + traffic_metering_and_policing + traffic_management + qos_framework diff --git a/doc/guides/prog_guide/poll_mode_drv.rst b/doc/guides/prog_guide/ethdev/poll_mode_drv.rst similarity index 100% rename from doc/guides/prog_guide/poll_mode_drv.rst rename to doc/guides/prog_guide/ethdev/poll_mode_drv.rst diff --git a/doc/guides/prog_guide/qos_framework.rst b/doc/guides/prog_guide/ethdev/qos_framework.rst similarity index 100% rename from doc/guides/prog_guide/qos_framework.rst rename to doc/guides/prog_guide/ethdev/qos_framework.rst diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/ethdev/rte_flow.rst similarity index 100% rename from doc/guides/prog_guide/rte_flow.rst rename to doc/guides/prog_guide/ethdev/rte_flow.rst diff --git a/doc/guides/prog_guide/switch_representation.rst b/doc/guides/prog_guide/ethdev/switch_representation.rst similarity index 100% rename from doc/guides/prog_guide/switch_representation.rst rename to doc/guides/prog_guide/ethdev/switch_representation.rst diff --git a/doc/guides/prog_guide/traffic_management.rst b/doc/guides/prog_guide/ethdev/traffic_management.rst similarity index 100% rename from doc/guides/prog_guide/traffic_management.rst rename to doc/guides/prog_guide/ethdev/traffic_management.rst diff --git a/doc/guides/prog_guide/traffic_metering_and_policing.rst b/doc/guides/prog_guide/ethdev/traffic_metering_and_policing.rst similarity index 100% rename from doc/guides/prog_guide/traffic_metering_and_policing.rst rename to doc/guides/prog_guide/ethdev/traffic_metering_and_policing.rst diff --git a/doc/guides/prog_guide/event_crypto_adapter.rst b/doc/guides/prog_guide/eventdev/event_crypto_adapter.rst similarity index 100% rename from doc/guides/prog_guide/event_crypto_adapter.rst rename to doc/guides/prog_guide/eventdev/event_crypto_adapter.rst diff --git a/doc/guides/prog_guide/event_ethernet_rx_adapter.rst b/doc/guides/prog_guide/eventdev/event_ethernet_rx_adapter.rst similarity index 100% rename from doc/guides/prog_guide/event_ethernet_rx_adapter.rst rename to doc/guides/prog_guide/eventdev/event_ethernet_rx_adapter.rst diff --git a/doc/guides/prog_guide/event_ethernet_tx_adapter.rst b/doc/guides/prog_guide/eventdev/event_ethernet_tx_adapter.rst similarity index 100% rename from doc/guides/prog_guide/event_ethernet_tx_adapter.rst rename to doc/guides/prog_guide/eventdev/event_ethernet_tx_adapter.rst diff --git a/doc/guides/prog_guide/event_timer_adapter.rst b/doc/guides/prog_guide/eventdev/event_timer_adapter.rst similarity index 100% rename from doc/guides/prog_guide/event_timer_adapter.rst rename to doc/guides/prog_guide/eventdev/event_timer_adapter.rst diff --git a/doc/guides/prog_guide/eventdev.rst b/doc/guides/prog_guide/eventdev/eventdev.rst similarity index 99% rename from doc/guides/prog_guide/eventdev.rst rename to doc/guides/prog_guide/eventdev/eventdev.rst index 2c83176846..211fcaeb9f 100644 --- a/doc/guides/prog_guide/eventdev.rst +++ b/doc/guides/prog_guide/eventdev/eventdev.rst @@ -169,7 +169,7 @@ walk-through: .. _figure_eventdev-usage1: -.. figure:: img/eventdev_usage.* +.. figure:: ../img/eventdev_usage.* Sample eventdev usage, with RX, two atomic stages and a single-link to TX. diff --git a/doc/guides/prog_guide/eventdev/index.rst b/doc/guides/prog_guide/eventdev/index.rst new file mode 100644 index 0000000000..e0e3f4328d --- /dev/null +++ b/doc/guides/prog_guide/eventdev/index.rst @@ -0,0 +1,11 @@ +Event Device Library +==================== + +.. toctree:: + :maxdepth: 1 + + eventdev + event_ethernet_rx_adapter + event_ethernet_tx_adapter + event_timer_adapter + event_crypto_adapter diff --git a/doc/guides/prog_guide/fib_lib.rst b/doc/guides/prog_guide/fib_lib.rst index 970a433d34..a81da2d491 100644 --- a/doc/guides/prog_guide/fib_lib.rst +++ b/doc/guides/prog_guide/fib_lib.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2021 Intel Corporation. -FIB Library -=========== +Forwarding Information Base (FIB) Library +========================================= The FIB library provides a fast Longest Prefix Match (LPM) search for 32-bit keys or 128-bit for IPv6. It can be used in a variety of applications, diff --git a/doc/guides/prog_guide/generic_receive_offload_lib.rst b/doc/guides/prog_guide/generic_receive_offload_lib.rst index 6d176947e4..f2b5ff9eed 100644 --- a/doc/guides/prog_guide/generic_receive_offload_lib.rst +++ b/doc/guides/prog_guide/generic_receive_offload_lib.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2017 Intel Corporation. -Generic Receive Offload Library -=============================== +Generic Receive Offload (GRO) Library +===================================== Generic Receive Offload (GRO) is a widely used SW-based offloading technique to reduce per-packet processing overheads. By reassembling diff --git a/doc/guides/prog_guide/generic_segmentation_offload_lib.rst b/doc/guides/prog_guide/generic_segmentation_offload_lib.rst index e605b86376..97b906aee1 100644 --- a/doc/guides/prog_guide/generic_segmentation_offload_lib.rst +++ b/doc/guides/prog_guide/generic_segmentation_offload_lib.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2017 Intel Corporation. -Generic Segmentation Offload Library -==================================== +Generic Segmentation Offload (GSO) Library +========================================== Overview -------- diff --git a/doc/guides/prog_guide/gpudev.rst b/doc/guides/prog_guide/gpudev.rst index c6ae7191c8..de246d2a4c 100644 --- a/doc/guides/prog_guide/gpudev.rst +++ b/doc/guides/prog_guide/gpudev.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2021 NVIDIA Corporation & Affiliates -General-Purpose Graphics Processing Unit Library -================================================ +General-Purpose Graphics Processing Unit (GPU) Library +====================================================== When mixing networking activity with task processing on a GPU device, there may be the need to put in communication the CPU with the device diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 52a6d9e7aa..6fcf304c68 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -4,28 +4,67 @@ Programmer's Guide ================== +Foundation Principles +--------------------- + .. toctree:: - :maxdepth: 3 - :numbered: + :maxdepth: 1 intro overview source_org - env_abstraction_layer - log_lib - service_cores - trace_lib - rcu_lib - ring_lib - stack_lib + glossary + +Memory Management +----------------- + +.. toctree:: + :maxdepth: 1 + mempool_lib mbuf_lib - poll_mode_drv - rte_flow - switch_representation - traffic_metering_and_policing - traffic_management - bbdev + multi_proc_support + +CPU Management +-------------- + +.. toctree:: + :maxdepth: 1 + + env_abstraction_layer + power_man + thread_safety + service_cores + +CPU Packet Processing +--------------------- + +.. toctree:: + :maxdepth: 1 + + lpm_lib + lpm6_lib + rib_lib + fib_lib + packet_classif_access_ctrl + packet_distrib_lib + efd_lib + reorder_lib + ip_fragment_reassembly_lib + generic_receive_offload_lib + generic_segmentation_offload_lib + toeplitz_hash_lib + hash_lib + member_lib + +Device Libraries +---------------- + +.. toctree:: + :maxdepth: 1 + + ethdev/index + vhost_lib cryptodev_lib compressdev regexdev @@ -35,46 +74,62 @@ Programmer's Guide rte_security rawdev link_bonding_poll_mode_drv_lib + bbdev + eventdev/index + +Utility Libraries +----------------- + +.. toctree:: + :maxdepth: 1 + timer_lib - hash_lib - toeplitz_hash_lib - efd_lib - member_lib - lpm_lib - lpm6_lib - fib_lib - rib_lib - packet_distrib_lib - reorder_lib - ip_fragment_reassembly_lib - generic_receive_offload_lib - generic_segmentation_offload_lib - ipsec_lib - pdcp_lib - pcapng_lib - pdump_lib - multi_proc_support - thread_safety_dpdk_functions - eventdev - event_ethernet_rx_adapter - event_ethernet_tx_adapter - event_timer_adapter - event_crypto_adapter - qos_framework - power_man - packet_classif_access_ctrl - packet_framework - vhost_lib + rcu_lib + ring_lib + stack_lib metrics_lib telemetry_lib + pdump_lib + pcapng_lib bpf_lib + trace_lib + +Protocol Processing Libraries +----------------------------- + +.. toctree:: + :maxdepth: 1 + + pdcp_lib + ipsec_lib + +High-Level Libraries +-------------------- + +.. toctree:: + :maxdepth: 1 + + packet_framework graph_lib + +Howto Guides +------------- + +.. toctree:: + :maxdepth: 1 + build-sdk-meson meson_ut build_app + +Tips & Tricks +------------- + +.. toctree:: + :maxdepth: 1 + perf_opt_guidelines writing_efficient_code lto profile_app asan - glossary diff --git a/doc/guides/prog_guide/lpm6_lib.rst b/doc/guides/prog_guide/lpm6_lib.rst index 8425d14805..2c3eb10857 100644 --- a/doc/guides/prog_guide/lpm6_lib.rst +++ b/doc/guides/prog_guide/lpm6_lib.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -LPM6 Library -============ +Longest Prefix Match 6 (LPM6) Library +===================================== The LPM6 (LPM for IPv6) library component implements the Longest Prefix Match (LPM) table search method for 128-bit keys that is typically used to find the best match route in IPv6 forwarding applications. diff --git a/doc/guides/prog_guide/lpm_lib.rst b/doc/guides/prog_guide/lpm_lib.rst index 03945904b3..191fb8d81b 100644 --- a/doc/guides/prog_guide/lpm_lib.rst +++ b/doc/guides/prog_guide/lpm_lib.rst @@ -3,8 +3,8 @@ .. _LPM_Library: -LPM Library -=========== +Longest Prefix Match (LPM) Library +================================== The DPDK LPM library component implements the Longest Prefix Match (LPM) table search method for 32-bit keys that is typically used to find the best route match in IP forwarding applications. diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst index 049357c755..50fbd99923 100644 --- a/doc/guides/prog_guide/mbuf_lib.rst +++ b/doc/guides/prog_guide/mbuf_lib.rst @@ -3,10 +3,10 @@ .. _Mbuf_Library: -Mbuf Library -============ +Packet (Mbuf) Library +===================== -The mbuf library provides the ability to allocate and free buffers (mbufs) +The Packet (MBuf) library provides the ability to allocate and free buffers (mbufs) that may be used by the DPDK application to store message buffers. The message buffers are stored in a mempool, using the :ref:`Mempool Library <Mempool_Library>`. diff --git a/doc/guides/prog_guide/mempool_lib.rst b/doc/guides/prog_guide/mempool_lib.rst index 4db577fe18..8769505d5d 100644 --- a/doc/guides/prog_guide/mempool_lib.rst +++ b/doc/guides/prog_guide/mempool_lib.rst @@ -3,8 +3,8 @@ .. _Mempool_Library: -Mempool Library -=============== +Memory Pool Library +=================== A memory pool is an allocator of a fixed-sized object. In the DPDK, it is identified by name and uses a mempool handler to store free objects. diff --git a/doc/guides/prog_guide/mldev.rst b/doc/guides/prog_guide/mldev.rst index 102fbda71c..f9109a6a22 100644 --- a/doc/guides/prog_guide/mldev.rst +++ b/doc/guides/prog_guide/mldev.rst @@ -1,10 +1,10 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2022 Marvell. -Machine Learning Device Library -=============================== +Machine Learning (ML) Device Library +=========================================== -The MLDEV library provides a Machine Learning device framework for the management and +The Machine Learning (ML) Device library provides a Machine Learning device framework for the management and provisioning of hardware and software ML poll mode drivers, defining an API which support a number of ML operations including device handling and inference processing. diff --git a/doc/guides/prog_guide/packet_classif_access_ctrl.rst b/doc/guides/prog_guide/packet_classif_access_ctrl.rst index 1811db4618..c8844d0616 100644 --- a/doc/guides/prog_guide/packet_classif_access_ctrl.rst +++ b/doc/guides/prog_guide/packet_classif_access_ctrl.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2015 Intel Corporation. -Packet Classification and Access Control -======================================== +Packet Classification and Access Control (ACL) Library +====================================================== The DPDK provides an Access Control library that gives the ability to classify an input packet based on a set of classification rules. diff --git a/doc/guides/prog_guide/packet_framework.rst b/doc/guides/prog_guide/packet_framework.rst index ebc69d8c3e..9b8896aa74 100644 --- a/doc/guides/prog_guide/packet_framework.rst +++ b/doc/guides/prog_guide/packet_framework.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -Packet Framework -================ +Packet Framework Library +======================== Design Objectives ----------------- diff --git a/doc/guides/prog_guide/rawdev.rst b/doc/guides/prog_guide/rawdev.rst index 488e0a7ef6..f8aa3856d7 100644 --- a/doc/guides/prog_guide/rawdev.rst +++ b/doc/guides/prog_guide/rawdev.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright 2018 NXP -Rawdevice Library -================= +Raw Device Library +================== Introduction ------------ diff --git a/doc/guides/prog_guide/regexdev.rst b/doc/guides/prog_guide/regexdev.rst index 93229fa743..3bf3b154b4 100644 --- a/doc/guides/prog_guide/regexdev.rst +++ b/doc/guides/prog_guide/regexdev.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright 2020 Mellanox Technologies, Ltd -RegEx Device Library -==================== +Regular Expression (RegEx) Device Library +========================================= The RegEx library provides a RegEx device framework for management and provisioning of hardware and software RegEx poll mode drivers, defining generic diff --git a/doc/guides/prog_guide/rib_lib.rst b/doc/guides/prog_guide/rib_lib.rst index 53ca3518a0..40b7de3f1d 100644 --- a/doc/guides/prog_guide/rib_lib.rst +++ b/doc/guides/prog_guide/rib_lib.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2021 Intel Corporation. -RIB Library -=========== +Routing Information Base (RIB) Library +====================================== The Routing Information Base (RIB) library provides a data store for routing information. This library is intended for use in control or management plane applications. diff --git a/doc/guides/prog_guide/thread_safety_dpdk_functions.rst b/doc/guides/prog_guide/thread_safety.rst similarity index 98% rename from doc/guides/prog_guide/thread_safety_dpdk_functions.rst rename to doc/guides/prog_guide/thread_safety.rst index 5618e25e47..f7cda8bb32 100644 --- a/doc/guides/prog_guide/thread_safety_dpdk_functions.rst +++ b/doc/guides/prog_guide/thread_safety.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -Thread Safety of DPDK Functions -=============================== +Thread Safety +============= The DPDK is comprised of several libraries. Some of the functions in these libraries can be safely called from multiple threads simultaneously, while others cannot. -- 2.41.0.windows.1 </blockquote></div>