Line data Source code
1 1 : /*
2 : * Copyright 2020 Google LLC
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @ingroup espi_emul_interface
10 : * @brief Main header file for eSPI emulation driver API.
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_DRIVERS_ESPI_SPI_EMUL_H_
14 : #define ZEPHYR_INCLUDE_DRIVERS_ESPI_SPI_EMUL_H_
15 :
16 : #include <zephyr/device.h>
17 : #include <zephyr/drivers/emul.h>
18 : #include <zephyr/drivers/espi.h>
19 : #include <zephyr/sys/slist.h>
20 : #include <zephyr/types.h>
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_ */
|
