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
