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 <dave@youngcopy.com> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
DPDK · Sep 3, 2024 · 41dd9a6 · 41dd9a6
1 parent cb9187b
commit 41dd9a6
Show file tree

Hide file tree

Showing 54 changed files with 270 additions and 209 deletions.
diff --git 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
@@ -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 <testpmd_rte_flow>`

diff --git 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
@@ -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 <extconf>`.
 
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <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 <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 <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 → doc/guides/prog_guide/ethdev/ethdev.rst b/doc/guides/prog_guide/poll_mode_drv.rst → 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 <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
-<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 <Mbuf_Library>` chapter.
+See :doc:`../mbuf_lib` chapter for more details.
 
 Ethernet Device API
 ~~~~~~~~~~~~~~~~~~~

diff --git a/doc/guides/prog_guide/rte_flow.rst → ...guides/prog_guide/ethdev/flow_offload.rst b/doc/guides/prog_guide/rte_flow.rst → ...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
@@ -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