Line data Source code
1 0 : /*
2 : * Copyright (c) 2021 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_IPC_SERVICE_IPC_SERVICE_BACKEND_H_
8 : #define ZEPHYR_INCLUDE_IPC_SERVICE_IPC_SERVICE_BACKEND_H_
9 :
10 : #include <zephyr/ipc/ipc_service.h>
11 : #include <zephyr/kernel.h>
12 : #include <stdio.h>
13 :
14 : #ifdef __cplusplus
15 : extern "C" {
16 : #endif
17 :
18 : /**
19 : * @brief IPC service backend
20 : * @defgroup ipc_service_backend IPC service backend
21 : * @ingroup ipc
22 : * @{
23 : */
24 :
25 : /** @brief IPC backend configuration structure.
26 : *
27 : * This structure is used for configuration backend during registration.
28 : */
29 1 : struct ipc_service_backend {
30 : /** @brief Pointer to the function that will be used to open an instance
31 : *
32 : * @param[in] instance Instance pointer.
33 : *
34 : * @retval -EALREADY when the instance is already opened.
35 : *
36 : * @retval 0 on success
37 : * @retval other errno codes depending on the implementation of the
38 : * backend.
39 : */
40 1 : int (*open_instance)(const struct device *instance);
41 :
42 : /** @brief Pointer to the function that will be used to close an instance
43 : *
44 : * @param[in] instance Instance pointer.
45 : *
46 : * @retval -EALREADY when the instance is not already inited.
47 : *
48 : * @retval 0 on success
49 : * @retval other errno codes depending on the implementation of the
50 : * backend.
51 : */
52 1 : int (*close_instance)(const struct device *instance);
53 :
54 : /** @brief Pointer to the function that will be used to send data to the endpoint.
55 : *
56 : * @param[in] instance Instance pointer.
57 : * @param[in] token Backend-specific token.
58 : * @param[in] data Pointer to the buffer to send.
59 : * @param[in] len Number of bytes to send.
60 : *
61 : * @retval -EINVAL when instance is invalid.
62 : * @retval -ENOENT when the endpoint is not registered with the instance.
63 : * @retval -EBADMSG when the message is invalid.
64 : * @retval -EBUSY when the instance is busy or not ready.
65 : * @retval -ENOMEM when no memory / buffers are available.
66 : *
67 : * @retval bytes number of bytes sent.
68 : * @retval other errno codes depending on the implementation of the
69 : * backend.
70 : */
71 1 : int (*send)(const struct device *instance, void *token,
72 : const void *data, size_t len);
73 :
74 : /** @brief Pointer to the function that will be used to register endpoints.
75 : *
76 : * @param[in] instance Instance to register the endpoint onto.
77 : * @param[out] token Backend-specific token.
78 : * @param[in] cfg Endpoint configuration.
79 : *
80 : * @retval -EINVAL when the endpoint configuration or instance is invalid.
81 : * @retval -EBUSY when the instance is busy or not ready.
82 : *
83 : * @retval 0 on success
84 : * @retval other errno codes depending on the implementation of the
85 : * backend.
86 : */
87 1 : int (*register_endpoint)(const struct device *instance,
88 : void **token,
89 : const struct ipc_ept_cfg *cfg);
90 :
91 : /** @brief Pointer to the function that will be used to deregister endpoints
92 : *
93 : * @param[in] instance Instance from which to deregister the endpoint.
94 : * @param[in] token Backend-specific token.
95 : *
96 : * @retval -EINVAL when the endpoint configuration or instance is invalid.
97 : * @retval -ENOENT when the endpoint is not registered with the instance.
98 : * @retval -EBUSY when the instance is busy or not ready.
99 : *
100 : * @retval 0 on success
101 : * @retval other errno codes depending on the implementation of the
102 : * backend.
103 : */
104 1 : int (*deregister_endpoint)(const struct device *instance, void *token);
105 :
106 : /** @brief Pointer to the function that will return the TX buffer size
107 : *
108 : * @param[in] instance Instance pointer.
109 : * @param[in] token Backend-specific token.
110 : *
111 : * @retval -EINVAL when instance is invalid.
112 : * @retval -ENOENT when the endpoint is not registered with the instance.
113 : * @retval -ENOTSUP when the operation is not supported.
114 : *
115 : * @retval size TX buffer size on success.
116 : * @retval other errno codes depending on the implementation of the
117 : * backend.
118 : */
119 1 : int (*get_tx_buffer_size)(const struct device *instance, void *token);
120 :
121 : /** @brief Pointer to the function that will return an empty TX buffer.
122 : *
123 : * @param[in] instance Instance pointer.
124 : * @param[in] token Backend-specific token.
125 : * @param[out] data Pointer to the empty TX buffer.
126 : * @param[in,out] len Pointer to store the TX buffer size.
127 : * @param[in] wait Timeout waiting for an available TX buffer.
128 : *
129 : * @retval -EINVAL when instance is invalid.
130 : * @retval -ENOENT when the endpoint is not registered with the instance.
131 : * @retval -ENOTSUP when the operation or the timeout is not supported.
132 : * @retval -ENOBUFS when there are no TX buffers available.
133 : * @retval -EALREADY when a buffer was already claimed and not yet released.
134 : * @retval -ENOMEM when the requested size is too big (and the size parameter
135 : * contains the maximum allowed size).
136 : *
137 : * @retval 0 on success
138 : * @retval other errno codes depending on the implementation of the
139 : * backend.
140 : */
141 1 : int (*get_tx_buffer)(const struct device *instance, void *token,
142 : void **data, uint32_t *len, k_timeout_t wait);
143 :
144 : /** @brief Pointer to the function that will drop a TX buffer.
145 : *
146 : * @param[in] instance Instance pointer.
147 : * @param[in] token Backend-specific token.
148 : * @param[in] data Pointer to the TX buffer.
149 : *
150 : * @retval -EINVAL when instance is invalid.
151 : * @retval -ENOENT when the endpoint is not registered with the instance.
152 : * @retval -ENOTSUP when this function is not supported.
153 : * @retval -EALREADY when the buffer was already dropped.
154 : *
155 : * @retval 0 on success
156 : * @retval other errno codes depending on the implementation of the
157 : * backend.
158 : */
159 1 : int (*drop_tx_buffer)(const struct device *instance, void *token,
160 : const void *data);
161 :
162 : /** @brief Pointer to the function that will be used to send data to
163 : * the endpoint when the TX buffer has been obtained using @ref
164 : * ipc_service_get_tx_buffer
165 : *
166 : * @param[in] instance Instance pointer.
167 : * @param[in] token Backend-specific token.
168 : * @param[in] data Pointer to the buffer to send.
169 : * @param[in] len Number of bytes to send.
170 : *
171 : * @retval -EINVAL when instance is invalid.
172 : * @retval -ENOENT when the endpoint is not registered with the instance.
173 : * @retval -EBADMSG when the data is invalid (i.e. invalid data format,
174 : * invalid length, ...)
175 : * @retval -EBUSY when the instance is busy or not ready.
176 : *
177 : * @retval bytes number of bytes sent.
178 : * @retval other errno codes depending on the implementation of the
179 : * backend.
180 : */
181 1 : int (*send_nocopy)(const struct device *instance, void *token,
182 : const void *data, size_t len);
183 :
184 : /** @brief Pointer to the function that will hold the RX buffer
185 : *
186 : * @param[in] instance Instance pointer.
187 : * @param[in] token Backend-specific token.
188 : * @param[in] data Pointer to the RX buffer to hold.
189 : *
190 : * @retval -EINVAL when instance is invalid.
191 : * @retval -ENOENT when the endpoint is not registered with the instance.
192 : * @retval -EALREADY when the buffer data has been already hold.
193 : * @retval -ENOTSUP when this function is not supported.
194 : *
195 : * @retval 0 on success
196 : * @retval other errno codes depending on the implementation of the
197 : * backend.
198 : */
199 1 : int (*hold_rx_buffer)(const struct device *instance, void *token,
200 : void *data);
201 :
202 : /** @brief Pointer to the function that will release the RX buffer.
203 : *
204 : * @param[in] instance Instance pointer.
205 : * @param[in] token Backend-specific token.
206 : * @param[in] data Pointer to the RX buffer to release.
207 : *
208 : * @retval -EINVAL when instance is invalid.
209 : * @retval -ENOENT when the endpoint is not registered with the instance.
210 : * @retval -EALREADY when the buffer data has been already released.
211 : * @retval -ENOTSUP when this function is not supported.
212 : *
213 : * @retval 0 on success
214 : * @retval other errno codes depending on the implementation of the
215 : * backend.
216 : */
217 1 : int (*release_rx_buffer)(const struct device *instance, void *token,
218 : void *data);
219 : };
220 :
221 : /**
222 : * @}
223 : */
224 :
225 : #ifdef __cplusplus
226 : }
227 : #endif
228 :
229 : #endif /* ZEPHYR_INCLUDE_IPC_SERVICE_IPC_SERVICE_BACKEND_H_ */
|
