blob: 30345cc6a0bc227bd97c1147b28ee55574dc25b2 [file] [log] [blame]
/*
* Copyright (c) 2023 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
#include <zephyr/drivers/emul.h>
#include <zephyr/drivers/sensor.h>
#include <zephyr/drivers/sensor_attribute_types.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, const 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);
/** Set the attribute value(s) of a given chanel. */
int (*set_attribute)(const struct emul *target, enum sensor_channel ch,
enum sensor_attribute attribute, const void *value);
/** Get metadata about an attribute. */
int (*get_attribute_metadata)(const struct emul *target, enum sensor_channel ch,
enum sensor_attribute attribute, q31_t *min, q31_t *max,
q31_t *increment, 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,
const 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;
}
/**
* @brief Set the emulator's attribute values
*
* @param[in] target Pointer to emulator instance to operate on
* @param[in] ch The channel to request info for. If \p ch is unsupported, return `-ENOTSUP`
* @param[in] attribute The attribute to set
* @param[in] value the value to use (cast according to the channel/attribute pair)
* @return 0 is successful
* @return < 0 on error
*/
static inline int emul_sensor_backend_set_attribute(const struct emul *target,
enum sensor_channel ch,
enum sensor_attribute attribute,
const void *value)
{
if (!target || !target->backend_api) {
return -ENOTSUP;
}
struct emul_sensor_backend_api *api = (struct emul_sensor_backend_api *)target->backend_api;
if (api->set_attribute == NULL) {
return -ENOTSUP;
}
return api->set_attribute(target, ch, attribute, value);
}
/**
* @brief Get metadata about an attribute.
*
* Information provided by this function includes the minimum/maximum values of the attribute as
* well as the increment (value per LSB) which can be used as an epsilon when comparing results.
*
* @param[in] target Pointer to emulator instance to operate on
* @param[in] ch The channel to request info for. If \p ch is unsupported, return '-ENOTSUP'
* @param[in] attribute The attribute to request info for. If \p attribute is unsupported, return
* '-ENOTSUP'
* @param[out] min The minimum value the attribute can be set to
* @param[out] max The maximum value the attribute can be set to
* @param[out] increment The value that the attribute increses by for every LSB
* @param[out] shift The shift for \p min, \p max, and \p increment
* @return 0 on SUCCESS
* @return < 0 on error
*/
static inline int emul_sensor_backend_get_attribute_metadata(const struct emul *target,
enum sensor_channel ch,
enum sensor_attribute attribute,
q31_t *min, q31_t *max,
q31_t *increment, 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_attribute_metadata == NULL) {
return -ENOTSUP;
}
return api->get_attribute_metadata(target, ch, attribute, min, max, increment, shift);
}
/**
* @}
*/