From nobody Tue Feb 10 12:58:47 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org ARC-Seal: i=1; a=rsa-sha256; t=1579112489; cv=none; d=zohomail.com; s=zohoarc; b=TCGMu3W0kDcv4bdJ4/PaxuiI0jUqr6FDSr2PilY0nn0nugRiBSNSGQ7TCRyjBo3U4nBYQ9hYMyynwyag0Z6pz+g+8/Fc01Rkx1oQDL+TXHvbLuh/PFTQVfAe0VAobJ3bYEWlNQXpZhs0WphhCT1KZy3Q0vBvzMUFKlFXABnifg4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1579112489; h=Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To; bh=Ou/rQnlHYF2lfF+KUuobNGu38KyoAhKKRRecJAtDLNw=; b=Au4jVL5Cq1Y34g2WOGF4d1H35GG5IIK0ZnQQFEukzHSQtGcOVdAFZK+vb+3X4PD/U44eCXEya7xsJq2y/kIImnYuqEu5NfuivkCoz6HGSif7+iQ/t7d42KwDum++YPwg42O2qbT/QB5WEEivJUPs0FmE1cHUmhL5K5hnot+07zQ= ARC-Authentication-Results: i=1; mx.zohomail.com; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1579112489491868.8356710665288; Wed, 15 Jan 2020 10:21:29 -0800 (PST) Received: from localhost ([::1]:58570 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1irnIG-00040e-6M for importer@patchew.org; Wed, 15 Jan 2020 13:21:28 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:53024) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1irnCi-0006Zk-Ds for qemu-devel@nongnu.org; Wed, 15 Jan 2020 13:15:45 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1irnCh-0003aJ-0o for qemu-devel@nongnu.org; Wed, 15 Jan 2020 13:15:44 -0500 Received: from albert.telenet-ops.be ([2a02:1800:110:4::f00:1a]:55256) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1irnCg-0003Xx-Qj for qemu-devel@nongnu.org; Wed, 15 Jan 2020 13:15:42 -0500 Received: from ramsan ([84.195.182.253]) by albert.telenet-ops.be with bizsmtp id qiFR2100Y5USYZQ06iFRqv; Wed, 15 Jan 2020 19:15:37 +0100 Received: from rox.of.borg ([192.168.97.57]) by ramsan with esmtp (Exim 4.90_1) (envelope-from ) id 1irnCP-00012d-IT; Wed, 15 Jan 2020 19:15:25 +0100 Received: from geert by rox.of.borg with local (Exim 4.90_1) (envelope-from ) id 1irnCP-00069F-GU; Wed, 15 Jan 2020 19:15:25 +0100 From: Geert Uytterhoeven To: Linus Walleij , Bartosz Golaszewski , Jonathan Corbet , Harish Jenny K N , Eugeniu Rosca Subject: [PATCH v4 4/5] docs: gpio: Add GPIO Aggregator documentation Date: Wed, 15 Jan 2020 19:15:22 +0100 Message-Id: <20200115181523.23556-5-geert+renesas@glider.be> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200115181523.23556-1-geert+renesas@glider.be> References: <20200115181523.23556-1-geert+renesas@glider.be> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 2a02:1800:110:4::f00:1a X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Mark Rutland , Peter Maydell , qemu-devel@nongnu.org, Geert Uytterhoeven , linux-doc@vger.kernel.org, Marc Zyngier , Magnus Damm , Christoffer Dall , linux-kernel@vger.kernel.org, linux-renesas-soc@vger.kernel.org, linux-gpio@vger.kernel.org, Rob Herring , Alexander Graf , Paolo Bonzini , Phil Reid Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Document the GPIO Aggregator, and the two typical use-cases. Signed-off-by: Geert Uytterhoeven Reviewed-by: Ulrich Hecht --- 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 | 102 ++++++++++++++++++ Documentation/admin-guide/gpio/index.rst | 1 + 2 files changed, 103 insertions(+) create mode 100644 Documentation/admin-guide/gpio/gpio-aggregator.rst diff --git a/Documentation/admin-guide/gpio/gpio-aggregator.rst b/Documenta= tion/admin-guide/gpio/gpio-aggregator.rst new file mode 100644 index 0000000000000000..954ed568b0b833b3 --- /dev/null +++ b/Documentation/admin-guide/gpio/gpio-aggregator.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +GPIO Aggregator +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The GPIO Aggregator allows 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 allows access control for individual GPIOs, by aggrega= ting +them into a new gpio_chip, which can be assigned to a group or user using +standard UNIX file ownership and permissions. Furthermore, this simplifie= s 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 + + [] [ ] ... + + Where: + + "" ... + is a GPIO line name, + + "" ... + is a GPIO chip label or name, and + + "" ... + 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 + 19 of "e6052000.gpio" and GPIOs 20-21 of "gpiochip2" into a new + gpio_chip: + + .. code-block:: bash + + echo 'e6052000.gpio 19 gpiochip2 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 "gpio-aggregator.0": + + .. code-block:: bash + + 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 to communicate with an SPI device from userspace. + +Binding a device to the GPIO Aggregator is performed either by modifying t= he +gpio-aggregator driver, or by writing to the "driver_override" file in Sys= fs. + +Example: If "door" is a GPIO-operated device described in DT, using its own +compatible value:: + + door { + compatible =3D "myvendor,mydoor"; + + gpios =3D <&gpio2 19 GPIO_ACTIVE_HIGH>, + <&gpio2 20 GPIO_ACTIVE_LOW>; + gpio-line-names =3D "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:: bash + + echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override + echo door > /sys/bus/platform/drivers/gpio-aggregator/bind 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 =20 + gpio-aggregator sysfs =20 .. only:: subproject and html --=20 2.17.1