eSPI¶
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 slave 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
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.
- 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.
Enums
-
enum
espi_io_mode
¶ eSPI I/O mode capabilities
Values:
-
enum
espi_channel
¶ eSPI channel.
+——————————————————————-+ | | | eSPI host +———-+ | | +——–+ | 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 slave | | | | 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:
-
enum
espi_bus_event
¶ eSPI bus event.
eSPI bus event to indicate events for which user can register callbacks
Values:
-
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
¶
-
enumerator
-
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
¶
-
enumerator
-
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_SLV_BOOT_STS
¶
-
enumerator
ESPI_VWIRE_SIGNAL_ERR_NON_FATAL
¶
-
enumerator
ESPI_VWIRE_SIGNAL_ERR_FATAL
¶
-
enumerator
ESPI_VWIRE_SIGNAL_SLV_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
-
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
¶
-
enumerator
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 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
+ + + +
- Parameters
dev – Pointer to the device structure for the driver instance.
cfg – the device runtime configuration for the eSPI controller.
- Returns
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.
-
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.
- Returns
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.
- Returns
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.
- Returns
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.
- Returns
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.
- Returns
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 slave to master.
- Parameters
dev – Pointer to the device structure for the driver instance.
signal – The signal to be send to eSPI master.
level – The level of signal requested LOW or HIGH.
- Returns
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 master and retrieve the signal level.
- Parameters
dev – Pointer to the device structure for the driver instance.
signal – the signal to be requested from eSPI master.
level – the level of signal requested 0b LOW, 1b HIGH.
- Returns
-EIO – General input / output error, failed request to master.
-
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.
- Returns
-EIO – General input / output error, failed request to master.
-
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.
- Returns
-EIO – General input / output error, failed request to master.
-
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 master and eSPI slaves.
- Parameters
dev – Pointer to the device structure for the driver instance.
pckt – Adddress of the representation of read flash transaction.
- Returns
-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_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 master and eSPI slaves.
- Parameters
dev – Pointer to the device structure for the driver instance.
pckt – Address of the representation of write flash transaction.
- Returns
-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_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 master and eSPI slaves.
- Parameters
dev – Pointer to the device structure for the driver instance.
pckt – Address of the representation of write flash transaction.
- Returns
-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_init_callback
(struct espi_callback *callback, espi_callback_handler_t handler, enum espi_bus_event evt_type)¶ Helper to initialize a struct espi_callback properly.
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
discrete regulator
espi_send_vwire_signal
power mgmt policy | | |
- 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
+ + + +
- Parameters
dev – Pointer to the device structure for the driver instance.
cfg – the device runtime configuration for the eSPI controller.
- Returns
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.
- Returns
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.
- Returns
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.
- Returns
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 – Adddress of the representation of read flash transaction.
- Returns
-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.
- Returns
-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.
- Returns
-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)¶ Helper to initialize a struct espi_callback properly.
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
discrete regulator
espi_send_vwire_signal
power mgmt policy | | |
- 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_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
-
enum espi_bus_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
-
enum espi_io_mode
-
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
-
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
-
typedef void (*