summaryrefslogtreecommitdiffstats
path: root/Documentation/driver-api
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2020-01-29 09:43:39 -0800
committerLinus Torvalds <torvalds@linux-foundation.org>2020-01-29 09:43:39 -0800
commitfa889d85551e0bd962fdefe1cc113f9ba1d04a36 (patch)
tree4f74147dc17e9fa39d06053a949c5491ccf2bace /Documentation/driver-api
parentb3a6082223369203d7e7db7e81253ac761377644 (diff)
parent0282c72d30d32913d641dc81f3f38607ace98802 (diff)
downloadlinux-fa889d85551e0bd962fdefe1cc113f9ba1d04a36.tar.gz
linux-fa889d85551e0bd962fdefe1cc113f9ba1d04a36.tar.bz2
linux-fa889d85551e0bd962fdefe1cc113f9ba1d04a36.zip
Merge tag 'gpio-v5.6-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio
Pull GPIO updates from Linus Walleij: "This is the bulk of GPIO changes for the v5.6 kernel cycle. This is a pretty calm cycle so far, nothing special going on really. Some more changes will come in from the irqchip and pin control trees. I also deleted an orphan include file for FMC that was dangling since subsystem was removed. Core changes: - Document the usecases for the kernelspace vs userspace handling of GPIOs. - Handle MSI (message signalled interrupts) properly in the core hierarchical irqdomain code. - Fix a rare race condition while initializing the descriptor array. New drivers: - Xylon LogiCVC GPIO driver. - WDC934x GPIO controller driver. Driver improvements: - Implemented suspend/resume in the Tegra driver. - MPC8xx edge detection fixup. - Properly convert ThunderX to use hierarchical irqdomain with GPIOLIB_IRQCHIP on top of the revert of the previous buggy switchover. This time it works (hopefully). Misc: - Drop a FMC remnant file <linux/ipmi-fru.h> - A slew of fixes" * tag 'gpio-v5.6-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: (48 commits) MAINTAINERS: Replace Tien Hock Loh as Altera PIO maintainer gpiolib: hold gpio devices lock until ->descs array is initialised gpio: aspeed-sgpio: fixed typos gpio: mvebu: clear irq in edge cause register before unmask edge irq gpiolib: Lower verbosity when allocating hierarchy irq gpiolib: Remove duplicated function gpio_do_set_config() gpio: Fix the no return statement warning gpio: wcd934x: Add support to wcd934x gpio controller gpiolib: remove set but not used variable 'config' gpio: vx855: fixed a typo gpio: mockup: sort headers alphabetically gpio: mockup: update the license tag gpio: Remove the unused flags gpiolib: Set lockdep class for hierarchical irq domains gpio: thunderx: Switch to GPIOLIB_IRQCHIP gpiolib: Add the support for the msi parent domain gpiolib: Add support for the irqdomain which doesn't use irq_fwspec as arg gpio: Add use guidance documentation dt-bindings: gpio: wcd934x: Add bindings for gpio gpio: altera: change to platform_get_irq_optional to avoid false-positive error ...
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r--Documentation/driver-api/driver-model/devres.rst2
-rw-r--r--Documentation/driver-api/gpio/drivers-on-gpio.rst8
-rw-r--r--Documentation/driver-api/gpio/index.rst1
-rw-r--r--Documentation/driver-api/gpio/using-gpio.rst50
4 files changed, 57 insertions, 4 deletions
diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst
index 20e07e40be02..46c13780994c 100644
--- a/Documentation/driver-api/driver-model/devres.rst
+++ b/Documentation/driver-api/driver-model/devres.rst
@@ -267,6 +267,8 @@ DRM
GPIO
devm_gpiod_get()
+ devm_gpiod_get_array()
+ devm_gpiod_get_array_optional()
devm_gpiod_get_index()
devm_gpiod_get_index_optional()
devm_gpiod_get_optional()
diff --git a/Documentation/driver-api/gpio/drivers-on-gpio.rst b/Documentation/driver-api/gpio/drivers-on-gpio.rst
index f3a189320e11..820b403d50f6 100644
--- a/Documentation/driver-api/gpio/drivers-on-gpio.rst
+++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst
@@ -95,7 +95,7 @@ to emulate MCTRL (modem control) signals CTS/RTS by using two GPIO lines. The
MTD NOR flash has add-ons for extra GPIO lines too, though the address bus is
usually connected directly to the flash.
-Use those instead of talking directly to the GPIOs using sysfs; they integrate
-with kernel frameworks better than your userspace code could. Needless to say,
-just using the appropriate kernel drivers will simplify and speed up your
-embedded hacking in particular by providing ready-made components.
+Use those instead of talking directly to the GPIOs from userspace; they
+integrate with kernel frameworks better than your userspace code could.
+Needless to say, just using the appropriate kernel drivers will simplify and
+speed up your embedded hacking in particular by providing ready-made components.
diff --git a/Documentation/driver-api/gpio/index.rst b/Documentation/driver-api/gpio/index.rst
index 5b61032aa4ea..1d48fe248f05 100644
--- a/Documentation/driver-api/gpio/index.rst
+++ b/Documentation/driver-api/gpio/index.rst
@@ -8,6 +8,7 @@ Contents:
:maxdepth: 2
intro
+ using-gpio
driver
consumer
board
diff --git a/Documentation/driver-api/gpio/using-gpio.rst b/Documentation/driver-api/gpio/using-gpio.rst
new file mode 100644
index 000000000000..dda069444032
--- /dev/null
+++ b/Documentation/driver-api/gpio/using-gpio.rst
@@ -0,0 +1,50 @@
+=========================
+Using GPIO Lines in Linux
+=========================
+
+The Linux kernel exists to abstract and present hardware to users. GPIO lines
+as such are normally not user facing abstractions. The most obvious, natural
+and preferred way to use GPIO lines is to let kernel hardware drivers deal
+with them.
+
+For examples of already existing generic drivers that will also be good
+examples for any other kernel drivers you want to author, refer to
+:doc:`drivers-on-gpio`
+
+For any kind of mass produced system you want to support, such as servers,
+laptops, phones, tablets, routers, and any consumer or office or business goods
+using appropriate kernel drivers is paramount. Submit your code for inclusion
+in the upstream Linux kernel when you feel it is mature enough and you will get
+help to refine it, see :doc:`../../process/submitting-patches`.
+
+In Linux GPIO lines also have a userspace ABI.
+
+The userspace ABI is intended for one-off deployments. Examples are prototypes,
+factory lines, maker community projects, workshop specimen, production tools,
+industrial automation, PLC-type use cases, door controllers, in short a piece
+of specialized equipment that is not produced by the numbers, requiring
+operators to have a deep knowledge of the equipment and knows about the
+software-hardware interface to be set up. They should not have a natural fit
+to any existing kernel subsystem and not be a good fit for an operating system,
+because of not being reusable or abstract enough, or involving a lot of non
+computer hardware related policy.
+
+Applications that have a good reason to use the industrial I/O (IIO) subsystem
+from userspace will likely be a good fit for using GPIO lines from userspace as
+well.
+
+Do not under any circumstances abuse the GPIO userspace ABI to cut corners in
+any product development projects. If you use it for prototyping, then do not
+productify the prototype: rewrite it using proper kernel drivers. Do not under
+any circumstances deploy any uniform products using GPIO from userspace.
+
+The userspace ABI is a character device for each GPIO hardware unit (GPIO chip).
+These devices will appear on the system as ``/dev/gpiochip0`` thru
+``/dev/gpiochipN``. Examples of how to directly use the userspace ABI can be
+found in the kernel tree ``tools/gpio`` subdirectory.
+
+For structured and managed applications, we recommend that you make use of the
+libgpiod_ library. This provides helper abstractions, command line utlities
+and arbitration for multiple simultaneous consumers on the same GPIO chip.
+
+.. _libgpiod: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/