On Wed, Sep 4, 2013 at 1:29 PM, Alexandre Courbot [off-list ref] wrote:

+The GPIO framework has quite a bit of history behind it. Currently there exist
+two different (although very similar) ways of using GPIOs:
+
+  - The legacy integer-based interface represents GPIOs as integers. This is
+    the "historic" way of accessing GPIOs and it was done so because it makes
+    GPIOs easy to represent and also allows for the compiler to statically know
+    the GPIO number and use fast-paths on GPIOs for which performance matters.
+    However, GPIOs can easily be forged this way, and the maximum number of
+    GPIOs in the system must be known in advance. Functions of this interface
+    are prefixed with "gpio_".
+
+  - The new descriptor-based interface represents GPIOs as an opaque pointer.
+    This ensures GPIOs are properly acquired before usage, and also does not
+    presume anything about their underlying implementation. This interface
+    provides get/put functions to acquire GPIOs according to their function for
+    a particular device, similarly to e.g. the regulator framework. For these
+    reasons, it is the preferred way to access GPIOs. Its functions are prefixed
+    with "gpiod_".

I would put all the new style gpiod_* based things on top of the file, and
all the old stuff under a separate heading below DEPRECATED LEGACY INTERFACE
so it's crystal clear that this is going away.

Yours,
Linus Walleij