Eric Lee / smarc-fsl-linux-kernel

Download as
Browse Code »

Commit c2746a1eb741759590e8766958232d06a71840d5

Authored by Mauro Carvalho Chehab
1 parent 4c68060bf6

docs: gpio: add sysfs interface to the admin-guide 

While this is stated as obsoleted, the sysfs interface described
there is still valid, and belongs to the admin-guide.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Linus Walleij <linus.walleij@linaro.org>

Showing 9 changed files with 190 additions and 189 deletions Side-by-side Diff

Documentation/ABI/obsolete/sysfs-gpio
Diff comments   View file @ c2746a1
... ... @@ -11,7 +11,7 @@
11 11 Kernel code may export it for complete or partial access.
12 12  
13 13 GPIOs are identified as they are inside the kernel, using integers in
14   - the range 0..INT_MAX. See Documentation/gpio for more information.
  14 + the range 0..INT_MAX. See Documentation/admin-guide/gpio for more information.
15 15  
16 16 /sys/class/gpio
17 17 /export ... asks the kernel to export a GPIO to userspace
Documentation/admin-guide/gpio/index.rst
Diff comments   View file @ c2746a1
  1 +.. SPDX-License-Identifier: GPL-2.0
  2 +
  3 +====
  4 +gpio
  5 +====
  6 +
  7 +.. toctree::
  8 + :maxdepth: 1
  9 +
  10 + sysfs
  11 +
  12 +.. only:: subproject and html
  13 +
  14 + Indices
  15 + =======
  16 +
  17 + * :ref:`genindex`
Documentation/admin-guide/gpio/sysfs.rst
Diff comments   View file @ c2746a1
  1 +GPIO Sysfs Interface for Userspace
  2 +==================================
  3 +
  4 +.. warning::
  5 +
  6 + THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
  7 + Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
  8 + ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
  9 + NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
  10 +
  11 +Refer to the examples in tools/gpio/* for an introduction to the new
  12 +character device ABI. Also see the userspace header in
  13 +include/uapi/linux/gpio.h
  14 +
  15 +The deprecated sysfs ABI
  16 +------------------------
  17 +Platforms which use the "gpiolib" implementors framework may choose to
  18 +configure a sysfs user interface to GPIOs. This is different from the
  19 +debugfs interface, since it provides control over GPIO direction and
  20 +value instead of just showing a gpio state summary. Plus, it could be
  21 +present on production systems without debugging support.
  22 +
  23 +Given appropriate hardware documentation for the system, userspace could
  24 +know for example that GPIO #23 controls the write protect line used to
  25 +protect boot loader segments in flash memory. System upgrade procedures
  26 +may need to temporarily remove that protection, first importing a GPIO,
  27 +then changing its output state, then updating the code before re-enabling
  28 +the write protection. In normal use, GPIO #23 would never be touched,
  29 +and the kernel would have no need to know about it.
  30 +
  31 +Again depending on appropriate hardware documentation, on some systems
  32 +userspace GPIO can be used to determine system configuration data that
  33 +standard kernels won't know about. And for some tasks, simple userspace
  34 +GPIO drivers could be all that the system really needs.
  35 +
  36 +DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS.
  37 +PLEASE READ THE DOCUMENT AT Documentation/driver-api/gpio/drivers-on-gpio.rst
  38 +TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY.
  39 +
  40 +Paths in Sysfs
  41 +--------------
  42 +There are three kinds of entries in /sys/class/gpio:
  43 +
  44 + - Control interfaces used to get userspace control over GPIOs;
  45 +
  46 + - GPIOs themselves; and
  47 +
  48 + - GPIO controllers ("gpio_chip" instances).
  49 +
  50 +That's in addition to standard files including the "device" symlink.
  51 +
  52 +The control interfaces are write-only:
  53 +
  54 + /sys/class/gpio/
  55 +
  56 + "export" ...
  57 + Userspace may ask the kernel to export control of
  58 + a GPIO to userspace by writing its number to this file.
  59 +
  60 + Example: "echo 19 > export" will create a "gpio19" node
  61 + for GPIO #19, if that's not requested by kernel code.
  62 +
  63 + "unexport" ...
  64 + Reverses the effect of exporting to userspace.
  65 +
  66 + Example: "echo 19 > unexport" will remove a "gpio19"
  67 + node exported using the "export" file.
  68 +
  69 +GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
  70 +and have the following read/write attributes:
  71 +
  72 + /sys/class/gpio/gpioN/
  73 +
  74 + "direction" ...
  75 + reads as either "in" or "out". This value may
  76 + normally be written. Writing as "out" defaults to
  77 + initializing the value as low. To ensure glitch free
  78 + operation, values "low" and "high" may be written to
  79 + configure the GPIO as an output with that initial value.
  80 +
  81 + Note that this attribute *will not exist* if the kernel
  82 + doesn't support changing the direction of a GPIO, or
  83 + it was exported by kernel code that didn't explicitly
  84 + allow userspace to reconfigure this GPIO's direction.
  85 +
  86 + "value" ...
  87 + reads as either 0 (low) or 1 (high). If the GPIO
  88 + is configured as an output, this value may be written;
  89 + any nonzero value is treated as high.
  90 +
  91 + If the pin can be configured as interrupt-generating interrupt
  92 + and if it has been configured to generate interrupts (see the
  93 + description of "edge"), you can poll(2) on that file and
  94 + poll(2) will return whenever the interrupt was triggered. If
  95 + you use poll(2), set the events POLLPRI and POLLERR. If you
  96 + use select(2), set the file descriptor in exceptfds. After
  97 + poll(2) returns, either lseek(2) to the beginning of the sysfs
  98 + file and read the new value or close the file and re-open it
  99 + to read the value.
  100 +
  101 + "edge" ...
  102 + reads as either "none", "rising", "falling", or
  103 + "both". Write these strings to select the signal edge(s)
  104 + that will make poll(2) on the "value" file return.
  105 +
  106 + This file exists only if the pin can be configured as an
  107 + interrupt generating input pin.
  108 +
  109 + "active_low" ...
  110 + reads as either 0 (false) or 1 (true). Write
  111 + any nonzero value to invert the value attribute both
  112 + for reading and writing. Existing and subsequent
  113 + poll(2) support configuration via the edge attribute
  114 + for "rising" and "falling" edges will follow this
  115 + setting.
  116 +
  117 +GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
  118 +controller implementing GPIOs starting at #42) and have the following
  119 +read-only attributes:
  120 +
  121 + /sys/class/gpio/gpiochipN/
  122 +
  123 + "base" ...
  124 + same as N, the first GPIO managed by this chip
  125 +
  126 + "label" ...
  127 + provided for diagnostics (not always unique)
  128 +
  129 + "ngpio" ...
  130 + how many GPIOs this manages (N to N + ngpio - 1)
  131 +
  132 +Board documentation should in most cases cover what GPIOs are used for
  133 +what purposes. However, those numbers are not always stable; GPIOs on
  134 +a daughtercard might be different depending on the base board being used,
  135 +or other cards in the stack. In such cases, you may need to use the
  136 +gpiochip nodes (possibly in conjunction with schematics) to determine
  137 +the correct GPIO number to use for a given signal.
  138 +
  139 +
  140 +Exporting from Kernel code
  141 +--------------------------
  142 +Kernel code can explicitly manage exports of GPIOs which have already been
  143 +requested using gpio_request()::
  144 +
  145 + /* export the GPIO to userspace */
  146 + int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
  147 +
  148 + /* reverse gpio_export() */
  149 + void gpiod_unexport(struct gpio_desc *desc);
  150 +
  151 + /* create a sysfs link to an exported GPIO node */
  152 + int gpiod_export_link(struct device *dev, const char *name,
  153 + struct gpio_desc *desc);
  154 +
  155 +After a kernel driver requests a GPIO, it may only be made available in
  156 +the sysfs interface by gpiod_export(). The driver can control whether the
  157 +signal direction may change. This helps drivers prevent userspace code
  158 +from accidentally clobbering important system state.
  159 +
  160 +This explicit exporting can help with debugging (by making some kinds
  161 +of experiments easier), or can provide an always-there interface that's
  162 +suitable for documenting as part of a board support package.
  163 +
  164 +After the GPIO has been exported, gpiod_export_link() allows creating
  165 +symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
  166 +use this to provide the interface under their own device in sysfs with
  167 +a descriptive name.
Documentation/admin-guide/index.rst
Diff comments   View file @ c2746a1
... ... @@ -91,6 +91,7 @@
91 91 cputopology
92 92 device-mapper/index
93 93 efi-stub
  94 + gpio/index
94 95 highuid
95 96 hw_random
96 97 iostats
Documentation/firmware-guide/acpi/enumeration.rst
Diff comments   View file @ c2746a1
... ... @@ -316,7 +316,7 @@
316 316 we need to translate them to the corresponding Linux GPIO descriptors.
317 317  
318 318 There is a standard GPIO API for that and is documented in
319   -Documentation/gpio/.
  319 +Documentation/admin-guide/gpio/.
320 320  
321 321 In the above example we can get the corresponding two GPIO descriptors with
322 322 a code like this::
Documentation/gpio/index.rst
View file @ c2746a1
1   -:orphan:
2   -
3   -====
4   -gpio
5   -====
6   -
7   -.. toctree::
8   - :maxdepth: 1
9   -
10   - sysfs
11   -
12   -.. only:: subproject and html
13   -
14   - Indices
15   - =======
16   -
17   - * :ref:`genindex`
Documentation/gpio/sysfs.rst
View file @ c2746a1
1   -GPIO Sysfs Interface for Userspace
2   -==================================
3   -
4   -.. warning::
5   -
6   - THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
7   - Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
8   - ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
9   - NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
10   -
11   -Refer to the examples in tools/gpio/* for an introduction to the new
12   -character device ABI. Also see the userspace header in
13   -include/uapi/linux/gpio.h
14   -
15   -The deprecated sysfs ABI
16   -------------------------
17   -Platforms which use the "gpiolib" implementors framework may choose to
18   -configure a sysfs user interface to GPIOs. This is different from the
19   -debugfs interface, since it provides control over GPIO direction and
20   -value instead of just showing a gpio state summary. Plus, it could be
21   -present on production systems without debugging support.
22   -
23   -Given appropriate hardware documentation for the system, userspace could
24   -know for example that GPIO #23 controls the write protect line used to
25   -protect boot loader segments in flash memory. System upgrade procedures
26   -may need to temporarily remove that protection, first importing a GPIO,
27   -then changing its output state, then updating the code before re-enabling
28   -the write protection. In normal use, GPIO #23 would never be touched,
29   -and the kernel would have no need to know about it.
30   -
31   -Again depending on appropriate hardware documentation, on some systems
32   -userspace GPIO can be used to determine system configuration data that
33   -standard kernels won't know about. And for some tasks, simple userspace
34   -GPIO drivers could be all that the system really needs.
35   -
36   -DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS.
37   -PLEASE READ THE DOCUMENT AT Documentation/driver-api/gpio/drivers-on-gpio.rst
38   -TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY.
39   -
40   -Paths in Sysfs
41   ---------------
42   -There are three kinds of entries in /sys/class/gpio:
43   -
44   - - Control interfaces used to get userspace control over GPIOs;
45   -
46   - - GPIOs themselves; and
47   -
48   - - GPIO controllers ("gpio_chip" instances).
49   -
50   -That's in addition to standard files including the "device" symlink.
51   -
52   -The control interfaces are write-only:
53   -
54   - /sys/class/gpio/
55   -
56   - "export" ...
57   - Userspace may ask the kernel to export control of
58   - a GPIO to userspace by writing its number to this file.
59   -
60   - Example: "echo 19 > export" will create a "gpio19" node
61   - for GPIO #19, if that's not requested by kernel code.
62   -
63   - "unexport" ...
64   - Reverses the effect of exporting to userspace.
65   -
66   - Example: "echo 19 > unexport" will remove a "gpio19"
67   - node exported using the "export" file.
68   -
69   -GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
70   -and have the following read/write attributes:
71   -
72   - /sys/class/gpio/gpioN/
73   -
74   - "direction" ...
75   - reads as either "in" or "out". This value may
76   - normally be written. Writing as "out" defaults to
77   - initializing the value as low. To ensure glitch free
78   - operation, values "low" and "high" may be written to
79   - configure the GPIO as an output with that initial value.
80   -
81   - Note that this attribute *will not exist* if the kernel
82   - doesn't support changing the direction of a GPIO, or
83   - it was exported by kernel code that didn't explicitly
84   - allow userspace to reconfigure this GPIO's direction.
85   -
86   - "value" ...
87   - reads as either 0 (low) or 1 (high). If the GPIO
88   - is configured as an output, this value may be written;
89   - any nonzero value is treated as high.
90   -
91   - If the pin can be configured as interrupt-generating interrupt
92   - and if it has been configured to generate interrupts (see the
93   - description of "edge"), you can poll(2) on that file and
94   - poll(2) will return whenever the interrupt was triggered. If
95   - you use poll(2), set the events POLLPRI and POLLERR. If you
96   - use select(2), set the file descriptor in exceptfds. After
97   - poll(2) returns, either lseek(2) to the beginning of the sysfs
98   - file and read the new value or close the file and re-open it
99   - to read the value.
100   -
101   - "edge" ...
102   - reads as either "none", "rising", "falling", or
103   - "both". Write these strings to select the signal edge(s)
104   - that will make poll(2) on the "value" file return.
105   -
106   - This file exists only if the pin can be configured as an
107   - interrupt generating input pin.
108   -
109   - "active_low" ...
110   - reads as either 0 (false) or 1 (true). Write
111   - any nonzero value to invert the value attribute both
112   - for reading and writing. Existing and subsequent
113   - poll(2) support configuration via the edge attribute
114   - for "rising" and "falling" edges will follow this
115   - setting.
116   -
117   -GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
118   -controller implementing GPIOs starting at #42) and have the following
119   -read-only attributes:
120   -
121   - /sys/class/gpio/gpiochipN/
122   -
123   - "base" ...
124   - same as N, the first GPIO managed by this chip
125   -
126   - "label" ...
127   - provided for diagnostics (not always unique)
128   -
129   - "ngpio" ...
130   - how many GPIOs this manages (N to N + ngpio - 1)
131   -
132   -Board documentation should in most cases cover what GPIOs are used for
133   -what purposes. However, those numbers are not always stable; GPIOs on
134   -a daughtercard might be different depending on the base board being used,
135   -or other cards in the stack. In such cases, you may need to use the
136   -gpiochip nodes (possibly in conjunction with schematics) to determine
137   -the correct GPIO number to use for a given signal.
138   -
139   -
140   -Exporting from Kernel code
141   ---------------------------
142   -Kernel code can explicitly manage exports of GPIOs which have already been
143   -requested using gpio_request()::
144   -
145   - /* export the GPIO to userspace */
146   - int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
147   -
148   - /* reverse gpio_export() */
149   - void gpiod_unexport(struct gpio_desc *desc);
150   -
151   - /* create a sysfs link to an exported GPIO node */
152   - int gpiod_export_link(struct device *dev, const char *name,
153   - struct gpio_desc *desc);
154   -
155   -After a kernel driver requests a GPIO, it may only be made available in
156   -the sysfs interface by gpiod_export(). The driver can control whether the
157   -signal direction may change. This helps drivers prevent userspace code
158   -from accidentally clobbering important system state.
159   -
160   -This explicit exporting can help with debugging (by making some kinds
161   -of experiments easier), or can provide an always-there interface that's
162   -suitable for documenting as part of a board support package.
163   -
164   -After the GPIO has been exported, gpiod_export_link() allows creating
165   -symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
166   -use this to provide the interface under their own device in sysfs with
167   -a descriptive name.
Documentation/translations/zh_CN/gpio.txt
Diff comments   View file @ c2746a1
1   -Chinese translated version of Documentation/gpio
  1 +Chinese translated version of Documentation/admin-guide/gpio
2 2  
3 3 If you have any comment or update to the content, please contact the
4 4 original document maintainer directly. However, if you have a problem
... ... @@ -10,7 +10,7 @@
10 10 Linus Walleij <linus.walleij@linaro.org>
11 11 Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
12 12 ---------------------------------------------------------------------
13   -Documentation/gpio 的中文翻译
  13 +Documentation/admin-guide/gpio 的中文翻译
14 14  
15 15 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
16 16 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
... ... @@ -6867,7 +6867,7 @@
6867 6867 S: Maintained
6868 6868 F: Documentation/devicetree/bindings/gpio/
6869 6869 F: Documentation/driver-api/gpio/
6870   -F: Documentation/gpio/
  6870 +F: Documentation/admin-guide/gpio/
6871 6871 F: Documentation/ABI/testing/gpio-cdev
6872 6872 F: Documentation/ABI/obsolete/sysfs-gpio
6873 6873 F: drivers/gpio/