emul: Introduce emulator backend API and generic sensor test

This PR introduces a backend API to be implemented by sensor emulators
that creates a standardized mechanism for setting expected sensor
readings in tests. This unlocks the ability to create a generic sensor
test that can automatically set expected values in supported sensor
emulators and verify them through the existing sensor API. An
implementation of this API is provided for the AKM09918C magnetometer.

A generic sensor test is also created to exercise this implementation.
Observe that this test knows nothing about the AKM09918C; info about
supported channels and sample ranges is discovered through the backend
API. The test iterates over all devices attached to the virtual I2C and
SPI buses in the test binary's device tree, which (theoretically) covers
all sensors. Sensors whose emulator does not exist yet or does not
support the backend API are skipped.

Signed-off-by: Tristan Honscheid <[email protected]>

Author: tristan-google

doc/hardware/peripherals/sensor.rst

@@ -228,3 +228,4 @@ API Reference
 **************
 
 .. doxygengroup:: sensor_interface
+.. doxygengroup:: sensor_emulator_backend

drivers/sensor/akm09918c/akm09918c_emul.c

@@ -7,10 +7,13 @@
 
 #include <zephyr/device.h>
 #include <zephyr/drivers/emul.h>
+#include <zephyr/drivers/emul_sensor.h>
 #include <zephyr/drivers/i2c.h>
 #include <zephyr/drivers/i2c_emul.h>
 #include <zephyr/logging/log.h>
+#include <zephyr/sys/util.h>
 
+#include "akm09918c.h"
 #include "akm09918c_emul.h"
 #include "akm09918c_reg.h"
 
@@ -130,14 +133,90 @@ static int akm09918c_emul_init(const struct emul *target, const struct device *p
 	return 0;
 }
 
+static int akm09918c_emul_backend_set_channel(const struct emul *target, enum sensor_channel ch,
+					      q31_t value, int8_t shift)
+{
+	if (!target || !target->data) {
+		return -EINVAL;
+	}
+
+	struct akm09918c_emul_data *data = target->data;
+	uint8_t reg;
+
+	switch (ch) {
+	case SENSOR_CHAN_MAGN_X:
+		reg = AKM09918C_REG_HXL;
+		break;
+	case SENSOR_CHAN_MAGN_Y:
+		reg = AKM09918C_REG_HYL;
+		break;
+	case SENSOR_CHAN_MAGN_Z:
+		reg = AKM09918C_REG_HZL;
+		break;
+	/* This function only supports setting single channels, so skip MAGN_XYZ */
+	default:
+		return -ENOTSUP;
+	}
+
+	/* Set the ST1 register to show we have data */
+	data->reg[AKM09918C_REG_ST1] |= AKM09918C_ST1_DRDY;
+
+	/* Convert fixed-point Gauss values into microgauss and then into its bit representation */
+	int32_t microgauss = (shift < 0 ? ((int64_t)value >> -shift) : ((int64_t)value << shift)) *
+			     1000000 / ((int64_t)INT32_MAX + 1);
+
+	int16_t reg_val =
+		CLAMP(microgauss, AKM09918C_MAGN_MIN_MICRO_GAUSS, AKM09918C_MAGN_MAX_MICRO_GAUSS) /
+		AKM09918C_MICRO_GAUSS_PER_BIT;
+
+	/* Insert reading into registers */
+	data->reg[reg] = reg_val & 0xFF;
+	data->reg[reg + 1] = (reg_val >> 8) & 0xFF;
+
+	return 0;
+}
+
+static int akm09918c_emul_backend_get_sample_range(const struct emul *target,
+						   enum sensor_channel ch, q31_t *lower,
+						   q31_t *upper, q31_t *epsilon, int8_t *shift)
+{
+	ARG_UNUSED(target);
+
+	if (!lower || !upper || !epsilon || !shift) {
+		return -EINVAL;
+	}
+
+	switch (ch) {
+	case SENSOR_CHAN_MAGN_X:
+	case SENSOR_CHAN_MAGN_Y:
+	case SENSOR_CHAN_MAGN_Z:
+		/* +/- 49.12 Gs is the measurement range. 0.0015 Gs is the granularity */
+		*shift = 6;
+		*upper = (int64_t)(49.12 * ((int64_t)INT32_MAX + 1)) >> *shift;
+		*lower = -*upper;
+		*epsilon = (int64_t)(0.0015 * ((int64_t)INT32_MAX + 1)) >> *shift;
+		break;
+	default:
+		return -ENOTSUP;
+	}
+
+	return 0;
+}
+
 static const struct i2c_emul_api akm09918c_emul_api_i2c = {
 	.transfer = akm09918c_emul_transfer_i2c,
 };
 
+static const struct emul_sensor_backend_api akm09918c_emul_sensor_backend_api = {
+	.set_channel = akm09918c_emul_backend_set_channel,
+	.get_sample_range = akm09918c_emul_backend_get_sample_range,
+};
+
 #define AKM09918C_EMUL(n)                                                                          \
 	const struct akm09918c_emul_cfg akm09918c_emul_cfg_##n;                                    \
 	struct akm09918c_emul_data akm09918c_emul_data_##n;                                        \
 	EMUL_DT_INST_DEFINE(n, akm09918c_emul_init, &akm09918c_emul_data_##n,                      \
-			    &akm09918c_emul_cfg_##n, &akm09918c_emul_api_i2c, NULL)
+			    &akm09918c_emul_cfg_##n, &akm09918c_emul_api_i2c,                      \
+			    &akm09918c_emul_sensor_backend_api)
 
 DT_INST_FOREACH_STATUS_OKAY(AKM09918C_EMUL)

include/zephyr/drivers/emul_sensor.h

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/drivers/emul.h>
+#include <zephyr/drivers/sensor.h>
+
+#include <stdint.h>
+
+/**
+ * @brief Sensor emulator backend API
+ * @defgroup sensor_emulator_backend Sensor emulator backend API
+ * @ingroup io_interfaces
+ * @{
+ */
+
+/**
+ * @cond INTERNAL_HIDDEN
+ *
+ * These are for internal use only, so skip these in public documentation.
+ */
+
+/**
+ * @brief Collection of function pointers implementing a common backend API for sensor emulators
+ */
+__subsystem struct emul_sensor_backend_api {
+	/** Sets a given fractional value for a given sensor channel. */
+	int (*set_channel)(const struct emul *target, enum sensor_channel ch, q31_t value,
+			   int8_t shift);
+	/** Retrieve a range of sensor values to use with test. */
+	int (*get_sample_range)(const struct emul *target, enum sensor_channel ch, q31_t *lower,
+				q31_t *upper, q31_t *epsilon, int8_t *shift);
+};
+/**
+ * @endcond
+ */
+
+/**
+ * @brief Check if a given sensor emulator supports the backend API
+ *
+ * @param target Pointer to emulator instance to query
+ *
+ * @return True if supported, false if unsupported or if \p target is NULL.
+ */
+static inline bool emul_sensor_backend_is_supported(const struct emul *target)
+{
+	return target && target->backend_api;
+}
+
+/**
+ * @brief Set an expected value for a given channel on a given sensor emulator
+ *
+ * @param target Pointer to emulator instance to operate on
+ * @param ch Sensor channel to set expected value for
+ * @param value Expected value in fixed-point format using standard SI unit for sensor type
+ * @param shift Shift value (scaling factor) applied to \p value
+ *
+ * @return 0 if successful
+ * @return -ENOTSUP if no backend API or if channel not supported by emul
+ * @return -ERANGE if provided value is not in the sensor's supported range
+ */
+static inline int emul_sensor_backend_set_channel(const struct emul *target, enum sensor_channel ch,
+						  q31_t value, int8_t shift)
+{
+	if (!target || !target->backend_api) {
+		return -ENOTSUP;
+	}
+
+	struct emul_sensor_backend_api *api = (struct emul_sensor_backend_api *)target->backend_api;
+
+	if (api->set_channel) {
+		return api->set_channel(target, ch, value, shift);
+	}
+	return -ENOTSUP;
+}
+
+/**
+ * @brief Query an emulator for a channel's supported sample value range and tolerance
+ *
+ * @param target Pointer to emulator instance to operate on
+ * @param ch The channel to request info for. If \p ch is unsupported, return `-ENOTSUP`
+ * @param[out] lower Minimum supported sample value in SI units, fixed-point format
+ * @param[out] upper Maximum supported sample value in SI units, fixed-point format
+ * @param[out] epsilon Tolerance to use comparing expected and actual values to account for rounding
+ *             and sensor precision issues. This can usually be set to the minimum sample value step
+ *             size. Uses SI units and fixed-point format.
+ * @param[out] shift The shift value (scaling factor) associated with \p lower, \p upper, and
+ *             \p epsilon.
+ *
+ * @return 0 if successful
+ * @return -ENOTSUP if no backend API or if channel not supported by emul
+ *
+ */
+static inline int emul_sensor_backend_get_sample_range(const struct emul *target,
+						       enum sensor_channel ch, q31_t *lower,
+						       q31_t *upper, q31_t *epsilon, int8_t *shift)
+{
+	if (!target || !target->backend_api) {
+		return -ENOTSUP;
+	}
+
+	struct emul_sensor_backend_api *api = (struct emul_sensor_backend_api *)target->backend_api;
+
+	if (api->get_sample_range) {
+		return api->get_sample_range(target, ch, lower, upper, epsilon, shift);
+	}
+	return -ENOTSUP;
+}
+
+/**
+ * @}
+ */

tests/drivers/build_all/sensor/CMakeLists.txt

@@ -4,5 +4,6 @@ cmake_minimum_required(VERSION 3.20.0)
 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
 project(build_all)
 
-FILE(GLOB app_sources src/*.c)
-target_sources(app PRIVATE ${app_sources})
+# Exclude main when running the generic test because ztest supplies its own
+target_sources_ifndef(CONFIG_GENERIC_SENSOR_TEST app PRIVATE src/main.c)
+target_sources_ifdef(CONFIG_GENERIC_SENSOR_TEST app PRIVATE src/generic_test.c)

tests/drivers/build_all/sensor/Kconfig

@@ -0,0 +1,24 @@
+# Copyright (c) 2023 Google LLC
+# SPDX-License-Identifier: Apache-2.0
+
+config GENERIC_SENSOR_TEST
+	bool "Compile and run the generic sensor tests"
+	depends on ZTEST && ZTEST_NEW_API
+	help
+	  Enables building and running the generic sensor test suite that will
+	  iterate through the device tree and run sample path tests on any
+	  sensor that supports the backend sensor emulator API.
+
+config GENERIC_SENSOR_TEST_NUM_EXPECTED_VALS
+	int "Number of expected values to use in test"
+	default 5
+	depends on GENERIC_SENSOR_TEST
+	help
+	  Controls the number of expected values to use in the generic sensor
+	  test, interpolated from the sensor's reported lower and upper sample
+	  range boundaries. The test will run one iteration for each expected
+	  value. For example, if GENERIC_TEST_NUM_EXPECTED_VALS == 5, and the
+	  sensor range is 0..100, the test will run 5 times with expected values
+	  0, 25, 50, 75, and 100. These iterations are run in parallel.
+
+source "Kconfig.zephyr"