[RFC] doc: updating doxy-api-index.md and doxy-api.conf.in

[RFC] doc: updating doxy-api-index.md and doxy-api.conf.in

[Marat Khalili]

I noticed that a few header files contain docstring-like comments but are not
present in doc/api/doxy-api-index.md and/or (fewer) in doc/api/doxy-api.conf.in
There seem to be no checks anywhere in the process that would make sure these
index files are updated. Do we even care, or is it unsupported legacy? If we do
care, would a check or an automatic generation fix be more promising?

With Best Regards,
Marat

Re: [RFC] doc: updating doxy-api-index.md and doxy-api.conf.in

[Thomas Monjalon]

Hello,

30/06/2026 11:03, Marat Khalili:
> I noticed that a few header files contain docstring-like comments but are not
> present in doc/api/doxy-api-index.md and/or (fewer) in doc/api/doxy-api.conf.in
> There seem to be no checks anywhere in the process that would make sure these
> index files are updated. Do we even care, or is it unsupported legacy? If we do
> care, would a check or an automatic generation fix be more promising?

Some internal files have doxygen comments, not sure why,
probably to run Doxygen manually on these files.

In the scope of our public documentation,
the goal was to document all and only public API.

If you see some public API not referenced, it is a bug.
And yes a script to check this may be useful.

Re: [RFC] doc: updating doxy-api-index.md and doxy-api.conf.in

[Bruce Richardson]

On Tue, Jun 30, 2026 at 06:10:59PM +0200, Thomas Monjalon wrote:
> Hello,
> 
> 30/06/2026 11:03, Marat Khalili:
> > I noticed that a few header files contain docstring-like comments but are not
> > present in doc/api/doxy-api-index.md and/or (fewer) in doc/api/doxy-api.conf.in
> > There seem to be no checks anywhere in the process that would make sure these
> > index files are updated. Do we even care, or is it unsupported legacy? If we do
> > care, would a check or an automatic generation fix be more promising?
> 
> Some internal files have doxygen comments, not sure why,
> probably to run Doxygen manually on these files.
> 
> In the scope of our public documentation,
> the goal was to document all and only public API.
> 
> If you see some public API not referenced, it is a bug.
> And yes a script to check this may be useful.
> 
Something like this could work as a quick check that all public headers are
getting indexed. Doesn't help with verifying that all contents within the
files have comments, but maybe its an easy start point:

diff --git a/drivers/meson.build b/drivers/meson.build
index 4d95604ecd..5a9ba68d54 100644
--- a/drivers/meson.build
+++ b/drivers/meson.build
@@ -278,6 +278,23 @@ foreach subpath:subdirs
         dpdk_headers += headers
         dpdk_drivers_headers += driver_sdk_headers
 
+        # On Linux, best-effort check that public headers are named correctly
+        # and that the driver directory is referenced in the Doxygen config so
+        # that its API gets indexed.
+        if is_linux and meson.version().version_compare('>= 0.59.0') and headers.length() > 0
+            foreach h:headers
+                hname = fs.name(h)
+                if not hname.startswith('rte_')
+                    warning('drivers/@0@: public header "@1@" does not start with "rte_"'.format(drv_path, hname))
+                endif
+            endforeach
+            if run_command('grep', '-qF', '@TOPDIR@/drivers/' + drv_path,
+                    dpdk_source_root / 'doc' / 'api' / 'doxy-api.conf.in',
+                    check: false).returncode() != 0
+                warning('drivers/@0@: has public headers but not listed in doxy-api.conf.in'.format(drv_path))
+            endif
+        endif
+
         if headers.length() > 0
             dpdk_includes += include_directories(drv_path)
         endif
diff --git a/lib/meson.build b/lib/meson.build
index af5c160cb8..d897b2c73a 100644
--- a/lib/meson.build
+++ b/lib/meson.build
@@ -209,6 +209,23 @@ foreach l:libraries
     dpdk_indirect_headers += indirect_headers
     dpdk_drivers_headers += driver_sdk_headers
 
+    # On Linux, best-effort check that public headers are named correctly
+    # and that the library directory is referenced in the Doxygen config so
+    # that its API gets indexed.
+    if is_linux and meson.version().version_compare('>= 0.59.0') and headers.length() > 0
+        foreach h:headers
+            hname = fs.name(h)
+            if not (hname.startswith('rte_') or hname.startswith('cmdline'))
+                warning('lib/@0@: public header "@1@" does not start with "rte_" or "cmdline"'.format(l, hname))
+            endif
+        endforeach
+        if run_command('grep', '-qF', '@TOPDIR@/lib/' + l,
+                dpdk_source_root / 'doc' / 'api' / 'doxy-api.conf.in',
+                check: false).returncode() != 0
+            warning('lib/@0@: has public headers but not listed in doxy-api.conf.in'.format(l))
+        endif
+    endif
+
     libname = 'rte_' + name
     includes += include_directories(l)
     dpdk_includes += include_directories(l)

[PATCH 0/7] doc: build for all public headers

[Marat Khalili]

It was noticed that not all public headers were included in the doxygen
build, and once built not all files were listed in the index file
serving as a point of entry for the HTML version.

Bruce Richardson provided an idea and a draft implementation of the
configuration-time check, which I optimized to avoid repeat grep calls
and expanded to include indexing check.

After all drivers and public headers were included, multiple small
problems have surfaced fixes for which (with one exception covered by
bug 1962) are also included in this patch set.

Marat Khalili (7):
  doc: detect ignored public headers
  doc: document rte_os.h
  doc: fix typos in rte_bus_pci.h
  doc: fix typos in rte_bus_vmbus.h
  doc: add missing globs to doxy-api.conf.in
  doc: add missing drivers to doxy-api.conf.in
  doc: add missing headers to doxy-api-index.md

 doc/api/doxy-api-index.md         | 116 ++++++++++++++++++++++++++----
 doc/api/doxy-api.conf.in          |  17 ++++-
 drivers/bus/pci/rte_bus_pci.h     |   4 +-
 drivers/bus/vmbus/rte_bus_vmbus.h |  33 +++++----
 drivers/meson.build               |  17 +++++
 lib/eal/include/generic/rte_os.h  |  13 ++++
 lib/meson.build                   |  23 ++++++
 meson.build                       |  19 +++++
 8 files changed, 211 insertions(+), 31 deletions(-)
 create mode 100644 lib/eal/include/generic/rte_os.h

-- 
2.43.0

[PATCH 1/7] doc: detect ignored public headers

[Marat Khalili]

Some public headers were omitted from doc/api/doxy-api-index.md and/or
doc/api/doxy-api.conf.in. Add checks to meson configuration detecting
and warning about these.

Suggested-by: Bruce Richardson <bruce.richardson@intel.com>
Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 drivers/meson.build | 17 +++++++++++++++++
 lib/meson.build     | 23 +++++++++++++++++++++++
 meson.build         | 19 +++++++++++++++++++
 3 files changed, 59 insertions(+)

diff --git a/drivers/meson.build b/drivers/meson.build
index 102a8262e588..09c063660291 100644
--- a/drivers/meson.build
+++ b/drivers/meson.build
@@ -287,6 +287,23 @@ foreach subpath:subdirs
         dpdk_headers += headers
         dpdk_drivers_headers += driver_sdk_headers
 
+        if check_docs and headers.length() > 0
+            foreach h:headers
+                hname = fs.name(h)
+                if not hname.startswith('rte_')
+                    warning('public header @0@ name does not start with "rte_"'.format(h))
+                endif
+                if hname not in doc_indexed_headers
+                    warning('public header @0@ is not listed in @1@'.format(h, doc_index_path))
+                endif
+            endforeach
+            doc_dir = 'drivers/' + drv_path
+            if doc_dir not in doc_built_dirs
+                warning('public header directory @0@ is not listed in @1@'.format(doc_dir,
+                    doc_build_path))
+            endif
+        endif
+
         if headers.length() > 0
             dpdk_includes += include_directories(drv_path)
         endif
diff --git a/lib/meson.build b/lib/meson.build
index af5c160cb800..ff5c474d2cc3 100644
--- a/lib/meson.build
+++ b/lib/meson.build
@@ -209,6 +209,29 @@ foreach l:libraries
     dpdk_indirect_headers += indirect_headers
     dpdk_drivers_headers += driver_sdk_headers
 
+    if check_docs and headers.length() > 0
+        foreach h:headers
+            hname = fs.name(h)
+            if not (hname.startswith('rte_') or hname.startswith('cmdline'))
+                warning('public header @0@ name does not start with "rte_" or "cmdline"'.format(h))
+            endif
+            if hname not in doc_indexed_headers
+                warning('public header @0@ is not listed in @1@'.format(h, doc_index_path))
+            endif
+        endforeach
+        if l == 'eal'
+            doc_dirs = ['lib/eal/include', 'lib/eal/include/generic']
+        else
+            doc_dirs = ['lib/' + l]
+        endif
+        foreach d:doc_dirs
+            if d not in doc_built_dirs
+                warning('public header directory @0@ is not listed in @1@'.format(doc_dir,
+                    doc_build_path))
+            endif
+        endforeach
+    endif
+
     libname = 'rte_' + name
     includes += include_directories(l)
     dpdk_includes += include_directories(l)
diff --git a/meson.build b/meson.build
index b01010ffa076..87666f1f81f4 100644
--- a/meson.build
+++ b/meson.build
@@ -88,6 +88,25 @@ if is_linux
     global_inc += include_directories('kernel/linux')
 endif
 
+# on linux, try to check that documentation sources are correctly built and indexed
+check_docs = is_linux and meson.version().version_compare('>= 0.60.0')
+
+if check_docs
+    doc_build_path = 'doc/api/doxy-api.conf.in'
+    doc_build_file = dpdk_source_root / doc_build_path
+    doc_built_dirs = run_command('sed', '--regexp-extended', '--quiet',
+        # Extract and print the file path immediately following @TOPDIR@/ .
+        's#^(INPUT *=)? *@TOPDIR@/([^ ]*)( .*|\\\\|)$#\\2#p',
+        doc_build_file, check: true).stdout().splitlines()
+
+    doc_index_path = 'doc/api/doxy-api-index.md'
+    doc_index_file = dpdk_source_root / doc_index_path
+    doc_indexed_headers = run_command('sed', '--regexp-extended', '--quiet',
+        # Extract and print the (@ref ...) contents.
+        's#^.*\\(@ref ([^)]*)\\).*$#\\1#p',
+        doc_index_file, check: true).stdout().splitlines()
+endif
+
 # build libs and drivers
 subdir('lib')
 subdir('drivers')
-- 
2.43.0

[PATCH 2/7] doc: document rte_os.h

[Marat Khalili]

File rte_os.h did not previously have a generic version to generate
documentation from, but its OS-specific version was installed. Since it
is now verified that documentation is generated for all public headers,
add a generic stub containing description of this file.

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 lib/eal/include/generic/rte_os.h | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 lib/eal/include/generic/rte_os.h

diff --git a/lib/eal/include/generic/rte_os.h b/lib/eal/include/generic/rte_os.h
new file mode 100644
index 000000000000..aa96321aefc4
--- /dev/null
+++ b/lib/eal/include/generic/rte_os.h
@@ -0,0 +1,13 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2010-2019 Intel Corporation
+ */
+
+#ifndef _RTE_OS_H_
+#define _RTE_OS_H_
+
+/**
+ * This header should contain any definition
+ * which is not supported natively or named differently in the local OS.
+ */
+
+#endif /* _RTE_OS_H_ */
-- 
2.43.0

[PATCH 3/7] doc: fix typos in rte_bus_pci.h

[Marat Khalili]

This file contained a couple of doxygen typos that prevented successful
documentation build. It was not discovered previously because the driver
despite the presence of public headers was not included in the
documentation build.

Fix doxygen typos (replace `@bar` with `@p bar`).

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 drivers/bus/pci/rte_bus_pci.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/bus/pci/rte_bus_pci.h b/drivers/bus/pci/rte_bus_pci.h
index 19a7b15b99fd..22a7beb1fc4c 100644
--- a/drivers/bus/pci/rte_bus_pci.h
+++ b/drivers/bus/pci/rte_bus_pci.h
@@ -222,7 +222,7 @@ int rte_pci_write_config(const struct rte_pci_device *device,
  * @param len
  *   The length of the data buffer.
  * @param offset
- *   The offset into MMIO space described by @bar.
+ *   The offset into MMIO space described by @p bar.
  * @return
  *   Number of bytes read on success, negative on error.
  */
@@ -246,7 +246,7 @@ int rte_pci_mmio_read(const struct rte_pci_device *device, int bar,
  * @param len
  *   The length of the data buffer.
  * @param offset
- *   The offset into MMIO space described by @bar.
+ *   The offset into MMIO space described by @p bar.
  * @return
  *   Number of bytes written on success, negative on error.
  */
-- 
2.43.0

[PATCH 4/7] doc: fix typos in rte_bus_vmbus.h

[Marat Khalili]

This file contained multiple doxygen issues that prevented successful
documentation build (missing, extra, misspelt parameter names etc). It
was not discovered previously because the driver despite the presence of
public headers was not included in the documentation build.

Fix invalid doxygen parameters annotations.

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 drivers/bus/vmbus/rte_bus_vmbus.h | 33 +++++++++++++++++++------------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/drivers/bus/vmbus/rte_bus_vmbus.h b/drivers/bus/vmbus/rte_bus_vmbus.h
index 2e9898ed7fb6..7f3ebd823201 100644
--- a/drivers/bus/vmbus/rte_bus_vmbus.h
+++ b/drivers/bus/vmbus/rte_bus_vmbus.h
@@ -111,7 +111,7 @@ int rte_vmbus_max_channels(const struct rte_vmbus_device *device);
  *
  * @param primary
  *   A pointer to primary VMBUS channel
- * @param chan
+ * @param new_chan
  *   A pointer to a secondary VMBUS channel pointer that will be filled.
  * @return
  *   - 0 Success; channel opened.
@@ -158,6 +158,8 @@ bool rte_vmbus_chan_rx_empty(const struct vmbus_channel *channel);
 /**
  * Send the specified buffer on the given channel
  *
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
  * @param channel
  *	Pointer to vmbus_channel structure.
  * @param type
@@ -184,7 +186,9 @@ int rte_vmbus_chan_send(struct rte_vmbus_device *dev,
 /**
  * Explicitly signal host that data is available
  *
- * @param
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
+ * @param channel
  *	Pointer to vmbus_channel structure.
  *
  * Used when batching multiple sends and only signaling host
@@ -203,11 +207,10 @@ struct iova_list {
 /**
  * Send a scattered buffer on the given channel
  *
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
  * @param channel
  *	Pointer to vmbus_channel structure.
- * @param type
- *	Type of packet that is being send e.g. negotiate, time
- *	packet etc.
  * @param gpa
  *	Array of buffers to send
  * @param gpacnt
@@ -218,8 +221,6 @@ struct iova_list {
  *	 Maximum size of what the buffer will hold
  * @param xact
  *	Identifier of the request
- * @param flags
- *	Message type inband, rxbuf, gpa
  * @param need_sig
  *	Is host signal tx is required (optional)
  *
@@ -234,13 +235,15 @@ int rte_vmbus_chan_send_sglist(struct rte_vmbus_device *dev,
  * Receive response to request on the given channel
  * skips the channel header.
  *
- * @param channel
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
+ * @param chan
  *	Pointer to vmbus_channel structure.
  * @param data
  *	Pointer to the buffer you want to receive the data into.
  * @param len
  *	Pointer to size of receive buffer (in/out)
- * @param
+ * @param request_id
  *	Pointer to received transaction_id
  * @return
  *   On success, returns 0
@@ -255,7 +258,7 @@ int rte_vmbus_chan_recv(struct rte_vmbus_device *dev,
  * Receive response to request on the given channel
  * includes the channel header.
  *
- * @param channel
+ * @param chan
  *	Pointer to vmbus_channel structure.
  * @param data
  *	Pointer to the buffer you want to receive the data into.
@@ -272,7 +275,9 @@ int rte_vmbus_chan_recv_raw(struct vmbus_channel *chan,
  * Notify host of bytes read (after recv_raw)
  * Signals host if required.
  *
- * @param channel
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
+ * @param chan
  *	Pointer to vmbus_channel structure.
  * @param bytes_read
  *	Number of bytes read since last signal
@@ -284,7 +289,7 @@ void rte_vmbus_chan_signal_read(struct rte_vmbus_device *dev,
 /**
  * Determine sub channel index of the given channel
  *
- * @param channel
+ * @param chan
  *	Pointer to vmbus_channel structure.
  * @return
  *   Sub channel index (0 for primary)
@@ -309,7 +314,9 @@ void rte_vmbus_set_latency(const struct rte_vmbus_device *dev,
 /**
  * For debug dump contents of ring buffer.
  *
- * @param channel
+ * @param f
+ *	Output file to dump to.
+ * @param chan
  *	Pointer to vmbus_channel structure.
  */
 void rte_vmbus_chan_dump(FILE *f, const struct vmbus_channel *chan);
-- 
2.43.0

[PATCH 5/7] doc: add missing globs to doxy-api.conf.in

[Marat Khalili]

Public headers starting from `cmdline` (except for `cmdline.h` itself)
and `bpf_def.h` were not previously included in the documentation build.

Add missing file patterns (globs) to include all public headers.

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 doc/api/doxy-api.conf.in | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index bedd94468150..2cb152d6db98 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -88,7 +88,8 @@ INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
                           @TOPDIR@/lib/vhost
 INPUT                   += @API_EXAMPLES@
 FILE_PATTERNS           = rte_*.h \
-                          cmdline.h
+                          cmdline*.h \
+                          bpf_def.h
 PREDEFINED              = __DOXYGEN__ \
                           RTE_ATOMIC \
                           RTE_HAS_CPUSET \
-- 
2.43.0

[PATCH 6/7] doc: add missing drivers to doxy-api.conf.in

[Marat Khalili]

Make sure all drivers declaring public headers are added to
`doxy-api.conf.in` to trigger documentation generation. Sort them.

The only driver still omitted is cnxk_bphy since it needs writing
multiple new doxygen descriptions which could not be done on the spot
(tracked by bug 1962 in bugzilla).

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 doc/api/doxy-api.conf.in | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index 2cb152d6db98..1620027215a9 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -5,15 +5,20 @@ PROJECT_NAME            = DPDK
 PROJECT_NUMBER          = @VERSION@
 USE_MDFILE_AS_MAINPAGE  = @TOPDIR@/doc/api/doxy-api-index.md
 INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
+                          @TOPDIR@/drivers/baseband/acc \
+                          @TOPDIR@/drivers/baseband/fpga_5gnr_fec \
+                          @TOPDIR@/drivers/bus/pci \
                           @TOPDIR@/drivers/bus/vdev \
+                          @TOPDIR@/drivers/bus/vmbus \
                           @TOPDIR@/drivers/common/dpaax \
                           @TOPDIR@/drivers/crypto/cnxk \
                           @TOPDIR@/drivers/crypto/scheduler \
-                          @TOPDIR@/drivers/event/dlb2 \
                           @TOPDIR@/drivers/event/cnxk \
+                          @TOPDIR@/drivers/event/dlb2 \
                           @TOPDIR@/drivers/mempool/cnxk \
                           @TOPDIR@/drivers/mempool/dpaa2 \
                           @TOPDIR@/drivers/net/ark \
+                          @TOPDIR@/drivers/net/avp \
                           @TOPDIR@/drivers/net/bnxt \
                           @TOPDIR@/drivers/net/bonding \
                           @TOPDIR@/drivers/net/cnxk \
@@ -23,9 +28,16 @@ INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
                           @TOPDIR@/drivers/net/intel/iavf \
                           @TOPDIR@/drivers/net/intel/ixgbe \
                           @TOPDIR@/drivers/net/mlx5 \
+                          @TOPDIR@/drivers/net/ntnic \
+                          @TOPDIR@/drivers/net/ring \
                           @TOPDIR@/drivers/net/softnic \
+                          @TOPDIR@/drivers/net/txgbe \
+                          @TOPDIR@/drivers/net/vhost \
+                          @TOPDIR@/drivers/power/kvm_vm \
+                          @TOPDIR@/drivers/raw/cnxk_gpio \
                           @TOPDIR@/drivers/raw/dpaa2_cmdif \
                           @TOPDIR@/drivers/raw/ifpga \
+                          @TOPDIR@/drivers/raw/ntb \
                           @TOPDIR@/lib/eal/include \
                           @TOPDIR@/lib/eal/include/generic \
                           @TOPDIR@/lib/acl \
-- 
2.43.0

[PATCH 7/7] doc: add missing headers to doxy-api-index.md

[Marat Khalili]

Make sure all public headers are listed in `doxy-api-index.md` to be
reachable in HTML version. Presumably each of them should contain at
least a general file description, though this is not checked now.

The only header still omitted is rte_pmd_bphy.h since it needs writing
multiple new doxygen descriptions which could not be done on the spot,
so it is excluded from the build (tracked by bug 1962 in bugzilla).

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 doc/api/doxy-api-index.md | 116 +++++++++++++++++++++++++++++++++-----
 1 file changed, 102 insertions(+), 14 deletions(-)

diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index 929604211946..db7aeccd4e30 100644
--- a/doc/api/doxy-api-index.md
+++ b/doc/api/doxy-api-index.md
@@ -9,14 +9,24 @@ API
 The public API headers are grouped by topics:
 
 - **device**:
+  [bus](@ref rte_bus.h),
   [dev](@ref rte_dev.h),
   [ethdev](@ref rte_ethdev.h),
+  [cman](@ref rte_cman.h),
+  [ethdev trace fp](@ref rte_ethdev_trace_fp.h),
+  [dev info](@ref rte_dev_info.h),
   [ethctrl](@ref rte_eth_ctrl.h),
   [rte_flow](@ref rte_flow.h),
   [rte_tm](@ref rte_tm.h),
   [rte_mtr](@ref rte_mtr.h),
   [bbdev](@ref rte_bbdev.h),
+  [bbdev op](@ref rte_bbdev_op.h),
+  [bbdev trace fp](@ref rte_bbdev_trace_fp.h),
   [cryptodev](@ref rte_cryptodev.h),
+  [crypto](@ref rte_crypto.h),
+  [crypto sym](@ref rte_crypto_sym.h),
+  [crypto asym](@ref rte_crypto_asym.h),
+  [cryptodev trace fp](@ref rte_cryptodev_trace_fp.h),
   [security](@ref rte_security.h),
   [compressdev](@ref rte_compressdev.h),
   [compress](@ref rte_comp.h),
@@ -25,6 +35,8 @@ The public API headers are grouped by topics:
   [dmadev](@ref rte_dmadev.h),
   [gpudev](@ref rte_gpudev.h),
   [eventdev](@ref rte_eventdev.h),
+  [event ring](@ref rte_event_ring.h),
+  [eventdev trace fp](@ref rte_eventdev_trace_fp.h),
   [event_eth_rx_adapter](@ref rte_event_eth_rx_adapter.h),
   [event_eth_tx_adapter](@ref rte_event_eth_tx_adapter.h),
   [event_timer_adapter](@ref rte_event_timer_adapter.h),
@@ -33,17 +45,27 @@ The public API headers are grouped by topics:
   [event_vector_adapter](@ref rte_event_vector_adapter.h),
   [rawdev](@ref rte_rawdev.h),
   [metrics](@ref rte_metrics.h),
+  [metrics telemetry](@ref rte_metrics_telemetry.h),
   [bitrate](@ref rte_bitrate.h),
   [latency](@ref rte_latencystats.h),
   [devargs](@ref rte_devargs.h),
   [PCI](@ref rte_pci.h),
+  [PCI dev feature defs](@ref rte_pci_dev_feature_defs.h),
+  [PCI dev features](@ref rte_pci_dev_features.h),
+  [bus PCI](@ref rte_bus_pci.h),
   [vdev](@ref rte_bus_vdev.h),
+  [vmbus](@ref rte_bus_vmbus.h),
+  [vmbus reg](@ref rte_vmbus_reg.h),
   [vfio](@ref rte_vfio.h)
 
 - **device specific**:
   [softnic](@ref rte_eth_softnic.h),
   [bond](@ref rte_eth_bond.h),
+  [bond 8023ad](@ref rte_eth_bond_8023ad.h),
   [vhost](@ref rte_vhost.h),
+  [vhost async](@ref rte_vhost_async.h),
+  [vhost crypto](@ref rte_vhost_crypto.h),
+  [eth vhost](@ref rte_eth_vhost.h),
   [vdpa](@ref rte_vdpa.h),
   [ixgbe](@ref rte_pmd_ixgbe.h),
   [i40e](@ref rte_pmd_i40e.h),
@@ -53,6 +75,7 @@ The public API headers are grouped by topics:
   [cnxk_crypto](@ref rte_pmd_cnxk_crypto.h),
   [cnxk_eventdev](@ref rte_pmd_cnxk_eventdev.h),
   [cnxk_mempool](@ref rte_pmd_cnxk_mempool.h),
+  [cnxk gpio](@ref rte_pmd_cnxk_gpio.h),
   [dpaa](@ref rte_pmd_dpaa.h),
   [dpaa2](@ref rte_pmd_dpaa2.h),
   [mlx5](@ref rte_pmd_mlx5.h),
@@ -60,25 +83,40 @@ The public API headers are grouped by topics:
   [dpaa2_cmdif](@ref rte_pmd_dpaa2_cmdif.h),
   [dpaax_qdma](@ref rte_pmd_dpaax_qdma.h),
   [crypto_scheduler](@ref rte_cryptodev_scheduler.h),
+  [crypto scheduler operations](@ref rte_cryptodev_scheduler_operations.h),
   [dlb2](@ref rte_pmd_dlb2.h),
-  [ifpga](@ref rte_pmd_ifpga.h)
+  [ifpga](@ref rte_pmd_ifpga.h),
+  [avp common](@ref rte_avp_common.h),
+  [avp fifo](@ref rte_avp_fifo.h),
+  [ntnic](@ref rte_pmd_ntnic.h),
+  [ring](@ref rte_eth_ring.h),
+  [txgbe](@ref rte_pmd_txgbe.h),
+  [ntb](@ref rte_pmd_ntb.h),
+  [acc cfg](@ref rte_acc_cfg.h),
+  [acc common cfg](@ref rte_acc_common_cfg.h),
+  [fpga 5gnr fec](@ref rte_pmd_fpga_5gnr_fec.h)
 
 - **memory**:
   [per-lcore](@ref rte_per_lcore.h),
   [lcore variables](@ref rte_lcore_var.h),
+  [EAL memconfig](@ref rte_eal_memconfig.h),
   [memseg](@ref rte_memory.h),
   [memzone](@ref rte_memzone.h),
   [mempool](@ref rte_mempool.h),
+  [mempool trace fp](@ref rte_mempool_trace_fp.h),
   [malloc](@ref rte_malloc.h),
   [memcpy](@ref rte_memcpy.h)
 
 - **timers**:
   [cycles](@ref rte_cycles.h),
+  [time](@ref rte_time.h),
   [timer](@ref rte_timer.h),
   [alarm](@ref rte_alarm.h)
 
 - **locks**:
   [atomic](@ref rte_atomic.h),
+  [stdatomic](@ref rte_stdatomic.h),
+  [lock annotations](@ref rte_lock_annotations.h),
   [mcslock](@ref rte_mcslock.h),
   [pflock](@ref rte_pflock.h),
   [rwlock](@ref rte_rwlock.h),
@@ -103,13 +141,18 @@ The public API headers are grouped by topics:
   [launch](@ref rte_launch.h),
   [lcore](@ref rte_lcore.h),
   [service cores](@ref rte_service.h),
+  [service component](@ref rte_service_component.h),
   [keepalive](@ref rte_keepalive.h),
   [power/freq](@ref rte_power_cpufreq.h),
   [power/uncore](@ref rte_power_uncore.h),
-  [PMD power](@ref rte_power_pmd_mgmt.h)
+  [PMD power](@ref rte_power_pmd_mgmt.h),
+  [power guest channel](@ref rte_power_guest_channel.h),
+  [power qos](@ref rte_power_qos.h)
 
 - **layers**:
   [ethernet](@ref rte_ether.h),
+  [net](@ref rte_net.h),
+  [net CRC](@ref rte_net_crc.h),
   [MACsec](@ref rte_macsec.h),
   [ARP](@ref rte_arp.h),
   [HIGIG](@ref rte_higig.h),
@@ -119,6 +162,7 @@ The public API headers are grouped by topics:
   [IPsec group](@ref rte_ipsec_group.h),
   [IPsec SA](@ref rte_ipsec_sa.h),
   [IPsec SAD](@ref rte_ipsec_sad.h),
+  [IP](@ref rte_ip.h),
   [IPv4](@ref rte_ip4.h),
   [IPv6](@ref rte_ip6.h),
   [frag/reass](@ref rte_ip_frag.h),
@@ -139,12 +183,15 @@ The public API headers are grouped by topics:
   [PDCP](@ref rte_pdcp.h),
   [L2TPv2](@ref rte_l2tpv2.h),
   [PPP](@ref rte_ppp.h),
-  [IB](@ref rte_ib.h)
+  [IB](@ref rte_ib.h),
+  [PTP](@ref rte_ptp.h)
 
 - **QoS**:
   [metering](@ref rte_meter.h),
   [scheduler](@ref rte_sched.h),
-  [RED congestion](@ref rte_red.h)
+  [sched common](@ref rte_sched_common.h),
+  [RED congestion](@ref rte_red.h),
+  [PIE](@ref rte_pie.h)
 
 - **routing**:
   [LPM IPv4 route](@ref rte_lpm.h),
@@ -168,18 +215,26 @@ The public API headers are grouped by topics:
   [distributor](@ref rte_distributor.h),
   [EFD](@ref rte_efd.h),
   [ACL](@ref rte_acl.h),
+  [ACL osdep](@ref rte_acl_osdep.h),
   [member](@ref rte_member.h),
-  [BPF](@ref rte_bpf.h)
+  [BPF](@ref rte_bpf.h),
+  [BPF def](@ref bpf_def.h),
+  [BPF ethdev](@ref rte_bpf_ethdev.h)
 
 - **containers**:
   [mbuf](@ref rte_mbuf.h),
+  [mbuf core](@ref rte_mbuf_core.h),
+  [mbuf ptype](@ref rte_mbuf_ptype.h),
+  [mbuf dyn](@ref rte_mbuf_dyn.h),
+  [mbuf history](@ref rte_mbuf_history.h),
   [mbuf pool ops](@ref rte_mbuf_pool_ops.h),
   [ring](@ref rte_ring.h),
   [soring](@ref rte_soring.h),
   [stack](@ref rte_stack.h),
   [tailq](@ref rte_tailq.h),
   [bitset](@ref rte_bitset.h),
-  [bitmap](@ref rte_bitmap.h)
+  [bitmap](@ref rte_bitmap.h),
+  [fbarray](@ref rte_fbarray.h)
 
 - **packet framework**:
   * [port](@ref rte_port.h):
@@ -188,21 +243,28 @@ The public API headers are grouped by topics:
     [frag](@ref rte_port_frag.h),
     [reass](@ref rte_port_ras.h),
     [sched](@ref rte_port_sched.h),
-    [src/sink](@ref rte_port_source_sink.h)
+    [src/sink](@ref rte_port_source_sink.h),
+    [fd](@ref rte_port_fd.h),
+    [sym crypto](@ref rte_port_sym_crypto.h),
+    [eventdev](@ref rte_port_eventdev.h)
   * [table](@ref rte_table.h):
     [lpm IPv4](@ref rte_table_lpm.h),
     [lpm IPv6](@ref rte_table_lpm_ipv6.h),
     [ACL](@ref rte_table_acl.h),
     [hash](@ref rte_table_hash.h),
     [array](@ref rte_table_array.h),
-    [stub](@ref rte_table_stub.h)
+    [stub](@ref rte_table_stub.h),
+    [LRU](@ref rte_lru.h),
+    [hash cuckoo](@ref rte_table_hash_cuckoo.h),
+    [hash func](@ref rte_table_hash_func.h)
   * [pipeline](@ref rte_pipeline.h)
     [port_in_action](@ref rte_port_in_action.h)
     [table_action](@ref rte_table_action.h)
   * SWX pipeline:
     [control](@ref rte_swx_ctl.h),
     [extern](@ref rte_swx_extern.h),
-    [pipeline](@ref rte_swx_pipeline.h)
+    [pipeline](@ref rte_swx_pipeline.h),
+    [IPsec](@ref rte_swx_ipsec.h)
   * SWX port:
     [port](@ref rte_swx_port.h),
     [ethdev](@ref rte_swx_port_ethdev.h),
@@ -211,8 +273,11 @@ The public API headers are grouped by topics:
     [src/sink](@ref rte_swx_port_source_sink.h)
   * SWX table:
     [table](@ref rte_swx_table.h),
-    [table_em](@ref rte_swx_table_em.h)
-    [table_wm](@ref rte_swx_table_wm.h)
+    [table_em](@ref rte_swx_table_em.h),
+    [table_wm](@ref rte_swx_table_wm.h),
+    [hash func](@ref rte_swx_hash_func.h),
+    [table learner](@ref rte_swx_table_learner.h),
+    [table selector](@ref rte_swx_table_selector.h)
   * [graph](@ref rte_graph.h):
     [graph_worker](@ref rte_graph_worker.h),
     [graph_feature_arc](@ref rte_graph_feature_arc.h),
@@ -222,7 +287,22 @@ The public API headers are grouped by topics:
     [ip4_node](@ref rte_node_ip4_api.h),
     [ip6_node](@ref rte_node_ip6_api.h),
     [udp4_input_node](@ref rte_node_udp4_input_api.h),
-    [mbuf_dynfield](@ref rte_node_mbuf_dynfield.h)
+    [mbuf_dynfield](@ref rte_node_mbuf_dynfield.h),
+    [pkt cls api](@ref rte_node_pkt_cls_api.h)
+
+- **cmdline**:
+  [cmdline](@ref cmdline.h),
+  [parse](@ref cmdline_parse.h),
+  [parse num](@ref cmdline_parse_num.h),
+  [parse bool](@ref cmdline_parse_bool.h),
+  [parse ipaddr](@ref cmdline_parse_ipaddr.h),
+  [parse etheraddr](@ref cmdline_parse_etheraddr.h),
+  [parse string](@ref cmdline_parse_string.h),
+  [parse portlist](@ref cmdline_parse_portlist.h),
+  [rdline](@ref cmdline_rdline.h),
+  [vt100](@ref cmdline_vt100.h),
+  [socket](@ref cmdline_socket.h),
+  [cirbuf](@ref cmdline_cirbuf.h)
 
 - **basic**:
   [bitops](@ref rte_bitops.h),
@@ -234,7 +314,9 @@ The public API headers are grouped by topics:
   [argument parsing](@ref rte_argparse.h),
   [ptr_compress](@ref rte_ptr_compress.h),
   [string](@ref rte_string_fns.h),
-  [thread](@ref rte_thread.h)
+  [thread](@ref rte_thread.h),
+  [reciprocal](@ref rte_reciprocal.h),
+  [UUID](@ref rte_uuid.h)
 
 - **debug**:
   [jobstats](@ref rte_jobstats.h),
@@ -247,11 +329,17 @@ The public API headers are grouped by topics:
   [log](@ref rte_log.h),
   [errno](@ref rte_errno.h),
   [trace](@ref rte_trace.h),
-  [trace_point](@ref rte_trace_point.h)
+  [EAL trace](@ref rte_eal_trace.h),
+  [trace_point](@ref rte_trace_point.h),
+  [trace point register](@ref rte_trace_point_register.h)
 
 - **misc**:
   [EAL config](@ref rte_eal.h),
+  [class](@ref rte_class.h),
   [common](@ref rte_common.h),
+  [epoll](@ref rte_epoll.h),
+  [hypervisor](@ref rte_hypervisor.h),
+  [OS](@ref rte_os.h),
   [experimental APIs](@ref rte_compat.h),
   [version](@ref rte_version.h)
 
-- 
2.43.0

[PATCH v2 0/7] doc: build for all public headers

[Marat Khalili]

It was noticed that not all public headers were included in the doxygen
build, and once built not all files were listed in the index file
serving as a point of entry for the HTML version.

Bruce Richardson provided an idea and a draft implementation of the
configuration-time check, which I optimized to avoid repeat grep calls
and expanded to include indexing check.

After all drivers and public headers were included, multiple small
problems have surfaced fixes for which (with one exception covered by
bug 1962) are also included in this patch set.

v2:
* switched from `splitlines()` to `strip('\n').split('\n')` for
  compatibility with older versions of meson;
* rebased on fresh main and updated BPF header links in the index file;

Marat Khalili (7):
  doc: detect ignored public headers
  doc: document rte_os.h
  doc: fix typos in rte_bus_pci.h
  doc: fix typos in rte_bus_vmbus.h
  doc: add missing globs to doxy-api.conf.in
  doc: add missing drivers to doxy-api.conf.in
  doc: add missing headers to doxy-api-index.md

 doc/api/doxy-api-index.md         | 120 ++++++++++++++++++++++++++----
 doc/api/doxy-api.conf.in          |  17 ++++-
 drivers/bus/pci/rte_bus_pci.h     |   4 +-
 drivers/bus/vmbus/rte_bus_vmbus.h |  33 ++++----
 drivers/meson.build               |  17 +++++
 lib/eal/include/generic/rte_os.h  |  13 ++++
 lib/meson.build                   |  23 ++++++
 meson.build                       |  19 +++++
 8 files changed, 214 insertions(+), 32 deletions(-)
 create mode 100644 lib/eal/include/generic/rte_os.h

-- 
2.43.0

[PATCH v2 1/7] doc: detect ignored public headers

[Marat Khalili]

Some public headers were omitted from doc/api/doxy-api-index.md and/or
doc/api/doxy-api.conf.in. Add checks to meson configuration detecting
and warning about these.

Suggested-by: Bruce Richardson <bruce.richardson@intel.com>
Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 drivers/meson.build | 17 +++++++++++++++++
 lib/meson.build     | 23 +++++++++++++++++++++++
 meson.build         | 19 +++++++++++++++++++
 3 files changed, 59 insertions(+)

diff --git a/drivers/meson.build b/drivers/meson.build
index 102a8262e588..09c063660291 100644
--- a/drivers/meson.build
+++ b/drivers/meson.build
@@ -287,6 +287,23 @@ foreach subpath:subdirs
         dpdk_headers += headers
         dpdk_drivers_headers += driver_sdk_headers
 
+        if check_docs and headers.length() > 0
+            foreach h:headers
+                hname = fs.name(h)
+                if not hname.startswith('rte_')
+                    warning('public header @0@ name does not start with "rte_"'.format(h))
+                endif
+                if hname not in doc_indexed_headers
+                    warning('public header @0@ is not listed in @1@'.format(h, doc_index_path))
+                endif
+            endforeach
+            doc_dir = 'drivers/' + drv_path
+            if doc_dir not in doc_built_dirs
+                warning('public header directory @0@ is not listed in @1@'.format(doc_dir,
+                    doc_build_path))
+            endif
+        endif
+
         if headers.length() > 0
             dpdk_includes += include_directories(drv_path)
         endif
diff --git a/lib/meson.build b/lib/meson.build
index af5c160cb800..ff5c474d2cc3 100644
--- a/lib/meson.build
+++ b/lib/meson.build
@@ -209,6 +209,29 @@ foreach l:libraries
     dpdk_indirect_headers += indirect_headers
     dpdk_drivers_headers += driver_sdk_headers
 
+    if check_docs and headers.length() > 0
+        foreach h:headers
+            hname = fs.name(h)
+            if not (hname.startswith('rte_') or hname.startswith('cmdline'))
+                warning('public header @0@ name does not start with "rte_" or "cmdline"'.format(h))
+            endif
+            if hname not in doc_indexed_headers
+                warning('public header @0@ is not listed in @1@'.format(h, doc_index_path))
+            endif
+        endforeach
+        if l == 'eal'
+            doc_dirs = ['lib/eal/include', 'lib/eal/include/generic']
+        else
+            doc_dirs = ['lib/' + l]
+        endif
+        foreach d:doc_dirs
+            if d not in doc_built_dirs
+                warning('public header directory @0@ is not listed in @1@'.format(doc_dir,
+                    doc_build_path))
+            endif
+        endforeach
+    endif
+
     libname = 'rte_' + name
     includes += include_directories(l)
     dpdk_includes += include_directories(l)
diff --git a/meson.build b/meson.build
index b01010ffa076..2488c54f1b17 100644
--- a/meson.build
+++ b/meson.build
@@ -88,6 +88,25 @@ if is_linux
     global_inc += include_directories('kernel/linux')
 endif
 
+# on linux, try to check that documentation sources are correctly built and indexed
+check_docs = is_linux and meson.version().version_compare('>= 0.60.0')
+
+if check_docs
+    doc_build_path = 'doc/api/doxy-api.conf.in'
+    doc_build_file = dpdk_source_root / doc_build_path
+    doc_built_dirs = run_command('sed', '--regexp-extended', '--quiet',
+        # Extract and print the file path immediately following @TOPDIR@/ .
+        's#^(INPUT *=)? *@TOPDIR@/([^ ]*)( .*|\\\\|)$#\\2#p',
+        doc_build_file, check: true).stdout().strip('\n').split('\n')
+
+    doc_index_path = 'doc/api/doxy-api-index.md'
+    doc_index_file = dpdk_source_root / doc_index_path
+    doc_indexed_headers = run_command('sed', '--regexp-extended', '--quiet',
+        # Extract and print the (@ref ...) contents.
+        's#^.*\\(@ref ([^)]*)\\).*$#\\1#p',
+        doc_index_file, check: true).stdout().strip('\n').split('\n')
+endif
+
 # build libs and drivers
 subdir('lib')
 subdir('drivers')
-- 
2.43.0

[PATCH v2 2/7] doc: document rte_os.h

[Marat Khalili]

File rte_os.h did not previously have a generic version to generate
documentation from, but its OS-specific version was installed. Since it
is now verified that documentation is generated for all public headers,
add a generic stub containing description of this file.

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 lib/eal/include/generic/rte_os.h | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 lib/eal/include/generic/rte_os.h

diff --git a/lib/eal/include/generic/rte_os.h b/lib/eal/include/generic/rte_os.h
new file mode 100644
index 000000000000..aa96321aefc4
--- /dev/null
+++ b/lib/eal/include/generic/rte_os.h
@@ -0,0 +1,13 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2010-2019 Intel Corporation
+ */
+
+#ifndef _RTE_OS_H_
+#define _RTE_OS_H_
+
+/**
+ * This header should contain any definition
+ * which is not supported natively or named differently in the local OS.
+ */
+
+#endif /* _RTE_OS_H_ */
-- 
2.43.0

[PATCH v2 3/7] doc: fix typos in rte_bus_pci.h

[Marat Khalili]

This file contained a couple of doxygen typos that prevented successful
documentation build. It was not discovered previously because the driver
despite the presence of public headers was not included in the
documentation build.

Fix doxygen typos (replace `@bar` with `@p bar`).

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 drivers/bus/pci/rte_bus_pci.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/bus/pci/rte_bus_pci.h b/drivers/bus/pci/rte_bus_pci.h
index 19a7b15b99fd..22a7beb1fc4c 100644
--- a/drivers/bus/pci/rte_bus_pci.h
+++ b/drivers/bus/pci/rte_bus_pci.h
@@ -222,7 +222,7 @@ int rte_pci_write_config(const struct rte_pci_device *device,
  * @param len
  *   The length of the data buffer.
  * @param offset
- *   The offset into MMIO space described by @bar.
+ *   The offset into MMIO space described by @p bar.
  * @return
  *   Number of bytes read on success, negative on error.
  */
@@ -246,7 +246,7 @@ int rte_pci_mmio_read(const struct rte_pci_device *device, int bar,
  * @param len
  *   The length of the data buffer.
  * @param offset
- *   The offset into MMIO space described by @bar.
+ *   The offset into MMIO space described by @p bar.
  * @return
  *   Number of bytes written on success, negative on error.
  */
-- 
2.43.0

[PATCH v2 4/7] doc: fix typos in rte_bus_vmbus.h

[Marat Khalili]

This file contained multiple doxygen issues that prevented successful
documentation build (missing, extra, misspelt parameter names etc). It
was not discovered previously because the driver despite the presence of
public headers was not included in the documentation build.

Fix invalid doxygen parameters annotations.

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 drivers/bus/vmbus/rte_bus_vmbus.h | 33 +++++++++++++++++++------------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/drivers/bus/vmbus/rte_bus_vmbus.h b/drivers/bus/vmbus/rte_bus_vmbus.h
index 2e9898ed7fb6..7f3ebd823201 100644
--- a/drivers/bus/vmbus/rte_bus_vmbus.h
+++ b/drivers/bus/vmbus/rte_bus_vmbus.h
@@ -111,7 +111,7 @@ int rte_vmbus_max_channels(const struct rte_vmbus_device *device);
  *
  * @param primary
  *   A pointer to primary VMBUS channel
- * @param chan
+ * @param new_chan
  *   A pointer to a secondary VMBUS channel pointer that will be filled.
  * @return
  *   - 0 Success; channel opened.
@@ -158,6 +158,8 @@ bool rte_vmbus_chan_rx_empty(const struct vmbus_channel *channel);
 /**
  * Send the specified buffer on the given channel
  *
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
  * @param channel
  *	Pointer to vmbus_channel structure.
  * @param type
@@ -184,7 +186,9 @@ int rte_vmbus_chan_send(struct rte_vmbus_device *dev,
 /**
  * Explicitly signal host that data is available
  *
- * @param
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
+ * @param channel
  *	Pointer to vmbus_channel structure.
  *
  * Used when batching multiple sends and only signaling host
@@ -203,11 +207,10 @@ struct iova_list {
 /**
  * Send a scattered buffer on the given channel
  *
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
  * @param channel
  *	Pointer to vmbus_channel structure.
- * @param type
- *	Type of packet that is being send e.g. negotiate, time
- *	packet etc.
  * @param gpa
  *	Array of buffers to send
  * @param gpacnt
@@ -218,8 +221,6 @@ struct iova_list {
  *	 Maximum size of what the buffer will hold
  * @param xact
  *	Identifier of the request
- * @param flags
- *	Message type inband, rxbuf, gpa
  * @param need_sig
  *	Is host signal tx is required (optional)
  *
@@ -234,13 +235,15 @@ int rte_vmbus_chan_send_sglist(struct rte_vmbus_device *dev,
  * Receive response to request on the given channel
  * skips the channel header.
  *
- * @param channel
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
+ * @param chan
  *	Pointer to vmbus_channel structure.
  * @param data
  *	Pointer to the buffer you want to receive the data into.
  * @param len
  *	Pointer to size of receive buffer (in/out)
- * @param
+ * @param request_id
  *	Pointer to received transaction_id
  * @return
  *   On success, returns 0
@@ -255,7 +258,7 @@ int rte_vmbus_chan_recv(struct rte_vmbus_device *dev,
  * Receive response to request on the given channel
  * includes the channel header.
  *
- * @param channel
+ * @param chan
  *	Pointer to vmbus_channel structure.
  * @param data
  *	Pointer to the buffer you want to receive the data into.
@@ -272,7 +275,9 @@ int rte_vmbus_chan_recv_raw(struct vmbus_channel *chan,
  * Notify host of bytes read (after recv_raw)
  * Signals host if required.
  *
- * @param channel
+ * @param dev
+ *	A pointer to a rte_vmbus_device structure describing the device
+ * @param chan
  *	Pointer to vmbus_channel structure.
  * @param bytes_read
  *	Number of bytes read since last signal
@@ -284,7 +289,7 @@ void rte_vmbus_chan_signal_read(struct rte_vmbus_device *dev,
 /**
  * Determine sub channel index of the given channel
  *
- * @param channel
+ * @param chan
  *	Pointer to vmbus_channel structure.
  * @return
  *   Sub channel index (0 for primary)
@@ -309,7 +314,9 @@ void rte_vmbus_set_latency(const struct rte_vmbus_device *dev,
 /**
  * For debug dump contents of ring buffer.
  *
- * @param channel
+ * @param f
+ *	Output file to dump to.
+ * @param chan
  *	Pointer to vmbus_channel structure.
  */
 void rte_vmbus_chan_dump(FILE *f, const struct vmbus_channel *chan);
-- 
2.43.0

[PATCH v2 5/7] doc: add missing globs to doxy-api.conf.in

[Marat Khalili]

Public headers starting from `cmdline` (except for `cmdline.h` itself)
and `bpf_def.h` were not previously included in the documentation build.

Add missing file patterns (globs) to include all public headers.

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 doc/api/doxy-api.conf.in | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index bedd94468150..2cb152d6db98 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -88,7 +88,8 @@ INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
                           @TOPDIR@/lib/vhost
 INPUT                   += @API_EXAMPLES@
 FILE_PATTERNS           = rte_*.h \
-                          cmdline.h
+                          cmdline*.h \
+                          bpf_def.h
 PREDEFINED              = __DOXYGEN__ \
                           RTE_ATOMIC \
                           RTE_HAS_CPUSET \
-- 
2.43.0

[PATCH v2 6/7] doc: add missing drivers to doxy-api.conf.in

[Marat Khalili]

Make sure all drivers declaring public headers are added to
`doxy-api.conf.in` to trigger documentation generation. Sort them.

The only driver still omitted is cnxk_bphy since it needs writing
multiple new doxygen descriptions which could not be done on the spot
(tracked by bug 1962 in bugzilla).

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 doc/api/doxy-api.conf.in | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
index 2cb152d6db98..1620027215a9 100644
--- a/doc/api/doxy-api.conf.in
+++ b/doc/api/doxy-api.conf.in
@@ -5,15 +5,20 @@ PROJECT_NAME            = DPDK
 PROJECT_NUMBER          = @VERSION@
 USE_MDFILE_AS_MAINPAGE  = @TOPDIR@/doc/api/doxy-api-index.md
 INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
+                          @TOPDIR@/drivers/baseband/acc \
+                          @TOPDIR@/drivers/baseband/fpga_5gnr_fec \
+                          @TOPDIR@/drivers/bus/pci \
                           @TOPDIR@/drivers/bus/vdev \
+                          @TOPDIR@/drivers/bus/vmbus \
                           @TOPDIR@/drivers/common/dpaax \
                           @TOPDIR@/drivers/crypto/cnxk \
                           @TOPDIR@/drivers/crypto/scheduler \
-                          @TOPDIR@/drivers/event/dlb2 \
                           @TOPDIR@/drivers/event/cnxk \
+                          @TOPDIR@/drivers/event/dlb2 \
                           @TOPDIR@/drivers/mempool/cnxk \
                           @TOPDIR@/drivers/mempool/dpaa2 \
                           @TOPDIR@/drivers/net/ark \
+                          @TOPDIR@/drivers/net/avp \
                           @TOPDIR@/drivers/net/bnxt \
                           @TOPDIR@/drivers/net/bonding \
                           @TOPDIR@/drivers/net/cnxk \
@@ -23,9 +28,16 @@ INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
                           @TOPDIR@/drivers/net/intel/iavf \
                           @TOPDIR@/drivers/net/intel/ixgbe \
                           @TOPDIR@/drivers/net/mlx5 \
+                          @TOPDIR@/drivers/net/ntnic \
+                          @TOPDIR@/drivers/net/ring \
                           @TOPDIR@/drivers/net/softnic \
+                          @TOPDIR@/drivers/net/txgbe \
+                          @TOPDIR@/drivers/net/vhost \
+                          @TOPDIR@/drivers/power/kvm_vm \
+                          @TOPDIR@/drivers/raw/cnxk_gpio \
                           @TOPDIR@/drivers/raw/dpaa2_cmdif \
                           @TOPDIR@/drivers/raw/ifpga \
+                          @TOPDIR@/drivers/raw/ntb \
                           @TOPDIR@/lib/eal/include \
                           @TOPDIR@/lib/eal/include/generic \
                           @TOPDIR@/lib/acl \
-- 
2.43.0

[PATCH v2 7/7] doc: add missing headers to doxy-api-index.md

[Marat Khalili]

Make sure all public headers are listed in `doxy-api-index.md` to be
reachable in HTML version. Presumably each of them should contain at
least a general file description, though this is not checked now.

The only header still omitted is rte_pmd_bphy.h since it needs writing
multiple new doxygen descriptions which could not be done on the spot,
so it is excluded from the build (tracked by bug 1962 in bugzilla).

Signed-off-by: Marat Khalili <marat.khalili@huawei.com>
---
 doc/api/doxy-api-index.md | 120 +++++++++++++++++++++++++++++++++-----
 1 file changed, 105 insertions(+), 15 deletions(-)

diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index 929604211946..f5c084c2c5a9 100644
--- a/doc/api/doxy-api-index.md
+++ b/doc/api/doxy-api-index.md
@@ -9,14 +9,24 @@ API
 The public API headers are grouped by topics:
 
 - **device**:
+  [bus](@ref rte_bus.h),
   [dev](@ref rte_dev.h),
   [ethdev](@ref rte_ethdev.h),
+  [cman](@ref rte_cman.h),
+  [ethdev trace fp](@ref rte_ethdev_trace_fp.h),
+  [dev info](@ref rte_dev_info.h),
   [ethctrl](@ref rte_eth_ctrl.h),
   [rte_flow](@ref rte_flow.h),
   [rte_tm](@ref rte_tm.h),
   [rte_mtr](@ref rte_mtr.h),
   [bbdev](@ref rte_bbdev.h),
+  [bbdev op](@ref rte_bbdev_op.h),
+  [bbdev trace fp](@ref rte_bbdev_trace_fp.h),
   [cryptodev](@ref rte_cryptodev.h),
+  [crypto](@ref rte_crypto.h),
+  [crypto sym](@ref rte_crypto_sym.h),
+  [crypto asym](@ref rte_crypto_asym.h),
+  [cryptodev trace fp](@ref rte_cryptodev_trace_fp.h),
   [security](@ref rte_security.h),
   [compressdev](@ref rte_compressdev.h),
   [compress](@ref rte_comp.h),
@@ -25,6 +35,8 @@ The public API headers are grouped by topics:
   [dmadev](@ref rte_dmadev.h),
   [gpudev](@ref rte_gpudev.h),
   [eventdev](@ref rte_eventdev.h),
+  [event ring](@ref rte_event_ring.h),
+  [eventdev trace fp](@ref rte_eventdev_trace_fp.h),
   [event_eth_rx_adapter](@ref rte_event_eth_rx_adapter.h),
   [event_eth_tx_adapter](@ref rte_event_eth_tx_adapter.h),
   [event_timer_adapter](@ref rte_event_timer_adapter.h),
@@ -33,17 +45,27 @@ The public API headers are grouped by topics:
   [event_vector_adapter](@ref rte_event_vector_adapter.h),
   [rawdev](@ref rte_rawdev.h),
   [metrics](@ref rte_metrics.h),
+  [metrics telemetry](@ref rte_metrics_telemetry.h),
   [bitrate](@ref rte_bitrate.h),
   [latency](@ref rte_latencystats.h),
   [devargs](@ref rte_devargs.h),
   [PCI](@ref rte_pci.h),
+  [PCI dev feature defs](@ref rte_pci_dev_feature_defs.h),
+  [PCI dev features](@ref rte_pci_dev_features.h),
+  [bus PCI](@ref rte_bus_pci.h),
   [vdev](@ref rte_bus_vdev.h),
+  [vmbus](@ref rte_bus_vmbus.h),
+  [vmbus reg](@ref rte_vmbus_reg.h),
   [vfio](@ref rte_vfio.h)
 
 - **device specific**:
   [softnic](@ref rte_eth_softnic.h),
   [bond](@ref rte_eth_bond.h),
+  [bond 8023ad](@ref rte_eth_bond_8023ad.h),
   [vhost](@ref rte_vhost.h),
+  [vhost async](@ref rte_vhost_async.h),
+  [vhost crypto](@ref rte_vhost_crypto.h),
+  [eth vhost](@ref rte_eth_vhost.h),
   [vdpa](@ref rte_vdpa.h),
   [ixgbe](@ref rte_pmd_ixgbe.h),
   [i40e](@ref rte_pmd_i40e.h),
@@ -53,6 +75,7 @@ The public API headers are grouped by topics:
   [cnxk_crypto](@ref rte_pmd_cnxk_crypto.h),
   [cnxk_eventdev](@ref rte_pmd_cnxk_eventdev.h),
   [cnxk_mempool](@ref rte_pmd_cnxk_mempool.h),
+  [cnxk gpio](@ref rte_pmd_cnxk_gpio.h),
   [dpaa](@ref rte_pmd_dpaa.h),
   [dpaa2](@ref rte_pmd_dpaa2.h),
   [mlx5](@ref rte_pmd_mlx5.h),
@@ -60,25 +83,40 @@ The public API headers are grouped by topics:
   [dpaa2_cmdif](@ref rte_pmd_dpaa2_cmdif.h),
   [dpaax_qdma](@ref rte_pmd_dpaax_qdma.h),
   [crypto_scheduler](@ref rte_cryptodev_scheduler.h),
+  [crypto scheduler operations](@ref rte_cryptodev_scheduler_operations.h),
   [dlb2](@ref rte_pmd_dlb2.h),
-  [ifpga](@ref rte_pmd_ifpga.h)
+  [ifpga](@ref rte_pmd_ifpga.h),
+  [avp common](@ref rte_avp_common.h),
+  [avp fifo](@ref rte_avp_fifo.h),
+  [ntnic](@ref rte_pmd_ntnic.h),
+  [ring](@ref rte_eth_ring.h),
+  [txgbe](@ref rte_pmd_txgbe.h),
+  [ntb](@ref rte_pmd_ntb.h),
+  [acc cfg](@ref rte_acc_cfg.h),
+  [acc common cfg](@ref rte_acc_common_cfg.h),
+  [fpga 5gnr fec](@ref rte_pmd_fpga_5gnr_fec.h)
 
 - **memory**:
   [per-lcore](@ref rte_per_lcore.h),
   [lcore variables](@ref rte_lcore_var.h),
+  [EAL memconfig](@ref rte_eal_memconfig.h),
   [memseg](@ref rte_memory.h),
   [memzone](@ref rte_memzone.h),
   [mempool](@ref rte_mempool.h),
+  [mempool trace fp](@ref rte_mempool_trace_fp.h),
   [malloc](@ref rte_malloc.h),
   [memcpy](@ref rte_memcpy.h)
 
 - **timers**:
   [cycles](@ref rte_cycles.h),
+  [time](@ref rte_time.h),
   [timer](@ref rte_timer.h),
   [alarm](@ref rte_alarm.h)
 
 - **locks**:
   [atomic](@ref rte_atomic.h),
+  [stdatomic](@ref rte_stdatomic.h),
+  [lock annotations](@ref rte_lock_annotations.h),
   [mcslock](@ref rte_mcslock.h),
   [pflock](@ref rte_pflock.h),
   [rwlock](@ref rte_rwlock.h),
@@ -103,13 +141,18 @@ The public API headers are grouped by topics:
   [launch](@ref rte_launch.h),
   [lcore](@ref rte_lcore.h),
   [service cores](@ref rte_service.h),
+  [service component](@ref rte_service_component.h),
   [keepalive](@ref rte_keepalive.h),
   [power/freq](@ref rte_power_cpufreq.h),
   [power/uncore](@ref rte_power_uncore.h),
-  [PMD power](@ref rte_power_pmd_mgmt.h)
+  [PMD power](@ref rte_power_pmd_mgmt.h),
+  [power guest channel](@ref rte_power_guest_channel.h),
+  [power qos](@ref rte_power_qos.h)
 
 - **layers**:
   [ethernet](@ref rte_ether.h),
+  [net](@ref rte_net.h),
+  [net CRC](@ref rte_net_crc.h),
   [MACsec](@ref rte_macsec.h),
   [ARP](@ref rte_arp.h),
   [HIGIG](@ref rte_higig.h),
@@ -119,6 +162,7 @@ The public API headers are grouped by topics:
   [IPsec group](@ref rte_ipsec_group.h),
   [IPsec SA](@ref rte_ipsec_sa.h),
   [IPsec SAD](@ref rte_ipsec_sad.h),
+  [IP](@ref rte_ip.h),
   [IPv4](@ref rte_ip4.h),
   [IPv6](@ref rte_ip6.h),
   [frag/reass](@ref rte_ip_frag.h),
@@ -139,12 +183,15 @@ The public API headers are grouped by topics:
   [PDCP](@ref rte_pdcp.h),
   [L2TPv2](@ref rte_l2tpv2.h),
   [PPP](@ref rte_ppp.h),
-  [IB](@ref rte_ib.h)
+  [IB](@ref rte_ib.h),
+  [PTP](@ref rte_ptp.h)
 
 - **QoS**:
   [metering](@ref rte_meter.h),
   [scheduler](@ref rte_sched.h),
-  [RED congestion](@ref rte_red.h)
+  [sched common](@ref rte_sched_common.h),
+  [RED congestion](@ref rte_red.h),
+  [PIE](@ref rte_pie.h)
 
 - **routing**:
   [LPM IPv4 route](@ref rte_lpm.h),
@@ -168,18 +215,28 @@ The public API headers are grouped by topics:
   [distributor](@ref rte_distributor.h),
   [EFD](@ref rte_efd.h),
   [ACL](@ref rte_acl.h),
-  [member](@ref rte_member.h),
-  [BPF](@ref rte_bpf.h)
+  [ACL osdep](@ref rte_acl_osdep.h),
+  [member](@ref rte_member.h)
+  * BPF:
+    [load and execute](@ref rte_bpf.h),
+    [machine code](@ref bpf_def.h),
+    [port filters](@ref rte_bpf_ethdev.h),
+    [validate debug](@ref rte_bpf_validate_debug.h)
 
 - **containers**:
   [mbuf](@ref rte_mbuf.h),
+  [mbuf core](@ref rte_mbuf_core.h),
+  [mbuf ptype](@ref rte_mbuf_ptype.h),
+  [mbuf dyn](@ref rte_mbuf_dyn.h),
+  [mbuf history](@ref rte_mbuf_history.h),
   [mbuf pool ops](@ref rte_mbuf_pool_ops.h),
   [ring](@ref rte_ring.h),
   [soring](@ref rte_soring.h),
   [stack](@ref rte_stack.h),
   [tailq](@ref rte_tailq.h),
   [bitset](@ref rte_bitset.h),
-  [bitmap](@ref rte_bitmap.h)
+  [bitmap](@ref rte_bitmap.h),
+  [fbarray](@ref rte_fbarray.h)
 
 - **packet framework**:
   * [port](@ref rte_port.h):
@@ -188,21 +245,28 @@ The public API headers are grouped by topics:
     [frag](@ref rte_port_frag.h),
     [reass](@ref rte_port_ras.h),
     [sched](@ref rte_port_sched.h),
-    [src/sink](@ref rte_port_source_sink.h)
+    [src/sink](@ref rte_port_source_sink.h),
+    [fd](@ref rte_port_fd.h),
+    [sym crypto](@ref rte_port_sym_crypto.h),
+    [eventdev](@ref rte_port_eventdev.h)
   * [table](@ref rte_table.h):
     [lpm IPv4](@ref rte_table_lpm.h),
     [lpm IPv6](@ref rte_table_lpm_ipv6.h),
     [ACL](@ref rte_table_acl.h),
     [hash](@ref rte_table_hash.h),
     [array](@ref rte_table_array.h),
-    [stub](@ref rte_table_stub.h)
+    [stub](@ref rte_table_stub.h),
+    [LRU](@ref rte_lru.h),
+    [hash cuckoo](@ref rte_table_hash_cuckoo.h),
+    [hash func](@ref rte_table_hash_func.h)
   * [pipeline](@ref rte_pipeline.h)
     [port_in_action](@ref rte_port_in_action.h)
     [table_action](@ref rte_table_action.h)
   * SWX pipeline:
     [control](@ref rte_swx_ctl.h),
     [extern](@ref rte_swx_extern.h),
-    [pipeline](@ref rte_swx_pipeline.h)
+    [pipeline](@ref rte_swx_pipeline.h),
+    [IPsec](@ref rte_swx_ipsec.h)
   * SWX port:
     [port](@ref rte_swx_port.h),
     [ethdev](@ref rte_swx_port_ethdev.h),
@@ -211,8 +275,11 @@ The public API headers are grouped by topics:
     [src/sink](@ref rte_swx_port_source_sink.h)
   * SWX table:
     [table](@ref rte_swx_table.h),
-    [table_em](@ref rte_swx_table_em.h)
-    [table_wm](@ref rte_swx_table_wm.h)
+    [table_em](@ref rte_swx_table_em.h),
+    [table_wm](@ref rte_swx_table_wm.h),
+    [hash func](@ref rte_swx_hash_func.h),
+    [table learner](@ref rte_swx_table_learner.h),
+    [table selector](@ref rte_swx_table_selector.h)
   * [graph](@ref rte_graph.h):
     [graph_worker](@ref rte_graph_worker.h),
     [graph_feature_arc](@ref rte_graph_feature_arc.h),
@@ -222,7 +289,22 @@ The public API headers are grouped by topics:
     [ip4_node](@ref rte_node_ip4_api.h),
     [ip6_node](@ref rte_node_ip6_api.h),
     [udp4_input_node](@ref rte_node_udp4_input_api.h),
-    [mbuf_dynfield](@ref rte_node_mbuf_dynfield.h)
+    [mbuf_dynfield](@ref rte_node_mbuf_dynfield.h),
+    [pkt cls api](@ref rte_node_pkt_cls_api.h)
+
+- **cmdline**:
+  [cmdline](@ref cmdline.h),
+  [parse](@ref cmdline_parse.h),
+  [parse num](@ref cmdline_parse_num.h),
+  [parse bool](@ref cmdline_parse_bool.h),
+  [parse ipaddr](@ref cmdline_parse_ipaddr.h),
+  [parse etheraddr](@ref cmdline_parse_etheraddr.h),
+  [parse string](@ref cmdline_parse_string.h),
+  [parse portlist](@ref cmdline_parse_portlist.h),
+  [rdline](@ref cmdline_rdline.h),
+  [vt100](@ref cmdline_vt100.h),
+  [socket](@ref cmdline_socket.h),
+  [cirbuf](@ref cmdline_cirbuf.h)
 
 - **basic**:
   [bitops](@ref rte_bitops.h),
@@ -234,7 +316,9 @@ The public API headers are grouped by topics:
   [argument parsing](@ref rte_argparse.h),
   [ptr_compress](@ref rte_ptr_compress.h),
   [string](@ref rte_string_fns.h),
-  [thread](@ref rte_thread.h)
+  [thread](@ref rte_thread.h),
+  [reciprocal](@ref rte_reciprocal.h),
+  [UUID](@ref rte_uuid.h)
 
 - **debug**:
   [jobstats](@ref rte_jobstats.h),
@@ -247,11 +331,17 @@ The public API headers are grouped by topics:
   [log](@ref rte_log.h),
   [errno](@ref rte_errno.h),
   [trace](@ref rte_trace.h),
-  [trace_point](@ref rte_trace_point.h)
+  [EAL trace](@ref rte_eal_trace.h),
+  [trace_point](@ref rte_trace_point.h),
+  [trace point register](@ref rte_trace_point_register.h)
 
 - **misc**:
   [EAL config](@ref rte_eal.h),
+  [class](@ref rte_class.h),
   [common](@ref rte_common.h),
+  [epoll](@ref rte_epoll.h),
+  [hypervisor](@ref rte_hypervisor.h),
+  [OS](@ref rte_os.h),
   [experimental APIs](@ref rte_compat.h),
   [version](@ref rte_version.h)
 
-- 
2.43.0

RE: [PATCH v2 0/7] doc: build for all public headers

[Marat Khalili]

> Marat Khalili (7):
>   doc: detect ignored public headers
>   doc: document rte_os.h
>   doc: fix typos in rte_bus_pci.h
>   doc: fix typos in rte_bus_vmbus.h

Newer version of doxygen in CI discovered additional issues in
rte_avp_common.h, will address in v3 tomorrow.

>   doc: add missing globs to doxy-api.conf.in
>   doc: add missing drivers to doxy-api.conf.in
>   doc: add missing headers to doxy-api-index.md