espi.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019 Intel Corporation.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_ESPI_H_
#define ZEPHYR_INCLUDE_ESPI_H_
 
#include <errno.h>
 
#include <zephyr/sys/__assert.h>
#include <zephyr/types.h>
#include <zephyr/device.h>
#include <zephyr/sys/slist.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
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),
};
 
enum espi_channel {
 ESPI_CHANNEL_PERIPHERAL = BIT(0),
 ESPI_CHANNEL_VWIRE = BIT(1),
 ESPI_CHANNEL_OOB = BIT(2),
 ESPI_CHANNEL_FLASH = BIT(3),
};
 
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),
};
 
enum espi_pc_event {
 ESPI_PC_EVT_BUS_CHANNEL_READY = BIT(0),
 ESPI_PC_EVT_BUS_MASTER_ENABLE = BIT(1),
};
 
#define ESPI_PERIPHERAL_INDEX_0 0ul
#define ESPI_PERIPHERAL_INDEX_1 1ul
#define ESPI_PERIPHERAL_INDEX_2 2ul
 
#define ESPI_TARGET_TO_CONTROLLER 0ul
#define ESPI_CONTROLLER_TO_TARGET 1ul
 
#define ESPI_VWIRE_SRC_ID0 0ul
#define ESPI_VWIRE_SRC_ID1 1ul
#define ESPI_VWIRE_SRC_ID2 2ul
#define ESPI_VWIRE_SRC_ID3 3ul
#define ESPI_VWIRE_SRC_ID_MAX 4ul
 
#define ESPI_PERIPHERAL_NODATA 0ul
 
#define E8042_START_OPCODE 0x50
#define E8042_MAX_OPCODE 0x5F
 
#define EACPI_START_OPCODE 0x60
#define EACPI_MAX_OPCODE 0x6F
 
#define ECUSTOM_START_OPCODE 0xF0
#define ECUSTOM_MAX_OPCODE 0xFF
 
enum espi_virtual_peripheral {
 ESPI_PERIPHERAL_UART,
 ESPI_PERIPHERAL_8042_KBC,
 ESPI_PERIPHERAL_HOST_IO,
 ESPI_PERIPHERAL_DEBUG_PORT80,
 ESPI_PERIPHERAL_HOST_IO_PVT,
#if defined(CONFIG_ESPI_PERIPHERAL_EC_HOST_CMD)
 ESPI_PERIPHERAL_EC_HOST_CMD,
#endif /* CONFIG_ESPI_PERIPHERAL_EC_HOST_CMD */
};
 
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,
};
 
enum espi_vwire_signal {
 /* Virtual wires that can only be send from controller to target */
 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,
 /* Virtual wires that can only be sent from target to controller */
 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,
 /* System management interrupt */
 ESPI_VWIRE_SIGNAL_SMI,
 /* System control interrupt */
 ESPI_VWIRE_SIGNAL_SCI,
 ESPI_VWIRE_SIGNAL_DNX_ACK,
 ESPI_VWIRE_SIGNAL_SUS_ACK,
 /*
 * Virtual wire GPIOs that can be sent from target to controller for
 * platform specific usage.
 */
 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,
 
 /* Number of Virtual Wires */
 ESPI_VWIRE_SIGNAL_COUNT
};
 
/* USB-C port over current */
#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
 
/* eSPI LPC peripherals. */
enum lpc_peripheral_opcode {
 /* Read transactions */
 E8042_OBF_HAS_CHAR = 0x50,
 E8042_IBF_HAS_CHAR,
 /* Write transactions */
 E8042_WRITE_KB_CHAR,
 E8042_WRITE_MB_CHAR,
 /* Write transactions without input parameters */
 E8042_RESUME_IRQ,
 E8042_PAUSE_IRQ,
 E8042_CLEAR_OBF,
 /* Status transactions */
 E8042_READ_KB_STS,
 E8042_SET_FLAG,
 E8042_CLEAR_FLAG,
 /* ACPI read transactions */
 EACPI_OBF_HAS_CHAR = EACPI_START_OPCODE,
 EACPI_IBF_HAS_CHAR,
 /* ACPI write transactions */
 EACPI_WRITE_CHAR,
 /* ACPI status transactions */
 EACPI_READ_STS,
 EACPI_WRITE_STS,
#if defined(CONFIG_ESPI_PERIPHERAL_ACPI_SHM_REGION)
 /* Shared memory region support to return the ACPI response data */
 EACPI_GET_SHARED_MEMORY,
#endif /* CONFIG_ESPI_PERIPHERAL_ACPI_SHM_REGION */
#if defined(CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE)
 /* Other customized transactions */
 ECUSTOM_HOST_SUBS_INTERRUPT_EN = ECUSTOM_START_OPCODE,
 ECUSTOM_HOST_CMD_GET_PARAM_MEMORY,
 ECUSTOM_HOST_CMD_GET_PARAM_MEMORY_SIZE,
 ECUSTOM_HOST_CMD_SEND_RESULT,
#endif /* CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE */
};
 
/* KBC 8042 event: Input Buffer Full */
#define HOST_KBC_EVT_IBF BIT(0)
/* KBC 8042 event: Output Buffer Empty */
#define HOST_KBC_EVT_OBE BIT(1)
struct espi_evt_data_kbc {
 uint32_t type:8;
 uint32_t data:8;
 uint32_t evt:8;
 uint32_t reserved:8;
};
 
struct espi_evt_data_acpi {
 uint32_t type:8;
 uint32_t data:8;
 uint32_t reserved:16;
};
 
struct espi_event {
 enum espi_bus_event evt_type;
 uint32_t evt_details;
 uint32_t evt_data;
};
 
struct espi_cfg {
 enum espi_io_mode io_caps;
 enum espi_channel channel_caps;
 uint8_t max_freq;
};
 
struct espi_request_packet {
 enum espi_cycle_type cycle_type;
 uint8_t tag;
 uint16_t len;
 uint32_t address;
 uint8_t *data;
};
 
struct espi_oob_packet {
 uint8_t *buf;
 uint16_t len;
};
 
struct espi_flash_packet {
 uint8_t *buf;
 uint32_t flash_addr;
 uint16_t len;
};
 
struct espi_callback;
 
typedef void (*espi_callback_handler_t) (const struct device *dev,
 struct espi_callback *cb,
 struct espi_event espi_evt);
 
struct espi_callback {
 sys_snode_t node;
 
 espi_callback_handler_t handler;
 
 enum espi_bus_event evt_type;
};
typedef int (*espi_api_config)(const struct device *dev, struct espi_cfg *cfg);
typedef bool (*espi_api_get_channel_status)(const struct device *dev,
 enum espi_channel ch);
/* Logical Channel 0 APIs */
typedef int (*espi_api_read_request)(const struct device *dev,
 struct espi_request_packet *req);
typedef int (*espi_api_write_request)(const struct device *dev,
 struct espi_request_packet *req);
typedef int (*espi_api_lpc_read_request)(const struct device *dev,
 enum lpc_peripheral_opcode op,
 uint32_t *data);
typedef int (*espi_api_lpc_write_request)(const struct device *dev,
 enum lpc_peripheral_opcode op,
 uint32_t *data);
/* Logical Channel 1 APIs */
typedef int (*espi_api_send_vwire)(const struct device *dev,
 enum espi_vwire_signal vw,
 uint8_t level);
typedef int (*espi_api_receive_vwire)(const struct device *dev,
 enum espi_vwire_signal vw,
 uint8_t *level);
/* Logical Channel 2 APIs */
typedef int (*espi_api_send_oob)(const struct device *dev,
 struct espi_oob_packet *pckt);
typedef int (*espi_api_receive_oob)(const struct device *dev,
 struct espi_oob_packet *pckt);
/* Logical Channel 3 APIs */
typedef int (*espi_api_flash_read)(const struct device *dev,
 struct espi_flash_packet *pckt);
typedef int (*espi_api_flash_write)(const struct device *dev,
 struct espi_flash_packet *pckt);
typedef int (*espi_api_flash_erase)(const struct device *dev,
 struct espi_flash_packet *pckt);
/* Callbacks and traffic intercept */
typedef int (*espi_api_manage_callback)(const struct device *dev,
 struct espi_callback *callback,
 bool set);
 
__subsystem struct espi_driver_api {
 espi_api_config config;
 espi_api_get_channel_status get_channel_status;
 espi_api_read_request read_request;
 espi_api_write_request write_request;
 espi_api_lpc_read_request read_lpc_request;
 espi_api_lpc_write_request write_lpc_request;
 espi_api_send_vwire send_vwire;
 espi_api_receive_vwire receive_vwire;
 espi_api_send_oob send_oob;
 espi_api_receive_oob receive_oob;
 espi_api_flash_read flash_read;
 espi_api_flash_write flash_write;
 espi_api_flash_erase flash_erase;
 espi_api_manage_callback manage_callback;
};
 
__syscall int espi_config(const struct device *dev, struct espi_cfg *cfg);
 
static inline int z_impl_espi_config(const struct device *dev,
 struct espi_cfg *cfg)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 return api->config(dev, cfg);
}
 
__syscall bool espi_get_channel_status(const struct device *dev,
 enum espi_channel ch);
 
static inline bool z_impl_espi_get_channel_status(const struct device *dev,
 enum espi_channel ch)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 return api->get_channel_status(dev, ch);
}
 
__syscall int espi_read_request(const struct device *dev,
 struct espi_request_packet *req);
 
static inline int z_impl_espi_read_request(const struct device *dev,
 struct espi_request_packet *req)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->read_request) {
 return -ENOTSUP;
 }
 
 return api->read_request(dev, req);
}
 
__syscall int espi_write_request(const struct device *dev,
 struct espi_request_packet *req);
 
static inline int z_impl_espi_write_request(const struct device *dev,
 struct espi_request_packet *req)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->write_request) {
 return -ENOTSUP;
 }
 
 return api->write_request(dev, req);
}
 
__syscall int espi_read_lpc_request(const struct device *dev,
 enum lpc_peripheral_opcode op,
 uint32_t *data);
 
static inline int z_impl_espi_read_lpc_request(const struct device *dev,
 enum lpc_peripheral_opcode op,
 uint32_t *data)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->read_lpc_request) {
 return -ENOTSUP;
 }
 
 return api->read_lpc_request(dev, op, data);
}
 
__syscall int espi_write_lpc_request(const struct device *dev,
 enum lpc_peripheral_opcode op,
 uint32_t *data);
 
static inline int z_impl_espi_write_lpc_request(const struct device *dev,
 enum lpc_peripheral_opcode op,
 uint32_t *data)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->write_lpc_request) {
 return -ENOTSUP;
 }
 
 return api->write_lpc_request(dev, op, data);
}
 
__syscall int espi_send_vwire(const struct device *dev,
 enum espi_vwire_signal signal,
 uint8_t level);
 
static inline int z_impl_espi_send_vwire(const struct device *dev,
 enum espi_vwire_signal signal,
 uint8_t level)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 return api->send_vwire(dev, signal, level);
}
 
__syscall int espi_receive_vwire(const struct device *dev,
 enum espi_vwire_signal signal,
 uint8_t *level);
 
static inline int z_impl_espi_receive_vwire(const struct device *dev,
 enum espi_vwire_signal signal,
 uint8_t *level)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 return api->receive_vwire(dev, signal, level);
}
 
__syscall int espi_send_oob(const struct device *dev,
 struct espi_oob_packet *pckt);
 
static inline int z_impl_espi_send_oob(const struct device *dev,
 struct espi_oob_packet *pckt)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->send_oob) {
 return -ENOTSUP;
 }
 
 return api->send_oob(dev, pckt);
}
 
__syscall int espi_receive_oob(const struct device *dev,
 struct espi_oob_packet *pckt);
 
static inline int z_impl_espi_receive_oob(const struct device *dev,
 struct espi_oob_packet *pckt)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->receive_oob) {
 return -ENOTSUP;
 }
 
 return api->receive_oob(dev, pckt);
}
 
__syscall int espi_read_flash(const struct device *dev,
 struct espi_flash_packet *pckt);
 
static inline int z_impl_espi_read_flash(const struct device *dev,
 struct espi_flash_packet *pckt)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->flash_read) {
 return -ENOTSUP;
 }
 
 return api->flash_read(dev, pckt);
}
 
__syscall int espi_write_flash(const struct device *dev,
 struct espi_flash_packet *pckt);
 
static inline int z_impl_espi_write_flash(const struct device *dev,
 struct espi_flash_packet *pckt)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->flash_write) {
 return -ENOTSUP;
 }
 
 return api->flash_write(dev, pckt);
}
 
__syscall int espi_flash_erase(const struct device *dev,
 struct espi_flash_packet *pckt);
 
static inline int z_impl_espi_flash_erase(const struct device *dev,
 struct espi_flash_packet *pckt)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->flash_erase) {
 return -ENOTSUP;
 }
 
 return api->flash_erase(dev, pckt);
}
 
static inline void espi_init_callback(struct espi_callback *callback,
 espi_callback_handler_t handler,
 enum espi_bus_event evt_type)
{
 __ASSERT(callback, "Callback pointer should not be NULL");
 __ASSERT(handler, "Callback handler pointer should not be NULL");
 
 callback->handler = handler;
 callback->evt_type = evt_type;
}
 
static inline int espi_add_callback(const struct device *dev,
 struct espi_callback *callback)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->manage_callback) {
 return -ENOTSUP;
 }
 
 return api->manage_callback(dev, callback, true);
}
 
static inline int espi_remove_callback(const struct device *dev,
 struct espi_callback *callback)
{
 const struct espi_driver_api *api =
 (const struct espi_driver_api *)dev->api;
 
 if (!api->manage_callback) {
 return -ENOTSUP;
 }
 
 return api->manage_callback(dev, callback, false);
}
 
#ifdef __cplusplus
}
#endif
 
#include <syscalls/espi.h>
#endif /* ZEPHYR_INCLUDE_ESPI_H_ */