Merge tag 'gpio-updates-for-v5.17' of git://git.kernel.org/pub/scm/linux/kernel/git/brgl/linux

.. SPDX-License-Identifier: GPL-2.0-or-later

Configfs GPIO Simulator

=======================

The configfs GPIO Simulator (gpio-sim) provides a way to create simulated GPIO

chips for testing purposes. The lines exposed by these chips can be accessed

using the standard GPIO character device interface as well as manipulated

using sysfs attributes.

Creating simulated chips

------------------------

The gpio-sim module registers a configfs subsystem called ``'gpio-sim'``. For

details of the configfs filesystem, please refer to the configfs documentation.

The user can create a hierarchy of configfs groups and items as well as modify

values of exposed attributes. Once the chip is instantiated, this hierarchy

will be translated to appropriate device properties. The general structure is:

**Group:** ``/config/gpio-sim``

This is the top directory of the gpio-sim configfs tree.

**Group:** ``/config/gpio-sim/gpio-device``

**Attribute:** ``/config/gpio-sim/gpio-device/dev_name``

**Attribute:** ``/config/gpio-sim/gpio-device/live``

This is a directory representing a GPIO platform device. The ``'dev_name'``

attribute is read-only and allows the user-space to read the platform device

name (e.g. ``'gpio-sim.0'``). The ``'live'`` attribute allows to trigger the

actual creation of the device once it's fully configured. The accepted values

are: ``'1'`` to enable the simulated device and ``'0'`` to disable and tear

it down.

**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX``

**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/chip_name``

**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/num_lines``

This group represents a bank of GPIOs under the top platform device. The

``'chip_name'`` attribute is read-only and allows the user-space to read the

device name of the bank device. The ``'num_lines'`` attribute allows to specify

the number of lines exposed by this bank.

**Group:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY``

**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/name``

This group represents a single line at the offset Y. The 'name' attribute

allows to set the line name as represented by the 'gpio-line-names' property.

**Item:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog``

**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/name``

**Attribute:** ``/config/gpio-sim/gpio-device/gpio-bankX/lineY/hog/direction``

This item makes the gpio-sim module hog the associated line. The ``'name'``

attribute specifies the in-kernel consumer name to use. The ``'direction'``

attribute specifies the hog direction and must be one of: ``'input'``,

``'output-high'`` and ``'output-low'``.

Inside each bank directory, there's a set of attributes that can be used to

configure the new chip. Additionally the user can ``mkdir()`` subdirectories

inside the chip's directory that allow to pass additional configuration for

specific lines. The name of those subdirectories must take the form of:

``'line<offset>'`` (e.g. ``'line0'``, ``'line20'``, etc.) as the name will be

used by the module to assign the config to the specific line at given offset.

Once the confiuration is complete, the ``'live'`` attribute must be set to 1 in

order to instantiate the chip. It can be set back to 0 to destroy the simulated

chip. The module will synchronously wait for the new simulated device to be

successfully probed and if this doesn't happen, writing to ``'live'`` will

result in an error.

Simulated GPIO chips can also be defined in device-tree. The compatible string

must be: ``"gpio-simulator"``. Supported properties are:

  ``"gpio-sim,label"`` - chip label

Other standard GPIO properties (like ``"gpio-line-names"``, ``"ngpios"`` or

``"gpio-hog"``) are also supported. Please refer to the GPIO documentation for

details.

An example device-tree code defining a GPIO simulator:

.. code-block :: none

    gpio-sim {

        compatible = "gpio-simulator";

        bank0 {

            gpio-controller;

            #gpio-cells = <2>;

            ngpios = <16>;

            gpio-sim,label = "dt-bank0";

            gpio-line-names = "", "sim-foo", "", "sim-bar";

        };

        bank1 {

            gpio-controller;

            #gpio-cells = <2>;

            ngpios = <8>;

            gpio-sim,label = "dt-bank1";

            line3 {

                gpio-hog;

                gpios = <3 0>;

                output-high;

                line-name = "sim-hog-from-dt";

            };

        };

    };

Manipulating simulated lines

----------------------------

Each simulated GPIO chip creates a separate sysfs group under its device

directory for each exposed line

(e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group

is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each

group there are two attibutes:

    ``pull`` - allows to read and set the current simulated pull setting for

               every line, when writing the value must be one of: ``'pull-up'``,

               ``'pull-down'``

    ``value`` - allows to read the current value of the line which may be

                different from the pull if the line is being driven from

                user-space

Samsung Exynos4 GPIO Controller

Required properties:

- compatible: Compatible property value should be "samsung,exynos4-gpio>".

- reg: Physical base address of the controller and length of memory mapped

  region.

- #gpio-cells: Should be 4. The syntax of the gpio specifier used by client nodes

  should be the following with values derived from the SoC user manual.

     <[phandle of the gpio controller node]

      [pin number within the gpio controller]

      [mux function]

      [flags and pull up/down]

      [drive strength]>

  Values for gpio specifier:

  - Pin number: is a value between 0 to 7.

  - Flags and Pull Up/Down: 0 - Pull Up/Down Disabled.

                            1 - Pull Down Enabled.

                            3 - Pull Up Enabled.

          Bit 16 (0x00010000) - Input is active low.

  - Drive Strength: 0 - 1x,

                    1 - 3x,

                    2 - 2x,

                    3 - 4x

- gpio-controller: Specifies that the node is a gpio controller.

- #address-cells: should be 1.

- #size-cells: should be 1.

Example:

	gpa0: gpio-controller@11400000 {

		#address-cells = <1>;

		#size-cells = <1>;

		compatible = "samsung,exynos4-gpio";

		reg = <0x11400000 0x20>;

		#gpio-cells = <4>;

		gpio-controller;

	};

      - items:

          - const: fsl,imx7ulp-gpio

          - const: fsl,vf610-gpio

      - items:

          - const: fsl,imx8ulp-gpio

          - const: fsl,imx7ulp-gpio

  reg:

    description: The first reg tuple represents the PORT module, the second tuple

    pattern: "^gpio@[0-9a-f]+$"

  compatible:

    const: mstar,msc313-gpio

    enum:

      - mstar,msc313-gpio

      - sstar,ssd20xd-gpio

  reg:

    maxItems: 1

NVIDIA Tegra186 GPIO controllers

Tegra186 contains two GPIO controllers; a main controller and an "AON"

controller. This binding document applies to both controllers. The register

layouts for the controllers share many similarities, but also some significant

differences. Hence, this document describes closely related but different

bindings and compatible values.

The Tegra186 GPIO controller allows software to set the IO direction of, and

read/write the value of, numerous GPIO signals. Routing of GPIO signals to

package balls is under the control of a separate pin controller HW block. Two

major sets of registers exist:

a) Security registers, which allow configuration of allowed access to the GPIO

register set. These registers exist in a single contiguous block of physical

address space. The size of this block, and the security features available,

varies between the different GPIO controllers.

Access to this set of registers is not necessary in all circumstances. Code

that wishes to configure access to the GPIO registers needs access to these

registers to do so. Code which simply wishes to read or write GPIO data does not

need access to these registers.

b) GPIO registers, which allow manipulation of the GPIO signals. In some GPIO

controllers, these registers are exposed via multiple "physical aliases" in

address space, each of which access the same underlying state. See the hardware

documentation for rationale. Any particular GPIO client is expected to access

just one of these physical aliases.

Tegra HW documentation describes a unified naming convention for all GPIOs

implemented by the SoC. Each GPIO is assigned to a port, and a port may control

a number of GPIOs. Thus, each GPIO is named according to an alphabetical port

name and an integer GPIO name within the port. For example, GPIO_PA0, GPIO_PN6,

or GPIO_PCC3.

The number of ports implemented by each GPIO controller varies. The number of

implemented GPIOs within each port varies. GPIO registers within a controller

are grouped and laid out according to the port they affect.

The mapping from port name to the GPIO controller that implements that port, and

the mapping from port name to register offset within a controller, are both

extremely non-linear. The header file <dt-bindings/gpio/tegra186-gpio.h>

describes the port-level mapping. In that file, the naming convention for ports

matches the HW documentation. The values chosen for the names are alphabetically

sorted within a particular controller. Drivers need to map between the DT GPIO

IDs and HW register offsets using a lookup table.

Each GPIO controller can generate a number of interrupt signals. Each signal

represents the aggregate status for all GPIOs within a set of ports. Thus, the

number of interrupt signals generated by a controller varies as a rough function

of the number of ports it implements. Note that the HW documentation refers to

both the overall controller HW module and the sets-of-ports as "controllers".

Each GPIO controller in fact generates multiple interrupts signals for each set

of ports. Each GPIO may be configured to feed into a specific one of the

interrupt signals generated by a set-of-ports. The intent is for each generated

signal to be routed to a different CPU, thus allowing different CPUs to each

handle subsets of the interrupts within a port. The status of each of these

per-port-set signals is reported via a separate register. Thus, a driver needs

to know which status register to observe. This binding currently defines no

configuration mechanism for this. By default, drivers should use register

GPIO_${port}_INTERRUPT_STATUS_G1_0. Future revisions to the binding could

define a property to configure this.

Required properties:

- compatible

    Array of strings.

    One of:

    - "nvidia,tegra186-gpio".

    - "nvidia,tegra186-gpio-aon".

    - "nvidia,tegra194-gpio".

    - "nvidia,tegra194-gpio-aon".

- reg-names

    Array of strings.

    Contains a list of names for the register spaces described by the reg

    property. May contain the following entries, in any order:

    - "gpio": Mandatory. GPIO control registers. This may cover either:

        a) The single physical alias that this OS should use.

        b) All physical aliases that exist in the controller. This is

           appropriate when the OS is responsible for managing assignment of

           the physical aliases.

    - "security": Optional. Security configuration registers.

    Users of this binding MUST look up entries in the reg property by name,

    using this reg-names property to do so.

- reg

    Array of (physical base address, length) tuples.

    Must contain one entry per entry in the reg-names property, in a matching

    order.

- interrupts

    Array of interrupt specifiers.

    The interrupt outputs from the HW block, one per set of ports, in the

    order the HW manual describes them. The number of entries required varies

    depending on compatible value:

    - "nvidia,tegra186-gpio": 6 entries.

    - "nvidia,tegra186-gpio-aon": 1 entry.

    - "nvidia,tegra194-gpio": 6 entries.

    - "nvidia,tegra194-gpio-aon": 1 entry.

- gpio-controller

    Boolean.

    Marks the device node as a GPIO controller/provider.

- #gpio-cells

    Single-cell integer.

    Must be <2>.

    Indicates how many cells are used in a consumer's GPIO specifier.

    In the specifier:

    - The first cell is the pin number.

        See <dt-bindings/gpio/tegra186-gpio.h>.

    - The second cell contains flags:

        - Bit 0 specifies polarity

            - 0: Active-high (normal).

            - 1: Active-low (inverted).

- interrupt-controller

    Boolean.

    Marks the device node as an interrupt controller/provider.

- #interrupt-cells

    Single-cell integer.

    Must be <2>.

    Indicates how many cells are used in a consumer's interrupt specifier.

    In the specifier:

    - The first cell is the GPIO number.

        See <dt-bindings/gpio/tegra186-gpio.h>.

    - The second cell is contains flags:

        - Bits [3:0] indicate trigger type and level:

            - 1: Low-to-high edge triggered.

            - 2: High-to-low edge triggered.

            - 4: Active high level-sensitive.

            - 8: Active low level-sensitive.

            Valid combinations are 1, 2, 3, 4, 8.

Example:

#include <dt-bindings/interrupt-controller/irq.h>

gpio@2200000 {

	compatible = "nvidia,tegra186-gpio";

	reg-names = "security", "gpio";

	reg =

		<0x0 0x2200000 0x0 0x10000>,

		<0x0 0x2210000 0x0 0x10000>;

	interrupts =

		<0 47 IRQ_TYPE_LEVEL_HIGH>,

		<0 50 IRQ_TYPE_LEVEL_HIGH>,

		<0 53 IRQ_TYPE_LEVEL_HIGH>,

		<0 56 IRQ_TYPE_LEVEL_HIGH>,

		<0 59 IRQ_TYPE_LEVEL_HIGH>,

		<0 180 IRQ_TYPE_LEVEL_HIGH>;

	gpio-controller;

	#gpio-cells = <2>;

	interrupt-controller;

	#interrupt-cells = <2>;

};

gpio@c2f0000 {

	compatible = "nvidia,tegra186-gpio-aon";

	reg-names = "security", "gpio";

	reg =

		<0x0 0xc2f0000 0x0 0x1000>,

		<0x0 0xc2f1000 0x0 0x1000>;

	interrupts =

		<0 60 IRQ_TYPE_LEVEL_HIGH>;

	gpio-controller;

	#gpio-cells = <2>;

	interrupt-controller;

	#interrupt-cells = <2>;

};