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

[Burakov, Anatoly]

On 11/30/2025 4:44 PM, Thomas Monjalon wrote:
> 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

Hi Thomas,

Agreed on all points. I'll prepare a v2 addressing feedback. Thanks for 
your review!

-- 
Thanks,
Anatoly