Emulator interface

Emulators used to test drivers and higher-level code that uses them. More...

Modules
	I2C Emulation Interface
	I2C Emulation Interface.
	MSPI Emulation Interface
	MSPI Emulation Interface.
	SPI Emulation Interface
	SPI Emulation Interface.
	UART Emulation Interface
	UART Emulation Interface.
	eSPI Emulation Interface
	eSPI Emulation Interface

Data Structures
struct	emul_link_for_bus
	Structure uniquely identifying a device to be emulated. More...
struct	emul_list_for_bus
	List of emulators attached to a bus. More...
struct	no_bus_emul
	Emulator API stub when an emulator is not actually placed on a bus. More...
struct	emul
	An emulator instance - represents the target emulated device/peripheral that is interacted with through an emulated bus. More...

Macros
#define	EMUL_DT_NAME_GET(node_id)   _CONCAT(__emulreg_, node_id)
	Use the devicetree node identifier as a unique name.
#define	EMUL_DT_DEFINE(node_id, init_fn, data_ptr, cfg_ptr, bus_api, _backend_api)
	Define a new emulator.
#define	EMUL_DT_INST_DEFINE(inst, ...)   EMUL_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
	Like EMUL_DT_DEFINE(), but uses an instance of a DT_DRV_COMPAT compatible instead of a node identifier.
#define	EMUL_DT_GET(node_id)   (&EMUL_DT_NAME_GET(node_id))
	Get a const struct emul* from a devicetree node identifier.
#define	EMUL_DT_GET_OR_NULL(node_id)    COND_CODE_1(DT_NODE_HAS_STATUS_OKAY(node_id), (EMUL_DT_GET(node_id)), (NULL))
	Utility macro to obtain an optional reference to an emulator.

Typedefs
typedef int(*	emul_init_t) (const struct emul *emul, const struct device *parent)
	Standard callback for emulator initialisation providing the initialiser record and the device that calls the emulator functions.

Enumerations
enum	emul_bus_type {   EMUL_BUS_TYPE_I2C , EMUL_BUS_TYPE_ESPI , EMUL_BUS_TYPE_SPI , EMUL_BUS_TYPE_MSPI ,   EMUL_BUS_TYPE_UART , EMUL_BUS_TYPE_NONE }
	The types of supported buses. More...

Functions
int	emul_init_for_bus (const struct device *dev)
	Set up a list of emulators.
const struct emul *	emul_get_binding (const char *name)
	Retrieve the emul structure for an emulator by name.

Detailed Description

Emulators used to test drivers and higher-level code that uses them.

Macro Definition Documentation

EMUL_DT_DEFINE

#define EMUL_DT_DEFINE	(		node_id,
			init_fn,
			data_ptr,
			cfg_ptr,
			bus_api,
			_backend_api
	)

#include <include/zephyr/drivers/emul.h>

Value:

        static struct Z_EMUL_BUS(node_id, i2c_emul, espi_emul, spi_emul, mspi_emul, uart_emul,     \
                                 no_bus_emul) Z_EMUL_REG_BUS_IDENTIFIER(node_id) = {               \
                .api = bus_api,                                                                    \
                IF_ENABLED(DT_NODE_HAS_PROP(node_id, reg),                                         \
                           (.Z_EMUL_BUS(node_id, addr, chipsel, chipsel, dev_idx, dummy, 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_UART,  \
                                       EMUL_BUS_TYPE_NONE),                                        \
                .bus = {.Z_EMUL_BUS(node_id, i2c, espi, spi, mspi, uart, none) =                   \
                                &(Z_EMUL_REG_BUS_IDENTIFIER(node_id))},                            \
                .backend_api = (_backend_api),                                                     \
        };

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.

Parameters

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().
init_fn	function to call to initialise the emulator (see emul_init typedef)
data_ptr	emulator-specific data
cfg_ptr	emulator-specific configuration data
bus_api	emulator-specific bus api
_backend_api	emulator-specific backend api

EMUL_DT_GET

#define EMUL_DT_GET

(

node_id

)

(&EMUL_DT_NAME_GET(node_id))

#include <include/zephyr/drivers/emul.h>

Get a const struct emul* from a devicetree node identifier.

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_<N>, that is what happened. Check to make sure your emulator implementation is being compiled, usually by enabling the Kconfig options it requires.

Parameters

node_id

A devicetree node identifier

Returns

A pointer to the emul object created for that node

EMUL_DT_GET_OR_NULL

#define EMUL_DT_GET_OR_NULL

(

node_id

)

COND_CODE_1(DT_NODE_HAS_STATUS_OKAY(node_id), (EMUL_DT_GET(node_id)), (NULL))

#include <include/zephyr/drivers/emul.h>

Utility macro to obtain an optional reference to an emulator.

If the node identifier refers to a node with status okay, this returns EMUL_DT_GET(node_id). Otherwise, it returns NULL.

Parameters

node_id

A devicetree node identifier

Returns

a emul reference for the node identifier, which may be NULL.

EMUL_DT_INST_DEFINE

#define EMUL_DT_INST_DEFINE	(		inst,
			...
	)		EMUL_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)

#include <include/zephyr/drivers/emul.h>

Like EMUL_DT_DEFINE(), but uses an instance of a DT_DRV_COMPAT compatible instead of a node identifier.

Parameters

inst	instance number. The node_id argument to EMUL_DT_DEFINE is set to DT_DRV_INST(inst).
...	other parameters as expected by EMUL_DT_DEFINE.

EMUL_DT_NAME_GET

#define EMUL_DT_NAME_GET

(

node_id

)

_CONCAT(__emulreg_, node_id)

#include <include/zephyr/drivers/emul.h>

Use the devicetree node identifier as a unique name.

Parameters

node_id

A devicetree node identifier

Typedef Documentation

emul_init_t

typedef int(* emul_init_t) (const struct emul *emul, const struct device *parent)

#include <include/zephyr/drivers/emul.h>

Standard callback for emulator initialisation providing the initialiser record and the device that calls the emulator functions.

Parameters

emul	Emulator to init
parent	Parent device that is using the emulator

Enumeration Type Documentation

emul_bus_type

enum emul_bus_type

#include <include/zephyr/drivers/emul.h>

The types of supported buses.

Enumerator
EMUL_BUS_TYPE_I2C
EMUL_BUS_TYPE_ESPI
EMUL_BUS_TYPE_SPI
EMUL_BUS_TYPE_MSPI
EMUL_BUS_TYPE_UART
EMUL_BUS_TYPE_NONE

Function Documentation

emul_get_binding()

const struct emul * emul_get_binding

(

const char *

name

)

#include <include/zephyr/drivers/emul.h>

Retrieve the emul structure for an emulator by name.

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).

Parameters

name	Emulator name to search for. A null pointer, or a pointer to an empty string, will cause NULL to be returned.

Returns

pointer to emulator structure; NULL if not found or cannot be used.

emul_init_for_bus()

int emul_init_for_bus

(

const struct device *

dev

)

#include <include/zephyr/drivers/emul.h>

Set up a list of emulators.

Parameters

dev	Device the emulators are attached to (e.g. an I2C controller)

Returns

0 if OK

negative value on error