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_SLAVE_TO_MASTER     0ul
#define ESPI_MASTER_TO_SLAVE     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 master to slave */
        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 slave to master */
        ESPI_VWIRE_SIGNAL_PME,
        ESPI_VWIRE_SIGNAL_WAKE,
        ESPI_VWIRE_SIGNAL_OOB_RST_ACK,
        ESPI_VWIRE_SIGNAL_SLV_BOOT_STS,
        ESPI_VWIRE_SIGNAL_ERR_NON_FATAL,
        ESPI_VWIRE_SIGNAL_ERR_FATAL,
        ESPI_VWIRE_SIGNAL_SLV_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 slave to master for
         * platform specific usage.
         */
        ESPI_VWIRE_SIGNAL_SLV_GPIO_0,
        ESPI_VWIRE_SIGNAL_SLV_GPIO_1,
        ESPI_VWIRE_SIGNAL_SLV_GPIO_2,
        ESPI_VWIRE_SIGNAL_SLV_GPIO_3,
        ESPI_VWIRE_SIGNAL_SLV_GPIO_4,
        ESPI_VWIRE_SIGNAL_SLV_GPIO_5,
        ESPI_VWIRE_SIGNAL_SLV_GPIO_6,
        ESPI_VWIRE_SIGNAL_SLV_GPIO_7,
 
        /* USB-C port over current */
        ESPI_VWIRE_SIGNAL_OCB_0,
        ESPI_VWIRE_SIGNAL_OCB_1,
        ESPI_VWIRE_SIGNAL_OCB_2,
        ESPI_VWIRE_SIGNAL_OCB_3,
 
        /* Number of Virtual Wires */
        ESPI_VWIRE_SIGNAL_COUNT
};
 
/* 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_ */