1 // SPDX-License-Identifier: GPL-2.0-or-later
2
3 #include <linux/module.h>
4
5 /**
6 * DOC: overview
7 *
8 * This library provides &struct drm_gem_vram_object (GEM VRAM), a GEM
9 * buffer object that is backed by video RAM. It can be used for
10 * framebuffer devices with dedicated memory. The video RAM can be
11 * managed with &struct drm_vram_mm (VRAM MM). Both data structures are
12 * supposed to be used together, but can also be used individually.
13 *
14 * With the GEM interface userspace applications create, manage and destroy
15 * graphics buffers, such as an on-screen framebuffer. GEM does not provide
16 * an implementation of these interfaces. It's up to the DRM driver to
17 * provide an implementation that suits the hardware. If the hardware device
18 * contains dedicated video memory, the DRM driver can use the VRAM helper
19 * library. Each active buffer object is stored in video RAM. Active
20 * buffer are used for drawing the current frame, typically something like
21 * the frame's scanout buffer or the cursor image. If there's no more space
22 * left in VRAM, inactive GEM objects can be moved to system memory.
23 *
24 * The easiest way to use the VRAM helper library is to call
25 * drm_vram_helper_alloc_mm(). The function allocates and initializes an
26 * instance of &struct drm_vram_mm in &struct drm_device.vram_mm . Use
27 * &DRM_GEM_VRAM_DRIVER to initialize &struct drm_driver and
28 * &DRM_VRAM_MM_FILE_OPERATIONS to initialize &struct file_operations;
29 * as illustrated below.
30 *
31 * .. code-block:: c
32 *
33 * struct file_operations fops ={
34 * .owner = THIS_MODULE,
35 * DRM_VRAM_MM_FILE_OPERATION
36 * };
37 * struct drm_driver drv = {
38 * .driver_feature = DRM_ ... ,
39 * .fops = &fops,
40 * DRM_GEM_VRAM_DRIVER
41 * };
42 *
43 * int init_drm_driver()
44 * {
45 * struct drm_device *dev;
46 * uint64_t vram_base;
47 * unsigned long vram_size;
48 * int ret;
49 *
50 * // setup device, vram base and size
51 * // ...
52 *
53 * ret = drm_vram_helper_alloc_mm(dev, vram_base, vram_size,
54 * &drm_gem_vram_mm_funcs);
55 * if (ret)
56 * return ret;
57 * return 0;
58 * }
59 *
60 * This creates an instance of &struct drm_vram_mm, exports DRM userspace
61 * interfaces for GEM buffer management and initializes file operations to
62 * allow for accessing created GEM buffers. With this setup, the DRM driver
63 * manages an area of video RAM with VRAM MM and provides GEM VRAM objects
64 * to userspace.
65 *
66 * To clean up the VRAM memory management, call drm_vram_helper_release_mm()
67 * in the driver's clean-up code.
68 *
69 * .. code-block:: c
70 *
71 * void fini_drm_driver()
72 * {
73 * struct drm_device *dev = ...;
74 *
75 * drm_vram_helper_release_mm(dev);
76 * }
77 *
78 * For drawing or scanout operations, buffer object have to be pinned in video
79 * RAM. Call drm_gem_vram_pin() with &DRM_GEM_VRAM_PL_FLAG_VRAM or
80 * &DRM_GEM_VRAM_PL_FLAG_SYSTEM to pin a buffer object in video RAM or system
81 * memory. Call drm_gem_vram_unpin() to release the pinned object afterwards.
82 *
83 * A buffer object that is pinned in video RAM has a fixed address within that
84 * memory region. Call drm_gem_vram_offset() to retrieve this value. Typically
85 * it's used to program the hardware's scanout engine for framebuffers, set
86 * the cursor overlay's image for a mouse cursor, or use it as input to the
87 * hardware's draing engine.
88 *
89 * To access a buffer object's memory from the DRM driver, call
90 * drm_gem_vram_kmap(). It (optionally) maps the buffer into kernel address
91 * space and returns the memory address. Use drm_gem_vram_kunmap() to
92 * release the mapping.
93 */
94
95 MODULE_DESCRIPTION("DRM VRAM memory-management helpers");
96 MODULE_LICENSE("GPL");