<commit_before>Writing a Device Driver in RIOT                                 {#driver-guide}
===============================

This document describes the requirement, design objectives, and some
non-function details when writing device drivers in/for RIOT. The term device
driver in this context includes all 'CPU-external' devices connected to the CPU
typically via peripherals like SPI, I2C, UART, GPIO, and similar. CPU
peripherals itself are in RIOT not considered to be device drivers, but
peripheral or low-level drivers. Typical devices are network devices like
radios, Ethernet adapters, sensors, and actuators.

[TOC]

# General Design Objectives                   {#driver-guide-design-objectives}

Device drivers should be as easy to use as possible. This implies an
'initialize->ready' paradigm, meaning, that device drivers should be ready to use
and in operation right after they have been initialized. On top, devices should
work with physical values wherever possible. So e.g. sensors should return
already converted values in some physical unit instead of RAW data, so that
users can work directly with data from different devices directly without having
to care about device specific conversion.

Additionally towards ease of use, all device drivers in RIOT should provide a
similar 'look and feel'. They should behave similar concerning things like their
state after initialization, like their used data representation and so on.

Secondly, all device drivers should be optimized for minimal RAM/ROM usage, as
RIOT targets (very) constrained devices. This implies, that instead of exposing
all thinkable functionality, the drivers should focus on exporting and
implementing a device's core functionality, thus covering ~95% of the use cases.
Furthermore great care should be put into ...(?)

Third, it should always be possible, to handle more than a single device of one
kind. Drivers and their interfaces are thus designed to keep their state
information in a parameterized location instead of driver defined global
variables.

Fourth, RIOT defines high-level interfaces for certain groups of devices (i.e.
netdev for network devices, SAUL for sensors and actuators), which enable users
to work with a wide variety of devices without having to know anything about the
actual device that is mapped.

Fifth, during initialization we make sure that we can communicate with a device.
Other functions should check the dev pointer is not void, and should also handle
error return values from the lower layer peripheral driver implementations,
where there are some.

Sixth, device drivers SHOULD be implemented independent of any CPU/board code.<commit_msg>doc/driver-guide.md: add a note about float<commit_after>Writing a Device Driver in RIOT                                 {#driver-guide}
===============================

This document describes the requirement, design objectives, and some
non-function details when writing device drivers in/for RIOT. The term device
driver in this context includes all 'CPU-external' devices connected to the CPU
typically via peripherals like SPI, I2C, UART, GPIO, and similar. CPU
peripherals itself are in RIOT not considered to be device drivers, but
peripheral or low-level drivers. Typical devices are network devices like
radios, Ethernet adapters, sensors, and actuators.

[TOC]

# General Design Objectives                   {#driver-guide-design-objectives}

Device drivers should be as easy to use as possible. This implies an
'initialize->ready' paradigm, meaning, that device drivers should be ready to use
and in operation right after they have been initialized. On top, devices should
work with physical values wherever possible. So e.g. sensors should return
already converted values in some physical unit instead of RAW data, so that
users can work directly with data from different devices directly without having
to care about device specific conversion.

However, please avoid the use of `float` or `double`. Instead, multiply to the
next SI (or appropriate) unit. E.g. if an ADC would return values like `1.23 V`,
chose to return `1230 mV` instead.

Additionally towards ease of use, all device drivers in RIOT should provide a
similar 'look and feel'. They should behave similar concerning things like their
state after initialization, like their used data representation and so on.

Secondly, all device drivers should be optimized for minimal RAM/ROM usage, as
RIOT targets (very) constrained devices. This implies, that instead of exposing
all thinkable functionality, the drivers should focus on exporting and
implementing a device's core functionality, thus covering ~95% of the use cases.
Furthermore great care should be put into ...(?)

Third, it should always be possible, to handle more than a single device of one
kind. Drivers and their interfaces are thus designed to keep their state
information in a parameterized location instead of driver defined global
variables.

Fourth, RIOT defines high-level interfaces for certain groups of devices (i.e.
netdev for network devices, SAUL for sensors and actuators), which enable users
to work with a wide variety of devices without having to know anything about the
actual device that is mapped.

Fifth, during initialization we make sure that we can communicate with a device.
Other functions should check the dev pointer is not void, and should also handle
error return values from the lower layer peripheral driver implementations,
where there are some.

Sixth, device drivers SHOULD be implemented independent of any CPU/board code.
{'fraction_non_alphanumeric': 0.04971284996410624, 'fraction_numerical': 0.002333094041636755, 'mean_word_length': 4.496055226824458, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5301191', 'n_tokens_mistral': 1316, 'n_tokens_neox': 1224, 'n_words': 804}