Line data Source code
1 0 : /*
2 : * Copyright (c) 2022 Trackunit Corporation
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #include <zephyr/types.h>
8 : #include <zephyr/kernel.h>
9 :
10 : #ifndef ZEPHYR_MODEM_PIPE_
11 : #define ZEPHYR_MODEM_PIPE_
12 :
13 : #ifdef __cplusplus
14 : extern "C" {
15 : #endif
16 :
17 : /**
18 : * @brief Modem Pipe
19 : * @defgroup modem_pipe Modem Pipe
20 : * @since 3.5
21 : * @version 1.0.0
22 : * @ingroup modem
23 : * @{
24 : */
25 :
26 : /** Modem pipe event */
27 0 : enum modem_pipe_event {
28 : MODEM_PIPE_EVENT_OPENED = 0,
29 : MODEM_PIPE_EVENT_RECEIVE_READY,
30 : MODEM_PIPE_EVENT_TRANSMIT_IDLE,
31 : MODEM_PIPE_EVENT_CLOSED,
32 : };
33 :
34 : /**
35 : * @cond INTERNAL_HIDDEN
36 : */
37 :
38 : struct modem_pipe;
39 :
40 : /**
41 : * @endcond
42 : */
43 :
44 0 : typedef void (*modem_pipe_api_callback)(struct modem_pipe *pipe, enum modem_pipe_event event,
45 : void *user_data);
46 :
47 : /**
48 : * @cond INTERNAL_HIDDEN
49 : */
50 :
51 : typedef int (*modem_pipe_api_open)(void *data);
52 :
53 : typedef int (*modem_pipe_api_transmit)(void *data, const uint8_t *buf, size_t size);
54 :
55 : typedef int (*modem_pipe_api_receive)(void *data, uint8_t *buf, size_t size);
56 :
57 : typedef int (*modem_pipe_api_close)(void *data);
58 :
59 : struct modem_pipe_api {
60 : modem_pipe_api_open open;
61 : modem_pipe_api_transmit transmit;
62 : modem_pipe_api_receive receive;
63 : modem_pipe_api_close close;
64 : };
65 :
66 : struct modem_pipe {
67 : void *data;
68 : const struct modem_pipe_api *api;
69 : modem_pipe_api_callback callback;
70 : void *user_data;
71 : struct k_spinlock spinlock;
72 : struct k_event event;
73 : };
74 :
75 : /**
76 : * @brief Initialize a modem pipe
77 : *
78 : * @param pipe Pipe instance to initialize
79 : * @param data Pipe data to bind to pipe instance
80 : * @param api Pipe API implementation to bind to pipe instance
81 : */
82 : void modem_pipe_init(struct modem_pipe *pipe, void *data, const struct modem_pipe_api *api);
83 :
84 : /**
85 : * @endcond
86 : */
87 :
88 : /**
89 : * @brief Open pipe
90 : *
91 : * @param pipe Pipe instance
92 : * @param timeout Timeout waiting for pipe to open
93 : *
94 : * @retval 0 if pipe was successfully opened or was already open
95 : * @retval -errno code otherwise
96 : *
97 : * @warning Be cautious when using this synchronous version of the call.
98 : * It may block the calling thread, which in the case of the system workqueue
99 : * can result in a deadlock until this call times out waiting for the pipe to be open.
100 : */
101 1 : int modem_pipe_open(struct modem_pipe *pipe, k_timeout_t timeout);
102 :
103 : /**
104 : * @brief Open pipe asynchronously
105 : *
106 : * @param pipe Pipe instance
107 : *
108 : * @note The MODEM_PIPE_EVENT_OPENED event is invoked immediately if pipe is
109 : * already opened.
110 : *
111 : * @retval 0 if pipe open was called successfully or pipe was already open
112 : * @retval -errno code otherwise
113 : */
114 1 : int modem_pipe_open_async(struct modem_pipe *pipe);
115 :
116 : /**
117 : * @brief Attach pipe to callback
118 : *
119 : * @param pipe Pipe instance
120 : * @param callback Callback called when pipe event occurs
121 : * @param user_data Free to use user data passed with callback
122 : *
123 : * @note The MODEM_PIPE_EVENT_RECEIVE_READY event is invoked immediately if pipe has pending
124 : * data ready to receive.
125 : */
126 1 : void modem_pipe_attach(struct modem_pipe *pipe, modem_pipe_api_callback callback, void *user_data);
127 :
128 : /**
129 : * @brief Transmit data through pipe
130 : *
131 : * @param pipe Pipe to transmit through
132 : * @param buf Data to transmit
133 : * @param size Number of bytes to transmit
134 : *
135 : * @retval Number of bytes placed in pipe
136 : * @retval -EPERM if pipe is closed
137 : * @retval -errno code on error
138 : *
139 : * @warning This call must be non-blocking
140 : */
141 1 : int modem_pipe_transmit(struct modem_pipe *pipe, const uint8_t *buf, size_t size);
142 :
143 : /**
144 : * @brief Receive data through pipe
145 : *
146 : * @param pipe Pipe to receive from
147 : * @param buf Destination for received data; must not be already in use in a modem module.
148 : * @param size Capacity of destination for received data
149 : *
150 : * @retval Number of bytes received from pipe
151 : * @retval -EPERM if pipe is closed
152 : * @retval -errno code on error
153 : *
154 : * @warning This call must be non-blocking
155 : */
156 1 : int modem_pipe_receive(struct modem_pipe *pipe, uint8_t *buf, size_t size);
157 :
158 : /**
159 : * @brief Clear callback
160 : *
161 : * @param pipe Pipe instance
162 : */
163 1 : void modem_pipe_release(struct modem_pipe *pipe);
164 :
165 : /**
166 : * @brief Close pipe
167 : *
168 : * @param pipe Pipe instance
169 : * @param timeout Timeout waiting for pipe to close
170 : *
171 : * @retval 0 if pipe open was called closed or pipe was already closed
172 : * @retval -errno code otherwise
173 : *
174 : * @warning Be cautious when using this synchronous version of the call.
175 : * It may block the calling thread, which in the case of the system workqueue
176 : * can result in a deadlock until this call times out waiting for the pipe to be closed.
177 : */
178 1 : int modem_pipe_close(struct modem_pipe *pipe, k_timeout_t timeout);
179 :
180 : /**
181 : * @brief Close pipe asynchronously
182 : *
183 : * @param pipe Pipe instance
184 : *
185 : * @note The MODEM_PIPE_EVENT_CLOSED event is invoked immediately if pipe is
186 : * already closed.
187 : *
188 : * @retval 0 if pipe close was called successfully or pipe was already closed
189 : * @retval -errno code otherwise
190 : */
191 1 : int modem_pipe_close_async(struct modem_pipe *pipe);
192 :
193 : /**
194 : * @cond INTERNAL_HIDDEN
195 : */
196 :
197 : /**
198 : * @brief Notify user of pipe that it has opened
199 : *
200 : * @param pipe Pipe instance
201 : *
202 : * @note Invoked from instance which initialized the pipe instance
203 : */
204 : void modem_pipe_notify_opened(struct modem_pipe *pipe);
205 :
206 : /**
207 : * @brief Notify user of pipe that it has closed
208 : *
209 : * @param pipe Pipe instance
210 : *
211 : * @note Invoked from instance which initialized the pipe instance
212 : */
213 : void modem_pipe_notify_closed(struct modem_pipe *pipe);
214 :
215 : /**
216 : * @brief Notify user of pipe that data is ready to be received
217 : *
218 : * @param pipe Pipe instance
219 : *
220 : * @note Invoked from instance which initialized the pipe instance
221 : */
222 : void modem_pipe_notify_receive_ready(struct modem_pipe *pipe);
223 :
224 : /**
225 : * @brief Notify user of pipe that pipe has no more data to transmit
226 : *
227 : * @param pipe Pipe instance
228 : *
229 : * @note Invoked from instance which initialized the pipe instance
230 : */
231 : void modem_pipe_notify_transmit_idle(struct modem_pipe *pipe);
232 :
233 : /**
234 : * @endcond
235 : */
236 :
237 : /**
238 : * @}
239 : */
240 :
241 : #ifdef __cplusplus
242 : }
243 : #endif
244 :
245 : #endif /* ZEPHYR_MODEM_PIPE_ */
|
