Re: [patch 2.6.20-rc1 0/6] arch-neutral GPIO calls

Re: [patch 2.6.20-rc1 0/6] arch-neutral GPIO calls

[Kevin O'Connor]

> Based on earlier discussion, I'm sending a refresh of the generic GPIO
> patch, with several (ARM based) implementations in separate patches:

Hi Dave,

I'm very interested in seeing an abstraction for gpios.  Over the last
several months, I've been working on getting Linux running on my phone
- see www.handhelds.org for more information.  These types of ARM
based PDAs and phones are riddled with GPIOs, and there is frequent
code duplication when two machines have to do similar functionality
with different gpios.

Unfortunately, I fear the implementation you propose is not robust
enough to handle the cases I need to handle.  In particular, I think a
"struct gpio" instead of "int gpio" is needed to describe a gpio pin.

Some background - on the phone I use, it has the standard PXA27x
gpios, a gpio extender chip (egpio) which is connected via the memory
bus, and a micro-controller attached via an i2c like bus.  Other
phones will commonly have the PXA27x, "egpio", and an "asic3" chip.
With the sale of the PXA line, it seems Samsung and TI based ARM chips
(and their corresponding GPIOs) will be on the rise.

As you know, basic functionality like setting a LED, detecting a
button press, requesting an irq, etc. are common with GPIOs regardless
of which platform, or which gpio chip, is in use.

The concern I have with your current implementation is that I don't
see a way to flexibly add in support for additional gpio pins on a
machine by machine basis.  The code does do a good job of abstracting
gpios based on the primary architecture (eg, PXA vs OMAP), but not on
a chip basis (eg, PXA vs ASIC3).

Specifically, once the code pulls in "<asm/gpio.h>" it will get the
PXA gpio code, but this will only allow access to the arch gpios, not
the machine specific gpios.  Also, one of the goals of the developers
at handhelds.org is to have one kernel for many different phones --
from a userspace point of view they don't generally differ very much.
As such, this isn't a matter of just having each "machine" override
the gpio.h file at compile time; it really needs to be done at
runtime.

I understand that the existing code works entirely on integers.
However, I fear this is at attribute of the problem, not of the
solution.

> - Core patch, doc + <asm-arm/gpio.h> + <asm-generic/gpio.h>
> - OMAP implementation
> - AT91 implementation
> - PXA implementation
> - SA1100 implementation
> - S3C2410 implementation

Your patch clearly shows that the existing implementations are using
integers.  I think there is a simple way to reuse the existing
implementations.  For example on pxa one could do something like:

============= include/linux/gpio.h

struct gpio_ops {
        int (*gpio_direction_input)(struct *gpio);
        ...
};

struct gpio {
     struct gpio_ops *ops;
};

============= arch/arm/mach-pxa/gpio.c

struct gpio pxa_gpios[120] = {
        {.ops = pxa_gpio_ops}, ...
};

int pxa_gpio_direction_input(struct *gpio) {
        int pxa_gpio = gpio - pxa_gpios;
        pxa_gpio_mode(pxa_gpio | GPIO_IN);
        return 0;
}

...

> Other than clarifications, the main change in the doc is defining
> new calls safe for use with GPIOs on things like pcf8574 I2C gpio
> expanders; those new calls can sleep, but are otherwise the same as
> the spinlock-safe versions. The implementations above implement that
> as a wrapper (the asm-generic header) around the spinlock-safe calls.

As above, I'm confused how these expanders would work in practice.
The expanders would be present on a machine by machine basis but the
code seems to be implemented on an arch by arch basis.  Perhaps an
example would help me.

Please CC me on replies.

Cheers,
-Kevin

Re: [patch 2.6.20-rc1 0/6] arch-neutral GPIO calls

[David Brownell]

On Sunday 31 December 2006 11:11 am, Kevin O'Connor wrote:
> > Based on earlier discussion, I'm sending a refresh of the generic GPIO
> > patch, with several (ARM based) implementations in separate patches:
> 
> Hi Dave,
> 
> I'm very interested in seeing an abstraction for gpios.

Good!  I suspect most folk who've had to work on a few different
embedded Linux boards have noticed lots of needlessly-different
GPIO code.  Not many folk are actually seeing that as more than
just ugliness though.


> Unfortunately, I fear the implementation you propose is not robust
> enough to handle the cases I need to handle. 

The _interface_ allows those additional GPIO controllers though.
Specifically of the type you mentioned ... that's why this version
defined new "cansleep" call variants.


> The concern I have with your current implementation is that I don't
> see a way to flexibly add in support for additional gpio pins on a
> machine by machine basis.  The code does do a good job of abstracting
> gpios based on the primary architecture (eg, PXA vs OMAP), but not on
> a chip basis (eg, PXA vs ASIC3).

You used the key word:  implementation.  The interface allows it,
but such board-specific extensions haven't yet been needed; so
they've not yet been implemented.

See the appended for a patch roughly along the lines of what has
previously been discussed here.  No interface change, just updated
implementation code.  And the additional implementation logic won't
kick on boards that don't need it.

Note that the current implementations are a win even without yet
being able to handle the board-specific external GPIO controllers.
The API is clearer than chip-specific register access, and since
it's arch-neutral it already solves integration problems (like
having one SPI controller driver work on both AT91 and AVR).


> > Other than clarifications, the main change in the doc is defining
> > new calls safe for use with GPIOs on things like pcf8574 I2C gpio
> > expanders; those new calls can sleep, but are otherwise the same as
> > the spinlock-safe versions. The implementations above implement that
> > as a wrapper (the asm-generic header) around the spinlock-safe calls.
> 
> As above, I'm confused how these expanders would work in practice.

One approach:  updating implementations along the lines the patch below.
Other implementations could work too.

Note that I see that kind of update as happening after the first round
of patches go upstream:  accept the interface first, then update boards
to support it ... including later the cansleep calls, on some boards.

I like the idea of first replacing the "old" GPIO accesses with ones
using the new APIs ... and only then starting to convert old I2C (etc)
accesses.


> The expanders would be present on a machine by machine basis but the
> code seems to be implemented on an arch by arch basis.  Perhaps an
> example would help me.

An example showing one way to implement that interface ... appended.
The expanders would be board-specific, not arch/.../mach-* specific.
(I try to avoid using the word "machine" there; it's too ambiguous.)

The code below just show how boards could plug in; it doesn't actually
convert any boards to use that infrastructure.  It should be obvious
how to do that, if you've got a board needing it which works with the
kernel.org GIT tree...

- Dave

=================	CUT HERE
Preliminary version of support for board-specific declaring GPIO controllers,
primarily for use with things like I2C access to GPIOs.

  * GPIOs numbered 0..ARCH_GPIO_MAX always use internal arch/SOC specific
    controller access, and are spinlock-safe.

  * All other GPIO numbers are allocated semi-dynamically, as part of
    declaring a GPIO controller, and are assumed spinlock-unsafe.

  * Such external GPIO controllers provide a simple ops vector for
    setting direction, and accessing GPIO values.

Board-specific init code can declare the controllers, then hand out the
GPIOs to code that needs them.

Index: pxa/include/asm-generic/gpio.h
===================================================================
--- pxa.orig/include/asm-generic/gpio.h	2007-01-01 11:20:14.000000000 -0800
+++ pxa/include/asm-generic/gpio.h	2007-01-01 11:34:42.000000000 -0800
@@ -1,7 +1,51 @@
 #ifndef _ASM_GENERIC_GPIO_H
 #define _ASM_GENERIC_GPIO_H
 
-/* platforms that don't directly support access to GPIOs through I2C, SPI,
+#ifdef	CONFIG_GPIOLIB
+
+/* Boards with GPIOs accessed through I2C etc can access them through some
+ * gpio expander library code:
+ *
+ *  - Define ARCH_GPIO_MAX.  All GPIO ids accessed through such expanders
+ *    will be above this number.  Most other GPIOs are SOC-integrated, and
+ *    could be accessed by inlined direct register reads/writes.
+ *
+ *  - Board-specific setup code declares each controller and how many GPIOs
+ *    it handles.  The return value is the first GPIO associated with that
+ *    controller; other GPIOs immediately follow.  These GPIO numbers are
+ *    then handed out to the drivers which need them.
+ *
+ *  - Have the gpio management code (request, free, set direction) delegate
+ *    to gpiolib for GPIOs above ARCH_MAX; and fail gpio_to_irq() for them.
+ */
+struct gpio_ops {
+	int	(*direction_input)(void *, unsigned offset);
+	int	(*direction_output)(void *, unsigned offset);
+	int	(*get_value)(void *, unsigned offset);
+	int	(*set_value)(void *, unsigned offset, int value);
+};
+
+extern int __init gpiolib_define_controller(struct gpio_ops *, void *, int n);
+
+extern int gpiolib_request(unsigned gpio, const char *name);
+extern void gpiolib_free(unsigned gpio);
+extern int gpiolib_direction_input(unsigned gpio);
+extern int gpiolib_direction_output(unsigned gpio);
+
+
+/* for now, assume only arch/soc gpios are spinlock-safe */
+static inline int gpio_cansleep(unsigned gpio)
+{
+	return gpio <= ARCH_GPIO_MAX;
+}
+
+/* these standard gpio calls handle both kinds of GPIO */
+extern int gpio_get_value_cansleep(unsigned gpio);
+extern void gpio_set_value_cansleep(unsigned gpio, int value);
+
+#else
+
+/* boards that don't directly support access to GPIOs through I2C, SPI,
  * or other blocking infrastructure can use these wrappers.
  */
 
@@ -22,4 +66,29 @@ static inline void gpio_set_value_cansle
 	gpio_set_value(gpio, value);
 }
 
+/* having these gpiolib_*() inlines makes it easy to just kick in
+ * the library code for boards that need it
+ */
+
+static inline int gpiolib_request(unsigned gpio, const char *name)
+{
+	return -EINVAL;
+}
+
+static inline void gpiolib_free(unsigned gpio)
+{
+}
+
+static inline int gpiolib_direction_input(unsigned gpio)
+{
+	return -EINVAL;
+}
+
+static inline int gpiolib_direction_output(unsigned gpio)
+{
+	return -EINVAL;
+}
+
+#endif
+
 #endif /* _ASM_GENERIC_GPIO_H */
Index: pxa/lib/Kconfig
===================================================================
--- pxa.orig/lib/Kconfig	2007-01-01 11:20:14.000000000 -0800
+++ pxa/lib/Kconfig	2007-01-01 11:34:42.000000000 -0800
@@ -106,4 +106,10 @@ config IOMAP_COPY
 	depends on !UML
 	default y
 
+#
+# gpiolib support is selected on boards that need it
+#
+config GPIOLIB
+	boolean
+
 endmenu
Index: pxa/lib/Makefile
===================================================================
--- pxa.orig/lib/Makefile	2007-01-01 11:20:14.000000000 -0800
+++ pxa/lib/Makefile	2007-01-01 11:34:42.000000000 -0800
@@ -57,6 +57,7 @@ obj-$(CONFIG_AUDIT_GENERIC) += audit.o
 
 obj-$(CONFIG_SWIOTLB) += swiotlb.o
 obj-$(CONFIG_FAULT_INJECTION) += fault-inject.o
+obj-$(CONFIG_GPIOLIB) += gpiolib.o
 
 lib-$(CONFIG_GENERIC_BUG) += bug.o
 
Index: pxa/lib/gpiolib.c
===================================================================
--- /dev/null	1970-01-01 00:00:00.000000000 +0000
+++ pxa/lib/gpiolib.c	2007-01-01 11:34:42.000000000 -0800
@@ -0,0 +1,192 @@
+#include <linux/kernel.h>
+#include <linux/init.h>
+#include <linux/bitops.h>
+#include <linux/spinlock.h>
+#include <linux/idr.h>
+#include <linux/mutex.h>
+#include <linux/module.h>
+
+#include <asm/gpio.h>
+
+
+/* This is a simple library to support GPIO controllers not integrated into
+ * system-on-chip level arch support.  These are reasonably common on embedded
+ * boards, where their hotpluggability is a non-issue.  They are often accessed
+ * through busses like I2C or SPI; getting or setting values for such GPIOs
+ * normally sleeps.  (Not always; ucb1x00 GPIOs are a counterexample.)
+ */
+
+struct gpio {
+	struct gpio_ops	*ops;
+	void		*controller;
+	int		base;
+	unsigned	n;
+	unsigned long	requested[1];
+};
+
+static DEFINE_MUTEX(gpio_lock);
+static struct idr gpio_idr;
+
+static struct gpio *gpionum2gpio(unsigned gpionum)
+{
+	struct gpio	*g;
+
+	mutex_lock(&gpio_lock);
+	g = idr_find(&gpio_idr, gpionum);
+	mutex_unlock(&gpio_lock);
+	return g;
+}
+
+/*-------------------------------------------------------------------------*/
+
+/* some controllers (e.g. simple FPGA logic) have fixed directions */
+
+int gpiolib_direction_input(unsigned gpionum)
+{
+	struct gpio	*g = gpionum2gpio(gpionum);
+
+	if (!g || !g->ops->direction_input)
+		return -EINVAL;
+	return g->ops->direction_input(g->controller, gpionum - g->base);
+}
+EXPORT_SYMBOL_GPL(gpiolib_direction_input);
+
+int gpiolib_direction_output(unsigned gpionum)
+{
+	struct gpio	*g = gpionum2gpio(gpionum);
+
+	if (!g || !g->ops->direction_output)
+		return -EINVAL;
+	return g->ops->direction_output(g->controller, gpionum - g->base);
+}
+EXPORT_SYMBOL_GPL(gpiolib_direction_output);
+
+
+/* Might as well have real implementations of request/free.  Debug versions
+ * might remember name and direction, and dump state in debugfs...
+ */
+
+int gpiolib_request(unsigned gpionum, const char *name)
+{
+	struct gpio	*g = gpionum2gpio(gpionum);
+	unsigned	offset;
+	int		value;
+
+	if (!g)
+		return -EINVAL;
+	offset = gpionum - g->base;
+
+	mutex_lock(&gpio_lock);
+	value = test_and_set_bit(offset, g->requested);
+	mutex_unlock(&gpio_lock);
+	return value ? -EBUSY : 0;
+}
+EXPORT_SYMBOL_GPL(gpiolib_request);
+
+void gpiolib_free(unsigned gpionum)
+{
+	struct gpio	*g = gpionum2gpio(gpionum);
+	unsigned	offset;
+
+	if (!g)
+		return;
+	offset = gpionum - g->base;
+
+	mutex_lock(&gpio_lock);
+	clear_bit(offset, g->requested);
+	mutex_unlock(&gpio_lock);
+}
+EXPORT_SYMBOL_GPL(gpiolib_free);
+
+/*-------------------------------------------------------------------------*/
+
+int gpio_get_value_cansleep(unsigned gpionum)
+{
+	struct gpio	*g;
+
+	might_sleep();
+	if (!gpio_cansleep(gpionum))
+		return gpio_get_value(gpionum);
+	g = gpionum2gpio(gpionum);
+	if (!g || !g->ops->get_value)
+		return 0;
+	return g->ops->get_value(g->controller, gpionum - g->base);
+}
+EXPORT_SYMBOL_GPL(gpio_get_value_cansleep);
+
+void gpio_set_value_cansleep(unsigned gpionum, int value)
+{
+	struct gpio	*g;
+
+	might_sleep();
+	if (!gpio_cansleep(gpionum)) {
+		gpio_set_value(gpionum, value);
+		return;
+	}
+	g = gpionum2gpio(gpionum);
+	if (!g || !g->ops->set_value)
+		return;
+	g->ops->set_value(g->controller, gpionum - g->base, value);
+}
+EXPORT_SYMBOL_GPL(gpio_set_value_cansleep);
+
+/*-------------------------------------------------------------------------*/
+
+/* board-specific arch_initcall() code usually defines external GPIO
+ * controllers available, along with the other board-specific devices.
+ */
+
+int __init
+gpiolib_define_controller(struct gpio_ops *ops, void *controller, int n)
+{
+	struct gpio	*g;
+	int		value;
+	int		gpionum;
+
+	if (n <= 0 || n > BITS_PER_LONG)
+		return -EINVAL;
+
+	idr_pre_get(&gpio_idr, GFP_KERNEL);
+
+	g = kzalloc(sizeof *g, GFP_KERNEL);
+	if (!g)
+		return -ENOMEM;
+
+	g->ops = ops;
+	g->controller = controller;
+	g->n = n;
+
+	mutex_lock(&gpio_lock);
+
+	value = idr_get_new_above(&gpio_idr, g, ARCH_GPIO_MAX + 1, &g->base);
+	if (value < 0)
+		goto fail0;
+	gpionum = g->base;
+	while (n--) {
+		int	gpio;
+
+		gpionum++;
+		value = idr_get_new_above(&gpio_idr, g, gpionum, &gpio);
+		if (value < 0 || gpio != gpionum)
+			goto fail;
+	}
+
+	mutex_unlock(&gpio_lock);
+	return g->base;
+
+fail:
+	n = g->n;
+	while (n--)
+		idr_replace(&gpio_idr, NULL, g->base + n);
+fail0:
+	mutex_unlock(&gpio_lock);
+	kfree(g);
+	return value;
+}
+
+static int __init gpio_cansleep_init(void)
+{
+	idr_init(&gpio_idr);
+	return 0;
+}
+postcore_initcall(gpio_cansleep_init);

Index: pxa/include/asm-arm/arch-pxa/gpio.h
===================================================================
--- pxa.orig/include/asm-arm/arch-pxa/gpio.h	2007-01-01 11:34:30.000000000 -0800
+++ pxa/include/asm-arm/arch-pxa/gpio.h	2007-01-01 11:35:13.000000000 -0800
@@ -30,6 +30,8 @@
 
 #include <asm/arch/pxa-regs.h>
 
+#define	ARCH_GPIO_MAX	PXA_LAST_GPIO
+
 static inline int gpio_get_value(unsigned gpio);
 static inline void gpio_set_value(unsigned gpio, int value);
 
@@ -47,11 +49,15 @@ static inline void gpio_free(unsigned gp
 
 static inline int gpio_direction_input(unsigned gpio)
 {
+	if (gpio_cansleep(gpio))
+		return gpiolib_direction_input(gpio);
 	return pxa_gpio_mode(gpio | GPIO_IN);
 }
 
 static inline int gpio_direction_output(unsigned gpio)
 {
+	if (gpio_cansleep(gpio))
+		return gpiolib_direction_output(gpio);
 	return pxa_gpio_mode(gpio | GPIO_OUT);
 }
 

Re: [patch 2.6.20-rc1 0/6] arch-neutral GPIO calls

[Kevin O'Connor]

Hi Dave,

On Mon, Jan 01, 2007 at 12:06:19PM -0800, David Brownell wrote:
> > The concern I have with your current implementation is that I don't
> > see a way to flexibly add in support for additional gpio pins on a
> > machine by machine basis.  The code does do a good job of abstracting
> > gpios based on the primary architecture (eg, PXA vs OMAP), but not on
> > a chip basis (eg, PXA vs ASIC3).
> 
> You used the key word:  implementation.  The interface allows it,
> but such board-specific extensions haven't yet been needed; so
> they've not yet been implemented.
> 
> See the appended for a patch roughly along the lines of what has
> previously been discussed here.  No interface change, just updated
> implementation code.  And the additional implementation logic won't
> kick on boards that don't need it.

Thanks for enlightening me on previous discussions.  The interface in
the "gpiolib" patch is along the lines of what I'm looking for.

However, I still feel this approach is backwards.  Going from a
'struct gpio' to an 'int gpio' is easy.  Attempting to go from an 'int
gpio' to a 'struct gpio' is hard, as the code you provide
demonstrates.

Can you help explain what the gain to using an integer over a 'struct
gpio' is?  I can't help but feel that fundamentally gpios are not
integers and that it is a mistake to code an API around that concept.

> Note that the current implementations are a win even without yet
> being able to handle the board-specific external GPIO controllers.
> The API is clearer than chip-specific register access, and since
> it's arch-neutral it already solves integration problems (like
> having one SPI controller driver work on both AT91 and AVR).

I agree that the code you provide is a big step up from the existing
code.  We also both seem to agree that more than just an arch
abstraction is necessary (the cansleep stuff seems to be an
acknowledgment of this).

However, I don't understand the downside to making the API sane from
the start and avoiding the artificial integer namespace problems.

> Note that I see that kind of update as happening after the first round
> of patches go upstream:  accept the interface first, then update boards
> to support it ... including later the cansleep calls, on some boards.

Once many of the problems are fixed, I fear fixing the remaining will
be a harder sell.  Due to the difficulty of implementing kernel wide
APIs, I suspect some maintainers will just stick to cramming features
in the arch directory (as your patch encourages) which can lead to
duplicated code and fragmented implementations.

Thanks for working on this.
-Kevin

[patch/rfc 2.6.19-rc5] arch-neutral GPIO calls

[David Brownell]

I know there have been discussions about standardizing GPIOs before,
but nothing quite "took".  One of the more recent ones was

  http://marc.theaimsgroup.com/?l=linux-kernel&m=110873454720555&w=2

Below, find what I think is a useful proposal, trivially implementable on
many ARMs (at91, omap, pxa, ep93xx, ixp2000, pnx4008, davinci, more) as well
as the new AVR32.

Compared to the proposal above, key differences include:

  - Only intended for use with "real" GPIOs that work from IRQ context;
    e.g. pins on a SOC that are controlled by chip register access.

  - Doesn't handle I2C or SPI based GPIOs.  I think we actually need
    a different API for those "message based" GPIOs, where synchronous
    get/set requires sleeping (and is thus unusable from IRQ context).
    That API could be used for "real" GPIOs; the converse is not true.

  - No IORESOURCE_GPIO resource type (could be added though).

  - Can be trivially implemented today, on many systems (see partial
    list above) ... no "provider" or gpiochip API necessary.

  - Provided in the form of a working patch, with sample implementation;
    known to be viable on multiple architectures and platforms.

  - Includes Documentation/gpio.txt

Comments?

- Dave


============================	CUT HERE
This defines a simple and minimalist convention for GPIO APIs, and an
implementation of it on one ARM platform (OMAP):

  - Documentation/gpio.txt ... describes things (read it)

  - include/asm-arm/gpio.h ... defines the ARM hook, which just punts
    to <asm/arch/gpio.h> for any implementation

  - include/asm-arm/arch-omap/gpio.h ... representative implementation
    as a wrapper around existing OMAP-specific GPIO calls

The immediate need for such a cross-architecture API convention is to support
drivers that work the same on AT91 ARM and AVR32 AP7000 chips, which embed many
of the same controllers but have different CPUs.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>


Index: osk/Documentation/gpio.txt
===================================================================
--- /dev/null	1970-01-01 00:00:00.000000000 +0000
+++ osk/Documentation/gpio.txt	2006-11-11 15:20:58.000000000 -0800
@@ -0,0 +1,233 @@
+GPIO Interfaces
+
+This provides an overview of GPIO access API conventions on Linux.
+
+
+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 many 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, and I2C-connected chips like power managers, audio codecs,
+and "GPIO Expanders" often have a few such pins to help with pin scarcity on
+SOCs.  Most PC southbridges have a few dozen GPIO-capable pins.
+
+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.
+
+  - 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.
+
+  - 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.
+
+On a given board each GPIO is used for one specific purpose like monitoring
+MMC/SD card insertion/removal, detecting card writeprotect status, driving
+a LED, configuring a transceiver, and so on.
+
+
+What are the Linux GPIO API conventions?
+========================================
+Note that this is called a "convention" because you don't need to do it this
+way, and it's no crime if you don't.  There **are** cases where portability
+is not the main issue; GPIOs are often used for the kind of board-specific
+glue logic that may even change between board revisions, and can't ever be
+used on a board that's wired differently.  Also, see the notes later on what
+these conventions omit.
+
+That said, if the convention is supported on their platform, drivers should
+probably use it when possible:
+
+	#include <asm/gpio.h>
+	
+If you stick to this convention then it'll be easier for other developers to
+see what your code is doing, and maintain it.
+
+
+Identifying GPIOs
+-----------------
+GPIOs are identified by unsigned integers in the range 0..MAX_INT.  That
+reserves "negative" numbers for other purposes like marking signals as
+"not available on this board", or indicating faults.
+
+A given platform defines how it uses those integers.  So for example one
+might not use "GPIO 0", instead using numbers 32-159.  Another platform
+could use numbers 0..63 with one set of GPIO controllers, 64-79 with a
+different type of GPIO controller, and 80-95 with an FPGA used with one
+particular board family.  GPIO numbers are not the same as IRQ numbers;
+see below for calls mapping between the two namespaces.
+
+A given platform may want to define symbols corresponding to GPIO lines,
+primarily for use in board-specific setup code. Most drivers should use
+GPIO numbers passed to them from that setup code, using platform_data to
+hold board-specific pin configuration data (along with other board
+specific data they need).
+
+
+Using GPIOs
+-----------
+One of the first things to do with a GPIO, often in board setup code when
+setting up a platform_device using the GPIO, is mark its direction:
+
+	/* set as input or output, returning 0 or negative errno */
+	int gpio_direction_input(unsigned gpio);
+	int gpio_direction_output(unsigned gpio);
+
+The return value is zero for success, else a negative errno; it must be
+checked, since the main calls don't have error returns.
+
+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
+it probably wasn't validated to do more than boot Linux.  (Similarly,
+that board setup code probably needs to multiplex that pin as a GPIO,
+and arrange pullups/pulldowns appropriately.)
+
+Driver code will then use this either as an input, or an output.  These
+calls can safely be issued from inside IRQ handlers; they don't sleep.
+
+	/* GPIO INPUT:  return zero or nonzero */
+	int gpio_get_value(unsigned gpio);
+
+	/* GPIO OUTPUT */
+	void gpio_set_value(unsigned gpio, int value);
+
+The get/set calls have no error returns because "invalid GPIO" would have
+been reported earlier in gpio_set_direction().  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.
+
+Platform-specific implementations are encouraged to optimise the two
+calls to access the GPIO value in cases where the GPIO number (and for
+output, value) are constant.  It's normal for them to need only a couple
+of instructions in such cases (reading or writing a hardware register),
+and not to need spinlocks.  Such optimized calls can make bitbanging
+applications a lot more efficient (in both space and time) than spending
+dozens of instructions on subroutine calls.
+
+
+Claiming and Releasing GPIOs (OPTIONAL)
+---------------------------------------
+To help catch system configuration errors, two calls are defined.
+However, many platforms don't currently support this mechanism.
+
+	/* request GPIO, returning 0 or negative errno.
+	 * non-null labels may be useful for diagnostics.
+	 */
+	int gpio_request(unsigned gpio, const char *label);
+
+	/* release previously-claimed GPIO */
+	void gpio_free(unsigned gpio);
+
+Passing invalid GPIO numbers to gpio_request() will fail, as will requesting
+GPIOs that have already been claimed with that call.  The return value of
+gpio_request() must be checked.
+
+These APIs 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 confusion between drivers, reporting
+errors when drivers wrongly think they have exclusive use of that signal.
+
+These two calls are optional because not not all current Linux platforms
+offer such functionality in their GPIO support; a valid implementation
+could return success for all gpio_request() calls.  Unlike the other calls,
+the state they represent doesn't normally match anything from a hardware
+register; it's just a software bitmap which clearly is not necessary for
+correct operation of hardware or (bug free) drivers.
+
+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).
+
+
+Identifying GPIO IRQs
+---------------------
+GPIO numbers are unsigned integers; so are IRQ numbers.  These make up
+two logically distinct namespaces (GPIO 0 need not use IRQ 0).  You can
+map between them using calls like:
+
+	/* map GPIO numbers to IRQ numbers */
+	int gpio_to_irq(unsigned gpio);
+
+	/* map IRQ numbers to GPIO numbers */
+	int irq_to_gpio(unsigned irq);
+
+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
+number that hasn't been marked as an input using gpio_set_direction(), or
+to use an IRQ number that didn't originally come from gpio_to_irq().
+
+These two mapping calls are expected to cost on the order of a single
+addition or subtraction.
+
+Non-error values returned from gpio_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 API, e.g. IRQF_TRIGGER_FALLING, as are system
+wakeup capabilities.
+
+Non-error values returned from irq_to_gpio() would most commonly be used
+with gpio_get_value().
+
+
+
+What do these conventions omit?
+===============================
+These conventions address least-common-denominator functionality, and
+nonportable features are left as platform-specific (but also accessible
+through <asm/gpio.h> inclusion).  Some of these may also be configuration
+dependent; the hardware may support reading or writing GPIOs in gangs,
+but only for GPIOs sharing the same bank.  (GPIOs are commonly grouped
+in banks of 16 or 32, with a given SOC having several such banks.)
+
+One of the biggest things these conventions omit is pin multiplexing, since
+this is highly chip-specific and nonportable.  One platform might not need
+explicit multiplexing; another might have just two options for use of any
+given pin; another might have eight options per pin; another might be able
+to switch a given GPIO to any of several pins.  (Yes, those examples all
+come from systems that run Linux today.)
+
+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 may use external
+pullups (or pulldowns) so that the on-chip ones should not be used.
+
+There are other system-specific mechanisms that are not specified here,
+like the aforementioned options for input de-glitching and wire-OR output,
+or ganged I/O.  Code relying on them will by definition be nonportable.
+
+GPIOs accessed through serial bus chips, like I2C GPIO expanders, are not
+supported here.  The main issue with these calls is that reading or writing
+such GPIO values can't be done from IRQ handlers.  Reading from an I2C chip
+involves sleeping to get to the head of a message queue (other chips on the
+bus may be using the controller already) and then get the response data;
+writing similarly involves sleeping.  A secondary issue is how to address
+GPIOs on those chips; globally assigned unsigned integers are not good
+choices, better ones would look like "GPIO 7 on that chip".  Managing the
+IRQs issued by such GPIOs is similarly troublesome.
+
+This API is purely for kernel space, but a userspace API could be built on
+top of it.
+
Index: osk/include/asm-arm/gpio.h
===================================================================
--- /dev/null	1970-01-01 00:00:00.000000000 +0000
+++ osk/include/asm-arm/gpio.h	2006-11-11 14:52:18.000000000 -0800
@@ -0,0 +1,7 @@
+#ifndef _ARCH_ARM_GPIO_H
+#define _ARCH_ARM_GPIO_H
+
+/* not all ARM platforms necessarily support this API ... */
+#include <asm/arch/gpio.h>
+
+#endif /* _ARCH_ARM_GPIO_H */
Index: osk/include/asm-arm/arch-omap/gpio.h
===================================================================
--- osk.orig/include/asm-arm/arch-omap/gpio.h	2006-11-11 14:52:16.000000000 -0800
+++ osk/include/asm-arm/arch-omap/gpio.h	2006-11-11 14:52:18.000000000 -0800
@@ -76,4 +76,58 @@ extern void omap_set_gpio_direction(int 
 extern void omap_set_gpio_dataout(int gpio, int enable);
 extern int omap_get_gpio_datain(int gpio);
 
+/*-------------------------------------------------------------------------*/
+
+/* wrappers for "new style" GPIO calls. the old OMAP-specfic ones should
+ * eventually be removed (along with this errno.h inclusion), and maybe
+ * gpios should put MPUIOs last too.
+ */
+
+#include <asm/errno.h>
+
+static inline int __must_check gpio_request(unsigned gpio, const char *label)
+	{ return omap_request_gpio(gpio); }
+
+static inline void gpio_free(unsigned gpio)
+	{ omap_free_gpio(gpio); }
+
+
+static inline int __must_check
+__gpio_set_direction(unsigned gpio, int is_input)
+{
+	if (cpu_class_is_omap2()) {
+		if (gpio > OMAP_MAX_GPIO_LINES)
+			return -EINVAL;
+	} else {
+		if (gpio > (OMAP_MAX_GPIO_LINES + 16 /* MPUIO */))
+			return -EINVAL;
+	}
+	omap_set_gpio_direction(gpio, is_input);
+	return 0;
+}
+
+static inline int gpio_direction_input(unsigned gpio)
+	{ return __gpio_set_direction(gpio, 1); }
+
+static inline int gpio_direction_output(unsigned gpio)
+	{ return __gpio_set_direction(gpio, 0); }
+
+
+static inline int gpio_get_value(unsigned gpio)
+	{ return omap_get_gpio_datain(gpio); }
+
+static inline void gpio_set_value(unsigned gpio, int value)
+	{ omap_set_gpio_dataout(gpio, value); }
+
+
+static inline int gpio_to_irq(unsigned gpio)
+	{ return OMAP_GPIO_IRQ(gpio); }
+
+static inline int irq_to_gpio(unsigned irq)
+{
+	if (cpu_class_is_omap1() && (irq < (IH_MPUIO_BASE + 16)))
+		return (irq - IH_MPUIO_BASE) + OMAP_MAX_GPIO_LINES;
+	return irq - IH_GPIO_BASE;
+}
+
 #endif

[patch 2.6.20-rc1 0/6] arch-neutral GPIO calls

[David Brownell]

Based on earlier discussion, I'm sending a refresh of the generic GPIO
patch, with several (ARM based) implementations in separate patches:

 - Core patch, doc + <asm-arm/gpio.h> + <asm-generic/gpio.h>
 - OMAP implementation
 - AT91 implementation
 - PXA implementation
 - SA1100 implementation
 - S3C2410 implementation

I know there's an AVR32 implementation too; and there's been interest
in this for some PPC support as well.

This time I'm proposing that at least the core patch go into the MM
tree; I think there's been enough discussion, and a general acceptance
that we need this kind of API.  Russell usually wants ARM patches to
go through his system, so those implementations above should probably
not go through MM.


With the exception of the AT91 implementation, those are all trivial
wrappers around the existing calls ... which should highlight the fact
that this API reflects existing practice, but with more generic syntax.
AT91 differed only because it needed to split out a "configure as GPIO"
primitive, not merged with the "set gpio direction" call.

Other than clarifications, the main change in the doc is defining
new calls safe for use with GPIOs on things like pcf8574 I2C gpio
expanders; those new calls can sleep, but are otherwise the same as
the spinlock-safe versions.  The implementations above implement that
as a wrapper (the asm-generic header) around the spinlock-safe calls.

This API is orthogonal to pin configuration (configure ball X17 as
GPIO 23 rather than R33, with pulldown, etc) which is in any case
highly platform-specific.

Also, as an API rather than an implementation framework, this does
not expose a notion of a "GPIO controller", of which any given
system might have several.  It's allowed by the API (e.g. see the
OMAP code), but is not required.  I expect that sort of thing will
come later; it's common enough to have SOC-based boards with GPIOs
on the SOC as well as a couple external chips.  

- Dave

Re: [patch 2.6.20-rc1 0/6] arch-neutral GPIO calls

[Håvard Skinnemoen]

On 12/20/06, David Brownell <david-b@pacbell.net> wrote:
> Based on earlier discussion, I'm sending a refresh of the generic GPIO
> patch, with several (ARM based) implementations in separate patches:
>
>  - Core patch, doc + <asm-arm/gpio.h> + <asm-generic/gpio.h>
>  - OMAP implementation
>  - AT91 implementation
>  - PXA implementation
>  - SA1100 implementation
>  - S3C2410 implementation
>
> I know there's an AVR32 implementation too; and there's been interest
> in this for some PPC support as well.

Great, thanks Dave. Unfortunately, I'm going to be more or less
offline for the rest of the year, but FWIW, the AVR32 implementation
is already in -mm as part of git-avr32.patch. I guess I should check
and see if it's in sync with the rest.

I'll refresh the atmel_spi patch when I get back to work in january.

Haavard

Re: [patch 2.6.20-rc1 0/6] arch-neutral GPIO calls

[David Brownell]

On Wednesday 20 December 2006 3:30 pm, Håvard Skinnemoen wrote:
> On 12/20/06, David Brownell <david-b@pacbell.net> wrote:
> > Based on earlier discussion, I'm sending a refresh of the generic GPIO
> > patch, with several (ARM based) implementations in separate patches:
> >
> >  - Core patch, doc + <asm-arm/gpio.h> + <asm-generic/gpio.h>
> >  - OMAP implementation
> >  - AT91 implementation
> >  - PXA implementation
> >  - SA1100 implementation
> >  - S3C2410 implementation
> >
> > I know there's an AVR32 implementation too; and there's been interest
> > in this for some PPC support as well.
> 
> Great, thanks Dave. Unfortunately, I'm going to be more or less
> offline for the rest of the year, but FWIW, the AVR32 implementation
> is already in -mm as part of git-avr32.patch.

That's appropriate; after all, as a programming interface, it's
appropriate that there be multiple implementations!  Presumably
that doc is missing, but the API calls _should_ make sense on
their own.


> I guess I should check 
> and see if it's in sync with the rest.

I'd at most expect you're missing an #include <asm-generic/gpio.h>
for the cansleep variants ... which only got added because folk
agreed such spinlock-unsafe calls were needed, not because anyone
had a pressing near-term need for them.  (Unlike the spinlock-safe
functionality, which is _very_ widely implemented.)


> I'll refresh the atmel_spi patch when I get back to work in january.

Heh, maybe I can even try it out by then.  ;)

- Dave