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