From: Geert Uytterhoeven <geert+renesas@glider.be> To: Linus Walleij <linus.walleij@linaro.org>, Bartosz Golaszewski <bgolaszewski@baylibre.com>, Jonathan Corbet <corbet@lwn.net>, Harish Jenny K N <harish_kandiga@mentor.com>, Eugeniu Rosca <erosca@de.adit-jv.com> Cc: Alexander Graf <graf@amazon.com>, Peter Maydell <peter.maydell@linaro.org>, Paolo Bonzini <pbonzini@redhat.com>, Phil Reid <preid@electromag.com.au>, Marc Zyngier <marc.zyngier@arm.com>, Christoffer Dall <christoffer.dall@arm.com>, Magnus Damm <magnus.damm@gmail.com>, Rob Herring <robh+dt@kernel.org>, Mark Rutland <mark.rutland@arm.com>, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, linux-renesas-soc@vger.kernel.org, linux-kernel@vger.kernel.org, qemu-devel@nongnu.org, Geert Uytterhoeven <geert+renesas@glider.be> Subject: [PATCH v6 7/8] docs: gpio: Add GPIO Aggregator documentation Date: Tue, 24 Mar 2020 14:56:52 +0100 Message-ID: <20200324135653.6676-7-geert+renesas@glider.be> (raw) In-Reply-To: <20200324135653.6676-1-geert+renesas@glider.be> Document the GPIO Aggregator, and the two typical use-cases. Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be> Reviewed-by: Ulrich Hecht <uli+renesas@fpond.eu> Reviewed-by: Eugeniu Rosca <erosca@de.adit-jv.com> Tested-by: Eugeniu Rosca <erosca@de.adit-jv.com> --- v6: - Fix "allows" without object: -> provides a mechanism to aggregate GPIOs, -> provides access control for a set of one or more GPIOs, -> allows the user to communicate, - Drop "gpiochipN" support, - Extend example, v5: - Add Reviewed-by, Tested-by, - Fix inconsistent indentation, v4: - Add Reviewed-by, - Drop controversial GPIO repeater, - Clarify industrial control use case, - Fix typo s/communicated/communicate/, - Replace abstract frobnicator example by concrete door example with gpio-line-names, v3: - New. --- .../admin-guide/gpio/gpio-aggregator.rst | 111 ++++++++++++++++++ Documentation/admin-guide/gpio/index.rst | 1 + 2 files changed, 112 insertions(+) create mode 100644 Documentation/admin-guide/gpio/gpio-aggregator.rst diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documentation/admin-guide/gpio/gpio-aggregator.rst new file mode 100644 index 0000000000000000..5cd1e7221756504c --- /dev/null +++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst @@ -0,0 +1,111 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +GPIO Aggregator +=============== + +The GPIO Aggregator provides a mechanism to aggregate GPIOs, and expose them as +a new gpio_chip. This supports the following use cases. + + +Aggregating GPIOs using Sysfs +----------------------------- + +GPIO controllers are exported to userspace using /dev/gpiochip* character +devices. Access control to these devices is provided by standard UNIX file +system permissions, on an all-or-nothing basis: either a GPIO controller is +accessible for a user, or it is not. + +The GPIO Aggregator provides access control for a set of one or more GPIOs, by +aggregating them into a new gpio_chip, which can be assigned to a group or user +using standard UNIX file ownership and permissions. Furthermore, this +simplifies and hardens exporting GPIOs to a virtual machine, as the VM can just +grab the full GPIO controller, and no longer needs to care about which GPIOs to +grab and which not, reducing the attack surface. + +Aggregated GPIO controllers are instantiated and destroyed by writing to +write-only attribute files in sysfs. + + /sys/bus/platform/drivers/gpio-aggregator/ + + "new_device" ... + Userspace may ask the kernel to instantiate an aggregated GPIO + controller by writing a string describing the GPIOs to + aggregate to the "new_device" file, using the format + + .. code-block:: none + + [<gpioA>] [<gpiochipB> <offsets>] ... + + Where: + + "<gpioA>" ... + is a GPIO line name, + + "<gpiochipB>" ... + is a GPIO chip label, and + + "<offsets>" ... + is a comma-separated list of GPIO offsets and/or + GPIO offset ranges denoted by dashes. + + Example: Instantiate a new GPIO aggregator by aggregating GPIO + line 19 of "e6052000.gpio" and GPIO lines 20-21 of + "e6050000.gpio" into a new gpio_chip: + + .. code-block:: sh + + $ echo 'e6052000.gpio 19 e6050000.gpio 20-21' > new_device + + "delete_device" ... + Userspace may ask the kernel to destroy an aggregated GPIO + controller after use by writing its device name to the + "delete_device" file. + + Example: Destroy the previously-created aggregated GPIO + controller, assumed to be "gpio-aggregator.0": + + .. code-block:: sh + + $ echo gpio-aggregator.0 > delete_device + + +Generic GPIO Driver +------------------- + +The GPIO Aggregator can also be used as a generic driver for a simple +GPIO-operated device described in DT, without a dedicated in-kernel driver. +This is useful in industrial control, and is not unlike e.g. spidev, which +allows the user to communicate with an SPI device from userspace. + +Binding a device to the GPIO Aggregator is performed either by modifying the +gpio-aggregator driver, or by writing to the "driver_override" file in Sysfs. + +Example: If "door" is a GPIO-operated device described in DT, using its own +compatible value:: + + door { + compatible = "myvendor,mydoor"; + + gpios = <&gpio2 19 GPIO_ACTIVE_HIGH>, + <&gpio2 20 GPIO_ACTIVE_LOW>; + gpio-line-names = "open", "lock"; + }; + +it can be bound to the GPIO Aggregator by either: + +1. Adding its compatible value to ``gpio_aggregator_dt_ids[]``, +2. Binding manually using "driver_override": + +.. code-block:: sh + + $ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override + $ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind + +After that, a new gpiochip "door" has been created: + +.. code-block:: sh + + $ gpioinfo door + gpiochip12 - 2 lines: + line 0: "open" unused input active-high + line 1: "lock" unused input active-high diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index a244ba4e87d5398a..ef2838638e967777 100644 --- a/Documentation/admin-guide/gpio/index.rst +++ b/Documentation/admin-guide/gpio/index.rst @@ -7,6 +7,7 @@ gpio .. toctree:: :maxdepth: 1 + gpio-aggregator sysfs .. only:: subproject and html -- 2.17.1
next prev parent reply index Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top 2020-03-24 13:53 [PATCH v6 0/8] gpio: Add GPIO Aggregator Geert Uytterhoeven 2020-03-24 13:56 ` [PATCH v6 1/8] ARM: integrator: impd1: Use GPIO_LOOKUP() helper macro Geert Uytterhoeven 2020-03-24 13:56 ` [PATCH v6 2/8] i2c: i801: " Geert Uytterhoeven 2020-03-25 9:14 ` Jean Delvare 2020-04-15 10:57 ` Wolfram Sang 2020-03-24 13:56 ` [PATCH v6 3/8] mfd: sm501: Use GPIO_LOOKUP_IDX() " Geert Uytterhoeven 2020-04-15 9:25 ` Lee Jones 2020-03-24 13:56 ` [PATCH v6 4/8] gpiolib: Add support for GPIO lookup by line name Geert Uytterhoeven 2020-03-26 21:18 ` Linus Walleij 2020-05-11 10:18 ` Geert Uytterhoeven 2020-03-24 13:56 ` [PATCH v6 5/8] gpiolib: Introduce gpiod_set_config() Geert Uytterhoeven 2020-03-26 21:26 ` Linus Walleij 2020-03-27 8:45 ` Geert Uytterhoeven 2020-03-27 21:33 ` Linus Walleij 2020-03-27 21:37 ` Linus Walleij 2020-03-24 13:56 ` [PATCH v6 6/8] gpio: Add GPIO Aggregator Geert Uytterhoeven 2020-03-24 13:56 ` Geert Uytterhoeven [this message] 2020-03-24 13:56 ` [PATCH v6 8/8] MAINTAINERS: Add GPIO Aggregator section Geert Uytterhoeven 2020-03-26 21:07 ` [PATCH v6 1/8] ARM: integrator: impd1: Use GPIO_LOOKUP() helper macro Linus Walleij
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20200324135653.6676-7-geert+renesas@glider.be \ --to=geert+renesas@glider.be \ --cc=bgolaszewski@baylibre.com \ --cc=christoffer.dall@arm.com \ --cc=corbet@lwn.net \ --cc=erosca@de.adit-jv.com \ --cc=graf@amazon.com \ --cc=harish_kandiga@mentor.com \ --cc=linus.walleij@linaro.org \ --cc=linux-doc@vger.kernel.org \ --cc=linux-gpio@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-renesas-soc@vger.kernel.org \ --cc=magnus.damm@gmail.com \ --cc=marc.zyngier@arm.com \ --cc=mark.rutland@arm.com \ --cc=pbonzini@redhat.com \ --cc=peter.maydell@linaro.org \ --cc=preid@electromag.com.au \ --cc=qemu-devel@nongnu.org \ --cc=robh+dt@kernel.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Linux-Renesas-SoC Archive on lore.kernel.org Archives are clonable: git clone --mirror https://lore.kernel.org/linux-renesas-soc/0 linux-renesas-soc/git/0.git # If you have public-inbox 1.1+ installed, you may # initialize and index your mirror using the following commands: public-inbox-init -V2 linux-renesas-soc linux-renesas-soc/ https://lore.kernel.org/linux-renesas-soc \ linux-renesas-soc@vger.kernel.org public-inbox-index linux-renesas-soc Example config snippet for mirrors Newsgroup available over NNTP: nntp://nntp.lore.kernel.org/org.kernel.vger.linux-renesas-soc AGPL code for this site: git clone https://public-inbox.org/public-inbox.git