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...

Functions
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

Interfaces for eSPI SAF (Serial Attached Flash) controllers.

Function Documentation

espi_saf_activate()

int espi_saf_activate

(

const struct device *

dev

)

#include <zephyr/drivers/espi_saf.h>

Activate SAF block.

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

Parameters

dev	Pointer to the device structure for the driver instance.

Return values

0	If successful
-EINVAL	if failed to activate SAF.

espi_saf_add_callback()

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

inlinestatic

#include <zephyr/drivers/espi_saf.h>

Add an application callback.

Parameters

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

Returns

0 if successful, negative errno code on failure.

Note

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

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

espi_saf_config()

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

#include <zephyr/drivers/espi_saf.h>

Configure operation of a eSPI controller.

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

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

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

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

Parameters

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

Return values

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

espi_saf_flash_erase()

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

#include <zephyr/drivers/espi_saf.h>

Sends a write request packet for slave attached flash.

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

Parameters

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

Return values

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

espi_saf_flash_read()

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

#include <zephyr/drivers/espi_saf.h>

Sends a read request packet for slave attached flash.

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

Parameters

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

Return values

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

espi_saf_flash_unsuccess()

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

#include <zephyr/drivers/espi_saf.h>

Response unsuccessful completion for slave attached flash.

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

Parameters

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

Return values

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

espi_saf_flash_write()

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

#include <zephyr/drivers/espi_saf.h>

Sends a write request packet for slave attached flash.

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

Parameters

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

Return values

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

espi_saf_get_channel_status()

bool espi_saf_get_channel_status

(

const struct device *

dev

)

#include <zephyr/drivers/espi_saf.h>

Query to see if SAF is ready.

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

Parameters

dev	Pointer to the device structure for the driver instance.

Return values

true	If eSPI SAF is ready.
false	otherwise.

espi_saf_init_callback()

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

inlinestatic

#include <zephyr/drivers/espi_saf.h>

Callback model.

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

Helper to initialize a struct espi_callback properly.

Parameters

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

espi_saf_remove_callback()

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

inlinestatic

#include <zephyr/drivers/espi_saf.h>

Remove an application callback.

Parameters

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

Returns

0 if successful, negative errno code on failure.

Warning

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

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

espi_saf_set_protection_regions()

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

#include <zephyr/drivers/espi_saf.h>

Set one or more SAF protection regions.

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

Parameters

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

Return values

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