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_TAF_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
 
/* eSPI specification defines eSPI target and eSPI controller terms
 * note that sometimes eSPI controller is also referred as eSPI host
 */
 
#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,
        ESPI_PERIPHERAL_HOST_IO_PVT2,
        ESPI_PERIPHERAL_HOST_IO_PVT3,
#if defined(CONFIG_ESPI_PERIPHERAL_EC_HOST_CMD) || defined(__DOXYGEN__)
        ESPI_PERIPHERAL_EC_HOST_CMD,
#endif /* CONFIG_ESPI_PERIPHERAL_EC_HOST_CMD */
};

enum espi_interrupt_flags {
        ESPI_BUS_EVENTS = BIT(0),
        ESPI_VIRTUAL_WIRE_CHANNEL_EVENTS = BIT(1),
        ESPI_OOB_CHANNEL_EVENTS = BIT(2),
        ESPI_FLASH_CHANNEL_EVENTS = BIT(3),

        ESPI_PERIPHERAL_UART_EVENTS = BIT(4),
        ESPI_PERIPHERAL_DEBUG_PORT80_EVENTS = BIT(5),
        ESPI_PERIPHERAL_8042_KBC_EVENTS = BIT(6),
        ESPI_PERIPHERAL_HOST_IO_EVENTS = BIT(7),
        ESPI_PERIPHERAL_SHARED_MEMORY_EVENTS = BIT(8),
};

#define ESPI_INT_ALL_MASK  (ESPI_BUS_EVENTS | ESPI_VIRTUAL_WIRE_CHANNEL_EVENTS | \
                        ESPI_OOB_CHANNEL_EVENTS | ESPI_FLASH_CHANNEL_EVENTS | \
                        ESPI_PERIPHERAL_DEBUG_PORT80_EVENTS | ESPI_PERIPHERAL_8042_KBC_EVENTS | \
                        ESPI_PERIPHERAL_HOST_IO_EVENTS | ESPI_PERIPHERAL_SHARED_MEMORY_EVENTS)

#define ESPI_INT_BUS_ONLY_MASK (ESPI_BUS_EVENTS | ESPI_VIRTUAL_WIRE_CHANNEL_EVENTS | \
                        ESPI_OOB_CHANNEL_EVENTS | ESPI_FLASH_CHANNEL_EVENTS)

#define ESPI_INT_NONE_MASK      0U
 

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,     
        ESPI_VWIRE_SIGNAL_SMI,              
        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, 

        ESPI_VWIRE_SIGNAL_COUNT
};

#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

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) || defined(__DOXYGEN__)
        EACPI_GET_SHARED_MEMORY,
#endif /* CONFIG_ESPI_PERIPHERAL_ACPI_SHM_REGION */
#if defined(CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE) || defined(__DOXYGEN__)
        /* 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 */
};

#define HOST_KBC_EVT_IBF BIT(0)
#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;
};

#define ESPI_EVENT_DATA_ACPI_TYPE_HOST_TO_EC_DATA    0
#define ESPI_EVENT_DATA_ACPI_TYPE_HOST_TO_EC_CMD     1U
#define ESPI_EVENT_DATA_ACPI_TYPE_HOST_RD_EC_TO_HOST 2U

struct espi_evt_data_pvt {
        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);
 
/* eSPI interrupt control */
typedef int (*espi_api_interrupt_configure)(const struct device *dev,
                                            uint32_t espi_interrupt_flags,
                                            uint32_t espi_interrupt_vendor);
 
__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;
        espi_api_interrupt_configure interrupt_config;
};


__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)
{
        return DEVICE_API_GET(espi, dev)->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)
{
        return DEVICE_API_GET(espi, dev)->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 = DEVICE_API_GET(espi, dev);
 
        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 = DEVICE_API_GET(espi, dev);
 
        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 = DEVICE_API_GET(espi, dev);
 
        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 = DEVICE_API_GET(espi, dev);
 
        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)
{
        return DEVICE_API_GET(espi, dev)->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)
{
        return DEVICE_API_GET(espi, dev)->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 = DEVICE_API_GET(espi, dev);
 
        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 = DEVICE_API_GET(espi, dev);
 
        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 = DEVICE_API_GET(espi, dev);
 
        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 = DEVICE_API_GET(espi, dev);
 
        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 = DEVICE_API_GET(espi, dev);
 
        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 = DEVICE_API_GET(espi, dev);
 
        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 = DEVICE_API_GET(espi, dev);
 
        if (!api->manage_callback) {
                return -ENOTSUP;
        }
 
        return api->manage_callback(dev, callback, false);
}

static inline int espi_interrupt_config(const struct device *dev, uint32_t espi_flags,
                                        uint32_t espi_vendor_flags)
{
        const struct espi_driver_api *api = DEVICE_API_GET(espi, dev);
 
        if (!api->interrupt_config) {
                return -ENOTSUP;
        }
 
        return api->interrupt_config(dev, espi_flags, espi_vendor_flags);
}
#ifdef __cplusplus
}
#endif

#include <zephyr/syscalls/espi.h>
#endif /* ZEPHYR_INCLUDE_ESPI_H_ */