On Wed, Jul 13, 2022 at 09:12:25AM +0100, Mauro Carvalho Chehab wrote: > This is a large struct used to describe gem objects. It is > currently partially documented. Finish its documentation, filling > the gaps from git logs. > > Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx> Reviewed-by: Rodrigo Vivi <rodrigo.vivi@xxxxxxxxx> > --- > > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. > See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@xxxxxxxxxx/ > > .../gpu/drm/i915/gem/i915_gem_object_types.h | 200 ++++++++++++++---- > 1 file changed, 158 insertions(+), 42 deletions(-) > > diff --git a/drivers/gpu/drm/i915/gem/i915_gem_object_types.h b/drivers/gpu/drm/i915/gem/i915_gem_object_types.h > index ceed0d220ce3..8c09e493590d 100644 > --- a/drivers/gpu/drm/i915/gem/i915_gem_object_types.h > +++ b/drivers/gpu/drm/i915/gem/i915_gem_object_types.h > @@ -233,6 +233,9 @@ struct i915_gem_object_page_iter { > struct mutex lock; /* protects this cache */ > }; > > +/** > + * struct drm_i915_gem_object - describes an i915 GEM object > + */ > struct drm_i915_gem_object { > /* > * We might have reason to revisit the below since it wastes > @@ -241,12 +244,16 @@ struct drm_i915_gem_object { > * when accessing it. > */ > union { > + /** @base: GEM base object */ > struct drm_gem_object base; > + /** @__do_not_access: TTM buffer object */ > struct ttm_buffer_object __do_not_access; > }; > > + /** @ops: pointer to GEM object ops */ > const struct drm_i915_gem_object_ops *ops; > > + /** @vma: struct containing VMA list, tree and lock */ > struct { > /** > * @vma.lock: protect the list/tree of vmas > @@ -280,10 +287,12 @@ struct drm_i915_gem_object { > * > * If this object is closed, we need to remove all of its VMA from > * the fast lookup index in associated contexts; @lut_list provides > - * this translation from object to context->handles_vma. > + * this translation from object to ``context->handles_vma``. > */ > struct list_head lut_list; > - spinlock_t lut_lock; /* guards lut_list */ > + > + /** @lut_lock: guards @lut_list */ > + spinlock_t lut_lock; > > /** > * @obj_link: Link into @i915_gem_ww_ctx.obj_list > @@ -294,42 +303,88 @@ struct drm_i915_gem_object { > */ > struct list_head obj_link; > /** > - * @shared_resv_from: The object shares the resv from this vm. > + * @shares_resv_from: The object shares the resv from this vm. > */ > struct i915_address_space *shares_resv_from; > > union { > + /** @rcu: head used when freeing objects with RCU */ > struct rcu_head rcu; > + /** @freed: list of GEM freed objects */ > struct llist_node freed; > }; > > /** > - * Whether the object is currently in the GGTT mmap. > + * @userfault_count: a value bigger than zero means that the object > + * was mmapped into userspace. > + * > + * Used when the object is currently in the GGTT mmap. > */ > unsigned int userfault_count; > + /** > + * @userfault_link: list of all objects that were > + * mmapped into userspace. > + * > + * Used when the object is currently in the GGTT mmap. > + */ > struct list_head userfault_link; > > + /** @mmo: struct containing mmo offsets and lock */ > struct { > - spinlock_t lock; /* Protects access to mmo offsets */ > + /** @mmo.lock: protects access to @mmo.offsets */ > + spinlock_t lock; > + /** @mmo.offsets: rbtree list of mmo offsets */ > struct rb_root offsets; > } mmo; > > + /* private: used on selftest only */ > I915_SELFTEST_DECLARE(struct list_head st_link); > + /* public: */ > > + /** > + * @flags: object flags. Current flags are: > + * > + * %I915_BO_ALLOC_CONTIGUOUS: > + * Object requires to be allocated as a contiguous block > + * %I915_BO_ALLOC_VOLATILE: > + * Volatile objects are marked as %DONTNEED while pinned, therefore > + * once unpinned the backing store can be discarded. > + * This is limited to kernel internal objects. > + * %I915_BO_ALLOC_CPU_CLEAR: > + * Some internal device local-memory objects may have an option > + * to CPU clear the pages upon gathering the backing store. > + * Note that this might be before the blitter is usable, which > + * is the case for some internal GuC objects. > + * %I915_BO_ALLOC_USER: > + * Make sure the object is cleared before any user access. > + * %I915_BO_ALLOC_PM_VOLATILE: > + * Object is allowed to lose its contents on suspend / resume, > + * even if pinned > + * %I915_BO_ALLOC_PM_EARLY: > + * Object needs to be restored early using memcpy during resume > + * %I915_BO_ALLOC_GPU_ONLY: > + * Object is likely never accessed by the CPU. This will > + * prioritise the BO to be allocated in the non-mappable portion > + * of lmem. This is merely a hint, and if dealing with userspace > + * objects the CPU fault handler is free to ignore this. > + * %I915_BO_READONLY: > + * User has created object as read-only > + * %I915_BO_PROTECTED: > + * User has created protected. All protected objects and > + * contexts will be considered invalid when the PXP session > + * is destroyed and all new submissions using them will be > + * rejected. All intel contexts within the invalidated gem > + * contexts will be marked banned. Userspace can detect that > + * an invalidation has occurred via the %RESET_STATS ioctl, > + * where we report it the same way as a ban due to a hang. > + */ > unsigned long flags; > #define I915_BO_ALLOC_CONTIGUOUS BIT(0) > #define I915_BO_ALLOC_VOLATILE BIT(1) > #define I915_BO_ALLOC_CPU_CLEAR BIT(2) > #define I915_BO_ALLOC_USER BIT(3) > -/* Object is allowed to lose its contents on suspend / resume, even if pinned */ > #define I915_BO_ALLOC_PM_VOLATILE BIT(4) > -/* Object needs to be restored early using memcpy during resume */ > #define I915_BO_ALLOC_PM_EARLY BIT(5) > -/* > - * Object is likely never accessed by the CPU. This will prioritise the BO to be > - * allocated in the non-mappable portion of lmem. This is merely a hint, and if > - * dealing with userspace objects the CPU fault handler is free to ignore this. > - */ > #define I915_BO_ALLOC_GPU_ONLY BIT(6) > #define I915_BO_ALLOC_FLAGS (I915_BO_ALLOC_CONTIGUOUS | \ > I915_BO_ALLOC_VOLATILE | \ > @@ -343,15 +398,21 @@ struct drm_i915_gem_object { > #define I915_BO_PROTECTED BIT(9) > #define I915_BO_WAS_BOUND_BIT 10 > /** > - * @mem_flags - Mutable placement-related flags > + * @mem_flags: Mutable placement-related flags > * > * These are flags that indicate specifics of the memory region > * the object is currently in. As such they are only stable > * either under the object lock or if the object is pinned. > + * There are two flags: > + * > + * %I915_BO_FLAG_STRUCT_PAGE: > + * Object backed by struct pages > + * %I915_BO_FLAG_IOMEM: > + * Object backed by IO memory > */ > unsigned int mem_flags; > -#define I915_BO_FLAG_STRUCT_PAGE BIT(0) /* Object backed by struct pages */ > -#define I915_BO_FLAG_IOMEM BIT(1) /* Object backed by IO memory */ > +#define I915_BO_FLAG_STRUCT_PAGE BIT(0) > +#define I915_BO_FLAG_IOMEM BIT(1) > /** > * @cache_level: The desired GTT caching level. > * > @@ -400,7 +461,7 @@ struct drm_i915_gem_object { > * > * Supported values: > * > - * I915_BO_CACHE_COHERENT_FOR_READ: > + * %I915_BO_CACHE_COHERENT_FOR_READ: > * > * On shared LLC platforms, we use this for special scanout surfaces, > * where the display engine is not coherent with the CPU cache. As such > @@ -423,7 +484,7 @@ struct drm_i915_gem_object { > * > * cache_coherent = 0 > * > - * I915_BO_CACHE_COHERENT_FOR_WRITE: > + * %I915_BO_CACHE_COHERENT_FOR_WRITE: > * > * When writing through the CPU cache, the GPU is still coherent. Note > * that this also implies I915_BO_CACHE_COHERENT_FOR_READ. > @@ -509,23 +570,29 @@ struct drm_i915_gem_object { > */ > u16 write_domain; > > + /** @frontbuffer: pointer to the object's frontbuffer */ > struct intel_frontbuffer __rcu *frontbuffer; > > - /** Current tiling stride for the object, if it's tiled. */ > + /** > + * @tiling_and_stride: current tiling stride for the object, > + * if it's tiled. > + */ > unsigned int tiling_and_stride; > #define FENCE_MINIMUM_STRIDE 128 /* See i915_tiling_ok() */ > #define TILING_MASK (FENCE_MINIMUM_STRIDE - 1) > #define STRIDE_MASK (~TILING_MASK) > > + /** @mm: struct containing mm-specific fields */ > struct { > - /* > - * Protects the pages and their use. Do not use directly, but > - * instead go through the pin/unpin interfaces. > + /** > + * @mm.pages_pin_count: protects the pages and their use. Do > + * not use directly, but instead go through the pin/unpin > + * interfaces. > */ > atomic_t pages_pin_count; > > /** > - * @shrink_pin: Prevents the pages from being made visible to > + * @mm.shrink_pin: Prevents the pages from being made visible to > * the shrinker, while the shrink_pin is non-zero. Most users > * should pretty much never have to care about this, outside of > * some special use cases. > @@ -536,7 +603,7 @@ struct drm_i915_gem_object { > * __i915_gem_object_set_pages(). They will then be removed the > * shrinker list once the pages are released. > * > - * The @shrink_pin is incremented by calling > + * The @mm.shrink_pin is incremented by calling > * i915_gem_object_make_unshrinkable(), which will also remove > * the object from the shrinker list, if the pin count was zero. > * > @@ -548,13 +615,13 @@ struct drm_i915_gem_object { > atomic_t shrink_pin; > > /** > - * @ttm_shrinkable: True when the object is using shmem pages > + * @mm.ttm_shrinkable: True when the object is using shmem pages > * underneath. Protected by the object lock. > */ > bool ttm_shrinkable; > > /** > - * @unknown_state: Indicate that the object is effectively > + * @mm.unknown_state: Indicate that the object is effectively > * borked. This is write-once and set if we somehow encounter a > * fatal error when moving/clearing the pages, and we are not > * able to fallback to memcpy/memset, like on small-BAR systems. > @@ -572,94 +639,143 @@ struct drm_i915_gem_object { > bool unknown_state; > > /** > - * Priority list of potential placements for this object. > + * @mm.placements: priority list of potential placements for > + * this object. > */ > struct intel_memory_region **placements; > + /** > + * @mm.n_placements: Size of @mm.placements. > + */ > int n_placements; > > /** > - * Memory region for this object. > + * @mm.region: memory region for this object. > */ > struct intel_memory_region *region; > > /** > - * Memory manager resource allocated for this object. Only > - * needed for the mock region. > + * @mm.res: Memory manager resource allocated for this object. > + * Only needed for the mock region. > */ > struct ttm_resource *res; > > /** > - * Element within memory_region->objects or region->purgeable > - * if the object is marked as DONTNEED. Access is protected by > - * region->obj_lock. > + * @mm.region_link: element within memory_region->objects or > + * ``region->purgeable`` if the object is marked as %DONTNEED. > + * Access is protected by ``region->obj_lock``. > */ > struct list_head region_link; > > + /** @mm.rsgt: refcounted sg-tables */ > struct i915_refct_sgt *rsgt; > + /** @mm.pages: pages pointer for GGTT entries */ > struct sg_table *pages; > + /** > + * @mm.mapping: mapped pages of the object into kernel space. > + * can be %NULL if unmapped. > + */ > void *mapping; > > + /** > + * @mm.page_sizes: Page sizes of the pages. > + */ > struct i915_page_sizes page_sizes; > > + /* private: used on selftest only */ > I915_SELFTEST_DECLARE(unsigned int page_mask); > + /* public: */ > > + /** @mm.get_page: */ > struct i915_gem_object_page_iter get_page; > + /** @mm.get_dma_page: */ > struct i915_gem_object_page_iter get_dma_page; > > /** > - * Element within i915->mm.shrink_list or i915->mm.purge_list, > - * locked by i915->mm.obj_lock. > + * @mm.link: element within ``i915->mm.shrink_list`` or > + * ``i915->mm.purge_list``, locked by ``i915->mm.obj_lock``. > */ > struct list_head link; > > /** > - * Advice: are the backing pages purgeable? > + * @mm.madv: Advice: are the backing pages purgeable? > */ > unsigned int madv:2; > > /** > - * This is set if the object has been written to since the > - * pages were last acquired. > + * @mm.dirty: this is set if the object has been written to > + * since the pages were last acquired. > */ > bool dirty:1; > } mm; > > + /** @ttm: struct containing TTM specific fields */ > struct { > + /** @ttm.cached_io_rsgt: cached refcounted sg-tables */ > struct i915_refct_sgt *cached_io_rsgt; > + /** @ttm.get_io_page: rbtree iterator to get IO pages */ > struct i915_gem_object_page_iter get_io_page; > + /** @ttm.backup: list of LMEM objects backed up at suspend */ > struct drm_i915_gem_object *backup; > + /** @ttm.created: indicate that object as created with TTM */ > bool created:1; > } ttm; > > - /* > - * Record which PXP key instance this object was created against (if > - * any), so we can use it to determine if the encryption is valid by > - * comparing against the current key instance. > + /** > + * @pxp_key_instance: rRecord which PXP key instance this object was > + * created against (if any), so we can use it to determine if the > + * encryption is valid by comparing against the current key instance. > */ > u32 pxp_key_instance; > > - /** Record of address bit 17 of each page at last unbind. */ > + /** @bit_17: Record of address bit 17 of each page at last unbind. */ > unsigned long *bit_17; > > union { > #ifdef CONFIG_MMU_NOTIFIER > + /** > + * @userptr: Struct which supports userptr data > + * Only used when %CONFIG_MMU_NOTIFIER is enabled > + */ > struct i915_gem_userptr { > + /** @userptr.ptr: pointer to the user-mapped ptr */ > uintptr_t ptr; > + /** @userptr.notifier_seq: */ > unsigned long notifier_seq; > > + /** @userptr.notifier: data used by MMU notifier */ > struct mmu_interval_notifier notifier; > + /** @userptr.pvec: S/G pages used by userptr */ > struct page **pvec; > + /** > + * @userptr.page_ref: number of page references > + * incremented when pages are in usage. > + * > + */ > int page_ref; > } userptr; > #endif > > + /** > + * @stolen: Used to identify an object allocated from > + * stolen memory. > + */ > struct drm_mm_node *stolen; > > + /** > + * @bo_offset: The range start. > + * Used only by TTM. > + */ > resource_size_t bo_offset; > > + /** @scratch: physical size of huge gem object */ > unsigned long scratch; > + /** @encode: gen8 PDE encode address */ > u64 encode; > > + /** > + * @gvt_info: contains a pointer to ``dmabuf_obj->info`` > + * Used only by gvt. > + */ > void *gvt_info; > }; > }; > -- > 2.36.1 >
