0001 =========================
0002 Using GPIO Lines in Linux
0003 =========================
0004
0005 The Linux kernel exists to abstract and present hardware to users. GPIO lines
0006 as such are normally not user facing abstractions. The most obvious, natural
0007 and preferred way to use GPIO lines is to let kernel hardware drivers deal
0008 with them.
0009
0010 For examples of already existing generic drivers that will also be good
0011 examples for any other kernel drivers you want to author, refer to
0012 Documentation/driver-api/gpio/drivers-on-gpio.rst
0013
0014 For any kind of mass produced system you want to support, such as servers,
0015 laptops, phones, tablets, routers, and any consumer or office or business goods
0016 using appropriate kernel drivers is paramount. Submit your code for inclusion
0017 in the upstream Linux kernel when you feel it is mature enough and you will get
0018 help to refine it, see Documentation/process/submitting-patches.rst.
0019
0020 In Linux GPIO lines also have a userspace ABI.
0021
0022 The userspace ABI is intended for one-off deployments. Examples are prototypes,
0023 factory lines, maker community projects, workshop specimen, production tools,
0024 industrial automation, PLC-type use cases, door controllers, in short a piece
0025 of specialized equipment that is not produced by the numbers, requiring
0026 operators to have a deep knowledge of the equipment and knows about the
0027 software-hardware interface to be set up. They should not have a natural fit
0028 to any existing kernel subsystem and not be a good fit for an operating system,
0029 because of not being reusable or abstract enough, or involving a lot of non
0030 computer hardware related policy.
0031
0032 Applications that have a good reason to use the industrial I/O (IIO) subsystem
0033 from userspace will likely be a good fit for using GPIO lines from userspace as
0034 well.
0035
0036 Do not under any circumstances abuse the GPIO userspace ABI to cut corners in
0037 any product development projects. If you use it for prototyping, then do not
0038 productify the prototype: rewrite it using proper kernel drivers. Do not under
0039 any circumstances deploy any uniform products using GPIO from userspace.
0040
0041 The userspace ABI is a character device for each GPIO hardware unit (GPIO chip).
0042 These devices will appear on the system as ``/dev/gpiochip0`` thru
0043 ``/dev/gpiochipN``. Examples of how to directly use the userspace ABI can be
0044 found in the kernel tree ``tools/gpio`` subdirectory.
0045
0046 For structured and managed applications, we recommend that you make use of the
0047 libgpiod_ library. This provides helper abstractions, command line utilities
0048 and arbitration for multiple simultaneous consumers on the same GPIO chip.
0049
0050 .. _libgpiod: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/
