Pin number documentation

[dsvensson]

Not really blaming this crate, but elaborating on pin numbering might be useful to the documentation reader.

I connected physical pin 24 on my Raspberry Pi 3, and now in hindsight, I think that pin really should be accessed via Pin 8, still not sure as SPI CS doesn't work as expected.

Output of gpio readall:

+-----+-----+---------+------+---+---Pi 3---+---+------+---------+-----+-----+
| BCM | wPi |   Name  | Mode | V | Physical | V | Mode | Name    | wPi | BCM |
+-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
|     |     |    3.3v |      |   |  1 || 2  |   |      | 5v      |     |     |
|   2 |   8 |   SDA.1 |   IN | 1 |  3 || 4  |   |      | 5v      |     |     |
|   3 |   9 |   SCL.1 |   IN | 1 |  5 || 6  |   |      | 0v      |     |     |
|   4 |   7 | GPIO. 7 |   IN | 1 |  7 || 8  | 0 | IN   | TxD     | 15  | 14  |
|     |     |      0v |      |   |  9 || 10 | 1 | IN   | RxD     | 16  | 15  |
|  17 |   0 | GPIO. 0 |   IN | 0 | 11 || 12 | 0 | IN   | GPIO. 1 | 1   | 18  |
|  27 |   2 | GPIO. 2 |   IN | 0 | 13 || 14 |   |      | 0v      |     |     |
|  22 |   3 | GPIO. 3 |   IN | 0 | 15 || 16 | 0 | IN   | GPIO. 4 | 4   | 23  |
|     |     |    3.3v |      |   | 17 || 18 | 1 | OUT  | GPIO. 5 | 5   | 24  |
|  10 |  12 |    MOSI | ALT0 | 0 | 19 || 20 |   |      | 0v      |     |     |
|   9 |  13 |    MISO | ALT0 | 0 | 21 || 22 | 0 | IN   | GPIO. 6 | 6   | 25  |
|  11 |  14 |    SCLK | ALT0 | 0 | 23 || 24 | 1 | OUT  | CE0     | 10  | 8   |
|     |     |      0v |      |   | 25 || 26 | 1 | OUT  | CE1     | 11  | 7   |
|   0 |  30 |   SDA.0 |   IN | 1 | 27 || 28 | 1 | IN   | SCL.0   | 31  | 1   |
|   5 |  21 | GPIO.21 |   IN | 1 | 29 || 30 |   |      | 0v      |     |     |
|   6 |  22 | GPIO.22 |   IN | 1 | 31 || 32 | 0 | IN   | GPIO.26 | 26  | 12  |
|  13 |  23 | GPIO.23 |   IN | 0 | 33 || 34 |   |      | 0v      |     |     |
|  19 |  24 | GPIO.24 |   IN | 0 | 35 || 36 | 0 | IN   | GPIO.27 | 27  | 16  |
|  26 |  25 | GPIO.25 |   IN | 0 | 37 || 38 | 0 | IN   | GPIO.28 | 28  | 20  |
|     |     |      0v |      |   | 39 || 40 | 0 | IN   | GPIO.29 | 29  | 21  |
+-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
| BCM | wPi |   Name  | Mode | V | Physical | V | Mode | Name    | wPi | BCM |
+-----+-----+---------+------+---+---Pi 3---+---+------+---------+-----+-----+

So a clarification on what the Pin number refers to would be nice.

[posborne]

I think that output is actually from WiringPi: https://raspberrypi.stackexchange.com/questions/66873/how-to-read-output-of-gpio-readall and not anything generated by this crate or gpio-utils (which uses this).

[dsvensson]

@posborne correct, but as the subject says, it gives me little help to interpret the documentation:

https://docs.rs/sysfs_gpio/0.5.3/sysfs_gpio/struct.Pin.html#method.new

So lets say I have CS connected to physical pin 24 on my Raspberry Pi pin header, I expect the relevant part of the above gpio readall output is:

24 | 1 | OUT | CE0 | 10 | 8 |

...but should I use 24, 10 or 8 as an argument to Pin::new()?

So I was hoping the documentation could be clarified a bit to avoid questions like this.

[posborne]

Ah, I see, unfortunately the answer is a bit tricky and this is part of the reason for the sysfs interface to GPIOs and global numbering that goes along with it being deprecated moving forward. I explain the situation a bit more in the documentation for an as-of-yet unreleased crate that will use the character device interface: https://github.com/posborne/rust-gpio-cdev/blob/first-pass/README.md#getting-access-to-a-gpio

For the case of the raspberry pi and most SOCs (and it will vary based on model a bit) we are looking the magic number will be calculated as something like the following:

magic_pinno = (gpio_bank_no - 1) * bank_size + pin_number_within_bank

On the IMX6, for instance, the BGA pin muxed as GPIO2_5 would be GPIO 37 (as each bank has 32 pins that could be muxed in.

For the raspberry pi (which uses a BCM chip), the builtin GPIO controller has a single bank and the pin number is what the output refers to as the "BCM" number (8). This matches with the example toml configuration file for another tool I wrote called gpio-utils: https://github.com/rust-embedded/gpio-utils/blob/master/examples/raspberrypi.toml#L73

The other thing to watch out for is the SPI driver in the kernel being setup to use the chip-select line directly; in this case I think the pin should fail to export but it depends on how things are implemented in the kernel (whether it is muxing it as a chip select for the peripheral or muxing as a GPIO and allowing the driver to claim the GPIO in the kernel for use as a chip select by the driver).