gpio-line-names policy

[Trevor Woerner <twoerner@gmail.com>]

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