LCOV - code coverage report
Current view: top level - zephyr/drivers - espi_emul.h Coverage Total Hit
Test: new.info Lines: 65.0 % 20 13
Test Date: 2025-09-05 20:47:19

            Line data    Source code
       1            1 : /*
       2              :  * Copyright 2020 Google LLC
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : #ifndef ZEPHYR_INCLUDE_DRIVERS_ESPI_SPI_EMUL_H_
       8              : #define ZEPHYR_INCLUDE_DRIVERS_ESPI_SPI_EMUL_H_
       9              : 
      10              : #include <zephyr/device.h>
      11              : #include <zephyr/drivers/emul.h>
      12              : #include <zephyr/drivers/espi.h>
      13              : #include <zephyr/sys/slist.h>
      14              : #include <zephyr/types.h>
      15              : 
      16              : /**
      17              :  * @file
      18              :  *
      19              :  * @brief Public APIs for the eSPI emulation drivers.
      20              :  */
      21              : 
      22              : /**
      23              :  * @brief eSPI Emulation Interface
      24              :  * @defgroup espi_emul_interface eSPI Emulation Interface
      25              :  * @ingroup io_emulators
      26              :  * @ingroup espi_interface
      27              :  * @{
      28              :  */
      29              : 
      30              : #ifdef __cplusplus
      31              : extern "C" {
      32              : #endif
      33              : 
      34            0 : #define EMUL_ESPI_HOST_CHIPSEL 0
      35              : 
      36              : struct espi_emul;
      37              : 
      38              : /**
      39              :  * Passes eSPI virtual wires set request (virtual wire packet) to the emulator.
      40              :  * The emulator updates the state (level) of its virtual wire.
      41              :  *
      42              :  * @param target The device Emulator instance
      43              :  * @param vw The signal to be set.
      44              :  * @param level The level of signal requested LOW(0) or HIGH(1).
      45              :  *
      46              :  * @retval 0 If successful.
      47              :  * @retval -EIO General input / output error.
      48              :  */
      49            1 : typedef int (*emul_espi_api_set_vw)(const struct emul *target, enum espi_vwire_signal vw,
      50              :                                     uint8_t level);
      51              : 
      52              : /**
      53              :  * Passes eSPI virtual wires get request (virtual wire packet) to the emulator.
      54              :  * The emulator returns the state (level) of its virtual wire.
      55              :  *
      56              :  * @param target The device Emulator instance
      57              :  * @param vw The signal to be get.
      58              :  * @param level The level of the signal to be get.
      59              :  *
      60              :  * @retval 0 If successful.
      61              :  * @retval -EIO General input / output error.
      62              :  */
      63            1 : typedef int (*emul_espi_api_get_vw)(const struct emul *target, enum espi_vwire_signal vw,
      64              :                                     uint8_t *level);
      65              : 
      66              : #ifdef CONFIG_ESPI_PERIPHERAL_ACPI_SHM_REGION
      67              : /**
      68              :  * Get the ACPI shared memory address owned by the emulator.
      69              :  *
      70              :  * @param target The device Emulator instance
      71              :  *
      72              :  * @retval The address of the memory.
      73              :  */
      74              : typedef uintptr_t (*emul_espi_api_get_acpi_shm)(const struct emul *target);
      75              : #endif
      76              : 
      77              : /**
      78              :  * Find an emulator present on a eSPI bus
      79              :  *
      80              :  * At present the function is used only to find an emulator of the host
      81              :  * device. It may be useful in systems with the SPI flash chips.
      82              :  *
      83              :  * @param dev eSPI emulation controller device
      84              :  * @param chipsel Chip-select value
      85              :  * @return espi_emul to use
      86              :  * @return NULL if not found
      87              :  */
      88              : typedef struct espi_emul *(*emul_find_emul)(const struct device *dev, unsigned int chipsel);
      89              : 
      90              : /**
      91              :  * Triggers an event on the emulator of eSPI controller side which causes
      92              :  * calling specific callbacks.
      93              :  *
      94              :  * @param dev Device instance of emulated eSPI controller
      95              :  * @param evt Event to be triggered
      96              :  *
      97              :  * @retval 0 If successful.
      98              :  * @retval -EIO General input / output error.
      99              :  */
     100            1 : typedef int (*emul_trigger_event)(const struct device *dev, struct espi_event *evt);
     101              : 
     102              : /** Definition of the eSPI device emulator API */
     103            1 : struct emul_espi_device_api {
     104            0 :         emul_espi_api_set_vw set_vw;
     105            0 :         emul_espi_api_get_vw get_vw;
     106              : #ifdef CONFIG_ESPI_PERIPHERAL_ACPI_SHM_REGION
     107              :         emul_espi_api_get_acpi_shm get_acpi_shm;
     108              : #endif
     109              : };
     110              : 
     111              : /** Node in a linked list of emulators for eSPI devices */
     112            1 : struct espi_emul {
     113            0 :         sys_snode_t node;
     114              :         /** Target emulator - REQUIRED for all emulated bus nodes of any type */
     115            1 :         const struct emul *target;
     116              :         /** API provided for this device */
     117            1 :         const struct emul_espi_device_api *api;
     118              :         /** eSPI chip-select of the emulated device */
     119            1 :         uint16_t chipsel;
     120              : };
     121              : 
     122              : /** Definition of the eSPI controller emulator API */
     123            1 : struct emul_espi_driver_api {
     124              :         /* The struct espi_driver_api has to be first in
     125              :          * struct emul_espi_driver_api to make pointer casting working
     126              :          */
     127            0 :         struct espi_driver_api espi_api;
     128              :         /* The rest, emulator specific functions */
     129            0 :         emul_trigger_event trigger_event;
     130            0 :         emul_find_emul find_emul;
     131              : };
     132              : 
     133              : /**
     134              :  * Register an emulated device on the controller
     135              :  *
     136              :  * @param dev Device that will use the emulator
     137              :  * @param emul eSPI emulator to use
     138              :  * @return 0 indicating success (always)
     139              :  */
     140            1 : int espi_emul_register(const struct device *dev, struct espi_emul *emul);
     141              : 
     142              : /**
     143              :  * Sets the eSPI virtual wire on the host side, which will
     144              :  * trigger a proper event(and callbacks) on the emulated eSPI controller
     145              :  *
     146              :  * @param espi_dev eSPI emulation controller device
     147              :  * @param vw The signal to be set.
     148              :  * @param level The level of the signal to be set.
     149              :  *
     150              :  * @retval 0 If successful.
     151              :  * @retval -EIO General input / output error.
     152              :  */
     153            1 : int emul_espi_host_send_vw(const struct device *espi_dev, enum espi_vwire_signal vw, uint8_t level);
     154              : 
     155              : /**
     156              :  * Perform port80 write on the emulated host side, which will
     157              :  * trigger a proper event(and callbacks) on the emulated eSPI controller
     158              :  *
     159              :  * @param espi_dev eSPI emulation controller device
     160              :  * @param data The date to be written.
     161              :  *
     162              :  * @retval 0 If successful.
     163              :  * @retval -EIO General input / output error.
     164              :  */
     165            1 : int emul_espi_host_port80_write(const struct device *espi_dev, uint32_t data);
     166              : 
     167              : #ifdef CONFIG_ESPI_PERIPHERAL_ACPI_SHM_REGION
     168              : /**
     169              :  * Get the host device's ACPI shared memory start address. The size of the region is
     170              :  * CONFIG_EMUL_ESPI_HOST_ACPI_SHM_REGION_SIZE.
     171              :  *
     172              :  * @param espi_dev eSPI emulation controller device.
     173              :  * @return Address of the start of the ACPI shared memory.
     174              :  */
     175              : uintptr_t emul_espi_host_get_acpi_shm(const struct device *espi_dev);
     176              : #endif
     177              : 
     178              : #ifdef __cplusplus
     179              : }
     180              : #endif
     181              : 
     182              : /**
     183              :  * @}
     184              :  */
     185              : 
     186              : #endif /* ZEPHYR_INCLUDE_DRIVERS_ESPI_SPI_EMUL_H_ */
        

Generated by: LCOV version 2.0-1