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