Line data Source code
1 0 : /*
2 : * Copyright 2022 Intel Corporation
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_DRIVERS_I3C_IBI_H_
8 : #define ZEPHYR_INCLUDE_DRIVERS_I3C_IBI_H_
9 :
10 : /**
11 : * @brief I3C In-Band Interrupts
12 : * @defgroup i3c_ibi I3C In-Band Interrupts
13 : * @ingroup i3c_interface
14 : * @{
15 : */
16 :
17 : #include <stdint.h>
18 :
19 : #include <zephyr/device.h>
20 : #include <zephyr/kernel.h>
21 : #include <zephyr/sys/slist.h>
22 :
23 : #ifndef CONFIG_I3C_IBI_MAX_PAYLOAD_SIZE
24 0 : #define CONFIG_I3C_IBI_MAX_PAYLOAD_SIZE 0
25 : #endif
26 :
27 : #ifdef __cplusplus
28 : extern "C" {
29 : #endif
30 :
31 : struct i3c_device_desc;
32 :
33 : /**
34 : * @brief IBI Types.
35 : */
36 0 : enum i3c_ibi_type {
37 : /** Target interrupt */
38 : I3C_IBI_TARGET_INTR,
39 :
40 : /** Controller Role Request */
41 : I3C_IBI_CONTROLLER_ROLE_REQUEST,
42 :
43 : /** Hot Join Request */
44 : I3C_IBI_HOTJOIN,
45 :
46 : I3C_IBI_TYPE_MAX = I3C_IBI_HOTJOIN,
47 :
48 : /**
49 : * Not an actual IBI type, but simply used by
50 : * the IBI workq for generic callbacks.
51 : */
52 : I3C_IBI_WORKQUEUE_CB,
53 : };
54 :
55 : /**
56 : * @brief Struct for IBI request.
57 : */
58 1 : struct i3c_ibi {
59 : /** Type of IBI. */
60 1 : enum i3c_ibi_type ibi_type;
61 :
62 : /** Pointer to payload of IBI. */
63 1 : uint8_t *payload;
64 :
65 : /** Length in bytes of the IBI payload. */
66 1 : uint8_t payload_len;
67 : };
68 :
69 : /**
70 : * @brief Structure of payload buffer for IBI.
71 : *
72 : * This is used for the IBI callback.
73 : */
74 1 : struct i3c_ibi_payload {
75 : /**
76 : * Length of available data in the payload buffer.
77 : */
78 1 : uint8_t payload_len;
79 :
80 : /**
81 : * Pointer to byte array as payload buffer.
82 : */
83 1 : uint8_t payload[CONFIG_I3C_IBI_MAX_PAYLOAD_SIZE];
84 : };
85 :
86 : /**
87 : * @brief Node about a queued IBI.
88 : */
89 1 : struct i3c_ibi_work {
90 0 : sys_snode_t node;
91 :
92 : /**
93 : * k_work struct.
94 : */
95 1 : struct k_work work;
96 :
97 : /**
98 : * IBI type.
99 : */
100 1 : enum i3c_ibi_type type;
101 :
102 : union {
103 : /**
104 : * Use for @see I3C_IBI_HOTJOIN.
105 : */
106 1 : const struct device *controller;
107 :
108 : /**
109 : * Use for @see I3C_IBI_TARGET_INTR,
110 : * and @see I3C_IBI_CONTROLLER_ROLE_REQUEST.
111 : */
112 1 : struct i3c_device_desc *target;
113 0 : };
114 :
115 : union {
116 : /**
117 : * IBI payload.
118 : */
119 1 : struct i3c_ibi_payload payload;
120 :
121 : /**
122 : * Generic workqueue callback when
123 : * type is I3C_IBI_WORKQUEUE_CB.
124 : */
125 1 : k_work_handler_t work_cb;
126 0 : };
127 : };
128 :
129 : /**
130 : * @brief Function called when In-Band Interrupt received from target device.
131 : *
132 : * This function is invoked by the controller when the controller
133 : * receives an In-Band Interrupt from the target device.
134 : *
135 : * A success return shall cause the controller to ACK the next byte
136 : * received. An error return shall cause the controller to NACK the
137 : * next byte received.
138 : *
139 : * @param target the device description structure associated with the
140 : * device to which the operation is addressed.
141 : * @param payload Payload associated with the IBI. NULL if there is
142 : * no payload.
143 : *
144 : * @return 0 if the IBI is accepted, or a negative error code.
145 : */
146 1 : typedef int (*i3c_target_ibi_cb_t)(struct i3c_device_desc *target,
147 : struct i3c_ibi_payload *payload);
148 :
149 :
150 : /**
151 : * @brief Queue an IBI work item for future processing.
152 : *
153 : * This queues up an IBI work item in the IBI workqueue
154 : * for future processing.
155 : *
156 : * Note that this will copy the @p ibi_work struct into
157 : * internal structure. If there is not enough space to
158 : * copy the @p ibi_work struct, this returns -ENOMEM.
159 : *
160 : * @param ibi_work Pointer to the IBI work item struct.
161 : *
162 : * @retval 0 If work item is successfully queued.
163 : * @retval -ENOMEM If no more free internal node to
164 : * store IBI work item.
165 : * @retval Others @see k_work_submit_to_queue
166 : */
167 1 : int i3c_ibi_work_enqueue(struct i3c_ibi_work *ibi_work);
168 :
169 : /**
170 : * @brief Queue a target interrupt IBI for future processing.
171 : *
172 : * This queues up a target interrupt IBI in the IBI workqueue
173 : * for future processing.
174 : *
175 : * @param target Pointer to target device descriptor.
176 : * @param payload Pointer to IBI payload byte array.
177 : * @param payload_len Length of payload byte array.
178 : *
179 : * @retval 0 If work item is successfully queued.
180 : * @retval -ENOMEM If no more free internal node to
181 : * store IBI work item.
182 : * @retval Others @see k_work_submit_to_queue
183 : */
184 1 : int i3c_ibi_work_enqueue_target_irq(struct i3c_device_desc *target,
185 : uint8_t *payload, size_t payload_len);
186 :
187 : /**
188 : * @brief Queue a controllership request IBI for future processing.
189 : *
190 : * This queues up a controllership request IBI in the IBI workqueue
191 : * for future processing.
192 : *
193 : * @param target Pointer to target device descriptor.
194 : *
195 : * @retval 0 If work item is successfully queued.
196 : * @retval -ENOMEM If no more free internal node to
197 : * store IBI work item.
198 : * @retval Others @see k_work_submit_to_queue
199 : */
200 1 : int i3c_ibi_work_enqueue_controller_request(struct i3c_device_desc *target);
201 :
202 : /**
203 : * @brief Queue a hot join IBI for future processing.
204 : *
205 : * This queues up a hot join IBI in the IBI workqueue
206 : * for future processing.
207 : *
208 : * @param dev Pointer to controller device driver instance.
209 : *
210 : * @retval 0 If work item is successfully queued.
211 : * @retval -ENOMEM If no more free internal node to
212 : * store IBI work item.
213 : * @retval Others @see k_work_submit_to_queue
214 : */
215 1 : int i3c_ibi_work_enqueue_hotjoin(const struct device *dev);
216 :
217 : /**
218 : * @brief Queue a generic callback for future processing.
219 : *
220 : * This queues up a generic callback in the IBI workqueue
221 : * for future processing.
222 : *
223 : * @param dev Pointer to controller device driver instance.
224 : * @param work_cb Callback function.
225 : *
226 : * @retval 0 If work item is successfully queued.
227 : * @retval -ENOMEM If no more free internal node to
228 : * store IBI work item.
229 : * @retval Others @see k_work_submit_to_queue
230 : */
231 1 : int i3c_ibi_work_enqueue_cb(const struct device *dev,
232 : k_work_handler_t work_cb);
233 :
234 : #ifdef __cplusplus
235 : }
236 : #endif
237 :
238 : /**
239 : * @}
240 : */
241 :
242 : #endif /* ZEPHYR_INCLUDE_DRIVERS_I3C_IBI_H_ */
|
