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