gpio-line-names policy

gpio-line-names policy

[Trevor Woerner]

Hi Linus Walleij,

I would like to ask a question about the gpio-line-names policy, before
sending in a patch.

The gpio line naming policy, outlined in

	Documentation/devicetree/bindings/gpio/gpio.txt

says you don't want to see line names such as "GPIO0" or "PortB_8", you
want to see lines being named according to their function, such as "MMC-CD"
or "ethernet reset". That makes complete sense... for lines that are
connected to things that are soldered onto a board. Lines whose function
could never change for the life of a device-tree source file.

But what about those lines that go out to general purpose headers such as
the 40 pins of the Raspberry Pi header? Most SBCs have some set of header
that's available to users to connect whatever devices they wish, many of
them have adopted the rpi's 40-pin layout.

When a user wishes to connect something to these pins, they have to go "find"
the pin so they can control the device they've connected. This might start
with the user running "gpioinfo". Sadly, in many cases the user's query is met
with:

	# gpioinfo
	gpiochip0 - 224 lines:
		line   0:      unnamed       unused   input  active-high
		line   1:      unnamed       unused   input  active-high
		line   2:      unnamed       unused   input  active-high
		line   3:      unnamed       unused   input  active-high
		line   4:      unnamed       unused   input  active-high
		line   5:      unnamed       unused   input  active-high
		line   6:      unnamed       unused   input  active-high
		line   7:      unnamed       unused   input  active-high
		line   8:      unnamed       unused   input  active-high
		line   9:      unnamed       unused   input  active-high
		line  10:      unnamed       unused   input  active-high
		line  11:      unnamed       unused   input  active-high
		...

The user still has no idea how to "find" which gpio line is connected to a
specific pin on an SBC's header. At this point their only recourse is to look
for a schematic, dig up the SoC's manual, and look through the kernel code. If
they're successful in all of that, then the might be able to associate one of
the 224 gpio lines with a specific pin.

These lines, by definition, are general purpose, and fresh out of the box
don't have any specific function assigned to them. So I can't send in
a patch to rename line 64 to be "1-wire temperature", because that only
becomes valid when I connect a 1-wire temperature device to pin 31 of my
board. This won't be valid for anyone else.

Ideally I would like to send in a patch that renames line 64 from:

	# gpioinfo
	gpiochip0 - 224 lines
		...
		line  64:      unnamed       unused   input  active-high
		...

to:

	# gpioinfo
	gpiochip0 - 224 lines
		...
		line  64:  "Pin31 [PC1,gpio21]"  unused   input  active-high
		...

(or some variation thereof)

One of these names will make sense to someone using this board. By virtue
of it telling the user this is pin 31 that should be enough. If they look
at the SoC's documentation then they'll know this to be PortC_pin1. Or if
they look at the card that comes with the SBC that describes the header
pins they'll know this to be gpio21. In any case, no work is required by the
user to dig into schematics, code, or processor manuals to know how to connect
a device to pin31.

Can we ammend the policy to make an exception for general purpose pins found
on SBCs?

Interestingly enough the dts file for BeagleBone (am335x-boneblack.dts)
contains:

	&gpio0 {
		gpio-line-names =
			"[mdio_data]",
			"[mdio_clk]",
			"P9_22 [spi0_sclk]",
			"P9_21 [spi0_d0]",
			"P9_18 [spi0_d1]",
			"P9_17 [spi0_cs0]",
			"[mmc0_cd]",
			"P8_42A [ecappwm0]",
			"P8_35 [lcd d12]",
			"P8_33 [lcd d13]",
			"P8_31 [lcd d14]",
			"P8_32 [lcd d15]",
			"P9_20 [i2c2_sda]",
			"P9_19 [i2c2_scl]",
			...

which lists off pin names, and the dts file for the rpi3 contains:

	&gpio {
		gpio-line-names = "ID_SDA",
				  "ID_SCL",
				  "SDA1",
				  "SCL1",
				  "GPIO_GCLK",
				  "GPIO5",
				  "GPIO6",
				  "SPI_CE1_N",
				  "SPI_CE0_N",
				  "SPI_MISO",
				  "SPI_MOSI",
				  "SPI_SCLK",
				  "GPIO12",
				  "GPIO13",
				  ...

which gives GPIO names.

I realize "they did it so I want to as well" isn't a justification. But that
it is being done indicates there is a need, and there is a gap in the policy.

Best regards,
    Trevor

Re: gpio-line-names policy

[Linus Walleij]

Hi Trevor,

On Tue, Feb 7, 2023 at 4:07 PM Trevor Woerner <twoerner@gmail.com> wrote:

> But what about those lines that go out to general purpose headers such as
> the 40 pins of the Raspberry Pi header? Most SBCs have some set of header
> that's available to users to connect whatever devices they wish, many of
> them have adopted the rpi's 40-pin layout.

I think using the names on the header is fine, what I didn't want to see
is things like the name of the pin on the SoC package or names made
up from kernel-internal software constructs. As long as it is something
real, and preferably unique I'm fine with it.

One early example is the HiKey N96 board:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm64/boot/dts/hisilicon/hi3670-hikey970.dts

Yours,
Linus Walleij

Re: gpio-line-names policy

[Trevor Woerner]

Hi Linus,

On Wed 2023-02-08 @ 04:01:05 PM, Linus Walleij wrote:
> On Tue, Feb 7, 2023 at 4:07 PM Trevor Woerner <twoerner@gmail.com> wrote:
> > But what about those lines that go out to general purpose headers such as
> > the 40 pins of the Raspberry Pi header? Most SBCs have some set of header
> > that's available to users to connect whatever devices they wish, many of
> > them have adopted the rpi's 40-pin layout.
> 
> I think using the names on the header is fine, what I didn't want to see
> is things like the name of the pin on the SoC package or names made
> up from kernel-internal software constructs. As long as it is something
> real, and preferably unique I'm fine with it.
> 
> One early example is the HiKey N96 board:
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm64/boot/dts/hisilicon/hi3670-hikey970.dts

Thank you for the clarification. Thinking from the user's point of view, I
added the actual pin number, then the SoC name, then the pin's label.

https://lore.kernel.org/linux-riscv/20230208014504.18899-1-twoerner@gmail.com/T/#u

I'll send a v2 with just the pin's label. Would leaving the pin number, in
addition to the name, be okay?

Best regards,
	Trevor

Re: gpio-line-names policy

[Linus Walleij]

On Wed, Feb 8, 2023 at 5:46 PM Trevor Woerner <twoerner@gmail.com> wrote:
> On Wed 2023-02-08 @ 04:01:05 PM, Linus Walleij wrote:
> > On Tue, Feb 7, 2023 at 4:07 PM Trevor Woerner <twoerner@gmail.com> wrote:
> > > But what about those lines that go out to general purpose headers such as
> > > the 40 pins of the Raspberry Pi header? Most SBCs have some set of header
> > > that's available to users to connect whatever devices they wish, many of
> > > them have adopted the rpi's 40-pin layout.
> >
> > I think using the names on the header is fine, what I didn't want to see
> > is things like the name of the pin on the SoC package or names made
> > up from kernel-internal software constructs. As long as it is something
> > real, and preferably unique I'm fine with it.
> >
> > One early example is the HiKey N96 board:
> > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm64/boot/dts/hisilicon/hi3670-hikey970.dts
>
> Thank you for the clarification. Thinking from the user's point of view, I
> added the actual pin number, then the SoC name, then the pin's label.
>
> https://lore.kernel.org/linux-riscv/20230208014504.18899-1-twoerner@gmail.com/T/#u
>
> I'll send a v2 with just the pin's label. Would leaving the pin number, in
> addition to the name, be okay?

As long as it is clear that this is the pin number on the *header*
not the pin number on the SoC package, this is fine. In order to
clarify it, do like in the HiKey DTS and add verbose comments
explaining what is going on.

The DTS look like it does to be human-readable so be generous
with comments.

Yours,
Linus Walleij