1 // Copyright 2019 The Fuchsia 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 #ifndef LIB_MAGMA_CLIENT_INCLUDE_LIB_MAGMA_MAGMA_SYSMEM_H_ 6 #define LIB_MAGMA_CLIENT_INCLUDE_LIB_MAGMA_MAGMA_SYSMEM_H_ 7 8 #include <lib/magma/magma_common_defs.h> 9 #include <stdint.h> 10 11 #if defined(__cplusplus) 12 extern "C" { 13 #endif 14 15 // This header is C, so clang-tidy shouldn't recommend using C++ features. 16 // NOLINTBEGIN(modernize-use-using) 17 18 // LINT.IfChange 19 20 // An opaque handle that corresponds to a fuchsia.sysmem.BufferCollection. 21 typedef uint64_t magma_buffer_collection_t; 22 23 // An opaque handle that corresponds to a set of constraints on a sysmem buffer collection (similar 24 // to a fuchsia.sysmem.BufferCollectionConstraints). Each set of constraints has multiple "format 25 // slots", and sysmem can use any one of those slots to determine the image format. If no format 26 // slots are set, the buffer collection may only be used as an opaque buffer. 27 typedef uint64_t magma_sysmem_buffer_constraints_t; 28 29 // An opaque handle that corresponds to a description of the format of an allocated buffer 30 // collection. Various attributes of the description can be queried and used to determine the pixel 31 // layout of the image. This corresponds most closely to a fuchsia.sysmem.BufferCollectionInfo_2. 32 typedef uint64_t magma_collection_info_t; 33 34 typedef struct magma_image_plane { 35 uint32_t bytes_per_row; 36 uint32_t byte_offset; 37 } magma_image_plane_t; 38 39 // A basic set of constraints on an image format. Corresponds to 40 // `fuchsia.sysmem.ImageFormatConstraints`. 41 typedef struct magma_image_format_constraints { 42 uint32_t image_format; 43 magma_bool_t has_format_modifier; 44 uint64_t format_modifier; 45 uint32_t width; 46 uint32_t height; 47 uint32_t layers; 48 uint32_t bytes_per_row_divisor; 49 uint32_t min_bytes_per_row; 50 } magma_image_format_constraints_t; 51 52 // Signals what struct members are valid on `magma_buffer_format_constraints_t`. 53 typedef uint32_t magma_buffer_format_constraint_options_t; 54 55 #define MAGMA_BUFFER_FORMAT_CONSTRAINT_OPTIONS_EXTRA_COUNTS \ 56 ((magma_buffer_format_constraint_options_t)(1 << 0)) 57 58 // A set of constraints on a buffer collection; corresponds to some properties of 59 // `fuchsia.sysmem.BufferCollectionConstraints`. 60 typedef struct magma_buffer_format_constraints { 61 // min_buffer_count 62 // Always enabled. 63 struct { 64 uint32_t count; 65 uint32_t usage; 66 magma_bool_t secure_permitted; 67 magma_bool_t secure_required; 68 magma_bool_t ram_domain_supported; 69 magma_bool_t cpu_domain_supported; 70 uint32_t min_size_bytes; 71 }; 72 magma_buffer_format_constraint_options_t options; 73 // Enabled with MAGMA_BUFFER_FORMAT_CONSTRAINT_OPTIONS_EXTRA_COUNTS set. 74 struct { 75 uint32_t max_buffer_count; 76 uint32_t min_buffer_count_for_camping; 77 uint32_t min_buffer_count_for_dedicated_slack; 78 uint32_t min_buffer_count_for_shared_slack; 79 }; 80 } magma_buffer_format_constraints_t; 81 82 typedef struct magma_buffer_format_additional_constraints { 83 uint32_t max_buffer_count; 84 uint32_t min_buffer_count_for_camping; 85 uint32_t min_buffer_count_for_dedicated_slack; 86 uint32_t min_buffer_count_for_shared_slack; 87 } magma_buffer_format_additional_constraints_t; 88 89 /// 90 /// \brief Import and take ownership of a sysmem connection 91 /// \param handle A channel connected to `fuchsia.sysmem.Allocator`. 92 /// \param connection_out The returned sysmem connection 93 /// 94 MAGMA_EXPORT magma_status_t 95 magma_sysmem_connection_import(magma_handle_t handle, magma_sysmem_connection_t* connection_out); 96 97 /// 98 /// \brief Release a connection to the sysmem service. Allocated buffers are allowed to outlive the 99 /// connection. 100 /// \param connection The connection to release. 101 /// 102 MAGMA_EXPORT void magma_sysmem_connection_release(magma_sysmem_connection_t connection); 103 104 /// 105 /// \brief Allocate a sysmem buffer with a specific size. This buffer doesn't have a sysmem token 106 /// and should only be used internally by the driver. 107 /// \param connection The connection to allocate it on. 108 /// \param flags A set of `MAGMA_SYSMEM_FLAG_` flags to use when allocating the buffer. 109 /// \param size The size of the buffer in bytes. 110 /// \param buffer_handle_out The returned buffer handle 111 /// 112 MAGMA_EXPORT magma_status_t 113 magma_sysmem_connection_allocate_buffer(magma_sysmem_connection_t connection, uint32_t flags, 114 uint64_t size, magma_handle_t* buffer_handle_out); 115 116 /// 117 /// \brief Release a magma_collection_info_t object. 118 /// \param description The object to release 119 /// 120 MAGMA_EXPORT void magma_collection_info_release(magma_collection_info_t collection_info); 121 122 /// 123 /// \brief Get information about the memory layout of all image planes of an image, given a set of 124 /// image dimensions. 125 /// \param description The description to retrieve information about. 126 /// \param width width of the image to retrieve layout information about 127 /// \param height height of the image to retrieve layout information about 128 /// \param image_planes_out An array with MAGMA_MAX_IMAGE_PLANES elements that will receive 129 /// information on all planes. 130 /// 131 MAGMA_EXPORT magma_status_t magma_collection_info_get_plane_info_with_size( 132 magma_collection_info_t collection_info, uint32_t width, uint32_t height, 133 magma_image_plane_t* image_planes_out); 134 135 /// 136 /// \brief Get the MAGMA_FORMAT_* value for a buffer description. 137 /// \param description The description to retrieve information about. 138 /// \param format_out Receives a `MAGMA_FORMAT_*` value describing the image. May receive 139 /// MAGMA_FORMAT_INVALID if the buffer isn't an image. 140 /// 141 MAGMA_EXPORT magma_status_t 142 magma_collection_info_get_format(magma_collection_info_t collection_info, uint32_t* format_out); 143 144 /// 145 /// \brief Get a sysmem buffer format modifier for an image description. 146 /// \param description The description to retrieve information about. 147 /// \param has_format_modifier_out Receives whether the description has a format modifier. 148 /// \param format_modifier_out Receives the sysmem format modifier value. 149 /// 150 MAGMA_EXPORT magma_status_t magma_collection_info_get_format_modifier( 151 magma_collection_info_t collection_info, magma_bool_t* has_format_modifier_out, 152 uint64_t* format_modifier_out); 153 154 /// 155 /// \brief Get the first allowable sysmem color space for a buffer. 156 /// \param description The description to retrieve information about. 157 /// \param color_space_out Receives the color space 158 /// 159 MAGMA_EXPORT magma_status_t magma_collection_info_get_color_space( 160 magma_collection_info_t collection_info, uint32_t* color_space_out); 161 162 /// 163 /// \brief Gets the buffer coherency domain for a description. 164 /// \param description The description to retrieve information about. 165 /// \param coherency_domain_out receives a `MAGMA_COHERENCY_DOMAIN_*` value. 166 /// 167 MAGMA_EXPORT magma_status_t magma_collection_info_get_coherency_domain( 168 magma_collection_info_t collection_info, uint32_t* coherency_domain_out); 169 170 /// 171 /// \brief Get the number of buffers allocated in a buffer collection. 172 /// \param description The description to retrieve information about. 173 /// \param count_out receives the buffer count. This corresponds to 174 /// `fuchsia.sysmem.BufferCollectionInfo_2.buffer_count`. 175 /// 176 MAGMA_EXPORT magma_status_t magma_collection_info_get_buffer_count( 177 magma_collection_info_t collection_info, uint32_t* count_out); 178 179 /// 180 /// \brief Gets the value of fuchsia.sysmem.BufferMemorySettings.is_secure is for the buffers in the 181 /// collection. 182 /// \param description The description to retrieve information about. 183 /// \param is_secure_out Receives the value. 184 /// 185 MAGMA_EXPORT magma_status_t magma_collection_info_get_is_secure( 186 magma_collection_info_t collection_info, magma_bool_t* is_secure_out); 187 188 /// 189 /// \brief Import a magma buffer collection. 190 /// \param connection The connection to import into. 191 /// \param handle a `fuchsia.symsmem.BufferCollectionToken` handle to import from. If 192 /// ZX_HANDLE_INVALID (0), then a new buffer collection is created. 193 /// \param collection_out Receives the collection 194 /// 195 MAGMA_EXPORT magma_status_t magma_sysmem_connection_import_buffer_collection( 196 magma_sysmem_connection_t connection, magma_handle_t handle, 197 magma_buffer_collection_t* collection_out); 198 199 /// 200 /// \brief Release a magma buffer collection. 201 /// \param collection The Collection to release. 202 /// 203 MAGMA_EXPORT void magma_buffer_collection_release2(magma_buffer_collection_t collection); 204 205 /// 206 /// \brief Create a set of buffer constraints. These constraints can be modified with additional 207 /// requirements, then set on a buffer collection. The buffer constraints must be freed using 208 /// `magma_buffer_constraints_release`. 209 /// \param connection The connection to create constraints on. 210 /// \param buffer_constraints A struct describing overall constraints of every image format. 211 /// \param constraints_out receives the allocated buffer constraints. 212 /// 213 MAGMA_EXPORT magma_status_t magma_sysmem_connection_create_buffer_constraints( 214 magma_sysmem_connection_t connection, 215 const magma_buffer_format_constraints_t* buffer_constraints, 216 magma_sysmem_buffer_constraints_t* constraints_out); 217 218 /// 219 /// \brief Set information about a format slot on the constraints. The sysmem driver will choose one 220 /// format slot to use when creating the image. May not be called after 221 /// `magma_buffer_collection_set_constraints` using these constraints. 222 /// \param connection The connection for the constraints. 223 /// \param constraints Constraints to modify. 224 /// \param index The format slot index to set. A format slot index may only be set once. 225 /// \param format_constraints constraints on the image format. 226 /// 227 MAGMA_EXPORT magma_status_t 228 magma_buffer_constraints_set_format2(magma_sysmem_buffer_constraints_t constraints, uint32_t index, 229 const magma_image_format_constraints_t* format_constraints); 230 231 /// 232 /// \brief Sets the list of allowable color spaces for an image format slot. 233 /// May not be called after `magma_buffer_collection_set_constraints` using these 234 /// constraints. 235 /// \param constraints Constraints to modify. 236 /// \param index the format slot index to set colorspace constraints on. 237 /// `magma_buffer_constraints_set_format` must have been set on this index. 238 /// \param color_space_count Number of elements in the color_spaces array. 239 /// \param color_spaces array of color spaces. Must be elements of `fuchsia.sysmem.ColorSpaceType` 240 /// 241 MAGMA_EXPORT magma_status_t magma_buffer_constraints_set_colorspaces2( 242 magma_sysmem_buffer_constraints_t constraints, uint32_t index, uint32_t color_space_count, 243 const uint32_t* color_spaces); 244 245 /// 246 /// \brief Release a `magma_sysmem_buffer_constraints_t`. 247 /// \param constraints The constraints to release. 248 MAGMA_EXPORT void magma_buffer_constraints_release2(magma_sysmem_buffer_constraints_t constraints); 249 250 /// 251 /// \brief Set format constraints for a buffer collection. This call may trigger sysmem to allocate 252 /// the collection if all constraints are set. 253 /// \param collection The collection to use 254 /// \param constraints Constraints to use 255 /// 256 MAGMA_EXPORT magma_status_t magma_buffer_collection_set_constraints2( 257 magma_buffer_collection_t collection, magma_sysmem_buffer_constraints_t constraints); 258 259 /// 260 /// \brief Creates a buffer format description to describe a collection of allocated buffers. This 261 /// call will wait until the initial buffers in the collection are allocated. 262 /// \param collection The collection 263 /// \param collection_info_out receives the buffer format description. On success must 264 /// later be released using magma_buffer_format_description_release. 265 /// 266 MAGMA_EXPORT magma_status_t magma_buffer_collection_get_collection_info( 267 magma_buffer_collection_t collection, magma_collection_info_t* collection_info_out); 268 269 /// 270 /// \brief Retrieves a handle to a VMO to retrieve from a buffer collection. This call will wait 271 /// until the initial buffers in the collection are allocated. 272 /// \param collection A collection to retrieve the handle from 273 /// \param index the index of the handle to retrieve. Must be < the value of 274 /// `magma_get_buffer_count` 275 /// \param buffer_handle_out receives a VMO handle for the collection. May be used with 276 /// `magma_import`. On success, the caller takes ownership. 277 /// \param vmo_offset Receives the byte offset into the VMO where the buffer starts. 278 /// 279 MAGMA_EXPORT magma_status_t magma_buffer_collection_get_buffer_handle( 280 magma_buffer_collection_t collection, uint32_t index, magma_handle_t* buffer_handle_out, 281 uint32_t* vmo_offset_out); 282 283 /// 284 /// \brief Determines which constraint format slot indices match the buffer description. 285 /// \param description The description to retrieve information about. 286 /// \param constraints The constraints originally used to allocate the collection that `description` 287 /// was retrieved from. 288 /// \param format_valid_out An array of elements; `format_valid_out[i]` is set to true if the format 289 /// slot index i in the constraints match the format description. Multiple format slots may 290 /// map to a single format in sysmem, which is why this call may set multiple formats as 291 /// valid. 292 /// \param format_valid_count The number of entires in `format_valid_out`. Must be > the maximum 293 /// format slot index used when creating the constraints. 294 /// 295 MAGMA_EXPORT magma_status_t magma_collection_info_get_format_index( 296 magma_collection_info_t collection_info, magma_sysmem_buffer_constraints_t constraints, 297 magma_bool_t* format_valid_out, uint32_t format_valid_count); 298 299 // LINT.ThenChange(magma_common_defs.h:version) 300 301 // NOLINTEND(modernize-use-using) 302 303 #if defined(__cplusplus) 304 } 305 #endif 306 307 #endif // LIB_MAGMA_CLIENT_INCLUDE_LIB_MAGMA_MAGMA_SYSMEM_H_ 308