drivers/gpu/drm/drm_vram_helper_common.c

   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");