matrixfurry.com
The open source OpenXR runtime
1// Copyright 2020, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief Shared memory helpers
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
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24/*!
25 * @class xrt_shmem_handle_t
26 * @brief Generic typedef for platform-specific shared memory handle.
27 */
28/*!
29 * Create and map a shared memory region.
30 *
31 * @param[in] size Desired size of region
32 * @param[in,out] out_handle Pointer to the handle to populate. Receives the
33 * handle if this succeeds, or the invalid value if it fails.
34 * @param[in,out] out_map Pointer to the pointer to populate with the mapping of
35 * this shared memory region. On failure, contents are undefined.
36 *
37 * @public @memberof xrt_shmem_handle_t
38 */
39xrt_result_t
40ipc_shmem_create(size_t size, xrt_shmem_handle_t *out_handle, void **out_map);
41
42/*!
43 * Map a shared memory region.
44 *
45 * @param[in] handle Handle for region
46 * @param[in] size Size of region
47 * @param[in,out] out_map Pointer to the pointer to populate with the mapping of
48 * this shared memory region.
49 *
50 * @public @memberof xrt_shmem_handle_t
51 */
52xrt_result_t
53ipc_shmem_map(xrt_shmem_handle_t handle, size_t size, void **out_map);
54
55/*!
56 * Unmap a shared memory region.
57 *
58 * @param[in] map_ptr pointer to region
59 * @param[in] size Size of region
60 *
61 * @public @memberof xrt_shmem_handle_t
62 */
63void
64ipc_shmem_unmap(void **map_ptr, size_t size);
65
66/*!
67 * Destroy a handle to a shared memory region.
68 *
69 * This probably does not destroy the underlying region, if other references to
70 * it (in this process or others) are still open.
71 *
72 * @param[in,out] handle_ptr Pointer to the handle to destroy - will be checked
73 * for validity, destroyed, and cleared.
74 * @param[in,out] map_ptr Pointer to the mapped memory to unmap - will be
75 * checked for validity, destroyed, and cleared. It's
76 * necessary unmap the region to destroy the shmem.
77 * @param[in] size Size of the mapped region.
78 *
79 * @public @memberof xrt_shmem_handle_t
80 */
81void
82ipc_shmem_destroy(xrt_shmem_handle_t *handle_ptr, void **map_ptr, size_t size);
83
84#ifdef __cplusplus
85}
86#endif