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