Commit 0dc665d4 authored by Stephen Warren's avatar Stephen Warren Committed by Grant Likely
Browse files

Documentation/gpio.txt: Explain expected pinctrl interaction 



Update gpio.txt based on recent discussions regarding interaction with the
pinctrl subsystem.

Previously, gpio_request() was described as explicitly not performing any
required mux setup operations etc.

Now, gpio_request() is explicitly as explicitly performing any required mux
setup operations where possible. In the case it isn't, platform code is
required to have set up any required muxing or other configuration prior to
gpio_request() being called, in order to maintain the same semantics.

This is achieved by gpiolib drivers calling e.g. pinctrl_request_gpio() in
their .request() operation.

Cc: Randy Dunlap <rdunlap@xenotime.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: default avatarStephen Warren <swarren@nvidia.com>
Reviewed-by: default avatarLinus Walleij <linus.walleij@linaro.org>
Signed-off-by: default avatarGrant Likely <grant.likely@secretlab.ca>
parent 46158aad

Documentation/gpio.txt

+20 −3
Original line number Diff line number Diff line
@@ -271,9 +271,26 @@ Some platforms may also use knowledge about what GPIOs are active for 
power management, such as by powering down unused chip sectors and, more

easily, gating off unused clocks.



Note that requesting a GPIO does NOT cause it to be configured in any

way; it just marks that GPIO as in use.  Separate code must handle any

pin setup (e.g. controlling which pin the GPIO uses, pullup/pulldown).

For GPIOs that use pins known to the pinctrl subsystem, that subsystem should

be informed of their use; a gpiolib driver's .request() operation may call

pinctrl_request_gpio(), and a gpiolib driver's .free() operation may call

pinctrl_free_gpio(). The pinctrl subsystem allows a pinctrl_request_gpio()

to succeed concurrently with a pin or pingroup being "owned" by a device for

pin multiplexing.



Any programming of pin multiplexing hardware that is needed to route the

GPIO signal to the appropriate pin should occur within a GPIO driver's

.direction_input() or .direction_output() operations, and occur after any

setup of an output GPIO's value. This allows a glitch-free migration from a

pin's special function to GPIO. This is sometimes required when using a GPIO

to implement a workaround on signals typically driven by a non-GPIO HW block.



Some platforms allow some or all GPIO signals to be routed to different pins.

Similarly, other aspects of the GPIO or pin may need to be configured, such as

pullup/pulldown. Platform software should arrange that any such details are

configured prior to gpio_request() being called for those GPIOs, e.g. using

the pinctrl subsystem's mapping table, so that GPIO users need not be aware

of these details.



Also note that it's your responsibility to have stopped using a GPIO

before you free it.

CRA Git | Maintained and supported by SUSTech CRA and CCSE