Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Emulator interface

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

Topics

 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)
 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, ...)
 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)
 Get a const struct emul* from a devicetree node identifier.
 
#define EMUL_DT_GET_OR_NULL(node_id)
 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 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, 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, \
.bus = {.Z_EMUL_BUS(node_id, i2c, espi, spi, mspi, uart, 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:255
#define DT_NODE_HAS_PROP(node_id, prop)
Does a devicetree node have a property?
Definition devicetree.h:3634
#define DT_REG_ADDR(node_id)
Get a node's (only) register block address.
Definition devicetree.h:2390
#define EMUL_DT_NAME_GET(node_id)
Use the devicetree node identifier as a unique name.
Definition emul.h:111
@ EMUL_BUS_TYPE_SPI
Definition emul.h:40
@ EMUL_BUS_TYPE_I2C
Definition emul.h:38
@ EMUL_BUS_TYPE_MSPI
Definition emul.h:41
@ EMUL_BUS_TYPE_ESPI
Definition emul.h:39
@ EMUL_BUS_TYPE_NONE
Definition emul.h:43
@ EMUL_BUS_TYPE_UART
Definition emul.h:42
#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:82
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:73
Node in a linked list of emulators for SPI devices.
Definition spi_emul.h:37
Node in a linked list of emulators for UART devices.
Definition uart_emul.h:46

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)

#include <zephyr/drivers/emul.h>

Value:
(&EMUL_DT_NAME_GET(node_id))

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)

#include <zephyr/drivers/emul.h>

Value:
COND_CODE_1(DT_NODE_HAS_STATUS_OKAY(node_id), (EMUL_DT_GET(node_id)), (NULL))
#define DT_NODE_HAS_STATUS_OKAY(node_id)
Does a node identifier refer to a node with a status okay?
Definition devicetree.h:3540
#define EMUL_DT_GET(node_id)
Get a const struct emul* from a devicetree node identifier.
Definition emul.h:186
#define COND_CODE_1(_flag, _if_1_code, _else_code)
Insert code depending on whether _flag expands to 1 or not.
Definition util_macro.h:195

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

#include <zephyr/drivers/emul.h>

Value:
EMUL_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
#define DT_DRV_INST(inst)
Node identifier for an instance of a DT_DRV_COMPAT compatible.
Definition devicetree.h:3759
#define EMUL_DT_DEFINE(node_id, init_fn, data_ptr, cfg_ptr, bus_api, _backend_api)
Define a new emulator.
Definition emul.h:142

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)

#include <zephyr/drivers/emul.h>

Value:
_CONCAT(__emulreg_, node_id)

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_UART 
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