Documentation: gpio: Move GPIO mapping documentation to driver-api

Move gpio/board.txt to driver-api/gpio/board.rst and make sure it builds
cleanly as ReST.

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

2 files changed, 0 insertions, 178 deletions

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
-<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.
-
-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.