Monado OpenXR Runtime
ipc_message_channel.h
Go to the documentation of this file.
1// Copyright 2020-2023, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief IPC message channel functions.
6 * @author Rylie Pavlik <rylie.pavlik@collabora.com>
7 * @ingroup ipc_shared
8 */
9
10#pragma once
11
12#include <xrt/xrt_handles.h>
13#include <xrt/xrt_results.h>
14
15#include <stddef.h>
16#include <stdbool.h>
17#include <stdint.h>
18
19#include "util/u_logging.h"
20
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26/*!
27 * Wrapper for a socket and flags.
28 */
29struct ipc_message_channel
30{
31 xrt_ipc_handle_t ipc_handle;
32 enum u_logging_level log_level;
33};
34
35/*!
36 * Close an IPC message channel
37 *
38 * @public @memberof ipc_message_channel
39 */
40void
41ipc_message_channel_close(struct ipc_message_channel *imc);
42
43/*!
44 * Send a bare message over the IPC channel.
45 *
46 * There are other functions if you have handles, not just scalar/aggregate
47 * data.
48 *
49 * @param imc Message channel to use
50 * @param[in] data Pointer to the data buffer to send. Must not be
51 * null: use a filler message if necessary.
52 * @param[in] size Size of data pointed-to by @p data, must be greater than 0
53 *
54 * @public @memberof ipc_message_channel
55 */
56xrt_result_t
57ipc_send(struct ipc_message_channel *imc, const void *data, size_t size);
58
59/*!
60 * Receive a bare message over the IPC channel.
61 *
62 * There are other functions if you have handles, not just scalar/aggregate
63 * data.
64 *
65 * @param imc Message channel to use
66 * @param[out] out_data Pointer to the buffer to fill with data. Must not be
67 * null.
68 * @param[in] size Maximum size to read, must be greater than 0
69 *
70 * @public @memberof ipc_message_channel
71 */
72xrt_result_t
73ipc_receive(struct ipc_message_channel *imc, void *out_data, size_t size);
74
75/*!
76 * @name File Descriptor or HANDLE utilities
77 * @brief These are typically called from within the send/receive_handles
78 * functions.
79 * @{
80 */
81#ifdef XRT_OS_UNIX
82
83/*!
84 * Receive a message along with a known number of file descriptors over the IPC
85 * channel.
86 *
87 * @param imc Message channel to use
88 * @param[out] out_data Pointer to the buffer to fill with data. Must not be
89 * null.
90 * @param[in] size Maximum size to read, must be greater than 0
91 * @param[out] out_fds Array of file descriptors to populate. Must not be null.
92 * @param[in] fd_count Number of elements to receive into @p out_fds, must be
93 * greater than 0 and must match the value provided at the
94 * other end.
95 *
96 * @public @memberof ipc_message_channel
97 */
98xrt_result_t
99ipc_receive_fds(struct ipc_message_channel *imc, void *out_data, size_t size, int *out_fds, uint32_t fd_count);
100
101/*!
102 * Send a message along with file descriptors over the IPC channel.
103 *
104 * @param imc Message channel to use
105 * @param[in] data Pointer to the data buffer to send. Must not be
106 * null: use a filler message if necessary.
107 * @param[in] size Size of data pointed-to by @p data, must be greater than 0.
108 * @param[out] fds Array of file descriptors to send. Must not benull.
109 * @param[in] fd_count Number of elements in @p fds, must be greater than 0. If
110 * this is variable, it must also be separately transmitted
111 * ahead of time, because the receiver must have the same
112 * value in its receive call.
113 *
114 * @public @memberof ipc_message_channel
115 */
116xrt_result_t
117ipc_send_fds(struct ipc_message_channel *imc, const void *data, size_t size, const int *fds, uint32_t fd_count);
118
119#elif defined(XRT_OS_WINDOWS)
120
121/*!
122 * Receive a message along with a known number of file HANDLEs over the IPC
123 * channel.
124 *
125 * @param imc Message channel to use
126 * @param[out] out_data Pointer to the buffer to fill with data. Must not be
127 * null.
128 * @param[in] size Maximum size to read, must be greater than 0
129 * @param[out] out_handles Array of file HANDLEs to populate. Must not be
130 * null.
131 * @param[in] handle_count Number of elements to receive into @p out_handles,
132 * must be greater than 0 and must match the value provided at the other end.
133 *
134 * @public @memberof ipc_message_channel
135 */
136xrt_result_t
137ipc_receive_handles(
138 struct ipc_message_channel *imc, void *out_data, size_t size, HANDLE *out_handles, uint32_t handle_count);
139
140/*!
141 * Send a message along with file HANDLEs over the IPC channel.
142 *
143 * @param imc Message channel to use
144 * @param[in] data Pointer to the data buffer to send. Must not be
145 * null: use a filler message if necessary.
146 * @param[in] size Size of data pointed-to by @p data, must be greater than 0
147 * @param[out] handles Array of file HANDLEs to send. Must not be
148 * null.
149 * @param[in] handle_count Number of elements in @p handles, must be greater
150 * than 0. If this is variable, it must also be separately transmitted ahead of
151 * time, because the receiver must have the same value in its receive call.
152 *
153 * @public @memberof ipc_message_channel
154 */
155xrt_result_t
156ipc_send_handles(
157 struct ipc_message_channel *imc, const void *data, size_t size, const HANDLE *handles, uint32_t handle_count);
158
159#endif // XRT_OS_UNIX
160/*!
161 * @}
162 */
163
164/*!
165 * @name Shared memory handle utilities
166 * @brief Send/receive shared memory handles along with scalar/aggregate message
167 * data.
168 * @{
169 */
170
171/*!
172 * Receive a message along with a known number of shared memory handles over the
173 * IPC channel.
174 *
175 * @param imc Message channel to use
176 * @param[out] out_data Pointer to the buffer to fill with data. Must not be
177 * null.
178 * @param[in] size Maximum size to read, must be greater than 0
179 * @param[out] out_handles Array of shared memory handles to populate. Must not
180 * be null.
181 * @param[in] handle_count Number of elements to receive into @p out_handles,
182 * must be greater than 0 and must match the value provided at the other end.
183 *
184 * @public @memberof ipc_message_channel
185 * @see xrt_shmem_handle_t
186 */
187xrt_result_t
188ipc_receive_handles_shmem(struct ipc_message_channel *imc,
189 void *out_data,
190 size_t size,
191 xrt_shmem_handle_t *out_handles,
192 uint32_t handle_count);
193
194
195/*!
196 * Send a message along with shared memory handles over the IPC channel.
197 *
198 * @param imc Message channel to use
199 * @param[in] data Pointer to the data buffer to send. Must not be
200 * null: use a filler message if necessary.
201 * @param[in] size Size of data pointed-to by @p data, must be greater than 0
202 * @param[out] handles Array of shared memory handles to send. Must not be
203 * null.
204 * @param[in] handle_count Number of elements in @p handles, must be greater
205 * than 0. If this is variable, it must also be separately transmitted ahead of
206 * time, because the receiver must have the same value in its receive call.
207 *
208 * @public @memberof ipc_message_channel
209 * @see xrt_shmem_handle_t
210 */
211xrt_result_t
212ipc_send_handles_shmem(struct ipc_message_channel *imc,
213 const void *data,
214 size_t size,
215 const xrt_shmem_handle_t *handles,
216 uint32_t handle_count);
217/*!
218 * @}
219 */
220
221
222/*!
223 * @name Graphics buffer handle utilities
224 * @brief Send/receive graphics buffer handles along with scalar/aggregate
225 * message data.
226 * @{
227 */
228
229/*!
230 * Receive a message along with a known number of graphics buffer handles over
231 * the IPC channel.
232 *
233 * @param imc Message channel to use
234 * @param[out] out_data Pointer to the buffer to fill with data. Must not be
235 * null.
236 * @param[in] size Maximum size to read, must be greater than 0
237 * @param[out] out_handles Array of graphics buffer handles to populate. Must
238 * not be null.
239 * @param[in] handle_count Number of elements to receive into @p out_handles,
240 * must be greater than 0 and must match the value provided at the other end.
241 *
242 * @public @memberof ipc_message_channel
243 * @see xrt_graphics_buffer_handle_t
244 */
245xrt_result_t
246ipc_receive_handles_graphics_buffer(struct ipc_message_channel *imc,
247 void *out_data,
248 size_t size,
249 xrt_graphics_buffer_handle_t *out_handles,
250 uint32_t handle_count);
251
252
253/*!
254 * Send a message along with native graphics buffer handles over the IPC
255 * channel.
256 *
257 * @param imc Message channel to use
258 * @param[in] data Pointer to the data buffer to send. Must not be
259 * null: use a filler message if necessary.
260 * @param[in] size Size of data pointed-to by @p data, must be greater than 0
261 * @param[out] handles Array of graphics buffer handles to send. Must not be
262 * null.
263 * @param[in] handle_count Number of elements in @p handles, must be greater
264 * than 0. If this is variable, it must also be separately transmitted ahead of
265 * time, because the receiver must have the same value in its receive call.
266 *
267 * @public @memberof ipc_message_channel
268 * @see xrt_graphics_buffer_handle_t
269 */
270xrt_result_t
271ipc_send_handles_graphics_buffer(struct ipc_message_channel *imc,
272 const void *data,
273 size_t size,
274 const xrt_graphics_buffer_handle_t *handles,
275 uint32_t handle_count);
276
277/*!
278 * @}
279 */
280
281
282/*!
283 * @name Graphics buffer handle utilities
284 * @brief Send/receive graphics buffer handles along with scalar/aggregate
285 * message data.
286 * @{
287 */
288
289/*!
290 * Receive a message along with a known number of graphics sync handles over
291 * the IPC channel.
292 *
293 * @param imc Message channel to use
294 * @param[out] out_data Pointer to the sync to fill with data. Must not be null.
295 * @param[in] size Maximum size to read, must be greater than 0
296 * @param[out] out_handles Array of graphics sync handles to populate. Must not
297 * be null.
298 * @param[in] handle_count Number of elements to receive into @p out_handles,
299 * must be greater than 0 and must match the value provided at the other end.
300 *
301 * @public @memberof ipc_message_channel
302 * @see xrt_graphics_sync_handle_t
303 */
304xrt_result_t
305ipc_receive_handles_graphics_sync(struct ipc_message_channel *imc,
306 void *out_data,
307 size_t size,
308 xrt_graphics_sync_handle_t *out_handles,
309 uint32_t handle_count);
310
311/*!
312 * Send a message along with native graphics sync handles over the IPC channel.
313 *
314 * @param imc Message channel to use
315 * @param[in] data Pointer to the data sync to send. Must not be null: use a
316 * filler message if necessary.
317 * @param[in] size Size of data pointed-to by @p data, must be greater than 0
318 * @param[out] handles Array of graphics sync handles to send. Must not be
319 * null.
320 * @param[in] handle_count Number of elements in @p handles, must be greater than
321 * 0. If this is variable, it must also be separately transmitted ahead of time,
322 * because the receiver must have the same value in its receive call.
323 *
324 * @public @memberof ipc_message_channel
325 * @see xrt_graphics_sync_handle_t
326 */
327xrt_result_t
328ipc_send_handles_graphics_sync(struct ipc_message_channel *imc,
329 const void *data,
330 size_t size,
331 const xrt_graphics_sync_handle_t *handles,
332 uint32_t handle_count);
333
334/*!
335 * @}
336 */
337
338#ifdef __cplusplus
339}
340#endif
xrt_shmem_handle_t
Generic typedef for platform-specific shared memory handle.
u_logging_level
u_logging_level
Logging level enum.
Definition: u_logging.h:43
xrt_result_t
enum xrt_result xrt_result_t
Result type used across Monado.
ipc_message_channel
Wrapper for a socket and flags.
Definition: ipc_message_channel.h:30
ipc_message_channel::ipc_send_handles_graphics_sync
xrt_result_t ipc_send_handles_graphics_sync(struct ipc_message_channel *imc, const void *data, size_t size, const xrt_graphics_sync_handle_t *handles, uint32_t handle_count)
Send a message along with native graphics sync handles over the IPC channel.
Definition: ipc_message_channel_windows.cpp:227
ipc_message_channel::ipc_receive_fds
xrt_result_t ipc_receive_fds(struct ipc_message_channel *imc, void *out_data, size_t size, int *out_fds, uint32_t fd_count)
Receive a message along with a known number of file descriptors over the IPC channel.
Definition: ipc_message_channel_unix.c:133
ipc_message_channel::ipc_receive_handles_graphics_sync
xrt_result_t ipc_receive_handles_graphics_sync(struct ipc_message_channel *imc, void *out_data, size_t size, xrt_graphics_sync_handle_t *out_handles, uint32_t handle_count)
Receive a message along with a known number of graphics sync handles over the IPC channel.
Definition: ipc_message_channel_windows.cpp:217
ipc_message_channel::ipc_receive_handles_shmem
xrt_result_t ipc_receive_handles_shmem(struct ipc_message_channel *imc, void *out_data, size_t size, xrt_shmem_handle_t *out_handles, uint32_t handle_count)
Receive a message along with a known number of shared memory handles over the IPC channel.
Definition: ipc_message_channel_unix.c:236
ipc_message_channel::ipc_send_handles_graphics_buffer
xrt_result_t ipc_send_handles_graphics_buffer(struct ipc_message_channel *imc, const void *data, size_t size, const xrt_graphics_buffer_handle_t *handles, uint32_t handle_count)
Send a message along with native graphics buffer handles over the IPC channel.
Definition: ipc_message_channel_windows.cpp:247
ipc_message_channel::ipc_receive
xrt_result_t ipc_receive(struct ipc_message_channel *imc, void *out_data, size_t size)
Receive a bare message over the IPC channel.
Definition: ipc_message_channel_unix.c:100
ipc_message_channel::ipc_send
xrt_result_t ipc_send(struct ipc_message_channel *imc, const void *data, size_t size)
Send a bare message over the IPC channel.
Definition: ipc_message_channel_unix.c:75
ipc_message_channel::ipc_message_channel_close
void ipc_message_channel_close(struct ipc_message_channel *imc)
Close an IPC message channel.
Definition: ipc_message_channel_unix.c:65
ipc_message_channel::ipc_send_handles_shmem
xrt_result_t ipc_send_handles_shmem(struct ipc_message_channel *imc, const void *data, size_t size, const xrt_shmem_handle_t *handles, uint32_t handle_count)
Send a message along with shared memory handles over the IPC channel.
Definition: ipc_message_channel_unix.c:246
ipc_message_channel::ipc_send_fds
xrt_result_t ipc_send_fds(struct ipc_message_channel *imc, const void *data, size_t size, const int *fds, uint32_t fd_count)
Send a message along with file descriptors over the IPC channel.
Definition: ipc_message_channel_unix.c:179
ipc_message_channel::ipc_receive_handles_graphics_buffer
xrt_result_t ipc_receive_handles_graphics_buffer(struct ipc_message_channel *imc, void *out_data, size_t size, xrt_graphics_buffer_handle_t *out_handles, uint32_t handle_count)
Receive a message along with a known number of graphics buffer handles over the IPC channel.
Definition: ipc_message_channel_windows.cpp:237
u_logging.h
Basic logging functionality.
xrt_handles.h
Native handle types.
xrt_graphics_buffer_handle_t
int xrt_graphics_buffer_handle_t
The type underlying buffers shared between compositor clients and the main compositor.
Definition: xrt_handles.h:246
xrt_graphics_sync_handle_t
int xrt_graphics_sync_handle_t
The type underlying synchronization primitives (semaphores, etc) shared between compositor clients an...
Definition: xrt_handles.h:348
xrt_ipc_handle_t
int xrt_ipc_handle_t
The type for an IPC handle.
Definition: xrt_handles.h:74
xrt_results.h
Internal result type for XRT.