Line data Source code
1 1 : /*
2 : * Copyright 2024 NXP
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Public APIs for the SCMI transport layer drivers
10 : */
11 :
12 : #ifndef _INCLUDE_ZEPHYR_DRIVERS_FIRMWARE_SCMI_TRANSPORT_H_
13 : #define _INCLUDE_ZEPHYR_DRIVERS_FIRMWARE_SCMI_TRANSPORT_H_
14 :
15 : #include <zephyr/device.h>
16 : #include <zephyr/kernel.h>
17 :
18 : struct scmi_message;
19 : struct scmi_channel;
20 :
21 : /**
22 : * @typedef scmi_channel_cb
23 : *
24 : * @brief Callback function for message replies
25 : *
26 : * This function should be called by the transport layer
27 : * driver whenever a reply to a previously sent message
28 : * has been received. Its purpose is to notifying the SCMI
29 : * core of the reply's arrival so that proper action can
30 : * be taken.
31 : *
32 : * @param chan pointer to SCMI channel on which the reply
33 : * arrived
34 : */
35 1 : typedef void (*scmi_channel_cb)(struct scmi_channel *chan);
36 :
37 : /**
38 : * @struct scmi_channel
39 : * @brief SCMI channel structure
40 : *
41 : * An SCMI channel is a medium through which a protocol
42 : * is able to transmit/receive messages. Each of the SCMI
43 : * channels is represented by a `struct scmi_channel`.
44 : */
45 1 : struct scmi_channel {
46 : /**
47 : * channel lock. This is meant to be initialized
48 : * and used only by the SCMI core to assure that
49 : * only one protocol can send/receive messages
50 : * through a channel at a given moment.
51 : */
52 1 : struct k_mutex lock;
53 : /**
54 : * binary semaphore. This is meant to be initialized
55 : * and used only by the SCMI core. Its purpose is to
56 : * signal that a reply has been received.
57 : */
58 1 : struct k_sem sem;
59 : /** channel private data */
60 1 : void *data;
61 : /**
62 : * callback function. This is meant to be set by
63 : * the SCMI core and should be called by the SCMI
64 : * transport layer driver whenever a reply has
65 : * been received.
66 : */
67 1 : scmi_channel_cb cb;
68 : /** is the channel ready to be used by a protocol? */
69 1 : bool ready;
70 : };
71 :
72 0 : struct scmi_transport_api {
73 0 : int (*init)(const struct device *transport);
74 0 : int (*send_message)(const struct device *transport,
75 : struct scmi_channel *chan,
76 : struct scmi_message *msg);
77 0 : int (*setup_chan)(const struct device *transport,
78 : struct scmi_channel *chan,
79 : bool tx);
80 0 : int (*read_message)(const struct device *transport,
81 : struct scmi_channel *chan,
82 : struct scmi_message *msg);
83 0 : bool (*channel_is_free)(const struct device *transport,
84 : struct scmi_channel *chan);
85 : struct scmi_channel *(*request_channel)(const struct device *transport,
86 : uint32_t proto, bool tx);
87 : };
88 :
89 : /**
90 : * @brief Request an SCMI channel dynamically
91 : *
92 : * Whenever the SCMI transport layer driver doesn't support
93 : * static channel allocation, the SCMI core will try to bind
94 : * a channel to a protocol dynamically using this function.
95 : * Note that no setup needs to be performed on the channel
96 : * in this function as the core will also call the channel
97 : * setup() function.
98 : *
99 : * @param transport pointer to the device structure for the
100 : * transport layer
101 : * @param proto ID of the protocol for which the core is
102 : * requesting the channel
103 : * @param tx true if the channel is TX, false if RX
104 : *
105 : * @retval pointer to SCMI channel that's to be bound
106 : * to the protocol
107 : * @retval NULL if operation was not successful
108 : */
109 : static inline struct scmi_channel *
110 1 : scmi_transport_request_channel(const struct device *transport,
111 : uint32_t proto, bool tx)
112 : {
113 : const struct scmi_transport_api *api =
114 : (const struct scmi_transport_api *)transport->api;
115 :
116 : if (api->request_channel) {
117 : return api->request_channel(transport, proto, tx);
118 : }
119 :
120 : return NULL;
121 : }
122 :
123 : /**
124 : * @brief Perform initialization for the transport layer driver
125 : *
126 : * The transport layer driver can't be initialized directly
127 : * (i.e via a call to its init() function) during system initialization.
128 : * This is because the macro used to define an SCMI transport places
129 : * `scmi_core_transport_init()` in the init section instead of the
130 : * driver's init() function. As such, `scmi_core_transport_init()`
131 : * needs to call this function to perfrom transport layer driver
132 : * initialization if required.
133 : *
134 : * This operation is optional.
135 : *
136 : * @param transport pointer to the device structure for the
137 : * transport layer
138 : *
139 : * @retval 0 if successful
140 : * @retval negative errno code if failure
141 : */
142 1 : static inline int scmi_transport_init(const struct device *transport)
143 : {
144 : const struct scmi_transport_api *api =
145 : (const struct scmi_transport_api *)transport->api;
146 :
147 : if (api->init) {
148 : return api->init(transport);
149 : }
150 :
151 : return 0;
152 : }
153 :
154 : /**
155 : * @brief Setup an SCMI channel
156 : *
157 : * Before being able to send/receive messages, an SCMI channel needs
158 : * to be prepared, which is what this function does. If it returns
159 : * successfully, an SCMI protocol will be able to use this channel
160 : * to send/receive messages.
161 : *
162 : * @param transport pointer to the device structure for the
163 : * transport layer
164 : * @param chan pointer to SCMI channel to be prepared
165 : * @param tx true if the channel is TX, false if RX
166 : *
167 : * @retval 0 if successful
168 : * @retval negative errno code if failure
169 : */
170 1 : static inline int scmi_transport_setup_chan(const struct device *transport,
171 : struct scmi_channel *chan,
172 : bool tx)
173 : {
174 : const struct scmi_transport_api *api =
175 : (const struct scmi_transport_api *)transport->api;
176 :
177 : if (!api || !api->setup_chan) {
178 : return -ENOSYS;
179 : }
180 :
181 : return api->setup_chan(transport, chan, tx);
182 : }
183 :
184 : /**
185 : * @brief Send an SCMI channel
186 : *
187 : * Send an SCMI message using given SCMI channel. This function is
188 : * not allowed to block.
189 : *
190 : * @param transport pointer to the device structure for the
191 : * transport layer
192 : * @param chan pointer to SCMI channel on which the message
193 : * is to be sent
194 : * @param msg pointer to message the caller wishes to send
195 : *
196 : * @retval 0 if successful
197 : * @retval negative errno code if failure
198 : */
199 1 : static inline int scmi_transport_send_message(const struct device *transport,
200 : struct scmi_channel *chan,
201 : struct scmi_message *msg)
202 : {
203 : const struct scmi_transport_api *api =
204 : (const struct scmi_transport_api *)transport->api;
205 :
206 : if (!api || !api->send_message) {
207 : return -ENOSYS;
208 : }
209 :
210 : return api->send_message(transport, chan, msg);
211 : }
212 :
213 : /**
214 : * @brief Read an SCMI message
215 : *
216 : * @param transport pointer to the device structure for the
217 : * transport layer
218 : * @param chan pointer to SCMI channel on which the message
219 : * is to be read
220 : * @param msg pointer to message the caller wishes to read
221 : *
222 : * @retval 0 if successful
223 : * @retval negative errno code if failure
224 : */
225 1 : static inline int scmi_transport_read_message(const struct device *transport,
226 : struct scmi_channel *chan,
227 : struct scmi_message *msg)
228 : {
229 : const struct scmi_transport_api *api =
230 : (const struct scmi_transport_api *)transport->api;
231 :
232 : if (!api || !api->read_message) {
233 : return -ENOSYS;
234 : }
235 :
236 : return api->read_message(transport, chan, msg);
237 : }
238 :
239 : /**
240 : * @brief Check if an SCMI channel is free
241 : *
242 : * @param transport pointer to the device structure for
243 : * the transport layer
244 : * @param chan pointer to SCMI channel the query is to be
245 : * performed on
246 : *
247 : * @retval 0 if successful
248 : * @retval negative errno code if failure
249 : */
250 1 : static inline bool scmi_transport_channel_is_free(const struct device *transport,
251 : struct scmi_channel *chan)
252 : {
253 : const struct scmi_transport_api *api =
254 : (const struct scmi_transport_api *)transport->api;
255 :
256 : if (!api || !api->channel_is_free) {
257 : return -ENOSYS;
258 : }
259 :
260 : return api->channel_is_free(transport, chan);
261 : }
262 :
263 : /**
264 : * @brief Perfrom SCMI core initialization
265 : *
266 : * @param transport pointer to the device structure for
267 : * the transport layer
268 : *
269 : * @retval 0 if successful
270 : * @retval negative errno code if failure
271 : */
272 1 : int scmi_core_transport_init(const struct device *transport);
273 :
274 : #endif /* _INCLUDE_ZEPHYR_DRIVERS_FIRMWARE_SCMI_TRANSPORT_H_ */
|
