^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0-only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) GPIO Aggregator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) The GPIO Aggregator provides a mechanism to aggregate GPIOs, and expose them as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) a new gpio_chip. This supports the following use cases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Aggregating GPIOs using Sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) GPIO controllers are exported to userspace using /dev/gpiochip* character
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) devices. Access control to these devices is provided by standard UNIX file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) system permissions, on an all-or-nothing basis: either a GPIO controller is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) accessible for a user, or it is not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) The GPIO Aggregator provides access control for a set of one or more GPIOs, by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) aggregating them into a new gpio_chip, which can be assigned to a group or user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) using standard UNIX file ownership and permissions. Furthermore, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) simplifies and hardens exporting GPIOs to a virtual machine, as the VM can just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) grab the full GPIO controller, and no longer needs to care about which GPIOs to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) grab and which not, reducing the attack surface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) Aggregated GPIO controllers are instantiated and destroyed by writing to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) write-only attribute files in sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) /sys/bus/platform/drivers/gpio-aggregator/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) "new_device" ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Userspace may ask the kernel to instantiate an aggregated GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) controller by writing a string describing the GPIOs to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) aggregate to the "new_device" file, using the format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) [<gpioA>] [<gpiochipB> <offsets>] ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) Where:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) "<gpioA>" ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) is a GPIO line name,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) "<gpiochipB>" ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) is a GPIO chip label, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) "<offsets>" ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) is a comma-separated list of GPIO offsets and/or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) GPIO offset ranges denoted by dashes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) Example: Instantiate a new GPIO aggregator by aggregating GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) line 19 of "e6052000.gpio" and GPIO lines 20-21 of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) "e6050000.gpio" into a new gpio_chip:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) .. code-block:: sh
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) $ echo 'e6052000.gpio 19 e6050000.gpio 20-21' > new_device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) "delete_device" ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) Userspace may ask the kernel to destroy an aggregated GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) controller after use by writing its device name to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) "delete_device" file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) Example: Destroy the previously-created aggregated GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) controller, assumed to be "gpio-aggregator.0":
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) .. code-block:: sh
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) $ echo gpio-aggregator.0 > delete_device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) Generic GPIO Driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) The GPIO Aggregator can also be used as a generic driver for a simple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) GPIO-operated device described in DT, without a dedicated in-kernel driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) This is useful in industrial control, and is not unlike e.g. spidev, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) allows the user to communicate with an SPI device from userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) Binding a device to the GPIO Aggregator is performed either by modifying the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) gpio-aggregator driver, or by writing to the "driver_override" file in Sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) Example: If "door" is a GPIO-operated device described in DT, using its own
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) compatible value::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) door {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) compatible = "myvendor,mydoor";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) gpios = <&gpio2 19 GPIO_ACTIVE_HIGH>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) <&gpio2 20 GPIO_ACTIVE_LOW>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) gpio-line-names = "open", "lock";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) it can be bound to the GPIO Aggregator by either:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) 1. Adding its compatible value to ``gpio_aggregator_dt_ids[]``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) 2. Binding manually using "driver_override":
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) .. code-block:: sh
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) $ echo gpio-aggregator > /sys/bus/platform/devices/door/driver_override
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) $ echo door > /sys/bus/platform/drivers/gpio-aggregator/bind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) After that, a new gpiochip "door" has been created:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) .. code-block:: sh
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) $ gpioinfo door
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) gpiochip12 - 2 lines:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) line 0: "open" unused input active-high
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) line 1: "lock" unused input active-high
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags