Commit | Line | Data |
---|---|---|
85438a8d TZ |
1 | // SPDX-License-Identifier: GPL-2.0-or-later |
2 | ||
3 | #include <linux/module.h> | |
4 | ||
59f5989a TZ |
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 | * If you have to evict a buffer object from video RAM (e.g., for freeing up | |
83 | * memory), unpin the buffer and call drm_gem_vram_push_to_system(). | |
84 | * | |
85 | * A buffer object that is pinned in video RAM has a fixed address within that | |
86 | * memory region. Call drm_gem_vram_offset() to retrieve this value. Typically | |
87 | * it's used to program the hardware's scanout engine for framebuffers, set | |
88 | * the cursor overlay's image for a mouse cursor, or use it as input to the | |
89 | * hardware's draing engine. | |
90 | * | |
91 | * To access a buffer object's memory from the DRM driver, call | |
92 | * drm_gem_vram_kmap(). It (optionally) maps the buffer into kernel address | |
93 | * space and returns the memory address. Use drm_gem_vram_kunmap() to | |
94 | * release the mapping. | |
95 | */ | |
96 | ||
85438a8d TZ |
97 | MODULE_DESCRIPTION("DRM VRAM memory-management helpers"); |
98 | MODULE_LICENSE("GPL"); |