eSPI Driver APIs More...

Data Structures
struct	espi_evt_data_kbc
	Bit field definition of evt_data in struct espi_event for KBC. More...

struct	espi_evt_data_acpi
	Bit field definition of evt_data in struct espi_event for ACPI. More...

struct	espi_event
	eSPI event More...

struct	espi_cfg
	eSPI bus configuration parameters More...

struct	espi_request_packet
	eSPI peripheral request packet format More...

struct	espi_oob_packet
	eSPI out-of-band transaction packet format More...

struct	espi_flash_packet
	eSPI flash transactions packet format More...

struct	espi_saf_cfg
	eSPI SAF configuration parameters More...

struct	espi_saf_packet
	eSPI SAF transaction packet format More...

Macros
#define	ESPI_VWIRE_SIGNAL_OCB_0 ESPI_VWIRE_SIGNAL_TARGET_GPIO_0

#define	ESPI_VWIRE_SIGNAL_OCB_1 ESPI_VWIRE_SIGNAL_TARGET_GPIO_1

#define	ESPI_VWIRE_SIGNAL_OCB_2 ESPI_VWIRE_SIGNAL_TARGET_GPIO_2

#define	ESPI_VWIRE_SIGNAL_OCB_3 ESPI_VWIRE_SIGNAL_TARGET_GPIO_3

#define	HOST_KBC_EVT_IBF BIT(0)

#define	HOST_KBC_EVT_OBE BIT(1)

Typedefs
typedef void(*	espi_callback_handler_t) (const struct device dev, struct espi_callback cb, struct espi_event espi_evt)
	Define the application callback handler function signature.

Enumerations
enum	espi_io_mode { ESPI_IO_MODE_SINGLE_LINE = BIT(0) , ESPI_IO_MODE_DUAL_LINES = BIT(1) , ESPI_IO_MODE_QUAD_LINES = BIT(2) }
	eSPI I/O mode capabilities More...

enum	espi_channel { ESPI_CHANNEL_PERIPHERAL = BIT(0) , ESPI_CHANNEL_VWIRE = BIT(1) , ESPI_CHANNEL_OOB = BIT(2) , ESPI_CHANNEL_FLASH = BIT(3) }
	eSPI channel. More...

enum	espi_bus_event { ESPI_BUS_RESET = BIT(0) , ESPI_BUS_EVENT_CHANNEL_READY = BIT(1) , ESPI_BUS_EVENT_VWIRE_RECEIVED = BIT(2) , ESPI_BUS_EVENT_OOB_RECEIVED = BIT(3) , ESPI_BUS_PERIPHERAL_NOTIFICATION = BIT(4) , ESPI_BUS_SAF_NOTIFICATION = BIT(5) }
	eSPI bus event. More...

enum	espi_pc_event { ESPI_PC_EVT_BUS_CHANNEL_READY = BIT(0) , ESPI_PC_EVT_BUS_MASTER_ENABLE = BIT(1) }
	eSPI peripheral channel events. More...

enum	espi_virtual_peripheral { ESPI_PERIPHERAL_UART , ESPI_PERIPHERAL_8042_KBC , ESPI_PERIPHERAL_HOST_IO , ESPI_PERIPHERAL_DEBUG_PORT80 , ESPI_PERIPHERAL_HOST_IO_PVT }
	eSPI peripheral notification type. More...

enum	espi_cycle_type { ESPI_CYCLE_MEMORY_READ32 , ESPI_CYCLE_MEMORY_READ64 , ESPI_CYCLE_MEMORY_WRITE32 , ESPI_CYCLE_MEMORY_WRITE64 , ESPI_CYCLE_MESSAGE_NODATA , ESPI_CYCLE_MESSAGE_DATA , ESPI_CYCLE_OK_COMPLETION_NODATA , ESPI_CYCLE_OKCOMPLETION_DATA , ESPI_CYCLE_NOK_COMPLETION_NODATA }
	eSPI cycle types supported over eSPI peripheral channel More...

enum	espi_vwire_signal { ESPI_VWIRE_SIGNAL_SLP_S3 , ESPI_VWIRE_SIGNAL_SLP_S4 , ESPI_VWIRE_SIGNAL_SLP_S5 , ESPI_VWIRE_SIGNAL_OOB_RST_WARN , ESPI_VWIRE_SIGNAL_PLTRST , ESPI_VWIRE_SIGNAL_SUS_STAT , ESPI_VWIRE_SIGNAL_NMIOUT , ESPI_VWIRE_SIGNAL_SMIOUT , ESPI_VWIRE_SIGNAL_HOST_RST_WARN , ESPI_VWIRE_SIGNAL_SLP_A , ESPI_VWIRE_SIGNAL_SUS_PWRDN_ACK , ESPI_VWIRE_SIGNAL_SUS_WARN , ESPI_VWIRE_SIGNAL_SLP_WLAN , ESPI_VWIRE_SIGNAL_SLP_LAN , ESPI_VWIRE_SIGNAL_HOST_C10 , ESPI_VWIRE_SIGNAL_DNX_WARN , ESPI_VWIRE_SIGNAL_PME , ESPI_VWIRE_SIGNAL_WAKE , ESPI_VWIRE_SIGNAL_OOB_RST_ACK , ESPI_VWIRE_SIGNAL_TARGET_BOOT_STS , ESPI_VWIRE_SIGNAL_ERR_NON_FATAL , ESPI_VWIRE_SIGNAL_ERR_FATAL , ESPI_VWIRE_SIGNAL_TARGET_BOOT_DONE , ESPI_VWIRE_SIGNAL_HOST_RST_ACK , ESPI_VWIRE_SIGNAL_RST_CPU_INIT , ESPI_VWIRE_SIGNAL_SMI , ESPI_VWIRE_SIGNAL_SCI , ESPI_VWIRE_SIGNAL_DNX_ACK , ESPI_VWIRE_SIGNAL_SUS_ACK , ESPI_VWIRE_SIGNAL_TARGET_GPIO_0 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_1 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_2 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_3 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_4 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_5 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_6 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_7 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_8 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_9 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_10 , ESPI_VWIRE_SIGNAL_TARGET_GPIO_11 , ESPI_VWIRE_SIGNAL_COUNT }
	eSPI system platform signals that can be send or receive through virtual wire channel More...

enum	lpc_peripheral_opcode { E8042_OBF_HAS_CHAR = 0x50 , E8042_IBF_HAS_CHAR , E8042_WRITE_KB_CHAR , E8042_WRITE_MB_CHAR , E8042_RESUME_IRQ , E8042_PAUSE_IRQ , E8042_CLEAR_OBF , E8042_READ_KB_STS , E8042_SET_FLAG , E8042_CLEAR_FLAG , EACPI_OBF_HAS_CHAR = EACPI_START_OPCODE , EACPI_IBF_HAS_CHAR , EACPI_WRITE_CHAR , EACPI_READ_STS , EACPI_WRITE_STS }

Functions
int	espi_config (const struct device dev, struct espi_cfg cfg)
	Configure operation of a eSPI controller.

bool	espi_get_channel_status (const struct device *dev, enum espi_channel ch)
	Query to see if it a channel is ready.

int	espi_read_request (const struct device dev, struct espi_request_packet req)
	Sends memory, I/O or message read request over eSPI.

int	espi_write_request (const struct device dev, struct espi_request_packet req)
	Sends memory, I/O or message write request over eSPI.

int	espi_read_lpc_request (const struct device dev, enum lpc_peripheral_opcode op, uint32_t data)
	Reads SOC data from a LPC peripheral with information updated over eSPI.

int	espi_write_lpc_request (const struct device dev, enum lpc_peripheral_opcode op, uint32_t data)
	Writes data to a LPC peripheral which generates an eSPI transaction.

int	espi_send_vwire (const struct device *dev, enum espi_vwire_signal signal, uint8_t level)
	Sends system/platform signal as a virtual wire packet.

int	espi_receive_vwire (const struct device dev, enum espi_vwire_signal signal, uint8_t level)
	Retrieves level status for a signal encapsulated in a virtual wire.

int	espi_send_oob (const struct device dev, struct espi_oob_packet pckt)
	Sends SMBus transaction (out-of-band) packet over eSPI bus.

int	espi_receive_oob (const struct device dev, struct espi_oob_packet pckt)
	Receives SMBus transaction (out-of-band) packet from eSPI bus.

int	espi_read_flash (const struct device dev, struct espi_flash_packet pckt)
	Sends a read request packet for shared flash.

int	espi_write_flash (const struct device dev, struct espi_flash_packet pckt)
	Sends a write request packet for shared flash.

int	espi_flash_erase (const struct device dev, struct espi_flash_packet pckt)
	Sends a write request packet for shared flash.

static void	espi_init_callback (struct espi_callback *callback, espi_callback_handler_t handler, enum espi_bus_event evt_type)
	Callback model.

static int	espi_add_callback (const struct device dev, struct espi_callback callback)
	Add an application callback.

static int	espi_remove_callback (const struct device dev, struct espi_callback callback)
	Remove an application callback.

int	espi_saf_config (const struct device dev, const struct espi_saf_cfg cfg)
	Configure operation of a eSPI controller.

int	espi_saf_set_protection_regions (const struct device dev, const struct espi_saf_protection pr)
	Set one or more SAF protection regions.

int	espi_saf_activate (const struct device *dev)
	Activate SAF block.

bool	espi_saf_get_channel_status (const struct device *dev)
	Query to see if SAF is ready.

int	espi_saf_flash_read (const struct device dev, struct espi_saf_packet pckt)
	Sends a read request packet for slave attached flash.

int	espi_saf_flash_write (const struct device dev, struct espi_saf_packet pckt)
	Sends a write request packet for slave attached flash.

int	espi_saf_flash_erase (const struct device dev, struct espi_saf_packet pckt)
	Sends a write request packet for slave attached flash.

int	espi_saf_flash_unsuccess (const struct device dev, struct espi_saf_packet pckt)
	Response unsuccessful completion for slave attached flash.

static void	espi_saf_init_callback (struct espi_callback *callback, espi_callback_handler_t handler, enum espi_bus_event evt_type)
	Callback model.

static int	espi_saf_add_callback (const struct device dev, struct espi_callback callback)
	Add an application callback.

static int	espi_saf_remove_callback (const struct device dev, struct espi_callback callback)
	Remove an application callback.

Detailed Description

eSPI Driver APIs

eSPI SAF Driver APIs

Macro Definition Documentation

◆ ESPI_VWIRE_SIGNAL_OCB_0

#define ESPI_VWIRE_SIGNAL_OCB_0 ESPI_VWIRE_SIGNAL_TARGET_GPIO_0

#include <zephyr/drivers/espi.h>

◆ ESPI_VWIRE_SIGNAL_OCB_1

#define ESPI_VWIRE_SIGNAL_OCB_1 ESPI_VWIRE_SIGNAL_TARGET_GPIO_1

#include <zephyr/drivers/espi.h>

◆ ESPI_VWIRE_SIGNAL_OCB_2

#define ESPI_VWIRE_SIGNAL_OCB_2 ESPI_VWIRE_SIGNAL_TARGET_GPIO_2

#include <zephyr/drivers/espi.h>

◆ ESPI_VWIRE_SIGNAL_OCB_3

#define ESPI_VWIRE_SIGNAL_OCB_3 ESPI_VWIRE_SIGNAL_TARGET_GPIO_3

#include <zephyr/drivers/espi.h>

◆ HOST_KBC_EVT_IBF

#define HOST_KBC_EVT_IBF BIT(0)

#include <zephyr/drivers/espi.h>

◆ HOST_KBC_EVT_OBE

#define HOST_KBC_EVT_OBE BIT(1)

#include <zephyr/drivers/espi.h>

Typedef Documentation

◆ espi_callback_handler_t

espi_callback_handler_t

#include <zephyr/drivers/espi.h>

Define the application callback handler function signature.

Parameters

dev	Device struct for the eSPI device.
cb	Original struct espi_callback owning this handler.
espi_evt	event details that trigger the callback handler.

Enumeration Type Documentation

◆ espi_bus_event

enum espi_bus_event

#include <zephyr/drivers/espi.h>

eSPI bus event.

eSPI bus event to indicate events for which user can register callbacks

Enumerator
ESPI_BUS_RESET
ESPI_BUS_EVENT_CHANNEL_READY
ESPI_BUS_EVENT_VWIRE_RECEIVED
ESPI_BUS_EVENT_OOB_RECEIVED
ESPI_BUS_PERIPHERAL_NOTIFICATION
ESPI_BUS_SAF_NOTIFICATION

◆ espi_channel

enum espi_channel

#include <zephyr/drivers/espi.h>

eSPI channel.

+----------------------------------------------------------------------+
|                                                                      |
|  eSPI controller                     +-------------+                 |
|                      +-----------+   |    Power    |   +----------+  |
|                      |Out of band|   |  management |   |   GPIO   |  |
|  +------------+      |processor  |   |  controller |   |  sources |  |
|  |  SPI flash |      +-----------+   +-------------+   +----------+  |
|  | controller |            |                |               |        |
|  +------------+            |                |               |        |
|   |  |    |                +--------+       +---------------+        |
|   |  |    |                         |               |                |
|   |  |    +-----+   +--------+   +----------+  +----v-----+          |
|   |  |          |   |  LPC   |   | Tunneled |  | Tunneled |          |
|   |  |          |   | bridge |   |  SMBus   |  |   GPIO   |          |
|   |  |          |   +--------+   +----------+  +----------+          |
|   |  |          |        |             |             |               |
|   |  |          |        ------+       |             |               |
|   |  |          |              |       |             |               |
|   |  |   +------v-----+    +---v-------v-------------v----+          |
|   |  |   | eSPI Flash |    |    eSPI protocol block       |          |
|   |  |   |   access   +--->+                              |          |
|   |  |   +------------+    +------------------------------+          |
|   |  |                             |                                 |
|   |  +-----------+                 |                                 |
|   |              v                 v                                 |
|   |           XXXXXXXXXXXXXXXXXXXXXXX                                |
|   |            XXXXXXXXXXXXXXXXXXXXX                                 |
|   |             XXXXXXXXXXXXXXXXXXX                                  |
+----------------------------------------------------------------------+
   |                      |
   v             +-----------------+
 +---------+     |  |   |   |   |  |
 |  Flash  |     |  |   |   |   |  |
 +---------+     |  +   +   +   +  |    eSPI bus
                 | CH0 CH1 CH2 CH3 |    (logical channels)
                 |  +   +   +   +  |
                 |  |   |   |   |  |
                 +-----------------+
                          |
+-----------------------------------------------------------------------+
|  eSPI target                                                          |
|                                                                       |
|       CH0         |     CH1      |      CH2      |    CH3             |
|   eSPI endpoint   |    VWIRE     |      OOB      |   Flash            |
+-----------------------------------------------------------------------+

Identifies each eSPI logical channel supported by eSPI controller Each channel allows independent traffic, but the assignment of channel type to channel number is fixed.

Note that generic commands are not associated with any channel, so traffic over eSPI can occur if all channels are disabled or not ready

Enumerator
ESPI_CHANNEL_PERIPHERAL
ESPI_CHANNEL_VWIRE
ESPI_CHANNEL_OOB
ESPI_CHANNEL_FLASH

◆ espi_cycle_type

enum espi_cycle_type

#include <zephyr/drivers/espi.h>

eSPI cycle types supported over eSPI peripheral channel

Enumerator
ESPI_CYCLE_MEMORY_READ32
ESPI_CYCLE_MEMORY_READ64
ESPI_CYCLE_MEMORY_WRITE32
ESPI_CYCLE_MEMORY_WRITE64
ESPI_CYCLE_MESSAGE_NODATA
ESPI_CYCLE_MESSAGE_DATA
ESPI_CYCLE_OK_COMPLETION_NODATA
ESPI_CYCLE_OKCOMPLETION_DATA
ESPI_CYCLE_NOK_COMPLETION_NODATA

◆ espi_io_mode

enum espi_io_mode

#include <zephyr/drivers/espi.h>

eSPI I/O mode capabilities

Enumerator
ESPI_IO_MODE_SINGLE_LINE
ESPI_IO_MODE_DUAL_LINES
ESPI_IO_MODE_QUAD_LINES

◆ espi_pc_event

enum espi_pc_event

#include <zephyr/drivers/espi.h>

eSPI peripheral channel events.

eSPI peripheral channel event types to indicate users.

Enumerator
ESPI_PC_EVT_BUS_CHANNEL_READY
ESPI_PC_EVT_BUS_MASTER_ENABLE

◆ espi_virtual_peripheral

enum espi_virtual_peripheral

#include <zephyr/drivers/espi.h>

eSPI peripheral notification type.

eSPI peripheral notification event details to indicate which peripheral trigger the eSPI callback

Enumerator
ESPI_PERIPHERAL_UART
ESPI_PERIPHERAL_8042_KBC
ESPI_PERIPHERAL_HOST_IO
ESPI_PERIPHERAL_DEBUG_PORT80
ESPI_PERIPHERAL_HOST_IO_PVT

◆ espi_vwire_signal

enum espi_vwire_signal

#include <zephyr/drivers/espi.h>

eSPI system platform signals that can be send or receive through virtual wire channel

Enumerator
ESPI_VWIRE_SIGNAL_SLP_S3
ESPI_VWIRE_SIGNAL_SLP_S4
ESPI_VWIRE_SIGNAL_SLP_S5
ESPI_VWIRE_SIGNAL_OOB_RST_WARN
ESPI_VWIRE_SIGNAL_PLTRST
ESPI_VWIRE_SIGNAL_SUS_STAT
ESPI_VWIRE_SIGNAL_NMIOUT
ESPI_VWIRE_SIGNAL_SMIOUT
ESPI_VWIRE_SIGNAL_HOST_RST_WARN
ESPI_VWIRE_SIGNAL_SLP_A
ESPI_VWIRE_SIGNAL_SUS_PWRDN_ACK
ESPI_VWIRE_SIGNAL_SUS_WARN
ESPI_VWIRE_SIGNAL_SLP_WLAN
ESPI_VWIRE_SIGNAL_SLP_LAN
ESPI_VWIRE_SIGNAL_HOST_C10
ESPI_VWIRE_SIGNAL_DNX_WARN
ESPI_VWIRE_SIGNAL_PME
ESPI_VWIRE_SIGNAL_WAKE
ESPI_VWIRE_SIGNAL_OOB_RST_ACK
ESPI_VWIRE_SIGNAL_TARGET_BOOT_STS
ESPI_VWIRE_SIGNAL_ERR_NON_FATAL
ESPI_VWIRE_SIGNAL_ERR_FATAL
ESPI_VWIRE_SIGNAL_TARGET_BOOT_DONE
ESPI_VWIRE_SIGNAL_HOST_RST_ACK
ESPI_VWIRE_SIGNAL_RST_CPU_INIT
ESPI_VWIRE_SIGNAL_SMI
ESPI_VWIRE_SIGNAL_SCI
ESPI_VWIRE_SIGNAL_DNX_ACK
ESPI_VWIRE_SIGNAL_SUS_ACK
ESPI_VWIRE_SIGNAL_TARGET_GPIO_0
ESPI_VWIRE_SIGNAL_TARGET_GPIO_1
ESPI_VWIRE_SIGNAL_TARGET_GPIO_2
ESPI_VWIRE_SIGNAL_TARGET_GPIO_3
ESPI_VWIRE_SIGNAL_TARGET_GPIO_4
ESPI_VWIRE_SIGNAL_TARGET_GPIO_5
ESPI_VWIRE_SIGNAL_TARGET_GPIO_6
ESPI_VWIRE_SIGNAL_TARGET_GPIO_7
ESPI_VWIRE_SIGNAL_TARGET_GPIO_8
ESPI_VWIRE_SIGNAL_TARGET_GPIO_9
ESPI_VWIRE_SIGNAL_TARGET_GPIO_10
ESPI_VWIRE_SIGNAL_TARGET_GPIO_11
ESPI_VWIRE_SIGNAL_COUNT

◆ lpc_peripheral_opcode

enum lpc_peripheral_opcode

#include <zephyr/drivers/espi.h>

Enumerator
E8042_OBF_HAS_CHAR
E8042_IBF_HAS_CHAR
E8042_WRITE_KB_CHAR
E8042_WRITE_MB_CHAR
E8042_RESUME_IRQ
E8042_PAUSE_IRQ
E8042_CLEAR_OBF
E8042_READ_KB_STS
E8042_SET_FLAG
E8042_CLEAR_FLAG
EACPI_OBF_HAS_CHAR
EACPI_IBF_HAS_CHAR
EACPI_WRITE_CHAR
EACPI_READ_STS
EACPI_WRITE_STS

Function Documentation

◆ espi_add_callback()

static int espi_add_callback	(	const struct device *	dev,
		struct espi_callback *	callback
	)

inlinestatic

#include <zephyr/drivers/espi.h>

Add an application callback.

Parameters

dev	Pointer to the device structure for the driver instance.
callback	A valid Application's callback structure pointer.

Returns: 0 if successful, negative errno code on failure.

Note: Callbacks may be added to the device from within a callback handler invocation, but whether they are invoked for the current eSPI event is not specified.

Note: enables to add as many callback as needed on the same device.

◆ espi_config()

int espi_config	(	const struct device *	dev,
		struct espi_cfg *	cfg
	)

#include <zephyr/drivers/espi.h>

Configure operation of a eSPI controller.

This routine provides a generic interface to override eSPI controller capabilities.

If this eSPI controller is acting as target, the values set here will be discovered as part through the GET_CONFIGURATION command issued by the eSPI controller during initialization.

If this eSPI controller is acting as controller, the values set here will be used by eSPI controller to determine minimum common capabilities with eSPI target then send via SET_CONFIGURATION command.

+---------+   +---------+     +------+          +---------+   +---------+
|  eSPI   |   |  eSPI   |     | eSPI |          |  eSPI   |   |  eSPI   |
|  target |   | driver  |     |  bus |          |  driver |   |  host   |
+--------+   +---------+     +------+          +---------+   +---------+
    |              |            |                   |             |
    | espi_config  | Set eSPI   |       Set eSPI    | espi_config |
    +--------------+ ctrl regs  |       cap ctrl reg| +-----------+
    |              +-------+    |          +--------+             |
    |              |<------+    |          +------->|             |
    |              |            |                   |             |
    |              |            |                   |             |
    |              |            | GET_CONFIGURATION |             |
    |              |            +<------------------+             |
    |              |<-----------|                   |             |
    |              | eSPI caps  |                   |             |
    |              |----------->+    response       |             |
    |              |            |------------------>+             |
    |              |            |                   |             |
    |              |            | SET_CONFIGURATION |             |
    |              |            +<------------------+             |
    |              |            |  accept           |             |
    |              |            +------------------>+             |
    +              +            +                   +             +

Parameters

dev	Pointer to the device structure for the driver instance.
cfg	the device runtime configuration for the eSPI controller.

Return values

0	If successful.
-EIO	General input / output error, failed to configure device.
-EINVAL	invalid capabilities, failed to configure device.
-ENOTSUP	capability not supported by eSPI target.

◆ espi_flash_erase()

int espi_flash_erase	(	const struct device *	dev,
		struct espi_flash_packet *	pckt
	)

#include <zephyr/drivers/espi.h>

Sends a write request packet for shared flash.

This routines provides an interface to send a request to write to the flash components shared between the eSPI controller and eSPI targets.

Parameters

dev	Pointer to the device structure for the driver instance.
pckt	Address of the representation of write flash transaction.

Return values

-ENOTSUP	eSPI flash logical channel transactions not supported.
-EBUSY	eSPI flash channel is not ready or disabled by controller.
-EIO	General input / output error, failed request to controller.

◆ espi_get_channel_status()

bool espi_get_channel_status	(	const struct device *	dev,
		enum espi_channel	ch
	)

#include <zephyr/drivers/espi.h>

Query to see if it a channel is ready.

This routine allows to check if logical channel is ready before use. Note that queries for channels not supported will always return false.

Parameters

dev	Pointer to the device structure for the driver instance.
ch	the eSPI channel for which status is to be retrieved.

Return values

true	If eSPI channel is ready.
false	otherwise.

◆ espi_init_callback()

static void espi_init_callback	(	struct espi_callback *	callback,
		espi_callback_handler_t	handler,
		enum espi_bus_event	evt_type
	)

inlinestatic

#include <zephyr/drivers/espi.h>

Callback model.

+-------+                  +-------------+   +------+     +---------+
|  App  |                  | eSPI driver |   |  HW  |     |eSPI Host|
+---+---+                  +-------+-----+   +---+--+     +----+----+
    |                              |             |             |
    |   espi_init_callback         |             |             |
    +----------------------------> |             |             |
    |   espi_add_callback          |             |
    +----------------------------->+             |
    |                              |             |  eSPI reset |  eSPI host
    |                              |    IRQ      +<------------+  resets the
    |                              | <-----------+             |  bus
    |                              |             |             |
    |                              | Processed   |             |
    |                              | within the  |             |
    |                              | driver      |             |
    |                              |             |             |
 
    |                              |             |  VW CH ready|  eSPI host
    |                              |    IRQ      +<------------+  enables VW
    |                              | <-----------+             |  channel
    |                              |             |             |
    |                              | Processed   |             |
    |                              | within the  |             |
    |                              | driver      |             |
    |                              |             |             |
    |                              |             | Memory I/O  |  Peripheral
    |                              |             <-------------+  event
    |                              +<------------+             |
    +<-----------------------------+ callback    |             |
    | Report peripheral event      |             |             |
    | and data for the event       |             |             |
    |                              |             |             |
    |                              |             | SLP_S5      |  eSPI host
    |                              |             <-------------+  send VWire
    |                              +<------------+             |
    +<-----------------------------+ callback    |             |
    | App enables/configures       |             |             |
    | discrete regulator           |             |             |
    |                              |             |             |
    |   espi_send_vwire_signal     |             |             |
    +------------------------------>------------>|------------>|
    |                              |             |             |
    |                              |             | HOST_RST    |  eSPI host
    |                              |             <-------------+  send VWire
    |                              +<------------+             |
    +<-----------------------------+ callback    |             |
    | App reset host-related       |             |             |
    | data structures              |             |             |
    |                              |             |             |
    |                              |             |   C10       |  eSPI host
    |                              |             +<------------+  send VWire
    |                              <-------------+             |
    <------------------------------+             |             |
    | App executes                 |             |             |
    + power mgmt policy            |             |             |

Helper to initialize a struct espi_callback properly.

Parameters

callback	A valid Application's callback structure pointer.
handler	A valid handler function pointer.
evt_type	indicates the eSPI event relevant for the handler. for VWIRE_RECEIVED event the data will indicate the new level asserted

◆ espi_read_flash()

int espi_read_flash	(	const struct device *	dev,
		struct espi_flash_packet *	pckt
	)

#include <zephyr/drivers/espi.h>

Sends a read request packet for shared flash.

This routines provides an interface to send a request to read the flash component shared between the eSPI controller and eSPI targets.

Parameters

dev	Pointer to the device structure for the driver instance.
pckt	Address of the representation of read flash transaction.

Return values

-ENOTSUP	eSPI flash logical channel transactions not supported.
-EBUSY	eSPI flash channel is not ready or disabled by controller.
-EIO	General input / output error, failed request to controller.

◆ espi_read_lpc_request()

int espi_read_lpc_request	(	const struct device *	dev,
		enum lpc_peripheral_opcode	op,
		uint32_t *	data
	)

#include <zephyr/drivers/espi.h>

Reads SOC data from a LPC peripheral with information updated over eSPI.

This routine provides a generic interface to read a block whose information was updated by an eSPI transaction. Reading may trigger a transaction. The eSPI packet is assembled by the HW block.

Parameters

dev	Pointer to the device structure for the driver instance.
op	Enum representing opcode for peripheral type and read request.
data	Parameter to be read from to the LPC peripheral.

Return values

0	If successful.
-ENOTSUP	if eSPI peripheral is off or not supported.
-EINVAL	for unimplemented lpc opcode, but in range.

◆ espi_read_request()

int espi_read_request	(	const struct device *	dev,
		struct espi_request_packet *	req
	)

#include <zephyr/drivers/espi.h>

Sends memory, I/O or message read request over eSPI.

This routines provides a generic interface to send a read request packet.

Parameters

dev	Pointer to the device structure for the driver instance.
req	Address of structure representing a memory, I/O or message read request.

Return values

0	If successful.
-ENOTSUP	if eSPI controller doesn't support raw packets and instead low memory transactions are handled by controller hardware directly.
-EIO	General input / output error, failed to send over the bus.

◆ espi_receive_oob()

int espi_receive_oob	(	const struct device *	dev,
		struct espi_oob_packet *	pckt
	)

#include <zephyr/drivers/espi.h>

Receives SMBus transaction (out-of-band) packet from eSPI bus.

This routines provides an interface to receive and decoded a SMBus transaction from eSPI bus

Parameters

dev	Pointer to the device structure for the driver instance.
pckt	Address of the packet representation of SMBus transaction.

Return values

-EIO	General input / output error, failed request to controller.

◆ espi_receive_vwire()

int espi_receive_vwire	(	const struct device *	dev,
		enum espi_vwire_signal	signal,
		uint8_t *	level
	)

#include <zephyr/drivers/espi.h>

Retrieves level status for a signal encapsulated in a virtual wire.

This routines provides a generic interface to request a virtual wire packet from eSPI controller and retrieve the signal level.

Parameters

dev	Pointer to the device structure for the driver instance.
signal	the signal to be requested from eSPI controller.
level	the level of signal requested 0b LOW, 1b HIGH.

Return values

-EIO	General input / output error, failed request to controller.

◆ espi_remove_callback()

static int espi_remove_callback	(	const struct device *	dev,
		struct espi_callback *	callback
	)

inlinestatic

#include <zephyr/drivers/espi.h>

Remove an application callback.

Parameters

dev	Pointer to the device structure for the driver instance.
callback	A valid application's callback structure pointer.

Returns: 0 if successful, negative errno code on failure.

Warning: It is explicitly permitted, within a callback handler, to remove the registration for the callback that is running, i.e. callback. Attempts to remove other registrations on the same device may result in undefined behavior, including failure to invoke callbacks that remain registered and unintended invocation of removed callbacks.

Note: enables to remove as many callbacks as added through espi_add_callback().

◆ espi_saf_activate()

int espi_saf_activate ( const struct device * dev )

#include <zephyr/drivers/espi_saf.h>

Activate SAF block.

This routine activates the SAF block and should only be called after SAF has been configured and the eSPI Master has enabled the Flash Channel.

Parameters

dev	Pointer to the device structure for the driver instance.

Return values

0	If successful
-EINVAL	if failed to activate SAF.

◆ espi_saf_add_callback()

static int espi_saf_add_callback	(	const struct device *	dev,
		struct espi_callback *	callback
	)

inlinestatic

#include <zephyr/drivers/espi_saf.h>

Add an application callback.

Parameters

dev	Pointer to the device structure for the driver instance.
callback	A valid Application's callback structure pointer.

Returns: 0 if successful, negative errno code on failure.

Note: Callbacks may be added to the device from within a callback handler invocation, but whether they are invoked for the current eSPI event is not specified.

Note: enables to add as many callback as needed on the same device.

◆ espi_saf_config()

int espi_saf_config	(	const struct device *	dev,
		const struct espi_saf_cfg *	cfg
	)

#include <zephyr/drivers/espi_saf.h>

Configure operation of a eSPI controller.

This routine provides a generic interface to override eSPI controller capabilities.

If this eSPI controller is acting as slave, the values set here will be discovered as part through the GET_CONFIGURATION command issued by the eSPI master during initialization.

If this eSPI controller is acting as master, the values set here will be used by eSPI master to determine minimum common capabilities with eSPI slave then send via SET_CONFIGURATION command.

+--------+   +---------+     +------+          +---------+   +---------+
|  eSPI  |   |  eSPI   |     | eSPI |          |  eSPI   |   |  eSPI   |
|  slave |   | driver  |     |  bus |          |  driver |   |  host   |
+--------+   +---------+     +------+          +---------+   +---------+
    |              |            |                   |             |
    | espi_config  | Set eSPI   |       Set eSPI    | espi_config |
    +--------------+ ctrl regs  |       cap ctrl reg| +-----------+
    |              +-------+    |          +--------+             |
    |              |<------+    |          +------->|             |
    |              |            |                   |             |
    |              |            |                   |             |
    |              |            | GET_CONFIGURATION |             |
    |              |            +<------------------+             |
    |              |<-----------|                   |             |
    |              | eSPI caps  |                   |             |
    |              |----------->+    response       |             |
    |              |            |------------------>+             |
    |              |            |                   |             |
    |              |            | SET_CONFIGURATION |             |
    |              |            +<------------------+             |
    |              |            |  accept           |             |
    |              |            +------------------>+             |
    +              +            +                   +             +

Parameters

dev	Pointer to the device structure for the driver instance.
cfg	the device runtime configuration for the eSPI controller.

Return values

0	If successful.
-EIO	General input / output error, failed to configure device.
-EINVAL	invalid capabilities, failed to configure device.
-ENOTSUP	capability not supported by eSPI slave.

◆ espi_saf_flash_erase()

int espi_saf_flash_erase	(	const struct device *	dev,
		struct espi_saf_packet *	pckt
	)

#include <zephyr/drivers/espi_saf.h>

Sends a write request packet for slave attached flash.

This routines provides an interface to send a request to write to the flash components shared between the eSPI master and eSPI slaves.

Parameters

dev	Pointer to the device structure for the driver instance.
pckt	Address of the representation of erase flash transaction.

Return values

-ENOTSUP	eSPI flash logical channel transactions not supported.
-EBUSY	eSPI flash channel is not ready or disabled by master.
-EIO	General input / output error, failed request to master.

◆ espi_saf_flash_read()

int espi_saf_flash_read	(	const struct device *	dev,
		struct espi_saf_packet *	pckt
	)

#include <zephyr/drivers/espi_saf.h>

Sends a read request packet for slave attached flash.

This routines provides an interface to send a request to read the flash component shared between the eSPI master and eSPI slaves.

Parameters

dev	Pointer to the device structure for the driver instance.
pckt	Address of the representation of read flash transaction.

Return values

-ENOTSUP	eSPI flash logical channel transactions not supported.
-EBUSY	eSPI flash channel is not ready or disabled by master.
-EIO	General input / output error, failed request to master.

◆ espi_saf_flash_unsuccess()

int espi_saf_flash_unsuccess	(	const struct device *	dev,
		struct espi_saf_packet *	pckt
	)

#include <zephyr/drivers/espi_saf.h>

Response unsuccessful completion for slave attached flash.

This routines provides an interface to response that transaction is invalid and return unsuccessful completion from target to controller.

Parameters

dev	Pointer to the device structure for the driver instance.
pckt	Address of the representation of flash transaction.

Return values

-ENOTSUP	eSPI flash logical channel transactions not supported.
-EBUSY	eSPI flash channel is not ready or disabled by master.
-EIO	General input / output error, failed request to master.

◆ espi_saf_flash_write()

int espi_saf_flash_write	(	const struct device *	dev,
		struct espi_saf_packet *	pckt
	)

#include <zephyr/drivers/espi_saf.h>

Sends a write request packet for slave attached flash.

This routines provides an interface to send a request to write to the flash components shared between the eSPI master and eSPI slaves.

Parameters

dev	Pointer to the device structure for the driver instance.
pckt	Address of the representation of write flash transaction.

Return values

-ENOTSUP	eSPI flash logical channel transactions not supported.
-EBUSY	eSPI flash channel is not ready or disabled by master.
-EIO	General input / output error, failed request to master.

◆ espi_saf_get_channel_status()

bool espi_saf_get_channel_status ( const struct device * dev )

#include <zephyr/drivers/espi_saf.h>

Query to see if SAF is ready.

This routine allows to check if SAF is ready before use.

Parameters

dev	Pointer to the device structure for the driver instance.

Return values

true	If eSPI SAF is ready.
false	otherwise.

◆ espi_saf_init_callback()

static void espi_saf_init_callback	(	struct espi_callback *	callback,
		espi_callback_handler_t	handler,
		enum espi_bus_event	evt_type
	)

inlinestatic

#include <zephyr/drivers/espi_saf.h>

Callback model.

+-------+                  +-------------+   +------+     +---------+
|  App  |                  | eSPI driver |   |  HW  |     |eSPI Host|
+---+---+                  +-------+-----+   +---+--+     +----+----+
    |                              |             |             |
    |   espi_init_callback         |             |             |
    +----------------------------> |             |             |
    |   espi_add_callback          |             |
    +----------------------------->+             |
    |                              |             |  eSPI reset |  eSPI host
    |                              |    IRQ      +<------------+  resets the
    |                              | <-----------+             |  bus
    |                              |             |             |
    |                              | Processed   |             |
    |                              | within the  |             |
    |                              | driver      |             |
    |                              |             |             |
 
    |                              |             |  VW CH ready|  eSPI host
    |                              |    IRQ      +<------------+  enables VW
    |                              | <-----------+             |  channel
    |                              |             |             |
    |                              | Processed   |             |
    |                              | within the  |             |
    |                              | driver      |             |
    |                              |             |             |
    |                              |             | Memory I/O  |  Peripheral
    |                              |             <-------------+  event
    |                              +<------------+             |
    +<-----------------------------+ callback    |             |
    | Report peripheral event      |             |             |
    | and data for the event       |             |             |
    |                              |             |             |
    |                              |             | SLP_S5      |  eSPI host
    |                              |             <-------------+  send VWire
    |                              +<------------+             |
    +<-----------------------------+ callback    |             |
    | App enables/configures       |             |             |
    | discrete regulator           |             |             |
    |                              |             |             |
    |   espi_send_vwire_signal     |             |             |
    +------------------------------>------------>|------------>|
    |                              |             |             |
    |                              |             | HOST_RST    |  eSPI host
    |                              |             <-------------+  send VWire
    |                              +<------------+             |
    +<-----------------------------+ callback    |             |
    | App reset host-related       |             |             |
    | data structures              |             |             |
    |                              |             |             |
    |                              |             |   C10       |  eSPI host
    |                              |             +<------------+  send VWire
    |                              <-------------+             |
    <------------------------------+             |             |
    | App executes                 |             |             |
    + power mgmt policy            |             |             |

Helper to initialize a struct espi_callback properly.

Parameters

callback	A valid Application's callback structure pointer.
handler	A valid handler function pointer.
evt_type	indicates the eSPI event relevant for the handler. for VWIRE_RECEIVED event the data will indicate the new level asserted

◆ espi_saf_remove_callback()

static int espi_saf_remove_callback	(	const struct device *	dev,
		struct espi_callback *	callback
	)

inlinestatic

#include <zephyr/drivers/espi_saf.h>

Remove an application callback.

Parameters

dev	Pointer to the device structure for the driver instance.
callback	A valid application's callback structure pointer.

Returns: 0 if successful, negative errno code on failure.

Warning: It is explicitly permitted, within a callback handler, to remove the registration for the callback that is running, i.e. callback. Attempts to remove other registrations on the same device may result in undefined behavior, including failure to invoke callbacks that remain registered and unintended invocation of removed callbacks.

Note: enables to remove as many callbacks as added through espi_add_callback().

◆ espi_saf_set_protection_regions()

int espi_saf_set_protection_regions	(	const struct device *	dev,
		const struct espi_saf_protection *	pr
	)

#include <zephyr/drivers/espi_saf.h>

Set one or more SAF protection regions.

This routine provides an interface to override the default flash protection regions of the SAF controller.

Parameters

dev	Pointer to the device structure for the driver instance.
pr	Pointer to the SAF protection region structure.

Return values

0	If successful.
-EIO	General input / output error, failed to configure device.
-EINVAL	invalid capabilities, failed to configure device.
-ENOTSUP	capability not supported by eSPI slave.

◆ espi_send_oob()

int espi_send_oob	(	const struct device *	dev,
		struct espi_oob_packet *	pckt
	)

#include <zephyr/drivers/espi.h>

Sends SMBus transaction (out-of-band) packet over eSPI bus.

This routines provides an interface to encapsulate a SMBus transaction and send into packet over eSPI bus

Parameters

dev	Pointer to the device structure for the driver instance.
pckt	Address of the packet representation of SMBus transaction.

Return values

-EIO	General input / output error, failed request to controller.

◆ espi_send_vwire()

int espi_send_vwire	(	const struct device *	dev,
		enum espi_vwire_signal	signal,
		uint8_t	level
	)

#include <zephyr/drivers/espi.h>

Sends system/platform signal as a virtual wire packet.

This routines provides a generic interface to send a virtual wire packet from target to controller.

Parameters

dev	Pointer to the device structure for the driver instance.
signal	The signal to be send to eSPI controller.
level	The level of signal requested LOW or HIGH.

Return values

0	If successful.
-EIO	General input / output error, failed to send over the bus.

◆ espi_write_flash()

int espi_write_flash	(	const struct device *	dev,
		struct espi_flash_packet *	pckt
	)

#include <zephyr/drivers/espi.h>

Sends a write request packet for shared flash.

This routines provides an interface to send a request to write to the flash components shared between the eSPI controller and eSPI targets.

Parameters

dev	Pointer to the device structure for the driver instance.
pckt	Address of the representation of write flash transaction.

Return values

-ENOTSUP	eSPI flash logical channel transactions not supported.
-EBUSY	eSPI flash channel is not ready or disabled by controller.
-EIO	General input / output error, failed request to controller.

◆ espi_write_lpc_request()

int espi_write_lpc_request	(	const struct device *	dev,
		enum lpc_peripheral_opcode	op,
		uint32_t *	data
	)

#include <zephyr/drivers/espi.h>

Writes data to a LPC peripheral which generates an eSPI transaction.

This routine provides a generic interface to write data to a block which triggers an eSPI transaction. The eSPI packet is assembled by the HW block.

Parameters

dev	Pointer to the device structure for the driver instance.
op	Enum representing an opcode for peripheral type and write request.
data	Represents the parameter passed to the LPC peripheral.

Return values

0	If successful.
-ENOTSUP	if eSPI peripheral is off or not supported.
-EINVAL	for unimplemented lpc opcode, but in range.

◆ espi_write_request()

int espi_write_request	(	const struct device *	dev,
		struct espi_request_packet *	req
	)

#include <zephyr/drivers/espi.h>

Sends memory, I/O or message write request over eSPI.

This routines provides a generic interface to send a write request packet.

Parameters

dev	Pointer to the device structure for the driver instance.
req	Address of structure representing a memory, I/O or message write request.

Return values

0	If successful.
-ENOTSUP	if eSPI controller doesn't support raw packets and instead low memory transactions are handled by controller hardware directly.
-EINVAL	General input / output error, failed to send over the bus.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ESPI_VWIRE_SIGNAL_OCB_0

◆ ESPI_VWIRE_SIGNAL_OCB_1

◆ ESPI_VWIRE_SIGNAL_OCB_2

◆ ESPI_VWIRE_SIGNAL_OCB_3

◆ HOST_KBC_EVT_IBF

◆ HOST_KBC_EVT_OBE

Typedef Documentation

◆ espi_callback_handler_t

Enumeration Type Documentation

◆ espi_bus_event

◆ espi_channel

◆ espi_cycle_type

◆ espi_io_mode

◆ espi_pc_event

◆ espi_virtual_peripheral

◆ espi_vwire_signal

◆ lpc_peripheral_opcode

Function Documentation

◆ espi_add_callback()

◆ espi_config()

◆ espi_flash_erase()

◆ espi_get_channel_status()

◆ espi_init_callback()

◆ espi_read_flash()

◆ espi_read_lpc_request()

◆ espi_read_request()

◆ espi_receive_oob()

◆ espi_receive_vwire()

◆ espi_remove_callback()

◆ espi_saf_activate()

◆ espi_saf_add_callback()

◆ espi_saf_config()

◆ espi_saf_flash_erase()

◆ espi_saf_flash_read()

◆ espi_saf_flash_unsuccess()

◆ espi_saf_flash_write()

◆ espi_saf_get_channel_status()

◆ espi_saf_init_callback()

◆ espi_saf_remove_callback()

◆ espi_saf_set_protection_regions()

◆ espi_send_oob()

◆ espi_send_vwire()

◆ espi_write_flash()

◆ espi_write_lpc_request()

◆ espi_write_request()