Re: [PATCH] doc: document the new devargs syntax

[Thomas Monjalon <thomas@monjalon.net>]

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.