Skip to contentSkip to conversation

gpio-line-names policy

DISCUSSION Trevor Woerner 2 participants 4 messages Feb 7, 2023 – Feb 9, 2023

lore
Share & tools
lore
#0 lore raw

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

#1 lore raw

Hi Trevor,

Quoted 4 lines · Trevor Woerner

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

#2 lore raw

Hi Linus,

Quoted 6 lines · Linus Walleij
Quoted 4 lines · Trevor Woerner

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.

Quoted 7 lines

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/[email protected]/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

#3 lore raw
Quoted 15 lines · Trevor Woerner
Quoted 6 lines · Linus Walleij
Quoted 4 lines · Trevor Woerner

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.

Quoted 7 lines

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

Quoted 7 lines

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/[email protected]/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