diff options
Diffstat (limited to 'packages/linux/linux-rp-2.6.24/tosa/0024-Update-Documentation-gpio.txt-primarily-to-include.patch')
| -rw-r--r-- | packages/linux/linux-rp-2.6.24/tosa/0024-Update-Documentation-gpio.txt-primarily-to-include.patch | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/packages/linux/linux-rp-2.6.24/tosa/0024-Update-Documentation-gpio.txt-primarily-to-include.patch b/packages/linux/linux-rp-2.6.24/tosa/0024-Update-Documentation-gpio.txt-primarily-to-include.patch new file mode 100644 index 0000000000..e460379de6 --- /dev/null +++ b/packages/linux/linux-rp-2.6.24/tosa/0024-Update-Documentation-gpio.txt-primarily-to-include.patch @@ -0,0 +1,238 @@ +From 7ba82399f2d2df6114ad552999f2e1b9a19cb47a Mon Sep 17 00:00:00 2001 +From: David Brownell <dbrownell@users.sourceforge.net> +Date: Sat, 19 Jan 2008 19:41:18 +0300 +Subject: [PATCH 24/64] Update Documentation/gpio.txt, primarily to include the new "gpiolib" + infrastructure. + +Signed-off-by: David Brownell <dbrownell@users.sourceforge.net> +Cc: Jean Delvare <khali@linux-fr.org> +Cc: Eric Miao <eric.miao@marvell.com> +Cc: Sam Ravnborg <sam@ravnborg.org> +Cc: Haavard Skinnemoen <hskinnemoen@atmel.com> +Cc: Philipp Zabel <philipp.zabel@gmail.com> +Cc: Russell King <rmk@arm.linux.org.uk> +Cc: Ben Gardner <bgardner@wabtec.com> +Signed-off-by: Andrew Morton <akpm@linux-foundation.org> +--- + Documentation/gpio.txt | 133 +++++++++++++++++++++++++++++++++++++++++++---- + 1 files changed, 121 insertions(+), 12 deletions(-) + +diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt +index 6bc2ba2..8da724e 100644 +--- a/Documentation/gpio.txt ++++ b/Documentation/gpio.txt +@@ -32,7 +32,7 @@ The exact capabilities of GPIOs vary between systems. Common options: + - 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 logic, sometimes with software controls. ++ 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 +@@ -60,10 +60,13 @@ used on a board that's wired differently. Only least-common-denominator + functionality can be very portable. Other features are platform-specific, + and that can be critical for glue logic. + +-Plus, this doesn't define an implementation framework, just an interface. ++Plus, this doesn't require any implementation framework, just an interface. + One platform might implement it as simple inline functions accessing chip + registers; another might implement it by delegating through abstractions +-used for several very different kinds of GPIO controller. ++used for several very different kinds of GPIO controller. (There is some ++optional code supporting such an implementation strategy, described later ++in this document, but drivers acting as clients to the GPIO interface must ++not care how it's implemented.) + + That said, if the convention is supported on their platform, drivers should + use it when possible. Platforms should declare GENERIC_GPIO support in +@@ -121,6 +124,11 @@ 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. + ++For compatibility with legacy interfaces to GPIOs, setting the direction ++of a GPIO implicitly requests that GPIO (see below) if it has not been ++requested already. That compatibility may be removed in the future; ++explicitly requesting GPIOs is strongly preferred. ++ + Setting the direction can fail if the GPIO number is invalid, or when + that particular GPIO can't be used in that mode. It's generally a bad + idea to rely on boot firmware to have set the direction correctly, since +@@ -133,6 +141,7 @@ Spinlock-Safe GPIO access + ------------------------- + Most GPIO controllers can be accessed with memory read/write instructions. + That doesn't need to sleep, and can safely be done from inside IRQ handlers. ++(That includes hardirq contexts on RT kernels.) + + Use these calls to access such GPIOs: + +@@ -145,7 +154,7 @@ Use these calls to access such GPIOs: + 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 wire-OR and output latencies. ++issues including open-drain signaling and output latencies. + + The get/set calls have no error returns because "invalid GPIO" should have + been reported earlier from gpio_direction_*(). However, note that not all +@@ -170,7 +179,8 @@ 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: ++by returning nonzero from this call (which requires a valid GPIO number, ++either explicitly or implicitly requested): + + int gpio_cansleep(unsigned gpio); + +@@ -209,8 +219,11 @@ before tasking is enabled, as part of early board setup. + These calls serve two basic purposes. One is marking the signals which + are actually in use as GPIOs, for better diagnostics; systems may have + several hundred potential GPIOs, but often only a dozen are used on any +-given board. Another is to catch conflicts between drivers, reporting +-errors when drivers wrongly think they have exclusive use of that signal. ++given board. Another is to catch conflicts, identifying errors when ++(a) two or more drivers wrongly think they have exclusive use of that ++signal, or (b) something wrongly believes it's safe to remove drivers ++needed to manage a signal that's in active use. That is, requesting a ++GPIO can serve as a kind of lock. + + These two calls are optional because not not all current Linux platforms + offer such functionality in their GPIO support; a valid implementation +@@ -223,6 +236,9 @@ Note that requesting a GPIO does NOT cause it to be configured in any + way; it just marks that GPIO as in use. Separate code must handle any + 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. ++ + + GPIOs mapped to IRQs + -------------------- +@@ -238,7 +254,7 @@ map between them using calls like: + + Those return either the corresponding number in the other namespace, or + else a negative errno code if the mapping can't be done. (For example, +-some GPIOs can't used as IRQs.) It is an unchecked error to use a GPIO ++some GPIOs can't be used as IRQs.) It is an unchecked error to use a GPIO + number that wasn't set up as an input using gpio_direction_input(), or + to use an IRQ number that didn't originally come from gpio_to_irq(). + +@@ -299,17 +315,110 @@ Related to multiplexing is configuration and enabling of the pullups or + pulldowns integrated on some platforms. Not all platforms support them, + or support them in the same way; and any given board might use external + pullups (or pulldowns) so that the on-chip ones should not be used. ++(When a circuit needs 5 kOhm, on-chip 100 kOhm resistors won't do.) + + There are other system-specific mechanisms that are not specified here, + like the aforementioned options for input de-glitching and wire-OR output. + Hardware may support reading or writing GPIOs in gangs, but that's usually + configuration dependent: for GPIOs sharing the same bank. (GPIOs are + commonly grouped in banks of 16 or 32, with a given SOC having several such +-banks.) Some systems can trigger IRQs from output GPIOs. Code relying on +-such mechanisms will necessarily be nonportable. ++banks.) Some systems can trigger IRQs from output GPIOs, or read values ++from pins not managed as GPIOs. Code relying on such mechanisms will ++necessarily be nonportable. + +-Dynamic definition of GPIOs is not currently supported; for example, as ++Dynamic definition of GPIOs is not currently standard; for example, as + a side effect of configuring an add-on board with some GPIO expanders. + + These calls are purely for kernel space, but a userspace API could be built +-on top of it. ++on top of them. ++ ++ ++GPIO implementor's framework (OPTIONAL) ++======================================= ++As noted earlier, there is an optional implementation framework making it ++easier for platforms to support different kinds of GPIO controller using ++the same programming interface. ++ ++As a debugging aid, if debugfs is available a /sys/kernel/debug/gpio file ++will be found there. That will list all the controllers registered through ++this framework, and the state of the GPIOs currently in use. ++ ++ ++Controller Drivers: gpio_chip ++----------------------------- ++In this framework each GPIO controller is packaged as a "struct gpio_chip" ++with information common to each controller of that type: ++ ++ - methods to establish GPIO direction ++ - methods used to access GPIO values ++ - flag saying whether calls to its methods may sleep ++ - optional debugfs dump method (showing extra state like pullup config) ++ - label for diagnostics ++ ++There is also per-instance data, which may come from device.platform_data: ++the number of its first GPIO, and how many GPIOs it exposes. ++ ++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. ++ ++ ++Platform Support ++---------------- ++To support this framework, a platform's Kconfig will "select HAVE_GPIO_LIB" ++and arrange that its <asm/gpio.h> includes <asm-generic/gpio.h> and defines ++three functions: gpio_get_value(), gpio_set_value(), and gpio_cansleep(). ++They may also want to provide a custom value for ARCH_NR_GPIOS. ++ ++Trivial implementations of those functions can directly use framework ++code, which always dispatches through the gpio_chip: ++ ++ #define gpio_get_value __gpio_get_value ++ #define gpio_set_value __gpio_set_value ++ #define gpio_cansleep __gpio_cansleep ++ ++Fancier implementations could instead define those as inline functions with ++logic optimizing access to specific SOC-based GPIOs. For example, if the ++referenced GPIO is the constant "12", getting or setting its value could ++cost as little as two or three instructions, never sleeping. When such an ++optimization is not possible those calls must delegate to the framework ++code, costing at least a few dozen instructions. For bitbanged I/O, such ++instruction savings can be significant. ++ ++For SOCs, platform-specific code defines and registers gpio_chip instances ++for each bank of on-chip GPIOs. Those GPIOs should be numbered/labeled to ++match chip vendor documentation, and directly match board schematics. They ++may well start at zero and go up to a platform-specific limit. Such GPIOs ++are normally integrated into platform initialization to make them always be ++available, from arch_initcall() or earlier; they can often serve as IRQs. ++ ++ ++Board Support ++------------- ++For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi ++function devices, FPGAs or CPLDs -- most often board-specific code handles ++registering controller devices and ensures that their drivers know what GPIO ++numbers to use with gpiochip_add(). Their numbers often start right after ++platform-specific GPIOs. ++ ++For example, board setup code could create structures identifying the range ++of GPIOs that chip will expose, and passes them to each GPIO expander chip ++using platform_data. Then the chip driver's probe() routine could pass that ++data to gpiochip_add(). ++ ++Initialization order can be important. For example, when a device relies on ++an I2C-based GPIO, its probe() routine should only be called after that GPIO ++becomes available. That may mean the device should not be registered until ++calls for that GPIO can work. One way to address such dependencies is for ++such gpio_chip controllers to provide setup() and teardown() callbacks to ++board specific code; those board specific callbacks would register devices ++once all the necessary resources are available. +-- +1.5.3.8 + |