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