include/drm/drm_gem.h

   1 #ifndef __DRM_GEM_H__
   2 #define __DRM_GEM_H__
   3
   4 /*
   5  * GEM Graphics Execution Manager Driver Interfaces
   6  *
   7  * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas.
   8  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
   9  * Copyright (c) 2009-2010, Code Aurora Forum.
  10  * All rights reserved.
  11  * Copyright © 2014 Intel Corporation
  12  *   Daniel Vetter <daniel.vetter@ffwll.ch>
  13  *
  14  * Author: Rickard E. (Rik) Faith <faith@valinux.com>
  15  * Author: Gareth Hughes <gareth@valinux.com>
  16  *
  17  * Permission is hereby granted, free of charge, to any person obtaining a
  18  * copy of this software and associated documentation files (the "Software"),
  19  * to deal in the Software without restriction, including without limitation
  20  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  21  * and/or sell copies of the Software, and to permit persons to whom the
  22  * Software is furnished to do so, subject to the following conditions:
  23  *
  24  * The above copyright notice and this permission notice (including the next
  25  * paragraph) shall be included in all copies or substantial portions of the
  26  * Software.
  27  *
  28  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  29  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  30  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  31  * VA LINUX SYSTEMS AND/OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
  32  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  33  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  34  * OTHER DEALINGS IN THE SOFTWARE.
  35  */
  36
  37 #include <linux/kref.h>
  38 #include <linux/dma-resv.h>
  39 #include <linux/list.h>
  40 #include <linux/mutex.h>
  41
  42 #include <drm/drm_vma_manager.h>
  43
  44 struct iosys_map;
  45 struct drm_gem_object;
  46
  47 /**
  48  * enum drm_gem_object_status - bitmask of object state for fdinfo reporting
  49  * @DRM_GEM_OBJECT_RESIDENT: object is resident in memory (ie. not unpinned)
  50  * @DRM_GEM_OBJECT_PURGEABLE: object marked as purgeable by userspace
  51  *
  52  * Bitmask of status used for fdinfo memory stats, see &drm_gem_object_funcs.status
  53  * and drm_show_fdinfo().  Note that an object can DRM_GEM_OBJECT_PURGEABLE if
  54  * it still active or not resident, in which case drm_show_fdinfo() will not
  55  * account for it as purgeable.  So drivers do not need to check if the buffer
  56  * is idle and resident to return this bit.  (Ie. userspace can mark a buffer
  57  * as purgeable even while it is still busy on the GPU.. it does not _actually_
  58  * become puregeable until it becomes idle.  The status gem object func does
  59  * not need to consider this.)
  60  */
  61 enum drm_gem_object_status {
  62         DRM_GEM_OBJECT_RESIDENT  = BIT(0),
  63         DRM_GEM_OBJECT_PURGEABLE = BIT(1),
  64 };
  65
  66 /**
  67  * struct drm_gem_object_funcs - GEM object functions
  68  */
  69 struct drm_gem_object_funcs {
  70         /**
  71          * @free:
  72          *
  73          * Deconstructor for drm_gem_objects.
  74          *
  75          * This callback is mandatory.
  76          */
  77         void (*free)(struct drm_gem_object *obj);
  78
  79         /**
  80          * @open:
  81          *
  82          * Called upon GEM handle creation.
  83          *
  84          * This callback is optional.
  85          */
  86         int (*open)(struct drm_gem_object *obj, struct drm_file *file);
  87
  88         /**
  89          * @close:
  90          *
  91          * Called upon GEM handle release.
  92          *
  93          * This callback is optional.
  94          */
  95         void (*close)(struct drm_gem_object *obj, struct drm_file *file);
  96
  97         /**
  98          * @print_info:
  99          *
 100          * If driver subclasses struct &drm_gem_object, it can implement this
 101          * optional hook for printing additional driver specific info.
 102          *
 103          * drm_printf_indent() should be used in the callback passing it the
 104          * indent argument.
 105          *
 106          * This callback is called from drm_gem_print_info().
 107          *
 108          * This callback is optional.
 109          */
 110         void (*print_info)(struct drm_printer *p, unsigned int indent,
 111                            const struct drm_gem_object *obj);
 112
 113         /**
 114          * @export:
 115          *
 116          * Export backing buffer as a &dma_buf.
 117          * If this is not set drm_gem_prime_export() is used.
 118          *
 119          * This callback is optional.
 120          */
 121         struct dma_buf *(*export)(struct drm_gem_object *obj, int flags);
 122
 123         /**
 124          * @pin:
 125          *
 126          * Pin backing buffer in memory. Used by the drm_gem_map_attach() helper.
 127          *
 128          * This callback is optional.
 129          */
 130         int (*pin)(struct drm_gem_object *obj);
 131
 132         /**
 133          * @unpin:
 134          *
 135          * Unpin backing buffer. Used by the drm_gem_map_detach() helper.
 136          *
 137          * This callback is optional.
 138          */
 139         void (*unpin)(struct drm_gem_object *obj);
 140
 141         /**
 142          * @get_sg_table:
 143          *
 144          * Returns a Scatter-Gather table representation of the buffer.
 145          * Used when exporting a buffer by the drm_gem_map_dma_buf() helper.
 146          * Releasing is done by calling dma_unmap_sg_attrs() and sg_free_table()
 147          * in drm_gem_unmap_buf(), therefore these helpers and this callback
 148          * here cannot be used for sg tables pointing at driver private memory
 149          * ranges.
 150          *
 151          * See also drm_prime_pages_to_sg().
 152          */
 153         struct sg_table *(*get_sg_table)(struct drm_gem_object *obj);
 154
 155         /**
 156          * @vmap:
 157          *
 158          * Returns a virtual address for the buffer. Used by the
 159          * drm_gem_dmabuf_vmap() helper.
 160          *
 161          * This callback is optional.
 162          */
 163         int (*vmap)(struct drm_gem_object *obj, struct iosys_map *map);
 164
 165         /**
 166          * @vunmap:
 167          *
 168          * Releases the address previously returned by @vmap. Used by the
 169          * drm_gem_dmabuf_vunmap() helper.
 170          *
 171          * This callback is optional.
 172          */
 173         void (*vunmap)(struct drm_gem_object *obj, struct iosys_map *map);
 174
 175         /**
 176          * @mmap:
 177          *
 178          * Handle mmap() of the gem object, setup vma accordingly.
 179          *
 180          * This callback is optional.
 181          *
 182          * The callback is used by both drm_gem_mmap_obj() and
 183          * drm_gem_prime_mmap().  When @mmap is present @vm_ops is not
 184          * used, the @mmap callback must set vma->vm_ops instead.
 185          */
 186         int (*mmap)(struct drm_gem_object *obj, struct vm_area_struct *vma);
 187
 188         /**
 189          * @evict:
 190          *
 191          * Evicts gem object out from memory. Used by the drm_gem_object_evict()
 192          * helper. Returns 0 on success, -errno otherwise.
 193          *
 194          * This callback is optional.
 195          */
 196         int (*evict)(struct drm_gem_object *obj);
 197
 198         /**
 199          * @status:
 200          *
 201          * The optional status callback can return additional object state
 202          * which determines which stats the object is counted against.  The
 203          * callback is called under table_lock.  Racing against object status
 204          * change is "harmless", and the callback can expect to not race
 205          * against object destruction.
 206          *
 207          * Called by drm_show_memory_stats().
 208          */
 209         enum drm_gem_object_status (*status)(struct drm_gem_object *obj);
 210
 211         /**
 212          * @vm_ops:
 213          *
 214          * Virtual memory operations used with mmap.
 215          *
 216          * This is optional but necessary for mmap support.
 217          */
 218         const struct vm_operations_struct *vm_ops;
 219 };
 220
 221 /**
 222  * struct drm_gem_lru - A simple LRU helper
 223  *
 224  * A helper for tracking GEM objects in a given state, to aid in
 225  * driver's shrinker implementation.  Tracks the count of pages
 226  * for lockless &shrinker.count_objects, and provides
 227  * &drm_gem_lru_scan for driver's &shrinker.scan_objects
 228  * implementation.
 229  */
 230 struct drm_gem_lru {
 231         /**
 232          * @lock:
 233          *
 234          * Lock protecting movement of GEM objects between LRUs.  All
 235          * LRUs that the object can move between should be protected
 236          * by the same lock.
 237          */
 238         struct mutex *lock;
 239
 240         /**
 241          * @count:
 242          *
 243          * The total number of backing pages of the GEM objects in
 244          * this LRU.
 245          */
 246         long count;
 247
 248         /**
 249          * @list:
 250          *
 251          * The LRU list.
 252          */
 253         struct list_head list;
 254 };
 255
 256 /**
 257  * struct drm_gem_object - GEM buffer object
 258  *
 259  * This structure defines the generic parts for GEM buffer objects, which are
 260  * mostly around handling mmap and userspace handles.
 261  *
 262  * Buffer objects are often abbreviated to BO.
 263  */
 264 struct drm_gem_object {
 265         /**
 266          * @refcount:
 267          *
 268          * Reference count of this object
 269          *
 270          * Please use drm_gem_object_get() to acquire and drm_gem_object_put_locked()
 271          * or drm_gem_object_put() to release a reference to a GEM
 272          * buffer object.
 273          */
 274         struct kref refcount;
 275
 276         /**
 277          * @handle_count:
 278          *
 279          * This is the GEM file_priv handle count of this object.
 280          *
 281          * Each handle also holds a reference. Note that when the handle_count
 282          * drops to 0 any global names (e.g. the id in the flink namespace) will
 283          * be cleared.
 284          *
 285          * Protected by &drm_device.object_name_lock.
 286          */
 287         unsigned handle_count;
 288
 289         /**
 290          * @dev: DRM dev this object belongs to.
 291          */
 292         struct drm_device *dev;
 293
 294         /**
 295          * @filp:
 296          *
 297          * SHMEM file node used as backing storage for swappable buffer objects.
 298          * GEM also supports driver private objects with driver-specific backing
 299          * storage (contiguous DMA memory, special reserved blocks). In this
 300          * case @filp is NULL.
 301          */
 302         struct file *filp;
 303
 304         /**
 305          * @vma_node:
 306          *
 307          * Mapping info for this object to support mmap. Drivers are supposed to
 308          * allocate the mmap offset using drm_gem_create_mmap_offset(). The
 309          * offset itself can be retrieved using drm_vma_node_offset_addr().
 310          *
 311          * Memory mapping itself is handled by drm_gem_mmap(), which also checks
 312          * that userspace is allowed to access the object.
 313          */
 314         struct drm_vma_offset_node vma_node;
 315
 316         /**
 317          * @size:
 318          *
 319          * Size of the object, in bytes.  Immutable over the object's
 320          * lifetime.
 321          */
 322         size_t size;
 323
 324         /**
 325          * @name:
 326          *
 327          * Global name for this object, starts at 1. 0 means unnamed.
 328          * Access is covered by &drm_device.object_name_lock. This is used by
 329          * the GEM_FLINK and GEM_OPEN ioctls.
 330          */
 331         int name;
 332
 333         /**
 334          * @dma_buf:
 335          *
 336          * dma-buf associated with this GEM object.
 337          *
 338          * Pointer to the dma-buf associated with this gem object (either
 339          * through importing or exporting). We break the resulting reference
 340          * loop when the last gem handle for this object is released.
 341          *
 342          * Protected by &drm_device.object_name_lock.
 343          */
 344         struct dma_buf *dma_buf;
 345
 346         /**
 347          * @import_attach:
 348          *
 349          * dma-buf attachment backing this object.
 350          *
 351          * Any foreign dma_buf imported as a gem object has this set to the
 352          * attachment point for the device. This is invariant over the lifetime
 353          * of a gem object.
 354          *
 355          * The &drm_gem_object_funcs.free callback is responsible for
 356          * cleaning up the dma_buf attachment and references acquired at import
 357          * time.
 358          *
 359          * Note that the drm gem/prime core does not depend upon drivers setting
 360          * this field any more. So for drivers where this doesn't make sense
 361          * (e.g. virtual devices or a displaylink behind an usb bus) they can
 362          * simply leave it as NULL.
 363          */
 364         struct dma_buf_attachment *import_attach;
 365
 366         /**
 367          * @resv:
 368          *
 369          * Pointer to reservation object associated with the this GEM object.
 370          *
 371          * Normally (@resv == &@_resv) except for imported GEM objects.
 372          */
 373         struct dma_resv *resv;
 374
 375         /**
 376          * @_resv:
 377          *
 378          * A reservation object for this GEM object.
 379          *
 380          * This is unused for imported GEM objects.
 381          */
 382         struct dma_resv _resv;
 383
 384         /**
 385          * @gpuva:
 386          *
 387          * Provides the list of GPU VAs attached to this GEM object.
 388          *
 389          * Drivers should lock list accesses with the GEMs &dma_resv lock
 390          * (&drm_gem_object.resv) or a custom lock if one is provided.
 391          */
 392         struct {
 393                 struct list_head list;
 394
 395 #ifdef CONFIG_LOCKDEP
 396                 struct lockdep_map *lock_dep_map;
 397 #endif
 398         } gpuva;
 399
 400         /**
 401          * @funcs:
 402          *
 403          * Optional GEM object functions. If this is set, it will be used instead of the
 404          * corresponding &drm_driver GEM callbacks.
 405          *
 406          * New drivers should use this.
 407          *
 408          */
 409         const struct drm_gem_object_funcs *funcs;
 410
 411         /**
 412          * @lru_node:
 413          *
 414          * List node in a &drm_gem_lru.
 415          */
 416         struct list_head lru_node;
 417
 418         /**
 419          * @lru:
 420          *
 421          * The current LRU list that the GEM object is on.
 422          */
 423         struct drm_gem_lru *lru;
 424 };
 425
 426 /**
 427  * DRM_GEM_FOPS - Default drm GEM file operations
 428  *
 429  * This macro provides a shorthand for setting the GEM file ops in the
 430  * &file_operations structure.  If all you need are the default ops, use
 431  * DEFINE_DRM_GEM_FOPS instead.
 432  */
 433 #define DRM_GEM_FOPS \
 434         .open           = drm_open,\
 435         .release        = drm_release,\
 436         .unlocked_ioctl = drm_ioctl,\
 437         .compat_ioctl   = drm_compat_ioctl,\
 438         .poll           = drm_poll,\
 439         .read           = drm_read,\
 440         .llseek         = noop_llseek,\
 441         .mmap           = drm_gem_mmap
 442
 443 /**
 444  * DEFINE_DRM_GEM_FOPS() - macro to generate file operations for GEM drivers
 445  * @name: name for the generated structure
 446  *
 447  * This macro autogenerates a suitable &struct file_operations for GEM based
 448  * drivers, which can be assigned to &drm_driver.fops. Note that this structure
 449  * cannot be shared between drivers, because it contains a reference to the
 450  * current module using THIS_MODULE.
 451  *
 452  * Note that the declaration is already marked as static - if you need a
 453  * non-static version of this you're probably doing it wrong and will break the
 454  * THIS_MODULE reference by accident.
 455  */
 456 #define DEFINE_DRM_GEM_FOPS(name) \
 457         static const struct file_operations name = {\
 458                 .owner          = THIS_MODULE,\
 459                 DRM_GEM_FOPS,\
 460         }
 461
 462 void drm_gem_object_release(struct drm_gem_object *obj);
 463 void drm_gem_object_free(struct kref *kref);
 464 int drm_gem_object_init(struct drm_device *dev,
 465                         struct drm_gem_object *obj, size_t size);
 466 void drm_gem_private_object_init(struct drm_device *dev,
 467                                  struct drm_gem_object *obj, size_t size);
 468 void drm_gem_private_object_fini(struct drm_gem_object *obj);
 469 void drm_gem_vm_open(struct vm_area_struct *vma);
 470 void drm_gem_vm_close(struct vm_area_struct *vma);
 471 int drm_gem_mmap_obj(struct drm_gem_object *obj, unsigned long obj_size,
 472                      struct vm_area_struct *vma);
 473 int drm_gem_mmap(struct file *filp, struct vm_area_struct *vma);
 474
 475 /**
 476  * drm_gem_object_get - acquire a GEM buffer object reference
 477  * @obj: GEM buffer object
 478  *
 479  * This function acquires an additional reference to @obj. It is illegal to
 480  * call this without already holding a reference. No locks required.
 481  */
 482 static inline void drm_gem_object_get(struct drm_gem_object *obj)
 483 {
 484         kref_get(&obj->refcount);
 485 }
 486
 487 __attribute__((nonnull))
 488 static inline void
 489 __drm_gem_object_put(struct drm_gem_object *obj)
 490 {
 491         kref_put(&obj->refcount, drm_gem_object_free);
 492 }
 493
 494 /**
 495  * drm_gem_object_put - drop a GEM buffer object reference
 496  * @obj: GEM buffer object
 497  *
 498  * This releases a reference to @obj.
 499  */
 500 static inline void
 501 drm_gem_object_put(struct drm_gem_object *obj)
 502 {
 503         if (obj)
 504                 __drm_gem_object_put(obj);
 505 }
 506
 507 int drm_gem_handle_create(struct drm_file *file_priv,
 508                           struct drm_gem_object *obj,
 509                           u32 *handlep);
 510 int drm_gem_handle_delete(struct drm_file *filp, u32 handle);
 511
 512
 513 void drm_gem_free_mmap_offset(struct drm_gem_object *obj);
 514 int drm_gem_create_mmap_offset(struct drm_gem_object *obj);
 515 int drm_gem_create_mmap_offset_size(struct drm_gem_object *obj, size_t size);
 516
 517 struct page **drm_gem_get_pages(struct drm_gem_object *obj);
 518 void drm_gem_put_pages(struct drm_gem_object *obj, struct page **pages,
 519                 bool dirty, bool accessed);
 520
 521 int drm_gem_vmap_unlocked(struct drm_gem_object *obj, struct iosys_map *map);
 522 void drm_gem_vunmap_unlocked(struct drm_gem_object *obj, struct iosys_map *map);
 523
 524 int drm_gem_objects_lookup(struct drm_file *filp, void __user *bo_handles,
 525                            int count, struct drm_gem_object ***objs_out);
 526 struct drm_gem_object *drm_gem_object_lookup(struct drm_file *filp, u32 handle);
 527 long drm_gem_dma_resv_wait(struct drm_file *filep, u32 handle,
 528                                     bool wait_all, unsigned long timeout);
 529 int drm_gem_lock_reservations(struct drm_gem_object **objs, int count,
 530                               struct ww_acquire_ctx *acquire_ctx);
 531 void drm_gem_unlock_reservations(struct drm_gem_object **objs, int count,
 532                                  struct ww_acquire_ctx *acquire_ctx);
 533 int drm_gem_dumb_map_offset(struct drm_file *file, struct drm_device *dev,
 534                             u32 handle, u64 *offset);
 535
 536 void drm_gem_lru_init(struct drm_gem_lru *lru, struct mutex *lock);
 537 void drm_gem_lru_remove(struct drm_gem_object *obj);
 538 void drm_gem_lru_move_tail_locked(struct drm_gem_lru *lru, struct drm_gem_object *obj);
 539 void drm_gem_lru_move_tail(struct drm_gem_lru *lru, struct drm_gem_object *obj);
 540 unsigned long drm_gem_lru_scan(struct drm_gem_lru *lru,
 541                                unsigned int nr_to_scan,
 542                                unsigned long *remaining,
 543                                bool (*shrink)(struct drm_gem_object *obj));
 544
 545 int drm_gem_evict(struct drm_gem_object *obj);
 546
 547 #ifdef CONFIG_LOCKDEP
 548 /**
 549  * drm_gem_gpuva_set_lock() - Set the lock protecting accesses to the gpuva list.
 550  * @obj: the &drm_gem_object
 551  * @lock: the lock used to protect the gpuva list. The locking primitive
 552  * must contain a dep_map field.
 553  *
 554  * Call this if you're not proctecting access to the gpuva list with the
 555  * dma-resv lock, but with a custom lock.
 556  */
 557 #define drm_gem_gpuva_set_lock(obj, lock) \
 558         if (!WARN((obj)->gpuva.lock_dep_map, \
 559                   "GEM GPUVA lock should be set only once.")) \
 560                 (obj)->gpuva.lock_dep_map = &(lock)->dep_map
 561 #define drm_gem_gpuva_assert_lock_held(obj) \
 562         lockdep_assert((obj)->gpuva.lock_dep_map ? \
 563                        lock_is_held((obj)->gpuva.lock_dep_map) : \
 564                        dma_resv_held((obj)->resv))
 565 #else
 566 #define drm_gem_gpuva_set_lock(obj, lock) do {} while (0)
 567 #define drm_gem_gpuva_assert_lock_held(obj) do {} while (0)
 568 #endif
 569
 570 /**
 571  * drm_gem_gpuva_init() - initialize the gpuva list of a GEM object
 572  * @obj: the &drm_gem_object
 573  *
 574  * This initializes the &drm_gem_object's &drm_gpuva list.
 575  *
 576  * Calling this function is only necessary for drivers intending to support the
 577  * &drm_driver_feature DRIVER_GEM_GPUVA.
 578  *
 579  * See also drm_gem_gpuva_set_lock().
 580  */
 581 static inline void drm_gem_gpuva_init(struct drm_gem_object *obj)
 582 {
 583         INIT_LIST_HEAD(&obj->gpuva.list);
 584 }
 585
 586 /**
 587  * drm_gem_for_each_gpuva() - iternator to walk over a list of gpuvas
 588  * @entry__: &drm_gpuva structure to assign to in each iteration step
 589  * @obj__: the &drm_gem_object the &drm_gpuvas to walk are associated with
 590  *
 591  * This iterator walks over all &drm_gpuva structures associated with the
 592  * &drm_gpuva_manager.
 593  */
 594 #define drm_gem_for_each_gpuva(entry__, obj__) \
 595         list_for_each_entry(entry__, &(obj__)->gpuva.list, gem.entry)
 596
 597 /**
 598  * drm_gem_for_each_gpuva_safe() - iternator to safely walk over a list of
 599  * gpuvas
 600  * @entry__: &drm_gpuva structure to assign to in each iteration step
 601  * @next__: &next &drm_gpuva to store the next step
 602  * @obj__: the &drm_gem_object the &drm_gpuvas to walk are associated with
 603  *
 604  * This iterator walks over all &drm_gpuva structures associated with the
 605  * &drm_gem_object. It is implemented with list_for_each_entry_safe(), hence
 606  * it is save against removal of elements.
 607  */
 608 #define drm_gem_for_each_gpuva_safe(entry__, next__, obj__) \
 609         list_for_each_entry_safe(entry__, next__, &(obj__)->gpuva.list, gem.entry)
 610
 611 #endif /* __DRM_GEM_H__ */