1 // Copyright 2014 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/constants and functions specific to buffers (and in 6 // particular shared buffers). 7 // TODO(vtl): Reorganize this file (etc.) to separate general buffer functions 8 // from (shared) buffer creation. 9 // 10 // Note: This header should be compilable as C. 11 12 #ifndef MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ 13 #define MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ 14 15 #include "mojo/public/c/system/macros.h" 16 #include "mojo/public/c/system/system_export.h" 17 #include "mojo/public/c/system/types.h" 18 19 // |MojoCreateSharedBufferOptions|: Used to specify creation parameters for a 20 // shared buffer to |MojoCreateSharedBuffer()|. 21 // |uint32_t struct_size|: Set to the size of the 22 // |MojoCreateSharedBufferOptions| struct. (Used to allow for future 23 // extensions.) 24 // |MojoCreateSharedBufferOptionsFlags flags|: Reserved for future use. 25 // |MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE|: No flags; default mode. 26 // 27 // TODO(vtl): Maybe add a flag to indicate whether the memory should be 28 // executable or not? 29 // TODO(vtl): Also a flag for discardable (ashmem-style) buffers. 30 31 typedef uint32_t MojoCreateSharedBufferOptionsFlags; 32 33 #ifdef __cplusplus 34 const MojoCreateSharedBufferOptionsFlags 35 MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE = 0; 36 #else 37 #define MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE \ 38 ((MojoCreateSharedBufferOptionsFlags) 0) 39 #endif 40 41 MOJO_COMPILE_ASSERT(MOJO_ALIGNOF(int64_t) == 8, int64_t_has_weird_alignment); 42 struct MOJO_ALIGNAS(8) MojoCreateSharedBufferOptions { 43 uint32_t struct_size; 44 MojoCreateSharedBufferOptionsFlags flags; 45 }; 46 MOJO_COMPILE_ASSERT(sizeof(MojoCreateSharedBufferOptions) == 8, 47 MojoCreateSharedBufferOptions_has_wrong_size); 48 49 // |MojoDuplicateBufferHandleOptions|: Used to specify parameters in duplicating 50 // access to a shared buffer to |MojoDuplicateBufferHandle()|. 51 // |uint32_t struct_size|: Set to the size of the 52 // |MojoDuplicateBufferHandleOptions| struct. (Used to allow for future 53 // extensions.) 54 // |MojoDuplicateBufferHandleOptionsFlags flags|: Reserved for future use. 55 // |MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE|: No flags; default 56 // mode. 57 // 58 // TODO(vtl): Add flags to remove writability (and executability)? Also, COW? 59 60 typedef uint32_t MojoDuplicateBufferHandleOptionsFlags; 61 62 #ifdef __cplusplus 63 const MojoDuplicateBufferHandleOptionsFlags 64 MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE = 0; 65 #else 66 #define MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE \ 67 ((MojoDuplicateBufferHandleOptionsFlags) 0) 68 #endif 69 70 struct MojoDuplicateBufferHandleOptions { 71 uint32_t struct_size; 72 MojoDuplicateBufferHandleOptionsFlags flags; 73 }; 74 MOJO_COMPILE_ASSERT(sizeof(MojoDuplicateBufferHandleOptions) == 8, 75 MojoDuplicateBufferHandleOptions_has_wrong_size); 76 77 // |MojoMapBufferFlags|: Used to specify different modes to |MojoMapBuffer()|. 78 // |MOJO_MAP_BUFFER_FLAG_NONE| - No flags; default mode. 79 80 typedef uint32_t MojoMapBufferFlags; 81 82 #ifdef __cplusplus 83 const MojoMapBufferFlags MOJO_MAP_BUFFER_FLAG_NONE = 0; 84 #else 85 #define MOJO_MAP_BUFFER_FLAG_NONE ((MojoMapBufferFlags) 0) 86 #endif 87 88 #ifdef __cplusplus 89 extern "C" { 90 #endif 91 92 // Note: See the comment in functions.h about the meaning of the "optional" 93 // label for pointer parameters. 94 95 // Creates a buffer of size |num_bytes| bytes that can be shared between 96 // applications (by duplicating the handle -- see |MojoDuplicateBufferHandle()| 97 // -- and passing it over a message pipe). To access the buffer, one must call 98 // |MojoMapBuffer()|. 99 // 100 // |options| may be set to null for a shared buffer with the default options. 101 // 102 // On success, |*shared_buffer_handle| will be set to the handle for the shared 103 // buffer. (On failure, it is not modified.) 104 // 105 // Note: While more than |num_bytes| bytes may apparently be 106 // available/visible/readable/writable, trying to use those extra bytes is 107 // undefined behavior. 108 // 109 // Returns: 110 // |MOJO_RESULT_OK| on success. 111 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if 112 // |*options| is invalid or |shared_buffer_handle| looks invalid). 113 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has 114 // been reached (e.g., if the requested size was too large, or if the 115 // maximum number of handles was exceeded). 116 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. 117 MOJO_SYSTEM_EXPORT MojoResult MojoCreateSharedBuffer( 118 const struct MojoCreateSharedBufferOptions* options, // Optional. 119 uint64_t num_bytes, // In. 120 MojoHandle* shared_buffer_handle); // Out. 121 122 // Duplicates the handle |buffer_handle| to a buffer. This creates another 123 // handle (returned in |*new_buffer_handle| on success), which can then be sent 124 // to another application over a message pipe, while retaining access to the 125 // |buffer_handle| (and any mappings that it may have). 126 // 127 // |options| may be set to null to duplicate the buffer handle with the default 128 // options. 129 // 130 // On success, |*shared_buffer_handle| will be set to the handle for the new 131 // buffer handle. (On failure, it is not modified.) 132 // 133 // Returns: 134 // |MOJO_RESULT_OK| on success. 135 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if 136 // |buffer_handle| is not a valid buffer handle, |*options| is invalid, or 137 // |new_buffer_handle| looks invalid). 138 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. 139 MOJO_SYSTEM_EXPORT MojoResult MojoDuplicateBufferHandle( 140 MojoHandle buffer_handle, 141 const struct MojoDuplicateBufferHandleOptions* options, // Optional. 142 MojoHandle* new_buffer_handle); // Out. 143 144 // Maps the part (at offset |offset| of length |num_bytes|) of the buffer given 145 // by |buffer_handle| into memory, with options specified by |flags|. |offset + 146 // num_bytes| must be less than or equal to the size of the buffer. On success, 147 // |*buffer| points to memory with the requested part of the buffer. (On 148 // failure, it is not modified.) 149 // 150 // A single buffer handle may have multiple active mappings (possibly depending 151 // on the buffer type). The permissions (e.g., writable or executable) of the 152 // returned memory may depend on the properties of the buffer and properties 153 // attached to the buffer handle as well as |flags|. 154 // 155 // Note: Though data outside the specified range may apparently be 156 // available/visible/readable/writable, trying to use those extra bytes is 157 // undefined behavior. 158 // 159 // Returns: 160 // |MOJO_RESULT_OK| on success. 161 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if 162 // |buffer_handle| is not a valid buffer handle, the range specified by 163 // |offset| and |num_bytes| is not valid, or |buffer| looks invalid). 164 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the mapping operation itself failed 165 // (e.g., due to not having appropriate address space available). 166 MOJO_SYSTEM_EXPORT MojoResult MojoMapBuffer(MojoHandle buffer_handle, 167 uint64_t offset, 168 uint64_t num_bytes, 169 void** buffer, // Out. 170 MojoMapBufferFlags flags); 171 172 // Unmaps a buffer pointer that was mapped by |MojoMapBuffer()|. |buffer| must 173 // have been the result of |MojoMapBuffer()| (not some pointer strictly inside 174 // the mapped memory), and the entire mapping will be removed (partial unmapping 175 // is not supported). A mapping may only be unmapped exactly once. 176 // 177 // Returns: 178 // |MOJO_RESULT_OK| on success. 179 // |MOJO_RESULT_INVALID_ARGUMENT| if |buffer| is invalid (e.g., if it is not 180 // the result of |MojoMapBuffer()| or it has already been unmapped). 181 MOJO_SYSTEM_EXPORT MojoResult MojoUnmapBuffer(void* buffer); // In. 182 183 #ifdef __cplusplus 184 } // extern "C" 185 #endif 186 187 #endif // MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ 188