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 <[email protected]> > --- > > 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
