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
40struct 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 */
83struct 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 */
168struct 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 */
180struct 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 */
198struct 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 */
209struct 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 */
226struct 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 */
237struct 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 */
256struct 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 */
266struct 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 */
285struct 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)
303typedef const struct gbm_backend *(*GBM_GET_BACKEND_PROC_PTR)(const struct gbm_core *gbm_core);
304
305#endif
306