From 41dd9a6bc2d9c6e20e139ad713cc9d172572dd43 Mon Sep 17 00:00:00 2001 From: David Young Date: Thu, 7 Dec 2023 21:11:08 -0500 Subject: [PATCH] doc: reorganize prog guide Create categories in the index of the programmer's guide, sort chapters and rewrite some titles for consistency. Subdirectories are created for ethdev and eventdev for grouping the files together. Useless link anchors at the beginning of files are removed, the corresponding :ref: are replaced with :doc: links. Signed-off-by: David Young Signed-off-by: Thomas Monjalon --- doc/guides/howto/flow_bifurcation.rst | 2 +- doc/guides/howto/rte_flow.rst | 2 +- doc/guides/nics/dpaa2.rst | 4 +- doc/guides/nics/mvpp2.rst | 8 +- doc/guides/nics/txgbe.rst | 4 +- doc/guides/prog_guide/bpf_lib.rst | 4 +- doc/guides/prog_guide/build_app.rst | 2 - doc/guides/prog_guide/dmadev.rst | 4 +- doc/guides/prog_guide/efd_lib.rst | 6 +- .../prog_guide/env_abstraction_layer.rst | 14 +- .../{poll_mode_drv.rst => ethdev/ethdev.rst} | 9 +- .../{rte_flow.rst => ethdev/flow_offload.rst} | 8 +- doc/guides/prog_guide/ethdev/index.rst | 15 ++ .../prog_guide/{ => ethdev}/qos_framework.rst | 36 ++-- .../{ => ethdev}/switch_representation.rst | 6 +- .../{ => ethdev}/traffic_management.rst | 0 .../traffic_metering_and_policing.rst | 2 +- .../{ => eventdev}/dispatcher_lib.rst | 4 +- .../{ => eventdev}/event_crypto_adapter.rst | 8 +- .../{ => eventdev}/event_dma_adapter.rst | 8 +- .../event_ethernet_rx_adapter.rst | 0 .../event_ethernet_tx_adapter.rst | 0 .../{ => eventdev}/event_timer_adapter.rst | 3 +- .../prog_guide/{ => eventdev}/eventdev.rst | 2 +- doc/guides/prog_guide/eventdev/index.rst | 16 ++ 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/hash_lib.rst | 6 +- doc/guides/prog_guide/index.rst | 175 +++++++++++++----- doc/guides/prog_guide/lpm6_lib.rst | 4 +- doc/guides/prog_guide/lpm_lib.rst | 8 +- doc/guides/prog_guide/mbuf_lib.rst | 16 +- doc/guides/prog_guide/member_lib.rst | 2 - doc/guides/prog_guide/mempool_lib.rst | 13 +- doc/guides/prog_guide/metrics_lib.rst | 2 - doc/guides/prog_guide/mldev.rst | 6 +- doc/guides/prog_guide/multi_proc_support.rst | 2 - doc/guides/prog_guide/overview.rst | 16 +- .../prog_guide/packet_classif_access_ctrl.rst | 4 +- doc/guides/prog_guide/packet_framework.rst | 4 +- doc/guides/prog_guide/perf_opt_guidelines.rst | 2 - doc/guides/prog_guide/rawdev.rst | 4 +- doc/guides/prog_guide/rcu_lib.rst | 6 +- doc/guides/prog_guide/regexdev.rst | 4 +- doc/guides/prog_guide/reorder_lib.rst | 2 - doc/guides/prog_guide/rib_lib.rst | 4 +- doc/guides/prog_guide/ring_lib.rst | 2 - doc/guides/prog_guide/rte_security.rst | 2 - ...y_dpdk_functions.rst => thread_safety.rst} | 4 +- doc/guides/prog_guide/timer_lib.rst | 2 - .../prog_guide/writing_efficient_code.rst | 2 +- doc/guides/rel_notes/release_17_02.rst | 4 +- 54 files changed, 270 insertions(+), 209 deletions(-) rename doc/guides/prog_guide/{poll_mode_drv.rst => ethdev/ethdev.rst} (99%) rename doc/guides/prog_guide/{rte_flow.rst => ethdev/flow_offload.rst} (99%) create mode 100644 doc/guides/prog_guide/ethdev/index.rst rename doc/guides/prog_guide/{ => ethdev}/qos_framework.rst (99%) rename doc/guides/prog_guide/{ => ethdev}/switch_representation.rst (99%) rename doc/guides/prog_guide/{ => ethdev}/traffic_management.rst (100%) rename doc/guides/prog_guide/{ => ethdev}/traffic_metering_and_policing.rst (99%) rename doc/guides/prog_guide/{ => eventdev}/dispatcher_lib.rst (99%) rename doc/guides/prog_guide/{ => eventdev}/event_crypto_adapter.rst (98%) rename doc/guides/prog_guide/{ => eventdev}/event_dma_adapter.rst (97%) 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 (99%) 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/howto/flow_bifurcation.rst b/doc/guides/howto/flow_bifurcation.rst index 554dd24c32c..5d2127bc31e 100644 --- a/doc/guides/howto/flow_bifurcation.rst +++ b/doc/guides/howto/flow_bifurcation.rst @@ -58,7 +58,7 @@ the :ref:`flow_isolated_mode` must be configured, so there is no default rule routing traffic to userspace. There is no specific instructions to follow. -The recommended reading is the :doc:`../prog_guide/rte_flow` guide. +The recommended reading is the :doc:`../prog_guide/ethdev/flow_offload` guide. Below is an example of testpmd commands for receiving VXLAN 42 in 4 queues of the DPDK port 0, while all other packets go to the kernel: diff --git a/doc/guides/howto/rte_flow.rst b/doc/guides/howto/rte_flow.rst index 27d4f28f773..7852b6e509a 100644 --- a/doc/guides/howto/rte_flow.rst +++ b/doc/guides/howto/rte_flow.rst @@ -8,7 +8,7 @@ This document demonstrates some concrete examples for programming flow rules with the ``rte_flow`` APIs. * Detail of the rte_flow APIs can be found in the following link: - :doc:`../prog_guide/rte_flow`. + :doc:`../prog_guide/ethdev/flow_offload`. * Details of the TestPMD commands to set the flow rules can be found in the following link: :ref:`TestPMD Flow rules ` diff --git a/doc/guides/nics/dpaa2.rst b/doc/guides/nics/dpaa2.rst index c0d3e7a178d..3175a8b4218 100644 --- a/doc/guides/nics/dpaa2.rst +++ b/doc/guides/nics/dpaa2.rst @@ -582,7 +582,7 @@ of configured tx queues. After hierarchy is complete it can be committed. -For an additional description please refer to DPDK :doc:`Traffic Management API <../prog_guide/traffic_management>`. +For an additional description please refer to DPDK :doc:`../prog_guide/ethdev/traffic_management`. Supported Features ~~~~~~~~~~~~~~~~~~ @@ -601,7 +601,7 @@ The following capabilities are supported: Usage example ~~~~~~~~~~~~~ -For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`. +For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`../testpmd_app_ug/testpmd_funcs`. #. Run testpmd as follows: diff --git a/doc/guides/nics/mvpp2.rst b/doc/guides/nics/mvpp2.rst index e3d4b6a479a..4e42abd70ec 100644 --- a/doc/guides/nics/mvpp2.rst +++ b/doc/guides/nics/mvpp2.rst @@ -403,7 +403,7 @@ can be configured via generic flow API offered by DPDK. The :ref:`flow_isolated_mode` is supported. -For an additional description please refer to DPDK :doc:`../prog_guide/rte_flow`. +For an additional description please refer to DPDK :doc:`../prog_guide/ethdev/flow_offload`. Supported flow actions ~~~~~~~~~~~~~~~~~~~~~~ @@ -578,7 +578,7 @@ MVPP2 PMD supports DPDK traffic metering and policing that allows the following: #. Gather statistics. -For an additional description please refer to DPDK :doc:`Traffic Metering and Policing API <../prog_guide/traffic_metering_and_policing>`. +For an additional description please refer to DPDK :doc:`../prog_guide/ethdev/traffic_metering_and_policing`. The policer objects defined by this feature can work with the default policer defined via config file as described in :ref:`QoS Support `. @@ -658,7 +658,7 @@ of configured tx queues. After hierarchy is complete it can be committed. -For an additional description please refer to DPDK :doc:`Traffic Management API <../prog_guide/traffic_management>`. +For an additional description please refer to DPDK :doc:`../prog_guide/ethdev/traffic_management`. Limitations ~~~~~~~~~~~ @@ -674,7 +674,7 @@ The following capabilities are not supported: Usage example ~~~~~~~~~~~~~ -For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`. +For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`../testpmd_app_ug/testpmd_funcs`. #. Run testpmd as follows: diff --git a/doc/guides/nics/txgbe.rst b/doc/guides/nics/txgbe.rst index c09cc3923f5..e55b0e643a6 100644 --- a/doc/guides/nics/txgbe.rst +++ b/doc/guides/nics/txgbe.rst @@ -166,7 +166,7 @@ For example, create a flow rule: testpmd> flow create 0 ingress pattern eth type is 0x0806 / end actions queue index 2 / end -For a detailed usage description please refer to "Flow rules management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`. +For a detailed usage description please refer to "Flow rules management" section in DPDK :doc:`../testpmd_app_ug/testpmd_funcs`. Traffic Management API ~~~~~~~~~~~~~~~~~~~~~~ @@ -181,7 +181,7 @@ For example, add shaper profile testpmd> add port tm node shaper profile 0 0 0 0 25000000 0 0 -For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`Testpmd Runtime Functions <../testpmd_app_ug/testpmd_funcs>`. +For a detailed usage description please refer to "Traffic Management" section in DPDK :doc:`../testpmd_app_ug/testpmd_funcs`. Limitations or Known issues --------------------------- diff --git a/doc/guides/prog_guide/bpf_lib.rst b/doc/guides/prog_guide/bpf_lib.rst index 1cf2d59429e..8c820328b98 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/build_app.rst b/doc/guides/prog_guide/build_app.rst index 84196a8e03f..855897c5aa4 100644 --- a/doc/guides/prog_guide/build_app.rst +++ b/doc/guides/prog_guide/build_app.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _Building_Your_Own_Application: - Building Your Own Application ============================= diff --git a/doc/guides/prog_guide/dmadev.rst b/doc/guides/prog_guide/dmadev.rst index 2aa26d33b83..67a62ff4202 100644 --- a/doc/guides/prog_guide/dmadev.rst +++ b/doc/guides/prog_guide/dmadev.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright 2021 HiSilicon Limited -DMA Device Library -================== +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 2b355ff2a64..68404d5f33b 100644 --- a/doc/guides/prog_guide/efd_lib.rst +++ b/doc/guides/prog_guide/efd_lib.rst @@ -1,10 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2016-2017 Intel Corporation. -.. _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 9559c12a98f..b9fac1839d6 100644 --- a/doc/guides/prog_guide/env_abstraction_layer.rst +++ b/doc/guides/prog_guide/env_abstraction_layer.rst @@ -1,10 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _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. @@ -39,7 +37,7 @@ EAL in a Linux-userland Execution Environment In a Linux user space environment, the DPDK application runs as a user-space application using the pthread library. The EAL performs physical memory allocation using mmap() in hugetlbfs (using huge page sizes to increase performance). -This memory is exposed to DPDK service layers such as the :ref:`Mempool Library `. +This memory is exposed to DPDK service layers such as the :doc:`mempool_lib`. At this point, the DPDK services layer will be initialized, then through pthread setaffinity calls, each execution unit will be assigned to a specific logical core to run as a user-level thread. @@ -80,8 +78,7 @@ Multi-process Support ~~~~~~~~~~~~~~~~~~~~~ The Linux EAL allows a multi-process as well as a multi-threaded (pthread) deployment model. -See chapter -:ref:`Multi-process Support ` for more details. +See chapter :doc:`multi_proc_support` for more details. Memory Mapping Discovery and Memory Reservation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -154,8 +151,7 @@ of memory that can be used by DPDK application. and IPC must not be mixed: it is not safe to allocate/free memory inside memory-related or IPC callbacks, and it is not safe to use IPC inside memory-related callbacks. See chapter - :ref:`Multi-process Support ` for more details about - DPDK IPC. + :doc:`multi_proc_support` for more details about DPDK IPC. Legacy Memory Mode ^^^^^^^^^^^^^^^^^^ diff --git a/doc/guides/prog_guide/poll_mode_drv.rst b/doc/guides/prog_guide/ethdev/ethdev.rst similarity index 99% rename from doc/guides/prog_guide/poll_mode_drv.rst rename to doc/guides/prog_guide/ethdev/ethdev.rst index 5008b41c609..89eb31a48d4 100644 --- a/doc/guides/prog_guide/poll_mode_drv.rst +++ b/doc/guides/prog_guide/ethdev/ethdev.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2015 Intel Corporation. -.. _Poll_Mode_Driver: - Poll Mode Driver ================ @@ -65,7 +63,7 @@ a private buffer pool in local memory to minimize remote memory access. The configuration of packet buffer pools should take into account the underlying physical memory architecture in terms of DIMMS, channels and ranks. The application must ensure that appropriate parameters are given at memory pool creation time. -See :ref:`Mempool Library `. +See :doc:`../mempool_lib`. Design Principles ----------------- @@ -294,8 +292,7 @@ The support of these offload features implies the addition of dedicated status bit(s) and value field(s) into the rte_mbuf data structure, along with their appropriate handling by the receive/transmit functions exported by each PMD. The list of flags and their precise meaning is -described in the mbuf API documentation and in the in :ref:`Mbuf Library -`, section "Meta Information". +described in the mbuf API documentation and in the :ref:`mbuf_meta` chapter. Per-Port and Per-Queue Offloads ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -357,7 +354,7 @@ The rte_mbuf data structure includes specific fields to represent, in a generic For an input packet, most fields of the rte_mbuf structure are filled in by the PMD receive function with the information contained in the receive descriptor. Conversely, for output packets, most fields of rte_mbuf structures are used by the PMD transmit function to initialize transmit descriptors. -The mbuf structure is fully described in the :ref:`Mbuf Library ` chapter. +See :doc:`../mbuf_lib` chapter for more details. Ethernet Device API ~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/ethdev/flow_offload.rst similarity index 99% rename from doc/guides/prog_guide/rte_flow.rst rename to doc/guides/prog_guide/ethdev/flow_offload.rst index dad588763fe..3f6255c1a49 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/ethdev/flow_offload.rst @@ -2,8 +2,8 @@ Copyright 2016 6WIND S.A. Copyright 2016 Mellanox Technologies, Ltd -Generic flow API (rte_flow) -=========================== +Generic flow API +================ Overview -------- @@ -4105,13 +4105,13 @@ The asynchronous flow rule insertion logic can be broken into two phases. .. _figure_rte_flow_async_init: - .. figure:: img/rte_flow_async_init.* + .. figure:: ../img/rte_flow_async_init.* #. Main loop as presented on a datapath application example: .. _figure_rte_flow_async_usage: - .. figure:: img/rte_flow_async_usage.* + .. figure:: ../img/rte_flow_async_usage.* Enqueue creation operation ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/prog_guide/ethdev/index.rst b/doc/guides/prog_guide/ethdev/index.rst new file mode 100644 index 00000000000..392ced0a2ef --- /dev/null +++ b/doc/guides/prog_guide/ethdev/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2024 The DPDK contributors + +Ethernet Device Library +======================= + +.. toctree:: + :maxdepth: 1 + + ethdev + switch_representation + flow_offload + traffic_metering_and_policing + traffic_management + qos_framework diff --git a/doc/guides/prog_guide/qos_framework.rst b/doc/guides/prog_guide/ethdev/qos_framework.rst similarity index 99% rename from doc/guides/prog_guide/qos_framework.rst rename to doc/guides/prog_guide/ethdev/qos_framework.rst index 22616117cbd..1144037dfa2 100644 --- a/doc/guides/prog_guide/qos_framework.rst +++ b/doc/guides/prog_guide/ethdev/qos_framework.rst @@ -13,7 +13,7 @@ An example of a complex packet processing pipeline with QoS support is shown in .. _figure_pkt_proc_pipeline_qos: -.. figure:: img/pkt_proc_pipeline_qos.* +.. figure:: ../img/pkt_proc_pipeline_qos.* Complex Packet Processing Pipeline with QoS Support @@ -114,7 +114,7 @@ these packets are later on removed and handed over to the NIC TX with the packet .. _figure_hier_sched_blk: -.. figure:: img/hier_sched_blk.* +.. figure:: ../img/hier_sched_blk.* Hierarchical Scheduler Block Internal Diagram @@ -137,7 +137,7 @@ Each queue hosts packets from one or multiple connections of the same type belon .. _figure_sched_hier_per_port: -.. figure:: img/sched_hier_per_port.* +.. figure:: ../img/sched_hier_per_port.* Scheduling Hierarchy per Port @@ -271,7 +271,7 @@ A schematic of the internal data structures in shown in with details in. .. _figure_data_struct_per_port: -.. figure:: img/data_struct_per_port.* +.. figure:: ../img/data_struct_per_port.* Internal Data Structures per Port @@ -414,7 +414,7 @@ No input packet can be part of more than one pipeline stage at a given time. .. _figure_prefetch_pipeline: -.. figure:: img/prefetch_pipeline.* +.. figure:: ../img/prefetch_pipeline.* Prefetch Pipeline for the Hierarchical Scheduler Enqueue Operation @@ -454,7 +454,7 @@ moving to the next active TC from the same pipe (if any) or to another active pi .. _figure_pipe_prefetch_sm: -.. figure:: img/pipe_prefetch_sm.* +.. figure:: ../img/pipe_prefetch_sm.* Pipe Prefetch State Machine for the Hierarchical Scheduler Dequeue Operation @@ -1170,7 +1170,7 @@ so the dropper provides the only method for congestion avoidance. .. _figure_blk_diag_dropper: -.. figure:: img/blk_diag_dropper.* +.. figure:: ../img/blk_diag_dropper.* High-level Block Diagram of the DPDK Dropper @@ -1201,7 +1201,7 @@ The RED/WRED/PIE algorithm is exercised first and tail drop second. .. _figure_flow_tru_dropper: -.. figure:: img/flow_tru_dropper.* +.. figure:: ../img/flow_tru_dropper.* Flow Through the Dropper @@ -1308,7 +1308,7 @@ decision is the output value and the remaining values are configuration paramete .. _figure_ex_data_flow_tru_dropper: -.. figure:: img/ex_data_flow_tru_dropper.* +.. figure:: ../img/ex_data_flow_tru_dropper.* Example Data Flow Through Dropper @@ -1329,7 +1329,7 @@ Average Queue Size Calculation when the Queue is not Empty The definition of the EWMA filter is given in the following equation. -.. image:: img/ewma_filter_eq_1.* +.. image:: ../img/ewma_filter_eq_1.* Where: @@ -1353,7 +1353,7 @@ When the queue becomes empty, average queue size should decay gradually to zero or remaining stagnant at the last computed value. When a packet is enqueued on an empty queue, the average queue size is computed using the following formula: -.. image:: img/ewma_filter_eq_2.* +.. image:: ../img/ewma_filter_eq_2.* Where: @@ -1361,7 +1361,7 @@ Where: In the dropper module, *m* is defined as: -.. image:: img/m_definition.* +.. image:: ../img/m_definition.* Where: @@ -1395,12 +1395,12 @@ A numerical method is used to compute the factor (1-wq)^m that appears in Equati This method is based on the following identity: -.. image:: img/eq2_factor.* +.. image:: ../img/eq2_factor.* This allows us to express the following: -.. image:: img/eq2_expression.* +.. image:: ../img/eq2_expression.* In the dropper module, a look-up table is used to compute log2(1-wq) for each value of wq supported by the dropper module. @@ -1484,7 +1484,7 @@ Initial Packet Drop Probability The initial drop probability is calculated using the following equation. -.. image:: img/drop_probability_eq3.* +.. image:: ../img/drop_probability_eq3.* Where: @@ -1504,7 +1504,7 @@ a drop probability is calculated to determine if the packet should be enqueued o .. _figure_pkt_drop_probability: -.. figure:: img/pkt_drop_probability.* +.. figure:: ../img/pkt_drop_probability.* Packet Drop Probability for a Given RED Configuration @@ -1515,7 +1515,7 @@ Actual Drop Probability If the average queue size is between the minimum and maximum thresholds, then the actual drop probability is calculated from the following equation. -.. image:: img/drop_probability_eq4.* +.. image:: ../img/drop_probability_eq4.* Where: @@ -1540,7 +1540,7 @@ one that has been taken by other RED implementations, for example, FreeBSD* ALTQ .. _figure_drop_probability_graph: -.. figure:: img/drop_probability_graph.* +.. figure:: ../img/drop_probability_graph.* Initial Drop Probability (pb), Actual Drop probability (pa) Computed Using a Factor 1 (Blue Curve) and a Factor 2 (Red Curve) diff --git a/doc/guides/prog_guide/switch_representation.rst b/doc/guides/prog_guide/ethdev/switch_representation.rst similarity index 99% rename from doc/guides/prog_guide/switch_representation.rst rename to doc/guides/prog_guide/ethdev/switch_representation.rst index 46e0ca85a5c..2ef2772afbd 100644 --- a/doc/guides/prog_guide/switch_representation.rst +++ b/doc/guides/prog_guide/ethdev/switch_representation.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2018 6WIND S.A. -.. _switch_representation: - Switch Representation within DPDK Applications ============================================== @@ -373,9 +371,9 @@ and actions. Enhancing **rte_flow** with the ability to make flow rules match and target these endpoints provides a standard interface to manage their interconnection without introducing new concepts and whole new API to -implement them. This is described in `flow API (rte_flow)`_. +implement them. This is described in [6]_. -.. [6] :doc:`Generic flow API (rte_flow) ` +.. [6] :doc:`flow_offload` Flow API (rte_flow) ------------------- 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 99% rename from doc/guides/prog_guide/traffic_metering_and_policing.rst rename to doc/guides/prog_guide/ethdev/traffic_metering_and_policing.rst index 2e8f419f97c..7f9faf36e27 100644 --- a/doc/guides/prog_guide/traffic_metering_and_policing.rst +++ b/doc/guides/prog_guide/ethdev/traffic_metering_and_policing.rst @@ -72,7 +72,7 @@ API walk-through .. _figure_rte_mtr_chaining: -.. figure:: img/rte_mtr_meter_chaining.* +.. figure:: ../img/rte_mtr_meter_chaining.* Meter components diff --git a/doc/guides/prog_guide/dispatcher_lib.rst b/doc/guides/prog_guide/eventdev/dispatcher_lib.rst similarity index 99% rename from doc/guides/prog_guide/dispatcher_lib.rst rename to doc/guides/prog_guide/eventdev/dispatcher_lib.rst index f9998f45236..e8d645d4748 100644 --- a/doc/guides/prog_guide/dispatcher_lib.rst +++ b/doc/guides/prog_guide/eventdev/dispatcher_lib.rst @@ -124,7 +124,7 @@ which part of the system actually runs the dispatching mechanism? Or phrased differently, what is replacing the function hosting the shared conditional logic (typically launched on all lcores using ``rte_eal_remote_launch()``)? To solve this issue, the dispatcher is -run as a DPDK :doc:`Service `. +run as a DPDK :doc:`Service <../service_cores>`. The dispatcher is a layer between the application and the event device in the receive direction. In the transmit (i.e., item of work @@ -408,7 +408,7 @@ services, running on the dispatcher core set. An example of such a task would be the management of a per-lcore timer wheel (i.e., calling ``rte_timer_manage()``). -Applications employing :doc:`Read-Copy-Update (RCU) ` (or +Applications employing :doc:`../rcu_lib` (or similar technique) may opt for having quiescent state (e.g., calling ``rte_rcu_qsbr_quiescent()``) signaling factored out into a separate service, to assure resource reclaiming occurs even though some diff --git a/doc/guides/prog_guide/event_crypto_adapter.rst b/doc/guides/prog_guide/eventdev/event_crypto_adapter.rst similarity index 98% rename from doc/guides/prog_guide/event_crypto_adapter.rst rename to doc/guides/prog_guide/eventdev/event_crypto_adapter.rst index ef727654944..e2481904b1a 100644 --- a/doc/guides/prog_guide/event_crypto_adapter.rst +++ b/doc/guides/prog_guide/eventdev/event_crypto_adapter.rst @@ -6,7 +6,7 @@ Event Crypto Adapter Library The DPDK :doc:`Eventdev library ` provides event driven programming model with features to schedule events. -The :doc:`Cryptodev library ` provides an interface to +The :doc:`../cryptodev_lib` provides an interface to the crypto poll mode drivers which supports different crypto operations. The Event Crypto Adapter is one of the adapter which is intended to bridge between the event device and the crypto device. @@ -47,7 +47,7 @@ which is needed to enqueue an event after the crypto operation is completed. .. _figure_event_crypto_adapter_op_new: -.. figure:: img/event_crypto_adapter_op_new.* +.. figure:: ../img/event_crypto_adapter_op_new.* Working model of ``RTE_EVENT_CRYPTO_ADAPTER_OP_NEW`` mode @@ -74,7 +74,7 @@ completed. .. _figure_event_crypto_adapter_op_forward: -.. figure:: img/event_crypto_adapter_op_forward.* +.. figure:: ../img/event_crypto_adapter_op_forward.* Working model of ``RTE_EVENT_CRYPTO_ADAPTER_OP_FORWARD`` mode @@ -193,7 +193,7 @@ Adding queue pair to the adapter instance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Cryptodev device id and queue pair are created using cryptodev APIs. -For more information see :doc:`here `. +For more information see :doc:`here <../cryptodev_lib>`. .. code-block:: c diff --git a/doc/guides/prog_guide/event_dma_adapter.rst b/doc/guides/prog_guide/eventdev/event_dma_adapter.rst similarity index 97% rename from doc/guides/prog_guide/event_dma_adapter.rst rename to doc/guides/prog_guide/eventdev/event_dma_adapter.rst index 1fb9b0a07b8..e040d89e8b6 100644 --- a/doc/guides/prog_guide/event_dma_adapter.rst +++ b/doc/guides/prog_guide/eventdev/event_dma_adapter.rst @@ -6,7 +6,7 @@ Event DMA Adapter Library DPDK :doc:`eventdev library ` provides event driven programming model with features to schedule events. -:doc:`DMA device library ` provides an interface to DMA poll mode drivers +:doc:`../dmadev` provides an interface to DMA poll mode drivers that support DMA operations. Event DMA adapter is intended to bridge between the event device and the DMA device. @@ -47,7 +47,7 @@ which is needed to enqueue an event after the DMA operation is completed. .. _figure_event_dma_adapter_op_new: -.. figure:: img/event_dma_adapter_op_new.* +.. figure:: ../img/event_dma_adapter_op_new.* Working model of ``RTE_EVENT_DMA_ADAPTER_OP_NEW`` mode @@ -77,7 +77,7 @@ needed to enqueue the event after the DMA operation has completed. .. _figure_event_dma_adapter_op_forward: -.. figure:: img/event_dma_adapter_op_forward.* +.. figure:: ../img/event_dma_adapter_op_forward.* Working model of ``RTE_EVENT_DMA_ADAPTER_OP_FORWARD`` mode @@ -194,7 +194,7 @@ Adding vchan to the adapter instance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ dmadev device ID and vchan are configured using dmadev APIs. -For more information, see :doc:`dmadev `. +For more information, see :doc:`dmadev <../dmadev>`. .. code-block:: c 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 99% rename from doc/guides/prog_guide/event_timer_adapter.rst rename to doc/guides/prog_guide/eventdev/event_timer_adapter.rst index adeddbedfce..879105fa356 100644 --- a/doc/guides/prog_guide/event_timer_adapter.rst +++ b/doc/guides/prog_guide/eventdev/event_timer_adapter.rst @@ -19,8 +19,7 @@ destroyed, and :ref:`event timers ` can be armed and canceled. The Event Timer Adapter library is designed to interface with hardware or software implementations of the timer mechanism; it will query an eventdev PMD to determine which implementation should be used. The default software -implementation manages timers using the DPDK -:doc:`Timer library `. +implementation manages timers using the DPDK :doc:`../timer_lib`. Examples of using the API are presented in the `API Overview`_ and `Processing Timer Expiry Events`_ sections. Code samples are abstracted and 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 9d398d07f7f..fb6dfce102d 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 00000000000..2e1940ce760 --- /dev/null +++ b/doc/guides/prog_guide/eventdev/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2024 The DPDK contributors + +Event Device Library +==================== + +.. toctree:: + :maxdepth: 1 + + eventdev + event_ethernet_rx_adapter + event_ethernet_tx_adapter + event_timer_adapter + event_crypto_adapter + event_dma_adapter + dispatcher_lib diff --git a/doc/guides/prog_guide/fib_lib.rst b/doc/guides/prog_guide/fib_lib.rst index 970a433d345..a81da2d491b 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 6d176947e4c..f2b5ff9eed5 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 30d13bcc613..618297044b3 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 c6ae7191c80..de246d2a4c1 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/hash_lib.rst b/doc/guides/prog_guide/hash_lib.rst index 96bb121682b..fdbb99fd5e9 100644 --- a/doc/guides/prog_guide/hash_lib.rst +++ b/doc/guides/prog_guide/hash_lib.rst @@ -2,8 +2,6 @@ Copyright(c) 2010-2015 Intel Corporation. Copyright(c) 2018 Arm Limited. -.. _Hash_Library: - Hash Library ============ @@ -104,7 +102,7 @@ For concurrent writes, and concurrent reads and writes the following flag values Where required, the application can make use of RCU mechanisms to determine when the readers have stopped referencing the position. RCU QSBR process is integrated within the Hash library for safe freeing of the position. Application has certain responsibilities while using this feature. For example, rte_hash_rcu_qsbr_add() need to be called to use the integrated RCU mechanism. - Please refer to resource reclamation framework of :ref:`RCU library ` for more details. + Please refer to resource reclamation framework of :doc:`rcu_lib` for more details. Extendable Bucket Functionality support @@ -291,7 +289,7 @@ The flow table operations on the application side are described below: wait till the readers are not referencing the position returned during add/delete flow and then free the position. RCU mechanisms can be used to find out when the readers are not referencing the position anymore. RCU QSBR process is integrated within the Hash library for safe freeing of the position. Application has certain responsibilities while using this feature. - Please refer to resource reclamation framework of :ref:`RCU library ` for more details. + Please refer to resource reclamation framework of :doc:`rcu_lib` for more details. * Lookup flow: Lookup for the flow key in the hash. If the returned position is valid (flow lookup hit), use the returned position to access the flow entry in the flow table. diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 6366849eb0b..7eb1a98d88b 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -4,82 +4,155 @@ Programmer's Guide ================== +Foundation Principles +--------------------- + .. toctree:: - :maxdepth: 3 + :maxdepth: 1 :numbered: intro overview source_org - env_abstraction_layer - log_lib - argparse_lib - cmdline - service_cores - trace_lib - rcu_lib - ring_lib - stack_lib + glossary + + +Memory Management +----------------- + +.. toctree:: + :maxdepth: 1 + :numbered: + 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 + :numbered: + + env_abstraction_layer + power_man + thread_safety + service_cores + + +CPU Packet Processing +--------------------- + +.. toctree:: + :maxdepth: 1 + :numbered: + + toeplitz_hash_lib + hash_lib + member_lib + ip_fragment_reassembly_lib + generic_receive_offload_lib + generic_segmentation_offload_lib + packet_classif_access_ctrl + packet_distrib_lib + efd_lib + reorder_lib + lpm_lib + lpm6_lib + rib_lib + fib_lib + + +Device Libraries +---------------- + +.. toctree:: + :maxdepth: 1 + :numbered: + + ethdev/index + link_bonding_poll_mode_drv_lib + vhost_lib cryptodev_lib + rte_security compressdev regexdev + bbdev mldev dmadev gpudev - rte_security rawdev - link_bonding_poll_mode_drv_lib - 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 + eventdev/index + + +Protocol Processing Libraries +----------------------------- + +.. toctree:: + :maxdepth: 1 + :numbered: + 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 - event_dma_adapter - dispatcher_lib - qos_framework - power_man - packet_classif_access_ctrl + ipsec_lib + + +High-Level Libraries +-------------------- + +.. toctree:: + :maxdepth: 1 + :numbered: + packet_framework - vhost_lib + graph_lib + + +Utility Libraries +----------------- + +.. toctree:: + :maxdepth: 1 + :numbered: + + argparse_lib + cmdline + ptr_compress_lib + timer_lib + rcu_lib + ring_lib + stack_lib + log_lib metrics_lib telemetry_lib + pdump_lib + pcapng_lib bpf_lib - graph_lib - ptr_compress_lib + trace_lib + + +Howto Guides +------------- + +.. toctree:: + :maxdepth: 1 + :numbered: + build-sdk-meson meson_ut build_app + + +Tips & Tricks +------------- + +.. toctree:: + :maxdepth: 1 + :numbered: + 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 8425d148050..2c3eb108578 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 03945904b3e..316ac835a46 100644 --- a/doc/guides/prog_guide/lpm_lib.rst +++ b/doc/guides/prog_guide/lpm_lib.rst @@ -1,10 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _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. @@ -174,7 +172,7 @@ When the LPM is not using RCU, tbl8 group can be freed immediately even though t the tbl8 group entries. This might result in incorrect lookup results. RCU QSBR process is integrated for safe tbl8 group reclamation. Application has certain responsibilities -while using this feature. Please refer to resource reclamation framework of :ref:`RCU library ` +while using this feature. Please refer to resource reclamation framework of :doc:`rcu_lib` for more details. Lookup diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst index 749f9c97a88..4ad2a21f3fe 100644 --- a/doc/guides/prog_guide/mbuf_lib.rst +++ b/doc/guides/prog_guide/mbuf_lib.rst @@ -1,14 +1,12 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _Mbuf_Library: +Packet (Mbuf) Library +===================== -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 `. +The message buffers are stored in a mempool, using the :doc:`mempool_lib`. A rte_mbuf struct generally carries network packet buffers, but it can actually be any data (control data, events, ...). @@ -64,7 +62,7 @@ The Buffer Manager implements a fairly standard set of buffer access functions t Buffers Stored in Memory Pools ------------------------------ -The Buffer Manager uses the :ref:`Mempool Library ` to allocate buffers. +The Buffer Manager uses the :doc:`mempool_lib` to allocate buffers. Therefore, it ensures that the packet header is interleaved optimally across the channels and ranks for L3 processing. An mbuf contains a field indicating the pool that it originated from. When calling rte_pktmbuf_free(m), the mbuf returns to its original pool. @@ -107,11 +105,13 @@ This library provides some functions for manipulating the data in a packet mbuf. * Remove data at the end of the buffer (rte_pktmbuf_trim()) Refer to the *DPDK API Reference* for details. +.. _mbuf_meta: + Meta Information ---------------- Some information is retrieved by the network driver and stored in an mbuf to make processing easier. -For instance, the VLAN, the RSS hash result (see :ref:`Poll Mode Driver `) +For instance, the VLAN, the RSS hash result and a flag indicating that the checksum was computed by hardware. An mbuf also contains the input port (where it comes from), and the number of segment mbufs in the chain. diff --git a/doc/guides/prog_guide/member_lib.rst b/doc/guides/prog_guide/member_lib.rst index f0c1909904f..d2f76de35ce 100644 --- a/doc/guides/prog_guide/member_lib.rst +++ b/doc/guides/prog_guide/member_lib.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2017 Intel Corporation. -.. _member_library: - Membership Library ================== diff --git a/doc/guides/prog_guide/mempool_lib.rst b/doc/guides/prog_guide/mempool_lib.rst index 46aeb691137..7eead7b5898 100644 --- a/doc/guides/prog_guide/mempool_lib.rst +++ b/doc/guides/prog_guide/mempool_lib.rst @@ -1,10 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _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. @@ -12,7 +10,7 @@ The default mempool handler is ring based. It provides some other optional services such as a per-core object cache and an alignment helper to ensure that objects are padded to spread them equally on all DRAM or DDR3 channels. -This library is used by the :ref:`Mbuf Library `. +This library is used by the :doc:`mbuf_lib`. Cookies ------- @@ -164,8 +162,5 @@ Use Cases All allocations that require a high level of performance should use a pool-based memory allocator. Below are some examples: -* :ref:`Mbuf Library ` - -* :ref:`Environment Abstraction Layer ` , for logging service - +* :doc:`mbuf_lib` * Any application that needs to allocate fixed-sized objects in the data plane and that will be continuously utilized by the system. diff --git a/doc/guides/prog_guide/metrics_lib.rst b/doc/guides/prog_guide/metrics_lib.rst index f8416eaa027..98fc8947c67 100644 --- a/doc/guides/prog_guide/metrics_lib.rst +++ b/doc/guides/prog_guide/metrics_lib.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2017 Intel Corporation. -.. _Metrics_Library: - Metrics Library =============== diff --git a/doc/guides/prog_guide/mldev.rst b/doc/guides/prog_guide/mldev.rst index 102fbda71c6..61661b998b5 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/multi_proc_support.rst b/doc/guides/prog_guide/multi_proc_support.rst index df234548a70..0c571454709 100644 --- a/doc/guides/prog_guide/multi_proc_support.rst +++ b/doc/guides/prog_guide/multi_proc_support.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _Multi-process_Support: - Multi-process Support ===================== diff --git a/doc/guides/prog_guide/overview.rst b/doc/guides/prog_guide/overview.rst index a3b66033207..666c151b9dd 100644 --- a/doc/guides/prog_guide/overview.rst +++ b/doc/guides/prog_guide/overview.rst @@ -77,7 +77,7 @@ The services provided by the EAL are: * Memory management (malloc) -The EAL is fully described in :ref:`Environment Abstraction Layer `. +The EAL is fully described in :doc:`env_abstraction_layer`. Core Components --------------- @@ -97,11 +97,11 @@ Ring Manager (librte_ring) The ring structure provides a lockless multi-producer, multi-consumer FIFO API in a finite size table. It has some advantages over lockless queues; easier to implement, adapted to bulk operations and faster. -A ring is used by the :ref:`Memory Pool Manager (librte_mempool) ` +A ring is used by the :doc:`mempool_lib` and may be used as a general communication mechanism between cores and/or execution blocks connected together on a logical core. -This ring buffer and its usage are fully described in :ref:`Ring Library `. +This ring buffer and its usage are fully described in :doc:`ring_lib`. Memory Pool Manager (librte_mempool) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -111,7 +111,7 @@ A pool is identified by name and uses a ring to store free objects. It provides some other optional services, such as a per-core object cache and an alignment helper to ensure that objects are padded to spread them equally on all RAM channels. -This memory pool allocator is described in :ref:`Mempool Library `. +This memory pool allocator is described in :doc:`mempool_lib`. Network Packet Buffer Management (librte_mbuf) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -123,7 +123,7 @@ The message buffers are created at startup time and stored in a mempool, using t This library provides an API to allocate/free mbufs, manipulate packet buffers which are used to carry network packets. -Network Packet Buffer Management is described in :ref:`Mbuf Library `. +Network Packet Buffer Management is described in :doc:`mbuf_lib`. Timer Manager (librte_timer) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -134,7 +134,7 @@ It can be periodic function calls, or just a one-shot call. It uses the timer interface provided by the Environment Abstraction Layer (EAL) to get a precise time reference and can be initiated on a per-core basis as required. -The library documentation is available in :ref:`Timer Library `. +The library documentation is available in :doc:`timer_lib`. Ethernet* Poll Mode Driver Architecture --------------------------------------- @@ -142,15 +142,13 @@ Ethernet* Poll Mode Driver Architecture The DPDK includes Poll Mode Drivers (PMDs) for 1 GbE, 10 GbE and 40GbE, and para virtualized virtio Ethernet controllers which are designed to work without asynchronous, interrupt-based signaling mechanisms. -See :ref:`Poll Mode Driver `. - Packet Forwarding Algorithm Support ----------------------------------- The DPDK includes Hash (librte_hash) and Longest Prefix Match (LPM,librte_lpm) libraries to support the corresponding packet forwarding algorithms. -See :ref:`Hash Library ` and :ref:`LPM Library ` for more information. +See :doc:`hash_lib` and :doc:`lpm_lib` for more information. librte_net ---------- diff --git a/doc/guides/prog_guide/packet_classif_access_ctrl.rst b/doc/guides/prog_guide/packet_classif_access_ctrl.rst index 1811db46189..c8844d06162 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 9987ead6c5f..17010b07dcd 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/perf_opt_guidelines.rst b/doc/guides/prog_guide/perf_opt_guidelines.rst index 360009f2e42..b858f106a5e 100644 --- a/doc/guides/prog_guide/perf_opt_guidelines.rst +++ b/doc/guides/prog_guide/perf_opt_guidelines.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _Performance_Optimization: - Performance Optimization Guidelines =================================== diff --git a/doc/guides/prog_guide/rawdev.rst b/doc/guides/prog_guide/rawdev.rst index 07a2c4e73c0..036f8cc107a 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/rcu_lib.rst b/doc/guides/prog_guide/rcu_lib.rst index d0aef3bc165..9f3654f398d 100644 --- a/doc/guides/prog_guide/rcu_lib.rst +++ b/doc/guides/prog_guide/rcu_lib.rst @@ -1,10 +1,8 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2019 Arm Limited. -.. _RCU_Library: - -RCU Library -============ +Read-Copy-Update (RCU) Library +============================== Lockless data structures provide scalability and determinism. They enable use cases where locking may not be allowed diff --git a/doc/guides/prog_guide/regexdev.rst b/doc/guides/prog_guide/regexdev.rst index 93229fa7432..3bf3b154b4c 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/reorder_lib.rst b/doc/guides/prog_guide/reorder_lib.rst index 8e95e26451f..3fb5df55708 100644 --- a/doc/guides/prog_guide/reorder_lib.rst +++ b/doc/guides/prog_guide/reorder_lib.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2015 Intel Corporation. -.. _Reorder_Library: - Reorder Library ================= diff --git a/doc/guides/prog_guide/rib_lib.rst b/doc/guides/prog_guide/rib_lib.rst index 53ca3518a0c..40b7de3f1db 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/ring_lib.rst b/doc/guides/prog_guide/ring_lib.rst index 515a715266c..f7dbba0e4e4 100644 --- a/doc/guides/prog_guide/ring_lib.rst +++ b/doc/guides/prog_guide/ring_lib.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _Ring_Library: - Ring Library ============ diff --git a/doc/guides/prog_guide/rte_security.rst b/doc/guides/prog_guide/rte_security.rst index 4d45e401396..4992fe1161f 100644 --- a/doc/guides/prog_guide/rte_security.rst +++ b/doc/guides/prog_guide/rte_security.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright 2017,2020-2021 NXP - - Security Library ================ 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 5618e25e47f..f7cda8bb325 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. diff --git a/doc/guides/prog_guide/timer_lib.rst b/doc/guides/prog_guide/timer_lib.rst index 3af2c92e0ee..7e67a693334 100644 --- a/doc/guides/prog_guide/timer_lib.rst +++ b/doc/guides/prog_guide/timer_lib.rst @@ -1,8 +1,6 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _Timer_Library: - Timer Library ============= diff --git a/doc/guides/prog_guide/writing_efficient_code.rst b/doc/guides/prog_guide/writing_efficient_code.rst index e6c26efdd3a..b849f1db071 100644 --- a/doc/guides/prog_guide/writing_efficient_code.rst +++ b/doc/guides/prog_guide/writing_efficient_code.rst @@ -76,7 +76,7 @@ the number of channels and the way the memory is distributed across the channels Each channel has a bandwidth limit, meaning that if all memory access operations are done on the first channel only, there is a potential bottleneck. -By default, the :ref:`Mempool Library ` spreads the addresses of objects among memory channels. +By default, the :doc:`mempool_lib` spreads the addresses of objects among memory channels. Locking memory pages ~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/rel_notes/release_17_02.rst b/doc/guides/rel_notes/release_17_02.rst index 753ef8a4088..929ba770ae7 100644 --- a/doc/guides/rel_notes/release_17_02.rst +++ b/doc/guides/rel_notes/release_17_02.rst @@ -43,7 +43,7 @@ New Features higher-level than the legacy filtering framework, which it encompasses and supersedes (including all functions and filter types) . - See the :doc:`../prog_guide/rte_flow` documentation for more information. + See the :doc:`../prog_guide/ethdev/flow_offload` documentation for more information. * **Added firmware version get API.** @@ -215,7 +215,7 @@ New Features therefore, it can better fit in CPU cache and scale to millions of flow keys. - See the :ref:`Elastic Flow Distributor Library ` documentation in + See the :doc:`../prog_guide/efd_lib` documentation in the Programmers Guide document, for more information.