Explanation of <asm/gpio.h> in Doc/gpio.txt seems out of date

[Robert P. J. Day]

   (the first in probably a number of questions related to digging  
around in embedded linux-related code -- i know there's an  
embedded-linux list, if that's a better forum, i'll move stuff there.)

   currently writing an intro to GPIO for my new EL course, and ran  
across this in doc file gpio.txt:

"Platforms must declare GENERIC_GPIO support in their Kconfig (boolean  
true), and provide an <asm/gpio.h> file. Drivers that can't work  
without standard GPIO calls should have Kconfig entries which depend  
on GENERIC_GPIO.  The GPIO calls are available, either as "real code"  
or as optimized-away stubs, when drivers use the include file:

        #include <linux/gpio.h>"

   hang on ... that explanation might have been true at one time, but  
consider this snippet from <linux/gpio.h>:

... snip ...
#ifdef CONFIG_GENERIC_GPIO

#ifdef CONFIG_ARCH_HAVE_CUSTOM_GPIO_H
#include <asm/gpio.h>
#else

#include <asm-generic/gpio.h>
... snip ...

   the above clearly suggests that you need provide an <asm/gpio.h>  
only if you've explicitly selected that you have a custom gpio.h file,  
and that Kconfig directive is defined thusly in drivers/gpio/Kconfig:

config ARCH_HAVE_CUSTOM_GPIO_H
         bool
         help
           Selecting this config option from the architecture Kconfig allows
           the architecture to provide a custom asm/gpio.h implementation
           overriding the default implementations.  New uses of this are
           strongly discouraged.

so, if i read this correctly, you *don't* need to supply your own  
<asm/gpio.h> except under exceptional circumstances which, these days,  
is strongly discouraged, does that sound right?

   further, there are numerous kernel source files that explicitly have:

#include <asm/gpio.h>

when it would *seem* that the cleaner approach would be to simply:

#include <linux/gpio.h>

and set the Kconfig variable ARCH_HAVE_CUSTOM_GPIO_H, no? it just  
seems that the Doc/gpio.txt file could stand a bit of tweaking to be  
brought up to date.

rday