• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright 2016 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 // This file contains types/functions and constants for platform handle wrapping
6 // and unwrapping APIs.
7 //
8 // Note: This header should be compilable as C.
9 
10 #ifndef MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_
11 #define MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_
12 
13 #include <stdint.h>
14 
15 #include "mojo/public/c/system/system_export.h"
16 #include "mojo/public/c/system/types.h"
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 // The type of handle value contained in a |MojoPlatformHandle| structure.
23 typedef uint32_t MojoPlatformHandleType;
24 
25 // An invalid handle value. Other contents of the |MojoPlatformHandle| are
26 // ignored.
27 #define MOJO_PLATFORM_HANDLE_TYPE_INVALID ((MojoPlatformHandleType)0)
28 
29 // The |MojoPlatformHandle| value represents a POSIX file descriptor. Only
30 // usable on POSIX host systems (e.g. Android, Linux, Chrome OS, Mac).
31 #define MOJO_PLATFORM_HANDLE_TYPE_FILE_DESCRIPTOR ((MojoPlatformHandleType)1)
32 
33 // The |MojoPlatformHandle| value represents a Mach port right (e.g. a value
34 // opaquely of type |mach_port_t|). Only usable on Mac OS X hosts.
35 #define MOJO_PLATFORM_HANDLE_TYPE_MACH_PORT ((MojoPlatformHandleType)2)
36 
37 // The |MojoPlatformHandle| value represents a Windows HANDLE value. Only usable
38 // on Windows hosts.
39 #define MOJO_PLATFORM_HANDLE_TYPE_WINDOWS_HANDLE ((MojoPlatformHandleType)3)
40 
41 // The |MojoPlatformHandle| value represents a Fuchsia system handle. Only
42 // usable on Fuchsia hosts.
43 #define MOJO_PLATFORM_HANDLE_TYPE_FUCHSIA_HANDLE ((MojoPlatformHandleType)4)
44 
45 // |MojoPlatformHandle|: A handle to a native platform object.
46 //
47 //     |uint32_t struct_size|: The size of this structure. Used for versioning
48 //         to allow for future extensions.
49 //
50 //     |MojoPlatformHandleType type|: The type of handle stored in |value|.
51 //
52 //     |uint64_t value|: The value of this handle. Ignored if |type| is
53 //         MOJO_PLATFORM_HANDLE_TYPE_INVALID. Otherwise the meaning of this
54 //         value depends on the value of |type|.
55 //
56 
57 // Represents a native platform handle value for coersion to or from a wrapping
58 // Mojo handle.
59 struct MOJO_ALIGNAS(8) MojoPlatformHandle {
60   // The size of this structure, used for versioning.
61   uint32_t struct_size;
62 
63   // The type of platform handle represented by |value|.
64   MojoPlatformHandleType type;
65 
66   // An opaque representation of the native platform handle. Interpretation and
67   // treatment of this value by Mojo depends on the value of |type|.
68   uint64_t value;
69 };
70 MOJO_STATIC_ASSERT(sizeof(MojoPlatformHandle) == 16,
71                    "MojoPlatformHandle has wrong size");
72 
73 // Flags passed to |MojoWrapPlatformHandle()| via
74 // |MojoWrapPlatformHandleOptions|.
75 typedef uint32_t MojoWrapPlatformHandleFlags;
76 
77 // No flags. Default behavior.
78 #define MOJO_WRAP_PLATFORM_HANDLE_FLAG_NONE ((MojoWrapPlatformHandleFlags)0)
79 
80 // Options passed to |MojoWrapPlatformHandle()|.
81 struct MOJO_ALIGNAS(8) MojoWrapPlatformHandleOptions {
82   // The size of this structure, used for versioning.
83   uint32_t struct_size;
84 
85   // See |MojoWrapPlatformHandleFlags|.
86   MojoWrapPlatformHandleFlags flags;
87 };
88 MOJO_STATIC_ASSERT(sizeof(MojoWrapPlatformHandleOptions) == 8,
89                    "MojoWrapPlatformHandleOptions has wrong size");
90 
91 // Flags passed to |MojoUnwrapPlatformHandle()| via
92 // |MojoUnwrapPlatformHandleOptions|.
93 typedef uint32_t MojoUnwrapPlatformHandleFlags;
94 
95 // No flags. Default behavior.
96 #define MOJO_UNWRAP_PLATFORM_HANDLE_FLAG_NONE ((MojoUnwrapPlatformHandleFlags)0)
97 
98 // Options passed to |MojoUnwrapPlatformHandle()|.
99 struct MOJO_ALIGNAS(8) MojoUnwrapPlatformHandleOptions {
100   // The size of this structure, used for versioning.
101   uint32_t struct_size;
102 
103   // See |MojoUnwrapPlatformHandleFlags|.
104   MojoUnwrapPlatformHandleFlags flags;
105 };
106 MOJO_STATIC_ASSERT(sizeof(MojoUnwrapPlatformHandleOptions) == 8,
107                    "MojoUnwrapPlatformHandleOptions has wrong size");
108 
109 // A GUID value used to identify the shared memory region backing a Mojo shared
110 // buffer handle.
111 struct MOJO_ALIGNAS(8) MojoSharedBufferGuid {
112   uint64_t high;
113   uint64_t low;
114 };
115 
116 // The access type of shared memory region wrapped by a Mojo shared buffer
117 // handle. See values defined below.
118 typedef uint32_t MojoPlatformSharedMemoryRegionAccessMode;
119 
120 // The region is read-only, meaning there is at most one writable mapped handle
121 // to the region somewhere, and there are any number of handles (including this
122 // one) which can only be mapped read-only.
123 //
124 // WARNING: See notes in |MojoWrapPlatformSharedMemoryRegion()| about the
125 // meaning and usage of different access modes. This CANNOT be used to change
126 // a buffer's access mode; it is merely an informational value to allow Mojo
127 // to retain consistency between wrapping and unwrapping of buffer handles.
128 #define MOJO_PLATFORM_SHARED_MEMORY_REGION_ACCESS_MODE_READ_ONLY \
129   ((MojoPlatformSharedMemoryRegionAccessMode)0)
130 
131 // The region is writable, meaning there is exactly one handle to the region and
132 // it is mappable read/writable.
133 //
134 // WARNING: See notes in |MojoWrapPlatformSharedMemoryRegion()| about the
135 // meaning and usage of different access modes. This CANNOT be used to change
136 // a buffer's access mode; it is merely an informational value to allow Mojo
137 // to retain consistency between wrapping and unwrapping of buffer handles.
138 #define MOJO_PLATFORM_SHARED_MEMORY_REGION_ACCESS_MODE_WRITABLE \
139   ((MojoPlatformSharedMemoryRegionAccessMode)1)
140 
141 // The region is unsafe, meaning any number of read/writable handles may refer
142 // to it.
143 //
144 // WARNING: See notes in |MojoWrapPlatformSharedMemoryRegion()| about the
145 // meaning and usage of different access modes. This CANNOT be used to change
146 // a buffer's access mode; it is merely an informational value to allow Mojo
147 // to retain consistency between wrapping and unwrapping of buffer handles.
148 #define MOJO_PLATFORM_SHARED_MEMORY_REGION_ACCESS_MODE_UNSAFE \
149   ((MojoPlatformSharedMemoryRegionAccessMode)2)
150 
151 // Flags passed to |MojoWrapPlatformSharedMemoryRegion()| via
152 // |MojoWrapPlatformSharedMemoryRegionOptions|.
153 typedef uint32_t MojoWrapPlatformSharedMemoryRegionFlags;
154 
155 // No flags. Default behavior.
156 #define MOJO_WRAP_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE \
157   ((MojoWrapPlatformSharedMemoryRegionFlags)0)
158 
159 // Options passed to |MojoWrapPlatformSharedMemoryRegion()|.
160 struct MOJO_ALIGNAS(8) MojoWrapPlatformSharedMemoryRegionOptions {
161   // The size of this structure, used for versioning.
162   uint32_t struct_size;
163 
164   // See |MojoWrapPlatformSharedMemoryRegionFlags|.
165   MojoWrapPlatformSharedMemoryRegionFlags flags;
166 };
167 MOJO_STATIC_ASSERT(sizeof(MojoWrapPlatformSharedMemoryRegionOptions) == 8,
168                    "MojoWrapPlatformSharedMemoryRegionOptions has wrong size");
169 
170 // Flags passed to |MojoUnwrapPlatformSharedMemoryRegion()| via
171 // |MojoUnwrapPlatformSharedMemoryRegionOptions|.
172 typedef uint32_t MojoUnwrapPlatformSharedMemoryRegionFlags;
173 
174 // No flags. Default behavior.
175 #define MOJO_UNWRAP_PLATFORM_SHARED_BUFFER_HANDLE_FLAG_NONE \
176   ((MojoUnwrapPlatformSharedMemoryRegionFlags)0)
177 
178 // Options passed to |MojoUnwrapPlatformSharedMemoryRegion()|.
179 struct MOJO_ALIGNAS(8) MojoUnwrapPlatformSharedMemoryRegionOptions {
180   // The size of this structure, used for versioning.
181   uint32_t struct_size;
182 
183   // See |MojoUnwrapPlatformSharedMemoryRegionFlags|.
184   MojoUnwrapPlatformSharedMemoryRegionFlags flags;
185 };
186 MOJO_STATIC_ASSERT(
187     sizeof(MojoUnwrapPlatformSharedMemoryRegionOptions) == 8,
188     "MojoUnwrapPlatformSharedMemoryRegionOptions has wrong size");
189 
190 // Wraps a native platform handle as a Mojo handle which can be transferred
191 // over a message pipe. Takes ownership of the underlying native platform
192 // object. i.e. if you wrap a POSIX file descriptor or Windows HANDLE and then
193 // call |MojoClose()| on the resulting MojoHandle, the underlying file
194 // descriptor or HANDLE will be closed.
195 //
196 // |platform_handle|: The platform handle to wrap.
197 //
198 // |options| may be null.
199 //
200 // Returns:
201 //     |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case
202 //         |*mojo_handle| contains the Mojo handle of the wrapped object.
203 //     |MOJO_RESULT_RESOURCE_EXHAUSTED| if the system is out of handles.
204 //     |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid
205 //          platform handle.
206 //
207 // NOTE: It is not always possible to detect if |platform_handle| is valid,
208 // particularly when |platform_handle->type| is valid but
209 // |platform_handle->value| does not represent a valid platform object.
210 MOJO_SYSTEM_EXPORT MojoResult
211 MojoWrapPlatformHandle(const struct MojoPlatformHandle* platform_handle,
212                        const struct MojoWrapPlatformHandleOptions* options,
213                        MojoHandle* mojo_handle);
214 
215 // Unwraps a native platform handle from a Mojo handle. If this call succeeds,
216 // ownership of the underlying platform object is assumed by the caller. The
217 // The Mojo handle is always closed regardless of success or failure.
218 //
219 // |mojo_handle|: The Mojo handle from which to unwrap the native platform
220 //     handle.
221 //
222 // |options| may be null.
223 //
224 // Returns:
225 //     |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case
226 //         |*platform_handle| contains the unwrapped platform handle.
227 //     |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| was not a valid Mojo
228 //         handle wrapping a platform handle.
229 MOJO_SYSTEM_EXPORT MojoResult
230 MojoUnwrapPlatformHandle(MojoHandle mojo_handle,
231                          const struct MojoUnwrapPlatformHandleOptions* options,
232                          struct MojoPlatformHandle* platform_handle);
233 
234 // Wraps a native platform shared memory region with a Mojo shared buffer handle
235 // which can be used exactly like a shared buffer handle created by
236 // |MojoCreateSharedBuffer()| or |MojoDuplicateBufferHandle()|.
237 //
238 // Takes ownership of the native platform shared buffer handle(s).
239 //
240 // |platform_handles|: The platform handle(s) to wrap. Must be one or more
241 //     native handles representing a shared memory region. On POSIX systems
242 //     with |access_mode| set to
243 //     |MOJO_PLATFORM_SHARED_MEMORY_REGION_ACCESS_MODE_WRITABLE| this must have
244 //     two handles, with the second one being a handle opened for read-only
245 //     mapping. For all other platforms and all other access modes, there should
246 //     be only one handle.
247 // |num_platform_handles|: The number of platform handles given in
248 //     |platform_handles|. See note above.
249 // |num_bytes|: The size of the shared memory region in bytes.
250 // |access_mode|: The current access mode of the shared memory region.
251 // |options|: Options to control behavior. May be null.
252 //
253 // !!WARNING!!: |access_mode| DOES NOT CONTROL ACCESS TO THE REGION. It is an
254 // informational field used by Mojo to ensure end-to-end consistency when
255 // wrapping and unwrapping region handles. The caller is responsible for
256 // ensuring that wrapped handles are already subject to the access constraints
257 // conveyed by |access_mode|.
258 //
259 // Returns:
260 //     |MOJO_RESULT_OK| if the handle was successfully wrapped. In this case
261 //         |*mojo_handle| contains a Mojo shared buffer handle.
262 //     |MOJO_RESULT_INVALID_ARGUMENT| if |platform_handle| was not a valid
263 //         platform shared buffer handle.
264 MOJO_SYSTEM_EXPORT MojoResult MojoWrapPlatformSharedMemoryRegion(
265     const struct MojoPlatformHandle* platform_handles,
266     uint32_t num_platform_handles,
267     uint64_t num_bytes,
268     const struct MojoSharedBufferGuid* guid,
269     MojoPlatformSharedMemoryRegionAccessMode access_mode,
270     const struct MojoWrapPlatformSharedMemoryRegionOptions* options,
271     MojoHandle* mojo_handle);
272 
273 // Unwraps a native platform shared memory region from a Mojo shared buffer
274 // handle. If this call succeeds, ownership of the underlying shared buffer
275 // object is assumed by the caller.
276 //
277 // The Mojo handle is always closed regardless of success or failure.
278 //
279 // |mojo_handle|: The Mojo shared buffer handle to unwrap.
280 //
281 // On input, |*num_platform_handles| must be non-zero, and |platform_handles|
282 // should point to enough memory to hold at least that many |MojoPlatformHandle|
283 // values. Each element in |platform_handles| must have also initialized
284 // |struct_size| to the caller's known |sizeof(MojoPlatformHandle)|.
285 //
286 // |platform_handles|, |num_platform_handles|, |num_bytes| and |access_mode| are
287 // all used to receive output values and MUST always be non-null.
288 //
289 // |options| may be null.
290 //
291 // NOTE: On POSIX systems when unwrapping regions with the
292 // |MOJO_PLATFORM_SHARED_MEMORY_REGION_ACCESS_MODE_WRITABLE| access mode,
293 // this will always unwrap two platform handles, with the first one being a
294 // POSIX file descriptor which can be mapped to writable memory, and the second
295 // one being a POSIX file descriptor which can only be mapped read-only. For all
296 // other access modes and all other platforms, this always unwraps to a single
297 // platform handle.
298 //
299 // Returns:
300 //    |MOJO_RESULT_OK| if the handle was successfully unwrapped. In this case
301 //        |*platform_handles| contains one or more platform handles to represent
302 //        the unwrapped region, |*num_platform_handles| contains the number of
303 //        platform handles actually stored in |platform_handles| on output,
304 //        |*num_bytes| contains the size of the shared buffer object, and
305 //        |*access_mode| indicates the access mode of the region.
306 //    |MOJO_RESULT_INVALID_ARGUMENT| if |mojo_handle| is not a valid Mojo
307 //        shared buffer handle or |*num_platform_handles| is not large enough
308 //        to hold all the handles that would have been unwrapped on success.
309 MOJO_SYSTEM_EXPORT MojoResult MojoUnwrapPlatformSharedMemoryRegion(
310     MojoHandle mojo_handle,
311     const struct MojoUnwrapPlatformSharedMemoryRegionOptions* options,
312     struct MojoPlatformHandle* platform_handles,
313     uint32_t* num_platform_handles,
314     uint64_t* num_bytes,
315     struct MojoSharedBufferGuid* guid,
316     MojoPlatformSharedMemoryRegionAccessMode* access_mode);
317 
318 #ifdef __cplusplus
319 }  // extern "C"
320 #endif
321 
322 #endif  // MOJO_PUBLIC_C_SYSTEM_PLATFORM_HANDLE_H_
323