X-Git-Url: http://ftp.safe.ca/?a=blobdiff_plain;f=Documentation%2Fgpio.txt;h=c2c6e9b39bbe39e747fbfe7ffed869bff9cdfff7;hb=5e8aa85253513b9c1ade8bd71dc341218a752a65;hp=145c25a170c7abf6e0e489fba4c00b4784759dca;hpb=8a0cecffeb52363a57257bbbbd58f4c4537a75bb;p=safe%2Fjmp%2Flinux-2.6 diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index 145c25a..c2c6e9b 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt @@ -253,6 +253,70 @@ pin setup (e.g. controlling which pin the GPIO uses, pullup/pulldown). Also note that it's your responsibility to have stopped using a GPIO before you free it. +Considering in most cases GPIOs are actually configured right after they +are claimed, three additional calls are defined: + + /* request a single GPIO, with initial configuration specified by + * 'flags', identical to gpio_request() wrt other arguments and + * return value + */ + int gpio_request_one(unsigned gpio, unsigned long flags, const char *label); + + /* request multiple GPIOs in a single call + */ + int gpio_request_array(struct gpio *array, size_t num); + + /* release multiple GPIOs in a single call + */ + void gpio_free_array(struct gpio *array, size_t num); + +where 'flags' is currently defined to specify the following properties: + + * GPIOF_DIR_IN - to configure direction as input + * GPIOF_DIR_OUT - to configure direction as output + + * GPIOF_INIT_LOW - as output, set initial level to LOW + * GPIOF_INIT_HIGH - as output, set initial level to HIGH + +since GPIOF_INIT_* are only valid when configured as output, so group valid +combinations as: + + * GPIOF_IN - configure as input + * GPIOF_OUT_INIT_LOW - configured as output, initial level LOW + * GPIOF_OUT_INIT_HIGH - configured as output, initial level HIGH + +In the future, these flags can be extended to support more properties such +as open-drain status. + +Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is +introduced to encapsulate all three fields as: + + struct gpio { + unsigned gpio; + unsigned long flags; + const char *label; + }; + +A typical example of usage: + + static struct gpio leds_gpios[] = { + { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */ + { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* default to OFF */ + { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* default to OFF */ + { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* default to OFF */ + { ... }, + }; + + err = gpio_request_one(31, GPIOF_IN, "Reset Button"); + if (err) + ... + + err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios)); + if (err) + ... + + gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios)); + GPIOs mapped to IRQs -------------------- @@ -380,7 +444,7 @@ 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, +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 @@ -458,7 +522,7 @@ 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 approprate hardware documentation for the system, userspace could +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, @@ -524,7 +588,21 @@ and have the following read/write attributes: is configured as an output, this value may be written; any nonzero value is treated as high. -GPIO controllers have paths like /sys/class/gpio/chipchip42/ (for the + "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: @@ -555,6 +633,13 @@ requested using gpio_request(): /* reverse gpio_export() */ void gpio_unexport(); + /* create a sysfs link to an exported GPIO node */ + int gpio_export_link(struct device *dev, const char *name, + unsigned gpio) + + /* change the polarity of a GPIO node in sysfs */ + int gpio_sysfs_set_active_low(unsigned gpio, int value); + After a kernel driver requests a GPIO, it may only be made available in the sysfs interface by gpio_export(). The driver can control whether the signal direction may change. This helps drivers prevent userspace code @@ -563,3 +648,14 @@ 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, gpio_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 gpio_sysfs_set_active_low() to hide GPIO line polarity +differences between boards from user space. This only affects the +sysfs interface. Polarity change can be done both before and after +gpio_export(), and previously enabled poll(2) support for either +rising or falling edge will be reconfigured to follow this setting.