Re: [PATCH v2 1/2] doc: add devargs documentation

[Bruce Richardson <bruce.richardson@intel.com>]

On Fri, Dec 19, 2025 at 01:25:55PM +0000, Anatoly Burakov wrote:
> Currently, the devargs syntax documentation is missing from the
> programmer's guide, and is only documented implicitly through the devargs
> API headers. Add a detailed description of the two supported devargs
> syntaxes.
> 
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
> ---
> 
> Notes:
>     v2:
>     - Made generic syntax the primary syntax
>     - Removed summary
>     - Moved index link to after ethdev/index
> 
>  doc/guides/prog_guide/dev_args.rst | 234 +++++++++++++++++++++++++++++
>  doc/guides/prog_guide/index.rst    |   1 +
>  2 files changed, 235 insertions(+)
>  create mode 100644 doc/guides/prog_guide/dev_args.rst
> 
> diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
> new file mode 100644
> index 0000000000..a8025d383b
> --- /dev/null
> +++ b/doc/guides/prog_guide/dev_args.rst
> @@ -0,0 +1,234 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2025 Intel Corporation.
> +
> +.. _device_arguments:
> +
> +Device Arguments
> +================
> +
> +Introduction
> +------------
> +
> +Device arguments (devargs) provide a standardized way to specify and configure devices in DPDK applications.
> +Devargs are used both at EAL initialization time (via command-line options) and at runtime (via hotplug APIs) to identify devices and pass configuration parameters to them.
> +
> +A devargs string can specify identifiers and arguments at multiple levels:
> +
> +* **Bus identifier and arguments**: Which bus handles the device (e.g., ``pci``, ``vdev``) and bus-level parameters
> +* **Class identifier and arguments**: Device class (e.g., ``eth``, ``crypto``) and class-level parameters
> +* **Driver identifier and arguments**: The specific driver and its driver-specific parameters
> +
> +DPDK supports two devargs syntaxes:
> +
> +1. **Multi-layer syntax** - Generic syntax for device filtering by bus, class, or driver.
> +2. **Simplified syntax** - Legacy simplified syntax.
> +
> +
> +Devargs Syntax
> +--------------
> +
> +Generic Syntax
> +~~~~~~~~~~~~~~
> +
> +Generic devargs syntax is meant to cover all use cases supported by devargs infrastructure, such as passing arguments to various layers or matching multiple devices.
> +The basic syntax format is as follows:
> +
> +.. code-block:: none
> +
> +   bus=<busname>,<bus_args>/class=<classname>,<class_args>/driver=<drvname>,<driver_args>
> +
> +This allows the user to specify:
> +
> +* ``bus`` layer: bus identifier, as well as bus-level arguments
> +* ``class`` layer: class identifier, as well as class-level arguments
> +* ``driver`` layer: driver identifier, as well as driver-specific parameters
> +
> +.. note::
> +   By default, multi-layer syntax is driver-centric and will apply to all devices using a particular bus, class, and driver combination.
> +   To target a specific device, a device-identifying argument can be provided to the bus layer. The specific key depends on the bus:
> +   for PCI use ``addr=`` (e.g. ``bus=pci,addr=0000:02:00.0``), for most other buses use ``name=`` (e.g. ``bus=vdev,name=net_ring0``).
> +
> +**Example**:
> +
> +.. code-block:: none
> +
> +   bus=pci/class=eth/driver=ice,representor=[0-3]
> +
> +The above example will pass "representor=[0-3]" devarg to each device matching the provided criteria (PCI bus, Ethernet class, in use by ``ice`` driver).
> +
> +Simplified syntax
> +~~~~~~~~~~~~~~~~~
> +
> +In cases where the full syntax is not required, devargs can be used with simplified format that targets specific devices only:
> +
> +.. code-block:: none
> +
> +   [bus:]device_identifier[,arg1=val1,arg2=val2,...]
> +
> +Where:
> +
> +* ``bus:`` is an optional prefix specifying the bus name (pci, vdev, auxiliary, etc.)
> +* ``device_identifier`` uniquely identifies the device on its bus
> +* ``arg1=val1,arg2=val2,...`` are optional driver-specific configuration parameters
> +
> +The arguments are provided to the driver, but the driver name itself is inferred from the device and does not need to be specified.
> +
> +**Examples**:
> +
> +.. code-block:: none
> +
> +   0000:02:00.0                          # PCI device, no arguments
> +   0000:02:00.0,txq_inline=128           # PCI device with driver arguments

I would look to include some examples with the "0000:" omitted at the start
of the PCI addresses, since that shortened form should work.

/Bruce