aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/Changes11
-rw-r--r--Documentation/DocBook/device-drivers.tmpl2
-rw-r--r--Documentation/devicetree/bindings/arm/omap/mpu.txt8
-rw-r--r--Documentation/devicetree/bindings/arm/pmu.txt1
-rw-r--r--Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt2
-rw-r--r--Documentation/devicetree/bindings/clock/exynos4-clock.txt2
-rw-r--r--Documentation/devicetree/bindings/clock/exynos5250-clock.txt2
-rw-r--r--Documentation/devicetree/bindings/clock/exynos5420-clock.txt2
-rw-r--r--Documentation/devicetree/bindings/clock/exynos5440-clock.txt2
-rw-r--r--Documentation/devicetree/bindings/gpio/8xxx_gpio.txt66
-rw-r--r--Documentation/devicetree/bindings/i2c/i2c-omap.txt3
-rw-r--r--Documentation/devicetree/bindings/mmc/ti-omap.txt54
-rw-r--r--Documentation/devicetree/bindings/net/fsl-fec.txt2
-rw-r--r--Documentation/devicetree/bindings/rng/qcom,prng.txt17
-rw-r--r--Documentation/devicetree/bindings/spi/nvidia,tegra20-spi.txt5
-rw-r--r--Documentation/devicetree/bindings/vendor-prefixes.txt2
-rw-r--r--Documentation/gpio/00-INDEX14
-rw-r--r--Documentation/gpio/board.txt115
-rw-r--r--Documentation/gpio/consumer.txt197
-rw-r--r--Documentation/gpio/driver.txt75
-rw-r--r--Documentation/gpio/gpio-legacy.txt (renamed from Documentation/gpio.txt)0
-rw-r--r--Documentation/gpio/gpio.txt119
-rw-r--r--Documentation/gpio/sysfs.txt155
23 files changed, 807 insertions, 49 deletions
diff --git a/Documentation/Changes b/Documentation/Changes
index b17580885273..07c75d18154e 100644
--- a/Documentation/Changes
+++ b/Documentation/Changes
@@ -196,13 +196,6 @@ chmod 0644 /dev/cpu/microcode
196as root before you can use this. You'll probably also want to 196as root before you can use this. You'll probably also want to
197get the user-space microcode_ctl utility to use with this. 197get the user-space microcode_ctl utility to use with this.
198 198
199Powertweak
200----------
201
202If you are running v0.1.17 or earlier, you should upgrade to
203version v0.99.0 or higher. Running old versions may cause problems
204with programs using shared memory.
205
206udev 199udev
207---- 200----
208udev is a userspace application for populating /dev dynamically with 201udev is a userspace application for populating /dev dynamically with
@@ -366,10 +359,6 @@ Intel P6 microcode
366------------------ 359------------------
367o <http://www.urbanmyth.org/microcode/> 360o <http://www.urbanmyth.org/microcode/>
368 361
369Powertweak
370----------
371o <http://powertweak.sourceforge.net/>
372
373udev 362udev
374---- 363----
375o <http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html> 364o <http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html>
diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index 6c9d9d37c83a..f5170082bdb3 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -58,7 +58,7 @@
58 </sect1> 58 </sect1>
59 <sect1><title>Wait queues and Wake events</title> 59 <sect1><title>Wait queues and Wake events</title>
60!Iinclude/linux/wait.h 60!Iinclude/linux/wait.h
61!Ekernel/wait.c 61!Ekernel/sched/wait.c
62 </sect1> 62 </sect1>
63 <sect1><title>High-resolution timers</title> 63 <sect1><title>High-resolution timers</title>
64!Iinclude/linux/ktime.h 64!Iinclude/linux/ktime.h
diff --git a/Documentation/devicetree/bindings/arm/omap/mpu.txt b/Documentation/devicetree/bindings/arm/omap/mpu.txt
index 1a5a42ce21bb..83f405bde138 100644
--- a/Documentation/devicetree/bindings/arm/omap/mpu.txt
+++ b/Documentation/devicetree/bindings/arm/omap/mpu.txt
@@ -7,10 +7,18 @@ The MPU contain CPUs, GIC, L2 cache and a local PRCM.
7Required properties: 7Required properties:
8- compatible : Should be "ti,omap3-mpu" for OMAP3 8- compatible : Should be "ti,omap3-mpu" for OMAP3
9 Should be "ti,omap4-mpu" for OMAP4 9 Should be "ti,omap4-mpu" for OMAP4
10 Should be "ti,omap5-mpu" for OMAP5
10- ti,hwmods: "mpu" 11- ti,hwmods: "mpu"
11 12
12Examples: 13Examples:
13 14
15- For an OMAP5 SMP system:
16
17mpu {
18 compatible = "ti,omap5-mpu";
19 ti,hwmods = "mpu"
20};
21
14- For an OMAP4 SMP system: 22- For an OMAP4 SMP system:
15 23
16mpu { 24mpu {
diff --git a/Documentation/devicetree/bindings/arm/pmu.txt b/Documentation/devicetree/bindings/arm/pmu.txt
index 343781b9f246..3e1e498fea96 100644
--- a/Documentation/devicetree/bindings/arm/pmu.txt
+++ b/Documentation/devicetree/bindings/arm/pmu.txt
@@ -7,6 +7,7 @@ representation in the device tree should be done as under:-
7Required properties: 7Required properties:
8 8
9- compatible : should be one of 9- compatible : should be one of
10 "arm,armv8-pmuv3"
10 "arm,cortex-a15-pmu" 11 "arm,cortex-a15-pmu"
11 "arm,cortex-a9-pmu" 12 "arm,cortex-a9-pmu"
12 "arm,cortex-a8-pmu" 13 "arm,cortex-a8-pmu"
diff --git a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt
index 47ada1dff216..5d49f2b37f68 100644
--- a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt
+++ b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt
@@ -49,7 +49,7 @@ adc@12D10000 {
49 /* NTC thermistor is a hwmon device */ 49 /* NTC thermistor is a hwmon device */
50 ncp15wb473@0 { 50 ncp15wb473@0 {
51 compatible = "ntc,ncp15wb473"; 51 compatible = "ntc,ncp15wb473";
52 pullup-uV = <1800000>; 52 pullup-uv = <1800000>;
53 pullup-ohm = <47000>; 53 pullup-ohm = <47000>;
54 pulldown-ohm = <0>; 54 pulldown-ohm = <0>;
55 io-channels = <&adc 4>; 55 io-channels = <&adc 4>;
diff --git a/Documentation/devicetree/bindings/clock/exynos4-clock.txt b/Documentation/devicetree/bindings/clock/exynos4-clock.txt
index c6bf8a6c8f52..a2ac2d9ac71a 100644
--- a/Documentation/devicetree/bindings/clock/exynos4-clock.txt
+++ b/Documentation/devicetree/bindings/clock/exynos4-clock.txt
@@ -6,7 +6,7 @@ SoC's in the Exynos4 family.
6 6
7Required Properties: 7Required Properties:
8 8
9- comptible: should be one of the following. 9- compatible: should be one of the following.
10 - "samsung,exynos4210-clock" - controller compatible with Exynos4210 SoC. 10 - "samsung,exynos4210-clock" - controller compatible with Exynos4210 SoC.
11 - "samsung,exynos4412-clock" - controller compatible with Exynos4412 SoC. 11 - "samsung,exynos4412-clock" - controller compatible with Exynos4412 SoC.
12 12
diff --git a/Documentation/devicetree/bindings/clock/exynos5250-clock.txt b/Documentation/devicetree/bindings/clock/exynos5250-clock.txt
index 24765c146e31..46f5c791ea0d 100644
--- a/Documentation/devicetree/bindings/clock/exynos5250-clock.txt
+++ b/Documentation/devicetree/bindings/clock/exynos5250-clock.txt
@@ -5,7 +5,7 @@ controllers within the Exynos5250 SoC.
5 5
6Required Properties: 6Required Properties:
7 7
8- comptible: should be one of the following. 8- compatible: should be one of the following.
9 - "samsung,exynos5250-clock" - controller compatible with Exynos5250 SoC. 9 - "samsung,exynos5250-clock" - controller compatible with Exynos5250 SoC.
10 10
11- reg: physical base address of the controller and length of memory mapped 11- reg: physical base address of the controller and length of memory mapped
diff --git a/Documentation/devicetree/bindings/clock/exynos5420-clock.txt b/Documentation/devicetree/bindings/clock/exynos5420-clock.txt
index 32aa34ecad36..458f34789e5d 100644
--- a/Documentation/devicetree/bindings/clock/exynos5420-clock.txt
+++ b/Documentation/devicetree/bindings/clock/exynos5420-clock.txt
@@ -5,7 +5,7 @@ controllers within the Exynos5420 SoC.
5 5
6Required Properties: 6Required Properties:
7 7
8- comptible: should be one of the following. 8- compatible: should be one of the following.
9 - "samsung,exynos5420-clock" - controller compatible with Exynos5420 SoC. 9 - "samsung,exynos5420-clock" - controller compatible with Exynos5420 SoC.
10 10
11- reg: physical base address of the controller and length of memory mapped 11- reg: physical base address of the controller and length of memory mapped
diff --git a/Documentation/devicetree/bindings/clock/exynos5440-clock.txt b/Documentation/devicetree/bindings/clock/exynos5440-clock.txt
index 4499e9966bc9..9955dc9c7d96 100644
--- a/Documentation/devicetree/bindings/clock/exynos5440-clock.txt
+++ b/Documentation/devicetree/bindings/clock/exynos5440-clock.txt
@@ -5,7 +5,7 @@ controllers within the Exynos5440 SoC.
5 5
6Required Properties: 6Required Properties:
7 7
8- comptible: should be "samsung,exynos5440-clock". 8- compatible: should be "samsung,exynos5440-clock".
9 9
10- reg: physical base address of the controller and length of memory mapped 10- reg: physical base address of the controller and length of memory mapped
11 region. 11 region.
diff --git a/Documentation/devicetree/bindings/gpio/8xxx_gpio.txt b/Documentation/devicetree/bindings/gpio/8xxx_gpio.txt
index b0019eb5330e..798cfc9d3839 100644
--- a/Documentation/devicetree/bindings/gpio/8xxx_gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/8xxx_gpio.txt
@@ -5,16 +5,42 @@ This is for the non-QE/CPM/GUTs GPIO controllers as found on
5 5
6Every GPIO controller node must have #gpio-cells property defined, 6Every GPIO controller node must have #gpio-cells property defined,
7this information will be used to translate gpio-specifiers. 7this information will be used to translate gpio-specifiers.
8See bindings/gpio/gpio.txt for details of how to specify GPIO
9information for devices.
10
11The GPIO module usually is connected to the SoC's internal interrupt
12controller, see bindings/interrupt-controller/interrupts.txt (the
13interrupt client nodes section) for details how to specify this GPIO
14module's interrupt.
15
16The GPIO module may serve as another interrupt controller (cascaded to
17the SoC's internal interrupt controller). See the interrupt controller
18nodes section in bindings/interrupt-controller/interrupts.txt for
19details.
8 20
9Required properties: 21Required properties:
10- compatible : "fsl,<CHIP>-gpio" followed by "fsl,mpc8349-gpio" for 22- compatible: "fsl,<chip>-gpio" followed by "fsl,mpc8349-gpio"
11 83xx, "fsl,mpc8572-gpio" for 85xx and "fsl,mpc8610-gpio" for 86xx. 23 for 83xx, "fsl,mpc8572-gpio" for 85xx, or
12- #gpio-cells : Should be two. The first cell is the pin number and the 24 "fsl,mpc8610-gpio" for 86xx.
13 second cell is used to specify optional parameters (currently unused). 25- #gpio-cells: Should be two. The first cell is the pin number
14 - interrupts : Interrupt mapping for GPIO IRQ. 26 and the second cell is used to specify optional
15 - interrupt-parent : Phandle for the interrupt controller that 27 parameters (currently unused).
16 services interrupts for this device. 28- interrupt-parent: Phandle for the interrupt controller that
17- gpio-controller : Marks the port as GPIO controller. 29 services interrupts for this device.
30- interrupts: Interrupt mapping for GPIO IRQ.
31- gpio-controller: Marks the port as GPIO controller.
32
33Optional properties:
34- interrupt-controller: Empty boolean property which marks the GPIO
35 module as an IRQ controller.
36- #interrupt-cells: Should be two. Defines the number of integer
37 cells required to specify an interrupt within
38 this interrupt controller. The first cell
39 defines the pin number, the second cell
40 defines additional flags (trigger type,
41 trigger polarity). Note that the available
42 set of trigger conditions supported by the
43 GPIO module depends on the actual SoC.
18 44
19Example of gpio-controller nodes for a MPC8347 SoC: 45Example of gpio-controller nodes for a MPC8347 SoC:
20 46
@@ -22,39 +48,27 @@ Example of gpio-controller nodes for a MPC8347 SoC:
22 #gpio-cells = <2>; 48 #gpio-cells = <2>;
23 compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio"; 49 compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio";
24 reg = <0xc00 0x100>; 50 reg = <0xc00 0x100>;
25 interrupts = <74 0x8>;
26 interrupt-parent = <&ipic>; 51 interrupt-parent = <&ipic>;
52 interrupts = <74 0x8>;
27 gpio-controller; 53 gpio-controller;
54 interrupt-controller;
55 #interrupt-cells = <2>;
28 }; 56 };
29 57
30 gpio2: gpio-controller@d00 { 58 gpio2: gpio-controller@d00 {
31 #gpio-cells = <2>; 59 #gpio-cells = <2>;
32 compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio"; 60 compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio";
33 reg = <0xd00 0x100>; 61 reg = <0xd00 0x100>;
34 interrupts = <75 0x8>;
35 interrupt-parent = <&ipic>; 62 interrupt-parent = <&ipic>;
63 interrupts = <75 0x8>;
36 gpio-controller; 64 gpio-controller;
37 }; 65 };
38 66
39See booting-without-of.txt for details of how to specify GPIO 67Example of a peripheral using the GPIO module as an IRQ controller:
40information for devices.
41
42To use GPIO pins as interrupt sources for peripherals, specify the
43GPIO controller as the interrupt parent and define GPIO number +
44trigger mode using the interrupts property, which is defined like
45this:
46
47interrupts = <number trigger>, where:
48 - number: GPIO pin (0..31)
49 - trigger: trigger mode:
50 2 = trigger on falling edge
51 3 = trigger on both edges
52
53Example of device using this is:
54 68
55 funkyfpga@0 { 69 funkyfpga@0 {
56 compatible = "funky-fpga"; 70 compatible = "funky-fpga";
57 ... 71 ...
58 interrupts = <4 3>;
59 interrupt-parent = <&gpio1>; 72 interrupt-parent = <&gpio1>;
73 interrupts = <4 3>;
60 }; 74 };
diff --git a/Documentation/devicetree/bindings/i2c/i2c-omap.txt b/Documentation/devicetree/bindings/i2c/i2c-omap.txt
index 56564aa4b444..7e49839d4124 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-omap.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-omap.txt
@@ -1,7 +1,8 @@
1I2C for OMAP platforms 1I2C for OMAP platforms
2 2
3Required properties : 3Required properties :
4- compatible : Must be "ti,omap3-i2c" or "ti,omap4-i2c" 4- compatible : Must be "ti,omap2420-i2c", "ti,omap2430-i2c", "ti,omap3-i2c"
5 or "ti,omap4-i2c"
5- ti,hwmods : Must be "i2c<n>", n being the instance number (1-based) 6- ti,hwmods : Must be "i2c<n>", n being the instance number (1-based)
6- #address-cells = <1>; 7- #address-cells = <1>;
7- #size-cells = <0>; 8- #size-cells = <0>;
diff --git a/Documentation/devicetree/bindings/mmc/ti-omap.txt b/Documentation/devicetree/bindings/mmc/ti-omap.txt
new file mode 100644
index 000000000000..8de579969763
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/ti-omap.txt
@@ -0,0 +1,54 @@
1* TI MMC host controller for OMAP1 and 2420
2
3The MMC Host Controller on TI OMAP1 and 2420 family provides
4an interface for MMC, SD, and SDIO types of memory cards.
5
6This file documents differences between the core properties described
7by mmc.txt and the properties used by the omap mmc driver.
8
9Note that this driver will not work with omap2430 or later omaps,
10please see the omap hsmmc driver for the current omaps.
11
12Required properties:
13- compatible: Must be "ti,omap2420-mmc", for OMAP2420 controllers
14- ti,hwmods: For 2420, must be "msdi<n>", where n is controller
15 instance starting 1
16
17Examples:
18
19 msdi1: mmc@4809c000 {
20 compatible = "ti,omap2420-mmc";
21 ti,hwmods = "msdi1";
22 reg = <0x4809c000 0x80>;
23 interrupts = <83>;
24 dmas = <&sdma 61 &sdma 62>;
25 dma-names = "tx", "rx";
26 };
27
28* TI MMC host controller for OMAP1 and 2420
29
30The MMC Host Controller on TI OMAP1 and 2420 family provides
31an interface for MMC, SD, and SDIO types of memory cards.
32
33This file documents differences between the core properties described
34by mmc.txt and the properties used by the omap mmc driver.
35
36Note that this driver will not work with omap2430 or later omaps,
37please see the omap hsmmc driver for the current omaps.
38
39Required properties:
40- compatible: Must be "ti,omap2420-mmc", for OMAP2420 controllers
41- ti,hwmods: For 2420, must be "msdi<n>", where n is controller
42 instance starting 1
43
44Examples:
45
46 msdi1: mmc@4809c000 {
47 compatible = "ti,omap2420-mmc";
48 ti,hwmods = "msdi1";
49 reg = <0x4809c000 0x80>;
50 interrupts = <83>;
51 dmas = <&sdma 61 &sdma 62>;
52 dma-names = "tx", "rx";
53 };
54
diff --git a/Documentation/devicetree/bindings/net/fsl-fec.txt b/Documentation/devicetree/bindings/net/fsl-fec.txt
index d53639221403..845ff848d895 100644
--- a/Documentation/devicetree/bindings/net/fsl-fec.txt
+++ b/Documentation/devicetree/bindings/net/fsl-fec.txt
@@ -15,6 +15,7 @@ Optional properties:
15 only if property "phy-reset-gpios" is available. Missing the property 15 only if property "phy-reset-gpios" is available. Missing the property
16 will have the duration be 1 millisecond. Numbers greater than 1000 are 16 will have the duration be 1 millisecond. Numbers greater than 1000 are
17 invalid and 1 millisecond will be used instead. 17 invalid and 1 millisecond will be used instead.
18- phy-supply: regulator that powers the Ethernet PHY.
18 19
19Example: 20Example:
20 21
@@ -25,4 +26,5 @@ ethernet@83fec000 {
25 phy-mode = "mii"; 26 phy-mode = "mii";
26 phy-reset-gpios = <&gpio2 14 0>; /* GPIO2_14 */ 27 phy-reset-gpios = <&gpio2 14 0>; /* GPIO2_14 */
27 local-mac-address = [00 04 9F 01 1B B9]; 28 local-mac-address = [00 04 9F 01 1B B9];
29 phy-supply = <&reg_fec_supply>;
28}; 30};
diff --git a/Documentation/devicetree/bindings/rng/qcom,prng.txt b/Documentation/devicetree/bindings/rng/qcom,prng.txt
new file mode 100644
index 000000000000..8e5853c2879b
--- /dev/null
+++ b/Documentation/devicetree/bindings/rng/qcom,prng.txt
@@ -0,0 +1,17 @@
1Qualcomm MSM pseudo random number generator.
2
3Required properties:
4
5- compatible : should be "qcom,prng"
6- reg : specifies base physical address and size of the registers map
7- clocks : phandle to clock-controller plus clock-specifier pair
8- clock-names : "core" clocks all registers, FIFO and circuits in PRNG IP block
9
10Example:
11
12 rng@f9bff000 {
13 compatible = "qcom,prng";
14 reg = <0xf9bff000 0x200>;
15 clocks = <&clock GCC_PRNG_AHB_CLK>;
16 clock-names = "core";
17 };
diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra20-spi.txt b/Documentation/devicetree/bindings/spi/nvidia,tegra20-spi.txt
deleted file mode 100644
index 6b9e51896693..000000000000
--- a/Documentation/devicetree/bindings/spi/nvidia,tegra20-spi.txt
+++ /dev/null
@@ -1,5 +0,0 @@
1NVIDIA Tegra 2 SPI device
2
3Required properties:
4- compatible : should be "nvidia,tegra20-spi".
5- gpios : should specify GPIOs used for chipselect.
diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt
index ce95ed1c6d3e..edbb8d88c85e 100644
--- a/Documentation/devicetree/bindings/vendor-prefixes.txt
+++ b/Documentation/devicetree/bindings/vendor-prefixes.txt
@@ -32,12 +32,14 @@ est ESTeem Wireless Modems
32fsl Freescale Semiconductor 32fsl Freescale Semiconductor
33GEFanuc GE Fanuc Intelligent Platforms Embedded Systems, Inc. 33GEFanuc GE Fanuc Intelligent Platforms Embedded Systems, Inc.
34gef GE Fanuc Intelligent Platforms Embedded Systems, Inc. 34gef GE Fanuc Intelligent Platforms Embedded Systems, Inc.
35gmt Global Mixed-mode Technology, Inc.
35hisilicon Hisilicon Limited. 36hisilicon Hisilicon Limited.
36hp Hewlett Packard 37hp Hewlett Packard
37ibm International Business Machines (IBM) 38ibm International Business Machines (IBM)
38idt Integrated Device Technologies, Inc. 39idt Integrated Device Technologies, Inc.
39img Imagination Technologies Ltd. 40img Imagination Technologies Ltd.
40intercontrol Inter Control Group 41intercontrol Inter Control Group
42lg LG Corporation
41linux Linux-specific binding 43linux Linux-specific binding
42lsi LSI Corp. (LSI Logic) 44lsi LSI Corp. (LSI Logic)
43marvell Marvell Technology Group Ltd. 45marvell Marvell Technology Group Ltd.
diff --git a/Documentation/gpio/00-INDEX b/Documentation/gpio/00-INDEX
new file mode 100644
index 000000000000..1de43ae46ae6
--- /dev/null
+++ b/Documentation/gpio/00-INDEX
@@ -0,0 +1,14 @@
100-INDEX
2 - This file
3gpio.txt
4 - Introduction to GPIOs and their kernel interfaces
5consumer.txt
6 - How to obtain and use GPIOs in a driver
7driver.txt
8 - How to write a GPIO driver
9board.txt
10 - How to assign GPIOs to a consumer device and a function
11sysfs.txt
12 - Information about the GPIO sysfs interface
13gpio-legacy.txt
14 - Historical documentation of the deprecated GPIO integer interface
diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt
new file mode 100644
index 000000000000..0d03506f2cc5
--- /dev/null
+++ b/Documentation/gpio/board.txt
@@ -0,0 +1,115 @@
1GPIO Mappings
2=============
3
4This document explains how GPIOs can be assigned to given devices and functions.
5Note that it only applies to the new descriptor-based interface. For a
6description of the deprecated integer-based GPIO interface please refer to
7gpio-legacy.txt (actually, there is no real mapping possible with the old
8interface; you just fetch an integer from somewhere and request the
9corresponding GPIO.
10
11Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage
12is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in
13their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
14describe its hardware layout. Currently, mappings can be defined through device
15tree, ACPI, and platform data.
16
17Device Tree
18-----------
19GPIOs can easily be mapped to devices and functions in the device tree. The
20exact way to do it depends on the GPIO controller providing the GPIOs, see the
21device tree bindings for your controller.
22
23GPIOs mappings are defined in the consumer device's node, in a property named
24<function>-gpios, where <function> is the function the driver will request
25through gpiod_get(). For example:
26
27 foo_device {
28 compatible = "acme,foo";
29 ...
30 led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
31 <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
32 <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
33
34 power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>;
35 };
36
37This property will make GPIOs 15, 16 and 17 available to the driver under the
38"led" function, and GPIO 1 as the "power" GPIO:
39
40 struct gpio_desc *red, *green, *blue, *power;
41
42 red = gpiod_get_index(dev, "led", 0);
43 green = gpiod_get_index(dev, "led", 1);
44 blue = gpiod_get_index(dev, "led", 2);
45
46 power = gpiod_get(dev, "power");
47
48The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.
49gpiod_is_active_low(power) will be true).
50
51ACPI
52----
53ACPI does not support function names for GPIOs. Therefore, only the "idx"
54argument of gpiod_get_index() is useful to discriminate between GPIOs assigned
55to a device. The "con_id" argument can still be set for debugging purposes (it
56will appear under error messages as well as debug and sysfs nodes).
57
58Platform Data
59-------------
60Finally, GPIOs can be bound to devices and functions using platform data. Board
61files that desire to do so need to include the following header:
62
63 #include <linux/gpio/driver.h>
64
65GPIOs are mapped by the means of tables of lookups, containing instances of the
66gpiod_lookup structure. Two macros are defined to help declaring such mappings:
67
68 GPIO_LOOKUP(chip_label, chip_hwnum, dev_id, con_id, flags)
69 GPIO_LOOKUP_IDX(chip_label, chip_hwnum, dev_id, con_id, idx, flags)
70
71where
72
73 - chip_label is the label of the gpiod_chip instance providing the GPIO
74 - chip_hwnum is the hardware number of the GPIO within the chip
75 - dev_id is the identifier of the device that will make use of this GPIO. If
76 NULL, the GPIO will be available to all devices.
77 - con_id is the name of the GPIO function from the device point of view. It
78 can be NULL.
79 - idx is the index of the GPIO within the function.
80 - flags is defined to specify the following properties:
81 * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low
82 * GPIOF_OPEN_DRAIN - GPIO pin is open drain type.
83 * GPIOF_OPEN_SOURCE - GPIO pin is open source type.
84
85In the future, these flags might be extended to support more properties.
86
87Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
88
89A lookup table can then be defined as follows:
90
91 struct gpiod_lookup gpios_table[] = {
92 GPIO_LOOKUP_IDX("gpio.0", 15, "foo.0", "led", 0, GPIO_ACTIVE_HIGH),
93 GPIO_LOOKUP_IDX("gpio.0", 16, "foo.0", "led", 1, GPIO_ACTIVE_HIGH),
94 GPIO_LOOKUP_IDX("gpio.0", 17, "foo.0", "led", 2, GPIO_ACTIVE_HIGH),
95 GPIO_LOOKUP("gpio.0", 1, "foo.0", "power", GPIO_ACTIVE_LOW),
96 };
97
98And the table can be added by the board code as follows:
99
100 gpiod_add_table(gpios_table, ARRAY_SIZE(gpios_table));
101
102The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
103
104 struct gpio_desc *red, *green, *blue, *power;
105
106 red = gpiod_get_index(dev, "led", 0);
107 green = gpiod_get_index(dev, "led", 1);
108 blue = gpiod_get_index(dev, "led", 2);
109
110 power = gpiod_get(dev, "power");
111 gpiod_direction_output(power, 1);
112
113Since the "power" GPIO is mapped as active-low, its actual signal will be 0
114after this code. Contrary to the legacy integer GPIO interface, the active-low
115property is handled during mapping and is thus transparent to GPIO consumers.
diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt
new file mode 100644
index 000000000000..07c74a3765a0
--- /dev/null
+++ b/Documentation/gpio/consumer.txt
@@ -0,0 +1,197 @@
1GPIO Descriptor Consumer Interface
2==================================
3
4This document describes the consumer interface of the GPIO framework. Note that
5it describes the new descriptor-based interface. For a description of the
6deprecated integer-based GPIO interface please refer to gpio-legacy.txt.
7
8
9Guidelines for GPIOs consumers
10==============================
11
12Drivers that can't work without standard GPIO calls should have Kconfig entries
13that depend on GPIOLIB. The functions that allow a driver to obtain and use
14GPIOs are available by including the following file:
15
16 #include <linux/gpio/consumer.h>
17
18All the functions that work with the descriptor-based GPIO interface are
19prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No
20other function in the kernel should use these prefixes.
21
22
23Obtaining and Disposing GPIOs
24=============================
25
26With the descriptor-based interface, GPIOs are identified with an opaque,
27non-forgeable handler that must be obtained through a call to one of the
28gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the
29device that will use the GPIO and the function the requested GPIO is supposed to
30fulfill:
31
32 struct gpio_desc *gpiod_get(struct device *dev, const char *con_id)
33
34If a function is implemented by using several GPIOs together (e.g. a simple LED
35device that displays digits), an additional index argument can be specified:
36
37 struct gpio_desc *gpiod_get_index(struct device *dev,
38 const char *con_id, unsigned int idx)
39
40Both functions return either a valid GPIO descriptor, or an error code checkable
41with IS_ERR(). They will never return a NULL pointer.
42
43Device-managed variants of these functions are also defined:
44
45 struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id)
46
47 struct gpio_desc *devm_gpiod_get_index(struct device *dev,
48 const char *con_id,
49 unsigned int idx)
50
51A GPIO descriptor can be disposed of using the gpiod_put() function:
52
53 void gpiod_put(struct gpio_desc *desc)
54
55It is strictly forbidden to use a descriptor after calling this function. The
56device-managed variant is, unsurprisingly:
57
58 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
59
60
61Using GPIOs
62===========
63
64Setting Direction
65-----------------
66The first thing a driver must do with a GPIO is setting its direction. This is
67done by invoking one of the gpiod_direction_*() functions:
68
69 int gpiod_direction_input(struct gpio_desc *desc)
70 int gpiod_direction_output(struct gpio_desc *desc, int value)
71
72The return value is zero for success, else a negative errno. It should be
73checked, since the get/set calls don't return errors and since misconfiguration
74is possible. You should normally issue these calls from a task context. However,
75for spinlock-safe GPIOs it is OK to use them before tasking is enabled, as part
76of early board setup.
77
78For output GPIOs, the value provided becomes the initial output value. This
79helps avoid signal glitching during system startup.
80
81A driver can also query the current direction of a GPIO:
82
83 int gpiod_get_direction(const struct gpio_desc *desc)
84
85This function will return either GPIOF_DIR_IN or GPIOF_DIR_OUT.
86
87Be aware that there is no default direction for GPIOs. Therefore, **using a GPIO
88without setting its direction first is illegal and will result in undefined
89behavior!**
90
91
92Spinlock-Safe GPIO Access
93-------------------------
94Most GPIO controllers can be accessed with memory read/write instructions. Those
95don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ
96handlers and similar contexts.
97
98Use the following calls to access GPIOs from an atomic context:
99
100 int gpiod_get_value(const struct gpio_desc *desc);
101 void gpiod_set_value(struct gpio_desc *desc, int value);
102
103The values are boolean, zero for low, nonzero for high. When reading the value
104of an output pin, the value returned should be what's seen on the pin. That
105won't always match the specified output value, because of issues including
106open-drain signaling and output latencies.
107
108The get/set calls do not return errors because "invalid GPIO" should have been
109reported earlier from gpiod_direction_*(). However, note that not all platforms
110can read the value of output pins; those that can't should always return zero.
111Also, using these calls for GPIOs that can't safely be accessed without sleeping
112(see below) is an error.
113
114
115GPIO Access That May Sleep
116--------------------------
117Some GPIO controllers must be accessed using message based buses like I2C or
118SPI. Commands to read or write those GPIO values require waiting to get to the
119head of a queue to transmit a command and get its response. This requires
120sleeping, which can't be done from inside IRQ handlers.
121
122Platforms that support this type of GPIO distinguish them from other GPIOs by
123returning nonzero from this call:
124
125 int gpiod_cansleep(const struct gpio_desc *desc)
126
127To access such GPIOs, a different set of accessors is defined:
128
129 int gpiod_get_value_cansleep(const struct gpio_desc *desc)
130 void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)
131
132Accessing such GPIOs requires a context which may sleep, for example a threaded
133IRQ handler, and those accessors must be used instead of spinlock-safe
134accessors without the cansleep() name suffix.
135
136Other than the fact that these accessors might sleep, and will work on GPIOs
137that can't be accessed from hardIRQ handlers, these calls act the same as the
138spinlock-safe calls.
139
140
141Active-low State and Raw GPIO Values
142------------------------------------
143Device drivers like to manage the logical state of a GPIO, i.e. the value their
144device will actually receive, no matter what lies between it and the GPIO line.
145In some cases, it might make sense to control the actual GPIO line value. The
146following set of calls ignore the active-low property of a GPIO and work on the
147raw line value:
148
149 int gpiod_get_raw_value(const struct gpio_desc *desc)
150 void gpiod_set_raw_value(struct gpio_desc *desc, int value)
151 int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)
152 void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
153
154The active-low state of a GPIO can also be queried using the following call:
155
156 int gpiod_is_active_low(const struct gpio_desc *desc)
157
158Note that these functions should only be used with great moderation ; a driver
159should not have to care about the physical line level.
160
161GPIOs mapped to IRQs
162--------------------
163GPIO lines can quite often be used as IRQs. You can get the IRQ number
164corresponding to a given GPIO using the following call:
165
166 int gpiod_to_irq(const struct gpio_desc *desc)
167
168It will return an IRQ number, or an negative errno code if the mapping can't be
169done (most likely because that particular GPIO cannot be used as IRQ). It is an
170unchecked error to use a GPIO that wasn't set up as an input using
171gpiod_direction_input(), or to use an IRQ number that didn't originally come
172from gpiod_to_irq(). gpiod_to_irq() is not allowed to sleep.
173
174Non-error values returned from gpiod_to_irq() can be passed to request_irq() or
175free_irq(). They will often be stored into IRQ resources for platform devices,
176by the board-specific initialization code. Note that IRQ trigger options are
177part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are system wakeup
178capabilities.
179
180
181Interacting With the Legacy GPIO Subsystem
182==========================================
183Many kernel subsystems still handle GPIOs using the legacy integer-based
184interface. Although it is strongly encouraged to upgrade them to the safer
185descriptor-based API, the following two functions allow you to convert a GPIO
186descriptor into the GPIO integer namespace and vice-versa:
187
188 int desc_to_gpio(const struct gpio_desc *desc)
189 struct gpio_desc *gpio_to_desc(unsigned gpio)
190
191The GPIO number returned by desc_to_gpio() can be safely used as long as the
192GPIO descriptor has not been freed. All the same, a GPIO number passed to
193gpio_to_desc() must have been properly acquired, and usage of the returned GPIO
194descriptor is only possible after the GPIO number has been released.
195
196Freeing a GPIO obtained by one API with the other API is forbidden and an
197unchecked error.
diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt
new file mode 100644
index 000000000000..9da0bfa74781
--- /dev/null
+++ b/Documentation/gpio/driver.txt
@@ -0,0 +1,75 @@
1GPIO Descriptor Driver Interface
2================================
3
4This document serves as a guide for GPIO chip drivers writers. Note that it
5describes the new descriptor-based interface. For a description of the
6deprecated integer-based GPIO interface please refer to gpio-legacy.txt.
7
8Each GPIO controller driver needs to include the following header, which defines
9the structures used to define a GPIO driver:
10
11 #include <linux/gpio/driver.h>
12
13
14Internal Representation of GPIOs
15================================
16
17Inside a GPIO driver, individual GPIOs are identified by their hardware number,
18which is a unique number between 0 and n, n being the number of GPIOs managed by
19the chip. This number is purely internal: the hardware number of a particular
20GPIO descriptor is never made visible outside of the driver.
21
22On top of this internal number, each GPIO also need to have a global number in
23the integer GPIO namespace so that it can be used with the legacy GPIO
24interface. Each chip must thus have a "base" number (which can be automatically
25assigned), and for each GPIO the global number will be (base + hardware number).
26Although the integer representation is considered deprecated, it still has many
27users and thus needs to be maintained.
28
29So for example one platform could use numbers 32-159 for GPIOs, with a
30controller defining 128 GPIOs at a "base" of 32 ; while another platform uses
31numbers 0..63 with one set of GPIO controllers, 64-79 with another type of GPIO
32controller, and on one particular board 80-95 with an FPGA. The numbers need not
33be contiguous; either of those platforms could also use numbers 2000-2063 to
34identify GPIOs in a bank of I2C GPIO expanders.
35
36
37Controller Drivers: gpio_chip
38=============================
39
40In the gpiolib framework each GPIO controller is packaged as a "struct
41gpio_chip" (see linux/gpio/driver.h for its complete definition) with members
42common to each controller of that type:
43
44 - methods to establish GPIO direction
45 - methods used to access GPIO values
46 - method to return the IRQ number associated to a given GPIO
47 - flag saying whether calls to its methods may sleep
48 - optional debugfs dump method (showing extra state like pullup config)
49 - optional base number (will be automatically assigned if omitted)
50 - label for diagnostics and GPIOs mapping using platform data
51
52The code implementing a gpio_chip should support multiple instances of the
53controller, possibly using the driver model. That code will configure each
54gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be rare;
55use gpiochip_remove() when it is unavoidable.
56
57Most often a gpio_chip is part of an instance-specific structure with state not
58exposed by the GPIO interfaces, such as addressing, power management, and more.
59Chips such as codecs will have complex non-GPIO state.
60
61Any debugfs dump method should normally ignore signals which haven't been
62requested as GPIOs. They can use gpiochip_is_requested(), which returns either
63NULL or the label associated with that GPIO when it was requested.
64
65Locking IRQ usage
66-----------------
67Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
68to mark the GPIO as being used as an IRQ:
69
70 int gpiod_lock_as_irq(struct gpio_desc *desc)
71
72This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
73is released:
74
75 void gpiod_unlock_as_irq(struct gpio_desc *desc)
diff --git a/Documentation/gpio.txt b/Documentation/gpio/gpio-legacy.txt
index 6f83fa965b4b..6f83fa965b4b 100644
--- a/Documentation/gpio.txt
+++ b/Documentation/gpio/gpio-legacy.txt
diff --git a/Documentation/gpio/gpio.txt b/Documentation/gpio/gpio.txt
new file mode 100644
index 000000000000..cd9b356e88cd
--- /dev/null
+++ b/Documentation/gpio/gpio.txt
@@ -0,0 +1,119 @@
1GPIO Interfaces
2===============
3
4The documents in this directory give detailed instructions on how to access
5GPIOs in drivers, and how to write a driver for a device that provides GPIOs
6itself.
7
8Due to the history of GPIO interfaces in the kernel, there are two different
9ways to obtain and use GPIOs:
10
11 - The descriptor-based interface is the preferred way to manipulate GPIOs,
12and is described by all the files in this directory excepted gpio-legacy.txt.
13 - The legacy integer-based interface which is considered deprecated (but still
14usable for compatibility reasons) is documented in gpio-legacy.txt.
15
16The remainder of this document applies to the new descriptor-based interface.
17gpio-legacy.txt contains the same information applied to the legacy
18integer-based interface.
19
20
21What is a GPIO?
22===============
23
24A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
25digital signal. They are provided from many kinds of chip, and are familiar
26to Linux developers working with embedded and custom hardware. Each GPIO
27represents a bit connected to a particular pin, or "ball" on Ball Grid Array
28(BGA) packages. Board schematics show which external hardware connects to
29which GPIOs. Drivers can be written generically, so that board setup code
30passes such pin configuration data to drivers.
31
32System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
33non-dedicated pin can be configured as a GPIO; and most chips have at least
34several dozen of them. Programmable logic devices (like FPGAs) can easily
35provide GPIOs; multifunction chips like power managers, and audio codecs
36often have a few such pins to help with pin scarcity on SOCs; and there are
37also "GPIO Expander" chips that connect using the I2C or SPI serial buses.
38Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
39firmware knowing how they're used).
40
41The exact capabilities of GPIOs vary between systems. Common options:
42
43 - Output values are writable (high=1, low=0). Some chips also have
44 options about how that value is driven, so that for example only one
45 value might be driven, supporting "wire-OR" and similar schemes for the
46 other value (notably, "open drain" signaling).
47
48 - Input values are likewise readable (1, 0). Some chips support readback
49 of pins configured as "output", which is very useful in such "wire-OR"
50 cases (to support bidirectional signaling). GPIO controllers may have
51 input de-glitch/debounce logic, sometimes with software controls.
52
53 - Inputs can often be used as IRQ signals, often edge triggered but
54 sometimes level triggered. Such IRQs may be configurable as system
55 wakeup events, to wake the system from a low power state.
56
57 - Usually a GPIO will be configurable as either input or output, as needed
58 by different product boards; single direction ones exist too.
59
60 - Most GPIOs can be accessed while holding spinlocks, but those accessed
61 through a serial bus normally can't. Some systems support both types.
62
63On a given board each GPIO is used for one specific purpose like monitoring
64MMC/SD card insertion/removal, detecting card write-protect status, driving
65a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware
66watchdog, sensing a switch, and so on.
67
68
69Common GPIO Properties
70======================
71
72These properties are met through all the other documents of the GPIO interface
73and it is useful to understand them, especially if you need to define GPIO
74mappings.
75
76Active-High and Active-Low
77--------------------------
78It is natural to assume that a GPIO is "active" when its output signal is 1
79("high"), and inactive when it is 0 ("low"). However in practice the signal of a
80GPIO may be inverted before is reaches its destination, or a device could decide
81to have different conventions about what "active" means. Such decisions should
82be transparent to device drivers, therefore it is possible to define a GPIO as
83being either active-high ("1" means "active", the default) or active-low ("0"
84means "active") so that drivers only need to worry about the logical signal and
85not about what happens at the line level.
86
87Open Drain and Open Source
88--------------------------
89Sometimes shared signals need to use "open drain" (where only the low signal
90level is actually driven), or "open source" (where only the high signal level is
91driven) signaling. That term applies to CMOS transistors; "open collector" is
92used for TTL. A pullup or pulldown resistor causes the high or low signal level.
93This is sometimes called a "wire-AND"; or more practically, from the negative
94logic (low=true) perspective this is a "wire-OR".
95
96One common example of an open drain signal is a shared active-low IRQ line.
97Also, bidirectional data bus signals sometimes use open drain signals.
98
99Some GPIO controllers directly support open drain and open source outputs; many
100don't. When you need open drain signaling but your hardware doesn't directly
101support it, there's a common idiom you can use to emulate it with any GPIO pin
102that can be used as either an input or an output:
103
104 LOW: gpiod_direction_output(gpio, 0) ... this drives the signal and overrides
105 the pullup.
106
107 HIGH: gpiod_direction_input(gpio) ... this turns off the output, so the pullup
108 (or some other device) controls the signal.
109
110The same logic can be applied to emulate open source signaling, by driving the
111high signal and configuring the GPIO as input for low. This open drain/open
112source emulation can be handled transparently by the GPIO framework.
113
114If you are "driving" the signal high but gpiod_get_value(gpio) reports a low
115value (after the appropriate rise time passes), you know some other component is
116driving the shared signal low. That's not necessarily an error. As one common
117example, that's how I2C clocks are stretched: a slave that needs a slower clock
118delays the rising edge of SCK, and the I2C master adjusts its signaling rate
119accordingly.
diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.txt
new file mode 100644
index 000000000000..c2c3a97f8ff7
--- /dev/null
+++ b/Documentation/gpio/sysfs.txt
@@ -0,0 +1,155 @@
1GPIO Sysfs Interface for Userspace
2==================================
3
4Platforms which use the "gpiolib" implementors framework may choose to
5configure a sysfs user interface to GPIOs. This is different from the
6debugfs interface, since it provides control over GPIO direction and
7value instead of just showing a gpio state summary. Plus, it could be
8present on production systems without debugging support.
9
10Given appropriate hardware documentation for the system, userspace could
11know for example that GPIO #23 controls the write protect line used to
12protect boot loader segments in flash memory. System upgrade procedures
13may need to temporarily remove that protection, first importing a GPIO,
14then changing its output state, then updating the code before re-enabling
15the write protection. In normal use, GPIO #23 would never be touched,
16and the kernel would have no need to know about it.
17
18Again depending on appropriate hardware documentation, on some systems
19userspace GPIO can be used to determine system configuration data that
20standard kernels won't know about. And for some tasks, simple userspace
21GPIO drivers could be all that the system really needs.
22
23Note that standard kernel drivers exist for common "LEDs and Buttons"
24GPIO tasks: "leds-gpio" and "gpio_keys", respectively. Use those
25instead of talking directly to the GPIOs; they integrate with kernel
26frameworks better than your userspace code could.
27
28
29Paths in Sysfs
30--------------
31There are three kinds of entry in /sys/class/gpio:
32
33 - Control interfaces used to get userspace control over GPIOs;
34
35 - GPIOs themselves; and
36
37 - GPIO controllers ("gpio_chip" instances).
38
39That's in addition to standard files including the "device" symlink.
40
41The control interfaces are write-only:
42
43 /sys/class/gpio/
44
45 "export" ... Userspace may ask the kernel to export control of
46 a GPIO to userspace by writing its number to this file.
47
48 Example: "echo 19 > export" will create a "gpio19" node
49 for GPIO #19, if that's not requested by kernel code.
50
51 "unexport" ... Reverses the effect of exporting to userspace.
52
53 Example: "echo 19 > unexport" will remove a "gpio19"
54 node exported using the "export" file.
55
56GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
57and have the following read/write attributes:
58
59 /sys/class/gpio/gpioN/
60
61 "direction" ... reads as either "in" or "out". This value may
62 normally be written. Writing as "out" defaults to
63 initializing the value as low. To ensure glitch free
64 operation, values "low" and "high" may be written to
65 configure the GPIO as an output with that initial value.
66
67 Note that this attribute *will not exist* if the kernel
68 doesn't support changing the direction of a GPIO, or
69 it was exported by kernel code that didn't explicitly
70 allow userspace to reconfigure this GPIO's direction.
71
72 "value" ... reads as either 0 (low) or 1 (high). If the GPIO
73 is configured as an output, this value may be written;
74 any nonzero value is treated as high.
75
76 If the pin can be configured as interrupt-generating interrupt
77 and if it has been configured to generate interrupts (see the
78 description of "edge"), you can poll(2) on that file and
79 poll(2) will return whenever the interrupt was triggered. If
80 you use poll(2), set the events POLLPRI and POLLERR. If you
81 use select(2), set the file descriptor in exceptfds. After
82 poll(2) returns, either lseek(2) to the beginning of the sysfs
83 file and read the new value or close the file and re-open it
84 to read the value.
85
86 "edge" ... reads as either "none", "rising", "falling", or
87 "both". Write these strings to select the signal edge(s)
88 that will make poll(2) on the "value" file return.
89
90 This file exists only if the pin can be configured as an
91 interrupt generating input pin.
92
93 "active_low" ... reads as either 0 (false) or 1 (true). Write
94 any nonzero value to invert the value attribute both
95 for reading and writing. Existing and subsequent
96 poll(2) support configuration via the edge attribute
97 for "rising" and "falling" edges will follow this
98 setting.
99
100GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
101controller implementing GPIOs starting at #42) and have the following
102read-only attributes:
103
104 /sys/class/gpio/gpiochipN/
105
106 "base" ... same as N, the first GPIO managed by this chip
107
108 "label" ... provided for diagnostics (not always unique)
109
110 "ngpio" ... how many GPIOs this manges (N to N + ngpio - 1)
111
112Board documentation should in most cases cover what GPIOs are used for
113what purposes. However, those numbers are not always stable; GPIOs on
114a daughtercard might be different depending on the base board being used,
115or other cards in the stack. In such cases, you may need to use the
116gpiochip nodes (possibly in conjunction with schematics) to determine
117the correct GPIO number to use for a given signal.
118
119
120Exporting from Kernel code
121--------------------------
122Kernel code can explicitly manage exports of GPIOs which have already been
123requested using gpio_request():
124
125 /* export the GPIO to userspace */
126 int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
127
128 /* reverse gpio_export() */
129 void gpiod_unexport(struct gpio_desc *desc);
130
131 /* create a sysfs link to an exported GPIO node */
132 int gpiod_export_link(struct device *dev, const char *name,
133 struct gpio_desc *desc);
134
135 /* change the polarity of a GPIO node in sysfs */
136 int gpiod_sysfs_set_active_low(struct gpio_desc *desc, int value);
137
138After a kernel driver requests a GPIO, it may only be made available in
139the sysfs interface by gpiod_export(). The driver can control whether the
140signal direction may change. This helps drivers prevent userspace code
141from accidentally clobbering important system state.
142
143This explicit exporting can help with debugging (by making some kinds
144of experiments easier), or can provide an always-there interface that's
145suitable for documenting as part of a board support package.
146
147After the GPIO has been exported, gpiod_export_link() allows creating
148symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
149use this to provide the interface under their own device in sysfs with
150a descriptive name.
151
152Drivers can use gpiod_sysfs_set_active_low() to hide GPIO line polarity
153differences between boards from user space. Polarity change can be done both
154before and after gpiod_export(), and previously enabled poll(2) support for
155either rising or falling edge will be reconfigured to follow this setting.
generated by cgit v1.2.2 (git 2.25.0) at 2025-01-01 19:04:09 -0500