gpio: Update documentation

Strictify the language a bit, move things around, make proper
headings, mention pull-up and pull-down, expand unreadable
acronyms etc.

Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

---
 Documentation/driver-api/gpio/driver.rst | 358 ++++++++++++++---------
 1 file changed, 227 insertions(+), 131 deletions(-)

-- 
2.20.1

czw., 25 kwi 2019 o 10:27 Linus Walleij <linus.walleij@linaro.org> napisał(a):
>

> Strictify the language a bit, move things around, make proper

> headings, mention pull-up and pull-down, expand unreadable

> acronyms etc.

>

> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>


Thanks for doing that! I've listed a couple nits below. Please be
aware that I'm not a native speaker of English so my remarks may be
completely rubbish. :)

> ---

>  Documentation/driver-api/gpio/driver.rst | 358 ++++++++++++++---------

>  1 file changed, 227 insertions(+), 131 deletions(-)

>

> diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst

> index 3043167fc557..229f36b3c462 100644

> --- a/Documentation/driver-api/gpio/driver.rst

> +++ b/Documentation/driver-api/gpio/driver.rst

> @@ -1,10 +1,8 @@

> -================================

> -GPIO Descriptor Driver Interface

> -================================

> +=====================

> +GPIO Driver Interface

> +=====================

>

> -This document serves as a guide for GPIO chip drivers writers. Note that it

> -describes the new descriptor-based interface. For a description of the

> -deprecated integer-based GPIO interface please refer to gpio-legacy.txt.

> +This document serves as a guide for GPIO chip drivers writers.

>


How about "for writers of GPIO chip drivers"?

>  Each GPIO controller driver needs to include the following header, which defines

>  the structures used to define a GPIO driver:

> @@ -15,32 +13,49 @@ the structures used to define a GPIO driver:

>  Internal Representation of GPIOs

>  ================================

>

> -Inside a GPIO driver, individual GPIOs are identified by their hardware number,

> -which is a unique number between 0 and n, n being the number of GPIOs managed by

> -the chip. This number is purely internal: the hardware number of a particular

> -GPIO descriptor is never made visible outside of the driver.

> -

> -On top of this internal number, each GPIO also need to have a global number in

> -the integer GPIO namespace so that it can be used with the legacy GPIO

> +A GPIO chip handles one or more GPIO lines. To be considered a GPIO chip, the

> +lines must conform to the definition: General Purpose Input/Output. If the

> +line is not general purpose, it is not GPIO and should not be handled by a

> +GPIO chip. The usecase is the indicative: there may be things inside a system


I think it should be "use case".

> +that are named GPIO but are not but rather special purpose, and there may be

> +things inside a system named e.g. LED driver line, which are used as general

> +purpose I/O and should therefore still be a gpio_chip.

> +


Maybe it'll be simpler this way: "certain lines in a system may be
called GPIO but serve a very particular purpose thus not meeting the
criteria of a general purpose I/O. On the other hand a LED driver line
may be used as a GPIO and should therefore still be handled by a
gpio_chip."

> +Inside a GPIO driver, individual GPIO lines are identified by their hardware

> +number, sometime also referred to as ``offset``, which is a unique number

> +between 0 and n-1, n being the number of GPIOs managed by the chip.

> +

> +The hardware GPIO number should be something intuitive to the hardware, for

> +example if a system uses a memory-mapped set of I/O-registers where 32 GPIO

> +lines are handled by one bit per line in a 32-bit register, it makes sense to

> +use hardware offsets 0..31 for these, corresponding to bits 0..31 in the

> +register.

> +

> +This number is purely internal: the hardware number of a particular GPIO

> +line is never made visible outside of the driver.

> +

> +On top of this internal number, each GPIO line also need to have a global


g/need/needs/

> +number in the integer GPIO namespace so that it can be used with the legacy GPIO

>  interface. Each chip must thus have a "base" number (which can be automatically

> -assigned), and for each GPIO the global number will be (base + hardware number).

> -Although the integer representation is considered deprecated, it still has many

> -users and thus needs to be maintained.

> +assigned), and for each GPIO line the global number will be (base + hardware

> +number). Although the integer representation is considered deprecated, it still

> +has many users and thus needs to be maintained.

>

> -So for example one platform could use numbers 32-159 for GPIOs, with a

> +So for example one platform could use global numbers 32-159 for GPIOs, with a

>  controller defining 128 GPIOs at a "base" of 32 ; while another platform uses

> -numbers 0..63 with one set of GPIO controllers, 64-79 with another type of GPIO

> -controller, and on one particular board 80-95 with an FPGA. The numbers need not

> -be contiguous; either of those platforms could also use numbers 2000-2063 to

> -identify GPIOs in a bank of I2C GPIO expanders.

> +global numbers 0..63 with one set of GPIO controllers, 64-79 with another type

> +of GPIO controller, and on one particular board 80-95 with an FPGA. The legacy

> +numbers need not be contiguous; either of those platforms could also use numbers

> +2000-2063 to identify GPIO lines in a bank of I2C GPIO expanders.

>

>

>  Controller Drivers: gpio_chip

>  =============================

>

>  In the gpiolib framework each GPIO controller is packaged as a "struct

> -gpio_chip" (see linux/gpio/driver.h for its complete definition) with members

> -common to each controller of that type:

> +gpio_chip" (see <linux/gpio/driver.h> for its complete definition) with members

> +common to each controller of that type, these should be assigned by the

> +driver code:

>

>   - methods to establish GPIO line direction

>   - methods used to access GPIO line values

> @@ -48,12 +63,12 @@ common to each controller of that type:

>   - method to return the IRQ number associated to a given GPIO line

>   - flag saying whether calls to its methods may sleep

>   - optional line names array to identify lines

> - - optional debugfs dump method (showing extra state like pullup config)

> + - optional debugfs dump method (showing extra state information)

>   - optional base number (will be automatically assigned if omitted)

>   - optional label for diagnostics and GPIO chip mapping using platform data

>

>  The code implementing a gpio_chip should support multiple instances of the

> -controller, possibly using the driver model. That code will configure each

> +controller, preferably using the driver model. That code will configure each

>  gpio_chip and issue ``gpiochip_add[_data]()`` or ``devm_gpiochip_add_data()``.

>  Removing a GPIO controller should be rare; use ``[devm_]gpiochip_remove()``

>  when it is unavoidable.

> @@ -62,24 +77,28 @@ Often a gpio_chip is part of an instance-specific structure with states not

>  exposed by the GPIO interfaces, such as addressing, power management, and more.

>  Chips such as audio codecs will have complex non-GPIO states.

>

> -Any debugfs dump method should normally ignore signals which haven't been

> -requested as GPIOs. They can use gpiochip_is_requested(), which returns either

> -NULL or the label associated with that GPIO when it was requested.

> +Any debugfs dump method should normally ignore lines which haven't been

> +requested. They can use gpiochip_is_requested(), which returns either

> +NULL or the label associated with that GPIO line when it was requested.

>

> -RT_FULL: the GPIO driver should not use spinlock_t or any sleepable APIs

> -(like PM runtime) in its gpio_chip implementation (.get/.set and direction

> -control callbacks) if it is expected to call GPIO APIs from atomic context

> -on -RT (inside hard IRQ handlers and similar contexts). Normally this should

> -not be required.

> +Realtime considerations: the GPIO driver should not use spinlock_t or any

> +sleepable APIs (like PM runtime) in its gpio_chip implementation (.get/.set

> +and direction control callbacks) if it is expected to call GPIO APIs from

> +atomic context on realtime kernels (inside hard IRQ handlers and similar

> +contexts). Normally this should not be required.

>

>

>  GPIO electrical configuration

>  -----------------------------

>

> -GPIOs can be configured for several electrical modes of operation by using the

> -.set_config() callback. Currently this API supports setting debouncing and

> -single-ended modes (open drain/open source). These settings are described

> -below.

> +GPIO lines can be configured for several electrical modes of operation by using

> +the .set_config() callback. Currently this API supports setting:

> +

> +- Debouncing

> +- Single-ended modes (open drain/open source)

> +- Pull up and pull down resistor enablement

> +

> +These settings are described below.

>

>  The .set_config() callback uses the same enumerators and configuration

>  semantics as the generic pin control drivers. This is not a coincidence: it is

> @@ -94,8 +113,8 @@ description needs to provide "GPIO ranges" mapping the GPIO line offsets to pin

>  numbers on the pin controller so they can properly cross-reference each other.

>

>

> -GPIOs with debounce support

> ----------------------------

> +GPIO lines with debounce support

> +--------------------------------

>

>  Debouncing is a configuration set to a pin indicating that it is connected to

>  a mechanical switch or button, or similar that may bounce. Bouncing means the

> @@ -111,8 +130,8 @@ a certain number of milliseconds for debouncing, or just "on/off" if that time

>  is not configurable.

>

>

> -GPIOs with open drain/source support

> -------------------------------------

> +GPIO lines with open drain/source support

> +-----------------------------------------

>

>  Open drain (CMOS) or open collector (TTL) means the line is not actively driven

>  high: instead you provide the drain/collector as output, so when the transistor

> @@ -132,7 +151,7 @@ This configuration is normally used as a way to achieve one of two things:

>  - Level-shifting: to reach a logical level higher than that of the silicon

>    where the output resides.

>

> -- inverse wire-OR on an I/O line, for example a GPIO line, making it possible

> +- Inverse wire-OR on an I/O line, for example a GPIO line, making it possible

>    for any driving stage on the line to drive it low even if any other output

>    to the same line is simultaneously driving it high. A special case of this

>    is driving the SCL and SDA lines of an I2C bus, which is by definition a

> @@ -208,27 +227,91 @@ For open source configuration the same principle is used, just that instead

>  of actively driving the line low, it is set to input.

>

>

> +GPIO lines with pull up/down resistor support

> +---------------------------------------------

> +

> +A GPIO line can support pull-up/down using the .set_config() callback. This

> +means that a pull up or pull-down resistor is available on the output of the

> +GPIO line, and this resistor is software controlled.

> +

> +In discrete designs, a pull-up or pull-down resistor is simply soldered on

> +the circuit board. This is not something we deal or model in software. The

> +most you will think about these lines is that they will very likely be

> +configured as open drain or open source (see the section above).

> +

> +The .set_config() callback can only turn pull up or down on and off, and will

> +no have any semantic knowledge about the resistance used. It will only say

> +switch a bit in a register enabling or disabling pull-up or pull-down.

> +

> +If the GPIO line supports shunting in different resistance values for the

> +pull-up or pull-down resistor, the GPIO chip callback .set_config() will not

> +suffice. For these complex use cases, a combined GPIO chip and pin controller

> +need to be implemented, as the pin config interface of a pin controller

> +supports more versatile control over electrical properties and can handle

> +different pull-up or pull-down resistance values.

> +

> +

>  GPIO drivers providing IRQs

> ----------------------------

> +===========================

> +

>  It is custom that GPIO drivers (GPIO chips) are also providing interrupts,

>  most often cascaded off a parent interrupt controller, and in some special

>  cases the GPIO logic is melded with a SoC's primary interrupt controller.

>

> -The IRQ portions of the GPIO block are implemented using an irqchip, using

> +The IRQ portions of the GPIO block are implemented using an irq_chip, using

>  the header <linux/irq.h>. So basically such a driver is utilizing two sub-

>  systems simultaneously: gpio and irq.

>

> -RT_FULL: a realtime compliant GPIO driver should not use spinlock_t or any

> -sleepable APIs (like PM runtime) as part of its irq_chip implementation.

> +It is legal for any IRQ consumer to request an IRQ from any irqchip no matter

> +if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and


Maybe: "It is legal for any IRQ consumer to request an IRQ from any
irqchip even if it is a combined..."

> +irq_chip are orthogonal, and offering their services independent of each

> +other.

> +

> +gpiod_to_irq() is just a convenience function to figure out the IRQ for a

> +certain GPIO line and should not be relied upon to have been called before

> +the IRQ is used.

>

> -* spinlock_t should be replaced with raw_spinlock_t [1].

> -* If sleepable APIs have to be used, these can be done from the .irq_bus_lock()

> +Always prepare the hardware and make it ready for action in respective

> +callbacks from the GPIO and irq_chip APIs. Do not rely on gpiod_to_irq() having

> +been called first.

> +

> +We can divide GPIO irqchips in two broad categories:

> +

> +- CASCADED INTERRUPT CHIPS: this means that the GPIO chip has one common

> +  interrupt output line, which is triggered by any enabled GPIO line on that

> +  chip. The interrupt output line will then be routed to an parent interrupt

> +  controller one level up, in the most simple case the systems primary

> +  interrupt controller. This is modeled by an irqchip that will inspect bits

> +  inside the GPIO controller to figure out which line fired it. The irqchip

> +  part of the driver needs to inspect registers to figure this out and it

> +  will likely also need to acknowledge that it is handling the interrupt

> +  by clearing some bit (sometime implicitly, by just reading a status

> +  register) and it will often need to set up the configuration such as

> +  edge sensitivity (rising or falling edge, or high/low level interrupt for

> +  example).

> +

> +- HIERARCHICAL INTERRUPT CHIPS: this means that each GPIO line has a dedicated

> +  irq line to a parent interrupt controller one level up. There is no need

> +  to inquire the GPIO hardware to figure out which line has figured, but it

> +  may still be necessary to acknowledge the interrupt and set up the

> +  configuration such as edge sensitivity.

> +

> +Realtime considerations: a realtime compliant GPIO driver should not use

> +spinlock_t or any sleepable APIs (like PM runtime) as part of its irqchip

> +implementation.

> +

> +- spinlock_t should be replaced with raw_spinlock_t [1].

> +- If sleepable APIs have to be used, these can be done from the .irq_bus_lock()

>    and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks

>    on an irqchip. Create the callbacks if needed [2].

>

> -GPIO irqchips usually fall in one of two categories:

>

> -* CHAINED GPIO irqchips: these are usually the type that is embedded on

> +Cascaded GPIO irqchips

> +----------------------

> +

> +Cascaded GPIO irqchips usually fall in one of three categories:

> +

> +- CHAINED CASCADED GPIO IRQCHIPS: these are usually the type that is embedded on

>    an SoC. This means that there is a fast IRQ flow handler for the GPIOs that

>    gets called in a chain from the parent IRQ handler, most typically the

>    system interrupt controller. This means that the GPIO irqchip handler will

> @@ -245,16 +328,19 @@ GPIO irqchips usually fall in one of two categories:

>    struct gpio_chip, as everything happens directly in the callbacks: no

>    slow bus traffic like I2C can be used.

>

> -  RT_FULL: Note, chained IRQ handlers will not be forced threaded on -RT.

> -  As result, spinlock_t or any sleepable APIs (like PM runtime) can't be used

> -  in chained IRQ handler.

> -  If required (and if it can't be converted to the nested threaded GPIO irqchip)

> -  a chained IRQ handler can be converted to generic irq handler and this way

> -  it will be a threaded IRQ handler on -RT and a hard IRQ handler on non-RT

> -  (for example, see [3]).

> -  Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled,

> +  Realtime considerations: Note that chained IRQ handlers will not be forced

> +  threaded on -RT. As a result, spinlock_t or any sleepable APIs (like PM

> +  runtime) can't be used in a chained IRQ handler.

> +

> +  If required (and if it can't be converted to the nested threaded GPIO irqchip,

> +  see below) a chained IRQ handler can be converted to generic irq handler and

> +  this way it will become a threaded IRQ handler on -RT and a hard IRQ handler

> +  on non-RT (for example, see [3]).

> +

> +  The generic_handle_irq() is expected to be called with IRQ disabled,

>    so the IRQ core will complain if it is called from an IRQ handler which is

> -  forced to a thread. The "fake?" raw lock can be used to W/A this problem::

> +  forced to a thread. The "fake?" raw lock can be used to work around this

> +  problem::

>

>         raw_spinlock_t wa_lock;

>         static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank)

> @@ -263,7 +349,7 @@ GPIO irqchips usually fall in one of two categories:

>                 generic_handle_irq(irq_find_mapping(bank->chip.irq.domain, bit));

>                 raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags);

>

> -* GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips",

> +- GENERIC CHAINED GPIO IRQCHIPS: these are the same as "CHAINED GPIO irqchips",

>    but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is

>    performed by generic IRQ handler which is configured using request_irq().

>    The GPIO irqchip will then end up calling something like this sequence in

> @@ -273,16 +359,19 @@ GPIO irqchips usually fall in one of two categories:

>          for each detected GPIO IRQ

>              generic_handle_irq(...);

>

> -  RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ

> -  core will complain that generic_handle_irq() is called with IRQ enabled and

> -  the same W/A as for "CHAINED GPIO irqchips" can be applied.

> +  Realtime considerations: this kind of handlers will be forced threaded on -RT,

> +  and as result the IRQ core will complain that generic_handle_irq() is called

> +  with IRQ enabled and the same work around as for "CHAINED GPIO irqchips" can

> +  be applied.

> +

> +- NESTED THREADED GPIO IRQCHIPS: these are off-chip GPIO expanders and any

> +  other GPIO irqchip residing on the other side of a sleeping bus such as I2C

> +  or SPI.

>

> -* NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any

> -  other GPIO irqchip residing on the other side of a sleeping bus. Of course

> -  such drivers that need slow bus traffic to read out IRQ status and similar,

> -  traffic which may in turn incur other IRQs to happen, cannot be handled

> -  in a quick IRQ handler with IRQs disabled. Instead they need to spawn a

> -  thread and then mask the parent IRQ line until the interrupt is handled

> +  Of course such drivers that need slow bus traffic to read out IRQ status and

> +  similar, traffic which may in turn incur other IRQs to happen, cannot be

> +  handled in a quick IRQ handler with IRQs disabled. Instead they need to spawn

> +  a thread and then mask the parent IRQ line until the interrupt is handled

>    by the driver. The hallmark of this driver is to call something like

>    this in its interrupt handler::

>

> @@ -294,36 +383,46 @@ GPIO irqchips usually fall in one of two categories:

>    flag on struct gpio_chip to true, indicating that this chip may sleep

>    when accessing the GPIOs.

>

> +  These kinds of irqchips are inherently realtime tolerant as they are

> +  already set up to handle sleeping contexts.

> +

> +

> +Infrastructure helpers for GPIO irqchips

> +----------------------------------------

> +

>  To help out in handling the set-up and management of GPIO irqchips and the

>  associated irqdomain and resource allocation callbacks, the gpiolib has

>  some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig

>  symbol:

>

> -* gpiochip_irqchip_add(): adds a chained irqchip to a gpiochip. It will pass

> -  the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks

> -  need to embed the gpio_chip in its state container and obtain a pointer

> -  to the container using container_of().

> +- gpiochip_irqchip_add(): adds a chained cascaded irqchip to a gpiochip. It

> +  will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the

> +  callbacks need to embed the gpio_chip in its state container and obtain a

> +  pointer to the container using container_of().

>    (See Documentation/driver-model/design-patterns.txt)

>

> -* gpiochip_irqchip_add_nested(): adds a nested irqchip to a gpiochip.

> +- gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip,

> +  as discussed above regarding different types of cascaded irqchips. The

> +  cascaded irq has to be handled by a threaded interrupt handler.

>    Apart from that it works exactly like the chained irqchip.

>

> -* gpiochip_set_chained_irqchip(): sets up a chained irq handler for a

> +- gpiochip_set_chained_irqchip(): sets up a chained cascaded irq handler for a

>    gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler

> -  data. (Notice handler data, since the irqchip data is likely used by the

> -  parent irqchip!).

> +  data. Notice that we pass is as the handler data, since the irqchip data is

> +  likely used by the parent irqchip.

>

> -* gpiochip_set_nested_irqchip(): sets up a nested irq handler for a

> +- gpiochip_set_nested_irqchip(): sets up a nested cascaded irq handler for a

>    gpio_chip from a parent IRQ. As the parent IRQ has usually been

>    explicitly requested by the driver, this does very little more than

>    mark all the child IRQs as having the other IRQ as parent.

>

> -If there is a need to exclude certain GPIOs from the IRQ domain, you can

> -set .irq.need_valid_mask of the gpiochip before gpiochip_add_data() is

> -called. This allocates an .irq.valid_mask with as many bits set as there

> -are GPIOs in the chip. Drivers can exclude GPIOs by clearing bits from this

> -mask. The mask must be filled in before gpiochip_irqchip_add() or

> -gpiochip_irqchip_add_nested() is called.

> +If there is a need to exclude certain GPIO lines from the IRQ domain handled by

> +these helpers, we can set .irq.need_valid_mask of the gpiochip before

> +[devm_]gpiochip_add_data() is called. This allocates an .irq.valid_mask with as

> +many bits set as there are GPIO lines in the chip, each bit representing line

> +0..n-1. Drivers can exclude GPIO lines by clearing bits from this mask. The mask

> +must be filled in before gpiochip_irqchip_add() or gpiochip_irqchip_add_nested()

> +is called.

>

>  To use the helpers please keep the following in mind:

>

> @@ -333,33 +432,24 @@ To use the helpers please keep the following in mind:

>

>  - Nominally set all handlers to handle_bad_irq() in the setup call and pass

>    handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is

> -  expected for GPIO driver that irqchip .set_type() callback have to be called

> -  before using/enabling GPIO IRQ. Then set the handler to handle_level_irq()

> -  and/or handle_edge_irq() in the irqchip .set_type() callback depending on

> -  what your controller supports.

> +  expected for GPIO driver that irqchip .set_type() callback will be called

> +  before using/enabling each GPIO IRQ. Then set the handler to

> +  handle_level_irq() and/or handle_edge_irq() in the irqchip .set_type()

> +  callback depending on what your controller supports and what is requested

> +  by the consumer.

>

> -It is legal for any IRQ consumer to request an IRQ from any irqchip no matter

> -if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and

> -irq_chip are orthogonal, and offering their services independent of each

> -other.

>

> -gpiod_to_irq() is just a convenience function to figure out the IRQ for a

> -certain GPIO line and should not be relied upon to have been called before

> -the IRQ is used.

> -

> -So always prepare the hardware and make it ready for action in respective

> -callbacks from the GPIO and irqchip APIs. Do not rely on gpiod_to_irq() having

> -been called first.

> +Locking IRQ usage

> +-----------------

>

> -This orthogonality leads to ambiguities that we need to solve: if there is

> -competition inside the subsystem which side is using the resource (a certain

> -GPIO line and register for example) it needs to deny certain operations and

> -keep track of usage inside of the gpiolib subsystem. This is why the API

> -below exists.

> +Since GPIO and irq_chip are orthogonal, we can get conflicts between different

> +use cases. For example a GPIO line used for IRQs should be an input line,

> +it does not make sense to fire interrupts on an output GPIO.

>

> +If there is competition inside the subsystem which side is using the

> +resource (a certain GPIO line and register for example) it needs to deny

> +certain operations and keep track of usage inside of the gpiolib subsystem.

>

> -Locking IRQ usage

> ------------------

>  Input GPIOs can be used as IRQ signals. When this happens, a driver is requested

>  to mark the GPIO as being used as an IRQ::

>

> @@ -380,9 +470,15 @@ assigned.

>

>  Disabling and enabling IRQs

>  ---------------------------

> +

> +In some (fringe) use cases, a driver may be using a GPIO line as input for IRQs,

> +but occasionally switch that line over to drive output and then back to being

> +an input with interrupts again. This happens on things like CEC (Consumer

> +Electronics Control).

> +

>  When a GPIO is used as an IRQ signal, then gpiolib also needs to know if

>  the IRQ is enabled or disabled. In order to inform gpiolib about this,

> -a driver should call::

> +the irqchip driver should call::

>

>         void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset)

>

> @@ -398,40 +494,44 @@ irqchip.

>  When using the gpiolib irqchip helpers, these callbacks are automatically

>  assigned.

>

> +


Is this double-newline on purpose?

>  Real-Time compliance for GPIO IRQ chips

>  ---------------------------------------

>

> -Any provider of irqchips needs to be carefully tailored to support Real Time

> +Any provider of irqchips needs to be carefully tailored to support Real-Time

>  preemption. It is desirable that all irqchips in the GPIO subsystem keep this

>  in mind and do the proper testing to assure they are real time-enabled.

> -So, pay attention on above " RT_FULL:" notes, please.

> -The following is a checklist to follow when preparing a driver for real

> -time-compliance:

>

> -- ensure spinlock_t is not used as part irq_chip implementation;

> -- ensure that sleepable APIs are not used as part irq_chip implementation.

> +So, pay attention on above realtime considerations in the documentation.

> +

> +The following is a checklist to follow when preparing a driver for real-time

> +compliance:

> +

> +- ensure spinlock_t is not used as part irq_chip implementation

> +- ensure that sleepable APIs are not used as part irq_chip implementation

>    If sleepable APIs have to be used, these can be done from the .irq_bus_lock()

> -  and .irq_bus_unlock() callbacks;

> +  and .irq_bus_unlock() callbacks

>  - Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used

> -  from chained IRQ handler;

> +  from the chained IRQ handler

>  - Generic chained GPIO irqchips: take care about generic_handle_irq() calls and

> -  apply corresponding W/A;

> -- Chained GPIO irqchips: get rid of chained IRQ handler and use generic irq

> -  handler if possible :)

> -- regmap_mmio: Sry, but you are in trouble :( if MMIO regmap is used as for

> -  GPIO IRQ chip implementation;

> -- Test your driver with the appropriate in-kernel real time test cases for both

> -  level and edge IRQs.

> +  apply corresponding work-around

> +- Chained GPIO irqchips: get rid of the chained IRQ handler and use generic irq

> +  handler if possible

> +- regmap_mmio: sorry, but you are in trouble, we do not know how to solve this


Just an FYI: if your concern is the internal regmap locking - you can
disable it in regmap_config by setting disable_locking to true and
taking care of that in the GPIO driver.

> +- Test your driver with the appropriate in-kernel real-time test cases for both

> +  level and edge IRQs

> +

> +* [1] http://www.spinics.net/lists/linux-omap/msg120425.html

> +* [2] https://lkml.org/lkml/2015/9/25/494

> +* [3] https://lkml.org/lkml/2015/9/25/495

>

>

>  Requesting self-owned GPIO pins

> --------------------------------

> +===============================

>

>  Sometimes it is useful to allow a GPIO chip driver to request its own GPIO

> -descriptors through the gpiolib API. Using gpio_request() for this purpose

> -does not help since it pins the module to the kernel forever (it calls

> -try_module_get()). A GPIO driver can use the following functions instead

> -to request and free descriptors without being pinned to the kernel forever::

> +descriptors through the gpiolib API. A GPIO driver can use the following

> +functions to request and free descriptors::

>

>         struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc,

>                                                     u16 hwnum,

> @@ -446,7 +546,3 @@ gpiochip_free_own_desc().

>  These functions must be used with care since they do not affect module use

>  count. Do not use the functions to request gpio descriptors not owned by the

>  calling driver.

> -

> -* [1] http://www.spinics.net/lists/linux-omap/msg120425.html

> -* [2] https://lkml.org/lkml/2015/9/25/494

> -* [3] https://lkml.org/lkml/2015/9/25/495

> --

> 2.20.1

>


Best regards,
Bartosz Golaszewski