[dpdk-dev] [PATCH] doc: document the new devargs syntax

[Gaëtan Rivet]

Hi Yuanhan,

On Tue, Jan 16, 2018 at 10:50:18PM +0800, Yuanhan Liu wrote:
> This patch documents the new devargs syntax, which is going to be
> implemented in DPDK v18.05.
> 
> The new devargs proposal is introduced for having a consistent
> interface for:
> 
> - whitelisting/blacklisting devices
> - identifying ports
> - attaching/detaching devices
> 
> Please check the patch content for the details. Also, here is link
> for the background:
>     http://dpdk.org/ml/archives/dev/2017-November/082600.html
> 
> This syntax is suggestd by Thomas:
>     http://dpdk.org/ml/archives/dev/2017-December/084234.html
> 
> Signed-off-by: Yuanhan Liu <yliu at fridaylinux.org>
> ---
>  doc/guides/prog_guide/env_abstraction_layer.rst | 34 +++++++++++++++++++++++++
>  1 file changed, 34 insertions(+)
> 
> diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
> index 34d871c..12f37f2 100644
> --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> @@ -213,6 +213,40 @@ device having emitted a Device Removal Event. In such case, calling
>  callback. Care must be taken not to close the device from the interrupt handler
>  context. It is necessary to reschedule such closing operation.
>  
> +Devargs
> +~~~~~~~
> +
> +The ``devargs`` can be used for whitelisting/blacklisting devices, identifying
> +DPDK ports and attaching/deatching devices. They all share the same syntax.
> +
> +It is split in 3 categories, where almost everything is optional key/value pairs:
> +
> +* bus (pci, vdev, vmbus, fslmc, etc)
> +* class (eth, crypto, etc)
> +* driver (i40e, mlx5, virtio, etc)
> +
> +The key/value pair describing the category scope is mandatory and must be the
> +first pair in the category properties. Example: bus=pci, must be placed before
> +id=0000:01:00.0.
> +
> +The syntax has below rules:
> +
> +* Between categories, the separator is a slash.
> +* Inside a category, the separator is a comma.
> +* Inside a key/value pair, the separator is an equal sign.
> +* Each category can be used alone.
> +
> +Here is an example with all categories::
> +
> +    bus=pci,id=0000:01:00.0/class=eth,mac=00:11:22:33:44:55/driver=PMD_NAME,driverspecificproperty=VALUE
> +

It might be a nitpick, but the driver specific properties might not
follow the key/value pair syntax. At least for the fail-safe, a custom
parsing needs to happen. I think vdev in general will need flexibility.

There could be a note that after the comma past the eventual
"driver=xxxx" pair, the syntax is driver-specific and might not follow
the equal-separated key/value pair syntax.

-- 
Gaëtan Rivet
6WIND