[riot-devel] Driver design rules in RIOT

Hauke Petersen hauke.petersen at fu-berlin.de
Wed Sep 26 10:25:50 CEST 2018

Hi everyone,

for documentation purposes a quote from a private mail that I wrote 
Gunar earlier today (at that point I was not aware of this email...):

Maybe one think that could (or even should?!) be considered: try to make 
very specialized features optional (e.g. via "sub-moduling" them). With 
this I mean thinks like e.g. event detection, interrupt mode vs. polling 
etc.). I know choosing those features is definitely not a black&white 
kind of task, but when keeping this on a coarse level I think it should 
be rather straight forward. The goal with this would be to allow people 
to use a simple (e.g. polling) driver configuration (-> low ROM/RAM 
usage), but also allow developers to chose the full fledged feature 
version of the driver, trading ROM/RAM usage against features.

As said, don't aim for a fine grained configuration (e.g. submodules for 
every small feature), but rather go with something like `USEMODULE += 
l3gd20h` for the simple polling configuration, and something like 
`USEMODULE += l3gd20h_full` for all the additional features.

To map this reply to the actual questions see inline comments below.

On 09/26/2018 09:27 AM, Gunar Schorcht wrote:
> Hi,
> I wrote a series of sensor drivers for esp-open-rtos/ESP-IDF, for
> example for different ST sensors, the BME680, the CCS811 or the SHT3x. I
> would like to port some of these drivers to RIOT OS. All the drivers are
> quite complex as they try to cover all the features of the sensors.
> I have seen that most drivers in RIOT for similar sensors usually only
> implement an interface to with init, read, power-up and power-down. So
> I'm wondering now, what the design rules for sensor drivers in RIOT are?
> - Should a driver be as complete as possible, which of cource produces
> more code, or should it be kept simple to produce small code? One option
> would be to use the pseudomodule approach to enable additional features.
> On some platforms unused code is not linked into the binary.
As always, the usage of a driver depends heavily on the application use 
case and can differ in many ways. Sometimes a simple but small driver is 
preferable (get me any simple temperature sensor, but I don't have 
RAM/ROM to spare), in other cases some specialized features of a device 
are even the key driver for selecting that specific device. In the 2nd 
case, it is surely of the essence to have a driver that supports all 
those little specials.

So as stated above: IMO having a coarse modularity inside the driver 
should be the way to go, this way we can cover both sides.
> - Should a driver support at least data-ready interrupts (if possible at
> all) to realize event-driven data retrieval?
If the driver comes with a 'full/extra' configuration, this is part of 
it anyway, right? In the simples 'basic' configuration I don't think 
this needs to be part of I would say.
> - Should a driver always return normalized/converted data, or rather
> return the raw data and the application needs to convert them? The
> conversion is sometimes quite complex. I saw both approaches of them for
> similar sensors.
My opinion is quite clear: I am always in favor of returning 
normalized/converted data. In 90% of the cases the conversion is not 
expensive, so just do it. In those rare cases, where the conversions is 
actually relatively expensive, we can always fall back by providing 
additional `xx_read_raw()` or similar functions, that allow to access 
the data before conversion.
> The design rules that are clear to me are:
> - Drivers have to provide an interface for polling with init and read
> that is compatible with SAUL.
that is a nice to have, but not a MUST.
> - Output are always 16 bit integers.
Not quite true. The SAUL interface is build around 16-bit integers, and 
at least when reading/writing data via SAUL the data needs to be 
converted. But the driver specific interface can always use other data 
types/lengths. If it is however easily possible to use int16, one should 
use it.
> What else?
All this information should go into the 'device driver guide' 
This guide needs however still work - and I will not have the time to do 
it. So it would be nice if other people can help here :-)


> Regards
> Gunar
> _______________________________________________
> devel mailing list
> devel at riot-os.org
> https://lists.riot-os.org/mailman/listinfo/devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/devel/attachments/20180926/55309612/attachment.html>

More information about the devel mailing list