/* * Copyright (c) 2020 Nordic Semiconductor ASA * Copyright 2020 Google LLC * * SPDX-License-Identifier: Apache-2.0 */ #ifndef ZEPHYR_INCLUDE_DRIVERS_EMUL_H_ #define ZEPHYR_INCLUDE_DRIVERS_EMUL_H_ /** * @brief Emulators used to test drivers and higher-level code that uses them * @defgroup io_emulators Emulator interface * @ingroup testing * @{ */ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ struct emul; /* #includes required after forward-declaration of struct emul later defined in this header. */ #include #include #include #include #include #include #include /** * The types of supported buses. */ enum emul_bus_type { EMUL_BUS_TYPE_I2C, EMUL_BUS_TYPE_ESPI, EMUL_BUS_TYPE_SPI, EMUL_BUS_TYPE_MSPI, EMUL_BUS_TYPE_NONE, }; /** * Structure uniquely identifying a device to be emulated */ struct emul_link_for_bus { const struct device *dev; }; /** List of emulators attached to a bus */ struct emul_list_for_bus { /** Identifiers for children of the node */ const struct emul_link_for_bus *children; /** Number of children of the node */ unsigned int num_children; }; /** * Standard callback for emulator initialisation providing the initialiser * record and the device that calls the emulator functions. * * @param emul Emulator to init * @param parent Parent device that is using the emulator */ typedef int (*emul_init_t)(const struct emul *emul, const struct device *parent); /** * Emulator API stub when an emulator is not actually placed on a bus. */ struct no_bus_emul { void *api; uint16_t addr; }; /** An emulator instance - represents the *target* emulated device/peripheral that is * interacted with through an emulated bus. Instances of emulated bus nodes (e.g. i2c_emul) * and emulators (i.e. struct emul) are exactly 1..1 */ struct emul { /** function used to initialise the emulator state */ emul_init_t init; /** handle to the device for which this provides low-level emulation */ const struct device *dev; /** Emulator-specific configuration data */ const void *cfg; /** Emulator-specific data */ void *data; /** The bus type that the emulator is attached to */ enum emul_bus_type bus_type; /** Pointer to the emulated bus node */ union bus { struct i2c_emul *i2c; struct espi_emul *espi; struct spi_emul *spi; struct mspi_emul *mspi; struct no_bus_emul *none; } bus; /** Address of the API structure exposed by the emulator instance */ const void *backend_api; }; /** * @brief Use the devicetree node identifier as a unique name. * * @param node_id A devicetree node identifier */ #define EMUL_DT_NAME_GET(node_id) _CONCAT(__emulreg_, node_id) /* Get a unique identifier based on the given _dev_node_id's reg property and * the bus its on. Intended for use in other internal macros when declaring {bus}_emul * structs in peripheral emulators. */ #define Z_EMUL_REG_BUS_IDENTIFIER(_dev_node_id) (_CONCAT(_CONCAT(__emulreg_, _dev_node_id), _bus)) /* Conditionally places text based on what bus _dev_node_id is on. */ #define Z_EMUL_BUS(_dev_node_id, _i2c, _espi, _spi, _mspi, _none) \ COND_CODE_1(DT_ON_BUS(_dev_node_id, i2c), (_i2c), \ (COND_CODE_1(DT_ON_BUS(_dev_node_id, espi), (_espi), \ (COND_CODE_1(DT_ON_BUS(_dev_node_id, spi), (_spi), \ (COND_CODE_1(DT_ON_BUS(_dev_node_id, mspi), (_mspi), \ (_none)))))))) /** * @brief Define a new emulator * * This adds a new struct emul to the linker list of emulations. This is * typically used in your emulator's DT_INST_FOREACH_STATUS_OKAY() clause. * * @param node_id Node ID of the driver to emulate (e.g. DT_DRV_INST(n)); the node_id *MUST* have a * corresponding DEVICE_DT_DEFINE(). * @param init_fn function to call to initialise the emulator (see emul_init typedef) * @param data_ptr emulator-specific data * @param cfg_ptr emulator-specific configuration data * @param bus_api emulator-specific bus api * @param _backend_api emulator-specific backend api */ #define EMUL_DT_DEFINE(node_id, init_fn, data_ptr, cfg_ptr, bus_api, _backend_api) \ static struct Z_EMUL_BUS(node_id, i2c_emul, espi_emul, spi_emul, mspi_emul, no_bus_emul) \ Z_EMUL_REG_BUS_IDENTIFIER(node_id) = { \ .api = bus_api, \ .Z_EMUL_BUS(node_id, addr, chipsel, chipsel, dev_idx, addr) = \ DT_REG_ADDR(node_id), \ }; \ const STRUCT_SECTION_ITERABLE(emul, EMUL_DT_NAME_GET(node_id)) __used = { \ .init = (init_fn), \ .dev = DEVICE_DT_GET(node_id), \ .cfg = (cfg_ptr), \ .data = (data_ptr), \ .bus_type = Z_EMUL_BUS(node_id, EMUL_BUS_TYPE_I2C, EMUL_BUS_TYPE_ESPI, \ EMUL_BUS_TYPE_SPI, EMUL_BUS_TYPE_MSPI, EMUL_BUS_TYPE_NONE), \ .bus = {.Z_EMUL_BUS(node_id, i2c, espi, spi, mspi, none) = \ &(Z_EMUL_REG_BUS_IDENTIFIER(node_id))}, \ .backend_api = (_backend_api), \ }; /** * @brief Like EMUL_DT_DEFINE(), but uses an instance of a DT_DRV_COMPAT compatible instead of a * node identifier. * * @param inst instance number. The @p node_id argument to EMUL_DT_DEFINE is set to * DT_DRV_INST(inst). * @param ... other parameters as expected by EMUL_DT_DEFINE. */ #define EMUL_DT_INST_DEFINE(inst, ...) EMUL_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__) /** * @brief Get a const struct emul* from a devicetree node identifier * * @details Returns a pointer to an emulator object created from a devicetree * node, if any device was allocated by an emulator implementation. * * If no such device was allocated, this will fail at linker time. If you get an * error that looks like undefined reference to __device_dts_ord_, * that is what happened. Check to make sure your emulator implementation is * being compiled, usually by enabling the Kconfig options it requires. * * @param node_id A devicetree node identifier * @return A pointer to the emul object created for that node */ #define EMUL_DT_GET(node_id) (&EMUL_DT_NAME_GET(node_id)) /** * @brief Utility macro to obtain an optional reference to an emulator * * If the node identifier referes to a node with status `okay`, this returns `EMUL_DT_GET(node_id)`. * Otherwise, it returns `NULL`. * * @param node_id A devicetree node identifier * @return a @ref emul reference for the node identifier, which may be `NULL`. */ #define EMUL_DT_GET_OR_NULL(node_id) \ COND_CODE_1(DT_NODE_HAS_STATUS(node_id, okay), (EMUL_DT_GET(node_id)), (NULL)) /** * @brief Set up a list of emulators * * @param dev Device the emulators are attached to (e.g. an I2C controller) * @return 0 if OK * @return negative value on error */ int emul_init_for_bus(const struct device *dev); /** * @brief Retrieve the emul structure for an emulator by name * * @details Emulator objects are created via the EMUL_DT_DEFINE() macro and placed in memory by the * linker. If the emulator structure is needed for custom API calls, it can be retrieved by the name * that the emulator exposes to the system (this is the devicetree node's label by default). * * @param name Emulator name to search for. A null pointer, or a pointer to an * empty string, will cause NULL to be returned. * * @return pointer to emulator structure; NULL if not found or cannot be used. */ const struct emul *emul_get_binding(const char *name); /** * @} */ #define Z_MAYBE_EMUL_DECLARE_INTERNAL(node_id) extern const struct emul EMUL_DT_NAME_GET(node_id); DT_FOREACH_STATUS_OKAY_NODE(Z_MAYBE_EMUL_DECLARE_INTERNAL); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* ZEPHYR_INCLUDE_DRIVERS_EMUL_H_ */