Difference between revisions of "Zephyr drivers"

From Wiki at Neela Nurseries
Jump to navigation Jump to search
m (→‎^ Zephyr logging: - note need for LOG_MODULE_REGISTER() macro in one project source, LOG_MODULE_DECLARE() in other sources which log info.)
m (Add section q Sensor Bus API and Sensor Bus q)
 
(44 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
<i><b>Keywords:</b>  sensor interrupts : sensor triggers : Zephyr triggers : sensor interrupt support</i>
  
−
== [[#top|^]] OVERVIEW ==
+
OVERVIEW
  
−
2022 Q4 notes on Zephyr RTOS drivers, driver frameworks and driver design.  Current projects include work to extend KX132-1211 Zephyr out-of-tree driver, plus work to craft an IIS2DH driver which supports in Zephyr RTOS context both I2C and SPI bus connections for this sensor.
+
This page a stash point to hold Zephyr driver notes.  Zephyr RTOS project includes a range of types of drivers.  First type referenced by this page will be Zephyr's sensor drivers.
  
−
<!-- comentario -->
+
== [[#top|^]] Zephyr Sensor Model ==
  
−
== [[#top|^]] Example Zephyr drivers ==
+
Zephyr 4.3.0 device driver documentation:
  
−
Example apps here offer varying amounts of insight into Zephyr RTOS' framework(s) for device driver development. Of particular interest 2022 Q4 are the ways in which developers use Zephyr device tree macros to obtain pointers to devices, in their mostly C based code, at compile time.  Though not fully explained in Zephyr's extensive documentation it appears that device pointers which can be correctly passed to and used with API function [https://docs.zephyrproject.org/latest/kernel/drivers/index.html#c.device_is_ready device_is_ready()] and macro [https://docs.zephyrproject.org/latest/kernel/drivers/index.html#c.DEVICE_DT_GET DEVICE_DT_GET()] involve pairings of macros, which must be expanded prior to these calls in order to compile correctly.
+
* https://docs.zephyrproject.org/4.3.0/doxygen/html/group__io__interfaces.html
  
−
*  https://github.com/circuitdojo/pcf85063a
+
Zephyr 4.3.0 sensor model:
  
−
*  https://docs.zephyrproject.org/latest/services/smf/index.html
+
*  https://docs.zephyrproject.org/4.3.0/doxygen/html/group__sensor__interface.html
  
−
* https://github.com/zephyrproject-rtos/zephyr/tree/main/samples/drivers/spi_bitbang
+
"Sensor attribute get" function prototype. This prototype reveals Zephyr's enumerations for sensor yyy . . .
  
−
*  https://github.com/zephyrproject-rtos/zephyr/tree/main/samples/drivers/uart/stm32/single_wire
+
*  https://docs.zephyrproject.org/4.3.0/doxygen/html/group__sensor__interface.html#gaedfdfc71dce702dc1fb1c6e60ff0f73a
−
ted@localhost1:~/projects-sandbox/workspace-out-of-tree/zephyr$ grep -nr init_res ./* | grep -v reset | grep init_res
 
−
./include/zephyr/device.h:416: unsigned int init_res : 8;
 
−
./include/zephyr/net/dns_resolve.h:459:void dns_init_resolver(void);
 
−
./include/zephyr/net/dns_resolve.h:462:#define dns_init_resolver(...)
 
−
./kernel/device.c:84: dev->state->init_res = rc;
 
−
./kernel/device.c:161: return dev->state->initialized && (dev->state->init_res == 0U);
 
−
./subsys/net/ip/net_core.c:476: dns_init_resolver();
 
−
./subsys/net/lib/dns/resolve.c:1428:void dns_init_resolver(void)
 
−
What's going on in LM77 temperature sensor Kconfig file, on line 10?  Interesting Kconfig stanza contains $(dt_compat_enabled,lm77):
 
  
−
* https://github.com/zephyrproject-rtos/zephyr/blob/main/drivers/sensor/lm77/Kconfig#L10
+
Zephyr's sensor model plays a big role in the design of sensor drivers for this RTOS. Zephyr's [... sensor.h] header defines many things.  Two important enums from this header file are:
  
 +
_ Sensor channel enum _
  
−
Zephyr sensor API routine `device_is_ready()` is prototyped in [https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/device.h#L710 zephyr/include/zephyr/device.h].  A search for `device_is_ready()` implementation gives:
+
*  https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/drivers/sensor.h#L65
  
−
<pre>
+
_ Sensor attribute enum _
−
ted@localhost1:~/projects-sandbox/workspace-out-of-tree/zephyr$ grep -nr z_device_is_ready ./*
 
−
./include/zephyr/device.h:782:bool z_device_is_ready(const struct device *dev);
 
−
./include/zephyr/device.h:803: return z_device_is_ready(dev);
 
−
./kernel/device.c:108: if (z_device_is_ready(dev) && (dev->name == name)) {
 
−
./kernel/device.c:114: if (z_device_is_ready(dev) && (strcmp(name, dev->name) == 0)) {
 
−
./kernel/device.c:151:bool z_device_is_ready(const struct device *dev)
 
−
</pre>
 
  
−
The body of this API routine is:
+
*  https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/drivers/sensor.h#L342
−
<pre>
 
−
bool z_device_is_ready(const struct device *dev)
 
−
{
 
−
        /*
 
−
        * if an invalid device pointer is passed as argument, this call
 
−
        * reports the `device` as not ready for usage.
 
−
        */
 
−
        if (dev == NULL) {
 
−
                return false;
 
−
        }
 
  
−
        return dev->state->initialized && (dev->state->init_res == 0U);
+
Sensor channels generally correspond to readings of a quantity in specific units, like degrees centigrade and acceleration in the x-axis.  Sensor attributes generally corrrespond to configuration settings for a sensor, where these settings modify the way in which readings are taken and reported.
−
}
 
−
</pre>
 
  
−
Having some trouble, however, finding places where `init_res` and `initialized` data members of device state structure get initialized.  Looked recursively in both modules and zephyr source tree.  Looks like there may be one place where this assignment takes place, in `zephyr/kernel/device.c`:
+
For a Zephyr driver to support configuration of a sensor's attributes, it must implement a function of the form:
  
 
<pre>
 
<pre>
−
ted@localhost1:~/projects-sandbox/workspace-out-of-tree/zephyr$ grep -nr init_res ./* | grep -v reset | grep init_res
+
sensor_attr_set()
−
./include/zephyr/device.h:416: unsigned int init_res : 8;
+
int sensor_attr_set(const struct device* dev,
−
./include/zephyr/net/dns_resolve.h:459:void dns_init_resolver(void);
+
                enum sensor_channel chan,
−
./include/zephyr/net/dns_resolve.h:462:#define dns_init_resolver(...)
+
                enum sensor_attribute attr,
−
./kernel/device.c:84: dev->state->init_res = rc;
+
                const struct sensor_value* val)
−
./kernel/device.c:161: return dev->state->initialized && (dev->state->init_res == 0U);
 
−
./subsys/net/ip/net_core.c:476: dns_init_resolver();
 
−
./subsys/net/lib/dns/resolve.c:1428:void dns_init_resolver(void)
 
 
</pre>
 
</pre>
  
−
Routine which iterates over and initializes all devices needing initialization prior to app code starting:
+
. . . whose typedef is at https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/drivers/sensor.h#L431.
 +
 
 +
== [[#top|^]] Bosch BMI323 Driver Example ==
  
−
<pre>
+
The Bosch BMI323 accelerometer magnetometer combined sensor has a driver in Zephyr 4.3.0. This driver implements its sensor attribute setter function in bmi323.c in two places. The first place is a sensor API struct which the driver declares. This API struct organizes the public API function of the driver. These APIs implement and honor each a function signature that's type defined in Zephyr's sensor.h header file.
−
  54 void z_sys_init_run_level(int32_t level)
 
−
55 {
 
−
  56        static const struct init_entry *levels[] = {
 
−
57                __init_PRE_KERNEL_1_start,
 
−
58                __init_PRE_KERNEL_2_start,
 
−
59                __init_POST_KERNEL_start,
 
−
60                __init_APPLICATION_start,
 
−
61 #ifdef CONFIG_SMP
 
−
62                __init_SMP_start,
 
−
63 #endif
 
−
64                /* End marker */
 
−
65                __init_end,
 
−
66        };
 
−
  67        const struct init_entry *entry;
 
−
68
 
−
69        for (entry = levels[level]; entry < levels[level+1]; entry++) {
 
−
70                const struct device *dev = entry->dev;
 
−
71                int rc = entry->init(dev);
 
−
72
 
−
  73                if (dev != NULL) {
 
−
74                        /* Mark device initialized. If initialization
 
−
75                          * failed, record the error condition.
 
−
76                          */
 
−
77                        if (rc != 0) {
 
−
78                                if (rc < 0) {
 
−
79                                        rc = -rc;
 
−
80                                }
 
−
81                                if (rc > UINT8_MAX) {
 
−
82                                        rc = UINT8_MAX;
 
−
83                                }
 
−
84                                dev->state->init_res = rc;
 
−
85                        }
 
−
86                        dev->state->initialized = true;
 
−
87                }
 
−
88        }
 
−
89 }
 
−
</pre>
 
  
−
Sensor init priority:
+
The structure is defined starting at about line 384, bmi323.c:384:
  
 
<pre>
 
<pre>
−
ted@localhost1:~/projects-sandbox/workspace-for-nexus/zephyr$ grep -nr SENSOR_INIT_PRIORITY ./* | grep -v CONFIG_SENSOR | grep SENSOR_INIT_PRIORITY
+
static DEVICE_API(sensor, bosch_bmi323_api) = {
−
./boards/arm/thingy52_nrf52832/board.c:33:#error BOARD_CCS_VDD_PWR_CTRL_INIT_PRIORITY must be lower than SENSOR_INIT_PRIORITY
+
        .attr_set = bosch_bmi323_driver_api_attr_set,        <-- attribute setter
−
./boards/arm/thingy52_nrf52832/Kconfig:15:   BOARD_VDD_PWR_CTRL_INIT_PRIORITY, but smaller than SENSOR_INIT_PRIORITY.
+
        .attr_get = bosch_bmi323_driver_api_attr_get,
−
./drivers/sensor/Kconfig:17:config SENSOR_INIT_PRIORITY
+
        .trigger_set = bosch_bmi323_driver_api_trigger_set,
 +
        .sample_fetch = bosch_bmi323_driver_api_sample_fetch,
 +
        .channel_get = bosch_bmi323_driver_api_channel_get,
 +
};
 
</pre>
 
</pre>
  
−
 
+
The attribute setter function is defined at about line 1101, bmi323.c:1101:
−
<!-- comentario -->
 
−
 
 
−
== [[#top|^]] Zephyr Kernel Level Device Support ==
 
−
 
 
−
Interesting code excerpt from `zephy/kernel/device.c`, this following routine is the implementation behind a wrapper like function `device_is_read()`.  But this routine, and sensibly so, doesn't say anything about how a given device is initialized. It only looks at two data members of a device instance data structure:
 
  
 
<pre>
 
<pre>
−
150
+
static int bosch_bmi323_driver_api_attr_set(const struct device *dev,
−
151 bool z_device_is_ready(const struct device *dev)
+
    enum sensor_channel chan,
−
152 {
+
    enum sensor_attribute attr,
−
153        /*
+
    const struct sensor_value *val)
−
154          * if an invalid device pointer is passed as argument, this call
+
{
−
155          * reports the `device` as not ready for usage.
+
struct bosch_bmi323_data *data = (struct bosch_bmi323_data *)dev->data;
−
156          */
+
int ret;
−
157        if (dev == NULL) {
 
−
158                return false;
 
−
159        }
 
−
160
 
−
161        return dev->state->initialized && (dev->state->init_res == 0U);
 
−
162 }
 
−
163
 
−
</pre>
 
  
−
On a somewhat unrelated note, a couple of important Zephyr documents, including Zephyr device tree macros used to obtain node identifiers:
+
k_mutex_lock(&data->lock, K_FOREVER);
  
−
*  https://docs.zephyrproject.org/latest/build/dts/api-usage.html#node-identifiers
+
switch (chan) {
 +
case SENSOR_CHAN_ACCEL_XYZ:
 +
switch (attr) {
 +
case SENSOR_ATTR_SAMPLING_FREQUENCY:
 +
ret = bosch_bmi323_driver_api_set_acc_odr(dev, val);
  
−
*  https://docs.zephyrproject.org/latest/build/dts/dt-vs-kconfig.html  Device Tree versus Kconfig, a fairly short read
+
break;
  
−
*  https://docs.zephyrproject.org/1.14.0/guides/kconfig/index.html
+
case SENSOR_ATTR_FULL_SCALE:
 +
ret = bosch_bmi323_driver_api_set_acc_full_scale(dev, val);
  
 +
break;
  
−
<!-- comentario -->
+
case SENSOR_ATTR_FEATURE_MASK:
 +
ret = bosch_bmi323_driver_api_set_acc_feature_mask(dev, val);
  
−
== [[#top|^]] Understanding Zephyr SPI API ==
+
break;
  
−
To make use of Zephyr API for SPI bus, we must in part understand how each of the three parameters passed to [https://docs.zephyrproject.org/latest/hardware/peripherals/spi.html#c.spi_read spi_read()] and [https://docs.zephyrproject.org/latest/hardware/peripherals/spi.html#c.spi_write spi_write()] are defined.  Further, when we have a sensor with which we communicate in our Zephyr based app we need to understand how parts of this sensor's data structures in the firmware relate to the SPI bus to which the sensor is connected.  Our sensor driver's code which talks with the sensor via SPI must pass certain SPI bus related pointers to Zephyr's SPI Application Programmers' Interface.
+
default:
 +
ret = -ENODEV;
  
−
Another important SPI defining resource in Zephyr RTOS is the header file [https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/drivers/spi.h#L379 spi.h#L379].  This file defines the small data structure named `spi_dt_spec`.  It gives us the data member names for a SPI bus peripheral, as Zephyr sees them.
+
break;
 +
}
  
−
2022-11-25
+
break;
  
−
The best Zephyr SPI instructions we find so far are in the sample app `spi_bitbang`.  The source file main.c there, sets up RX and TX buffers, and some Zephyr driver structures about these.  There is an interesting design pattern in Zephyr's SPI API: receive and transmit buffer pairs can be made multiple, in two arrays of these same buffers.  The SPI interface function `spi_tranceive()`, about which spi_write() and spi_read() wrap, steps through the count of write buffers and receive buffers it is passed from calling code.  In this way, a careful choosing of sets of buffers permits app developers to express more complex SPI communications by defining the buffers with needed lengths, and then call the SPI API of Zephyr RTOS just once.
+
case SENSOR_CHAN_GYRO_XYZ:
 +
switch (attr) {
 +
case SENSOR_ATTR_SAMPLING_FREQUENCY:
 +
ret = bosch_bmi323_driver_api_set_gyro_odr(dev, val);
  
−
<!-- comentario -->
+
break;
  
−
== [[#top|^]] Zephyr logging ==
+
case SENSOR_ATTR_FULL_SCALE:
 +
ret = bosch_bmi323_driver_api_set_gyro_full_scale(dev, val);
  
−
Note, in a Zephyr project or an out-of-tree driver, what we have learned here is that LOG_MODULE_REGISTER(project_name) must be called in one -- possibly the first -- of the project's source files.  Any other dot c files from which developers need logging capability must include the function like macro LOG_MODULE_DECLARE().
+
break;
  
−
*  https://docs.zephyrproject.org/3.0.0/reference/logging/index.html#logging-in-a-module
+
case SENSOR_ATTR_FEATURE_MASK:
−
*  https://docs.zephyrproject.org/3.0.0/reference/logging/index.html#c.LOG_MODULE_DECLARE
+
ret = bosch_bmi323_driver_api_set_gyro_feature_mask(dev, val);
  
 +
break;
  
−
<!-- comentario -->
+
default:
 +
ret = -ENODEV;
  
−
== [[#top|^]] LPC55S69 flexcomm2 and hs_lspi pins conflict ==
+
break;
 +
}
  
−
zephyr/boards/arm/lpcxpresso55s69/lpcxpresso55s69-pinctrl.dtsi lines 21 - 28
+
break;
  
−
Note that in spite of the comment above in the dot dtsi file from NXP, SPI communications with an IIS2DH sensor work while UART2 is also in use and working - TMH
+
default:
 +
ret = -ENODEV;
  
−
<!-- comentario -->
+
break;
 +
}
  
−
== [[#top|^]] STMicro device context data structure ==
+
k_mutex_unlock(&data->lock);
  
−
Symbol `stmdev_ctx_t` is defined in file <b>modules/hal/st/sensor/stmemsc/iis2dh_STdC/driver/iis2dh_reg.c</b>.  On github this file as of 2022-11-18 located at https://github.com/zephyrproject-rtos/hal_st/tree/master/sensor/stmemsc/iis2dh_STdC/driver'
+
return ret;
−
 
+
}
−
Data structure `stmdev_ctx_t` defined as follows:
 
−
 
 
−
<pre>
 
−
104 /** @addtogroup  Interfaces_Functions
 
−
105  * @brief      This section provide a set of functions used to read and
 
−
106  *              write a generic register of the device.
 
−
107  *              MANDATORY: return 0 -> no Error.
 
−
108  * @{
 
−
109  *
 
−
110  */
 
−
111
 
−
112 typedef int32_t (*stmdev_write_ptr)(void *, uint8_t, const uint8_t *, uint16_t);
 
−
113 typedef int32_t (*stmdev_read_ptr)(void *, uint8_t, uint8_t *, uint16_t);
 
−
114
 
−
115 typedef struct
 
−
116 {
 
−
117  /** Component mandatory fields **/
 
−
118  stmdev_write_ptr  write_reg;
 
−
119  stmdev_read_ptr  read_reg;
 
−
120  /** Customizable optional pointer **/
 
−
121  void *handle;
 
−
122 } stmdev_ctx_t;
 
 
</pre>
 
</pre>
  
−
Parameter lists for the register write and register read functions are nearly the same, with exception of the third parameter.  In the register write function this parameter is qualified with C `const`, as it is only expected to be read by the function using it.
+
== [[#top|^]] Mutex Use in BMI323 Driver ==
  
 +
BMI323 driver code locks a mutex in the following routines of bmi323.c:
  
 +
1.  line 384: static int bosch_bmi323_driver_api_attr_set(...)
  
−
With the above definition, an instance of stmdev_cts_t is created for each device with device tree compatible property of 'st_iis2dh', and is assigned in `zephyr/drivers/sensor/iis2dh/iis2dh-i2c.c` as follows:
+
2. line 727: static int bosch_bmi323_driver_api_attr_get(...)
−
 
 
−
<pre>
 
−
38 stmdev_ctx_t iis2dh_i2c_ctx = {
 
−
39        .read_reg = (stmdev_read_ptr) iis2dh_i2c_read,
 
−
40        .write_reg = (stmdev_write_ptr) iis2dh_i2c_write,
 
−
41 };
 
−
42
 
−
43 int iis2dh_i2c_init(const struct device *dev)
 
−
44 {
 
−
45        struct iis2dh_data *data = dev->data;
 
−
46        const struct iis2dh_device_config *config = dev->config;
 
−
47
 
−
48        if (!device_is_ready(config->i2c.bus)) {
 
−
49                LOG_ERR("Bus device is not ready");
 
−
50                return -ENODEV;
 
−
51        }
 
−
52
 
−
53        data->ctx = &iis2dh_i2c_ctx;
 
−
54        data->ctx->handle = (void *)dev;
 
−
55
 
−
56        return 0;
 
−
57 }
 
−
58 #endif /* DT_ANY_INST_ON_BUS_STATUS_OKAY(i2c) */
 
−
</pre>
 
−
 
 
−
The above init function is called from iis2dh.c:
 
  
−
<pre>
+
3.  line 843: static int bosch_bmi323_driver_api_trigger_set(...)
−
232 static int iis2dh_init_interface(const struct device *dev)
 
−
233 {
 
−
234        int res;
 
−
235
 
−
236 #if DT_ANY_INST_ON_BUS_STATUS_OKAY(spi)
 
−
237        res = iis2dh_spi_init(dev);
 
−
238        if (res) {
 
−
239                return res;
 
−
240        }
 
−
241 #elif DT_ANY_INST_ON_BUS_STATUS_OKAY(i2c)
 
−
242        res = iis2dh_i2c_init(dev);
 
−
243        if (res) {
 
−
244                return res;
 
−
245        }
 
−
246 #else
 
−
247 #error "BUS MACRO NOT DEFINED IN DTS"
 
−
248 #endif
 
−
249
 
−
250        return 0;
 
−
251 }
 
−
252
 
−
253 static int iis2dh_init(const struct device *dev)
 
−
254 {
 
−
255        struct iis2dh_data *iis2dh = dev->data;
 
−
256        const struct iis2dh_device_config *cfg = dev->config;
 
−
257        uint8_t wai;
 
−
258
 
−
259        if (iis2dh_init_interface(dev)) {
 
−
260                return -EINVAL;
 
−
261        }
 
  
−
</pre>
+
4.  line 996: static int bosch_bmi323_driver_api_sample_fetch(const struct device *dev, enum sensor_channel chan)
  
 +
5. line 1047: static int bosch_bmi323_driver_api_channel_get(...)
  
 +
6. line 1150: static void bosch_bmi323_irq_callback_handler(...)
 +
       
 +
7. line 1241: static int bosch_bmi323_pm_action(...)
  
−
Pointer *dev has a member named 'data', which in turn has a member named 'ctx', which in turn gets assigned the address of a not named instance of `iis2dh_i2c_ctx`.  This means that we have `dev->data->ctx->read_reg()` and `dev->data->ctx->write_reg` on successful completion of routine iis2dh_i2c_init().  This is reflected in <b>modules/hal/st/sensor/stmemsc/iis2dh_STdC/driver/iis2dh_reg.c</b>, in the two generalized register read and write functions:
+
== [[#top|^]] BMI323 Driver Routines ==
  
 
<pre>
 
<pre>
−
  39 /**
+
59:static int bosch_bmi323_bus_init(const struct device *dev)
−
  40  * @brief  Read generic device register
+
68:static int bosch_bmi323_bus_read_words(const struct device *dev, uint8_t offset, uint16_t *words,
−
  41  *
+
78:static int bosch_bmi323_bus_write_words(const struct device *dev, uint8_t offset, uint16_t *words,
−
  42  * @param  ctx  read / write interface definitions(ptr)
+
88:static int32_t bosch_bmi323_lsb_from_fullscale(int64_t fullscale)
−
  43  * @param  reg  register to read
+
94:static int64_t bosch_bmi323_value_to_micro(int16_t value, int32_t lsb)
−
  44  * @param  data  pointer to buffer that store the data read(ptr)
+
100:static void bosch_bmi323_value_to_sensor_value(struct sensor_value *result, int16_t value,
−
  45  * @param  len  number of consecutive register to read
+
111:static bool bosch_bmi323_value_is_valid(int16_t value)
−
  46  * @retval          interface status (MANDATORY: return 0 -> no Error)
+
116:static int bosch_bmi323_validate_chip_id(const struct device *dev)
−
  47  *
+
134:static int bosch_bmi323_soft_reset(const struct device *dev)
−
  48  */
+
152:static int bosch_bmi323_enable_feature_engine(const struct device *dev)
−
  49 int32_t iis2dh_read_reg(stmdev_ctx_t *ctx, uint8_t reg, uint8_t *data,
+
178:static int bosch_bmi323_driver_api_set_acc_odr(const struct device *dev,
−
  50                        uint16_t len)
+
226:static int bosch_bmi323_driver_api_set_acc_full_scale(const struct device *dev,
−
  51 {
+
257:static int bosch_bmi323_driver_api_set_acc_feature_mask(const struct device *dev,
−
  52  int32_t ret;
+
280:static int bosch_bmi323_driver_api_set_gyro_odr(const struct device *dev,
−
  53
+
328:static int bosch_bmi323_driver_api_set_gyro_full_scale(const struct device *dev,
−
  54  ret = ctx->read_reg(ctx->handle, reg, data, len);
+
361:static int bosch_bmi323_driver_api_set_gyro_feature_mask(const struct device *dev,
−
  55
+
384:static int bosch_bmi323_driver_api_attr_set(const struct device *dev, enum sensor_channel chan,
−
  56  return ret;
+
455:static int bosch_bmi323_driver_api_get_acc_odr(const struct device *dev, struct sensor_value *val)
−
  57 }
+
530:static int bosch_bmi323_driver_api_get_acc_full_scale(const struct device *dev,
−
  58
+
566:static int bosch_bmi323_driver_api_get_acc_feature_mask(const struct device *dev,
−
  59 /**
+
589:static int bosch_bmi323_driver_api_get_gyro_odr(const struct device *dev, struct sensor_value *val)
−
  60  * @brief  Write generic device register
+
664:static int bosch_bmi323_driver_api_get_gyro_full_scale(const struct device *dev,
−
  61  *
+
704:static int bosch_bmi323_driver_api_get_gyro_feature_mask(const struct device *dev,
−
  62  * @param  ctx  read / write interface definitions(ptr)
+
727:static int bosch_bmi323_driver_api_attr_get(const struct device *dev, enum sensor_channel chan,
−
  63  * @param  reg  register to write
+
796:static int bosch_bmi323_driver_api_trigger_set_acc_drdy(const struct device *dev)
−
  64  * @param  data  pointer to data to write in register reg(ptr)
+
806:static int bosch_bmi323_driver_api_trigger_set_acc_motion(const struct device *dev)
−
  65  * @param  len  number of consecutive register to write
+
843:static int bosch_bmi323_driver_api_trigger_set(const struct device *dev,
−
  66  * @retval          interface status (MANDATORY: return 0 -> no Error)
+
883:static int bosch_bmi323_driver_api_fetch_acc_samples(const struct device *dev)
−
  67  *
+
925:static int bosch_bmi323_driver_api_fetch_gyro_samples(const struct device *dev)
−
  68  */
+
968:static int bosch_bmi323_driver_api_fetch_temperature(const struct device *dev)
−
  69 int32_t iis2dh_write_reg(stmdev_ctx_t *ctx, uint8_t reg,
+
996:static int bosch_bmi323_driver_api_sample_fetch(const struct device *dev, enum sensor_channel chan)
−
  70                          uint8_t *data,
+
1047:static int bosch_bmi323_driver_api_channel_get(const struct device *dev, enum sensor_channel chan,
−
  71                          uint16_t len)
+
1100:static DEVICE_API(sensor, bosch_bmi323_api) = {
−
  72 {
+
1108:static void bosch_bmi323_irq_callback(const struct device *dev)
−
  73  int32_t ret;
+
1115:static int bosch_bmi323_init_irq(const struct device *dev)
−
  74
+
1139:static int bosch_bmi323_init_int1(const struct device *dev)
−
  75  ret = ctx->write_reg(ctx->handle, reg, data, len);
+
1150:static void bosch_bmi323_irq_callback_handler(struct k_work *item)
−
  76
+
1164:static int bosch_bmi323_pm_resume(const struct device *dev)
−
  77  return ret;
+
1225:static int bosch_bmi323_pm_suspend(const struct device *dev)
−
  78 }
+
1241:static int bosch_bmi323_pm_action(const struct device *dev, enum pm_device_action action)
 +
1271:static int bosch_bmi323_init(const struct device *dev)
 +
1318: static struct bosch_bmi323_data bosch_bmi323_data_##inst;                                 \
 +
1322: static void bosch_bmi323_irq_callback##inst(const struct device *dev,                      \
 +
1328: static const struct bosch_bmi323_config bosch_bmi323_config_##inst = {                    \
 
</pre>
 
</pre>
  
−
 
+
== [[#top|^]] Sensor Bus API and Sensor Bus ==
−
. . .
 
−
 
 
−
 
 
−
 
 
−
https://docs.zephyrproject.org/latest/hardware/peripherals/i2c.html#c.i2c_burst_read_dt
 
−
 
 
−
 
 
−
 
 
−
<!-- comentario -->
 
−
 
 
−
== [[#top|^]] Zephyr interrupt set up code ==
 
−
 
 
−
Some pages from Zephyr 3.2.0 documentation . . .
 
−
 
 
−
*  https://docs.zephyrproject.org/latest/hardware/peripherals/sensor.html#triggers
 
−
*  https://docs.zephyrproject.org/latest/hardware/peripherals/sensor.html#c.sensor_trigger_type
 
−
 
 
−
In Zephyr RTOS context, triggers are interrupts which are generated by sensors.  Zephyr constructs a notion of "trigger types" and "trigger channels".
 
−
 
 
−
 
 
−
Zephyr interrupt set up code from button sample app . . .
 
  
 
<pre>
 
<pre>
−
      MODULE_ID__THREAD_IIS2DH, sensor->state->init_res);
+
178 struct bosch_bmi323_bus_api {
−
 
+
179        /* Read up to multiple words from the BMI323 */
−
 
+
180         int (*read_words)(const void *context, uint8_t offset, uint16_t *words,
−
 
+
181                          uint16_t words_count);
−
// 'button' from samples/basic/button becomes 'interrupt_line_1':
+
182
−
 
+
183         /* Write up to multiple words to the BLI323 */
−
// STEP config step
+
184         int (*write_words)(const void *context, uint8_t offset, uint16_t *words,
−
         if (!device_is_ready(interrupt_line_1.port)) {
+
185                            uint16_t words_count);
−
                printk("Error: sensor interrupt 1 port '%s' detected as not ready\n",
+
186
−
                      interrupt_line_1.port->name);
+
187         /* Initialize the bus */
−
//                return;
+
188         int (*init)(const void *context);
−
         }
+
189 };
−
 
+
190
−
// STEP config step
+
191 struct bosch_bmi323_bus {
−
         rstatus = gpio_pin_configure_dt(&interrupt_line_1, GPIO_INPUT);
+
192        const void *context;
−
        if (rstatus != 0) {
+
193        const struct bosch_bmi323_bus_api *api;
−
                printk("Error %d: failed to configure %s pin %d\n",
+
194 };
−
                      rstatus, interrupt_line_1.port->name, interrupt_line_1.pin);
+
</pre>
−
//                return;
 
−
         }
 
−
 
 
−
// STEP config step
 
−
         rstatus = gpio_pin_interrupt_configure_dt(&interrupt_line_1,
 
−
                                              GPIO_INT_EDGE_TO_ACTIVE);
 
−
        if (rstatus != 0) {
 
−
                printk("Error %d: failed to configure interrupt on %s pin %d\n",
 
−
                        rstatus, interrupt_line_1.port->name, interrupt_line_1.pin);
 
−
//                return;
 
−
        }
 
−
 
 
−
// STEP config step
 
−
//        gpio_init_callback(&button_cb_data, button_pressed, BIT(button.pin));
 
−
//        gpio_add_callback(button.port, &button_cb_data);
 
−
//        printk("Set up button at %s pin %d\n", button.port->name, button.pin);
 
  
−
        gpio_init_callback(&sensor_interrupt_1_cb_data, sensor_interrupt_1_cb, BIT(interrupt_line_1.pin));
+
== [[#top|^]] References ==
−
        gpio_add_callback(interrupt_line_1.port, &sensor_interrupt_1_cb_data);
 
−
        printk("Set up button at %s pin %d\n", interrupt_line_1.port->name, interrupt_line_1.pin);
 
  
−
</pre>
+
<span id="ref--zephyr-interrupts--zephyr-s-issues-s-30133"></span>
 +
1.  https://github.com/zephyrproject-rtos/zephyr/issues/30133
  
 
<!-- comentario -->
 
<!-- comentario -->
  
−
== [[#top|^]] C Preprocessor macros ==
 
−
 
−
*  https://stackoverflow.com/questions/1489932/how-can-i-concatenate-twice-with-the-c-preprocessor-and-expand-a-macro-as-in-ar
 
−
 
−
<!-- comentario -->
 
  
−
== [[#top|^]] Sensors to seek for Zephyr demo exercising ==
+
<center>
 +
[[#top|- - - top of page - - -]]
 +
</center>
  
−
[ ]  [https://www.adafruit.com/product/1782 MCP9808] I2C based temperature sensor, [https://www.mouser.com/datasheet/2/268/25095A-15487.pdf datasheet], long lead times at Mouser
 
  
 
<!-- comentario -->
 
<!-- comentario -->

Latest revision as of 04:58, 22 February 2026

Keywords: sensor interrupts : sensor triggers : Zephyr triggers : sensor interrupt support

OVERVIEW

This page a stash point to hold Zephyr driver notes. Zephyr RTOS project includes a range of types of drivers. First type referenced by this page will be Zephyr's sensor drivers.

^ Zephyr Sensor Model

Zephyr 4.3.0 device driver documentation:

Zephyr 4.3.0 sensor model:

"Sensor attribute get" function prototype. This prototype reveals Zephyr's enumerations for sensor yyy . . .

Zephyr's sensor model plays a big role in the design of sensor drivers for this RTOS. Zephyr's [... sensor.h] header defines many things. Two important enums from this header file are:

_ Sensor channel enum _

_ Sensor attribute enum _

Sensor channels generally correspond to readings of a quantity in specific units, like degrees centigrade and acceleration in the x-axis. Sensor attributes generally corrrespond to configuration settings for a sensor, where these settings modify the way in which readings are taken and reported.

For a Zephyr driver to support configuration of a sensor's attributes, it must implement a function of the form: 

sensor_attr_set()
int sensor_attr_set(const struct device* dev,
                enum sensor_channel chan,
                enum sensor_attribute attr,
                const struct sensor_value* val)

. . . whose typedef is at https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/drivers/sensor.h#L431.

^ Bosch BMI323 Driver Example

The Bosch BMI323 accelerometer magnetometer combined sensor has a driver in Zephyr 4.3.0. This driver implements its sensor attribute setter function in bmi323.c in two places. The first place is a sensor API struct which the driver declares. This API struct organizes the public API function of the driver. These APIs implement and honor each a function signature that's type defined in Zephyr's sensor.h header file.

The structure is defined starting at about line 384, bmi323.c:384: 

static DEVICE_API(sensor, bosch_bmi323_api) = {
        .attr_set = bosch_bmi323_driver_api_attr_set,        <-- attribute setter
        .attr_get = bosch_bmi323_driver_api_attr_get,
        .trigger_set = bosch_bmi323_driver_api_trigger_set,
        .sample_fetch = bosch_bmi323_driver_api_sample_fetch,
        .channel_get = bosch_bmi323_driver_api_channel_get,
};

The attribute setter function is defined at about line 1101, bmi323.c:1101: 

static int bosch_bmi323_driver_api_attr_set(const struct device *dev,
					    enum sensor_channel chan,
					    enum sensor_attribute attr,
					    const struct sensor_value *val)
{
	struct bosch_bmi323_data *data = (struct bosch_bmi323_data *)dev->data;
	int ret;

	k_mutex_lock(&data->lock, K_FOREVER);

	switch (chan) {
	case SENSOR_CHAN_ACCEL_XYZ:
		switch (attr) {
		case SENSOR_ATTR_SAMPLING_FREQUENCY:
			ret = bosch_bmi323_driver_api_set_acc_odr(dev, val);

			break;

		case SENSOR_ATTR_FULL_SCALE:
			ret = bosch_bmi323_driver_api_set_acc_full_scale(dev, val);

			break;

		case SENSOR_ATTR_FEATURE_MASK:
			ret = bosch_bmi323_driver_api_set_acc_feature_mask(dev, val);

			break;

		default:
			ret = -ENODEV;

			break;
		}

		break;

	case SENSOR_CHAN_GYRO_XYZ:
		switch (attr) {
		case SENSOR_ATTR_SAMPLING_FREQUENCY:
			ret = bosch_bmi323_driver_api_set_gyro_odr(dev, val);

			break;

		case SENSOR_ATTR_FULL_SCALE:
			ret = bosch_bmi323_driver_api_set_gyro_full_scale(dev, val);

			break;

		case SENSOR_ATTR_FEATURE_MASK:
			ret = bosch_bmi323_driver_api_set_gyro_feature_mask(dev, val);

			break;

		default:
			ret = -ENODEV;

			break;
		}

		break;

	default:
		ret = -ENODEV;

		break;
	}

	k_mutex_unlock(&data->lock);

	return ret;
}

^ Mutex Use in BMI323 Driver

BMI323 driver code locks a mutex in the following routines of bmi323.c:

1. line 384: static int bosch_bmi323_driver_api_attr_set(...)

2. line 727: static int bosch_bmi323_driver_api_attr_get(...)

3. line 843: static int bosch_bmi323_driver_api_trigger_set(...)

4. line 996: static int bosch_bmi323_driver_api_sample_fetch(const struct device *dev, enum sensor_channel chan)

5. line 1047: static int bosch_bmi323_driver_api_channel_get(...)

6. line 1150: static void bosch_bmi323_irq_callback_handler(...)

7. line 1241: static int bosch_bmi323_pm_action(...)

^ BMI323 Driver Routines

59:static int bosch_bmi323_bus_init(const struct device *dev)
68:static int bosch_bmi323_bus_read_words(const struct device *dev, uint8_t offset, uint16_t *words,
78:static int bosch_bmi323_bus_write_words(const struct device *dev, uint8_t offset, uint16_t *words,
88:static int32_t bosch_bmi323_lsb_from_fullscale(int64_t fullscale)
94:static int64_t bosch_bmi323_value_to_micro(int16_t value, int32_t lsb)
100:static void bosch_bmi323_value_to_sensor_value(struct sensor_value *result, int16_t value,
111:static bool bosch_bmi323_value_is_valid(int16_t value)
116:static int bosch_bmi323_validate_chip_id(const struct device *dev)
134:static int bosch_bmi323_soft_reset(const struct device *dev)
152:static int bosch_bmi323_enable_feature_engine(const struct device *dev)
178:static int bosch_bmi323_driver_api_set_acc_odr(const struct device *dev,
226:static int bosch_bmi323_driver_api_set_acc_full_scale(const struct device *dev,
257:static int bosch_bmi323_driver_api_set_acc_feature_mask(const struct device *dev,
280:static int bosch_bmi323_driver_api_set_gyro_odr(const struct device *dev,
328:static int bosch_bmi323_driver_api_set_gyro_full_scale(const struct device *dev,
361:static int bosch_bmi323_driver_api_set_gyro_feature_mask(const struct device *dev,
384:static int bosch_bmi323_driver_api_attr_set(const struct device *dev, enum sensor_channel chan,
455:static int bosch_bmi323_driver_api_get_acc_odr(const struct device *dev, struct sensor_value *val)
530:static int bosch_bmi323_driver_api_get_acc_full_scale(const struct device *dev,
566:static int bosch_bmi323_driver_api_get_acc_feature_mask(const struct device *dev,
589:static int bosch_bmi323_driver_api_get_gyro_odr(const struct device *dev, struct sensor_value *val)
664:static int bosch_bmi323_driver_api_get_gyro_full_scale(const struct device *dev,
704:static int bosch_bmi323_driver_api_get_gyro_feature_mask(const struct device *dev,
727:static int bosch_bmi323_driver_api_attr_get(const struct device *dev, enum sensor_channel chan,
796:static int bosch_bmi323_driver_api_trigger_set_acc_drdy(const struct device *dev)
806:static int bosch_bmi323_driver_api_trigger_set_acc_motion(const struct device *dev)
843:static int bosch_bmi323_driver_api_trigger_set(const struct device *dev,
883:static int bosch_bmi323_driver_api_fetch_acc_samples(const struct device *dev)
925:static int bosch_bmi323_driver_api_fetch_gyro_samples(const struct device *dev)
968:static int bosch_bmi323_driver_api_fetch_temperature(const struct device *dev)
996:static int bosch_bmi323_driver_api_sample_fetch(const struct device *dev, enum sensor_channel chan)
1047:static int bosch_bmi323_driver_api_channel_get(const struct device *dev, enum sensor_channel chan,
1100:static DEVICE_API(sensor, bosch_bmi323_api) = {
1108:static void bosch_bmi323_irq_callback(const struct device *dev)
1115:static int bosch_bmi323_init_irq(const struct device *dev)
1139:static int bosch_bmi323_init_int1(const struct device *dev)
1150:static void bosch_bmi323_irq_callback_handler(struct k_work *item)
1164:static int bosch_bmi323_pm_resume(const struct device *dev)
1225:static int bosch_bmi323_pm_suspend(const struct device *dev)
1241:static int bosch_bmi323_pm_action(const struct device *dev, enum pm_device_action action)
1271:static int bosch_bmi323_init(const struct device *dev)
1318:	static struct bosch_bmi323_data bosch_bmi323_data_##inst;                                  \
1322:	static void bosch_bmi323_irq_callback##inst(const struct device *dev,                      \
1328:	static const struct bosch_bmi323_config bosch_bmi323_config_##inst = {                     \

^ Sensor Bus API and Sensor Bus

178 struct bosch_bmi323_bus_api {
179         /* Read up to multiple words from the BMI323 */
180         int (*read_words)(const void *context, uint8_t offset, uint16_t *words,
181                           uint16_t words_count);
182 
183         /* Write up to multiple words to the BLI323 */
184         int (*write_words)(const void *context, uint8_t offset, uint16_t *words,
185                            uint16_t words_count);
186 
187         /* Initialize the bus */
188         int (*init)(const void *context);
189 };
190 
191 struct bosch_bmi323_bus {
192         const void *context;
193         const struct bosch_bmi323_bus_api *api;
194 };

^ References

1. https://github.com/zephyrproject-rtos/zephyr/issues/30133


- - - top of page - - -


Retrieved from "https://wiki.neelanurseries.com/index.php?title=Zephyr_drivers&oldid=8884"