include/drm/drm_gem_dma_helper.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef __DRM_GEM_DMA_HELPER_H__
   3 #define __DRM_GEM_DMA_HELPER_H__
   4
   5 #include <drm/drm_file.h>
   6 #include <drm/drm_ioctl.h>
   7 #include <drm/drm_gem.h>
   8
   9 struct drm_mode_create_dumb;
  10
  11 /**
  12  * struct drm_gem_dma_object - GEM object backed by DMA memory allocations
  13  * @base: base GEM object
  14  * @dma_addr: DMA address of the backing memory
  15  * @sgt: scatter/gather table for imported PRIME buffers. The table can have
  16  *       more than one entry but they are guaranteed to have contiguous
  17  *       DMA addresses.
  18  * @vaddr: kernel virtual address of the backing memory
  19  * @map_noncoherent: if true, the GEM object is backed by non-coherent memory
  20  */
  21 struct drm_gem_dma_object {
  22         struct drm_gem_object base;
  23         dma_addr_t dma_addr;
  24         struct sg_table *sgt;
  25
  26         /* For objects with DMA memory allocated by GEM DMA */
  27         void *vaddr;
  28
  29         bool map_noncoherent;
  30 };
  31
  32 #define to_drm_gem_dma_obj(gem_obj) \
  33         container_of(gem_obj, struct drm_gem_dma_object, base)
  34
  35 struct drm_gem_dma_object *drm_gem_dma_create(struct drm_device *drm,
  36                                               size_t size);
  37 void drm_gem_dma_free(struct drm_gem_dma_object *dma_obj);
  38 void drm_gem_dma_print_info(const struct drm_gem_dma_object *dma_obj,
  39                             struct drm_printer *p, unsigned int indent);
  40 struct sg_table *drm_gem_dma_get_sg_table(struct drm_gem_dma_object *dma_obj);
  41 int drm_gem_dma_vmap(struct drm_gem_dma_object *dma_obj,
  42                      struct iosys_map *map);
  43 int drm_gem_dma_mmap(struct drm_gem_dma_object *dma_obj, struct vm_area_struct *vma);
  44
  45 extern const struct vm_operations_struct drm_gem_dma_vm_ops;
  46
  47 /*
  48  * GEM object functions
  49  */
  50
  51 /**
  52  * drm_gem_dma_object_free - GEM object function for drm_gem_dma_free()
  53  * @obj: GEM object to free
  54  *
  55  * This function wraps drm_gem_dma_free_object(). Drivers that employ the DMA helpers
  56  * should use it as their &drm_gem_object_funcs.free handler.
  57  */
  58 static inline void drm_gem_dma_object_free(struct drm_gem_object *obj)
  59 {
  60         struct drm_gem_dma_object *dma_obj = to_drm_gem_dma_obj(obj);
  61
  62         drm_gem_dma_free(dma_obj);
  63 }
  64
  65 /**
  66  * drm_gem_dma_object_print_info() - Print &drm_gem_dma_object info for debugfs
  67  * @p: DRM printer
  68  * @indent: Tab indentation level
  69  * @obj: GEM object
  70  *
  71  * This function wraps drm_gem_dma_print_info(). Drivers that employ the DMA helpers
  72  * should use this function as their &drm_gem_object_funcs.print_info handler.
  73  */
  74 static inline void drm_gem_dma_object_print_info(struct drm_printer *p, unsigned int indent,
  75                                                  const struct drm_gem_object *obj)
  76 {
  77         const struct drm_gem_dma_object *dma_obj = to_drm_gem_dma_obj(obj);
  78
  79         drm_gem_dma_print_info(dma_obj, p, indent);
  80 }
  81
  82 /**
  83  * drm_gem_dma_object_get_sg_table - GEM object function for drm_gem_dma_get_sg_table()
  84  * @obj: GEM object
  85  *
  86  * This function wraps drm_gem_dma_get_sg_table(). Drivers that employ the DMA helpers should
  87  * use it as their &drm_gem_object_funcs.get_sg_table handler.
  88  *
  89  * Returns:
  90  * A pointer to the scatter/gather table of pinned pages or NULL on failure.
  91  */
  92 static inline struct sg_table *drm_gem_dma_object_get_sg_table(struct drm_gem_object *obj)
  93 {
  94         struct drm_gem_dma_object *dma_obj = to_drm_gem_dma_obj(obj);
  95
  96         return drm_gem_dma_get_sg_table(dma_obj);
  97 }
  98
  99 /*
 100  * drm_gem_dma_object_vmap - GEM object function for drm_gem_dma_vmap()
 101  * @obj: GEM object
 102  * @map: Returns the kernel virtual address of the DMA GEM object's backing store.
 103  *
 104  * This function wraps drm_gem_dma_vmap(). Drivers that employ the DMA helpers should
 105  * use it as their &drm_gem_object_funcs.vmap handler.
 106  *
 107  * Returns:
 108  * 0 on success or a negative error code on failure.
 109  */
 110 static inline int drm_gem_dma_object_vmap(struct drm_gem_object *obj,
 111                                           struct iosys_map *map)
 112 {
 113         struct drm_gem_dma_object *dma_obj = to_drm_gem_dma_obj(obj);
 114
 115         return drm_gem_dma_vmap(dma_obj, map);
 116 }
 117
 118 /**
 119  * drm_gem_dma_object_mmap - GEM object function for drm_gem_dma_mmap()
 120  * @obj: GEM object
 121  * @vma: VMA for the area to be mapped
 122  *
 123  * This function wraps drm_gem_dma_mmap(). Drivers that employ the dma helpers should
 124  * use it as their &drm_gem_object_funcs.mmap handler.
 125  *
 126  * Returns:
 127  * 0 on success or a negative error code on failure.
 128  */
 129 static inline int drm_gem_dma_object_mmap(struct drm_gem_object *obj, struct vm_area_struct *vma)
 130 {
 131         struct drm_gem_dma_object *dma_obj = to_drm_gem_dma_obj(obj);
 132
 133         return drm_gem_dma_mmap(dma_obj, vma);
 134 }
 135
 136 /*
 137  * Driver ops
 138  */
 139
 140 /* create memory region for DRM framebuffer */
 141 int drm_gem_dma_dumb_create_internal(struct drm_file *file_priv,
 142                                      struct drm_device *drm,
 143                                      struct drm_mode_create_dumb *args);
 144
 145 /* create memory region for DRM framebuffer */
 146 int drm_gem_dma_dumb_create(struct drm_file *file_priv,
 147                             struct drm_device *drm,
 148                             struct drm_mode_create_dumb *args);
 149
 150 struct drm_gem_object *
 151 drm_gem_dma_prime_import_sg_table(struct drm_device *dev,
 152                                   struct dma_buf_attachment *attach,
 153                                   struct sg_table *sgt);
 154
 155 /**
 156  * DRM_GEM_DMA_DRIVER_OPS_WITH_DUMB_CREATE - DMA GEM driver operations
 157  * @dumb_create_func: callback function for .dumb_create
 158  *
 159  * This macro provides a shortcut for setting the default GEM operations in the
 160  * &drm_driver structure.
 161  *
 162  * This macro is a variant of DRM_GEM_DMA_DRIVER_OPS for drivers that
 163  * override the default implementation of &struct rm_driver.dumb_create. Use
 164  * DRM_GEM_DMA_DRIVER_OPS if possible. Drivers that require a virtual address
 165  * on imported buffers should use
 166  * DRM_GEM_DMA_DRIVER_OPS_VMAP_WITH_DUMB_CREATE() instead.
 167  */
 168 #define DRM_GEM_DMA_DRIVER_OPS_WITH_DUMB_CREATE(dumb_create_func) \
 169         .dumb_create               = (dumb_create_func), \
 170         .gem_prime_import_sg_table = drm_gem_dma_prime_import_sg_table
 171
 172 /**
 173  * DRM_GEM_DMA_DRIVER_OPS - DMA GEM driver operations
 174  *
 175  * This macro provides a shortcut for setting the default GEM operations in the
 176  * &drm_driver structure.
 177  *
 178  * Drivers that come with their own implementation of
 179  * &struct drm_driver.dumb_create should use
 180  * DRM_GEM_DMA_DRIVER_OPS_WITH_DUMB_CREATE() instead. Use
 181  * DRM_GEM_DMA_DRIVER_OPS if possible. Drivers that require a virtual address
 182  * on imported buffers should use DRM_GEM_DMA_DRIVER_OPS_VMAP instead.
 183  */
 184 #define DRM_GEM_DMA_DRIVER_OPS \
 185         DRM_GEM_DMA_DRIVER_OPS_WITH_DUMB_CREATE(drm_gem_dma_dumb_create)
 186
 187 /**
 188  * DRM_GEM_DMA_DRIVER_OPS_VMAP_WITH_DUMB_CREATE - DMA GEM driver operations
 189  *                                                ensuring a virtual address
 190  *                                                on the buffer
 191  * @dumb_create_func: callback function for .dumb_create
 192  *
 193  * This macro provides a shortcut for setting the default GEM operations in the
 194  * &drm_driver structure for drivers that need the virtual address also on
 195  * imported buffers.
 196  *
 197  * This macro is a variant of DRM_GEM_DMA_DRIVER_OPS_VMAP for drivers that
 198  * override the default implementation of &struct drm_driver.dumb_create. Use
 199  * DRM_GEM_DMA_DRIVER_OPS_VMAP if possible. Drivers that do not require a
 200  * virtual address on imported buffers should use
 201  * DRM_GEM_DMA_DRIVER_OPS_WITH_DUMB_CREATE() instead.
 202  */
 203 #define DRM_GEM_DMA_DRIVER_OPS_VMAP_WITH_DUMB_CREATE(dumb_create_func) \
 204         .dumb_create               = (dumb_create_func), \
 205         .gem_prime_import_sg_table = drm_gem_dma_prime_import_sg_table_vmap
 206
 207 /**
 208  * DRM_GEM_DMA_DRIVER_OPS_VMAP - DMA GEM driver operations ensuring a virtual
 209  *                               address on the buffer
 210  *
 211  * This macro provides a shortcut for setting the default GEM operations in the
 212  * &drm_driver structure for drivers that need the virtual address also on
 213  * imported buffers.
 214  *
 215  * Drivers that come with their own implementation of
 216  * &struct drm_driver.dumb_create should use
 217  * DRM_GEM_DMA_DRIVER_OPS_VMAP_WITH_DUMB_CREATE() instead. Use
 218  * DRM_GEM_DMA_DRIVER_OPS_VMAP if possible. Drivers that do not require a
 219  * virtual address on imported buffers should use DRM_GEM_DMA_DRIVER_OPS
 220  * instead.
 221  */
 222 #define DRM_GEM_DMA_DRIVER_OPS_VMAP \
 223         DRM_GEM_DMA_DRIVER_OPS_VMAP_WITH_DUMB_CREATE(drm_gem_dma_dumb_create)
 224
 225 struct drm_gem_object *
 226 drm_gem_dma_prime_import_sg_table_vmap(struct drm_device *drm,
 227                                        struct dma_buf_attachment *attach,
 228                                        struct sg_table *sgt);
 229
 230 /*
 231  * File ops
 232  */
 233
 234 #ifndef CONFIG_MMU
 235 unsigned long drm_gem_dma_get_unmapped_area(struct file *filp,
 236                                             unsigned long addr,
 237                                             unsigned long len,
 238                                             unsigned long pgoff,
 239                                             unsigned long flags);
 240 #define DRM_GEM_DMA_UNMAPPED_AREA_FOPS \
 241         .get_unmapped_area      = drm_gem_dma_get_unmapped_area,
 242 #else
 243 #define DRM_GEM_DMA_UNMAPPED_AREA_FOPS
 244 #endif
 245
 246 /**
 247  * DEFINE_DRM_GEM_DMA_FOPS() - macro to generate file operations for DMA drivers
 248  * @name: name for the generated structure
 249  *
 250  * This macro autogenerates a suitable &struct file_operations for DMA based
 251  * drivers, which can be assigned to &drm_driver.fops. Note that this structure
 252  * cannot be shared between drivers, because it contains a reference to the
 253  * current module using THIS_MODULE.
 254  *
 255  * Note that the declaration is already marked as static - if you need a
 256  * non-static version of this you're probably doing it wrong and will break the
 257  * THIS_MODULE reference by accident.
 258  */
 259 #define DEFINE_DRM_GEM_DMA_FOPS(name) \
 260         static const struct file_operations name = {\
 261                 .owner          = THIS_MODULE,\
 262                 .open           = drm_open,\
 263                 .release        = drm_release,\
 264                 .unlocked_ioctl = drm_ioctl,\
 265                 .compat_ioctl   = drm_compat_ioctl,\
 266                 .poll           = drm_poll,\
 267                 .read           = drm_read,\
 268                 .llseek         = noop_llseek,\
 269                 .mmap           = drm_gem_mmap,\
 270                 DRM_GEM_DMA_UNMAPPED_AREA_FOPS \
 271         }
 272
 273 #endif /* __DRM_GEM_DMA_HELPER_H__ */