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