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 shared buffers. 6 // 7 // Note: This header should be compilable as C. 8 9 #ifndef MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ 10 #define MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ 11 12 #include <stdint.h> 13 14 #include "mojo/public/c/system/macros.h" 15 #include "mojo/public/c/system/system_export.h" 16 #include "mojo/public/c/system/types.h" 17 18 // Flags passed to |MojoCreateSharedBuffer()| via 19 // |MojoCreateSharedBufferOptions|. See values defined below. 20 typedef uint32_t MojoCreateSharedBufferFlags; 21 22 // No flags. Default behavior. 23 #define MOJO_CREATE_SHARED_BUFFER_FLAG_NONE ((uint32_t)0) 24 25 // Options passed to |MojoCreateSharedBuffer()|. 26 struct MOJO_ALIGNAS(8) MojoCreateSharedBufferOptions { 27 // The size of this structure, used for versioning. 28 uint32_t struct_size; 29 30 // See |MojoCreateSharedBufferFlags|. 31 MojoCreateSharedBufferFlags flags; 32 }; 33 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int64_t) <= 8, "int64_t has weird alignment"); 34 MOJO_STATIC_ASSERT(sizeof(MojoCreateSharedBufferOptions) == 8, 35 "MojoCreateSharedBufferOptions has wrong size"); 36 37 // Flags passed to |MojoGetBufferInfo()| via |MojoGetBufferInfoOptions|. See 38 // values defined below. 39 typedef uint32_t MojoGetBufferInfoFlags; 40 41 // No flags. Default behavior. 42 #define MOJO_GET_BUFFER_INFO_FLAG_NONE ((uint32_t)0) 43 44 // Options passed to |MojoGetBufferInfo()|. 45 struct MOJO_ALIGNAS(8) MojoGetBufferInfoOptions { 46 // The size of this structure, used for versioning. 47 uint32_t struct_size; 48 49 // See |MojoGetBufferInfoFlags|. 50 MojoGetBufferInfoFlags flags; 51 }; 52 MOJO_STATIC_ASSERT(sizeof(MojoGetBufferInfoOptions) == 8, 53 "MojoSharedBufferOptions has wrong size"); 54 55 // Structure used to receive information about a shared buffer via 56 // |MojoGetBufferInfo()|. 57 struct MOJO_ALIGNAS(8) MojoSharedBufferInfo { 58 // The size of this structure, used for versioning. 59 uint32_t struct_size; 60 61 // The size of the shared buffer. 62 uint64_t size; 63 }; 64 MOJO_STATIC_ASSERT(sizeof(MojoSharedBufferInfo) == 16, 65 "MojoSharedBufferInfo has wrong size"); 66 67 // Flags passed to |MojoDuplicateBufferHandle()| via 68 // |MojoDuplicateBufferHandleOptions|. See values defined below. 69 typedef uint32_t MojoDuplicateBufferHandleFlags; 70 71 // No options. Default behavior. Note that if a shared buffer handle is ever 72 // duplicated without |MOJO_DUPLICATE_BUFFER_HANDLE_READ_ONLY| (see below), 73 // neither it nor any of its duplicates can ever be duplicated *with* 74 // |MOJO_DUPLICATE_BUFFER_HANDLE_READ_ONLY| in the future. That is, once a 75 // writable handle has been duplicated as another writable handle, it is no 76 // longer possible to create read-only handles to the underlying buffer object. 77 #define MOJO_DUPLICATE_BUFFER_HANDLE_FLAG_NONE ((uint32_t)0) 78 79 // Duplicates the handle as read-only. If successful, the resulting new handle 80 // will always map to a read-only memory region. Successful use of this flag 81 // also imposes the limitation that the handle or any of its subsequent 82 // duplicates may never be duplicated *without* this flag in the future. That 83 // is, once a read-only handle is produced for a buffer object, all future 84 // handles to that object must also be read-only. 85 #define MOJO_DUPLICATE_BUFFER_HANDLE_FLAG_READ_ONLY ((uint32_t)1 << 0) 86 87 // Options passed to |MojoDuplicateBufferHandle()|. 88 struct MojoDuplicateBufferHandleOptions { 89 // The size of this structure, used for versioning. 90 uint32_t struct_size; 91 92 // See |MojoDuplicateBufferHandleFlags|. 93 MojoDuplicateBufferHandleFlags flags; 94 }; 95 MOJO_STATIC_ASSERT(sizeof(MojoDuplicateBufferHandleOptions) == 8, 96 "MojoDuplicateBufferHandleOptions has wrong size"); 97 98 // Flags passed to |MojoMapBuffer()| via |MojoMapBufferOptions|. See values 99 // defined below. 100 typedef uint32_t MojoMapBufferFlags; 101 102 // No flags. Default behavior. 103 #define MOJO_MAP_BUFFER_FLAG_NONE ((uint32_t)0) 104 105 // Options passed to |MojoMapBuffer()|. 106 struct MojoMapBufferOptions { 107 // The size of this structure, used for versioning. 108 uint32_t struct_size; 109 110 // See |MojoMapBufferFlags|. 111 MojoMapBufferFlags flags; 112 }; 113 MOJO_STATIC_ASSERT(sizeof(MojoMapBufferOptions) == 8, 114 "MojoMapBufferOptions has wrong size"); 115 116 #ifdef __cplusplus 117 extern "C" { 118 #endif 119 120 // Creates a buffer of size |num_bytes| bytes that can be shared between 121 // processes. The returned handle may be duplicated any number of times by 122 // |MojoDuplicateBufferHandle()|. 123 // 124 // To access the buffer's storage, one must call |MojoMapBuffer()|. 125 // 126 // |options| may be set to null for a shared buffer with the default options. 127 // 128 // On success, |*shared_buffer_handle| will be set to the handle for the shared 129 // buffer. On failure it is not modified. 130 // 131 // Returns: 132 // |MOJO_RESULT_OK| on success. 133 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 134 // |*options| is invalid). 135 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has 136 // been reached (e.g., if the requested size was too large, or if the 137 // maximum number of handles was exceeded). 138 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. 139 MOJO_SYSTEM_EXPORT MojoResult 140 MojoCreateSharedBuffer(uint64_t num_bytes, 141 const struct MojoCreateSharedBufferOptions* options, 142 MojoHandle* shared_buffer_handle); 143 144 // Duplicates the handle |buffer_handle| as a new shared buffer handle. On 145 // success this returns the new handle in |*new_buffer_handle|. A shared buffer 146 // remains allocated as long as there is at least one shared buffer handle 147 // referencing it in at least one process in the system. 148 // 149 // |options| may be set to null to duplicate the buffer handle with the default 150 // options. 151 // 152 // Access rights to mapped memory from the duplicated handle may be controlled 153 // by flags in |*options|, with some limitations. See notes on 154 // |MOJO_DUPLICATE_BUFFER_HANDLE_FLAG_NONE| and 155 // |MOJO_DUPLICATE_BUFFER_HANDLE_FLAG_READ_ONLY| regarding restrictions on 156 // duplication with respect to these flags. 157 // 158 // Returns: 159 // |MOJO_RESULT_OK| on success. 160 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 161 // |buffer_handle| is not a valid buffer handle or |*options| is invalid). 162 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. 163 // |MOJO_RESULT_FAILED_PRECONDITION| if 164 // |MOJO_DUPLICATE_BUFFER_HANDLE_FLAG_READ_ONLY| was set but the handle 165 // was already previously duplicated without that flag; or if 166 // |MOJO_DUPLICATE_BUFFER_HANDLE_FLAG_READ_ONLY| was not set but the 167 // handle was already previously duplicated with that flag. 168 MOJO_SYSTEM_EXPORT MojoResult MojoDuplicateBufferHandle( 169 MojoHandle buffer_handle, 170 const struct MojoDuplicateBufferHandleOptions* options, 171 MojoHandle* new_buffer_handle); 172 173 // Maps the part (at offset |offset| of length |num_bytes|) of the buffer given 174 // by |buffer_handle| into memory, with options specified by |options|. 175 // |offset+num_bytes| must be less than or equal to the size of the buffer. On 176 // success, |*buffer| points to memory with the requested part of the buffer. On 177 // failure |*buffer| it is not modified. 178 // 179 // A single buffer handle may have multiple active mappings. The permissions 180 // (e.g., writable or executable) of the returned memory depend on the 181 // properties of the buffer and properties attached to the buffer handle, as 182 // well as |flags|. 183 // 184 // A mapped buffer must eventually be unmapped by calling |MojoUnmapBuffer()| 185 // with the value of |*buffer| returned by this function. 186 // 187 // |options| may be null to map the buffer with default behavior. 188 // 189 // Returns: 190 // |MOJO_RESULT_OK| on success. 191 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 192 // |buffer_handle| is not a valid buffer handle, the range specified by 193 // |offset| and |num_bytes| is not valid, or |*options| is invalid). 194 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the mapping operation itself failed 195 // (e.g., due to not having appropriate address space available). 196 MOJO_SYSTEM_EXPORT MojoResult 197 MojoMapBuffer(MojoHandle buffer_handle, 198 uint64_t offset, 199 uint64_t num_bytes, 200 const struct MojoMapBufferOptions* options, 201 void** buffer); 202 203 // Unmaps a buffer pointer that was mapped by |MojoMapBuffer()|. |buffer| must 204 // have been the result of |MojoMapBuffer()| (not some other pointer inside 205 // the mapped memory), and the entire mapping will be removed. 206 // 207 // A mapping may only be unmapped once. 208 // 209 // Returns: 210 // |MOJO_RESULT_OK| on success. 211 // |MOJO_RESULT_INVALID_ARGUMENT| if |buffer| is invalid (e.g., is not the 212 // result of |MojoMapBuffer()| or has already been unmapped). 213 MOJO_SYSTEM_EXPORT MojoResult MojoUnmapBuffer(void* buffer); 214 215 // Retrieve information about |buffer_handle| into |info|. 216 // 217 // Callers must initialize |info->struct_size| to |sizeof(MojoSharedBufferInfo)| 218 // before calling this function. 219 // 220 // |options| may be null for default options. 221 // 222 // Returns: 223 // |MOJO_RESULT_OK| on success. 224 // |MOJO_RESULT_INVALID_ARGUMENT| if |buffer_handle| is invalid, |info| is 225 // null, or |*options| is invalid. 226 // 227 // On success, |info->size| will be set to the size of the buffer. On failure it 228 // is not modified. 229 MOJO_SYSTEM_EXPORT MojoResult 230 MojoGetBufferInfo(MojoHandle buffer_handle, 231 const struct MojoGetBufferInfoOptions* options, 232 struct MojoSharedBufferInfo* info); 233 234 #ifdef __cplusplus 235 } // extern "C" 236 #endif 237 238 #endif // MOJO_PUBLIC_C_SYSTEM_BUFFER_H_ 239