Zephyr API Documentation  3.7.0-rc1
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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.
 
 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(node_id, okay), (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_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 emulemul_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 <zephyr/drivers/emul.h>

Value:
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, \
.bus = {.Z_EMUL_BUS(node_id, i2c, espi, spi, mspi, none) = \
&(Z_EMUL_REG_BUS_IDENTIFIER(node_id))}, \
.backend_api = (_backend_api), \
};
#define DEVICE_DT_GET(node_id)
Get a device reference from a devicetree node identifier.
Definition: device.h:246
#define EMUL_DT_NAME_GET(node_id)
Use the devicetree node identifier as a unique name.
Definition: emul.h:108
@ EMUL_BUS_TYPE_SPI
Definition: emul.h:39
@ EMUL_BUS_TYPE_I2C
Definition: emul.h:37
@ EMUL_BUS_TYPE_MSPI
Definition: emul.h:40
@ EMUL_BUS_TYPE_ESPI
Definition: emul.h:38
@ EMUL_BUS_TYPE_NONE
Definition: emul.h:41
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition: iterable_sections.h:216
An emulator instance - represents the target emulated device/peripheral that is interacted with throu...
Definition: emul.h:80
Node in a linked list of emulators for eSPI devices.
Definition: espi_emul.h:111
Node in a linked list of emulators for I2C devices.
Definition: i2c_emul.h:37
Node in a linked list of emulators for MSPI devices.
Definition: mspi_emul.h:87
Emulator API stub when an emulator is not actually placed on a bus.
Definition: emul.h:71
Node in a linked list of emulators for SPI devices.
Definition: spi_emul.h:37

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_idNode ID of the driver to emulate (e.g. DT_DRV_INST(n)); the node_id MUST have a corresponding DEVICE_DT_DEFINE().
init_fnfunction to call to initialise the emulator (see emul_init typedef)
data_ptremulator-specific data
cfg_ptremulator-specific configuration data
bus_apiemulator-specific bus api
_backend_apiemulator-specific backend api

◆ EMUL_DT_GET

#define EMUL_DT_GET (   node_id)    (&EMUL_DT_NAME_GET(node_id))

#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_idA 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(node_id, okay), (EMUL_DT_GET(node_id)), (NULL))

#include <zephyr/drivers/emul.h>

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.

Parameters
node_idA 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 <zephyr/drivers/emul.h>

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

Parameters
instinstance 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 <zephyr/drivers/emul.h>

Use the devicetree node identifier as a unique name.

Parameters
node_idA devicetree node identifier

Typedef Documentation

◆ emul_init_t

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

#include <zephyr/drivers/emul.h>

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

Parameters
emulEmulator to init
parentParent device that is using the emulator

Enumeration Type Documentation

◆ emul_bus_type

#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_NONE 

Function Documentation

◆ emul_get_binding()

const struct emul * emul_get_binding ( const char *  name)

#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
nameEmulator 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 <zephyr/drivers/emul.h>

Set up a list of emulators.

Parameters
devDevice the emulators are attached to (e.g. an I2C controller)
Returns
0 if OK
negative value on error