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

Message ID 1516114218-21501-1-git-send-email-yliu@fridaylinux.org
State New
Delegated to: Thomas Monjalon
Headers show

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation fail Compilation issues

Commit Message

Yuanhan Liu Jan. 16, 2018, 2:50 p.m. UTC
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@fridaylinux.org>
---
 doc/guides/prog_guide/env_abstraction_layer.rst | 34 +++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

Comments

Mcnamara, John Jan. 16, 2018, 4:33 p.m. UTC | #1
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Yuanhan Liu
> Sent: Tuesday, January 16, 2018 2:50 PM
> To: dev@dpdk.org
> Cc: Thomas Monjalon <thomas@monjalon.net>; Yuanhan Liu
> <yliu@fridaylinux.org>
> Subject: [dpdk-dev] [PATCH] doc: document the new devargs syntax
> 
> 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@fridaylinux.org>

Initially I thought that a semi-colon would be better (more common) than a forward slash as a category separator but the forward slash is a bit clearer.

Either way the doc looks good, so:

Acked-by: John McNamara <john.mcnamara@intel.com>
Gaëtan Rivet Jan. 16, 2018, 11:19 p.m. UTC | #2
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@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.
Thomas Monjalon Jan. 16, 2018, 11:22 p.m. UTC | #3
17/01/2018 00:19, Gaëtan Rivet:
> Hi Yuanhan,
> 
> On Tue, Jan 16, 2018 at 10:50:18PM +0800, Yuanhan Liu wrote:
> > +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.

What is more flexible than key/value?

> 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.

Please give an example.
Gaëtan Rivet Jan. 16, 2018, 11:46 p.m. UTC | #4
On Wed, Jan 17, 2018 at 12:22:43AM +0100, Thomas Monjalon wrote:
> 17/01/2018 00:19, Gaëtan Rivet:
> > Hi Yuanhan,
> > 
> > On Tue, Jan 16, 2018 at 10:50:18PM +0800, Yuanhan Liu wrote:
> > > +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.
> 
> What is more flexible than key/value?
> 

fail-safe does not need something more flexible, but different.
It needs to define substrings describing whole devices, thus substrings
following the aforementioned syntax.

I choose to use ( and ) as markers of beginning and end of the "special
sub-device part that we need to skip for the moment". In the end, I need
a way to mark the beginning and the end of a parameter. Without this,
the next parameter would be considered as the parameter of the
sub-device, not of the fail-safe.

= separated key/value pair does not allow for this (or with very
convoluted additional rules to the syntax).

> > 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.
> 
> Please give an example.

bus=vdev/driver=failsafe,dev(bus=pci,id=00:02.0),fd(/some/file/)

Here, without some kind of "end-of-parameter" mark, fd() would be
considered as a new parameter of the sub-device 00:02.0

--------------

And while I'm at it, there is an ambiguity that might need to be defined
before the whole shebang is implemented: whether the parameters
positions are meaningful or not. Currently some drivers might consider their
parameters to mean different things depending on their order of appearance.

It could help to explicitly say that the order is asemic and should not
be considered by drivers.

Why this is important: I think that depending on the new rte_devargs
representation, it could be beneficial to have a canonical representation
of an rte_devargs: given an arbitrary string given by users, the devargs
could then be rewritten in a determinist way, which would help implementing
comparison, assignment, and some other operations.

However, for this canonicalization to be possible, order needs to be
explicitly said to be meaningless.
Thomas Monjalon Jan. 17, 2018, 12:03 a.m. UTC | #5
17/01/2018 00:46, Gaëtan Rivet:
> On Wed, Jan 17, 2018 at 12:22:43AM +0100, Thomas Monjalon wrote:
> > 17/01/2018 00:19, Gaëtan Rivet:
> > > 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.
> > 
> > What is more flexible than key/value?
> 
> fail-safe does not need something more flexible, but different.
> It needs to define substrings describing whole devices, thus substrings
> following the aforementioned syntax.
> 
> I choose to use ( and ) as markers of beginning and end of the "special
> sub-device part that we need to skip for the moment". In the end, I need
> a way to mark the beginning and the end of a parameter. Without this,
> the next parameter would be considered as the parameter of the
> sub-device, not of the fail-safe.
> 
> = separated key/value pair does not allow for this (or with very
> convoluted additional rules to the syntax).

OK, I agree we need beginning and end markers.
I wonder whether we should consider devargs as a specific case of value.
Maybe we just want to allow using marker characters inside values.
So we can use parens or quotes to optionnaly protect the values.
But as the shell developers learned, parens are better than quotes in
the long term because it allows nested expressions.

> > > 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.
> > 
> > Please give an example.
> 
> bus=vdev/driver=failsafe,dev(bus=pci,id=00:02.0),fd(/some/file/)
> 
> Here, without some kind of "end-of-parameter" mark, fd() would be
> considered as a new parameter of the sub-device 00:02.0

Right.
I think an equal sign is missing between "dev" and parenthesis.

> --------------
> 
> And while I'm at it, there is an ambiguity that might need to be defined
> before the whole shebang is implemented: whether the parameters
> positions are meaningful or not. Currently some drivers might consider their
> parameters to mean different things depending on their order of appearance.
> 
> It could help to explicitly say that the order is asemic and should not
> be considered by drivers.
> 
> Why this is important: I think that depending on the new rte_devargs
> representation, it could be beneficial to have a canonical representation
> of an rte_devargs: given an arbitrary string given by users, the devargs
> could then be rewritten in a determinist way, which would help implementing
> comparison, assignment, and some other operations.
> 
> However, for this canonicalization to be possible, order needs to be
> explicitly said to be meaningless.

Good idea. I vote for meaningless ordering, except the first property
of each category, which describes the category.
Gaëtan Rivet Jan. 17, 2018, 9:37 a.m. UTC | #6
Hi Thomas,

On Wed, Jan 17, 2018 at 01:03:50AM +0100, Thomas Monjalon wrote:
> 17/01/2018 00:46, Gaëtan Rivet:
> > On Wed, Jan 17, 2018 at 12:22:43AM +0100, Thomas Monjalon wrote:
> > > 17/01/2018 00:19, Gaëtan Rivet:
> > > > 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.
> > > 
> > > What is more flexible than key/value?
> > 
> > fail-safe does not need something more flexible, but different.
> > It needs to define substrings describing whole devices, thus substrings
> > following the aforementioned syntax.
> > 
> > I choose to use ( and ) as markers of beginning and end of the "special
> > sub-device part that we need to skip for the moment". In the end, I need
> > a way to mark the beginning and the end of a parameter. Without this,
> > the next parameter would be considered as the parameter of the
> > sub-device, not of the fail-safe.
> > 
> > = separated key/value pair does not allow for this (or with very
> > convoluted additional rules to the syntax).
> 
> OK, I agree we need beginning and end markers.
> I wonder whether we should consider devargs as a specific case of value.

Not sure I follow: you would want to consider a different syntax whether
we are defining or identifying a device?

This seems dangerous to me, a single unifying syntax should be used. But
I probably misunderstood.

> Maybe we just want to allow using marker characters inside values.

That would be nice. That, or allow drivers to use arbitrary parameters,
by freeing the last field (past the "driver" token of the last
category).

Do you have a justification for restricting drivers parameters? Why
couldn't this only be structured by commas (or any separators), and otherwise
left to the drivers to do as they see fit?

> So we can use parens or quotes to optionnaly protect the values.
> But as the shell developers learned, parens are better than quotes in
> the long term because it allows nested expressions.
> 

This was the initial reason for using parens in the fail-safe, yes.

However, any paired symbol could do, and parens do not actually play
nice within a command in shell (the shell keep trying to capture the
parens for its own parsing).

The usual alternative was to use {}. I'd vote for this.

> > > > 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.
> > > 
> > > Please give an example.
> > 
> > bus=vdev/driver=failsafe,dev(bus=pci,id=00:02.0),fd(/some/file/)
> > 
> > Here, without some kind of "end-of-parameter" mark, fd() would be
> > considered as a new parameter of the sub-device 00:02.0
> 
> Right.
> I think an equal sign is missing between "dev" and parenthesis.
> 
> > --------------
> > 
> > And while I'm at it, there is an ambiguity that might need to be defined
> > before the whole shebang is implemented: whether the parameters
> > positions are meaningful or not. Currently some drivers might consider their
> > parameters to mean different things depending on their order of appearance.
> > 
> > It could help to explicitly say that the order is asemic and should not
> > be considered by drivers.
> > 
> > Why this is important: I think that depending on the new rte_devargs
> > representation, it could be beneficial to have a canonical representation
> > of an rte_devargs: given an arbitrary string given by users, the devargs
> > could then be rewritten in a determinist way, which would help implementing
> > comparison, assignment, and some other operations.
> > 
> > However, for this canonicalization to be possible, order needs to be
> > explicitly said to be meaningless.
> 
> Good idea. I vote for meaningless ordering, except the first property
> of each category, which describes the category.

Agreed.
Thomas Monjalon Jan. 17, 2018, 9:43 a.m. UTC | #7
17/01/2018 10:37, Gaëtan Rivet:
> Hi Thomas,
> 
> On Wed, Jan 17, 2018 at 01:03:50AM +0100, Thomas Monjalon wrote:
> > 17/01/2018 00:46, Gaëtan Rivet:
> > > On Wed, Jan 17, 2018 at 12:22:43AM +0100, Thomas Monjalon wrote:
> > > > 17/01/2018 00:19, Gaëtan Rivet:
> > > > > 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.
> > > > 
> > > > What is more flexible than key/value?
> > > 
> > > fail-safe does not need something more flexible, but different.
> > > It needs to define substrings describing whole devices, thus substrings
> > > following the aforementioned syntax.
> > > 
> > > I choose to use ( and ) as markers of beginning and end of the "special
> > > sub-device part that we need to skip for the moment". In the end, I need
> > > a way to mark the beginning and the end of a parameter. Without this,
> > > the next parameter would be considered as the parameter of the
> > > sub-device, not of the fail-safe.
> > > 
> > > = separated key/value pair does not allow for this (or with very
> > > convoluted additional rules to the syntax).
> > 
> > OK, I agree we need beginning and end markers.
> > I wonder whether we should consider devargs as a specific case of value.
> 
> Not sure I follow: you would want to consider a different syntax whether
> we are defining or identifying a device?
> 
> This seems dangerous to me, a single unifying syntax should be used. But
> I probably misunderstood.

No, I'm just saying that it is a more generic problem:
values can contain some characters used in this syntax.
So yes, we need to protect them with parens (or braces).

> > Maybe we just want to allow using marker characters inside values.
> 
> That would be nice. That, or allow drivers to use arbitrary parameters,
> by freeing the last field (past the "driver" token of the last
> category).
> 
> Do you have a justification for restricting drivers parameters? Why
> couldn't this only be structured by commas (or any separators), and otherwise
> left to the drivers to do as they see fit?

User experience.
I don't think key/value is restricting.

> > So we can use parens or quotes to optionnaly protect the values.
> > But as the shell developers learned, parens are better than quotes in
> > the long term because it allows nested expressions.
> 
> This was the initial reason for using parens in the fail-safe, yes.
> 
> However, any paired symbol could do, and parens do not actually play
> nice within a command in shell (the shell keep trying to capture the
> parens for its own parsing).
> 
> The usual alternative was to use {}. I'd vote for this.

Yes braces are also OK.

> > > > > 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.
> > > > 
> > > > Please give an example.
> > > 
> > > bus=vdev/driver=failsafe,dev(bus=pci,id=00:02.0),fd(/some/file/)
> > > 
> > > Here, without some kind of "end-of-parameter" mark, fd() would be
> > > considered as a new parameter of the sub-device 00:02.0
> > 
> > Right.
> > I think an equal sign is missing between "dev" and parenthesis.
> > 
> > > --------------
> > > 
> > > And while I'm at it, there is an ambiguity that might need to be defined
> > > before the whole shebang is implemented: whether the parameters
> > > positions are meaningful or not. Currently some drivers might consider their
> > > parameters to mean different things depending on their order of appearance.
> > > 
> > > It could help to explicitly say that the order is asemic and should not
> > > be considered by drivers.
> > > 
> > > Why this is important: I think that depending on the new rte_devargs
> > > representation, it could be beneficial to have a canonical representation
> > > of an rte_devargs: given an arbitrary string given by users, the devargs
> > > could then be rewritten in a determinist way, which would help implementing
> > > comparison, assignment, and some other operations.
> > > 
> > > However, for this canonicalization to be possible, order needs to be
> > > explicitly said to be meaningless.
> > 
> > Good idea. I vote for meaningless ordering, except the first property
> > of each category, which describes the category.
> 
> Agreed.
Gaëtan Rivet Jan. 17, 2018, 10:11 a.m. UTC | #8
A new suggestion about the syntax.

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@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 can also be simple like below::
> +
> +    class=eth,mac=00:11:22:33:44:55
> +

1/

All categories are named, their order is known, and their name comes
first.

It is thus possible to declare categories unambiguously without using
the field name first.

    pci,id=0000:01:00.0/eth,mac=00:11:22:33:44:55/PMD_NAME,driverspecificproperty=VALUE
    eth,mac=00:11:22:33:44:55
    pci,id=00:02.0

The only requirement for this to hold is for the layer names not to collide
(bus, dev, drivers), which seems like an easy enough requirement to follow.

-------------------------------

> +A device is identified when every properties are matched. Before device is
> +probed, only the bus category is relevant.
> + 

2/

When using the following ID:

    class=eth,mac=00:11:22:33:44:55

The bus is skipped, as well as the driver.
Does that mean that it is allowed to skip any layer, as long as the
resulting match is unambiguous?

What I mean is that a user could then do

    driver=net_ring

To find the one port using the driver net_ring.

-------------------------------

3/

The driver would generate a name for the eth_dev structure.
I guess it would be possible to identify the device with

    class=eth,name=net_ring0

Or something. Where does the rte_dev name appears? Is it a property
of the bus layer? Is it merged with the eth_dev name? If so, which one
will stay, the rte_dev name or the eth_dev name?
Thomas Monjalon Jan. 17, 2018, 10:54 a.m. UTC | #9
17/01/2018 11:11, Gaëtan Rivet:
> A new suggestion about the syntax.
> 
> 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@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 can also be simple like below::
> > +
> > +    class=eth,mac=00:11:22:33:44:55
> > +
> 
> 1/
> 
> All categories are named, their order is known, and their name comes
> first.

The order of categories is known but some categories may be omitted.

> It is thus possible to declare categories unambiguously without using
> the field name first.
> 
>     pci,id=0000:01:00.0/eth,mac=00:11:22:33:44:55/PMD_NAME,driverspecificproperty=VALUE
>     eth,mac=00:11:22:33:44:55
>     pci,id=00:02.0
> 
> The only requirement for this to hold is for the layer names not to collide
> (bus, dev, drivers), which seems like an easy enough requirement to follow.

I don't like it for 2 reasons:
- it is less explicit
- it is less obvious to dispatch to parsers

> -------------------------------
> 
> > +A device is identified when every properties are matched. Before device is
> > +probed, only the bus category is relevant.
> > + 
> 
> 2/
> 
> When using the following ID:
> 
>     class=eth,mac=00:11:22:33:44:55
> 
> The bus is skipped, as well as the driver.
> Does that mean that it is allowed to skip any layer, as long as the
> resulting match is unambiguous?
> 
> What I mean is that a user could then do
> 
>     driver=net_ring
> 
> To find the one port using the driver net_ring.

I think yes, if there is only one net_ring device.

> -------------------------------
> 
> 3/
> 
> The driver would generate a name for the eth_dev structure.
> I guess it would be possible to identify the device with
> 
>     class=eth,name=net_ring0
> 
> Or something. Where does the rte_dev name appears? Is it a property
> of the bus layer? Is it merged with the eth_dev name? If so, which one
> will stay, the rte_dev name or the eth_dev name?

EAL device and ethdev are different layers.
There is no 1:1 mapping.
So both must stay.
rte_dev name should be a property of the bus layer.
Ferruh Yigit Jan. 17, 2018, 12:34 p.m. UTC | #10
On 1/16/2018 2:50 PM, 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

Hi Yuanhan,

devargs = device arguments, the PMD specific arguments, similar to module_param
in Linux.

Currently only "--vdev" and -w/-b eal parameters parse proceeding strings as
devargs.

Like: "--vdev "net_pcap,iface=lo" .
For this case "iface=lo" device specific argument and available to use from pcap
PMD.

I agree it to have a consistent way to describe device, that makes better
whitelist/blacklist support. But that part is not device args, more like device
identifier.

When you use this string with whitelist/blacklist I think you won't need
"iface=lo" part, only need first part. And when using with --vdev, (or perhaps
with attach) you don't need to use first part
"bus=pci,id=0000:01:00.0/class=eth,mac=00:11:22:33:44:55", PMD already knows it
is in virtual bus and its class etc.

So does it make sense to separate them logically? Perhaps as "device identifier"
and "device args".

string can become:
"device=bus=pci,id=0000:01:00.0/class=eth,mac=00:11:22:33:44:55;driver=PMD_NAME,driverspecificproperty=VALUE"

specific usages can become:
-w "device=bus=pci,id=0000:01:00.0/class=eth,mac=00:11:22:33:44:55"
--vdev "driver=PMD_NAME,driverspecificproperty=VALUE"

And store them in two separate storage, and eal or PMD can ask for "device
identifier" or "device args" separately?

What do you think?

> 
> 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@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 can also be simple like below::
> +
> +    class=eth,mac=00:11:22:33:44:55
> +
> +A device is identified when every properties are matched. Before device is
> +probed, only the bus category is relevant.
> +
>  Blacklisting
>  ~~~~~~~~~~~~
>  
>
Yuanhan Liu Jan. 18, 2018, 7:35 a.m. UTC | #11
On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> On 1/16/2018 2:50 PM, 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
> 
> Hi Yuanhan,

Hi Ferruh,

> devargs = device arguments, the PMD specific arguments, similar to module_param
> in Linux.

Not exactly. If you look at the function
rte_eth_dev_attach(const char *devargs, uint16_t *port_id), the "device
identifier" part you called also part of the devargs.

> 
> Currently only "--vdev" and -w/-b eal parameters parse proceeding strings as
> devargs.
> 
> Like: "--vdev "net_pcap,iface=lo" .
> For this case "iface=lo" device specific argument and available to use from pcap
> PMD.
> 
> I agree it to have a consistent way to describe device, that makes better
> whitelist/blacklist support. But that part is not device args, more like device
> identifier.
> 
> When you use this string with whitelist/blacklist I think you won't need
> "iface=lo" part,

Right. That's actaully mentioned in this patch:

   Before device is probed, only the bus category is relevant.

> only need first part. And when using with --vdev, (or perhaps
> with attach) you don't need to use first part
> "bus=pci,id=0000:01:00.0/class=eth,mac=00:11:22:33:44:55", PMD already knows it
> is in virtual bus and its class etc.

We are going to keep the compatibily, meaning we will leave "-w" and
"--vdev" as they are. We plan to introduce one more CLI option and
let user to switch to it so that it can work with any bus, not only
PCI and vdev bus.

> So does it make sense to separate them logically? Perhaps as "device identifier"
> and "device args".

Then I think it returns back to the old issue: how could we identify a
port when the bus id (say BDF for PCI bus) is not enough for identifying
a port? Such case could happen when a single NIC has 2 ports sharing
the same BDF. It could also happen with the VF representors that will
be introduced shortly.

	--yliu

> string can become:
> "device=bus=pci,id=0000:01:00.0/class=eth,mac=00:11:22:33:44:55;driver=PMD_NAME,driverspecificproperty=VALUE"
> 
> specific usages can become:
> -w "device=bus=pci,id=0000:01:00.0/class=eth,mac=00:11:22:33:44:55"
> --vdev "driver=PMD_NAME,driverspecificproperty=VALUE"
> 
> And store them in two separate storage, and eal or PMD can ask for "device
> identifier" or "device args" separately?
> 
> What do you think?
> 
> > 
> > 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@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 can also be simple like below::
> > +
> > +    class=eth,mac=00:11:22:33:44:55
> > +
> > +A device is identified when every properties are matched. Before device is
> > +probed, only the bus category is relevant.
> > +
> >  Blacklisting
> >  ~~~~~~~~~~~~
> >  
> >
Thomas Monjalon Jan. 18, 2018, 8:46 a.m. UTC | #12
18/01/2018 08:35, Yuanhan Liu:
> On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > So does it make sense to separate them logically? Perhaps as "device identifier"
> > and "device args".
> 
> Then I think it returns back to the old issue: how could we identify a
> port when the bus id (say BDF for PCI bus) is not enough for identifying
> a port? Such case could happen when a single NIC has 2 ports sharing
> the same BDF. It could also happen with the VF representors that will
> be introduced shortly.

Yes, the device matching syntax must include bus category, class category
and driver category. So any device can be identified in future.

But I think Ferruh is talking about separating device matching
(which is described in this proposal) and device settings
(which are usually mixed in -w and --vdev options).
I agree there are different things and may be separate.
They could share the same syntax (bus/class/driver) but be separate
with a semicolon:
	matching;settings
Gaëtan Rivet Jan. 18, 2018, 9:46 a.m. UTC | #13
On Thu, Jan 18, 2018 at 09:46:29AM +0100, Thomas Monjalon wrote:
> 18/01/2018 08:35, Yuanhan Liu:
> > On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > > So does it make sense to separate them logically? Perhaps as "device identifier"
> > > and "device args".
> > 
> > Then I think it returns back to the old issue: how could we identify a
> > port when the bus id (say BDF for PCI bus) is not enough for identifying
> > a port? Such case could happen when a single NIC has 2 ports sharing
> > the same BDF. It could also happen with the VF representors that will
> > be introduced shortly.
> 
> Yes, the device matching syntax must include bus category, class category
> and driver category. So any device can be identified in future.
> 
> But I think Ferruh is talking about separating device matching
> (which is described in this proposal) and device settings
> (which are usually mixed in -w and --vdev options).
> I agree there are different things and may be separate.
> They could share the same syntax (bus/class/driver) but be separate
> with a semicolon:
> 	matching;settings

Can you give an example?
Yuanhan Liu Jan. 23, 2018, 12:46 p.m. UTC | #14
On Thu, Jan 18, 2018 at 10:46:23AM +0100, Gaëtan Rivet wrote:
> On Thu, Jan 18, 2018 at 09:46:29AM +0100, Thomas Monjalon wrote:
> > 18/01/2018 08:35, Yuanhan Liu:
> > > On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > > > So does it make sense to separate them logically? Perhaps as "device identifier"
> > > > and "device args".
> > > 
> > > Then I think it returns back to the old issue: how could we identify a
> > > port when the bus id (say BDF for PCI bus) is not enough for identifying
> > > a port? Such case could happen when a single NIC has 2 ports sharing
> > > the same BDF. It could also happen with the VF representors that will
> > > be introduced shortly.
> > 
> > Yes, the device matching syntax must include bus category, class category
> > and driver category. So any device can be identified in future.
> > 
> > But I think Ferruh is talking about separating device matching
> > (which is described in this proposal) and device settings
> > (which are usually mixed in -w and --vdev options).
> > I agree there are different things and may be separate.
> > They could share the same syntax (bus/class/driver) but be separate
> > with a semicolon:
> > 	matching;settings
>
> Can you give an example?

Let's take port addition in OVS-DPDK as an example. It happens in 2
steps:
- port lookup (if port is already probed)
- dev attachment (if lookup fails)

And also let's assume we need probe a ConnectX-3 port. Note that for
ConnectX-3, there are 2 ports sharing the same PCI addr. Thus, PCI
BDF is not enough. And let's assume we use another extra property
"port".

If the proposal described in this patch is being used, the devarg
would look like following:

    bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...

Then "bus=pci,id=04:00.0/class=eth,port=0" will be used for lookup,
It means we are looking for a port with PCI BDF == 04:00.0 AND
port == 0 (the first port of the 2 ports).

Note that in my proposal the driver category is not intended for lookup.
If any properties needed be looked in the driver category, they would
probably need be elevated to the class category.

If port not found, then the whole string will be used for dev attachment.
It means we are attaching a port with PCI BDF == 04.00.0 AND
port == 0 (the 2nd port will not be attached).


And here is how the devargs would look like if "matching;settings" is
being used:

    bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...

The part before ";" will be used for lookup and the later part will be
used for attachment. It should work. It just looks redundant.

	-yliu
Thomas Monjalon Jan. 23, 2018, 2:29 p.m. UTC | #15
23/01/2018 13:46, Yuanhan Liu:
> On Thu, Jan 18, 2018 at 10:46:23AM +0100, Gaëtan Rivet wrote:
> > On Thu, Jan 18, 2018 at 09:46:29AM +0100, Thomas Monjalon wrote:
> > > 18/01/2018 08:35, Yuanhan Liu:
> > > > On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > > > > So does it make sense to separate them logically? Perhaps as "device identifier"
> > > > > and "device args".
> > > > 
> > > > Then I think it returns back to the old issue: how could we identify a
> > > > port when the bus id (say BDF for PCI bus) is not enough for identifying
> > > > a port? Such case could happen when a single NIC has 2 ports sharing
> > > > the same BDF. It could also happen with the VF representors that will
> > > > be introduced shortly.
> > > 
> > > Yes, the device matching syntax must include bus category, class category
> > > and driver category. So any device can be identified in future.
> > > 
> > > But I think Ferruh is talking about separating device matching
> > > (which is described in this proposal) and device settings
> > > (which are usually mixed in -w and --vdev options).
> > > I agree there are different things and may be separate.
> > > They could share the same syntax (bus/class/driver) but be separate
> > > with a semicolon:
> > > 	matching;settings
> >
> > Can you give an example?
> 
> Let's take port addition in OVS-DPDK as an example. It happens in 2
> steps:
> - port lookup (if port is already probed)
> - dev attachment (if lookup fails)
> 
> And also let's assume we need probe a ConnectX-3 port. Note that for
> ConnectX-3, there are 2 ports sharing the same PCI addr. Thus, PCI
> BDF is not enough. And let's assume we use another extra property
> "port".
> 
> If the proposal described in this patch is being used, the devarg
> would look like following:
> 
>     bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> 
> Then "bus=pci,id=04:00.0/class=eth,port=0" will be used for lookup,
> It means we are looking for a port with PCI BDF == 04:00.0 AND
> port == 0 (the first port of the 2 ports).
> 
> Note that in my proposal the driver category is not intended for lookup.
> If any properties needed be looked in the driver category, they would
> probably need be elevated to the class category.

It is not my thought.
I think we should be able to use bus, class and driver properties for lookup.
We can imagine doing a lookup on a driver specific id, which is not
candidate to elevation to the class category.

> If port not found, then the whole string will be used for dev attachment.
> It means we are attaching a port with PCI BDF == 04.00.0 AND
> port == 0 (the 2nd port will not be attached).
> 
> 
> And here is how the devargs would look like if "matching;settings" is
> being used:
> 
>     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> 
> The part before ";" will be used for lookup and the later part will be
> used for attachment. It should work. It just looks redundant.

It does not have to be redundant.
It can be:
	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...

Another example, setting the MAC address:
	bus=pci,id=04:00.0/class=eth,port=0;class=eth,mac=00:11:22:33:44:55
Gaëtan Rivet Jan. 23, 2018, 4:08 p.m. UTC | #16
Hi Yuanhan, Thomas,

On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> 23/01/2018 13:46, Yuanhan Liu:
> > On Thu, Jan 18, 2018 at 10:46:23AM +0100, Gaëtan Rivet wrote:
> > > On Thu, Jan 18, 2018 at 09:46:29AM +0100, Thomas Monjalon wrote:
> > > > 18/01/2018 08:35, Yuanhan Liu:
> > > > > On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > > > > > So does it make sense to separate them logically? Perhaps as "device identifier"
> > > > > > and "device args".
> > > > > 
> > > > > Then I think it returns back to the old issue: how could we identify a
> > > > > port when the bus id (say BDF for PCI bus) is not enough for identifying
> > > > > a port? Such case could happen when a single NIC has 2 ports sharing
> > > > > the same BDF. It could also happen with the VF representors that will
> > > > > be introduced shortly.
> > > > 
> > > > Yes, the device matching syntax must include bus category, class category
> > > > and driver category. So any device can be identified in future.
> > > > 
> > > > But I think Ferruh is talking about separating device matching
> > > > (which is described in this proposal) and device settings
> > > > (which are usually mixed in -w and --vdev options).
> > > > I agree there are different things and may be separate.
> > > > They could share the same syntax (bus/class/driver) but be separate
> > > > with a semicolon:
> > > > 	matching;settings
> > >
> > > Can you give an example?
> > 
> > Let's take port addition in OVS-DPDK as an example. It happens in 2
> > steps:
> > - port lookup (if port is already probed)
> > - dev attachment (if lookup fails)
> > 
> > And also let's assume we need probe a ConnectX-3 port. Note that for
> > ConnectX-3, there are 2 ports sharing the same PCI addr. Thus, PCI
> > BDF is not enough. And let's assume we use another extra property
> > "port".
> > 
> > If the proposal described in this patch is being used, the devarg
> > would look like following:
> > 
> >     bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > 
> > Then "bus=pci,id=04:00.0/class=eth,port=0" will be used for lookup,
> > It means we are looking for a port with PCI BDF == 04:00.0 AND
> > port == 0 (the first port of the 2 ports).
> > 
> > Note that in my proposal the driver category is not intended for lookup.
> > If any properties needed be looked in the driver category, they would
> > probably need be elevated to the class category.
> 
> It is not my thought.
> I think we should be able to use bus, class and driver properties for lookup.
> We can imagine doing a lookup on a driver specific id, which is not
> candidate to elevation to the class category.
> 

This means having a new set of ops for drivers to implement (get / set
on specific properties -- configuration items).

> > If port not found, then the whole string will be used for dev attachment.
> > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > port == 0 (the 2nd port will not be attached).
> > 
> > 
> > And here is how the devargs would look like if "matching;settings" is
> > being used:
> > 
> >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > 
> > The part before ";" will be used for lookup and the later part will be
> > used for attachment. It should work. It just looks redundant.
> 
> It does not have to be redundant.
> It can be:
> 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> 

Did you mean

> 	bus=pci,id=04:00.0/class=eth,port=0;class=driver,name=mlx4,mlx4_arg1=settings1,...

Here? Or is it that you "elevated" driver to be a property of the eth
class, and then immediately chained with driver parameters without
declaring the new driver class?

> Another example, setting the MAC address:
> 	bus=pci,id=04:00.0/class=eth,port=0;class=eth,mac=00:11:22:33:44:55

So, I guess this ";" syntax is meant for a user to provide once and for
all a device string: perhaps on the command line, or programmatically.
It would be used first for EAL init, then reused as-is (the entire
string) for lookup / port matching afterward.

I think this is forcing the user to keep in mind a logic that should be
abstracted away ("Here I am writing for init time, here I am writing for
matching -- but I need to put it at the same place for 'reasons'").

I think mashing those two concepts together introduce complexity, and I
think keeping them separate is user hostile as the devargs that was used
for initializing a device cannot be re-used afterward for matching the
device that resulted from this initialization string.

Drivers answers to a specific API (ethdev, cryptodev, ...), to create
standardized objects in response to parameters that are given to them
for init. I think matching properties should be restricted to higher
classes (bus, eth/crypto), while the driver class should be left
free-form and to the responsibility of the PMD itself (while having the
proper libraries for helping parsing safely, thus driving developpers
toward similar syntaxes, while not forcing them in those).

Match could be performed on bus / eth classes only, while init could
use elements of the three classes. For simplicity, the same syntax rules
could be enforced at all level, or for flexibility some leeway could be
left on the most specific (driver).
Thomas Monjalon Jan. 23, 2018, 5:22 p.m. UTC | #17
23/01/2018 17:08, Gaëtan Rivet:
> Hi Yuanhan, Thomas,
> 
> On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > 23/01/2018 13:46, Yuanhan Liu:
> > > On Thu, Jan 18, 2018 at 10:46:23AM +0100, Gaëtan Rivet wrote:
> > > > On Thu, Jan 18, 2018 at 09:46:29AM +0100, Thomas Monjalon wrote:
> > > > > 18/01/2018 08:35, Yuanhan Liu:
> > > > > > On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > > > > > > So does it make sense to separate them logically? Perhaps as "device identifier"
> > > > > > > and "device args".
> > > > > > 
> > > > > > Then I think it returns back to the old issue: how could we identify a
> > > > > > port when the bus id (say BDF for PCI bus) is not enough for identifying
> > > > > > a port? Such case could happen when a single NIC has 2 ports sharing
> > > > > > the same BDF. It could also happen with the VF representors that will
> > > > > > be introduced shortly.
> > > > > 
> > > > > Yes, the device matching syntax must include bus category, class category
> > > > > and driver category. So any device can be identified in future.
> > > > > 
> > > > > But I think Ferruh is talking about separating device matching
> > > > > (which is described in this proposal) and device settings
> > > > > (which are usually mixed in -w and --vdev options).
> > > > > I agree there are different things and may be separate.
> > > > > They could share the same syntax (bus/class/driver) but be separate
> > > > > with a semicolon:
> > > > > 	matching;settings
> > > >
> > > > Can you give an example?
> > > 
> > > Let's take port addition in OVS-DPDK as an example. It happens in 2
> > > steps:
> > > - port lookup (if port is already probed)
> > > - dev attachment (if lookup fails)
> > > 
> > > And also let's assume we need probe a ConnectX-3 port. Note that for
> > > ConnectX-3, there are 2 ports sharing the same PCI addr. Thus, PCI
> > > BDF is not enough. And let's assume we use another extra property
> > > "port".
> > > 
> > > If the proposal described in this patch is being used, the devarg
> > > would look like following:
> > > 
> > >     bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > 
> > > Then "bus=pci,id=04:00.0/class=eth,port=0" will be used for lookup,
> > > It means we are looking for a port with PCI BDF == 04:00.0 AND
> > > port == 0 (the first port of the 2 ports).
> > > 
> > > Note that in my proposal the driver category is not intended for lookup.
> > > If any properties needed be looked in the driver category, they would
> > > probably need be elevated to the class category.
> > 
> > It is not my thought.
> > I think we should be able to use bus, class and driver properties for lookup.
> > We can imagine doing a lookup on a driver specific id, which is not
> > candidate to elevation to the class category.
> 
> This means having a new set of ops for drivers to implement (get / set
> on specific properties -- configuration items).

Just new ops to parse the string.
Then the driver is free to do whatever he wants internally.

> > > If port not found, then the whole string will be used for dev attachment.
> > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > port == 0 (the 2nd port will not be attached).
> > > 
> > > 
> > > And here is how the devargs would look like if "matching;settings" is
> > > being used:
> > > 
> > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > 
> > > The part before ";" will be used for lookup and the later part will be
> > > used for attachment. It should work. It just looks redundant.
> > 
> > It does not have to be redundant.
> > It can be:
> > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > 
> 
> Did you mean
> 
> > 	bus=pci,id=04:00.0/class=eth,port=0;class=driver,name=mlx4,mlx4_arg1=settings1,...

No :)
There are 3 categories: bus, class and driver.
class is for eth, crypto, event, etc.

> Here? Or is it that you "elevated" driver to be a property of the eth
> class, and then immediately chained with driver parameters without
> declaring the new driver class?

No I think you misunderstand.
I re-use the same syntax for matching and settings.
Overview is: bus/class/driver;bus/class/driver
where first part is for matching, and second part is for settings if any.
Another overview is: matching;settings

> > Another example, setting the MAC address:
> > 	bus=pci,id=04:00.0/class=eth,port=0;class=eth,mac=00:11:22:33:44:55
> 
> So, I guess this ";" syntax is meant for a user to provide once and for
> all a device string: perhaps on the command line, or programmatically.
> It would be used first for EAL init, then reused as-is (the entire
> string) for lookup / port matching afterward.
> 
> I think this is forcing the user to keep in mind a logic that should be
> abstracted away ("Here I am writing for init time, here I am writing for
> matching -- but I need to put it at the same place for 'reasons'").
> 
> I think mashing those two concepts together introduce complexity, and I
> think keeping them separate is user hostile as the devargs that was used
> for initializing a device cannot be re-used afterward for matching the
> device that resulted from this initialization string.
> 
> Drivers answers to a specific API (ethdev, cryptodev, ...), to create
> standardized objects in response to parameters that are given to them
> for init. I think matching properties should be restricted to higher
> classes (bus, eth/crypto), while the driver class should be left
> free-form and to the responsibility of the PMD itself (while having the
> proper libraries for helping parsing safely, thus driving developpers
> toward similar syntaxes, while not forcing them in those).
> 
> Match could be performed on bus / eth classes only, while init could
> use elements of the three classes. For simplicity, the same syntax rules
> could be enforced at all level, or for flexibility some leeway could be
> left on the most specific (driver).

I think it is more generic to allow bus/class/driver for matching
and for settings.
You seem to disagree about having driver-specific matching properties.
I argue it will address all future corner cases.
You say driver settings should be free form while I propose just
key=value syntax for them; it is a kind of free form.
Gaëtan Rivet Jan. 23, 2018, 5:37 p.m. UTC | #18
On Tue, Jan 23, 2018 at 06:22:53PM +0100, Thomas Monjalon wrote:
> 23/01/2018 17:08, Gaëtan Rivet:
> > Hi Yuanhan, Thomas,
> > 
> > On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > > 23/01/2018 13:46, Yuanhan Liu:
> > > > On Thu, Jan 18, 2018 at 10:46:23AM +0100, Gaëtan Rivet wrote:
> > > > > On Thu, Jan 18, 2018 at 09:46:29AM +0100, Thomas Monjalon wrote:
> > > > > > 18/01/2018 08:35, Yuanhan Liu:
> > > > > > > On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > > > > > > > So does it make sense to separate them logically? Perhaps as "device identifier"
> > > > > > > > and "device args".
> > > > > > > 
> > > > > > > Then I think it returns back to the old issue: how could we identify a
> > > > > > > port when the bus id (say BDF for PCI bus) is not enough for identifying
> > > > > > > a port? Such case could happen when a single NIC has 2 ports sharing
> > > > > > > the same BDF. It could also happen with the VF representors that will
> > > > > > > be introduced shortly.
> > > > > > 
> > > > > > Yes, the device matching syntax must include bus category, class category
> > > > > > and driver category. So any device can be identified in future.
> > > > > > 
> > > > > > But I think Ferruh is talking about separating device matching
> > > > > > (which is described in this proposal) and device settings
> > > > > > (which are usually mixed in -w and --vdev options).
> > > > > > I agree there are different things and may be separate.
> > > > > > They could share the same syntax (bus/class/driver) but be separate
> > > > > > with a semicolon:
> > > > > > 	matching;settings
> > > > >
> > > > > Can you give an example?
> > > > 
> > > > Let's take port addition in OVS-DPDK as an example. It happens in 2
> > > > steps:
> > > > - port lookup (if port is already probed)
> > > > - dev attachment (if lookup fails)
> > > > 
> > > > And also let's assume we need probe a ConnectX-3 port. Note that for
> > > > ConnectX-3, there are 2 ports sharing the same PCI addr. Thus, PCI
> > > > BDF is not enough. And let's assume we use another extra property
> > > > "port".
> > > > 
> > > > If the proposal described in this patch is being used, the devarg
> > > > would look like following:
> > > > 
> > > >     bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > 
> > > > Then "bus=pci,id=04:00.0/class=eth,port=0" will be used for lookup,
> > > > It means we are looking for a port with PCI BDF == 04:00.0 AND
> > > > port == 0 (the first port of the 2 ports).
> > > > 
> > > > Note that in my proposal the driver category is not intended for lookup.
> > > > If any properties needed be looked in the driver category, they would
> > > > probably need be elevated to the class category.
> > > 
> > > It is not my thought.
> > > I think we should be able to use bus, class and driver properties for lookup.
> > > We can imagine doing a lookup on a driver specific id, which is not
> > > candidate to elevation to the class category.
> > 
> > This means having a new set of ops for drivers to implement (get / set
> > on specific properties -- configuration items).
> 
> Just new ops to parse the string.
> Then the driver is free to do whatever he wants internally.
> 
> > > > If port not found, then the whole string will be used for dev attachment.
> > > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > > port == 0 (the 2nd port will not be attached).
> > > > 
> > > > 
> > > > And here is how the devargs would look like if "matching;settings" is
> > > > being used:
> > > > 
> > > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > 
> > > > The part before ";" will be used for lookup and the later part will be
> > > > used for attachment. It should work. It just looks redundant.
> > > 
> > > It does not have to be redundant.
> > > It can be:
> > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > > 
> > 
> > Did you mean
> > 
> > > 	bus=pci,id=04:00.0/class=eth,port=0;class=driver,name=mlx4,mlx4_arg1=settings1,...
> 
> No :)
> There are 3 categories: bus, class and driver.
> class is for eth, crypto, event, etc.
> 

ah yes, mixed up.
It makes more sense then.

> > Here? Or is it that you "elevated" driver to be a property of the eth
> > class, and then immediately chained with driver parameters without
> > declaring the new driver class?
> 
> No I think you misunderstand.
> I re-use the same syntax for matching and settings.
> Overview is: bus/class/driver;bus/class/driver
> where first part is for matching, and second part is for settings if any.
> Another overview is: matching;settings
> 

Sure, with the mixup above straightened it's clear.

> > > Another example, setting the MAC address:
> > > 	bus=pci,id=04:00.0/class=eth,port=0;class=eth,mac=00:11:22:33:44:55
> > 
> > So, I guess this ";" syntax is meant for a user to provide once and for
> > all a device string: perhaps on the command line, or programmatically.
> > It would be used first for EAL init, then reused as-is (the entire
> > string) for lookup / port matching afterward.
> > 
> > I think this is forcing the user to keep in mind a logic that should be
> > abstracted away ("Here I am writing for init time, here I am writing for
> > matching -- but I need to put it at the same place for 'reasons'").
> > 
> > I think mashing those two concepts together introduce complexity, and I
> > think keeping them separate is user hostile as the devargs that was used
> > for initializing a device cannot be re-used afterward for matching the
> > device that resulted from this initialization string.
> > 
> > Drivers answers to a specific API (ethdev, cryptodev, ...), to create
> > standardized objects in response to parameters that are given to them
> > for init. I think matching properties should be restricted to higher
> > classes (bus, eth/crypto), while the driver class should be left
> > free-form and to the responsibility of the PMD itself (while having the
> > proper libraries for helping parsing safely, thus driving developpers
> > toward similar syntaxes, while not forcing them in those).
> > 
> > Match could be performed on bus / eth classes only, while init could
> > use elements of the three classes. For simplicity, the same syntax rules
> > could be enforced at all level, or for flexibility some leeway could be
> > left on the most specific (driver).
> 
> I think it is more generic to allow bus/class/driver for matching
> and for settings.

Yes. When you propose

> > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...

As an example: what I was thinking about was along those lines. "bus"
and "class" used for matching, "driver" used only for init.

So your proposition is more flexible, but I do not see how "driver" will
be used for matching. I guess I'll see.
Thomas Monjalon Jan. 23, 2018, 6:12 p.m. UTC | #19
23/01/2018 18:37, Gaëtan Rivet:
> So your proposition is more flexible, but I do not see how "driver" will
> be used for matching. I guess I'll see.

For now, I am not sure there are real examples of driver-specific
properties to match.
An example in my mind: Napatech can have ports with the same PCI address
and they don't have any standard way of distinguishing them.
Yuanhan Liu Jan. 24, 2018, 6:43 a.m. UTC | #20
On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> 23/01/2018 13:46, Yuanhan Liu:
> > On Thu, Jan 18, 2018 at 10:46:23AM +0100, Gaëtan Rivet wrote:
> > > On Thu, Jan 18, 2018 at 09:46:29AM +0100, Thomas Monjalon wrote:
> > > > 18/01/2018 08:35, Yuanhan Liu:
> > > > > On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > > > > > So does it make sense to separate them logically? Perhaps as "device identifier"
> > > > > > and "device args".
> > > > > 
> > > > > Then I think it returns back to the old issue: how could we identify a
> > > > > port when the bus id (say BDF for PCI bus) is not enough for identifying
> > > > > a port? Such case could happen when a single NIC has 2 ports sharing
> > > > > the same BDF. It could also happen with the VF representors that will
> > > > > be introduced shortly.
> > > > 
> > > > Yes, the device matching syntax must include bus category, class category
> > > > and driver category. So any device can be identified in future.
> > > > 
> > > > But I think Ferruh is talking about separating device matching
> > > > (which is described in this proposal) and device settings
> > > > (which are usually mixed in -w and --vdev options).
> > > > I agree there are different things and may be separate.
> > > > They could share the same syntax (bus/class/driver) but be separate
> > > > with a semicolon:
> > > > 	matching;settings
> > >
> > > Can you give an example?
> > 
> > Let's take port addition in OVS-DPDK as an example. It happens in 2
> > steps:
> > - port lookup (if port is already probed)
> > - dev attachment (if lookup fails)
> > 
> > And also let's assume we need probe a ConnectX-3 port. Note that for
> > ConnectX-3, there are 2 ports sharing the same PCI addr. Thus, PCI
> > BDF is not enough. And let's assume we use another extra property
> > "port".
> > 
> > If the proposal described in this patch is being used, the devarg
> > would look like following:
> > 
> >     bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > 
> > Then "bus=pci,id=04:00.0/class=eth,port=0" will be used for lookup,
> > It means we are looking for a port with PCI BDF == 04:00.0 AND
> > port == 0 (the first port of the 2 ports).
> > 
> > Note that in my proposal the driver category is not intended for lookup.
> > If any properties needed be looked in the driver category, they would
> > probably need be elevated to the class category.
> 
> It is not my thought.
> I think we should be able to use bus, class and driver properties for lookup.
> We can imagine doing a lookup on a driver specific id, which is not
> candidate to elevation to the class category.
> 
> > If port not found, then the whole string will be used for dev attachment.
> > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > port == 0 (the 2nd port will not be attached).
> > 
> > 
> > And here is how the devargs would look like if "matching;settings" is
> > being used:
> > 
> >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > 
> > The part before ";" will be used for lookup and the later part will be
> > used for attachment. It should work. It just looks redundant.
> 
> It does not have to be redundant.
> It can be:
> 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...

I knew you would make such reply :)
Then there is a contradiction. According your suggestion, the "port=0" belongs
to the matching section, but it also has to be used in the settings section.

> Another example, setting the MAC address:
> 	bus=pci,id=04:00.0/class=eth,port=0;class=eth,mac=00:11:22:33:44:55

What's the scenario it will be used? And who is going to parse it?

	--yliu
Thomas Monjalon Jan. 24, 2018, 8:19 a.m. UTC | #21
24/01/2018 07:43, Yuanhan Liu:
> On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > 23/01/2018 13:46, Yuanhan Liu:
> > > On Thu, Jan 18, 2018 at 10:46:23AM +0100, Gaëtan Rivet wrote:
> > > > On Thu, Jan 18, 2018 at 09:46:29AM +0100, Thomas Monjalon wrote:
> > > > > 18/01/2018 08:35, Yuanhan Liu:
> > > > > > On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > > > > > > So does it make sense to separate them logically? Perhaps as "device identifier"
> > > > > > > and "device args".
> > > > > > 
> > > > > > Then I think it returns back to the old issue: how could we identify a
> > > > > > port when the bus id (say BDF for PCI bus) is not enough for identifying
> > > > > > a port? Such case could happen when a single NIC has 2 ports sharing
> > > > > > the same BDF. It could also happen with the VF representors that will
> > > > > > be introduced shortly.
> > > > > 
> > > > > Yes, the device matching syntax must include bus category, class category
> > > > > and driver category. So any device can be identified in future.
> > > > > 
> > > > > But I think Ferruh is talking about separating device matching
> > > > > (which is described in this proposal) and device settings
> > > > > (which are usually mixed in -w and --vdev options).
> > > > > I agree there are different things and may be separate.
> > > > > They could share the same syntax (bus/class/driver) but be separate
> > > > > with a semicolon:
> > > > > 	matching;settings
> > > >
> > > > Can you give an example?
> > > 
> > > Let's take port addition in OVS-DPDK as an example. It happens in 2
> > > steps:
> > > - port lookup (if port is already probed)
> > > - dev attachment (if lookup fails)
> > > 
> > > And also let's assume we need probe a ConnectX-3 port. Note that for
> > > ConnectX-3, there are 2 ports sharing the same PCI addr. Thus, PCI
> > > BDF is not enough. And let's assume we use another extra property
> > > "port".
> > > 
> > > If the proposal described in this patch is being used, the devarg
> > > would look like following:
> > > 
> > >     bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > 
> > > Then "bus=pci,id=04:00.0/class=eth,port=0" will be used for lookup,
> > > It means we are looking for a port with PCI BDF == 04:00.0 AND
> > > port == 0 (the first port of the 2 ports).
> > > 
> > > Note that in my proposal the driver category is not intended for lookup.
> > > If any properties needed be looked in the driver category, they would
> > > probably need be elevated to the class category.
> > 
> > It is not my thought.
> > I think we should be able to use bus, class and driver properties for lookup.
> > We can imagine doing a lookup on a driver specific id, which is not
> > candidate to elevation to the class category.
> > 
> > > If port not found, then the whole string will be used for dev attachment.
> > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > port == 0 (the 2nd port will not be attached).
> > > 
> > > 
> > > And here is how the devargs would look like if "matching;settings" is
> > > being used:
> > > 
> > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > 
> > > The part before ";" will be used for lookup and the later part will be
> > > used for attachment. It should work. It just looks redundant.
> > 
> > It does not have to be redundant.
> > It can be:
> > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> 
> I knew you would make such reply :)
> Then there is a contradiction. According your suggestion, the "port=0" belongs
> to the matching section, but it also has to be used in the settings section.

If port=0 is matched, it is already set, right?
Why it needs to be in settings?

> > Another example, setting the MAC address:
> > 	bus=pci,id=04:00.0/class=eth,port=0;class=eth,mac=00:11:22:33:44:55
> 
> What's the scenario it will be used? And who is going to parse it?

It can be used on command line for whitelisting a device and let the user
change its MAC address.
The matching is parsed by the PCI driver + ethdev, here.
As mac is a property of ethdev (class=eth), this part must be parsed by ethdev.
Yuanhan Liu Jan. 24, 2018, 9:28 a.m. UTC | #22
On Wed, Jan 24, 2018 at 09:19:10AM +0100, Thomas Monjalon wrote:
> 24/01/2018 07:43, Yuanhan Liu:
> > On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > > 23/01/2018 13:46, Yuanhan Liu:
> > > > On Thu, Jan 18, 2018 at 10:46:23AM +0100, Gaëtan Rivet wrote:
> > > > > On Thu, Jan 18, 2018 at 09:46:29AM +0100, Thomas Monjalon wrote:
> > > > > > 18/01/2018 08:35, Yuanhan Liu:
> > > > > > > On Wed, Jan 17, 2018 at 12:34:08PM +0000, Ferruh Yigit wrote:
> > > > > > > > So does it make sense to separate them logically? Perhaps as "device identifier"
> > > > > > > > and "device args".
> > > > > > > 
> > > > > > > Then I think it returns back to the old issue: how could we identify a
> > > > > > > port when the bus id (say BDF for PCI bus) is not enough for identifying
> > > > > > > a port? Such case could happen when a single NIC has 2 ports sharing
> > > > > > > the same BDF. It could also happen with the VF representors that will
> > > > > > > be introduced shortly.
> > > > > > 
> > > > > > Yes, the device matching syntax must include bus category, class category
> > > > > > and driver category. So any device can be identified in future.
> > > > > > 
> > > > > > But I think Ferruh is talking about separating device matching
> > > > > > (which is described in this proposal) and device settings
> > > > > > (which are usually mixed in -w and --vdev options).
> > > > > > I agree there are different things and may be separate.
> > > > > > They could share the same syntax (bus/class/driver) but be separate
> > > > > > with a semicolon:
> > > > > > 	matching;settings
> > > > >
> > > > > Can you give an example?
> > > > 
> > > > Let's take port addition in OVS-DPDK as an example. It happens in 2
> > > > steps:
> > > > - port lookup (if port is already probed)
> > > > - dev attachment (if lookup fails)
> > > > 
> > > > And also let's assume we need probe a ConnectX-3 port. Note that for
> > > > ConnectX-3, there are 2 ports sharing the same PCI addr. Thus, PCI
> > > > BDF is not enough. And let's assume we use another extra property
> > > > "port".
> > > > 
> > > > If the proposal described in this patch is being used, the devarg
> > > > would look like following:
> > > > 
> > > >     bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > 
> > > > Then "bus=pci,id=04:00.0/class=eth,port=0" will be used for lookup,
> > > > It means we are looking for a port with PCI BDF == 04:00.0 AND
> > > > port == 0 (the first port of the 2 ports).
> > > > 
> > > > Note that in my proposal the driver category is not intended for lookup.
> > > > If any properties needed be looked in the driver category, they would
> > > > probably need be elevated to the class category.
> > > 
> > > It is not my thought.
> > > I think we should be able to use bus, class and driver properties for lookup.
> > > We can imagine doing a lookup on a driver specific id, which is not
> > > candidate to elevation to the class category.
> > > 
> > > > If port not found, then the whole string will be used for dev attachment.
> > > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > > port == 0 (the 2nd port will not be attached).
> > > > 
> > > > 
> > > > And here is how the devargs would look like if "matching;settings" is
> > > > being used:
> > > > 
> > > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > 
> > > > The part before ";" will be used for lookup and the later part will be
> > > > used for attachment. It should work. It just looks redundant.
> > > 
> > > It does not have to be redundant.
> > > It can be:
> > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > 
> > I knew you would make such reply :)
> > Then there is a contradiction. According your suggestion, the "port=0" belongs
> > to the matching section, but it also has to be used in the settings section.
> 
> If port=0 is matched, it is already set, right?

Yes.

> Why it needs to be in settings?

But I was talking the case it's not matched, say it's not probed and here
we do hotplug.

	--yliu

> > > Another example, setting the MAC address:
> > > 	bus=pci,id=04:00.0/class=eth,port=0;class=eth,mac=00:11:22:33:44:55
> > 
> > What's the scenario it will be used? And who is going to parse it?
> 
> It can be used on command line for whitelisting a device and let the user
> change its MAC address.
> The matching is parsed by the PCI driver + ethdev, here.
> As mac is a property of ethdev (class=eth), this part must be parsed by ethdev.
Thomas Monjalon Jan. 24, 2018, 10:21 a.m. UTC | #23
24/01/2018 10:28, Yuanhan Liu:
> On Wed, Jan 24, 2018 at 09:19:10AM +0100, Thomas Monjalon wrote:
> > 24/01/2018 07:43, Yuanhan Liu:
> > > On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > > > 23/01/2018 13:46, Yuanhan Liu:
> > > > > If port not found, then the whole string will be used for dev attachment.
> > > > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > > > port == 0 (the 2nd port will not be attached).
> > > > > 
> > > > > 
> > > > > And here is how the devargs would look like if "matching;settings" is
> > > > > being used:
> > > > > 
> > > > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > > 
> > > > > The part before ";" will be used for lookup and the later part will be
> > > > > used for attachment. It should work. It just looks redundant.
> > > > 
> > > > It does not have to be redundant.
> > > > It can be:
> > > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > > 
> > > I knew you would make such reply :)
> > > Then there is a contradiction. According your suggestion, the "port=0" belongs
> > > to the matching section, but it also has to be used in the settings section.
> > 
> > If port=0 is matched, it is already set, right?
> 
> Yes.
> 
> > Why it needs to be in settings?
> 
> But I was talking the case it's not matched, say it's not probed and here
> we do hotplug.

I don't understand.
Anyway, the port property should be read-only.
Are we talking about the dev_port from the Linux kernel?
Yuanhan Liu Jan. 24, 2018, 10:36 a.m. UTC | #24
On Wed, Jan 24, 2018 at 11:21:44AM +0100, Thomas Monjalon wrote:
> 24/01/2018 10:28, Yuanhan Liu:
> > On Wed, Jan 24, 2018 at 09:19:10AM +0100, Thomas Monjalon wrote:
> > > 24/01/2018 07:43, Yuanhan Liu:
> > > > On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > > > > 23/01/2018 13:46, Yuanhan Liu:
> > > > > > If port not found, then the whole string will be used for dev attachment.
> > > > > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > > > > port == 0 (the 2nd port will not be attached).
> > > > > > 
> > > > > > 
> > > > > > And here is how the devargs would look like if "matching;settings" is
> > > > > > being used:
> > > > > > 
> > > > > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > > > 
> > > > > > The part before ";" will be used for lookup and the later part will be
> > > > > > used for attachment. It should work. It just looks redundant.
> > > > > 
> > > > > It does not have to be redundant.
> > > > > It can be:
> > > > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > > > 
> > > > I knew you would make such reply :)
> > > > Then there is a contradiction. According your suggestion, the "port=0" belongs
> > > > to the matching section, but it also has to be used in the settings section.
> > > 
> > > If port=0 is matched, it is already set, right?
> > 
> > Yes.
> > 
> > > Why it needs to be in settings?
> > 
> > But I was talking the case it's not matched, say it's not probed and here
> > we do hotplug.
> 
> I don't understand.
> Anyway, the port property should be read-only.

All proberties should be read-only.

> Are we talking about the dev_port from the Linux kernel?

Yes. And it can be used for probing one port only (out of 2 ports in a NIC)
at probe stage. So, at this stage, it's a setting but not a match.

	--yliu
Thomas Monjalon Jan. 24, 2018, 10:37 a.m. UTC | #25
24/01/2018 11:36, Yuanhan Liu:
> On Wed, Jan 24, 2018 at 11:21:44AM +0100, Thomas Monjalon wrote:
> > 24/01/2018 10:28, Yuanhan Liu:
> > > On Wed, Jan 24, 2018 at 09:19:10AM +0100, Thomas Monjalon wrote:
> > > > 24/01/2018 07:43, Yuanhan Liu:
> > > > > On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > > > > > 23/01/2018 13:46, Yuanhan Liu:
> > > > > > > If port not found, then the whole string will be used for dev attachment.
> > > > > > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > > > > > port == 0 (the 2nd port will not be attached).
> > > > > > > 
> > > > > > > 
> > > > > > > And here is how the devargs would look like if "matching;settings" is
> > > > > > > being used:
> > > > > > > 
> > > > > > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > > > > 
> > > > > > > The part before ";" will be used for lookup and the later part will be
> > > > > > > used for attachment. It should work. It just looks redundant.
> > > > > > 
> > > > > > It does not have to be redundant.
> > > > > > It can be:
> > > > > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > > > > 
> > > > > I knew you would make such reply :)
> > > > > Then there is a contradiction. According your suggestion, the "port=0" belongs
> > > > > to the matching section, but it also has to be used in the settings section.
> > > > 
> > > > If port=0 is matched, it is already set, right?
> > > 
> > > Yes.
> > > 
> > > > Why it needs to be in settings?
> > > 
> > > But I was talking the case it's not matched, say it's not probed and here
> > > we do hotplug.
> > 
> > I don't understand.
> > Anyway, the port property should be read-only.
> 
> All proberties should be read-only.
> 
> > Are we talking about the dev_port from the Linux kernel?
> 
> Yes. And it can be used for probing one port only (out of 2 ports in a NIC)
> at probe stage. So, at this stage, it's a setting but not a match.

No it's a match!

A settings is changing data in the port.
Yuanhan Liu Jan. 24, 2018, 3:04 p.m. UTC | #26
On Wed, Jan 24, 2018 at 11:37:31AM +0100, Thomas Monjalon wrote:
> 24/01/2018 11:36, Yuanhan Liu:
> > On Wed, Jan 24, 2018 at 11:21:44AM +0100, Thomas Monjalon wrote:
> > > 24/01/2018 10:28, Yuanhan Liu:
> > > > On Wed, Jan 24, 2018 at 09:19:10AM +0100, Thomas Monjalon wrote:
> > > > > 24/01/2018 07:43, Yuanhan Liu:
> > > > > > On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > > > > > > 23/01/2018 13:46, Yuanhan Liu:
> > > > > > > > If port not found, then the whole string will be used for dev attachment.
> > > > > > > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > > > > > > port == 0 (the 2nd port will not be attached).
> > > > > > > > 
> > > > > > > > 
> > > > > > > > And here is how the devargs would look like if "matching;settings" is
> > > > > > > > being used:
> > > > > > > > 
> > > > > > > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > > > > > 
> > > > > > > > The part before ";" will be used for lookup and the later part will be
> > > > > > > > used for attachment. It should work. It just looks redundant.
> > > > > > > 
> > > > > > > It does not have to be redundant.
> > > > > > > It can be:
> > > > > > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > > > > > 
> > > > > > I knew you would make such reply :)
> > > > > > Then there is a contradiction. According your suggestion, the "port=0" belongs
> > > > > > to the matching section, but it also has to be used in the settings section.
> > > > > 
> > > > > If port=0 is matched, it is already set, right?
> > > > 
> > > > Yes.
> > > > 
> > > > > Why it needs to be in settings?
> > > > 
> > > > But I was talking the case it's not matched, say it's not probed and here
> > > > we do hotplug.
> > > 
> > > I don't understand.
> > > Anyway, the port property should be read-only.
> > 
> > All proberties should be read-only.
> > 
> > > Are we talking about the dev_port from the Linux kernel?
> > 
> > Yes. And it can be used for probing one port only (out of 2 ports in a NIC)
> > at probe stage. So, at this stage, it's a setting but not a match.
> 
> No it's a match!
> 
> A settings is changing data in the port.

So I see that's your definition about the "settings". What I think is
everything needed for driver initiation are settings.

For example, one proposed interface for VF rep is the "vf_id" property,
Similar to "port" property we have just discussed above,  it's used for
probing one specific VR rep for the given VF id.

You can say it's a match here, just like the "port" property.

But note that "vf_id" could be a range, to enable multiple VF reps.
The semantics looks like "setting" more than "match".

Another example is from the failsafe PMD that Gaetan had mentioned:

    driver=failsafe,dev(bus=pci,id=00:02.0),fd(/some/file/)

They (dev and fd) should belong the "setting" section, for 2 reasons:

- they should not be used for matching
- they are used for failsafe PMD initiation

But it belongs "match", according to your definition about "settings",
because it doesn't change data in the port.

That also means, the word "settings" might not be well named. It's
probably better to name it "drvargs".

	--yliu
Yuanhan Liu Jan. 24, 2018, 3:24 p.m. UTC | #27
On Tue, Jan 23, 2018 at 05:08:16PM +0100, Gaëtan Rivet wrote:
> Drivers answers to a specific API (ethdev, cryptodev, ...), to create
> standardized objects in response to parameters that are given to them
> for init. I think matching properties should be restricted to higher
> classes (bus, eth/crypto),

That's also what I thought. But I'm okay to have "driver" category
included for matching. I just don't really see a good example for that.

> while the driver class should be left
> free-form and to the responsibility of the PMD itself (while having the
> proper libraries for helping parsing safely, thus driving developpers
> toward similar syntaxes, while not forcing them in those).

I agree. The drv args are parsed by the drivers after all. It's hard to
have a good parser for all. I also don't know why we have to force them
to use "key=value" pairs.

I even see some drawbacks from the forcement:

- some PMDs already use none key/value format. Forcing them breaks more.
  If the "-w" "--vdev" compatibility is kept", nothing will be broken
  from the user point of view. However, if "key=value" pair is going to
  be used, user have to do some changes.

- Some "value" might have to use the nested "=". Handling the nested pairs
  introduces more complexity.

- sometimes, it's simple without an assignment. For example, it could be
  "driver=vhost-pmd,...,client" to let the vhost PMD acts as the client
  mode.

Both Linux kernel and QEMU don't force the "key=value" pair usage, I don't
see any good reason why we have to do that.

	--yliu
Thomas Monjalon Jan. 24, 2018, 4:51 p.m. UTC | #28
24/01/2018 16:24, Yuanhan Liu:
> On Tue, Jan 23, 2018 at 05:08:16PM +0100, Gaëtan Rivet wrote:
> > Drivers answers to a specific API (ethdev, cryptodev, ...), to create
> > standardized objects in response to parameters that are given to them
> > for init. I think matching properties should be restricted to higher
> > classes (bus, eth/crypto),
> 
> That's also what I thought. But I'm okay to have "driver" category
> included for matching. I just don't really see a good example for that.
> 
> > while the driver class should be left
> > free-form and to the responsibility of the PMD itself (while having the
> > proper libraries for helping parsing safely, thus driving developpers
> > toward similar syntaxes, while not forcing them in those).
> 
> I agree. The drv args are parsed by the drivers after all. It's hard to
> have a good parser for all. I also don't know why we have to force them
> to use "key=value" pairs.
> 
> I even see some drawbacks from the forcement:
> 
> - some PMDs already use none key/value format. Forcing them breaks more.
>   If the "-w" "--vdev" compatibility is kept", nothing will be broken
>   from the user point of view. However, if "key=value" pair is going to
>   be used, user have to do some changes.
> 
> - Some "value" might have to use the nested "=". Handling the nested pairs
>   introduces more complexity.
> 
> - sometimes, it's simple without an assignment. For example, it could be
>   "driver=vhost-pmd,...,client" to let the vhost PMD acts as the client
>   mode.
> 
> Both Linux kernel and QEMU don't force the "key=value" pair usage, I don't
> see any good reason why we have to do that.

OK
Thomas Monjalon Jan. 24, 2018, 4:57 p.m. UTC | #29
24/01/2018 16:04, Yuanhan Liu:
> On Wed, Jan 24, 2018 at 11:37:31AM +0100, Thomas Monjalon wrote:
> > 24/01/2018 11:36, Yuanhan Liu:
> > > On Wed, Jan 24, 2018 at 11:21:44AM +0100, Thomas Monjalon wrote:
> > > > 24/01/2018 10:28, Yuanhan Liu:
> > > > > On Wed, Jan 24, 2018 at 09:19:10AM +0100, Thomas Monjalon wrote:
> > > > > > 24/01/2018 07:43, Yuanhan Liu:
> > > > > > > On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > > > > > > > 23/01/2018 13:46, Yuanhan Liu:
> > > > > > > > > If port not found, then the whole string will be used for dev attachment.
> > > > > > > > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > > > > > > > port == 0 (the 2nd port will not be attached).
> > > > > > > > > 
> > > > > > > > > 
> > > > > > > > > And here is how the devargs would look like if "matching;settings" is
> > > > > > > > > being used:
> > > > > > > > > 
> > > > > > > > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > > > > > > 
> > > > > > > > > The part before ";" will be used for lookup and the later part will be
> > > > > > > > > used for attachment. It should work. It just looks redundant.
> > > > > > > > 
> > > > > > > > It does not have to be redundant.
> > > > > > > > It can be:
> > > > > > > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > > > > > > 
> > > > > > > I knew you would make such reply :)
> > > > > > > Then there is a contradiction. According your suggestion, the "port=0" belongs
> > > > > > > to the matching section, but it also has to be used in the settings section.
> > > > > > 
> > > > > > If port=0 is matched, it is already set, right?
> > > > > 
> > > > > Yes.
> > > > > 
> > > > > > Why it needs to be in settings?
> > > > > 
> > > > > But I was talking the case it's not matched, say it's not probed and here
> > > > > we do hotplug.
> > > > 
> > > > I don't understand.
> > > > Anyway, the port property should be read-only.
> > > 
> > > All proberties should be read-only.
> > > 
> > > > Are we talking about the dev_port from the Linux kernel?
> > > 
> > > Yes. And it can be used for probing one port only (out of 2 ports in a NIC)
> > > at probe stage. So, at this stage, it's a setting but not a match.
> > 
> > No it's a match!
> > 
> > A settings is changing data in the port.
> 
> So I see that's your definition about the "settings". What I think is
> everything needed for driver initiation are settings.
> 
> For example, one proposed interface for VF rep is the "vf_id" property,
> Similar to "port" property we have just discussed above,  it's used for
> probing one specific VR rep for the given VF id.
> 
> You can say it's a match here, just like the "port" property.
> 
> But note that "vf_id" could be a range, to enable multiple VF reps.
> The semantics looks like "setting" more than "match".

Not sure why it would look like settings.

> Another example is from the failsafe PMD that Gaetan had mentioned:
> 
>     driver=failsafe,dev(bus=pci,id=00:02.0),fd(/some/file/)
> 
> They (dev and fd) should belong the "setting" section, for 2 reasons:
> 
> - they should not be used for matching
> - they are used for failsafe PMD initiation

Yes these ones are settings.

> But it belongs "match", according to your definition about "settings",
> because it doesn't change data in the port.

No, it changes data, dev() is adding a slave, and fd() is adding
a file descriptor.
So we agree these are settings.

> That also means, the word "settings" might not be well named. It's
> probably better to name it "drvargs".

I disagree. But it's only naming.
Settings can be class settings, not only driver settings.
And driver properties can be matching or settings.
So "drvargs" does not make sense.
Yuanhan Liu Jan. 25, 2018, 2:41 p.m. UTC | #30
On Wed, Jan 24, 2018 at 05:57:34PM +0100, Thomas Monjalon wrote:
> 24/01/2018 16:04, Yuanhan Liu:
> > On Wed, Jan 24, 2018 at 11:37:31AM +0100, Thomas Monjalon wrote:
> > > 24/01/2018 11:36, Yuanhan Liu:
> > > > On Wed, Jan 24, 2018 at 11:21:44AM +0100, Thomas Monjalon wrote:
> > > > > 24/01/2018 10:28, Yuanhan Liu:
> > > > > > On Wed, Jan 24, 2018 at 09:19:10AM +0100, Thomas Monjalon wrote:
> > > > > > > 24/01/2018 07:43, Yuanhan Liu:
> > > > > > > > On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > > > > > > > > 23/01/2018 13:46, Yuanhan Liu:
> > > > > > > > > > If port not found, then the whole string will be used for dev attachment.
> > > > > > > > > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > > > > > > > > port == 0 (the 2nd port will not be attached).
> > > > > > > > > > 
> > > > > > > > > > 
> > > > > > > > > > And here is how the devargs would look like if "matching;settings" is
> > > > > > > > > > being used:
> > > > > > > > > > 
> > > > > > > > > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > > > > > > > 
> > > > > > > > > > The part before ";" will be used for lookup and the later part will be
> > > > > > > > > > used for attachment. It should work. It just looks redundant.
> > > > > > > > > 
> > > > > > > > > It does not have to be redundant.
> > > > > > > > > It can be:
> > > > > > > > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > > > > > > > 
> > > > > > > > I knew you would make such reply :)
> > > > > > > > Then there is a contradiction. According your suggestion, the "port=0" belongs
> > > > > > > > to the matching section, but it also has to be used in the settings section.
> > > > > > > 
> > > > > > > If port=0 is matched, it is already set, right?
> > > > > > 
> > > > > > Yes.
> > > > > > 
> > > > > > > Why it needs to be in settings?
> > > > > > 
> > > > > > But I was talking the case it's not matched, say it's not probed and here
> > > > > > we do hotplug.
> > > > > 
> > > > > I don't understand.
> > > > > Anyway, the port property should be read-only.
> > > > 
> > > > All proberties should be read-only.
> > > > 
> > > > > Are we talking about the dev_port from the Linux kernel?
> > > > 
> > > > Yes. And it can be used for probing one port only (out of 2 ports in a NIC)
> > > > at probe stage. So, at this stage, it's a setting but not a match.
> > > 
> > > No it's a match!
> > > 
> > > A settings is changing data in the port.
> > 
> > So I see that's your definition about the "settings". What I think is
> > everything needed for driver initiation are settings.
> > 
> > For example, one proposed interface for VF rep is the "vf_id" property,
> > Similar to "port" property we have just discussed above,  it's used for
> > probing one specific VR rep for the given VF id.
> > 
> > You can say it's a match here, just like the "port" property.
> > 
> > But note that "vf_id" could be a range, to enable multiple VF reps.
> > The semantics looks like "setting" more than "match".
> 
> Not sure why it would look like settings.
> 
> > Another example is from the failsafe PMD that Gaetan had mentioned:
> > 
> >     driver=failsafe,dev(bus=pci,id=00:02.0),fd(/some/file/)
> > 
> > They (dev and fd) should belong the "setting" section, for 2 reasons:
> > 
> > - they should not be used for matching
> > - they are used for failsafe PMD initiation
> 
> Yes these ones are settings.
> 
> > But it belongs "match", according to your definition about "settings",
> > because it doesn't change data in the port.
> 
> No, it changes data, dev() is adding a slave, and fd() is adding
> a file descriptor.

Then "port" should be settings, as it's used for adding a port.
Moreover, "vf_id=0-3" is definitely settings (according your definition),
as it's going to add 4 VF rep ports.

	--yliu

> So we agree these are settings.
> 
> > That also means, the word "settings" might not be well named. It's
> > probably better to name it "drvargs".
> 
> I disagree. But it's only naming.
> Settings can be class settings, not only driver settings.
> And driver properties can be matching or settings.
> So "drvargs" does not make sense.
Thomas Monjalon Jan. 25, 2018, 2:58 p.m. UTC | #31
25/01/2018 15:41, Yuanhan Liu:
> On Wed, Jan 24, 2018 at 05:57:34PM +0100, Thomas Monjalon wrote:
> > 24/01/2018 16:04, Yuanhan Liu:
> > > On Wed, Jan 24, 2018 at 11:37:31AM +0100, Thomas Monjalon wrote:
> > > > 24/01/2018 11:36, Yuanhan Liu:
> > > > > On Wed, Jan 24, 2018 at 11:21:44AM +0100, Thomas Monjalon wrote:
> > > > > > 24/01/2018 10:28, Yuanhan Liu:
> > > > > > > On Wed, Jan 24, 2018 at 09:19:10AM +0100, Thomas Monjalon wrote:
> > > > > > > > 24/01/2018 07:43, Yuanhan Liu:
> > > > > > > > > On Tue, Jan 23, 2018 at 03:29:34PM +0100, Thomas Monjalon wrote:
> > > > > > > > > > 23/01/2018 13:46, Yuanhan Liu:
> > > > > > > > > > > If port not found, then the whole string will be used for dev attachment.
> > > > > > > > > > > It means we are attaching a port with PCI BDF == 04.00.0 AND
> > > > > > > > > > > port == 0 (the 2nd port will not be attached).
> > > > > > > > > > > 
> > > > > > > > > > > 
> > > > > > > > > > > And here is how the devargs would look like if "matching;settings" is
> > > > > > > > > > > being used:
> > > > > > > > > > > 
> > > > > > > > > > >     bus=pci,id=04:00.0/class=eth,port=0;bus=pci,id=04:00.0/class=eth,port=0/driver=mlx4,mlx4_arg_A=val,...
> > > > > > > > > > > 
> > > > > > > > > > > The part before ";" will be used for lookup and the later part will be
> > > > > > > > > > > used for attachment. It should work. It just looks redundant.
> > > > > > > > > > 
> > > > > > > > > > It does not have to be redundant.
> > > > > > > > > > It can be:
> > > > > > > > > > 	bus=pci,id=04:00.0/class=eth,port=0;driver=mlx4,mlx4_arg1=settings1,...
> > > > > > > > > 
> > > > > > > > > I knew you would make such reply :)
> > > > > > > > > Then there is a contradiction. According your suggestion, the "port=0" belongs
> > > > > > > > > to the matching section, but it also has to be used in the settings section.
> > > > > > > > 
> > > > > > > > If port=0 is matched, it is already set, right?
> > > > > > > 
> > > > > > > Yes.
> > > > > > > 
> > > > > > > > Why it needs to be in settings?
> > > > > > > 
> > > > > > > But I was talking the case it's not matched, say it's not probed and here
> > > > > > > we do hotplug.
> > > > > > 
> > > > > > I don't understand.
> > > > > > Anyway, the port property should be read-only.
> > > > > 
> > > > > All proberties should be read-only.
> > > > > 
> > > > > > Are we talking about the dev_port from the Linux kernel?
> > > > > 
> > > > > Yes. And it can be used for probing one port only (out of 2 ports in a NIC)
> > > > > at probe stage. So, at this stage, it's a setting but not a match.
> > > > 
> > > > No it's a match!
> > > > 
> > > > A settings is changing data in the port.
> > > 
> > > So I see that's your definition about the "settings". What I think is
> > > everything needed for driver initiation are settings.
> > > 
> > > For example, one proposed interface for VF rep is the "vf_id" property,
> > > Similar to "port" property we have just discussed above,  it's used for
> > > probing one specific VR rep for the given VF id.
> > > 
> > > You can say it's a match here, just like the "port" property.
> > > 
> > > But note that "vf_id" could be a range, to enable multiple VF reps.
> > > The semantics looks like "setting" more than "match".
> > 
> > Not sure why it would look like settings.
> > 
> > > Another example is from the failsafe PMD that Gaetan had mentioned:
> > > 
> > >     driver=failsafe,dev(bus=pci,id=00:02.0),fd(/some/file/)
> > > 
> > > They (dev and fd) should belong the "setting" section, for 2 reasons:
> > > 
> > > - they should not be used for matching
> > > - they are used for failsafe PMD initiation
> > 
> > Yes these ones are settings.
> > 
> > > But it belongs "match", according to your definition about "settings",
> > > because it doesn't change data in the port.
> > 
> > No, it changes data, dev() is adding a slave, and fd() is adding
> > a file descriptor.
> 
> Then "port" should be settings, as it's used for adding a port.
> Moreover, "vf_id=0-3" is definitely settings (according your definition),
> as it's going to add 4 VF rep ports.

They are properties to identify a device.
Question we should ask is which device is identified by this string?

In the failsafe case, it is different because at first, we identify
the failsafe vdev itself. So the slaves are not part of this.
Slaves id are settings to bind another device to the failsafe.

> > So we agree these are settings.
> > 
> > > That also means, the word "settings" might not be well named. It's
> > > probably better to name it "drvargs".
> > 
> > I disagree. But it's only naming.
> > Settings can be class settings, not only driver settings.
> > And driver properties can be matching or settings.
> > So "drvargs" does not make sense.

Patch
diff mbox

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 can also be simple like below::
+
+    class=eth,mac=00:11:22:33:44:55
+
+A device is identified when every properties are matched. Before device is
+probed, only the bus category is relevant.
+
 Blacklisting
 ~~~~~~~~~~~~