eSPI SAF

Interfaces for eSPI SAF (Serial Attached Flash) controllers. More...

Data Structures
struct	espi_saf_cfg
	eSPI SAF configuration parameters More...
struct	espi_saf_packet
	eSPI SAF transaction packet format More...
struct	espi_saf_driver_api
	@driver_ops{eSPI SAF} More...

Enumerations
enum	espi_taf_event { ESPI_TAF_EVENT_NO_REQUEST = 0 , ESPI_TAF_EVENT_HOST_REQUEST , ESPI_TAF_EVENT_EC0_REQUEST , ESPI_TAF_EVENT_MAX_REQUEST }
	eSPI TAF notification type. More...

Functions
int	espi_saf_config (const struct device *dev, const struct espi_saf_cfg *cfg)
	Configure operation of an 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 an erase 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.
typedef int(*	espi_saf_api_config) (const struct device *dev, const struct espi_saf_cfg *cfg)
	@def_driverbackendgroup{eSPI SAF,espi_saf_interface}
typedef int(*	espi_saf_api_set_protection_regions) (const struct device *dev, const struct espi_saf_protection *pr)
	Callback API to set one or more SAF protection regions.
typedef int(*	espi_saf_api_activate) (const struct device *dev)
	Callback API to activate the SAF block.
typedef bool(*	espi_saf_api_get_channel_status) (const struct device *dev)
	Callback API to query if SAF is ready.
typedef int(*	espi_saf_api_flash_read) (const struct device *dev, struct espi_saf_packet *pckt)
	Callback API to send a read request for slave attached flash.
typedef int(*	espi_saf_api_flash_write) (const struct device *dev, struct espi_saf_packet *pckt)
	Callback API to send a write request for slave attached flash.
typedef int(*	espi_saf_api_flash_erase) (const struct device *dev, struct espi_saf_packet *pckt)
	Callback API to send an erase request for slave attached flash.
typedef int(*	espi_saf_api_flash_unsuccess) (const struct device *dev, struct espi_saf_packet *pckt)
	Callback API to respond unsuccessful completion for slave attached flash.
typedef int(*	espi_saf_api_manage_callback) (const struct device *dev, struct espi_callback *callback, bool set)
	Callback API to manage (add or remove) application callbacks.

Detailed Description

Interfaces for eSPI SAF (Serial Attached Flash) controllers.

Since

2.6

Version

0.8.0

Typedef Documentation

espi_saf_api_activate

typedef int(* espi_saf_api_activate) (const struct device *dev)

#include <espi_saf.h>

Callback API to activate the SAF block.

See espi_saf_activate() for argument description.

espi_saf_api_config

typedef int(* espi_saf_api_config) (const struct device *dev, const struct espi_saf_cfg *cfg)

#include <espi_saf.h>

@def_driverbackendgroup{eSPI SAF,espi_saf_interface}

Callback API to configure the eSPI SAF controller. See espi_saf_config() for argument description.

espi_saf_api_flash_erase

typedef int(* espi_saf_api_flash_erase) (const struct device *dev, struct espi_saf_packet *pckt)

#include <espi_saf.h>

Callback API to send an erase request for slave attached flash.

See espi_saf_flash_erase() for argument description.

espi_saf_api_flash_read

typedef int(* espi_saf_api_flash_read) (const struct device *dev, struct espi_saf_packet *pckt)

#include <espi_saf.h>

Callback API to send a read request for slave attached flash.

See espi_saf_flash_read() for argument description.

espi_saf_api_flash_unsuccess

typedef int(* espi_saf_api_flash_unsuccess) (const struct device *dev, struct espi_saf_packet *pckt)

#include <espi_saf.h>

Callback API to respond unsuccessful completion for slave attached flash.

See espi_saf_flash_unsuccess() for argument description.

espi_saf_api_flash_write

typedef int(* espi_saf_api_flash_write) (const struct device *dev, struct espi_saf_packet *pckt)

#include <espi_saf.h>

Callback API to send a write request for slave attached flash.

See espi_saf_flash_write() for argument description.

espi_saf_api_get_channel_status

typedef bool(* espi_saf_api_get_channel_status) (const struct device *dev)

#include <espi_saf.h>

Callback API to query if SAF is ready.

See espi_saf_get_channel_status() for argument description.

espi_saf_api_manage_callback

typedef int(* espi_saf_api_manage_callback) (const struct device *dev, struct espi_callback *callback, bool set)

#include <espi_saf.h>

Callback API to manage (add or remove) application callbacks.

See espi_saf_add_callback() and espi_saf_remove_callback() for argument description.

espi_saf_api_set_protection_regions

typedef int(* espi_saf_api_set_protection_regions) (const struct device *dev, const struct espi_saf_protection *pr)

#include <espi_saf.h>

Callback API to set one or more SAF protection regions.

See espi_saf_set_protection_regions() for argument description.

Enumeration Type Documentation

espi_taf_event

enum espi_taf_event

#include <espi_saf.h>

eSPI TAF notification type.

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

eSPI TAF notification event details indicates the event which triggered the callback.

Enumerator
ESPI_TAF_EVENT_NO_REQUEST	TAF generic event.
ESPI_TAF_EVENT_HOST_REQUEST	TAF flash access request was from the Host eSPI controller.
ESPI_TAF_EVENT_EC0_REQUEST	TAF flash access request was from EC firmware portal 0.
ESPI_TAF_EVENT_MAX_REQUEST	maximum request

Function Documentation

espi_saf_activate()

int espi_saf_activate

(

const struct device *

dev

)

#include <espi_saf.h>

Activate SAF block.

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

Parameters

dev	Pointer to the device structure for the driver instance.

Return values

0	If successful
-EINVAL	if failed to activate SAF.

espi_saf_add_callback()

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

inlinestatic

#include <espi_saf.h>

Add an application callback.

Parameters

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

Returns

0 if successful, negative errno code on failure.

Note

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

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

espi_saf_config()

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

#include <espi_saf.h>

Configure operation of an eSPI controller.

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

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

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

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

Parameters

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

Return values

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

espi_saf_flash_erase()

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

#include <espi_saf.h>

Sends an erase request packet for slave attached flash.

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

Parameters

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

Return values

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

espi_saf_flash_read()

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

#include <espi_saf.h>

Sends a read request packet for slave attached flash.

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

Parameters

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

Return values

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

espi_saf_flash_unsuccess()

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

#include <espi_saf.h>

Response unsuccessful completion for slave attached flash.

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

Parameters

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

Return values

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

espi_saf_flash_write()

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

#include <espi_saf.h>

Sends a write request packet for slave attached flash.

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

Parameters

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

Return values

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

espi_saf_get_channel_status()

bool espi_saf_get_channel_status

(

const struct device *

dev

)

#include <espi_saf.h>

Query to see if SAF is ready.

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

Parameters

dev	Pointer to the device structure for the driver instance.

Return values

true	If eSPI SAF is ready.
false	otherwise.

espi_saf_init_callback()

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

inlinestatic

#include <espi_saf.h>

Callback model.

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

Helper to initialize a struct espi_callback properly.

Parameters

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

espi_saf_remove_callback()

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

inlinestatic

#include <espi_saf.h>

Remove an application callback.

Parameters

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

Returns

0 if successful, negative errno code on failure.

Warning

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

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

espi_saf_set_protection_regions()

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

#include <espi_saf.h>

Set one or more SAF protection regions.

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

Parameters

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

Return values

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