From 6960341aa33420a8aadf1d625b486933487e6592 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Fri, 9 Mar 2018 00:40:23 +0100 Subject: Documentation: gpio: Move GPIO mapping documentation to driver-api MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move gpio/board.txt to driver-api/gpio/board.rst and make sure it builds cleanly as ReST. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Linus Walleij --- Documentation/gpio/00-INDEX | 2 - Documentation/gpio/board.txt | 176 ------------------------------------------- 2 files changed, 178 deletions(-) delete mode 100644 Documentation/gpio/board.txt (limited to 'Documentation/gpio') diff --git a/Documentation/gpio/00-INDEX b/Documentation/gpio/00-INDEX index f960fc00a3ef..650cb0696211 100644 --- a/Documentation/gpio/00-INDEX +++ b/Documentation/gpio/00-INDEX @@ -3,7 +3,5 @@ drivers-on-gpio.txt: - Drivers in other subsystems that can use GPIO to provide more complex functionality. -board.txt - - How to assign GPIOs to a consumer device and a function sysfs.txt - Information about the GPIO sysfs interface diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt deleted file mode 100644 index 659bb19f5b3c..000000000000 --- a/Documentation/gpio/board.txt +++ /dev/null @@ -1,176 +0,0 @@ -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 --gpios, where 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 -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 -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 - -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. - -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. -- cgit v1.2.3