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