Re: [PATCH] arm: dts: am33xx-bone-common: add gpio-line-names

[Drew Fustini <drew@beagleboard.org>]

On Mon, May 18, 2020 at 09:11:07AM +0200, Linus Walleij wrote:
> On Fri, May 8, 2020 at 6:57 PM Drew Fustini <drew@beagleboard.org> wrote:
> 
> > Add gpio-line-names properties to the gpio controller nodes.
> > BeagleBone boards have P8 and P9 headers [0] which expose many the
> > AM3358 SoC balls to stacking expansion boards called "capes", or to
> > other external connections like jumper wires to a breadboard.
> >
> > Many of the P8/P9 header pins can muxed to a gpio line.  The
> > gpio-line-names describe which P8/P9 pin that line goes to and the
> > default mux for that P8/P9 pin.  Some lines are not routed to the
> > P8/P9 headers, but instead are dedicated to some functionality such as
> > status LEDs.  The line name will indicate this.  Some line names are
> > left empty as the corresponding AM3358 balls are not connected.
> >
> > The goal is to make it easier for a user viewing the output of gpioinfo
> > to determine which P8/P9 pin is connected to a line.  The output of
> > gpioinfo on a BeagleBone Black will now look like this:
> >
> > gpiochip0 - 32 lines:
> >         line   0:   "ethernet"       unused   input  active-high
> >         line   1:   "ethernet"       unused   input  active-high
> 
> Why are the ethernet lines not tagged with respective signal name
> when right below the SPI lines are explicitly tagged with
> sclk, cs0 etc?
> 
> Ethernet is usually RGMII and has signal names like
> tx_clk, tx_d0, tx_en etc.

Thank you for the feedback, Linus.

My desire is to communicate that the AM3358 balls corresponding to these
GPIO lines are being used for Ethernet and not exposed to the P8 and P9
expansion headers.

I am happy to switch these labels to the actual Ethernet signals such as
RGMII and MDIO signal names if you think that is better.

For example, AM3358 ZCZ ball M17 is both gpio0_0 and mdio_data [0].  On 
BeagleBone, the ball is routed to the Ethernet PHY and used for MDIO [1]
Thus gpiochio 0 line 0 is not connected to the P8 or P9 expansion header.

Which of the following line name would be best?

1) "[MDIO_DATA]"

precise signal name, placed in brackets to denote is not possible to 
use as GPIO on the P8 or P9 headers

2) "[ethernet]" 

instead of the precise signal name, just indicate that it is used for
Ethernet and is not usable for GPIO on the P8 or P9 headers

3) ""

no label as this gpio line is not connected to the P8/P9 and is
hardwired in the PCB layout for Ethernet (MDIO).

> Also some lines seem to be tagged with the pin number
> like P9_22, P2_21 below, it seems a bit inconsistent
> to have much information on some pins and very sketchy
> information on some.

The goal for these line names is make it easier for a BeagleBone user to
identify which GPIO lines are connected to the P8 and P9 expansion
headers.  Our users are most likely to refer to cape-headers.png [2] as
it is part of the bone101 out-of-the-box tutorial [3]. 

Some GPIO lines are free to be used for GPIO in the default
configuration.  For example, gpiochip 1 line 12 is connected to P8_12
and it is not used by another peripheral by default. I used the label:
"P8_12 gpio"

However, gpiochip 1 line 0 is connected to P8_25 but is also used by the
on-board eMMC.  The eMMc is enabled by default so this line can not be
used for GPIO unless the user modifies the pinmux in the device tree.  

Thus, I used this label: "P8_25 emmc"

Maybe a better label would be "P8_25 [EMMC]"?

> 
> >         line  18:        "usb"       unused   input  active-high
> >         line  19:       "hdmi"       unused   input  active-high
> 
> Similar comments for these.


These are similar to the Ethernet MDIO example above.  The balls
corresponding to these GPIO lines are not connected to the P8 or P9 
headers and are hardwired on the PCB for other peripherals like USB
and HDMI.

For example, gpiochip 0 line 18 is USB0_DRVVBUS so I simplified it to
"usb" to indicate it can not be used for GPIO. Maybe "[USB]" is better?

gpiochip 0 line 19 is AM3358 ZCZ ball A15 and the BeagleBone Black
schematic shows that this is connected to the CEC clock for the HDMI
framer [4].  I though "hdmi" was a nice way to summarize that this is
used for HDMI and can not be changed, though maybe "[HDMI]" is better
or no label at all.

In conclusion, the motivation of these line names is to be a quick
reference for a user to find GPIO lines on the P8 and P9 headers.

Thanks,
Drew

[0] http://www.ti.com/lit/ds/symlink/am3358.pdf
[1] https://github.com/beagleboard/beaglebone-black/wiki/System-Reference-Manual#ethernet-processor-interface
[2] http://beagleboard.org/static/images/cape-headers.png
[3] https://beagleboard.org/Support/bone101
[4] https://github.com/beagleboard/beaglebone-black/blob/master/BBB_SCH.pdf