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-25 19:22:35

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

Generated by: LCOV version 2.0-1