diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/Changes | 11 | ||||
| -rw-r--r-- | Documentation/DocBook/device-drivers.tmpl | 2 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/rng/qcom,prng.txt | 17 | ||||
| -rw-r--r-- | Documentation/gpio/board.txt | 115 | ||||
| -rw-r--r-- | Documentation/gpio/consumer.txt | 197 | ||||
| -rw-r--r-- | Documentation/gpio/driver.txt | 75 | ||||
| -rw-r--r-- | Documentation/gpio/gpio-legacy.txt (renamed from Documentation/gpio.txt) | 0 | ||||
| -rw-r--r-- | Documentation/gpio/gpio.txt | 119 | ||||
| -rw-r--r-- | Documentation/gpio/sysfs.txt | 155 |
9 files changed, 679 insertions, 12 deletions
diff --git a/Documentation/Changes b/Documentation/Changes index b17580885273..07c75d18154e 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -196,13 +196,6 @@ chmod 0644 /dev/cpu/microcode as root before you can use this. You'll probably also want to get the user-space microcode_ctl utility to use with this. -Powertweak ----------- - -If you are running v0.1.17 or earlier, you should upgrade to -version v0.99.0 or higher. Running old versions may cause problems -with programs using shared memory. - udev ---- udev is a userspace application for populating /dev dynamically with @@ -366,10 +359,6 @@ Intel P6 microcode ------------------ o <http://www.urbanmyth.org/microcode/> -Powertweak ----------- -o <http://powertweak.sourceforge.net/> - udev ---- o <http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 6c9d9d37c83a..f5170082bdb3 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -58,7 +58,7 @@ </sect1> <sect1><title>Wait queues and Wake events</title> !Iinclude/linux/wait.h -!Ekernel/wait.c +!Ekernel/sched/wait.c </sect1> <sect1><title>High-resolution timers</title> !Iinclude/linux/ktime.h diff --git a/Documentation/devicetree/bindings/rng/qcom,prng.txt b/Documentation/devicetree/bindings/rng/qcom,prng.txt new file mode 100644 index 000000000000..8e5853c2879b --- /dev/null +++ b/Documentation/devicetree/bindings/rng/qcom,prng.txt @@ -0,0 +1,17 @@ +Qualcomm MSM pseudo random number generator. + +Required properties: + +- compatible : should be "qcom,prng" +- reg : specifies base physical address and size of the registers map +- clocks : phandle to clock-controller plus clock-specifier pair +- clock-names : "core" clocks all registers, FIFO and circuits in PRNG IP block + +Example: + + rng@f9bff000 { + compatible = "qcom,prng"; + reg = <0xf9bff000 0x200>; + clocks = <&clock GCC_PRNG_AHB_CLK>; + clock-names = "core"; + }; diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt new file mode 100644 index 000000000000..0d03506f2cc5 --- /dev/null +++ b/Documentation/gpio/board.txt @@ -0,0 +1,115 @@ +GPIO Mappings +============= + +This document explains how GPIOs can be assigned to given devices and functions. +Note that it only applies to the new descriptor-based interface. For a +description of the deprecated integer-based GPIO interface please refer to +gpio-legacy.txt (actually, there is no real mapping possible with the old +interface; you just fetch an integer from somewhere and request the +corresponding GPIO. + +Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage +is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in +their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to +describe its hardware layout. Currently, mappings can be defined through device +tree, ACPI, and platform data. + +Device Tree +----------- +GPIOs can easily be mapped to devices and functions in the device tree. The +exact way to do it depends on the GPIO controller providing the GPIOs, see the +device tree bindings for your controller. + +GPIOs mappings are defined in the consumer device's node, in a property named +<function>-gpios, where <function> is the function the driver will request +through gpiod_get(). For example: + + foo_device { + compatible = "acme,foo"; + ... + led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */ + <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */ + <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */ + + power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>; + }; + +This property will make GPIOs 15, 16 and 17 available to the driver under the +"led" function, and GPIO 1 as the "power" GPIO: + + struct gpio_desc *red, *green, *blue, *power; + + red = gpiod_get_index(dev, "led", 0); + green = gpiod_get_index(dev, "led", 1); + blue = gpiod_get_index(dev, "led", 2); + + power = gpiod_get(dev, "power"); + +The led GPIOs will be active-high, while the power GPIO will be active-low (i.e. +gpiod_is_active_low(power) will be true). + +ACPI +---- +ACPI does not support function names for GPIOs. Therefore, only the "idx" +argument of gpiod_get_index() is useful to discriminate between GPIOs assigned +to a device. The "con_id" argument can still be set for debugging purposes (it +will appear under error messages as well as debug and sysfs nodes). + +Platform Data +------------- +Finally, GPIOs can be bound to devices and functions using platform data. Board +files that desire to do so need to include the following header: + + #include <linux/gpio/driver.h> + +GPIOs are mapped by the means of tables of lookups, containing instances of the +gpiod_lookup structure. Two macros are defined to help declaring such mappings: + + GPIO_LOOKUP(chip_label, chip_hwnum, dev_id, con_id, flags) + GPIO_LOOKUP_IDX(chip_label, chip_hwnum, dev_id, con_id, idx, flags) + +where + + - chip_label is the label of the gpiod_chip instance providing the GPIO + - chip_hwnum is the hardware number of the GPIO within the chip + - dev_id is the identifier of the device that will make use of this GPIO. If + NULL, the GPIO will be available to all devices. + - con_id is the name of the GPIO function from the device point of view. It + can be NULL. + - idx is the index of the GPIO within the function. + - flags is defined to specify the following properties: + * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low + * GPIOF_OPEN_DRAIN - GPIO pin is open drain type. + * GPIOF_OPEN_SOURCE - GPIO pin is open source type. + +In the future, these flags might be extended to support more properties. + +Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. + +A lookup table can then be defined as follows: + + struct gpiod_lookup gpios_table[] = { + GPIO_LOOKUP_IDX("gpio.0", 15, "foo.0", "led", 0, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP_IDX("gpio.0", 16, "foo.0", "led", 1, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP_IDX("gpio.0", 17, "foo.0", "led", 2, GPIO_ACTIVE_HIGH), + GPIO_LOOKUP("gpio.0", 1, "foo.0", "power", GPIO_ACTIVE_LOW), + }; + +And the table can be added by the board code as follows: + + gpiod_add_table(gpios_table, ARRAY_SIZE(gpios_table)); + +The driver controlling "foo.0" will then be able to obtain its GPIOs as follows: + + struct gpio_desc *red, *green, *blue, *power; + + red = gpiod_get_index(dev, "led", 0); + green = gpiod_get_index(dev, "led", 1); + blue = gpiod_get_index(dev, "led", 2); + + power = gpiod_get(dev, "power"); + gpiod_direction_output(power, 1); + +Since the "power" GPIO is mapped as active-low, its actual signal will be 0 +after this code. Contrary to the legacy integer GPIO interface, the active-low +property is handled during mapping and is thus transparent to GPIO consumers. diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt new file mode 100644 index 000000000000..07c74a3765a0 --- /dev/null +++ b/Documentation/gpio/consumer.txt @@ -0,0 +1,197 @@ +GPIO Descriptor Consumer Interface +================================== + +This document describes the consumer interface of the GPIO framework. 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. + + +Guidelines for GPIOs consumers +============================== + +Drivers that can't work without standard GPIO calls should have Kconfig entries +that depend on GPIOLIB. The functions that allow a driver to obtain and use +GPIOs are available by including the following file: + + #include <linux/gpio/consumer.h> + +All the functions that work with the descriptor-based GPIO interface are +prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No +other function in the kernel should use these prefixes. + + +Obtaining and Disposing GPIOs +============================= + +With the descriptor-based interface, GPIOs are identified with an opaque, +non-forgeable handler that must be obtained through a call to one of the +gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the +device that will use the GPIO and the function the requested GPIO is supposed to +fulfill: + + struct gpio_desc *gpiod_get(struct device *dev, const char *con_id) + +If a function is implemented by using several GPIOs together (e.g. a simple LED +device that displays digits), an additional index argument can be specified: + + struct gpio_desc *gpiod_get_index(struct device *dev, + const char *con_id, unsigned int idx) + +Both functions return either a valid GPIO descriptor, or an error code checkable +with IS_ERR(). They will never return a NULL pointer. + +Device-managed variants of these functions are also defined: + + struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id) + + struct gpio_desc *devm_gpiod_get_index(struct device *dev, + const char *con_id, + unsigned int idx) + +A GPIO descriptor can be disposed of using the gpiod_put() function: + + void gpiod_put(struct gpio_desc *desc) + +It is strictly forbidden to use a descriptor after calling this function. The +device-managed variant is, unsurprisingly: + + void devm_gpiod_put(struct device *dev, struct gpio_desc *desc) + + +Using GPIOs +=========== + +Setting Direction +----------------- +The first thing a driver must do with a GPIO is setting its direction. This is +done by invoking one of the gpiod_direction_*() functions: + + int gpiod_direction_input(struct gpio_desc *desc) + int gpiod_direction_output(struct gpio_desc *desc, int value) + +The return value is zero for success, else a negative errno. It should be +checked, since the get/set calls don't return errors and since misconfiguration +is possible. You should normally issue these calls from a task context. However, +for spinlock-safe GPIOs it is OK to use them before tasking is enabled, as part +of early board setup. + +For output GPIOs, the value provided becomes the initial output value. This +helps avoid signal glitching during system startup. + +A driver can also query the current direction of a GPIO: + + int gpiod_get_direction(const struct gpio_desc *desc) + +This function will return either GPIOF_DIR_IN or GPIOF_DIR_OUT. + +Be aware that there is no default direction for GPIOs. Therefore, **using a GPIO +without setting its direction first is illegal and will result in undefined +behavior!** + + +Spinlock-Safe GPIO Access +------------------------- +Most GPIO controllers can be accessed with memory read/write instructions. Those +don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ +handlers and similar contexts. + +Use the following calls to access GPIOs from an atomic context: + + int gpiod_get_value(const struct gpio_desc *desc); + void gpiod_set_value(struct gpio_desc *desc, int value); + +The values are boolean, zero for low, nonzero for high. When reading the value +of an output pin, the value returned should be what's seen on the pin. That +won't always match the specified output value, because of issues including +open-drain signaling and output latencies. + +The get/set calls do not return errors because "invalid GPIO" should have been +reported earlier from gpiod_direction_*(). However, note that not all platforms +can read the value of output pins; those that can't should always return zero. +Also, using these calls for GPIOs that can't safely be accessed without sleeping +(see below) is an error. + + +GPIO Access That May Sleep +-------------------------- +Some GPIO controllers must be accessed using message based buses like I2C or +SPI. Commands to read or write those GPIO values require waiting to get to the +head of a queue to transmit a command and get its response. This requires +sleeping, which can't be done from inside IRQ handlers. + +Platforms that support this type of GPIO distinguish them from other GPIOs by +returning nonzero from this call: + + int gpiod_cansleep(const struct gpio_desc *desc) + +To access such GPIOs, a different set of accessors is defined: + + int gpiod_get_value_cansleep(const struct gpio_desc *desc) + void gpiod_set_value_cansleep(struct gpio_desc *desc, int value) + +Accessing such GPIOs requires a context which may sleep, for example a threaded +IRQ handler, and those accessors must be used instead of spinlock-safe +accessors without the cansleep() name suffix. + +Other than the fact that these accessors might sleep, and will work on GPIOs +that can't be accessed from hardIRQ handlers, these calls act the same as the +spinlock-safe calls. + + +Active-low State and Raw GPIO Values +------------------------------------ +Device drivers like to manage the logical state of a GPIO, i.e. the value their +device will actually receive, no matter what lies between it and the GPIO line. +In some cases, it might make sense to control the actual GPIO line value. The +following set of calls ignore the active-low property of a GPIO and work on the +raw line value: + + int gpiod_get_raw_value(const struct gpio_desc *desc) + void gpiod_set_raw_value(struct gpio_desc *desc, int value) + int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc) + void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value) + +The active-low state of a GPIO can also be queried using the following call: + + int gpiod_is_active_low(const struct gpio_desc *desc) + +Note that these functions should only be used with great moderation ; a driver +should not have to care about the physical line level. + +GPIOs mapped to IRQs +-------------------- +GPIO lines can quite often be used as IRQs. You can get the IRQ number +corresponding to a given GPIO using the following call: + + int gpiod_to_irq(const struct gpio_desc *desc) + +It will return an IRQ number, or an negative errno code if the mapping can't be +done (most likely because that particular GPIO cannot be used as IRQ). It is an +unchecked error to use a GPIO that wasn't set up as an input using +gpiod_direction_input(), or to use an IRQ number that didn't originally come +from gpiod_to_irq(). gpiod_to_irq() is not allowed to sleep. + +Non-error values returned from gpiod_to_irq() can be passed to request_irq() or +free_irq(). They will often be stored into IRQ resources for platform devices, +by the board-specific initialization code. Note that IRQ trigger options are +part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are system wakeup +capabilities. + + +Interacting With the Legacy GPIO Subsystem +========================================== +Many kernel subsystems still handle GPIOs using the legacy integer-based +interface. Although it is strongly encouraged to upgrade them to the safer +descriptor-based API, the following two functions allow you to convert a GPIO +descriptor into the GPIO integer namespace and vice-versa: + + int desc_to_gpio(const struct gpio_desc *desc) + struct gpio_desc *gpio_to_desc(unsigned gpio) + +The GPIO number returned by desc_to_gpio() can be safely used as long as the +GPIO descriptor has not been freed. All the same, a GPIO number passed to +gpio_to_desc() must have been properly acquired, and usage of the returned GPIO +descriptor is only possible after the GPIO number has been released. + +Freeing a GPIO obtained by one API with the other API is forbidden and an +unchecked error. diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt new file mode 100644 index 000000000000..9da0bfa74781 --- /dev/null +++ b/Documentation/gpio/driver.txt @@ -0,0 +1,75 @@ +GPIO Descriptor 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. + +Each GPIO controller driver needs to include the following header, which defines +the structures used to define a GPIO driver: + + #include <linux/gpio/driver.h> + + +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 +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. + +So for example one platform could use 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. + + +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: + + - methods to establish GPIO direction + - methods used to access GPIO values + - method to return the IRQ number associated to a given GPIO + - flag saying whether calls to its methods may sleep + - optional debugfs dump method (showing extra state like pullup config) + - optional base number (will be automatically assigned if omitted) + - label for diagnostics and GPIOs 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 +gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be rare; +use gpiochip_remove() when it is unavoidable. + +Most often a gpio_chip is part of an instance-specific structure with state not +exposed by the GPIO interfaces, such as addressing, power management, and more. +Chips such as codecs will have complex non-GPIO state. + +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. + +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: + + int gpiod_lock_as_irq(struct gpio_desc *desc) + +This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock +is released: + + void gpiod_unlock_as_irq(struct gpio_desc *desc) diff --git a/Documentation/gpio.txt b/Documentation/gpio/gpio-legacy.txt index 6f83fa965b4b..6f83fa965b4b 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio/gpio-legacy.txt diff --git a/Documentation/gpio/gpio.txt b/Documentation/gpio/gpio.txt new file mode 100644 index 000000000000..cd9b356e88cd --- /dev/null +++ b/Documentation/gpio/gpio.txt @@ -0,0 +1,119 @@ +GPIO Interfaces +=============== + +The documents in this directory give detailed instructions on how to access +GPIOs in drivers, and how to write a driver for a device that provides GPIOs +itself. + +Due to the history of GPIO interfaces in the kernel, there are two different +ways to obtain and use GPIOs: + + - The descriptor-based interface is the preferred way to manipulate GPIOs, +and is described by all the files in this directory excepted gpio-legacy.txt. + - The legacy integer-based interface which is considered deprecated (but still +usable for compatibility reasons) is documented in gpio-legacy.txt. + +The remainder of this document applies to the new descriptor-based interface. +gpio-legacy.txt contains the same information applied to the legacy +integer-based interface. + + +What is a GPIO? +=============== + +A "General Purpose Input/Output" (GPIO) is a flexible software-controlled +digital signal. They are provided from many kinds of chip, and are familiar +to Linux developers working with embedded and custom hardware. Each GPIO +represents a bit connected to a particular pin, or "ball" on Ball Grid Array +(BGA) packages. Board schematics show which external hardware connects to +which GPIOs. Drivers can be written generically, so that board setup code +passes such pin configuration data to drivers. + +System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every +non-dedicated pin can be configured as a GPIO; and most chips have at least +several dozen of them. Programmable logic devices (like FPGAs) can easily +provide GPIOs; multifunction chips like power managers, and audio codecs +often have a few such pins to help with pin scarcity on SOCs; and there are +also "GPIO Expander" chips that connect using the I2C or SPI serial buses. +Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS +firmware knowing how they're used). + +The exact capabilities of GPIOs vary between systems. Common options: + + - Output values are writable (high=1, low=0). Some chips also have + options about how that value is driven, so that for example only one + value might be driven, supporting "wire-OR" and similar schemes for the + other value (notably, "open drain" signaling). + + - Input values are likewise readable (1, 0). Some chips support readback + of pins configured as "output", which is very useful in such "wire-OR" + cases (to support bidirectional signaling). GPIO controllers may have + input de-glitch/debounce logic, sometimes with software controls. + + - Inputs can often be used as IRQ signals, often edge triggered but + sometimes level triggered. Such IRQs may be configurable as system + wakeup events, to wake the system from a low power state. + + - Usually a GPIO will be configurable as either input or output, as needed + by different product boards; single direction ones exist too. + + - Most GPIOs can be accessed while holding spinlocks, but those accessed + through a serial bus normally can't. Some systems support both types. + +On a given board each GPIO is used for one specific purpose like monitoring +MMC/SD card insertion/removal, detecting card write-protect status, driving +a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware +watchdog, sensing a switch, and so on. + + +Common GPIO Properties +====================== + +These properties are met through all the other documents of the GPIO interface +and it is useful to understand them, especially if you need to define GPIO +mappings. + +Active-High and Active-Low +-------------------------- +It is natural to assume that a GPIO is "active" when its output signal is 1 +("high"), and inactive when it is 0 ("low"). However in practice the signal of a +GPIO may be inverted before is reaches its destination, or a device could decide +to have different conventions about what "active" means. Such decisions should +be transparent to device drivers, therefore it is possible to define a GPIO as +being either active-high ("1" means "active", the default) or active-low ("0" +means "active") so that drivers only need to worry about the logical signal and +not about what happens at the line level. + +Open Drain and Open Source +-------------------------- +Sometimes shared signals need to use "open drain" (where only the low signal +level is actually driven), or "open source" (where only the high signal level is +driven) signaling. That term applies to CMOS transistors; "open collector" is +used for TTL. A pullup or pulldown resistor causes the high or low signal level. +This is sometimes called a "wire-AND"; or more practically, from the negative +logic (low=true) perspective this is a "wire-OR". + +One common example of an open drain signal is a shared active-low IRQ line. +Also, bidirectional data bus signals sometimes use open drain signals. + +Some GPIO controllers directly support open drain and open source outputs; many +don't. When you need open drain signaling but your hardware doesn't directly +support it, there's a common idiom you can use to emulate it with any GPIO pin +that can be used as either an input or an output: + + LOW: gpiod_direction_output(gpio, 0) ... this drives the signal and overrides + the pullup. + + HIGH: gpiod_direction_input(gpio) ... this turns off the output, so the pullup + (or some other device) controls the signal. + +The same logic can be applied to emulate open source signaling, by driving the +high signal and configuring the GPIO as input for low. This open drain/open +source emulation can be handled transparently by the GPIO framework. + +If you are "driving" the signal high but gpiod_get_value(gpio) reports a low +value (after the appropriate rise time passes), you know some other component is +driving the shared signal low. That's not necessarily an error. As one common +example, that's how I2C clocks are stretched: a slave that needs a slower clock +delays the rising edge of SCK, and the I2C master adjusts its signaling rate +accordingly. diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.txt new file mode 100644 index 000000000000..c2c3a97f8ff7 --- /dev/null +++ b/Documentation/gpio/sysfs.txt @@ -0,0 +1,155 @@ +GPIO Sysfs Interface for Userspace +================================== + +Platforms which use the "gpiolib" implementors framework may choose to +configure a sysfs user interface to GPIOs. This is different from the +debugfs interface, since it provides control over GPIO direction and +value instead of just showing a gpio state summary. Plus, it could be +present on production systems without debugging support. + +Given appropriate hardware documentation for the system, userspace could +know for example that GPIO #23 controls the write protect line used to +protect boot loader segments in flash memory. System upgrade procedures +may need to temporarily remove that protection, first importing a GPIO, +then changing its output state, then updating the code before re-enabling +the write protection. In normal use, GPIO #23 would never be touched, +and the kernel would have no need to know about it. + +Again depending on appropriate hardware documentation, on some systems +userspace GPIO can be used to determine system configuration data that +standard kernels won't know about. And for some tasks, simple userspace +GPIO drivers could be all that the system really needs. + +Note that standard kernel drivers exist for common "LEDs and Buttons" +GPIO tasks: "leds-gpio" and "gpio_keys", respectively. Use those +instead of talking directly to the GPIOs; they integrate with kernel +frameworks better than your userspace code could. + + +Paths in Sysfs +-------------- +There are three kinds of entry in /sys/class/gpio: + + - Control interfaces used to get userspace control over GPIOs; + + - GPIOs themselves; and + + - GPIO controllers ("gpio_chip" instances). + +That's in addition to standard files including the "device" symlink. + +The control interfaces are write-only: + + /sys/class/gpio/ + + "export" ... Userspace may ask the kernel to export control of + a GPIO to userspace by writing its number to this file. + + Example: "echo 19 > export" will create a "gpio19" node + for GPIO #19, if that's not requested by kernel code. + + "unexport" ... Reverses the effect of exporting to userspace. + + Example: "echo 19 > unexport" will remove a "gpio19" + node exported using the "export" file. + +GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42) +and have the following read/write attributes: + + /sys/class/gpio/gpioN/ + + "direction" ... reads as either "in" or "out". This value may + normally be written. Writing as "out" defaults to + initializing the value as low. To ensure glitch free + operation, values "low" and "high" may be written to + configure the GPIO as an output with that initial value. + + Note that this attribute *will not exist* if the kernel + doesn't support changing the direction of a GPIO, or + it was exported by kernel code that didn't explicitly + allow userspace to reconfigure this GPIO's direction. + + "value" ... reads as either 0 (low) or 1 (high). If the GPIO + is configured as an output, this value may be written; + any nonzero value is treated as high. + + If the pin can be configured as interrupt-generating interrupt + and if it has been configured to generate interrupts (see the + description of "edge"), you can poll(2) on that file and + poll(2) will return whenever the interrupt was triggered. If + you use poll(2), set the events POLLPRI and POLLERR. If you + use select(2), set the file descriptor in exceptfds. After + poll(2) returns, either lseek(2) to the beginning of the sysfs + file and read the new value or close the file and re-open it + to read the value. + + "edge" ... reads as either "none", "rising", "falling", or + "both". Write these strings to select the signal edge(s) + that will make poll(2) on the "value" file return. + + This file exists only if the pin can be configured as an + interrupt generating input pin. + + "active_low" ... reads as either 0 (false) or 1 (true). Write + any nonzero value to invert the value attribute both + for reading and writing. Existing and subsequent + poll(2) support configuration via the edge attribute + for "rising" and "falling" edges will follow this + setting. + +GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the +controller implementing GPIOs starting at #42) and have the following +read-only attributes: + + /sys/class/gpio/gpiochipN/ + + "base" ... same as N, the first GPIO managed by this chip + + "label" ... provided for diagnostics (not always unique) + + "ngpio" ... how many GPIOs this manges (N to N + ngpio - 1) + +Board documentation should in most cases cover what GPIOs are used for +what purposes. However, those numbers are not always stable; GPIOs on +a daughtercard might be different depending on the base board being used, +or other cards in the stack. In such cases, you may need to use the +gpiochip nodes (possibly in conjunction with schematics) to determine +the correct GPIO number to use for a given signal. + + +Exporting from Kernel code +-------------------------- +Kernel code can explicitly manage exports of GPIOs which have already been +requested using gpio_request(): + + /* export the GPIO to userspace */ + int gpiod_export(struct gpio_desc *desc, bool direction_may_change); + + /* reverse gpio_export() */ + void gpiod_unexport(struct gpio_desc *desc); + + /* create a sysfs link to an exported GPIO node */ + int gpiod_export_link(struct device *dev, const char *name, + struct gpio_desc *desc); + + /* change the polarity of a GPIO node in sysfs */ + int gpiod_sysfs_set_active_low(struct gpio_desc *desc, int value); + +After a kernel driver requests a GPIO, it may only be made available in +the sysfs interface by gpiod_export(). The driver can control whether the +signal direction may change. This helps drivers prevent userspace code +from accidentally clobbering important system state. + +This explicit exporting can help with debugging (by making some kinds +of experiments easier), or can provide an always-there interface that's +suitable for documenting as part of a board support package. + +After the GPIO has been exported, gpiod_export_link() allows creating +symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can +use this to provide the interface under their own device in sysfs with +a descriptive name. + +Drivers can use gpiod_sysfs_set_active_low() to hide GPIO line polarity +differences between boards from user space. Polarity change can be done both +before and after gpiod_export(), and previously enabled poll(2) support for +either rising or falling edge will be reconfigured to follow this setting. |