Re: [PATCH] devicetree - document using aliases to set spi bus number.

[Mark Rutland]

On Tue, May 24, 2016 at 01:41:26PM -0700, Frank Rowand wrote:
> On 5/24/2016 10:41 AM, Mark Rutland wrote:
> > On Tue, May 24, 2016 at 06:39:20PM +0200, Christer Weinigel wrote:
> >> Document how to use devicetree aliases to assign a stable
> >> bus number to a spi bus.
> >>
> >> Signed-off-by: Christer Weinigel <christer@xxxxxxxxxxx>
> >>
> >> ---
> >>
> >> Trivial documentation change.
> >>
> >> Not having used devicetree that much it was surprisingly hard to
> >> figure out how to assign a stable bus number to a spi bus.  Add a
> >> simple example that shows how to do that.
> >>
> >> Mark Cced as the SPI maintainer.  Or should trivial documentation
> >> fixes like this be addressed to someone else?
> >>
> >>   /Christer
> >>
> >>  Documentation/devicetree/bindings/spi/spi-bus.txt | 10 ++++++++++
> >>  1 file changed, 10 insertions(+)
> >>
> >> diff --git a/Documentation/devicetree/bindings/spi/spi-bus.txt b/Documentation/devicetree/bindings/spi/spi-bus.txt
> >> index 42d5954..c35c4c2 100644
> >> --- a/Documentation/devicetree/bindings/spi/spi-bus.txt
> >> +++ b/Documentation/devicetree/bindings/spi/spi-bus.txt
> >> @@ -94,3 +94,13 @@ SPI example for an MPC5200 SPI bus:
> >>  			reg = <1>;
> >>  		};
> >>  	};
> >> +
> >> +Normally SPI buses are assigned dynamic bus numbers starting at 32766
> >> +and counting downwards.  It is possible to assign the bus number
> >> +statically using devicetee aliases.  For example, on the MPC5200 the
> >> +"spi@f00" device above is connected to the "soc" bus.  To set its
> >> +bus_num to 1 add an aliases entry like this:
> > 
> > As Mark Brown pointed out, this is very Linux-specific (at least in the
> > wording of the above).
> 
> Yes, Linux-specific.  So the Linux documentation of bindings is the
> correct place for it.

I don't entirely agree. Which is not to say that I disagree as such, but
rather that this is not a black-and-white affair.

While bindings do happen to live in the kernel tree, we try to keep them
separate from Linux internals or Linux API details that are outside of
the scope of the HW/kernel interface. There are certainly reasons to
describe Linux-specific bindings (e.g. things under /chosen).

Mark Brown's comments imply that there is a better mechanism which does
not rely on this binding, so even if we must retain support for it in
Linux for legacy reasons, documenting it as a binding is not necessarily
in anyone's best interest. If we want to document it, we may want to
mark it as deprecated, with a pointer to better alternatives.

> > Generally, aliases are there to match _physical_ identifiers (e.g. to
> > match physical labels for UART0, UART1, and on).
> > 
> > I'm not sure whether that applies here.
> 
> The code and behavior is in the Linux kernel. It should be visible in
> the documentation instead of being a big mystery of how it works.

As above, I don't entirely agree. Mindlessly documenting existing Linux
behaviour can have the unfortuante effect of moving people towards the
wrong tool for the job.

Thanks,
Mark.