Zephyr drivers

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:

• https://docs.zephyrproject.org/4.3.0/doxygen/html/group__io__interfaces.html

Zephyr 4.3.0 sensor model:

• https://docs.zephyrproject.org/4.3.0/doxygen/html/group__sensor__interface.html

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

• https://docs.zephyrproject.org/4.3.0/doxygen/html/group__sensor__interface.html#gaedfdfc71dce702dc1fb1c6e60ff0f73a

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 _

• https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/drivers/sensor.h#L65

_ Sensor attribute enum _

• https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/drivers/sensor.h#L342

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 = {                     \

^ References

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

- - - top of page - - -