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

[Thomas Monjalon <thomas@monjalon.net>]

14/11/2025 13:13, Anatoly Burakov:
> 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.

Thank you for writing this. It is really important.

> +* **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. **Simplified syntax** - For common case targeting a specific device.
> +2. **Multi-layer syntax** - For device filtering by bus, class, or driver.

I would prefer we see the last one as a generic syntax.
Others are shortcuts.

> +
> +
> +Devargs Syntax
> +--------------
> +
> +Device-centric syntax
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +In most cases, devargs can be used with simplified format that targets specific devices:
> +
> +.. code-block:: none
> +
> +   [bus:]device_identifier[,arg1=val1,arg2=val2,...]
[...]
> +Driver-centric Syntax
> +~~~~~~~~~~~~~~~~~~~~~

If you give a PCI address or a vdev name, it targets a device.

> +
> +For advanced use cases that need to pass arguments to bus and/or class layers, or when matching multiple devices is required, DPDK supports a multi-layer syntax with three slash-separated segments:
> +
> +.. code-block:: none
> +
> +   bus=<busname>,<bus_args>/class=<classname>,<class_args>/driver=<drvname>,<driver_args>

I think we should present this syntax first, with supported bus and class args.
Then we can present shortcuts equivalents with the old syntax.

[...]
> +Summary
> +-------
> +
> +Device arguments provide a flexible and standardized way to specify and configure devices in DPDK:
> +
> +* **Unified syntax**: Works across different bus types
> +* **Runtime and initialization**: Can be used both at EAL init and for hotplug
> +* **Driver configuration**: Supports arbitrary driver-specific parameters
> +* **Complex specifications**: Multi-layer syntax allows device filtering and configuration at bus, class, and driver levels

I'm not sur a summary is a good idea in such a documentation.
General statements are better viewed as intro.

You did a good job, but I think we should move things around to avoid confusion.
Please let's work on it together.
Thank you