LCOV - code coverage report
Current view: top level - zephyr/drivers - espi.h Coverage Total Hit
Test: new.info Lines: 100.0 % 66 66
Test Date: 2025-09-05 16:43:28

            Line data    Source code
       1            1 : /*
       2              :  * Copyright (c) 2019 Intel Corporation.
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @file
       9              :  * @brief Public APIs for eSPI driver
      10              :  */
      11              : 
      12              : #ifndef ZEPHYR_INCLUDE_ESPI_H_
      13              : #define ZEPHYR_INCLUDE_ESPI_H_
      14              : 
      15              : #include <errno.h>
      16              : 
      17              : #include <zephyr/sys/__assert.h>
      18              : #include <zephyr/types.h>
      19              : #include <zephyr/device.h>
      20              : #include <zephyr/sys/slist.h>
      21              : 
      22              : #ifdef __cplusplus
      23              : extern "C" {
      24              : #endif
      25              : 
      26              : /**
      27              :  * @brief eSPI Driver APIs
      28              :  * @defgroup espi_interface ESPI Driver APIs
      29              :  * @ingroup io_interfaces
      30              :  * @{
      31              :  */
      32              : 
      33              : /**
      34              :  * @brief eSPI I/O mode capabilities
      35              :  */
      36            1 : enum espi_io_mode {
      37              :         /** Single data line mode (traditional SPI) */
      38              :         ESPI_IO_MODE_SINGLE_LINE = BIT(0),
      39              :         /** Dual data line mode */
      40              :         ESPI_IO_MODE_DUAL_LINES = BIT(1),
      41              :         /** Quad data line mode */
      42              :         ESPI_IO_MODE_QUAD_LINES = BIT(2),
      43              : };
      44              : 
      45              : /**
      46              :  * @code
      47              :  *+----------------------------------------------------------------------+
      48              :  *|                                                                      |
      49              :  *|  eSPI controller                     +-------------+                 |
      50              :  *|                      +-----------+   |    Power    |   +----------+  |
      51              :  *|                      |Out of band|   |  management |   |   GPIO   |  |
      52              :  *|  +------------+      |processor  |   |  controller |   |  sources |  |
      53              :  *|  |  SPI flash |      +-----------+   +-------------+   +----------+  |
      54              :  *|  | controller |            |                |               |        |
      55              :  *|  +------------+            |                |               |        |
      56              :  *|   |  |    |                +--------+       +---------------+        |
      57              :  *|   |  |    |                         |               |                |
      58              :  *|   |  |    +-----+   +--------+   +----------+  +----v-----+          |
      59              :  *|   |  |          |   |  LPC   |   | Tunneled |  | Tunneled |          |
      60              :  *|   |  |          |   | bridge |   |  SMBus   |  |   GPIO   |          |
      61              :  *|   |  |          |   +--------+   +----------+  +----------+          |
      62              :  *|   |  |          |        |             |             |               |
      63              :  *|   |  |          |        ------+       |             |               |
      64              :  *|   |  |          |              |       |             |               |
      65              :  *|   |  |   +------v-----+    +---v-------v-------------v----+          |
      66              :  *|   |  |   | eSPI Flash |    |    eSPI protocol block       |          |
      67              :  *|   |  |   |   access   +--->+                              |          |
      68              :  *|   |  |   +------------+    +------------------------------+          |
      69              :  *|   |  |                             |                                 |
      70              :  *|   |  +-----------+                 |                                 |
      71              :  *|   |              v                 v                                 |
      72              :  *|   |           XXXXXXXXXXXXXXXXXXXXXXX                                |
      73              :  *|   |            XXXXXXXXXXXXXXXXXXXXX                                 |
      74              :  *|   |             XXXXXXXXXXXXXXXXXXX                                  |
      75              :  *+----------------------------------------------------------------------+
      76              :  *   |                      |
      77              :  *   v             +-----------------+
      78              :  * +---------+     |  |   |   |   |  |
      79              :  * |  Flash  |     |  |   |   |   |  |
      80              :  * +---------+     |  +   +   +   +  |    eSPI bus
      81              :  *                 | CH0 CH1 CH2 CH3 |    (logical channels)
      82              :  *                 |  +   +   +   +  |
      83              :  *                 |  |   |   |   |  |
      84              :  *                 +-----------------+
      85              :  *                          |
      86              :  *+-----------------------------------------------------------------------+
      87              :  *|  eSPI target                                                          |
      88              :  *|                                                                       |
      89              :  *|       CH0         |     CH1      |      CH2      |    CH3             |
      90              :  *|   eSPI endpoint   |    VWIRE     |      OOB      |   Flash            |
      91              :  *+-----------------------------------------------------------------------+
      92              :  * @endcode
      93              :  */
      94              : 
      95              : /**
      96              :  * @brief eSPI channel.
      97              :  *
      98              :  * Identifies each eSPI logical channel supported by eSPI controller
      99              :  * Each channel allows independent traffic, but the assignment of channel
     100              :  * type to channel number is fixed.
     101              :  *
     102              :  * Note that generic commands are not associated with any channel, so traffic
     103              :  * over eSPI can occur if all channels are disabled or not ready
     104              :  */
     105            1 : enum espi_channel {
     106              :         ESPI_CHANNEL_PERIPHERAL = BIT(0), /**< Peripheral channel (channel 0) */
     107              :         ESPI_CHANNEL_VWIRE      = BIT(1), /**< Virtual Wire channel (channel 1) */
     108              :         ESPI_CHANNEL_OOB        = BIT(2), /**< Out-of-Band channel (channel 2) */
     109              :         ESPI_CHANNEL_FLASH      = BIT(3), /**< Flash Access channel (channel 3) */
     110              : };
     111              : 
     112              : /**
     113              :  * @brief eSPI bus event.
     114              :  *
     115              :  * eSPI bus event to indicate events for which user can register callbacks
     116              :  */
     117            1 : enum espi_bus_event {
     118              :         /** Indicates the eSPI bus was reset either via eSPI reset pin.
     119              :          * eSPI drivers should convey the eSPI reset status to eSPI driver clients
     120              :          * following eSPI specification reset pin convention:
     121              :          * 0-eSPI bus in reset, 1-eSPI bus out-of-reset
     122              :          *
     123              :          * Note: There is no need to send this callback for in-band reset.
     124              :          */
     125              :         ESPI_BUS_RESET                      = BIT(0),
     126              : 
     127              :         /** Indicates the eSPI HW has received channel enable notification from eSPI host,
     128              :          * once the eSPI channel is signaled as ready to the eSPI host,
     129              :          * eSPI drivers should convey the eSPI channel ready to eSPI driver client via this event.
     130              :          */
     131              :         ESPI_BUS_EVENT_CHANNEL_READY        = BIT(1),
     132              : 
     133              :         /** Indicates the eSPI HW has received a virtual wire message from eSPI host.
     134              :          * eSPI drivers should convey the eSPI virtual wire latest status.
     135              :          */
     136              :         ESPI_BUS_EVENT_VWIRE_RECEIVED       = BIT(2),
     137              : 
     138              :         /** Indicates the eSPI HW has received a Out-of-band packet from eSPI host.
     139              :          */
     140              :         ESPI_BUS_EVENT_OOB_RECEIVED         = BIT(3),
     141              : 
     142              :         /** Indicates the eSPI HW has received a peripheral eSPI host event.
     143              :          * eSPI drivers should convey the peripheral type.
     144              :          */
     145              :         ESPI_BUS_PERIPHERAL_NOTIFICATION    = BIT(4),
     146              :         /** Indicates the eSPI HW has received a Target Attached Flash (TAF) notification event */
     147              :         ESPI_BUS_TAF_NOTIFICATION           = BIT(5),
     148              : };
     149              : 
     150              : /**
     151              :  * @brief eSPI peripheral channel events.
     152              :  *
     153              :  * eSPI peripheral channel event types to signal users.
     154              :  */
     155            1 : enum espi_pc_event {
     156              :         /** Bus channel ready event */
     157              :         ESPI_PC_EVT_BUS_CHANNEL_READY = BIT(0),
     158              :         /** Bus master enable event */
     159              :         ESPI_PC_EVT_BUS_MASTER_ENABLE = BIT(1),
     160              : };
     161              : 
     162              : /**
     163              :  * @cond INTERNAL_HIDDEN
     164              :  *
     165              :  */
     166              : #define ESPI_PERIPHERAL_INDEX_0  0ul
     167              : #define ESPI_PERIPHERAL_INDEX_1  1ul
     168              : #define ESPI_PERIPHERAL_INDEX_2  2ul
     169              : 
     170              : #define ESPI_TARGET_TO_CONTROLLER   0ul
     171              : #define ESPI_CONTROLLER_TO_TARGET   1ul
     172              : 
     173              : #define ESPI_VWIRE_SRC_ID0       0ul
     174              : #define ESPI_VWIRE_SRC_ID1       1ul
     175              : #define ESPI_VWIRE_SRC_ID2       2ul
     176              : #define ESPI_VWIRE_SRC_ID3       3ul
     177              : #define ESPI_VWIRE_SRC_ID_MAX    4ul
     178              : 
     179              : #define ESPI_PERIPHERAL_NODATA   0ul
     180              : 
     181              : #define E8042_START_OPCODE      0x50
     182              : #define E8042_MAX_OPCODE        0x5F
     183              : 
     184              : #define EACPI_START_OPCODE      0x60
     185              : #define EACPI_MAX_OPCODE        0x6F
     186              : 
     187              : #define ECUSTOM_START_OPCODE    0xF0
     188              : #define ECUSTOM_MAX_OPCODE      0xFF
     189              : 
     190              : /** @endcond */
     191              : 
     192              : /**
     193              :  * @brief eSPI peripheral notification type.
     194              :  *
     195              :  * eSPI peripheral notification event details to indicate which peripheral
     196              :  * trigger the eSPI callback
     197              :  */
     198            1 : enum espi_virtual_peripheral {
     199              :         /** UART peripheral */
     200              :         ESPI_PERIPHERAL_UART,
     201              :         /** 8042 Keyboard Controller peripheral */
     202              :         ESPI_PERIPHERAL_8042_KBC,
     203              :         /** Host I/O peripheral */
     204              :         ESPI_PERIPHERAL_HOST_IO,
     205              :         /** Debug Port 80 peripheral */
     206              :         ESPI_PERIPHERAL_DEBUG_PORT80,
     207              :         /** Private Host I/O peripheral */
     208              :         ESPI_PERIPHERAL_HOST_IO_PVT,
     209              :         /** Private Host I/O peripheral 2 */
     210              :         ESPI_PERIPHERAL_HOST_IO_PVT2,
     211              :         /** Private Host I/O peripheral 3 */
     212              :         ESPI_PERIPHERAL_HOST_IO_PVT3,
     213              : #if defined(CONFIG_ESPI_PERIPHERAL_EC_HOST_CMD) || defined(__DOXYGEN__)
     214              :         /**
     215              :          * Embedded Controller Host Command peripheral
     216              :          * @kconfig_dep{CONFIG_ESPI_PERIPHERAL_EC_HOST_CMD}
     217              :          */
     218              :         ESPI_PERIPHERAL_EC_HOST_CMD,
     219              : #endif /* CONFIG_ESPI_PERIPHERAL_EC_HOST_CMD */
     220              : };
     221              : 
     222              : /**
     223              :  * @brief eSPI cycle types supported over eSPI peripheral channel
     224              :  */
     225            1 : enum espi_cycle_type {
     226              :         /** 32-bit memory read cycle */
     227              :         ESPI_CYCLE_MEMORY_READ32,
     228              :         /** 64-bit memory read cycle */
     229              :         ESPI_CYCLE_MEMORY_READ64,
     230              :         /** 32-bit memory write cycle */
     231              :         ESPI_CYCLE_MEMORY_WRITE32,
     232              :         /** 64-bit memory write cycle */
     233              :         ESPI_CYCLE_MEMORY_WRITE64,
     234              :         /** Message cycle with no data */
     235              :         ESPI_CYCLE_MESSAGE_NODATA,
     236              :         /** Message cycle with data */
     237              :         ESPI_CYCLE_MESSAGE_DATA,
     238              :         /** Successful completion with no data */
     239              :         ESPI_CYCLE_OK_COMPLETION_NODATA,
     240              :         /** Successful completion with data */
     241              :         ESPI_CYCLE_OKCOMPLETION_DATA,
     242              :         /** Unsuccessful completion with no data */
     243              :         ESPI_CYCLE_NOK_COMPLETION_NODATA,
     244              : };
     245              : 
     246              : /**
     247              :  * @brief eSPI system platform signals that can be sent or received through
     248              :  * virtual wire channel
     249              :  */
     250            1 : enum espi_vwire_signal {
     251              :         /* Virtual wires that can only be send from controller to target */
     252              :         ESPI_VWIRE_SIGNAL_SLP_S3,        /**< Sleep S3 state signal */
     253              :         ESPI_VWIRE_SIGNAL_SLP_S4,        /**< Sleep S4 state signal */
     254              :         ESPI_VWIRE_SIGNAL_SLP_S5,        /**< Sleep S5 state signal */
     255              :         ESPI_VWIRE_SIGNAL_OOB_RST_WARN,  /**< Out-of-band reset warning signal */
     256              :         ESPI_VWIRE_SIGNAL_PLTRST,        /**< Platform reset signal */
     257              :         ESPI_VWIRE_SIGNAL_SUS_STAT,      /**< Suspend status signal */
     258              :         ESPI_VWIRE_SIGNAL_NMIOUT,        /**< NMI output signal */
     259              :         ESPI_VWIRE_SIGNAL_SMIOUT,        /**< SMI output signal */
     260              :         ESPI_VWIRE_SIGNAL_HOST_RST_WARN, /**< Host reset warning signal */
     261              :         ESPI_VWIRE_SIGNAL_SLP_A,         /**< Sleep A state signal */
     262              :         ESPI_VWIRE_SIGNAL_SUS_PWRDN_ACK, /**< Suspend power down acknowledge signal */
     263              :         ESPI_VWIRE_SIGNAL_SUS_WARN,      /**< Suspend warning signal */
     264              :         ESPI_VWIRE_SIGNAL_SLP_WLAN,      /**< Sleep WLAN signal */
     265              :         ESPI_VWIRE_SIGNAL_SLP_LAN,       /**< Sleep LAN signal */
     266              :         ESPI_VWIRE_SIGNAL_HOST_C10,      /**< Host C10 state signal */
     267              :         ESPI_VWIRE_SIGNAL_DNX_WARN,      /**< DNX (Debug and eXception) warning signal */
     268              : 
     269              :         /* Virtual wires that can only be sent from target to controller */
     270              :         ESPI_VWIRE_SIGNAL_PME,              /**< Power Management Event signal */
     271              :         ESPI_VWIRE_SIGNAL_WAKE,             /**< Wake signal */
     272              :         ESPI_VWIRE_SIGNAL_OOB_RST_ACK,      /**< Out-of-band reset acknowledge signal */
     273              :         ESPI_VWIRE_SIGNAL_TARGET_BOOT_STS,  /**< Target boot status signal */
     274              :         ESPI_VWIRE_SIGNAL_ERR_NON_FATAL,    /**< Non-fatal error signal */
     275              :         ESPI_VWIRE_SIGNAL_ERR_FATAL,        /**< Fatal error signal */
     276              :         ESPI_VWIRE_SIGNAL_TARGET_BOOT_DONE, /**< Target boot done signal */
     277              :         ESPI_VWIRE_SIGNAL_HOST_RST_ACK,     /**< Host reset acknowledge signal */
     278              :         ESPI_VWIRE_SIGNAL_RST_CPU_INIT,     /**< Reset CPU initialization signal */
     279              :         ESPI_VWIRE_SIGNAL_SMI,              /**< System Management Interrupt signal */
     280              :         ESPI_VWIRE_SIGNAL_SCI,              /**< System Control Interrupt signal */
     281              :         ESPI_VWIRE_SIGNAL_DNX_ACK,          /**< DNX acknowledge signal */
     282              :         ESPI_VWIRE_SIGNAL_SUS_ACK,          /**< Suspend acknowledge signal */
     283              : 
     284              :         /*
     285              :          * Virtual wire GPIOs that can be sent from target to controller for
     286              :          * platform specific usage.
     287              :          */
     288              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_0,  /**< Target GPIO 0 signal */
     289              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_1,  /**< Target GPIO 1 signal */
     290              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_2,  /**< Target GPIO 2 signal */
     291              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_3,  /**< Target GPIO 3 signal */
     292              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_4,  /**< Target GPIO 4 signal */
     293              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_5,  /**< Target GPIO 5 signal */
     294              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_6,  /**< Target GPIO 6 signal */
     295              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_7,  /**< Target GPIO 7 signal */
     296              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_8,  /**< Target GPIO 8 signal */
     297              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_9,  /**< Target GPIO 9 signal */
     298              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_10, /**< Target GPIO 10 signal */
     299              :         ESPI_VWIRE_SIGNAL_TARGET_GPIO_11, /**< Target GPIO 11 signal */
     300              : 
     301              :         /** Number of Virtual Wire signals */
     302              :         ESPI_VWIRE_SIGNAL_COUNT
     303              : };
     304              : 
     305              : /**
     306              :  * @name USB-C port over current signal aliases
     307              :  * @{
     308              :  */
     309              : /** USB-C port 0 over current signal */
     310            1 : #define ESPI_VWIRE_SIGNAL_OCB_0 ESPI_VWIRE_SIGNAL_TARGET_GPIO_0
     311              : /** USB-C port 1 over current signal */
     312            1 : #define ESPI_VWIRE_SIGNAL_OCB_1 ESPI_VWIRE_SIGNAL_TARGET_GPIO_1
     313              : /** USB-C port 2 over current signal */
     314            1 : #define ESPI_VWIRE_SIGNAL_OCB_2 ESPI_VWIRE_SIGNAL_TARGET_GPIO_2
     315              : /** USB-C port 3 over current signal */
     316            1 : #define ESPI_VWIRE_SIGNAL_OCB_3 ESPI_VWIRE_SIGNAL_TARGET_GPIO_3
     317              : /** @} */
     318              : 
     319              : /**
     320              :  * @brief eSPI LPC peripheral opcodes
     321              :  *
     322              :  * Opcodes for LPC peripheral operations that are tunneled through eSPI.
     323              :  * These opcodes are used to interact with legacy LPC devices.
     324              :  */
     325            1 : enum lpc_peripheral_opcode {
     326              :         /* Read transactions */
     327              :         E8042_OBF_HAS_CHAR = 0x50, /**< Check if 8042 output buffer has character */
     328              :         E8042_IBF_HAS_CHAR,        /**< Check if 8042 input buffer has character */
     329              :         /* Write transactions */
     330              :         E8042_WRITE_KB_CHAR, /**< Write character to 8042 keyboard buffer */
     331              :         E8042_WRITE_MB_CHAR, /**< Write character to 8042 mouse buffer */
     332              :         /* Write transactions without input parameters */
     333              :         E8042_RESUME_IRQ, /**< Resume 8042 interrupt processing */
     334              :         E8042_PAUSE_IRQ,  /**< Pause 8042 interrupt processing */
     335              :         E8042_CLEAR_OBF,  /**< Clear 8042 output buffer */
     336              :         /* Status transactions */
     337              :         E8042_READ_KB_STS, /**< Read 8042 keyboard status */
     338              :         E8042_SET_FLAG,    /**< Set 8042 flag */
     339              :         E8042_CLEAR_FLAG,  /**< Clear 8042 flag */
     340              :         /* ACPI read transactions */
     341              :         EACPI_OBF_HAS_CHAR = EACPI_START_OPCODE, /**< Check if ACPI output buffer has character */
     342              :         EACPI_IBF_HAS_CHAR,                      /**< Check if ACPI input buffer has character */
     343              :         /* ACPI write transactions */
     344              :         EACPI_WRITE_CHAR, /**< Write character to ACPI output buffer */
     345              :         /* ACPI status transactions */
     346              :         EACPI_READ_STS,  /**< Read ACPI status */
     347              :         EACPI_WRITE_STS, /**< Write ACPI status */
     348              : #if defined(CONFIG_ESPI_PERIPHERAL_ACPI_SHM_REGION) || defined(__DOXYGEN__)
     349              :         /**
     350              :          * Shared memory region support to return the ACPI response data
     351              :          * @kconfig_dep{CONFIG_ESPI_PERIPHERAL_ACPI_SHM_REGION}
     352              :          */
     353              :         EACPI_GET_SHARED_MEMORY,
     354              : #endif /* CONFIG_ESPI_PERIPHERAL_ACPI_SHM_REGION */
     355              : #if defined(CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE) || defined(__DOXYGEN__)
     356              :         /* Other customized transactions */
     357              :         /**
     358              :          * Enable host subsystem interrupt (custom)
     359              :          * @kconfig_dep{CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE}
     360              :          */
     361              :         ECUSTOM_HOST_SUBS_INTERRUPT_EN = ECUSTOM_START_OPCODE,
     362              :         /**
     363              :          * Get host command parameter memory (custom)
     364              :          * @kconfig_dep{CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE}
     365              :          */
     366              :         ECUSTOM_HOST_CMD_GET_PARAM_MEMORY,
     367              :         /**
     368              :          * Get host command parameter memory size (custom)
     369              :          * @kconfig_dep{CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE}
     370              :          */
     371              :         ECUSTOM_HOST_CMD_GET_PARAM_MEMORY_SIZE,
     372              :         /**
     373              :          * Send host command result (custom)
     374              :          * @kconfig_dep{CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE}
     375              :          */
     376              :         ECUSTOM_HOST_CMD_SEND_RESULT,
     377              : #endif /* CONFIG_ESPI_PERIPHERAL_CUSTOM_OPCODE */
     378              : };
     379              : 
     380              : /** KBC 8042 event: Input Buffer Full */
     381            1 : #define HOST_KBC_EVT_IBF BIT(0)
     382              : /** KBC 8042 event: Output Buffer Empty */
     383            1 : #define HOST_KBC_EVT_OBE BIT(1)
     384              : 
     385              : /**
     386              :  * @brief Event data format for KBC events.
     387              :  *
     388              :  * Event data (@ref espi_event.evt_data) for Keyboard Controller (8042)
     389              :  * events, allowing to manipulate the raw event data as a bit field.
     390              :  */
     391            1 : struct espi_evt_data_kbc {
     392              :         /** Event type identifier */
     393            1 :         uint32_t type: 8;
     394              :         /** Event data payload */
     395            1 :         uint32_t data: 8;
     396              :         /** Event flags */
     397            1 :         uint32_t evt: 8;
     398              :         /** Reserved field for future use */
     399            1 :         uint32_t reserved: 8;
     400              : };
     401              : 
     402              : /**
     403              :  * @brief Event data format for ACPI events.
     404              :  *
     405              :  * Event data (@ref espi_event.evt_data) for ACPI events, allowing to manipulate the raw event
     406              :  * data as a bit field.
     407              :  */
     408            1 : struct espi_evt_data_acpi {
     409              :         /** Event type identifier */
     410            1 :         uint32_t type: 8;
     411              :         /** Event data payload */
     412            1 :         uint32_t data: 8;
     413              :         /** Reserved field for future use */
     414            1 :         uint32_t reserved: 16;
     415              : };
     416              : 
     417              : /**
     418              :  * @brief Event data format for Private Channel (PVT) events.
     419              :  *
     420              :  * Event data (@ref espi_event.evt_data) for Private Channel (PVT) events, allowing to manipulate
     421              :  * the raw event data as a bit field.
     422              :  */
     423            1 : struct espi_evt_data_pvt {
     424              :         /** Event type identifier */
     425            1 :         uint32_t type: 8;
     426              :         /** Event data payload */
     427            1 :         uint32_t data: 8;
     428              :         /** Reserved field for future use */
     429            1 :         uint32_t reserved: 16;
     430              : };
     431              : 
     432              : /**
     433              :  * @brief eSPI event
     434              :  *
     435              :  * Represents an eSPI bus event that is passed to application callbacks,
     436              :  * providing details about what occurred.
     437              :  */
     438            1 : struct espi_event {
     439              :         /** The type of event that occurred. */
     440            1 :         enum espi_bus_event evt_type;
     441              :         /**
     442              :          * Additional details for the event.
     443              :          *
     444              :          * The meaning depends on @ref evt_type.
     445              :          */
     446            1 :         uint32_t evt_details;
     447              :         /**
     448              :          * Data associated with the event.
     449              :          *
     450              :          * The meaning depends on @ref evt_type.
     451              :          * @c espi_evt_data_* structures can be used to manipulate the raw event data as a bit
     452              :          * field.
     453              :          */
     454            1 :         uint32_t evt_data;
     455              : };
     456              : 
     457              : /**
     458              :  * @brief eSPI bus configuration parameters
     459              :  */
     460            1 : struct espi_cfg {
     461              :         /** Supported I/O mode */
     462            1 :         enum espi_io_mode io_caps;
     463              :         /** Supported channels */
     464            1 :         enum espi_channel channel_caps;
     465              :         /** Maximum supported frequency in MHz */
     466            1 :         uint8_t max_freq;
     467              : };
     468              : 
     469              : /**
     470              :  * @brief eSPI peripheral request packet.
     471              :  *
     472              :  * Defines the format for peripheral channel (CH0) transactions, which are used
     473              :  * for memory, I/O, and message cycles.
     474              :  */
     475            1 : struct espi_request_packet {
     476              :         /** Type of eSPI cycle being performed. */
     477            1 :         enum espi_cycle_type cycle_type;
     478              :         /** Transaction tag for tracking. */
     479            1 :         uint8_t tag;
     480              :         /** Length of the data payload in bytes. */
     481            1 :         uint16_t len;
     482              :         /** Target address for the transaction. */
     483            1 :         uint32_t address;
     484              :         /** Pointer to the data buffer for read or write operations. */
     485            1 :         uint8_t *data;
     486              : };
     487              : 
     488              : /**
     489              :  * @brief eSPI out-of-band transaction packet format
     490              :  *
     491              :  * - For Tx packet, eSPI driver client shall specify the OOB payload data and its length in bytes.
     492              :  * - For Rx packet, eSPI driver client shall indicate the maximum number of bytes that can receive,
     493              :  *   while the eSPI driver should update the length field with the actual data received/available.
     494              :  *
     495              :  * @note In all cases, the @ref len does not include OOB header size 3 bytes.
     496              :  */
     497            1 : struct espi_oob_packet {
     498              :         /** Pointer to the data buffer. */
     499            1 :         uint8_t *buf;
     500              :         /**
     501              :          * Length of the data in bytes (excluding the 3-byte OOB header).
     502              :          * On reception, this is updated by the driver to the actual size.
     503              :          */
     504            1 :         uint16_t len;
     505              : };
     506              : 
     507              : /**
     508              :  * @brief eSPI flash transactions packet format
     509              :  */
     510            1 : struct espi_flash_packet {
     511              :         /** Pointer to the data buffer. */
     512            1 :         uint8_t *buf;
     513              :         /** Flash address to access. */
     514            1 :         uint32_t flash_addr;
     515              :         /**
     516              :          * Length of the data in bytes for read/write, or the size of the
     517              :          * sector/block for an erase operation.
     518              :          */
     519            1 :         uint16_t len;
     520              : };
     521              : 
     522              : /**
     523              :  * @brief Opaque type representing an eSPI callback.
     524              :  *
     525              :  * Used to register a callback in the driver instance callback list.
     526              :  * As many callbacks as needed can be added as long as each of them
     527              :  * are unique pointers of struct espi_callback.
     528              :  * Beware such structure should not be allocated on stack.
     529              :  *
     530              :  * @note To help setting a callback, see @ref espi_init_callback() helper.
     531              :  */
     532              : struct espi_callback;
     533              : 
     534              : /**
     535              :  * @typedef espi_callback_handler_t
     536              :  * @brief Define the application callback handler function signature.
     537              :  *
     538              :  * @param dev Device struct for the eSPI device.
     539              :  * @param cb Original struct espi_callback owning this handler.
     540              :  * @param espi_evt event details that trigger the callback handler.
     541              :  *
     542              :  */
     543            1 : typedef void (*espi_callback_handler_t) (const struct device *dev,
     544              :                                          struct espi_callback *cb,
     545              :                                          struct espi_event espi_evt);
     546              : 
     547              : /**
     548              :  * @cond INTERNAL_HIDDEN
     549              :  */
     550              : struct espi_callback {
     551              :         /** This is meant to be used in the driver only */
     552              :         sys_snode_t node;
     553              : 
     554              :         /** Actual callback function being called when relevant */
     555              :         espi_callback_handler_t handler;
     556              : 
     557              :         /** An event which user is interested in, if 0 the callback
     558              :          * will never be called. Such evt_mask can be modified whenever
     559              :          * necessary by the owner, and thus will affect the handler being
     560              :          * called or not.
     561              :          */
     562              :         enum espi_bus_event evt_type;
     563              : };
     564              : /** @endcond */
     565              : 
     566              : /**
     567              :  * @cond INTERNAL_HIDDEN
     568              :  *
     569              :  * eSPI driver API definition and system call entry points
     570              :  *
     571              :  * (Internal use only.)
     572              :  */
     573              : typedef int (*espi_api_config)(const struct device *dev, struct espi_cfg *cfg);
     574              : typedef bool (*espi_api_get_channel_status)(const struct device *dev,
     575              :                                             enum espi_channel ch);
     576              : /* Logical Channel 0 APIs */
     577              : typedef int (*espi_api_read_request)(const struct device *dev,
     578              :                                      struct espi_request_packet *req);
     579              : typedef int (*espi_api_write_request)(const struct device *dev,
     580              :                                       struct espi_request_packet *req);
     581              : typedef int (*espi_api_lpc_read_request)(const struct device *dev,
     582              :                                          enum lpc_peripheral_opcode op,
     583              :                                          uint32_t *data);
     584              : typedef int (*espi_api_lpc_write_request)(const struct device *dev,
     585              :                                           enum lpc_peripheral_opcode op,
     586              :                                           uint32_t *data);
     587              : /* Logical Channel 1 APIs */
     588              : typedef int (*espi_api_send_vwire)(const struct device *dev,
     589              :                                    enum espi_vwire_signal vw,
     590              :                                    uint8_t level);
     591              : typedef int (*espi_api_receive_vwire)(const struct device *dev,
     592              :                                       enum espi_vwire_signal vw,
     593              :                                       uint8_t *level);
     594              : /* Logical Channel 2 APIs */
     595              : typedef int (*espi_api_send_oob)(const struct device *dev,
     596              :                                  struct espi_oob_packet *pckt);
     597              : typedef int (*espi_api_receive_oob)(const struct device *dev,
     598              :                                     struct espi_oob_packet *pckt);
     599              : /* Logical Channel 3 APIs */
     600              : typedef int (*espi_api_flash_read)(const struct device *dev,
     601              :                                    struct espi_flash_packet *pckt);
     602              : typedef int (*espi_api_flash_write)(const struct device *dev,
     603              :                                     struct espi_flash_packet *pckt);
     604              : typedef int (*espi_api_flash_erase)(const struct device *dev,
     605              :                                     struct espi_flash_packet *pckt);
     606              : /* Callbacks and traffic intercept */
     607              : typedef int (*espi_api_manage_callback)(const struct device *dev,
     608              :                                         struct espi_callback *callback,
     609              :                                         bool set);
     610              : 
     611              : __subsystem struct espi_driver_api {
     612              :         espi_api_config config;
     613              :         espi_api_get_channel_status get_channel_status;
     614              :         espi_api_read_request read_request;
     615              :         espi_api_write_request write_request;
     616              :         espi_api_lpc_read_request read_lpc_request;
     617              :         espi_api_lpc_write_request write_lpc_request;
     618              :         espi_api_send_vwire send_vwire;
     619              :         espi_api_receive_vwire receive_vwire;
     620              :         espi_api_send_oob send_oob;
     621              :         espi_api_receive_oob receive_oob;
     622              :         espi_api_flash_read flash_read;
     623              :         espi_api_flash_write flash_write;
     624              :         espi_api_flash_erase flash_erase;
     625              :         espi_api_manage_callback manage_callback;
     626              : };
     627              : 
     628              : /**
     629              :  * @endcond
     630              :  */
     631              : 
     632              : /**
     633              :  * @brief Configure operation of a eSPI controller.
     634              :  *
     635              :  * This routine provides a generic interface to override eSPI controller
     636              :  * capabilities.
     637              :  *
     638              :  * If this eSPI controller is acting as target, the values set here
     639              :  * will be discovered as part through the GET_CONFIGURATION command
     640              :  * issued by the eSPI controller during initialization.
     641              :  *
     642              :  * If this eSPI controller is acting as controller, the values set here
     643              :  * will be used by eSPI controller to determine minimum common capabilities with
     644              :  * eSPI target then send via SET_CONFIGURATION command.
     645              :  *
     646              :  * @code
     647              :  * +---------+   +---------+     +------+          +---------+   +---------+
     648              :  * |  eSPI   |   |  eSPI   |     | eSPI |          |  eSPI   |   |  eSPI   |
     649              :  * |  target |   | driver  |     |  bus |          |  driver |   |  host   |
     650              :  * +--------+   +---------+     +------+          +---------+   +---------+
     651              :  *     |              |            |                   |             |
     652              :  *     | espi_config  | Set eSPI   |       Set eSPI    | espi_config |
     653              :  *     +--------------+ ctrl regs  |       cap ctrl reg| +-----------+
     654              :  *     |              +-------+    |          +--------+             |
     655              :  *     |              |<------+    |          +------->|             |
     656              :  *     |              |            |                   |             |
     657              :  *     |              |            |                   |             |
     658              :  *     |              |            | GET_CONFIGURATION |             |
     659              :  *     |              |            +<------------------+             |
     660              :  *     |              |<-----------|                   |             |
     661              :  *     |              | eSPI caps  |                   |             |
     662              :  *     |              |----------->+    response       |             |
     663              :  *     |              |            |------------------>+             |
     664              :  *     |              |            |                   |             |
     665              :  *     |              |            | SET_CONFIGURATION |             |
     666              :  *     |              |            +<------------------+             |
     667              :  *     |              |            |  accept           |             |
     668              :  *     |              |            +------------------>+             |
     669              :  *     +              +            +                   +             +
     670              :  * @endcode
     671              :  *
     672              :  * @param dev Pointer to the device structure for the driver instance.
     673              :  * @param cfg the device runtime configuration for the eSPI controller.
     674              :  *
     675              :  * @retval 0 If successful.
     676              :  * @retval -EIO General input / output error, failed to configure device.
     677              :  * @retval -EINVAL invalid capabilities, failed to configure device.
     678              :  * @retval -ENOTSUP capability not supported by eSPI target.
     679              :  */
     680            1 : __syscall int espi_config(const struct device *dev, struct espi_cfg *cfg);
     681              : 
     682              : static inline int z_impl_espi_config(const struct device *dev,
     683              :                                      struct espi_cfg *cfg)
     684              : {
     685              :         const struct espi_driver_api *api =
     686              :                 (const struct espi_driver_api *)dev->api;
     687              : 
     688              :         return api->config(dev, cfg);
     689              : }
     690              : 
     691              : /**
     692              :  * @brief Query whether a logical channel is ready.
     693              :  *
     694              :  * This routine allows to check if logical channel is ready before use.
     695              :  * Note that queries for channels not supported will always return false.
     696              :  *
     697              :  * @param dev Pointer to the device structure for the driver instance.
     698              :  * @param ch the eSPI channel for which status is to be retrieved.
     699              :  *
     700              :  * @retval true If eSPI channel is ready.
     701              :  * @retval false otherwise.
     702              :  */
     703            1 : __syscall bool espi_get_channel_status(const struct device *dev,
     704              :                                        enum espi_channel ch);
     705              : 
     706              : static inline bool z_impl_espi_get_channel_status(const struct device *dev,
     707              :                                                   enum espi_channel ch)
     708              : {
     709              :         const struct espi_driver_api *api =
     710              :                 (const struct espi_driver_api *)dev->api;
     711              : 
     712              :         return api->get_channel_status(dev, ch);
     713              : }
     714              : 
     715              : /**
     716              :  * @brief Sends memory, I/O or message read request over eSPI.
     717              :  *
     718              :  * This routine provides a generic interface to send a read request packet.
     719              :  *
     720              :  * @param dev Pointer to the device structure for the driver instance.
     721              :  * @param req Address of structure representing a memory,
     722              :  *            I/O or message read request.
     723              :  *
     724              :  * @retval 0 If successful.
     725              :  * @retval -ENOTSUP if eSPI controller doesn't support raw packets and instead
     726              :  *         low memory transactions are handled by controller hardware directly.
     727              :  * @retval -EIO General input / output error, failed to send over the bus.
     728              :  */
     729            1 : __syscall int espi_read_request(const struct device *dev,
     730              :                                 struct espi_request_packet *req);
     731              : 
     732              : static inline int z_impl_espi_read_request(const struct device *dev,
     733              :                                            struct espi_request_packet *req)
     734              : {
     735              :         const struct espi_driver_api *api =
     736              :                 (const struct espi_driver_api *)dev->api;
     737              : 
     738              :         if (!api->read_request) {
     739              :                 return -ENOTSUP;
     740              :         }
     741              : 
     742              :         return api->read_request(dev, req);
     743              : }
     744              : 
     745              : /**
     746              :  * @brief Sends memory, I/O or message write request over eSPI.
     747              :  *
     748              :  * This routine provides a generic interface to send a write request packet.
     749              :  *
     750              :  * @param dev Pointer to the device structure for the driver instance.
     751              :  * @param req Address of structure representing a memory, I/O or
     752              :  *            message write request.
     753              :  *
     754              :  * @retval 0 If successful.
     755              :  * @retval -ENOTSUP if eSPI controller doesn't support raw packets and instead
     756              :  *         low memory transactions are handled by controller hardware directly.
     757              :  * @retval -EIO General input / output error, failed to send over the bus.
     758              :  */
     759            1 : __syscall int espi_write_request(const struct device *dev,
     760              :                                  struct espi_request_packet *req);
     761              : 
     762              : static inline int z_impl_espi_write_request(const struct device *dev,
     763              :                                             struct espi_request_packet *req)
     764              : {
     765              :         const struct espi_driver_api *api =
     766              :                 (const struct espi_driver_api *)dev->api;
     767              : 
     768              :         if (!api->write_request) {
     769              :                 return -ENOTSUP;
     770              :         }
     771              : 
     772              :         return api->write_request(dev, req);
     773              : }
     774              : 
     775              : /**
     776              :  * @brief Reads SOC data from a LPC peripheral with information
     777              :  * updated over eSPI.
     778              :  *
     779              :  * This routine provides a generic interface to read a block whose
     780              :  * information was updated by an eSPI transaction. Reading may trigger
     781              :  * a transaction. The eSPI packet is assembled by the HW block.
     782              :  *
     783              :  * @param dev Pointer to the device structure for the driver instance.
     784              :  * @param op Enum representing opcode for peripheral type and read request.
     785              :  * @param data Parameter to be read from to the LPC peripheral.
     786              :  *
     787              :  * @retval 0 If successful.
     788              :  * @retval -ENOTSUP if eSPI peripheral is off or not supported.
     789              :  * @retval -EINVAL for unimplemented lpc opcode, but in range.
     790              :  */
     791            1 : __syscall int espi_read_lpc_request(const struct device *dev,
     792              :                                     enum lpc_peripheral_opcode op,
     793              :                                     uint32_t *data);
     794              : 
     795              : static inline int z_impl_espi_read_lpc_request(const struct device *dev,
     796              :                                                enum lpc_peripheral_opcode op,
     797              :                                                uint32_t *data)
     798              : {
     799              :         const struct espi_driver_api *api =
     800              :                 (const struct espi_driver_api *)dev->api;
     801              : 
     802              :         if (!api->read_lpc_request) {
     803              :                 return -ENOTSUP;
     804              :         }
     805              : 
     806              :         return api->read_lpc_request(dev, op, data);
     807              : }
     808              : 
     809              : /**
     810              :  * @brief Writes data to a LPC peripheral which generates an eSPI transaction.
     811              :  *
     812              :  * This routine provides a generic interface to write data to a block which
     813              :  * triggers an eSPI transaction. The eSPI packet is assembled by the HW
     814              :  * block.
     815              :  *
     816              :  * @param dev Pointer to the device structure for the driver instance.
     817              :  * @param op Enum representing an opcode for peripheral type and write request.
     818              :  * @param data Represents the parameter passed to the LPC peripheral.
     819              :  *
     820              :  * @retval 0 If successful.
     821              :  * @retval -ENOTSUP if eSPI peripheral is off or not supported.
     822              :  * @retval -EINVAL for unimplemented lpc opcode, but in range.
     823              :  */
     824            1 : __syscall int espi_write_lpc_request(const struct device *dev,
     825              :                                      enum lpc_peripheral_opcode op,
     826              :                                      uint32_t *data);
     827              : 
     828              : static inline int z_impl_espi_write_lpc_request(const struct device *dev,
     829              :                                                 enum lpc_peripheral_opcode op,
     830              :                                                 uint32_t *data)
     831              : {
     832              :         const struct espi_driver_api *api =
     833              :                 (const struct espi_driver_api *)dev->api;
     834              : 
     835              :         if (!api->write_lpc_request) {
     836              :                 return -ENOTSUP;
     837              :         }
     838              : 
     839              :         return api->write_lpc_request(dev, op, data);
     840              : }
     841              : 
     842              : /**
     843              :  * @brief Sends system/platform signal as a virtual wire packet.
     844              :  *
     845              :  * This routine provides a generic interface to send a virtual wire packet
     846              :  * from target to controller.
     847              :  *
     848              :  * @param dev Pointer to the device structure for the driver instance.
     849              :  * @param signal The signal to be sent to eSPI controller.
     850              :  * @param level The level of signal requested. LOW (0) or HIGH (1).
     851              :  *
     852              :  * @retval 0 If successful.
     853              :  * @retval -EIO General input / output error, failed to send over the bus.
     854              :  * @retval -EINVAL invalid signal.
     855              :  * @retval -ETIMEDOUT timeout waiting for eSPI controller to process the VW.
     856              :  */
     857            1 : __syscall int espi_send_vwire(const struct device *dev,
     858              :                               enum espi_vwire_signal signal,
     859              :                               uint8_t level);
     860              : 
     861              : static inline int z_impl_espi_send_vwire(const struct device *dev,
     862              :                                          enum espi_vwire_signal signal,
     863              :                                          uint8_t level)
     864              : {
     865              :         const struct espi_driver_api *api =
     866              :                 (const struct espi_driver_api *)dev->api;
     867              : 
     868              :         return api->send_vwire(dev, signal, level);
     869              : }
     870              : 
     871              : /**
     872              :  * @brief Retrieves level status for a signal encapsulated in a virtual wire.
     873              :  *
     874              :  * This routine provides a generic interface to request a virtual wire packet
     875              :  * from eSPI controller and retrieve the signal level.
     876              :  *
     877              :  * @param dev Pointer to the device structure for the driver instance.
     878              :  * @param signal the signal to be requested from eSPI controller.
     879              :  * @param[out] level the level of signal requested 0b LOW, 1b HIGH.
     880              :  *
     881              :  * @retval -EIO General input / output error, failed request to controller.
     882              :  */
     883            1 : __syscall int espi_receive_vwire(const struct device *dev,
     884              :                                  enum espi_vwire_signal signal,
     885              :                                  uint8_t *level);
     886              : 
     887              : static inline int z_impl_espi_receive_vwire(const struct device *dev,
     888              :                                             enum espi_vwire_signal signal,
     889              :                                             uint8_t *level)
     890              : {
     891              :         const struct espi_driver_api *api =
     892              :                 (const struct espi_driver_api *)dev->api;
     893              : 
     894              :         return api->receive_vwire(dev, signal, level);
     895              : }
     896              : 
     897              : /**
     898              :  * @brief Sends SMBus transaction (out-of-band) packet over eSPI bus.
     899              :  *
     900              :  * This routine provides an interface to encapsulate a SMBus transaction
     901              :  * and send into packet over eSPI bus
     902              :  *
     903              :  * @param dev Pointer to the device structure for the driver instance.
     904              :  * @param pckt Address of the packet representation of SMBus transaction.
     905              :  *
     906              :  * @retval -EIO General input / output error, failed request to controller.
     907              :  */
     908            1 : __syscall int espi_send_oob(const struct device *dev,
     909              :                             struct espi_oob_packet *pckt);
     910              : 
     911              : static inline int z_impl_espi_send_oob(const struct device *dev,
     912              :                                        struct espi_oob_packet *pckt)
     913              : {
     914              :         const struct espi_driver_api *api =
     915              :                 (const struct espi_driver_api *)dev->api;
     916              : 
     917              :         if (!api->send_oob) {
     918              :                 return -ENOTSUP;
     919              :         }
     920              : 
     921              :         return api->send_oob(dev, pckt);
     922              : }
     923              : 
     924              : /**
     925              :  * @brief Receives SMBus transaction (out-of-band) packet from eSPI bus.
     926              :  *
     927              :  * This routine provides an interface to receive and decode an SMBus
     928              :  * transaction from eSPI bus
     929              :  *
     930              :  * @param dev Pointer to the device structure for the driver instance.
     931              :  * @param pckt Address of the packet representation of SMBus transaction.
     932              :  *
     933              :  * @retval -EIO General input / output error, failed request to controller.
     934              :  */
     935            1 : __syscall int espi_receive_oob(const struct device *dev,
     936              :                                struct espi_oob_packet *pckt);
     937              : 
     938              : static inline int z_impl_espi_receive_oob(const struct device *dev,
     939              :                                           struct espi_oob_packet *pckt)
     940              : {
     941              :         const struct espi_driver_api *api =
     942              :                 (const struct espi_driver_api *)dev->api;
     943              : 
     944              :         if (!api->receive_oob) {
     945              :                 return -ENOTSUP;
     946              :         }
     947              : 
     948              :         return api->receive_oob(dev, pckt);
     949              : }
     950              : 
     951              : /**
     952              :  * @brief Sends a read request packet for shared flash.
     953              :  *
     954              :  * This routine provides an interface to send a request to read the flash
     955              :  * component shared between the eSPI controller and eSPI targets.
     956              :  *
     957              :  * @param dev Pointer to the device structure for the driver instance.
     958              :  * @param pckt Address of the representation of read flash transaction.
     959              :  *
     960              :  * @retval -ENOTSUP eSPI flash logical channel transactions not supported.
     961              :  * @retval -EBUSY eSPI flash channel is not ready or disabled by controller.
     962              :  * @retval -EIO General input / output error, failed request to controller.
     963              :  */
     964            1 : __syscall int espi_read_flash(const struct device *dev,
     965              :                               struct espi_flash_packet *pckt);
     966              : 
     967              : static inline int z_impl_espi_read_flash(const struct device *dev,
     968              :                                          struct espi_flash_packet *pckt)
     969              : {
     970              :         const struct espi_driver_api *api =
     971              :                 (const struct espi_driver_api *)dev->api;
     972              : 
     973              :         if (!api->flash_read) {
     974              :                 return -ENOTSUP;
     975              :         }
     976              : 
     977              :         return api->flash_read(dev, pckt);
     978              : }
     979              : 
     980              : /**
     981              :  * @brief Sends a write request packet for shared flash.
     982              :  *
     983              :  * This routine provides an interface to send a request to write to the flash
     984              :  * components shared between the eSPI controller and eSPI targets.
     985              :  *
     986              :  * @param dev Pointer to the device structure for the driver instance.
     987              :  * @param pckt Address of the representation of write flash transaction.
     988              :  *
     989              :  * @retval -ENOTSUP eSPI flash logical channel transactions not supported.
     990              :  * @retval -EBUSY eSPI flash channel is not ready or disabled by controller.
     991              :  * @retval -EIO General input / output error, failed request to controller.
     992              :  */
     993            1 : __syscall int espi_write_flash(const struct device *dev,
     994              :                                struct espi_flash_packet *pckt);
     995              : 
     996              : static inline int z_impl_espi_write_flash(const struct device *dev,
     997              :                                           struct espi_flash_packet *pckt)
     998              : {
     999              :         const struct espi_driver_api *api =
    1000              :                 (const struct espi_driver_api *)dev->api;
    1001              : 
    1002              :         if (!api->flash_write) {
    1003              :                 return -ENOTSUP;
    1004              :         }
    1005              : 
    1006              :         return api->flash_write(dev, pckt);
    1007              : }
    1008              : 
    1009              : /**
    1010              :  * @brief Sends a write request packet for shared flash.
    1011              :  *
    1012              :  * This routine provides an interface to send a request to erase the flash
    1013              :  * components shared between the eSPI controller and eSPI targets.
    1014              :  *
    1015              :  * @param dev Pointer to the device structure for the driver instance.
    1016              :  * @param pckt Address of the representation of erase flash transaction.
    1017              :  *
    1018              :  * @retval -ENOTSUP eSPI flash logical channel transactions not supported.
    1019              :  * @retval -EBUSY eSPI flash channel is not ready or disabled by controller.
    1020              :  * @retval -EIO General input / output error, failed request to controller.
    1021              :  */
    1022            1 : __syscall int espi_flash_erase(const struct device *dev,
    1023              :                                struct espi_flash_packet *pckt);
    1024              : 
    1025              : static inline int z_impl_espi_flash_erase(const struct device *dev,
    1026              :                                           struct espi_flash_packet *pckt)
    1027              : {
    1028              :         const struct espi_driver_api *api =
    1029              :                 (const struct espi_driver_api *)dev->api;
    1030              : 
    1031              :         if (!api->flash_erase) {
    1032              :                 return -ENOTSUP;
    1033              :         }
    1034              : 
    1035              :         return api->flash_erase(dev, pckt);
    1036              : }
    1037              : 
    1038              : /**
    1039              :  * Callback model
    1040              :  *
    1041              :  * @code
    1042              :  *+-------+                  +-------------+   +------+     +---------+
    1043              :  *|  App  |                  | eSPI driver |   |  HW  |     |eSPI Host|
    1044              :  *+---+---+                  +-------+-----+   +---+--+     +----+----+
    1045              :  *    |                              |             |             |
    1046              :  *    |   espi_init_callback         |             |             |
    1047              :  *    +----------------------------> |             |             |
    1048              :  *    |   espi_add_callback          |             |
    1049              :  *    +----------------------------->+             |
    1050              :  *    |                              |             |  eSPI reset |  eSPI host
    1051              :  *    |                              |    IRQ      +<------------+  resets the
    1052              :  *    |                              | <-----------+             |  bus
    1053              :  *    |<-----------------------------|             |             |
    1054              :  *    | Report eSPI bus reset        | Processed   |             |
    1055              :  *    |                              | within the  |             |
    1056              :  *    |                              | driver      |             |
    1057              :  *    |                              |             |             |
    1058              :  *    |                              |             |  VW CH ready|  eSPI host
    1059              :  *    |                              |    IRQ      +<------------+  enables VW
    1060              :  *    |                              | <-----------+             |  channel
    1061              :  *    |                              |             |             |
    1062              :  *    |                              | Processed   |             |
    1063              :  *    |                              | within the  |             |
    1064              :  *    |                              | driver      |             |
    1065              :  *    |                              |             |             |
    1066              :  *    |                              |             | Memory I/O  |  Peripheral
    1067              :  *    |                              |             <-------------+  event
    1068              :  *    |                              +<------------+             |
    1069              :  *    +<-----------------------------+ callback    |             |
    1070              :  *    | Report peripheral event      |             |             |
    1071              :  *    | and data for the event       |             |             |
    1072              :  *    |                              |             |             |
    1073              :  *    |                              |             | SLP_S5      |  eSPI host
    1074              :  *    |                              |             <-------------+  send VWire
    1075              :  *    |                              +<------------+             |
    1076              :  *    +<-----------------------------+ callback    |             |
    1077              :  *    | App enables/configures       |             |             |
    1078              :  *    | discrete regulator           |             |             |
    1079              :  *    |                              |             |             |
    1080              :  *    |   espi_send_vwire_signal     |             |             |
    1081              :  *    +------------------------------>------------>|------------>|
    1082              :  *    |                              |             |             |
    1083              :  *    |                              |             | HOST_RST    |  eSPI host
    1084              :  *    |                              |             <-------------+  send VWire
    1085              :  *    |                              +<------------+             |
    1086              :  *    +<-----------------------------+ callback    |             |
    1087              :  *    | App reset host-related       |             |             |
    1088              :  *    | data structures              |             |             |
    1089              :  *    |                              |             |             |
    1090              :  *    |                              |             |   C10       |  eSPI host
    1091              :  *    |                              |             +<------------+  send VWire
    1092              :  *    |                              <-------------+             |
    1093              :  *    <------------------------------+             |             |
    1094              :  *    | App executes                 |             |             |
    1095              :  *    + power mgmt policy            |             |             |
    1096              :  * @endcode
    1097              :  */
    1098              : 
    1099              : /**
    1100              :  * @brief Helper to initialize an espi_callback structure properly.
    1101              :  *
    1102              :  * @param callback A valid Application's callback structure pointer.
    1103              :  * @param handler A valid handler function pointer.
    1104              :  * @param evt_type indicates the eSPI event relevant for the handler.
    1105              :  * for VWIRE_RECEIVED event the data will indicate the new level asserted
    1106              :  */
    1107            1 : static inline void espi_init_callback(struct espi_callback *callback,
    1108              :                                       espi_callback_handler_t handler,
    1109              :                                       enum espi_bus_event evt_type)
    1110              : {
    1111              :         __ASSERT(callback, "Callback pointer should not be NULL");
    1112              :         __ASSERT(handler, "Callback handler pointer should not be NULL");
    1113              : 
    1114              :         callback->handler = handler;
    1115              :         callback->evt_type = evt_type;
    1116              : }
    1117              : 
    1118              : /**
    1119              :  * @brief Add an application callback.
    1120              :  * @param dev Pointer to the device structure for the driver instance.
    1121              :  * @param callback A valid Application's callback structure pointer.
    1122              :  * @return 0 if successful, negative errno code on failure.
    1123              :  *
    1124              :  * @note Callbacks may be added to the device from within a callback
    1125              :  * handler invocation, but whether they are invoked for the current
    1126              :  * eSPI event is not specified.
    1127              :  *
    1128              :  * Note: enables to add as many callback as needed on the same device.
    1129              :  */
    1130            1 : static inline int espi_add_callback(const struct device *dev,
    1131              :                                     struct espi_callback *callback)
    1132              : {
    1133              :         const struct espi_driver_api *api =
    1134              :                 (const struct espi_driver_api *)dev->api;
    1135              : 
    1136              :         if (!api->manage_callback) {
    1137              :                 return -ENOTSUP;
    1138              :         }
    1139              : 
    1140              :         return api->manage_callback(dev, callback, true);
    1141              : }
    1142              : 
    1143              : /**
    1144              :  * @brief Remove an application callback.
    1145              :  * @param dev Pointer to the device structure for the driver instance.
    1146              :  * @param callback A valid application's callback structure pointer.
    1147              :  * @return 0 if successful, negative errno code on failure.
    1148              :  *
    1149              :  * @warning It is explicitly permitted, within a callback handler, to
    1150              :  * remove the registration for the callback that is running, i.e. @p
    1151              :  * callback.  Attempts to remove other registrations on the same
    1152              :  * device may result in undefined behavior, including failure to
    1153              :  * invoke callbacks that remain registered and unintended invocation
    1154              :  * of removed callbacks.
    1155              :  *
    1156              :  * Note: enables to remove as many callbacks as added through
    1157              :  *       espi_add_callback().
    1158              :  */
    1159            1 : static inline int espi_remove_callback(const struct device *dev,
    1160              :                                        struct espi_callback *callback)
    1161              : {
    1162              :         const struct espi_driver_api *api =
    1163              :                 (const struct espi_driver_api *)dev->api;
    1164              : 
    1165              :         if (!api->manage_callback) {
    1166              :                 return -ENOTSUP;
    1167              :         }
    1168              : 
    1169              :         return api->manage_callback(dev, callback, false);
    1170              : }
    1171              : 
    1172              : #ifdef __cplusplus
    1173              : }
    1174              : #endif
    1175              : 
    1176              : /**
    1177              :  * @}
    1178              :  */
    1179              : #include <zephyr/syscalls/espi.h>
    1180              : #endif /* ZEPHYR_INCLUDE_ESPI_H_ */
        

Generated by: LCOV version 2.0-1