Driver Headers

[Brennan Ashton <ba...@brennanashton.com>]

I am a little confused by what should be stored in the header files
for drivers in these two locations and I do not want to further any
existing mistakes:

include/nuttx/<subsystem>/<driver>.h
and
drivers/<subsystem/<driver.h>

To mean it seems it should be organized like this:

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.


Currently there are lots of examples of both and it also seems odd to
me that the header used for the internal board interfaces is also used
by user space applications.  So maybe I am very off base here.

--Brennan

Re: Driver Headers

[Gregory Nutt <sp...@gmail.com>]

>>
>>> 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

I think only the arch/ hardware definitions handle this is a 
satisfactory way, with two separate, public header files:  One for the 
hardware definition and one for driver interface.

Re: Driver Headers

[Gregory Nutt <sp...@gmail.com>]

>
>> 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

Re: Driver Headers

[Gregory Nutt <sp...@gmail.com>]

> 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.