Enhanced Serial Peripheral Interface (eSPI) Bus

Overview

The eSPI (enhanced serial peripheral interface) is a serial bus that is based on SPI. It also features a four-wire interface (receive, transmit, clock and target select) and three configurations: single IO, dual IO and quad IO.

The technical advancements include lower voltage signal levels (1.8V vs. 3.3V), lower pin count, and the frequency is twice as fast (66MHz vs. 33MHz) Because of its enhancements, the eSPI is used to replace the LPC (lower pin count) interface, SPI, SMBus and sideband signals.

See eSPI interface specification for additional details.

API Reference

group espi_interface

eSPI Driver APIs

eSPI SAF Driver APIs

Defines

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

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.

Param dev:

Device struct for the eSPI device.

Param cb:

Original struct espi_callback owning this handler.

Param espi_evt:

event details that trigger the callback handler.

Enums

enum espi_io_mode

eSPI I/O mode capabilities

Values:

enumerator ESPI_IO_MODE_SINGLE_LINE = BIT(0)
enumerator ESPI_IO_MODE_DUAL_LINES = BIT(1)
enumerator ESPI_IO_MODE_QUAD_LINES = BIT(2)
enum espi_channel

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

Values:

enumerator ESPI_CHANNEL_PERIPHERAL = BIT(0)
enumerator ESPI_CHANNEL_VWIRE = BIT(1)
enumerator ESPI_CHANNEL_OOB = BIT(2)
enumerator ESPI_CHANNEL_FLASH = BIT(3)
enum espi_bus_event

eSPI bus event.

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

Values:

enumerator ESPI_BUS_RESET = BIT(0)

Indicates the eSPI bus was reset either via eSPI reset pin.

eSPI drivers should convey the eSPI reset status to eSPI driver clients following eSPI specification reset pin convention: 0-eSPI bus in reset, 1-eSPI bus out-of-reset

Note: There is no need to send this callback for in-band reset.

enumerator ESPI_BUS_EVENT_CHANNEL_READY = BIT(1)

Indicates the eSPI HW has received channel enable notification from eSPI host, once the eSPI channel is signal as ready to the eSPI host, eSPI drivers should convey the eSPI channel ready to eSPI driver client via this event.

enumerator ESPI_BUS_EVENT_VWIRE_RECEIVED = BIT(2)

Indicates the eSPI HW has received a virtual wire message from eSPI host.

eSPI drivers should convey the eSPI virtual wire latest status.

enumerator ESPI_BUS_EVENT_OOB_RECEIVED = BIT(3)

Indicates the eSPI HW has received a Out-of-band package from eSPI host.

enumerator ESPI_BUS_PERIPHERAL_NOTIFICATION = BIT(4)

Indicates the eSPI HW has received a peripheral eSPI host event.

eSPI drivers should convey the peripheral type.

enumerator ESPI_BUS_TAF_NOTIFICATION = BIT(5)
enum espi_pc_event

eSPI peripheral channel events.

eSPI peripheral channel event types to indicate users.

Values:

enumerator ESPI_PC_EVT_BUS_CHANNEL_READY = BIT(0)
enumerator ESPI_PC_EVT_BUS_MASTER_ENABLE = BIT(1)
enum espi_virtual_peripheral

eSPI peripheral notification type.

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

Values:

enumerator ESPI_PERIPHERAL_UART
enumerator ESPI_PERIPHERAL_8042_KBC
enumerator ESPI_PERIPHERAL_HOST_IO
enumerator ESPI_PERIPHERAL_DEBUG_PORT80
enumerator ESPI_PERIPHERAL_HOST_IO_PVT
enum espi_cycle_type

eSPI cycle types supported over eSPI peripheral channel

Values:

enumerator ESPI_CYCLE_MEMORY_READ32
enumerator ESPI_CYCLE_MEMORY_READ64
enumerator ESPI_CYCLE_MEMORY_WRITE32
enumerator ESPI_CYCLE_MEMORY_WRITE64
enumerator ESPI_CYCLE_MESSAGE_NODATA
enumerator ESPI_CYCLE_MESSAGE_DATA
enumerator ESPI_CYCLE_OK_COMPLETION_NODATA
enumerator ESPI_CYCLE_OKCOMPLETION_DATA
enumerator ESPI_CYCLE_NOK_COMPLETION_NODATA
enum espi_vwire_signal

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

Values:

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

Values:

enumerator E8042_OBF_HAS_CHAR = 0x50
enumerator E8042_IBF_HAS_CHAR
enumerator E8042_WRITE_KB_CHAR
enumerator E8042_WRITE_MB_CHAR
enumerator E8042_RESUME_IRQ
enumerator E8042_PAUSE_IRQ
enumerator E8042_CLEAR_OBF
enumerator E8042_READ_KB_STS
enumerator E8042_SET_FLAG
enumerator E8042_CLEAR_FLAG
enumerator EACPI_OBF_HAS_CHAR = EACPI_START_OPCODE
enumerator EACPI_IBF_HAS_CHAR
enumerator EACPI_WRITE_CHAR
enumerator EACPI_READ_STS
enumerator EACPI_WRITE_STS

Functions

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

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.

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

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

Callback model.

+-------+                  +-------------+   +------+     +---------+
|  App  |                  | eSPI driver |   |  HW  |     |eSPI Host|
+---+---+                  +-------+-----+   +---+--+     +----+----+
    |                              |             |             |
    |   espi_init_callback         |             |             |
    +----------------------------> |             |             |
    |   espi_add_callback          |             |
    +----------------------------->+             |
    |                              |             |  eSPI reset |  eSPI host
    |                              |    IRQ      +<------------+  resets the
    |                              | <-----------+             |  bus
    |<-----------------------------|             |             |
    | Report eSPI bus reset        | 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

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

Add an application callback.

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

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.

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.

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

Remove an application callback.

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

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.

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.

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

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.

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

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.

int espi_saf_activate(const struct device *dev)

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.

bool espi_saf_get_channel_status(const struct device *dev)

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.

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

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.

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

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.

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

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.

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

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.

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

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

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

Add an application callback.

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

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.

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.

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

Remove an application callback.

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

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.

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.

struct espi_evt_data_kbc
#include <espi.h>

Bit field definition of evt_data in struct espi_event for KBC.

struct espi_evt_data_acpi
#include <espi.h>

Bit field definition of evt_data in struct espi_event for ACPI.

struct espi_event
#include <espi.h>

eSPI event

Public Members

enum espi_bus_event evt_type

Event type.

uint32_t evt_details

Additional details for bus event type.

uint32_t evt_data

Data associated to the event.

struct espi_cfg
#include <espi.h>

eSPI bus configuration parameters

Public Members

enum espi_io_mode io_caps

Supported I/O mode.

enum espi_channel channel_caps

Supported channels.

uint8_t max_freq

Maximum supported frequency in MHz.

struct espi_request_packet
#include <espi.h>

eSPI peripheral request packet format

struct espi_oob_packet
#include <espi.h>

eSPI out-of-band transaction packet format

For Tx packet, eSPI driver client shall specify the OOB payload data and its length in bytes. For Rx packet, eSPI driver client shall indicate the maximum number of bytes that can receive, while the eSPI driver should update the length field with the actual data received/available.

In all cases, the length does not include OOB header size 3 bytes.

struct espi_flash_packet
#include <espi.h>

eSPI flash transactions packet format

struct espi_saf_cfg
#include <espi_saf.h>

eSPI SAF configuration parameters

struct espi_saf_packet
#include <espi_saf.h>

eSPI SAF transaction packet format