1 /*
2  * Copyright 2020 Google LLC
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef ZEPHYR_INCLUDE_DRIVERS_MSPI_EMUL_H_
8 #define ZEPHYR_INCLUDE_DRIVERS_MSPI_EMUL_H_
9 
10 #include <zephyr/device.h>
11 #include <zephyr/drivers/emul.h>
12 #include <zephyr/drivers/mspi.h>
13 #include <zephyr/sys/slist.h>
14 #include <zephyr/types.h>
15 
16 /**
17  * @file
18  *
19  * @brief Public APIs for the MSPI emulation drivers.
20  */
21 
22 /**
23  * @brief MSPI Emulation Interface
24  * @defgroup mspi_emul_interface MSPI Emulation Interface
25  * @ingroup io_emulators
26  * @{
27  */
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 struct mspi_emul;
34 
35 /**
36  * Find an emulator present on a MSPI bus
37  *
38  * At present the function is used only to find an emulator of the host
39  * device. It may be useful in systems with the SPI flash chips.
40  *
41  * @param dev MSPI emulation controller device
42  * @param dev_idx Device index from device tree.
43  * @return mspi_emul to use
44  * @return NULL if not found
45  */
46 typedef struct mspi_emul *(*mspi_emul_find_emul)(const struct device *dev,
47 						 uint16_t dev_idx);
48 
49 /**
50  * Triggers an event on the emulator of MSPI controller side which causes
51  * calling specific callbacks.
52  *
53  * @param dev MSPI emulation controller device
54  * @param evt_type Event type to be triggered @see mspi_bus_event
55  *
56  * @retval 0 If successful.
57  * @retval -EIO General input / output error.
58  */
59 typedef int (*mspi_emul_trigger_event)(const struct device *dev,
60 				       enum mspi_bus_event evt_type);
61 
62 /**
63  * Loopback MSPI transceive request to the device emulator
64  * as no real hardware attached
65  *
66  * @param target The device Emulator instance
67  * @param packets Pointer to the buffers of command, addr, data and etc.
68  * @param num_packet The number of packets in packets.
69  * @param async Indicate whether this is a asynchronous request.
70  * @param timeout Maximum Time allowed for this request
71  *
72  * @retval 0 If successful.
73  * @retval -EIO General input / output error.
74  */
75 typedef int (*emul_mspi_dev_api_transceive)(const struct emul *target,
76 					    const struct mspi_xfer_packet *packets,
77 					    uint32_t num_packet,
78 					    bool async,
79 					    uint32_t timeout);
80 
81 /** Definition of the MSPI device emulator API */
82 struct emul_mspi_device_api {
83 	emul_mspi_dev_api_transceive transceive;
84 };
85 
86 /** Node in a linked list of emulators for MSPI devices */
87 struct mspi_emul {
88 	sys_snode_t                  node;
89 	/** Target emulator - REQUIRED for all emulated bus nodes of any type */
90 	const struct emul            *target;
91 	/** API provided for this device */
92 	const struct emul_mspi_device_api *api;
93 	/** device index */
94 	uint16_t                     dev_idx;
95 };
96 
97 /** Definition of the MSPI controller emulator API */
98 struct emul_mspi_driver_api {
99 	/* The struct mspi_driver_api has to be first in
100 	 * struct emul_mspi_driver_api to make pointer casting working
101 	 */
102 	struct mspi_driver_api       mspi_api;
103 	/* The rest, emulator specific functions */
104 	mspi_emul_trigger_event      trigger_event;
105 	mspi_emul_find_emul          find_emul;
106 };
107 
108 /**
109  * Register an emulated device on the controller
110  *
111  * @param dev MSPI emulation controller device
112  * @param emul MSPI device emulator to be registered
113  * @return 0 indicating success (always)
114  */
115 int mspi_emul_register(const struct device *dev, struct mspi_emul *emul);
116 
117 #ifdef __cplusplus
118 }
119 #endif
120 
121 /**
122  * @}
123  */
124 
125 #endif /* ZEPHYR_INCLUDE_DRIVERS_MSPI_EMUL_H_ */
126