Line data Source code
1 0 : /*
2 : * Copyright (c) 2023 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_IPC_ICMSG_ME_H_
8 : #define ZEPHYR_INCLUDE_IPC_ICMSG_ME_H_
9 :
10 : #include <stdint.h>
11 : #include <zephyr/kernel.h>
12 : #include <zephyr/ipc/icmsg.h>
13 : #include <zephyr/ipc/ipc_service.h>
14 :
15 : #ifdef __cplusplus
16 : extern "C" {
17 : #endif
18 :
19 : /**
20 : * @brief Multi-endpoint extension of icmsg IPC library
21 : * @defgroup ipc_icmsg_me_api Icmsg multi-endpoint IPC library API
22 : * @ingroup ipc
23 : * @{
24 : */
25 :
26 :
27 : /* If more bytes than 1 was used for endpoint id, endianness should be
28 : * considered.
29 : */
30 0 : typedef uint8_t icmsg_me_ept_id_t;
31 :
32 0 : struct icmsg_me_data_t {
33 0 : struct icmsg_data_t icmsg_data;
34 0 : struct ipc_ept_cfg ept_cfg;
35 :
36 0 : struct k_event event;
37 :
38 0 : struct k_mutex send_mutex;
39 0 : const struct ipc_ept_cfg *epts[CONFIG_IPC_SERVICE_BACKEND_ICMSG_ME_NUM_EP];
40 :
41 0 : uint8_t send_buffer[CONFIG_IPC_SERVICE_BACKEND_ICMSG_ME_SEND_BUF_SIZE] __aligned(4);
42 : };
43 :
44 :
45 : /** @brief Initialize an icmsg_me instance
46 : *
47 : * This function is intended to be called during system initialization.
48 : * It initializes the underlying icmsg instance as one of the initialization
49 : * steps.
50 : *
51 : * @param[in] conf Structure containing configuration parameters for the
52 : * underlying icmsg instance being created.
53 : * @param[inout] data Structure containing run-time data used by the icmsg_me
54 : * instance. The structure shall be filled with zeros
55 : * when calling this function. The content of this
56 : * structure must be preserved while the icmsg_me instance
57 : * is active.
58 : *
59 : * @retval 0 on success.
60 : * @retval other errno codes from dependent modules.
61 : */
62 1 : int icmsg_me_init(const struct icmsg_config_t *conf,
63 : struct icmsg_me_data_t *data);
64 :
65 : /** @brief Open an icmsg_me instance
66 : *
67 : * Open an icmsg_me instance to be able to send and receive messages to a
68 : * remote instance.
69 : * This function is blocking until the handshake with the remote instance is
70 : * completed.
71 : * This function is intended to be called late in the initialization process,
72 : * possibly from a thread which can be safely blocked while handshake with the
73 : * remote instance is being pefromed.
74 : *
75 : * @param[in] conf Structure containing configuration parameters for the
76 : * underlying icmsg instance.
77 : * @param[inout] data Structure containing run-time data used by the icmsg_me
78 : * instance. The structure is initialized with
79 : * @ref icmsg_me_init and its content must be preserved
80 : * while the icmsg_me instance is active.
81 : * @param[in] cb Structure containing callback functions to be called on
82 : * events generated by this icmsg_me instance. The pointed memory
83 : * must be preserved while the icmsg_me instance is active.
84 : * @param[in] ctx Pointer to context passed as an argument to callbacks.
85 : *
86 : *
87 : * @retval 0 on success.
88 : * @retval other errno codes from dependent modules.
89 : */
90 1 : int icmsg_me_open(const struct icmsg_config_t *conf,
91 : struct icmsg_me_data_t *data,
92 : const struct ipc_service_cb *cb,
93 : void *ctx);
94 :
95 : /** @brief Wait until the underlying icmsg instance calls bound callback
96 : *
97 : * This function blocks calling thread until the underlying icmsg connection
98 : * is bound. If the connection was bound before this function is called, the
99 : * function ends immediately without any delay.
100 : *
101 : * This function is intended to be used in the endpoints handshake procedure
102 : * to make sure that handshake is not performed until the icmsg channel is
103 : * ready to pass handshake messages.
104 : *
105 : * @param[inout] data Structure containing run-time data used by the icmsg_me
106 : * instance. The structure is initialized with
107 : * @ref icmsg_me_init and its content must be preserved
108 : * while the icmsg_me instance is active.
109 : */
110 1 : void icmsg_me_wait_for_icmsg_bind(struct icmsg_me_data_t *data);
111 :
112 : /** @brief Notify the icmsg_me instance that the underlying icmsg was bound
113 : *
114 : * The icmsg_me API users are responsible to implement the callback functions
115 : * called by the underlying icmsg instance. One of the actions of the bound
116 : * callback must be calling this function.
117 : *
118 : * @param[inout] data Structure containing run-time data used by the icmsg_me
119 : * instance. The structure is initialized with
120 : * @ref icmsg_me_init and its content must be preserved
121 : * while the icmsg_me instance is active.
122 : */
123 1 : void icmsg_me_icmsg_bound(struct icmsg_me_data_t *data);
124 :
125 : /** @brief Notify the icmsg_me instance that data for an endpoint was received
126 : *
127 : * The icmsg_me API users are responsible to implement the callback functions
128 : * called by the underlying icmsg instance. If the data received by the icmsg
129 : * instance contains data frame destined to one of the endpoints, this
130 : * function must be called.
131 : *
132 : * @param[inout] data Structure containing run-time data used by the icmsg_me
133 : * instance. The structure is initialized with
134 : * @ref icmsg_me_init and its content must be preserved
135 : * while the icmsg_me instance is active.
136 : * @param[in] id The value identifyig the endpoint.
137 : * @param[in] msg Data frame received from the peer, stripped of the
138 : * multi-endpoint header.
139 : * @param[in] len Size of the data pointed by @p msg.
140 : */
141 1 : void icmsg_me_received_data(struct icmsg_me_data_t *data, icmsg_me_ept_id_t id,
142 : const void *msg, size_t len);
143 :
144 : /** @brief Set endpoint configuration in an empty endpoint slot
145 : *
146 : * During endpoint handshake the handshake initiator must select an id number
147 : * and store endpoint metadata required to finalize handshake and maintain
148 : * the connection. This function is a helper which stores the configuration
149 : * in an empty configuration slot and provides the unique id value associated
150 : * with the selected slot.
151 : *
152 : * @note This function is not reentrant for a single icmsg_me instance.
153 : * It must be protected by the caller using mutex, critical section,
154 : * spinlock, or similar solution.
155 : * This function is reentrant for different icmsg_me instances. The
156 : * protection scope might be limited to a single instance.
157 : *
158 : * @param[inout] data Structure containing run-time data used by the icmsg_me
159 : * instance. The structure is initialized with
160 : * @ref icmsg_me_init and its content must be preserved
161 : * while the icmsg_me instance is active.
162 : * @param[in] ept_cfg Configuration data of the endpoint for which the
163 : * handshake procedure is being initiated.
164 : * @param[out] id The value uniquely identifyig this endpoint.
165 : *
166 : * @retval 0 on success.
167 : * @retval -ENOMEM when there are no more empty endpoint configuration slots.
168 : */
169 1 : int icmsg_me_set_empty_ept_cfg_slot(struct icmsg_me_data_t *data,
170 : const struct ipc_ept_cfg *ept_cfg,
171 : icmsg_me_ept_id_t *id);
172 :
173 : /** @brief Set endpoint configuration in a selected endpoint slot
174 : *
175 : * During endpoint handshake the handshake follower must store endpoint id and
176 : * metadata required to finalize handshake and maintain the connection. This
177 : * function is a helper which stores the configuration in a configuration slot
178 : * associated with the id of the endpoint.
179 : *
180 : * @param[inout] data Structure containing run-time data used by the icmsg_me
181 : * instance. The structure is initialized with
182 : * @ref icmsg_me_init and its content must be preserved
183 : * while the icmsg_me instance is active.
184 : * @param[in] id The value uniquely identifyig this endpoint.
185 : * @param[in] ept_cfg Configuration data of the endpoint for which the
186 : * handshake procedure is ongoing.
187 : *
188 : * @retval 0 on success.
189 : * @retval -ENOENT when @p id is out of range of available slots.
190 : */
191 1 : int icmsg_me_set_ept_cfg(struct icmsg_me_data_t *data, icmsg_me_ept_id_t id,
192 : const struct ipc_ept_cfg *ept_cfg);
193 :
194 : /** @brief Get endpoint configuration from a selected endpoint slot
195 : *
196 : * When the icmsg_me instance receives data from a remote endpoint, it must
197 : * get the endpoint configuration based on the id of the endpoint. This
198 : * function is designed for this purpose.
199 : *
200 : * If retrieved endpoint configuration is not set, @p ept_cfg points to NULL.
201 : *
202 : * @param[inout] data Structure containing run-time data used by the icmsg_me
203 : * instance. The structure is initialized with
204 : * @ref icmsg_me_init and its content must be preserved
205 : * while the icmsg_me instance is active.
206 : * @param[in] id The value uniquely identifyig endpoint.
207 : * @param[in] ept_cfg Configuration data of the endpoint with given id.
208 : *
209 : * @retval 0 on success.
210 : * @retval -ENOENT when @p id is out of range of available slots.
211 : */
212 1 : int icmsg_me_get_ept_cfg(struct icmsg_me_data_t *data, icmsg_me_ept_id_t id,
213 : const struct ipc_ept_cfg **ept_cfg);
214 :
215 : /** @brief Reset endpoint configuration in a selected endpoint slot.
216 : *
217 : * If handshake fails or an endpoint is disconnected, then configuration
218 : * slot for given endpoint should be vacated. This function is intended to
219 : * be used for this purpose.
220 : *
221 : * @param[inout] data Structure containing run-time data used by the icmsg_me
222 : * instance. The structure is initialized with
223 : * @ref icmsg_me_init and its content must be preserved
224 : * while the icmsg_me instance is active.
225 : * @param[in] id The value uniquely identifyig endpoint.
226 : */
227 1 : void icmsg_me_reset_ept_cfg(struct icmsg_me_data_t *data, icmsg_me_ept_id_t id);
228 :
229 : /** @brief Send a message to the remote icmsg_me endpoint.
230 : *
231 : * @param[in] conf Structure containing configuration parameters for the
232 : * underlying icmsg instance.
233 : * @param[inout] data Structure containing run-time data used by the icmsg_me
234 : * instance. The structure is initialized with
235 : * @ref icmsg_me_init and its content must be preserved
236 : * while the icmsg_me instance is active.
237 : * @param[in] id Id of the endpoint to use.
238 : * @param[in] msg Pointer to a buffer containing data to send.
239 : * @param[in] len Size of data in the @p msg buffer.
240 : *
241 : *
242 : * @retval 0 on success.
243 : * @retval -EBADMSG when the requested data to send is too big.
244 : * @retval other errno codes from dependent modules.
245 : */
246 1 : int icmsg_me_send(const struct icmsg_config_t *conf,
247 : struct icmsg_me_data_t *data, icmsg_me_ept_id_t id,
248 : const void *msg, size_t len);
249 :
250 : /**
251 : * @}
252 : */
253 :
254 : #ifdef __cplusplus
255 : }
256 : #endif
257 :
258 : #endif /* ZEPHYR_INCLUDE_IPC_ICMSG_ME_H_ */
|
