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 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
  93 MODULE_DESCRIPTION("DRM VRAM memory-management helpers");
  94 MODULE_LICENSE("GPL");