Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
ESPI Driver APIs

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

◆ ESPI_VWIRE_SIGNAL_OCB_1

#define ESPI_VWIRE_SIGNAL_OCB_1   ESPI_VWIRE_SIGNAL_TARGET_GPIO_1

◆ ESPI_VWIRE_SIGNAL_OCB_2

#define ESPI_VWIRE_SIGNAL_OCB_2   ESPI_VWIRE_SIGNAL_TARGET_GPIO_2

◆ ESPI_VWIRE_SIGNAL_OCB_3

#define ESPI_VWIRE_SIGNAL_OCB_3   ESPI_VWIRE_SIGNAL_TARGET_GPIO_3

◆ HOST_KBC_EVT_IBF

#define HOST_KBC_EVT_IBF   BIT(0)

◆ HOST_KBC_EVT_OBE

#define HOST_KBC_EVT_OBE   BIT(1)

Typedef Documentation

◆ espi_callback_handler_t

espi_callback_handler_t

#include <zephyr/drivers/espi.h>

Define the application callback handler function signature.

Parameters
devDevice struct for the eSPI device.
cbOriginal struct espi_callback owning this handler.
espi_evtevent details that trigger the callback handler.

Enumeration Type Documentation

◆ 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

#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

#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

#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

#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

#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

#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

#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
devPointer to the device structure for the driver instance.
callbackA 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 | |
| | +------------------>+ |
+ + + + +
static int accept(int sock, struct sockaddr *addr, socklen_t *addrlen)
POSIX wrapper for zsock_accept.
Definition: socket.h:910
int espi_config(const struct device *dev, struct espi_cfg *cfg)
Configure operation of a eSPI controller.
Parameters
devPointer to the device structure for the driver instance.
cfgthe device runtime configuration for the eSPI controller.
Return values
0If successful.
-EIOGeneral input / output error, failed to configure device.
-EINVALinvalid capabilities, failed to configure device.
-ENOTSUPcapability 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
devPointer to the device structure for the driver instance.
pcktAddress of the representation of write flash transaction.
Return values
-ENOTSUPeSPI flash logical channel transactions not supported.
-EBUSYeSPI flash channel is not ready or disabled by controller.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
chthe eSPI channel for which status is to be retrieved.
Return values
trueIf eSPI channel is ready.
falseotherwise.

◆ 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 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 | | |
static ssize_t send(int sock, const void *buf, size_t len, int flags)
POSIX wrapper for zsock_send.
Definition: socket.h:916
static void espi_init_callback(struct espi_callback *callback, espi_callback_handler_t handler, enum espi_bus_event evt_type)
Callback model.
Definition: espi.h:953
static int espi_add_callback(const struct device *dev, struct espi_callback *callback)
Add an application callback.
Definition: espi.h:976

Helper to initialize a struct espi_callback properly.

Parameters
callbackA valid Application's callback structure pointer.
handlerA valid handler function pointer.
evt_typeindicates 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
devPointer to the device structure for the driver instance.
pcktAddress of the representation of read flash transaction.
Return values
-ENOTSUPeSPI flash logical channel transactions not supported.
-EBUSYeSPI flash channel is not ready or disabled by controller.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
opEnum representing opcode for peripheral type and read request.
dataParameter to be read from to the LPC peripheral.
Return values
0If successful.
-ENOTSUPif eSPI peripheral is off or not supported.
-EINVALfor 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
devPointer to the device structure for the driver instance.
reqAddress of structure representing a memory, I/O or message read request.
Return values
0If successful.
-ENOTSUPif eSPI controller doesn't support raw packets and instead low memory transactions are handled by controller hardware directly.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
pcktAddress of the packet representation of SMBus transaction.
Return values
-EIOGeneral 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
devPointer to the device structure for the driver instance.
signalthe signal to be requested from eSPI controller.
levelthe level of signal requested 0b LOW, 1b HIGH.
Return values
-EIOGeneral 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
devPointer to the device structure for the driver instance.
callbackA 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
devPointer to the device structure for the driver instance.
Return values
0If successful
-EINVALif 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
devPointer to the device structure for the driver instance.
callbackA 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
devPointer to the device structure for the driver instance.
cfgthe device runtime configuration for the eSPI controller.
Return values
0If successful.
-EIOGeneral input / output error, failed to configure device.
-EINVALinvalid capabilities, failed to configure device.
-ENOTSUPcapability 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
devPointer to the device structure for the driver instance.
pcktAddress of the representation of erase flash transaction.
Return values
-ENOTSUPeSPI flash logical channel transactions not supported.
-EBUSYeSPI flash channel is not ready or disabled by master.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
pcktAddress of the representation of read flash transaction.
Return values
-ENOTSUPeSPI flash logical channel transactions not supported.
-EBUSYeSPI flash channel is not ready or disabled by master.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
pcktAddress of the representation of flash transaction.
Return values
-ENOTSUPeSPI flash logical channel transactions not supported.
-EBUSYeSPI flash channel is not ready or disabled by master.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
pcktAddress of the representation of write flash transaction.
Return values
-ENOTSUPeSPI flash logical channel transactions not supported.
-EBUSYeSPI flash channel is not ready or disabled by master.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
Return values
trueIf eSPI SAF is ready.
falseotherwise.

◆ 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 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
callbackA valid Application's callback structure pointer.
handlerA valid handler function pointer.
evt_typeindicates 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
devPointer to the device structure for the driver instance.
callbackA 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
devPointer to the device structure for the driver instance.
prPointer to the SAF protection region structure.
Return values
0If successful.
-EIOGeneral input / output error, failed to configure device.
-EINVALinvalid capabilities, failed to configure device.
-ENOTSUPcapability 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
devPointer to the device structure for the driver instance.
pcktAddress of the packet representation of SMBus transaction.
Return values
-EIOGeneral 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
devPointer to the device structure for the driver instance.
signalThe signal to be send to eSPI controller.
levelThe level of signal requested LOW or HIGH.
Return values
0If successful.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
pcktAddress of the representation of write flash transaction.
Return values
-ENOTSUPeSPI flash logical channel transactions not supported.
-EBUSYeSPI flash channel is not ready or disabled by controller.
-EIOGeneral 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
devPointer to the device structure for the driver instance.
opEnum representing an opcode for peripheral type and write request.
dataRepresents the parameter passed to the LPC peripheral.
Return values
0If successful.
-ENOTSUPif eSPI peripheral is off or not supported.
-EINVALfor 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
devPointer to the device structure for the driver instance.
reqAddress of structure representing a memory, I/O or message write request.
Return values
0If successful.
-ENOTSUPif eSPI controller doesn't support raw packets and instead low memory transactions are handled by controller hardware directly.
-EINVALGeneral input / output error, failed to send over the bus.