1// SPDX-License-Identifier: GPL-2.0-or-later
2/*
3 * drm gem framebuffer helper functions
4 *
5 * Copyright (C) 2017 Noralf Trønnes
6 */
7
8#include <linux/export.h>
9#include <linux/slab.h>
10#include <linux/module.h>
11
12#include <drm/drm_damage_helper.h>
13#include <drm/drm_drv.h>
14#include <drm/drm_fourcc.h>
15#include <drm/drm_framebuffer.h>
16#include <drm/drm_gem.h>
17#include <drm/drm_gem_framebuffer_helper.h>
18#include <drm/drm_modeset_helper.h>
19
20#include "drm_internal.h"
21
22MODULE_IMPORT_NS("DMA_BUF");
23
24#define AFBC_HEADER_SIZE 16
25#define AFBC_TH_LAYOUT_ALIGNMENT 8
26#define AFBC_HDR_ALIGN 64
27#define AFBC_SUPERBLOCK_PIXELS 256
28#define AFBC_SUPERBLOCK_ALIGNMENT 128
29#define AFBC_TH_BODY_START_ALIGNMENT 4096
30
31/**
32 * DOC: overview
33 *
34 * This library provides helpers for drivers that don't subclass
35 * &drm_framebuffer and use &drm_gem_object for their backing storage.
36 *
37 * Drivers without additional needs to validate framebuffers can simply use
38 * drm_gem_fb_create() and everything is wired up automatically. Other drivers
39 * can use all parts independently.
40 */
41
42/**
43 * drm_gem_fb_get_obj() - Get GEM object backing the framebuffer
44 * @fb: Framebuffer
45 * @plane: Plane index
46 *
47 * No additional reference is taken beyond the one that the &drm_frambuffer
48 * already holds.
49 *
50 * Returns:
51 * Pointer to &drm_gem_object for the given framebuffer and plane index or NULL
52 * if it does not exist.
53 */
54struct drm_gem_object *drm_gem_fb_get_obj(struct drm_framebuffer *fb,
55 unsigned int plane)
56{
57 struct drm_device *dev = fb->dev;
58
59 if (drm_WARN_ON_ONCE(dev, plane >= ARRAY_SIZE(fb->obj)))
60 return NULL;
61 else if (drm_WARN_ON_ONCE(dev, !fb->obj[plane]))
62 return NULL;
63
64 return fb->obj[plane];
65}
66EXPORT_SYMBOL_GPL(drm_gem_fb_get_obj);
67
68static int
69drm_gem_fb_init(struct drm_device *dev,
70 struct drm_framebuffer *fb,
71 const struct drm_format_info *info,
72 const struct drm_mode_fb_cmd2 *mode_cmd,
73 struct drm_gem_object **obj, unsigned int num_planes,
74 const struct drm_framebuffer_funcs *funcs)
75{
76 unsigned int i;
77 int ret;
78
79 drm_helper_mode_fill_fb_struct(dev, fb, info, mode_cmd);
80
81 for (i = 0; i < num_planes; i++)
82 fb->obj[i] = obj[i];
83
84 ret = drm_framebuffer_init(dev, fb, funcs);
85 if (ret)
86 drm_err(dev, "Failed to init framebuffer: %d\n", ret);
87
88 return ret;
89}
90
91/**
92 * drm_gem_fb_destroy - Free GEM backed framebuffer
93 * @fb: Framebuffer
94 *
95 * Frees a GEM backed framebuffer with its backing buffer(s) and the structure
96 * itself. Drivers can use this as their &drm_framebuffer_funcs->destroy
97 * callback.
98 */
99void drm_gem_fb_destroy(struct drm_framebuffer *fb)
100{
101 unsigned int i;
102
103 for (i = 0; i < fb->format->num_planes; i++)
104 drm_gem_object_put(obj: fb->obj[i]);
105
106 drm_framebuffer_cleanup(fb);
107 kfree(objp: fb);
108}
109EXPORT_SYMBOL(drm_gem_fb_destroy);
110
111/**
112 * drm_gem_fb_create_handle - Create handle for GEM backed framebuffer
113 * @fb: Framebuffer
114 * @file: DRM file to register the handle for
115 * @handle: Pointer to return the created handle
116 *
117 * This function creates a handle for the GEM object backing the framebuffer.
118 * Drivers can use this as their &drm_framebuffer_funcs->create_handle
119 * callback. The GETFB IOCTL calls into this callback.
120 *
121 * Returns:
122 * 0 on success or a negative error code on failure.
123 */
124int drm_gem_fb_create_handle(struct drm_framebuffer *fb, struct drm_file *file,
125 unsigned int *handle)
126{
127 return drm_gem_handle_create(file_priv: file, obj: fb->obj[0], handlep: handle);
128}
129EXPORT_SYMBOL(drm_gem_fb_create_handle);
130
131/**
132 * drm_gem_fb_init_with_funcs() - Helper function for implementing
133 * &drm_mode_config_funcs.fb_create
134 * callback in cases when the driver
135 * allocates a subclass of
136 * struct drm_framebuffer
137 * @dev: DRM device
138 * @fb: framebuffer object
139 * @file: DRM file that holds the GEM handle(s) backing the framebuffer
140 * @info: pixel format information
141 * @mode_cmd: Metadata from the userspace framebuffer creation request
142 * @funcs: vtable to be used for the new framebuffer object
143 *
144 * This function can be used to set &drm_framebuffer_funcs for drivers that need
145 * custom framebuffer callbacks. Use drm_gem_fb_create() if you don't need to
146 * change &drm_framebuffer_funcs. The function does buffer size validation.
147 * The buffer size validation is for a general case, though, so users should
148 * pay attention to the checks being appropriate for them or, at least,
149 * non-conflicting.
150 *
151 * Returns:
152 * Zero or a negative error code.
153 */
154int drm_gem_fb_init_with_funcs(struct drm_device *dev,
155 struct drm_framebuffer *fb,
156 struct drm_file *file,
157 const struct drm_format_info *info,
158 const struct drm_mode_fb_cmd2 *mode_cmd,
159 const struct drm_framebuffer_funcs *funcs)
160{
161 struct drm_gem_object *objs[DRM_FORMAT_MAX_PLANES];
162 unsigned int i;
163 int ret;
164
165 if (drm_drv_uses_atomic_modeset(dev) &&
166 !drm_any_plane_has_format(dev, format: mode_cmd->pixel_format,
167 modifier: mode_cmd->modifier[0])) {
168 drm_dbg_kms(dev, "Unsupported pixel format %p4cc / modifier 0x%llx\n",
169 &mode_cmd->pixel_format, mode_cmd->modifier[0]);
170 return -EINVAL;
171 }
172
173 for (i = 0; i < info->num_planes; i++) {
174 unsigned int width = mode_cmd->width / (i ? info->hsub : 1);
175 unsigned int height = mode_cmd->height / (i ? info->vsub : 1);
176 unsigned int min_size;
177
178 objs[i] = drm_gem_object_lookup(filp: file, handle: mode_cmd->handles[i]);
179 if (!objs[i]) {
180 drm_dbg_kms(dev, "Failed to lookup GEM object\n");
181 ret = -ENOENT;
182 goto err_gem_object_put;
183 }
184
185 min_size = (height - 1) * mode_cmd->pitches[i]
186 + drm_format_info_min_pitch(info, plane: i, buffer_width: width)
187 + mode_cmd->offsets[i];
188
189 if (objs[i]->size < min_size) {
190 drm_dbg_kms(dev,
191 "GEM object size (%zu) smaller than minimum size (%u) for plane %d\n",
192 objs[i]->size, min_size, i);
193 drm_gem_object_put(obj: objs[i]);
194 ret = -EINVAL;
195 goto err_gem_object_put;
196 }
197 }
198
199 ret = drm_gem_fb_init(dev, fb, info, mode_cmd, obj: objs, num_planes: i, funcs);
200 if (ret)
201 goto err_gem_object_put;
202
203 return 0;
204
205err_gem_object_put:
206 while (i > 0) {
207 --i;
208 drm_gem_object_put(obj: objs[i]);
209 }
210 return ret;
211}
212EXPORT_SYMBOL_GPL(drm_gem_fb_init_with_funcs);
213
214/**
215 * drm_gem_fb_create_with_funcs() - Helper function for the
216 * &drm_mode_config_funcs.fb_create
217 * callback
218 * @dev: DRM device
219 * @file: DRM file that holds the GEM handle(s) backing the framebuffer
220 * @info: pixel format information
221 * @mode_cmd: Metadata from the userspace framebuffer creation request
222 * @funcs: vtable to be used for the new framebuffer object
223 *
224 * This function can be used to set &drm_framebuffer_funcs for drivers that need
225 * custom framebuffer callbacks. Use drm_gem_fb_create() if you don't need to
226 * change &drm_framebuffer_funcs. The function does buffer size validation.
227 *
228 * Returns:
229 * Pointer to a &drm_framebuffer on success or an error pointer on failure.
230 */
231struct drm_framebuffer *
232drm_gem_fb_create_with_funcs(struct drm_device *dev, struct drm_file *file,
233 const struct drm_format_info *info,
234 const struct drm_mode_fb_cmd2 *mode_cmd,
235 const struct drm_framebuffer_funcs *funcs)
236{
237 struct drm_framebuffer *fb;
238 int ret;
239
240 fb = kzalloc(sizeof(*fb), GFP_KERNEL);
241 if (!fb)
242 return ERR_PTR(error: -ENOMEM);
243
244 ret = drm_gem_fb_init_with_funcs(dev, fb, file, info, mode_cmd, funcs);
245 if (ret) {
246 kfree(objp: fb);
247 return ERR_PTR(error: ret);
248 }
249
250 return fb;
251}
252EXPORT_SYMBOL_GPL(drm_gem_fb_create_with_funcs);
253
254static const struct drm_framebuffer_funcs drm_gem_fb_funcs = {
255 .destroy = drm_gem_fb_destroy,
256 .create_handle = drm_gem_fb_create_handle,
257};
258
259/**
260 * drm_gem_fb_create() - Helper function for the
261 * &drm_mode_config_funcs.fb_create callback
262 * @dev: DRM device
263 * @file: DRM file that holds the GEM handle(s) backing the framebuffer
264 * @info: pixel format information
265 * @mode_cmd: Metadata from the userspace framebuffer creation request
266 *
267 * This function creates a new framebuffer object described by
268 * &drm_mode_fb_cmd2. This description includes handles for the buffer(s)
269 * backing the framebuffer.
270 *
271 * If your hardware has special alignment or pitch requirements these should be
272 * checked before calling this function. The function does buffer size
273 * validation. Use drm_gem_fb_create_with_dirty() if you need framebuffer
274 * flushing.
275 *
276 * Drivers can use this as their &drm_mode_config_funcs.fb_create callback.
277 * The ADDFB2 IOCTL calls into this callback.
278 *
279 * Returns:
280 * Pointer to a &drm_framebuffer on success or an error pointer on failure.
281 */
282struct drm_framebuffer *
283drm_gem_fb_create(struct drm_device *dev, struct drm_file *file,
284 const struct drm_format_info *info,
285 const struct drm_mode_fb_cmd2 *mode_cmd)
286{
287 return drm_gem_fb_create_with_funcs(dev, file, info, mode_cmd,
288 &drm_gem_fb_funcs);
289}
290EXPORT_SYMBOL_GPL(drm_gem_fb_create);
291
292static const struct drm_framebuffer_funcs drm_gem_fb_funcs_dirtyfb = {
293 .destroy = drm_gem_fb_destroy,
294 .create_handle = drm_gem_fb_create_handle,
295 .dirty = drm_atomic_helper_dirtyfb,
296};
297
298/**
299 * drm_gem_fb_create_with_dirty() - Helper function for the
300 * &drm_mode_config_funcs.fb_create callback
301 * @dev: DRM device
302 * @file: DRM file that holds the GEM handle(s) backing the framebuffer
303 * @info: pixel format information
304 * @mode_cmd: Metadata from the userspace framebuffer creation request
305 *
306 * This function creates a new framebuffer object described by
307 * &drm_mode_fb_cmd2. This description includes handles for the buffer(s)
308 * backing the framebuffer. drm_atomic_helper_dirtyfb() is used for the dirty
309 * callback giving framebuffer flushing through the atomic machinery. Use
310 * drm_gem_fb_create() if you don't need the dirty callback.
311 * The function does buffer size validation.
312 *
313 * Drivers should also call drm_plane_enable_fb_damage_clips() on all planes
314 * to enable userspace to use damage clips also with the ATOMIC IOCTL.
315 *
316 * Drivers can use this as their &drm_mode_config_funcs.fb_create callback.
317 * The ADDFB2 IOCTL calls into this callback.
318 *
319 * Returns:
320 * Pointer to a &drm_framebuffer on success or an error pointer on failure.
321 */
322struct drm_framebuffer *
323drm_gem_fb_create_with_dirty(struct drm_device *dev, struct drm_file *file,
324 const struct drm_format_info *info,
325 const struct drm_mode_fb_cmd2 *mode_cmd)
326{
327 return drm_gem_fb_create_with_funcs(dev, file, info, mode_cmd,
328 &drm_gem_fb_funcs_dirtyfb);
329}
330EXPORT_SYMBOL_GPL(drm_gem_fb_create_with_dirty);
331
332/**
333 * drm_gem_fb_vmap - maps all framebuffer BOs into kernel address space
334 * @fb: the framebuffer
335 * @map: returns the mapping's address for each BO
336 * @data: returns the data address for each BO, can be NULL
337 *
338 * This function maps all buffer objects of the given framebuffer into
339 * kernel address space and stores them in struct iosys_map. If the
340 * mapping operation fails for one of the BOs, the function unmaps the
341 * already established mappings automatically.
342 *
343 * Callers that want to access a BO's stored data should pass @data.
344 * The argument returns the addresses of the data stored in each BO. This
345 * is different from @map if the framebuffer's offsets field is non-zero.
346 *
347 * Both, @map and @data, must each refer to arrays with at least
348 * fb->format->num_planes elements.
349 *
350 * See drm_gem_fb_vunmap() for unmapping.
351 *
352 * Returns:
353 * 0 on success, or a negative errno code otherwise.
354 */
355int drm_gem_fb_vmap(struct drm_framebuffer *fb, struct iosys_map *map,
356 struct iosys_map *data)
357{
358 struct drm_gem_object *obj;
359 unsigned int i;
360 int ret;
361
362 for (i = 0; i < fb->format->num_planes; ++i) {
363 obj = drm_gem_fb_get_obj(fb, i);
364 if (!obj) {
365 ret = -EINVAL;
366 goto err_drm_gem_vunmap;
367 }
368 ret = drm_gem_vmap(obj, map: &map[i]);
369 if (ret)
370 goto err_drm_gem_vunmap;
371 }
372
373 if (data) {
374 for (i = 0; i < fb->format->num_planes; ++i) {
375 memcpy(to: &data[i], from: &map[i], len: sizeof(data[i]));
376 if (iosys_map_is_null(map: &data[i]))
377 continue;
378 iosys_map_incr(map: &data[i], incr: fb->offsets[i]);
379 }
380 }
381
382 return 0;
383
384err_drm_gem_vunmap:
385 while (i) {
386 --i;
387 obj = drm_gem_fb_get_obj(fb, i);
388 if (!obj)
389 continue;
390 drm_gem_vunmap(obj, map: &map[i]);
391 }
392 return ret;
393}
394EXPORT_SYMBOL(drm_gem_fb_vmap);
395
396/**
397 * drm_gem_fb_vunmap - unmaps framebuffer BOs from kernel address space
398 * @fb: the framebuffer
399 * @map: mapping addresses as returned by drm_gem_fb_vmap()
400 *
401 * This function unmaps all buffer objects of the given framebuffer.
402 *
403 * See drm_gem_fb_vmap() for more information.
404 */
405void drm_gem_fb_vunmap(struct drm_framebuffer *fb, struct iosys_map *map)
406{
407 unsigned int i = fb->format->num_planes;
408 struct drm_gem_object *obj;
409
410 while (i) {
411 --i;
412 obj = drm_gem_fb_get_obj(fb, i);
413 if (!obj)
414 continue;
415 if (iosys_map_is_null(map: &map[i]))
416 continue;
417 drm_gem_vunmap(obj, map: &map[i]);
418 }
419}
420EXPORT_SYMBOL(drm_gem_fb_vunmap);
421
422static void __drm_gem_fb_end_cpu_access(struct drm_framebuffer *fb, enum dma_data_direction dir,
423 unsigned int num_planes)
424{
425 struct dma_buf_attachment *import_attach;
426 struct drm_gem_object *obj;
427 int ret;
428
429 while (num_planes) {
430 --num_planes;
431 obj = drm_gem_fb_get_obj(fb, num_planes);
432 if (!obj)
433 continue;
434 import_attach = obj->import_attach;
435 if (!drm_gem_is_imported(obj))
436 continue;
437 ret = dma_buf_end_cpu_access(dma_buf: import_attach->dmabuf, dir);
438 if (ret)
439 drm_err(fb->dev, "dma_buf_end_cpu_access(%u, %d) failed: %d\n",
440 ret, num_planes, dir);
441 }
442}
443
444/**
445 * drm_gem_fb_begin_cpu_access - prepares GEM buffer objects for CPU access
446 * @fb: the framebuffer
447 * @dir: access mode
448 *
449 * Prepares a framebuffer's GEM buffer objects for CPU access. This function
450 * must be called before accessing the BO data within the kernel. For imported
451 * BOs, the function calls dma_buf_begin_cpu_access().
452 *
453 * See drm_gem_fb_end_cpu_access() for signalling the end of CPU access.
454 *
455 * Returns:
456 * 0 on success, or a negative errno code otherwise.
457 */
458int drm_gem_fb_begin_cpu_access(struct drm_framebuffer *fb, enum dma_data_direction dir)
459{
460 struct dma_buf_attachment *import_attach;
461 struct drm_gem_object *obj;
462 unsigned int i;
463 int ret;
464
465 for (i = 0; i < fb->format->num_planes; ++i) {
466 obj = drm_gem_fb_get_obj(fb, i);
467 if (!obj) {
468 ret = -EINVAL;
469 goto err___drm_gem_fb_end_cpu_access;
470 }
471 import_attach = obj->import_attach;
472 if (!drm_gem_is_imported(obj))
473 continue;
474 ret = dma_buf_begin_cpu_access(dma_buf: import_attach->dmabuf, dir);
475 if (ret)
476 goto err___drm_gem_fb_end_cpu_access;
477 }
478
479 return 0;
480
481err___drm_gem_fb_end_cpu_access:
482 __drm_gem_fb_end_cpu_access(fb, dir, num_planes: i);
483 return ret;
484}
485EXPORT_SYMBOL(drm_gem_fb_begin_cpu_access);
486
487/**
488 * drm_gem_fb_end_cpu_access - signals end of CPU access to GEM buffer objects
489 * @fb: the framebuffer
490 * @dir: access mode
491 *
492 * Signals the end of CPU access to the given framebuffer's GEM buffer objects. This
493 * function must be paired with a corresponding call to drm_gem_fb_begin_cpu_access().
494 * For imported BOs, the function calls dma_buf_end_cpu_access().
495 *
496 * See also drm_gem_fb_begin_cpu_access().
497 */
498void drm_gem_fb_end_cpu_access(struct drm_framebuffer *fb, enum dma_data_direction dir)
499{
500 __drm_gem_fb_end_cpu_access(fb, dir, num_planes: fb->format->num_planes);
501}
502EXPORT_SYMBOL(drm_gem_fb_end_cpu_access);
503
504// TODO Drop this function and replace by drm_format_info_bpp() once all
505// DRM_FORMAT_* provide proper block info in drivers/gpu/drm/drm_fourcc.c
506static __u32 drm_gem_afbc_get_bpp(struct drm_device *dev,
507 const struct drm_format_info *info,
508 const struct drm_mode_fb_cmd2 *mode_cmd)
509{
510 switch (info->format) {
511 case DRM_FORMAT_YUV420_8BIT:
512 return 12;
513 case DRM_FORMAT_YUV420_10BIT:
514 return 15;
515 case DRM_FORMAT_VUY101010:
516 return 30;
517 default:
518 return drm_format_info_bpp(info, plane: 0);
519 }
520}
521
522static int drm_gem_afbc_min_size(struct drm_device *dev,
523 const struct drm_format_info *info,
524 const struct drm_mode_fb_cmd2 *mode_cmd,
525 struct drm_afbc_framebuffer *afbc_fb)
526{
527 __u32 n_blocks, w_alignment, h_alignment, hdr_alignment;
528 /* remove bpp when all users properly encode cpp in drm_format_info */
529 __u32 bpp;
530
531 switch (mode_cmd->modifier[0] & AFBC_FORMAT_MOD_BLOCK_SIZE_MASK) {
532 case AFBC_FORMAT_MOD_BLOCK_SIZE_16x16:
533 afbc_fb->block_width = 16;
534 afbc_fb->block_height = 16;
535 break;
536 case AFBC_FORMAT_MOD_BLOCK_SIZE_32x8:
537 afbc_fb->block_width = 32;
538 afbc_fb->block_height = 8;
539 break;
540 /* no user exists yet - fall through */
541 case AFBC_FORMAT_MOD_BLOCK_SIZE_64x4:
542 case AFBC_FORMAT_MOD_BLOCK_SIZE_32x8_64x4:
543 default:
544 drm_dbg_kms(dev, "Invalid AFBC_FORMAT_MOD_BLOCK_SIZE: %lld.\n",
545 mode_cmd->modifier[0]
546 & AFBC_FORMAT_MOD_BLOCK_SIZE_MASK);
547 return -EINVAL;
548 }
549
550 /* tiled header afbc */
551 w_alignment = afbc_fb->block_width;
552 h_alignment = afbc_fb->block_height;
553 hdr_alignment = AFBC_HDR_ALIGN;
554 if (mode_cmd->modifier[0] & AFBC_FORMAT_MOD_TILED) {
555 w_alignment *= AFBC_TH_LAYOUT_ALIGNMENT;
556 h_alignment *= AFBC_TH_LAYOUT_ALIGNMENT;
557 hdr_alignment = AFBC_TH_BODY_START_ALIGNMENT;
558 }
559
560 afbc_fb->aligned_width = ALIGN(mode_cmd->width, w_alignment);
561 afbc_fb->aligned_height = ALIGN(mode_cmd->height, h_alignment);
562 afbc_fb->offset = mode_cmd->offsets[0];
563
564 bpp = drm_gem_afbc_get_bpp(dev, info, mode_cmd);
565 if (!bpp) {
566 drm_dbg_kms(dev, "Invalid AFBC bpp value: %d\n", bpp);
567 return -EINVAL;
568 }
569
570 n_blocks = (afbc_fb->aligned_width * afbc_fb->aligned_height)
571 / AFBC_SUPERBLOCK_PIXELS;
572 afbc_fb->afbc_size = ALIGN(n_blocks * AFBC_HEADER_SIZE, hdr_alignment);
573 afbc_fb->afbc_size += n_blocks * ALIGN(bpp * AFBC_SUPERBLOCK_PIXELS / 8,
574 AFBC_SUPERBLOCK_ALIGNMENT);
575
576 return 0;
577}
578
579/**
580 * drm_gem_fb_afbc_init() - Helper function for drivers using afbc to
581 * fill and validate all the afbc-specific
582 * struct drm_afbc_framebuffer members
583 *
584 * @dev: DRM device
585 * @afbc_fb: afbc-specific framebuffer
586 * @info: pixel format information
587 * @mode_cmd: Metadata from the userspace framebuffer creation request
588 * @afbc_fb: afbc framebuffer
589 *
590 * This function can be used by drivers which support afbc to complete
591 * the preparation of struct drm_afbc_framebuffer. It must be called after
592 * allocating the said struct and calling drm_gem_fb_init_with_funcs().
593 * It is caller's responsibility to put afbc_fb->base.obj objects in case
594 * the call is unsuccessful.
595 *
596 * Returns:
597 * Zero on success or a negative error value on failure.
598 */
599int drm_gem_fb_afbc_init(struct drm_device *dev,
600 const struct drm_format_info *info,
601 const struct drm_mode_fb_cmd2 *mode_cmd,
602 struct drm_afbc_framebuffer *afbc_fb)
603{
604 struct drm_gem_object **objs;
605 int ret;
606
607 objs = afbc_fb->base.obj;
608
609 ret = drm_gem_afbc_min_size(dev, info, mode_cmd, afbc_fb);
610 if (ret < 0)
611 return ret;
612
613 if (objs[0]->size < afbc_fb->afbc_size) {
614 drm_dbg_kms(dev, "GEM object size (%zu) smaller than minimum afbc size (%u)\n",
615 objs[0]->size, afbc_fb->afbc_size);
616 return -EINVAL;
617 }
618
619 return 0;
620}
621EXPORT_SYMBOL_GPL(drm_gem_fb_afbc_init);
622