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