Monado OpenXR Runtime
Loading...
Searching...
No Matches
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 */
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 */
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 Number of bytes to read. On Unix this function blocks until
69 * exactly @p size bytes are received or an error occurs. On Windows message-mode
70 * pipes, @p size is the maximum number of bytes to read from one message. Must
71 * be greater than 0.
72 *
73 * @public @memberof ipc_message_channel
74 */
76ipc_receive(struct ipc_message_channel *imc, void *out_data, size_t size);
77
78/*!
79 * @name File Descriptor or HANDLE utilities
80 * @brief These are typically called from within the send/receive_handles
81 * functions.
82 * @{
83 */
84#ifdef XRT_OS_UNIX
85
86/*!
87 * Receive a message along with a known number of file descriptors over the IPC
88 * channel.
89 *
90 * @param imc Message channel to use
91 * @param[out] out_data Pointer to the buffer to fill with data. Must not be
92 * null.
93 * @param[in] size Exact byte count for this one recvmsg. A short count is
94 * an error: unlike ipc_receive, this function does not read
95 * the rest of a message the kernel split. Must be greater
96 * than 0.
97 * @param[out] out_fds Array of file descriptors to populate. Must not be null.
98 * @param[in] fd_count Number of elements to receive into @p out_fds, must be
99 * greater than 0 and must match the value provided at the
100 * other end.
101 *
102 * @public @memberof ipc_message_channel
103 */
105ipc_receive_fds(struct ipc_message_channel *imc, void *out_data, size_t size, int *out_fds, uint32_t fd_count);
106
107/*!
108 * Send a message along with file descriptors over the IPC channel.
109 *
110 * @param imc Message channel to use
111 * @param[in] data Pointer to the data buffer to send. Must not be
112 * null: use a filler message if necessary.
113 * @param[in] size Size of data pointed-to by @p data, must be greater than 0.
114 * @param[out] fds Array of file descriptors to send. Must not benull.
115 * @param[in] fd_count Number of elements in @p fds, must be greater than 0. If
116 * this is variable, it must also be separately transmitted
117 * ahead of time, because the receiver must have the same
118 * value in its receive call.
119 *
120 * @public @memberof ipc_message_channel
121 */
123ipc_send_fds(struct ipc_message_channel *imc, const void *data, size_t size, const int *fds, uint32_t fd_count);
124
125#elif defined(XRT_OS_WINDOWS)
126
127/*!
128 * Receive a message along with a known number of file HANDLEs over the IPC
129 * channel.
130 *
131 * @param imc Message channel to use
132 * @param[out] out_data Pointer to the buffer to fill with data. Must not be
133 * null.
134 * @param[in] size Maximum size to read, must be greater than 0
135 * @param[out] out_handles Array of file HANDLEs to populate. Must not be
136 * null.
137 * @param[in] handle_count Number of elements to receive into @p out_handles,
138 * must be greater than 0 and must match the value provided at the other end.
139 *
140 * @public @memberof ipc_message_channel
141 */
143ipc_receive_handles(
144 struct ipc_message_channel *imc, void *out_data, size_t size, HANDLE *out_handles, uint32_t handle_count);
145
146/*!
147 * Send a message along with file HANDLEs over the IPC channel.
148 *
149 * @param imc Message channel to use
150 * @param[in] data Pointer to the data buffer to send. Must not be
151 * null: use a filler message if necessary.
152 * @param[in] size Size of data pointed-to by @p data, must be greater than 0
153 * @param[out] handles Array of file HANDLEs to send. Must not be
154 * null.
155 * @param[in] handle_count Number of elements in @p handles, must be greater
156 * than 0. If this is variable, it must also be separately transmitted ahead of
157 * time, because the receiver must have the same value in its receive call.
158 *
159 * @public @memberof ipc_message_channel
160 */
162ipc_send_handles(
163 struct ipc_message_channel *imc, const void *data, size_t size, const HANDLE *handles, uint32_t handle_count);
164
165#endif // XRT_OS_UNIX
166/*!
167 * @}
168 */
169
170/*!
171 * @name Shared memory handle utilities
172 * @brief Send/receive shared memory handles along with scalar/aggregate message
173 * data.
174 * @{
175 */
176
177/*!
178 * Receive a message along with a known number of shared memory handles over the
179 * IPC channel.
180 *
181 * @param imc Message channel to use
182 * @param[out] out_data Pointer to the buffer to fill with data. Must not be
183 * null.
184 * @param[in] size Maximum size to read, must be greater than 0
185 * @param[out] out_handles Array of shared memory handles to populate. Must not
186 * be null.
187 * @param[in] handle_count Number of elements to receive into @p out_handles,
188 * must be greater than 0 and must match the value provided at the other end.
189 *
190 * @public @memberof ipc_message_channel
191 * @see xrt_shmem_handle_t
192 */
194ipc_receive_handles_shmem(struct ipc_message_channel *imc,
195 void *out_data,
196 size_t size,
197 xrt_shmem_handle_t *out_handles,
198 uint32_t handle_count);
199
200
201/*!
202 * Send a message along with shared memory handles over the IPC channel.
203 *
204 * @param imc Message channel to use
205 * @param[in] data Pointer to the data buffer to send. Must not be
206 * null: use a filler message if necessary.
207 * @param[in] size Size of data pointed-to by @p data, must be greater than 0
208 * @param[out] handles Array of shared memory handles to send. Must not be
209 * null.
210 * @param[in] handle_count Number of elements in @p handles, must be greater
211 * than 0. If this is variable, it must also be separately transmitted ahead of
212 * time, because the receiver must have the same value in its receive call.
213 *
214 * @public @memberof ipc_message_channel
215 * @see xrt_shmem_handle_t
216 */
218ipc_send_handles_shmem(struct ipc_message_channel *imc,
219 const void *data,
220 size_t size,
221 const xrt_shmem_handle_t *handles,
222 uint32_t handle_count);
223/*!
224 * @}
225 */
226
227
228/*!
229 * @name Graphics buffer handle utilities
230 * @brief Send/receive graphics buffer handles along with scalar/aggregate
231 * message data.
232 * @{
233 */
234
235/*!
236 * Receive a message along with a known number of graphics buffer handles over
237 * the IPC channel.
238 *
239 * @param imc Message channel to use
240 * @param[out] out_data Pointer to the buffer to fill with data. Must not be
241 * null.
242 * @param[in] size Maximum size to read, must be greater than 0
243 * @param[out] out_handles Array of graphics buffer handles to populate. Must
244 * not be null.
245 * @param[in] handle_count Number of elements to receive into @p out_handles,
246 * must be greater than 0 and must match the value provided at the other end.
247 *
248 * @public @memberof ipc_message_channel
249 * @see xrt_graphics_buffer_handle_t
250 */
252ipc_receive_handles_graphics_buffer(struct ipc_message_channel *imc,
253 void *out_data,
254 size_t size,
255 xrt_graphics_buffer_handle_t *out_handles,
256 uint32_t handle_count);
257
258
259/*!
260 * Send a message along with native graphics buffer handles over the IPC
261 * channel.
262 *
263 * @param imc Message channel to use
264 * @param[in] data Pointer to the data buffer to send. Must not be
265 * null: use a filler message if necessary.
266 * @param[in] size Size of data pointed-to by @p data, must be greater than 0
267 * @param[out] handles Array of graphics buffer handles to send. Must not be
268 * null.
269 * @param[in] handle_count Number of elements in @p handles, must be greater
270 * than 0. If this is variable, it must also be separately transmitted ahead of
271 * time, because the receiver must have the same value in its receive call.
272 *
273 * @public @memberof ipc_message_channel
274 * @see xrt_graphics_buffer_handle_t
275 */
277ipc_send_handles_graphics_buffer(struct ipc_message_channel *imc,
278 const void *data,
279 size_t size,
280 const xrt_graphics_buffer_handle_t *handles,
281 uint32_t handle_count);
282
283/*!
284 * @}
285 */
286
287
288/*!
289 * @name Graphics buffer handle utilities
290 * @brief Send/receive graphics buffer handles along with scalar/aggregate
291 * message data.
292 * @{
293 */
294
295/*!
296 * Receive a message along with a known number of graphics sync handles over
297 * the IPC channel.
298 *
299 * @param imc Message channel to use
300 * @param[out] out_data Pointer to the sync to fill with data. Must not be null.
301 * @param[in] size Maximum size to read, must be greater than 0
302 * @param[out] out_handles Array of graphics sync handles to populate. Must not
303 * be null.
304 * @param[in] handle_count Number of elements to receive into @p out_handles,
305 * must be greater than 0 and must match the value provided at the other end.
306 *
307 * @public @memberof ipc_message_channel
308 * @see xrt_graphics_sync_handle_t
309 */
311ipc_receive_handles_graphics_sync(struct ipc_message_channel *imc,
312 void *out_data,
313 size_t size,
314 xrt_graphics_sync_handle_t *out_handles,
315 uint32_t handle_count);
316
317/*!
318 * Send a message along with native graphics sync handles over the IPC channel.
319 *
320 * @param imc Message channel to use
321 * @param[in] data Pointer to the data sync to send. Must not be null: use a
322 * filler message if necessary.
323 * @param[in] size Size of data pointed-to by @p data, must be greater than 0
324 * @param[out] handles Array of graphics sync handles to send. Must not be
325 * null.
326 * @param[in] handle_count Number of elements in @p handles, must be greater than
327 * 0. If this is variable, it must also be separately transmitted ahead of time,
328 * because the receiver must have the same value in its receive call.
329 *
330 * @public @memberof ipc_message_channel
331 * @see xrt_graphics_sync_handle_t
332 */
334ipc_send_handles_graphics_sync(struct ipc_message_channel *imc,
335 const void *data,
336 size_t size,
337 const xrt_graphics_sync_handle_t *handles,
338 uint32_t handle_count);
339
340/*!
341 * @}
342 */
343
344#ifdef __cplusplus
345}
346#endif
Generic typedef for platform-specific shared memory handle.
u_logging_level
Logging level enum.
Definition u_logging.h:45
enum xrt_result xrt_result_t
Result type used across Monado.
Wrapper for a socket and flags.
Definition ipc_message_channel.h:30
Basic logging functionality.
Native handle types.
int xrt_graphics_buffer_handle_t
The type underlying buffers shared between compositor clients and the main compositor.
Definition xrt_handles.h:252
int xrt_graphics_sync_handle_t
The type underlying synchronization primitives (semaphores, etc) shared between compositor clients an...
Definition xrt_handles.h:354
int xrt_ipc_handle_t
The type for an IPC handle.
Definition xrt_handles.h:75
Internal result type for XRT.