diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2018-04-05 09:51:41 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2018-04-05 09:51:41 -0700 |
commit | 1b2951dd99af3970c1c1a8385a12b90236b837de (patch) | |
tree | f0263fd6e22c23078b38360ea7495b1dd2d212dc /Documentation/driver-api/gpio/board.rst | |
parent | 06dd3dfeea60e2a6457a6aedf97afc8e6d2ba497 (diff) | |
parent | 348f3cde84ab5b1f53cd3c0eaac1ca99a4dcb148 (diff) | |
download | linux-1b2951dd99af3970c1c1a8385a12b90236b837de.tar.bz2 |
Merge tag 'gpio-v4.17-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio
Pull GPIO updates from Linus Walleij:
"This is the bulk of GPIO changes for the v4.17 kernel cycle:
New drivers:
- Nintendo Wii GameCube GPIO, known as "Hollywood"
- Raspberry Pi mailbox service GPIO expander
- Spreadtrum main SC9860 SoC and IEC GPIO controllers.
Improvements:
- Implemented .get_multiple() callback for most of the
high-performance industrial GPIO cards for the ISA bus.
- ISA GPIO drivers now select the ISA_BUS_API instead of depending on
it. This is merged with the same pattern for all the ISA drivers
and some other Kconfig cleanups related to this.
Cleanup:
- Delete the TZ1090 GPIO drivers following the deletion of this SoC
from the ARM tree.
- Move the documentation over to driver-api to conform with the rest
of the kernel documentation build.
- Continue to make the GPIO drivers include only
<linux/gpio/driver.h> and not the too broad <linux/gpio.h> that we
want to get rid of.
- Managed to remove VLA allocation from two drivers pending more
fixes in this area for the next merge window.
- Misc janitorial fixes"
* tag 'gpio-v4.17-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: (77 commits)
gpio: Add Spreadtrum PMIC EIC driver support
gpio: Add Spreadtrum EIC driver support
dt-bindings: gpio: Add Spreadtrum EIC controller documentation
gpio: ath79: Fix potential NULL dereference in ath79_gpio_probe()
pinctrl: qcom: Don't allow protected pins to be requested
gpiolib: Support 'gpio-reserved-ranges' property
gpiolib: Change bitmap allocation to kmalloc_array
gpiolib: Extract mask allocation into subroutine
dt-bindings: gpio: Add a gpio-reserved-ranges property
gpio: mockup: fix a potential crash when creating debugfs entries
gpio: pca953x: add compatibility for pcal6524 and pcal9555a
gpio: dwapb: Add support for a bus clock
gpio: Remove VLA from xra1403 driver
gpio: Remove VLA from MAX3191X driver
gpio: ws16c48: Implement get_multiple callback
gpio: gpio-mm: Implement get_multiple callback
gpio: 104-idi-48: Implement get_multiple callback
gpio: 104-dio-48e: Implement get_multiple callback
gpio: pcie-idio-24: Implement get_multiple/set_multiple callbacks
gpio: pci-idio-16: Implement get_multiple callback
...
Diffstat (limited to 'Documentation/driver-api/gpio/board.rst')
-rw-r--r-- | Documentation/driver-api/gpio/board.rst | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst new file mode 100644 index 000000000000..25d62b2e9fd0 --- /dev/null +++ b/Documentation/driver-api/gpio/board.rst @@ -0,0 +1,179 @@ +============= +GPIO Mappings +============= + +This document explains how GPIOs can be assigned to given devices and functions. + +Note that it only applies to the new descriptor-based interface. For a +description of the deprecated integer-based GPIO interface please refer to +gpio-legacy.txt (actually, there is no real mapping possible with the old +interface; you just fetch an integer from somewhere and request the +corresponding GPIO). + +All platforms can enable the GPIO library, but if the platform strictly +requires GPIO functionality to be present, it needs to select GPIOLIB from its +Kconfig. Then, how GPIOs are mapped depends on what the platform uses to +describe its hardware layout. Currently, mappings can be defined through device +tree, ACPI, and platform data. + +Device Tree +----------- +GPIOs can easily be mapped to devices and functions in the device tree. The +exact way to do it depends on the GPIO controller providing the GPIOs, see the +device tree bindings for your controller. + +GPIOs mappings are defined in the consumer device's node, in a property named +<function>-gpios, where <function> is the function the driver will request +through gpiod_get(). For example:: + + foo_device { + compatible = "acme,foo"; + ... + led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */ + <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */ + <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */ + + power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>; + }; + +Properties named <function>-gpio are also considered valid and old bindings use +it but are only supported for compatibility reasons and should not be used for +newer bindings since it has been deprecated. + +This property will make GPIOs 15, 16 and 17 available to the driver under the +"led" function, and GPIO 1 as the "power" GPIO:: + + struct gpio_desc *red, *green, *blue, *power; + + red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH); + green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH); + blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH); + + power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); + +The led GPIOs will be active high, while the power GPIO will be active low (i.e. +gpiod_is_active_low(power) will be true). + +The second parameter of the gpiod_get() functions, the con_id string, has to be +the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically +looked up by the gpiod functions internally) used in the device tree. With above +"led-gpios" example, use the prefix without the "-" as con_id parameter: "led". + +Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio") +with the string passed in con_id to get the resulting string +(``snprintf(... "%s-%s", con_id, gpio_suffixes[]``). + +ACPI +---- +ACPI also supports function names for GPIOs in a similar fashion to DT. +The above DT example can be converted to an equivalent ACPI description +with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:: + + Device (FOO) { + Name (_CRS, ResourceTemplate () { + GpioIo (Exclusive, ..., IoRestrictionOutputOnly, + "\\_SB.GPI0") {15} // red + GpioIo (Exclusive, ..., IoRestrictionOutputOnly, + "\\_SB.GPI0") {16} // green + GpioIo (Exclusive, ..., IoRestrictionOutputOnly, + "\\_SB.GPI0") {17} // blue + GpioIo (Exclusive, ..., IoRestrictionOutputOnly, + "\\_SB.GPI0") {1} // power + }) + + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { + "led-gpios", + Package () { + ^FOO, 0, 0, 1, + ^FOO, 1, 0, 1, + ^FOO, 2, 0, 1, + } + }, + Package () { + "power-gpios", + Package () {^FOO, 3, 0, 0}, + }, + } + }) + } + +For more information about the ACPI GPIO bindings see +Documentation/acpi/gpio-properties.txt. + +Platform Data +------------- +Finally, GPIOs can be bound to devices and functions using platform data. Board +files that desire to do so need to include the following header:: + + #include <linux/gpio/machine.h> + +GPIOs are mapped by the means of tables of lookups, containing instances of the +gpiod_lookup structure. Two macros are defined to help declaring such mappings:: + + GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags) + GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags) + +where + + - chip_label is the label of the gpiod_chip instance providing the GPIO + - chip_hwnum is the hardware number of the GPIO within the chip + - con_id is the name of the GPIO function from the device point of view. It + can be NULL, in which case it will match any function. + - idx is the index of the GPIO within the function. + - flags is defined to specify the following properties: + * GPIO_ACTIVE_HIGH - GPIO line is active high + * GPIO_ACTIVE_LOW - GPIO line is active low + * GPIO_OPEN_DRAIN - GPIO line is set up as open drain + * GPIO_OPEN_SOURCE - GPIO line is set up as open source + * GPIO_PERSISTENT - GPIO line is persistent during + suspend/resume and maintains its value + * GPIO_TRANSITORY - GPIO line is transitory and may loose its + electrical state during suspend/resume + +In the future, these flags might be extended to support more properties. + +Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. + +A lookup table can then be defined as follows, with an empty entry defining its +end. The 'dev_id' field of the table is the identifier of the device that will +make use of these GPIOs. It can be NULL, in which case it will be matched for +calls to gpiod_get() with a NULL device. + +.. code-block:: c + + struct gpiod_lookup_table gpios_table = { + .dev_id = "foo.0", + .table = { + GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW), + { }, + }, + }; + +And the table can be added by the board code as follows:: + + gpiod_add_lookup_table(&gpios_table); + +The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:: + + struct gpio_desc *red, *green, *blue, *power; + + red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH); + green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH); + blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH); + + power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); + +Since the "led" GPIOs are mapped as active-high, this example will switch their +signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped +as active-low, its actual signal will be 0 after this code. Contrary to the +legacy integer GPIO interface, the active-low property is handled during +mapping and is thus transparent to GPIO consumers. + +A set of functions such as gpiod_set_value() is available to work with +the new descriptor-oriented interface. |