[riot-devel] Driver design rules in RIOT

Gunar Schorcht gunar at schorcht.net
Wed Sep 26 14:23:09 CEST 2018

Hi Juan,

thank you for your very comprehensive answer, which gives another view
on the use of drivers from a developer who is obviously interested in
very accurate results :-)

Obviously, there are two different groups of application developers that
should be supported by a driver interface:

1. Application developers who just want to retrieve sensor data as easy
as possible without any special requirements for accuracy and without
having detailed knowledge about the sensor, for example the temperature
in tenths of degree Celsius.

2. Application developers with deep knowledge about the sensor, the
physics and data processing, who want to get raw data from sensor with
best accuracy to process them in the application or to use them
directly, for example in control applications.

Even though you are right, that a driver in general should realize only
the access to the the device, the conversion from raw data is quite
complex for some sensors and requires deep knowledge of the sensor and
its data sheet. Therefore, there are good reasons why a driver should
hide the complexity of processing raw data and provide converted data.

If each sensor driver provides the two functions "read" and "read_raw"
both groups of application developers are be satisfied. The "read"
function calls "read_raw" implicitly. If the "read" function is not
used, it doesn't produce processing overhead.

The parameters of "read_raw" function should of course correspond to the
data format of raw data.


On 26.09.2018 12:16, Juan Ignacio Carrano wrote:
> Hi Gunar,
> I'm not very experienced on the driver development side, but enough as a 
> user to see some issues.
> On 9/26/18 9:27 AM, Gunar Schorcht wrote:
>> - 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.
> Part of keeping it small is omitting conversion code (see answer below).
> How often does it happen that one runs out of flash space? I'm asking 
> because I honestly don't know. I do know that it's probably easier for 
> the user to remove stuff if he runs out of flash than to read the device 
> manual and add the missing functions if the driver is incomplete.
>> On some platforms unused code is not linked into the binary.
> Unused functions, where the linker can determine the function is not 
> used. If you have a big function for configuring device modes, but you 
> never call it with certain parameters and a bit chunk goes unused, it 
> may not be optimized away (I'm not sure if LTO changes this).
>> - Should a driver support at least data-ready interrupts (if possible at
>> all) to realize event-driven data retrieval?
> Yes. Totally yes. Polling is dumb:
> * Goes against low power goals.
> * The data is not polled with a clock that is synchronized with the 
> sensor clock (if the sensor has an ADC), meaning unpredictable jitter.
>> - 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.
> RAW data.
> * Conversion usually results in loss of precision, especially if one 
> limits the word length to something like 16 bits (see answer below).
> * Doing conversion "right" (in an unbiased way) is non trivial. You 
> cannot just go around truncating digits.
> * Is is beyond the scope of the driver, which should handle device 
> communication/configurations only.
> * If the converted value is not needed, the conversion cannot be undone.
> * In SAUL, conversion to and from the base-10 floating point format used 
> is really painful.
> I think the measurement should be raw, and there should be a way to 
> query the conversion constant. This way the user can choose, and there 
> are not unnecessary computations done.
> In control applications, for example, the conversion is totally not 
> necessary, as the conversion constants can be folded into the control 
> system constants.
>> 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.
> Yes. It makes all interfaces consistent. That being said, it is sad that 
> there is no unified way for configuring and for interrupt driven 
> measurements.
>> - Output are always 16 bit integers.
> I think it is a bad idea to limit output to 16 bits. ADCs meant for 
> scales, for example, usually have 24 bit [1]. Other applications also 
> demand higher that 16 bits. Keep in mind that 16 bits is equivalent to 
> 4,8 decimal digits, take 1 bit for the sign and you are left with 4,5.
> [1] http://www.analog.com/en/products/ad7799.html
>> What else?
> Maybe off topic, but I think we need a IO layer (think SAUL, but more 
> complete) so that the user does not have to directly interact with 
> drivers. I would answer many of your questions, as in that case there 
> would be a well defined interface that device drivers would have to 
> expose. It is an OS, after all.
> Regards,
> Juan I Carrano.
> _______________________________________________
> devel mailing list
> devel at riot-os.org
> https://lists.riot-os.org/mailman/listinfo/devel

Wenn du laufen willst, lauf eine Meile. Wenn du ein neues Leben
kennenlernen willst, dann lauf Marathon. (Emil Zatopek)

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://lists.riot-os.org/pipermail/devel/attachments/20180926/b66f6f91/attachment.sig>

More information about the devel mailing list