drivers/<subsystem/<driver.h>
should be holding internal to the driver interfaces, such register
definitions, low level communication interfaces readreg, writereg,
etc... that might be shared across implementations.
include/nuttx/<subsystem>/<driver>.h
should hold the interfaces/types required to interact with the driver,
registration, initialization, callbacks, etc... that are expected to
be used by the board integration. As well as things like IOCTL and
types used by userspace.
That seems reasonable. I have also always kept standard definitions
form the device specification in include/nuttx/<subsystem>/<driver>.h
since these are a part of the public description of the hardware and
not part of the arbitrary driver design. Certainly there is not
architectural reason to obfuscate the standard specified hardware
interface. But I also understand you could argue as you have done here.
So for me:
drivers/<subsystem/<driver.h>:
Internal driver design that should not be exposed outside of the
driver. Otherwise the arbitrary design could be incorporated into
some external logic introducing a nasty coupling.
The device description from the specification is NOT part of the
internal design (and can introduce no coupling).
include/nuttx/<subsystem>/<driver>.h:
(1) everything that external logic needs to interface with the design,
plus (2) all of the standard definitions from device specification
that are totally independent of the driver design.
All driver that I have written are done this way.
I can see how you can argue either way.
But networking is handled the same way: include/nuttx/net/<protocol>.h
provides all protocol define definitions from the RFC. AND it includes
the required interface information to use the protocol. Isn't that the
same?
But that is not done consistently. Most of the spec definitions fro FAT
are in fs/fat/, not include/nuttx/fs/fat.h
