1 ========================= 1 =========================
2 Using GPIO Lines in Linux 2 Using GPIO Lines in Linux
3 ========================= 3 =========================
4 4
5 The Linux kernel exists to abstract and presen 5 The Linux kernel exists to abstract and present hardware to users. GPIO lines
6 as such are normally not user facing abstracti 6 as such are normally not user facing abstractions. The most obvious, natural
7 and preferred way to use GPIO lines is to let 7 and preferred way to use GPIO lines is to let kernel hardware drivers deal
8 with them. 8 with them.
9 9
10 For examples of already existing generic drive 10 For examples of already existing generic drivers that will also be good
11 examples for any other kernel drivers you want 11 examples for any other kernel drivers you want to author, refer to
12 Documentation/driver-api/gpio/drivers-on-gpio. 12 Documentation/driver-api/gpio/drivers-on-gpio.rst
13 13
14 For any kind of mass produced system you want 14 For any kind of mass produced system you want to support, such as servers,
15 laptops, phones, tablets, routers, and any con 15 laptops, phones, tablets, routers, and any consumer or office or business goods
16 using appropriate kernel drivers is paramount. 16 using appropriate kernel drivers is paramount. Submit your code for inclusion
17 in the upstream Linux kernel when you feel it 17 in the upstream Linux kernel when you feel it is mature enough and you will get
18 help to refine it, see Documentation/process/s 18 help to refine it, see Documentation/process/submitting-patches.rst.
19 19
20 In Linux GPIO lines also have a userspace ABI. 20 In Linux GPIO lines also have a userspace ABI.
21 21
22 The userspace ABI is intended for one-off depl 22 The userspace ABI is intended for one-off deployments. Examples are prototypes,
23 factory lines, maker community projects, works 23 factory lines, maker community projects, workshop specimen, production tools,
24 industrial automation, PLC-type use cases, doo 24 industrial automation, PLC-type use cases, door controllers, in short a piece
25 of specialized equipment that is not produced 25 of specialized equipment that is not produced by the numbers, requiring
26 operators to have a deep knowledge of the equi 26 operators to have a deep knowledge of the equipment and knows about the
27 software-hardware interface to be set up. They 27 software-hardware interface to be set up. They should not have a natural fit
28 to any existing kernel subsystem and not be a 28 to any existing kernel subsystem and not be a good fit for an operating system,
29 because of not being reusable or abstract enou 29 because of not being reusable or abstract enough, or involving a lot of non
30 computer hardware related policy. 30 computer hardware related policy.
31 31
32 Applications that have a good reason to use th 32 Applications that have a good reason to use the industrial I/O (IIO) subsystem
33 from userspace will likely be a good fit for u 33 from userspace will likely be a good fit for using GPIO lines from userspace as
34 well. 34 well.
35 35
36 Do not under any circumstances abuse the GPIO 36 Do not under any circumstances abuse the GPIO userspace ABI to cut corners in
37 any product development projects. If you use i 37 any product development projects. If you use it for prototyping, then do not
38 productify the prototype: rewrite it using pro 38 productify the prototype: rewrite it using proper kernel drivers. Do not under
39 any circumstances deploy any uniform products 39 any circumstances deploy any uniform products using GPIO from userspace.
40 40
41 The userspace ABI is a character device for ea 41 The userspace ABI is a character device for each GPIO hardware unit (GPIO chip).
42 These devices will appear on the system as ``/ 42 These devices will appear on the system as ``/dev/gpiochip0`` thru
43 ``/dev/gpiochipN``. Examples of how to directl 43 ``/dev/gpiochipN``. Examples of how to directly use the userspace ABI can be
44 found in the kernel tree ``tools/gpio`` subdir 44 found in the kernel tree ``tools/gpio`` subdirectory.
45 45
46 For structured and managed applications, we re 46 For structured and managed applications, we recommend that you make use of the
47 libgpiod_ library. This provides helper abstra 47 libgpiod_ library. This provides helper abstractions, command line utilities
48 and arbitration for multiple simultaneous cons 48 and arbitration for multiple simultaneous consumers on the same GPIO chip.
49 49
50 .. _libgpiod: https://git.kernel.org/pub/scm/l 50 .. _libgpiod: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.