On Tuesday 01 May 2012 09:34:29 Will Deacon wrote:
> On Sat, Apr 28, 2012 at 12:26:11AM +0100, Mike Frysinger wrote:
> > i am strongly in favor though of agreeing on & documenting the baseline
> > API first before attempting to clean anything up.  sorry to keep harping
> > on this.
> 
> It would be nice if we could just use asm-generic/io.h as the documention,
> i.e. if you want to write a portable driver, just stick to the functions
> implemented there.

we have Documentation/DocBook/deviceiobook.tmpl where we can document what 
should be used in device drivers for portability, and what should be avoided.  
then we can refer to asm-generic/io.h for just the API level stuff (i.e. 
inputs/outputs/return values).

then we update asm-generic/io.h to:
 - refer device driver authors to deviceiobook for the higher level 
documentation
 - explicitly state that the API here is the baseline and any new functions 
should be discussed first on linux-arch/lkml
 - explicitly state what API functions have been omitted, and what should be 
used instead of those

how's that sound as a plan ?

> It would be nice if we could just use asm-generic/io.h as the documention,
> i.e. if you want to write a portable driver, just stick to the functions
> implemented there. Apart from the string accessors, I think it's already
> fairly accurate. The __raw_* functions seem to be missing on s390 but I
> don't think driver portability is a huge concern for that architecture.

as long as we document expectations at the top of the file, that's fine.  this 
implicit assumption doesn't fly in general for asm-generic/ because it's been a 
constantly increasing code base as it merges more arches.  there were a bunch 
of files/apis i extended in asm-generic/ as i converted Blackfin over to it.  
this is what we wanted from the beginning (afaik; i'm sure Arnd can correct 
me).
-mike