1 /* 2 * Copyright © 2011 Intel Corporation 3 * Copyright © 2021 NVIDIA Corporation 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a 6 * copy of this software and associated documentation files (the "Software"), 7 * to deal in the Software without restriction, including without limitation 8 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 9 * and/or sell copies of the Software, and to permit persons to whom the 10 * Software is furnished to do so, subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice (including the next 13 * paragraph) shall be included in all copies or substantial portions of the 14 * Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 19 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 20 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 21 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 23 * DEALINGS IN THE SOFTWARE. 24 * 25 * Authors: 26 * Benjamin Franzke <benjaminfranzke@googlemail.com> 27 * James Jones <jajones@nvidia.com> 28 */ 29 30 #ifndef GBM_BACKEND_ABI_H_ 31 #define GBM_BACKEND_ABI_H_ 32 33 #include "gbm.h" 34 35 /** 36 * \file gbm_backend_abi.h 37 * \brief ABI between the GBM loader and its backends 38 */ 39 40 struct gbm_backend_desc; 41 42 /** 43 * The GBM backend interface version defined by this file. 44 * 45 * The GBM device interface version must be incremented whenever the structures 46 * defined in this file are modified. To preserve ABI compatibility with 47 * backends that support only older versions, modifications to this file must 48 * consist only of appending new fields to the end of the structures defined in 49 * it, defining new structures, or declaring new exported functions or global 50 * variables. 51 * 52 * Note this version applies to ALL structures in this file, not just the core, 53 * backend, and device structures which contain it explicitly. Buffer objects, 54 * surfaces, and any other new structures introduced to this file are also part 55 * of the backend ABI. The ABI version of an instance of any object in this file 56 * is defined as the minimum of the version of the backend associated with the 57 * object instance and the loader's core object version. Hence, any new objects 58 * added to this file should contain either a reference to an existing object 59 * defined here, or an explicit version field. 60 * 61 * A few examples of object versions: 62 * 63 * Backend ABI version: 0 64 * Core ABI version: 3 65 * ABI version of a device created by the backend: 0 66 * 67 * Backend ABI version: 2 68 * Core ABI version: 1 69 * ABI version of a surface created by a device from the backend: 1 70 * 71 * Backend ABI version: 4 72 * Core ABI version: 4 73 * ABI version of a buffer object created by a device from the backend: 4 74 */ 75 #define GBM_BACKEND_ABI_VERSION 1 76 77 /** 78 * GBM device interface corresponding to GBM_BACKEND_ABI_VERSION = 0 79 * 80 * DO NOT MODIFY THIS STRUCT. Instead, introduce a gbm_bo_v1, increment 81 * GBM_BACKEND_ABI_VERSION, and append gbm_bo_v1 to gbm_bo. 82 */ 83 struct gbm_device_v0 { 84 const struct gbm_backend_desc *backend_desc; 85 86 /** 87 * The version of the GBM backend interface supported by this device and its 88 * child objects. This may be less than the maximum version supported by the 89 * GBM loader if the device was created by an older backend, or less than the 90 * maximum version supported by the backend if the device was created by an 91 * older loader. In other words, this will be: 92 * 93 * MIN(backend GBM interface version, loader GBM interface version) 94 * 95 * It is the backend's responsibility to assign this field the value passed 96 * in by the GBM loader to the backend's create_device function. The GBM 97 * loader will pre-clamp the value based on the loader version and the 98 * version reported by the backend in its gbm_backend_v0::backend_version 99 * field. It is the loader's responsibility to respect this version when 100 * directly accessing a device instance or any child objects instantiated by 101 * a device instance. 102 */ 103 uint32_t backend_version; 104 105 int fd; 106 const char *name; 107 108 void (*destroy)(struct gbm_device *gbm); 109 int (*is_format_supported)(struct gbm_device *gbm, 110 uint32_t format, 111 uint32_t usage); 112 int (*get_format_modifier_plane_count)(struct gbm_device *device, 113 uint32_t format, 114 uint64_t modifier); 115 116 /** 117 * Since version 1, usage is properly populated when modifiers are 118 * supplied. Version 0 always set usage to 0 in this case. 119 */ 120 struct gbm_bo *(*bo_create)(struct gbm_device *gbm, 121 uint32_t width, uint32_t height, 122 uint32_t format, 123 uint32_t usage, 124 const uint64_t *modifiers, 125 const unsigned int count); 126 struct gbm_bo *(*bo_import)(struct gbm_device *gbm, uint32_t type, 127 void *buffer, uint32_t usage); 128 void *(*bo_map)(struct gbm_bo *bo, 129 uint32_t x, uint32_t y, 130 uint32_t width, uint32_t height, 131 uint32_t flags, uint32_t *stride, 132 void **map_data); 133 void (*bo_unmap)(struct gbm_bo *bo, void *map_data); 134 int (*bo_write)(struct gbm_bo *bo, const void *buf, size_t data); 135 int (*bo_get_fd)(struct gbm_bo *bo); 136 int (*bo_get_planes)(struct gbm_bo *bo); 137 union gbm_bo_handle (*bo_get_handle)(struct gbm_bo *bo, int plane); 138 int (*bo_get_plane_fd)(struct gbm_bo *bo, int plane); 139 uint32_t (*bo_get_stride)(struct gbm_bo *bo, int plane); 140 uint32_t (*bo_get_offset)(struct gbm_bo *bo, int plane); 141 uint64_t (*bo_get_modifier)(struct gbm_bo *bo); 142 void (*bo_destroy)(struct gbm_bo *bo); 143 144 /** 145 * Since version 1, flags are properly populated when modifiers are 146 * supplied. Version 0 always set flags to 0 in this case. 147 */ 148 struct gbm_surface *(*surface_create)(struct gbm_device *gbm, 149 uint32_t width, uint32_t height, 150 uint32_t format, uint32_t flags, 151 const uint64_t *modifiers, 152 const unsigned count); 153 struct gbm_bo *(*surface_lock_front_buffer)(struct gbm_surface *surface); 154 void (*surface_release_buffer)(struct gbm_surface *surface, 155 struct gbm_bo *bo); 156 int (*surface_has_free_buffers)(struct gbm_surface *surface); 157 void (*surface_destroy)(struct gbm_surface *surface); 158 }; 159 160 /** 161 * The device used for the memory allocation. 162 * 163 * The members of this structure should be not accessed directly 164 * 165 * To modify this structure, introduce a new gbm_device_v<N> structure, add it 166 * to the end of this structure, and increment GBM_BACKEND_ABI_VERSION. 167 */ 168 struct gbm_device { 169 /* Hack to make a gbm_device detectable by its first element. */ 170 struct gbm_device *(*dummy)(int); 171 struct gbm_device_v0 v0; 172 }; 173 174 /** 175 * GBM buffer object interface corresponding to GBM_BACKEND_ABI_VERSION = 0 176 * 177 * DO NOT MODIFY THIS STRUCT. Instead, introduce a gbm_bo_v1, increment 178 * GBM_BACKEND_ABI_VERSION, and append gbm_bo_v1 to gbm_bo. 179 */ 180 struct gbm_bo_v0 { 181 uint32_t width; 182 uint32_t height; 183 uint32_t stride; 184 uint32_t format; 185 union gbm_bo_handle handle; 186 void *user_data; 187 void (*destroy_user_data)(struct gbm_bo *, void *); 188 }; 189 190 /** 191 * The allocated buffer object. 192 * 193 * The members in this structure should not be accessed directly. 194 * 195 * To modify this structure, introduce a new gbm_bo_v<N> structure, add it to 196 * the end of this structure, and increment GBM_BACKEND_ABI_VERSION. 197 */ 198 struct gbm_bo { 199 struct gbm_device *gbm; 200 struct gbm_bo_v0 v0; 201 }; 202 203 /** 204 * GBM surface interface corresponding to GBM_BACKEND_ABI_VERSION = 0 205 * 206 * DO NOT MODIFY THIS STRUCT. Instead, introduce a gbm_surface_v1, increment 207 * GBM_BACKEND_ABI_VERSION, and append gbm_surface_v1 to gbm_surface. 208 */ 209 struct gbm_surface_v0 { 210 uint32_t width; 211 uint32_t height; 212 uint32_t format; 213 uint32_t flags; 214 struct { 215 uint64_t *modifiers; 216 unsigned count; 217 }; 218 }; 219 220 /** 221 * An allocated GBM surface. 222 * 223 * To modify this structure, introduce a new gbm_surface_v<N> structure, add it 224 * to the end of this structure, and increment GBM_BACKEND_ABI_VERSION. 225 */ 226 struct gbm_surface { 227 struct gbm_device *gbm; 228 struct gbm_surface_v0 v0; 229 }; 230 231 /** 232 * GBM backend interfaces corresponding to GBM_BACKEND_ABI_VERSION = 0 233 * 234 * DO NOT MODIFY THIS STRUCT. Instead, introduce a gbm_backend_v1, increment 235 * GBM_BACKEND_ABI_VERSION, append gbm_backend_v1 to gbm_backend. 236 */ 237 struct gbm_backend_v0 { 238 /** 239 * The version of the GBM backend interface supported by this backend. This 240 * is set by the backend itself, and may be greater or less than the version 241 * supported by the loader. It is the responsibility of the GBM loader to 242 * respect this version when accessing fields in this structure. 243 */ 244 uint32_t backend_version; 245 246 const char *backend_name; 247 struct gbm_device *(*create_device)(int fd, uint32_t gbm_backend_version); 248 }; 249 250 /** 251 * The interface exposed by an external GBM backend. 252 * 253 * To modify this structure, introduce a new gbm_backend_v<N> structure, add it 254 * to the end of this structure, and increment GBM_BACKEND_ABI_VERSION. 255 */ 256 struct gbm_backend { 257 struct gbm_backend_v0 v0; 258 }; 259 260 /** 261 * GBM interfaces exposed to GBM backends at GBM_BACKEND_ABI_VERSION >= 0 262 * 263 * DO NOT MODIFY THIS STRUCT. Instead, introduce a gbm_core_v1, increment 264 * GBM_BACKEND_ABI_VERSION, and append gbm_core_v1 to gbm_backend. 265 */ 266 struct gbm_core_v0 { 267 /** 268 * The version of the GBM backend interface supported by the GBM loader. This 269 * is set by the loader, and may be greater or less than the version 270 * supported by a given backend. It is the responsibility of the backend to 271 * respect this version when accessing fields in this structure and other 272 * structures allocated or modified by the loader. 273 */ 274 uint32_t core_version; 275 276 uint32_t (*format_canonicalize)(uint32_t gbm_format); 277 }; 278 279 /** 280 * The interface exposed by the GBM core/loader code to GBM backends. 281 * 282 * To modify this structure, introduce a new gbm_core_v<N> structure, add it 283 * to the end of this structure, and increment GBM_BACKEND_ABI_VERSION. 284 */ 285 struct gbm_core { 286 struct gbm_core_v0 v0; 287 }; 288 289 /** 290 * The entrypoint an external GBM backend exports. 291 * 292 * Prior to creating any devices using the backend, GBM will look up and call 293 * this function to request the backend's interface and convey the loader's 294 * version and exported interface to the backend. 295 * 296 * DO NOT MODIFY THIS FUNCTION NAME OR PROTOTYPE. It must remain unchanged to 297 * preserve backwards compatibility with existing GBM backends. 298 */ 299 #define GBM_GET_BACKEND_PROC gbmint_get_backend 300 #define _GBM_MKSTRX(s) _GBM_MKSTR(s) 301 #define _GBM_MKSTR(s) #s 302 #define GBM_GET_BACKEND_PROC_NAME _GBM_MKSTRX(GBM_GET_BACKEND_PROC) 303 typedef const struct gbm_backend *(*GBM_GET_BACKEND_PROC_PTR)(const struct gbm_core *gbm_core); 304 305 #endif 306