Commit e25d1ea4 authored by Matthew Auld's avatar Matthew Auld
Browse files

drm/i915: add some kernel-doc for shrink_pin and friends 



Attempt to document shrink_pin and the other relevant interfaces that
interact with it, before we start messing with it.

Signed-off-by: default avatarMatthew Auld <matthew.auld@intel.com>
Cc: Thomas Hellström <thomas.hellstrom@linux.intel.com>
Reviewed-by: default avatarThomas Hellström <thomas.hellstrom@linux.intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20211018091055.1998191-5-matthew.auld@intel.com
parent 893f11f0

drivers/gpu/drm/i915/gem/i915_gem_object_types.h

+23 −1
Original line number Diff line number Diff line
@@ -488,6 +488,28 @@ struct drm_i915_gem_object { 
		 * instead go through the pin/unpin interfaces.

		 */

		atomic_t pages_pin_count;



		/**

		 * @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.

		 *

		 * By default most objects will start out as visible to the

		 * shrinker(if I915_GEM_OBJECT_IS_SHRINKABLE) as soon as the

		 * backing pages are attached to the object, like in

		 * __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

		 * i915_gem_object_make_unshrinkable(), which will also remove

		 * the object from the shrinker list, if the pin count was zero.

		 *

		 * Callers will then typically call

		 * i915_gem_object_make_shrinkable() or

		 * i915_gem_object_make_purgeable() to decrement the pin count,

		 * and make the pages visible again.

		 */

		atomic_t shrink_pin;



		/**
@@ -549,7 +571,7 @@ struct drm_i915_gem_object { 
		struct i915_gem_object_page_iter get_dma_page;



		/**

		 * Element within i915->mm.unbound_list or i915->mm.bound_list,

		 * Element within i915->mm.shrink_list or i915->mm.purge_list,

		 * locked by i915->mm.obj_lock.

		 */

		struct list_head link;

drivers/gpu/drm/i915/gem/i915_gem_shrinker.c

+31 −0
Original line number Diff line number Diff line
@@ -463,6 +463,16 @@ void i915_gem_shrinker_taints_mutex(struct drm_i915_private *i915, 


#define obj_to_i915(obj__) to_i915((obj__)->base.dev)



/**

 * i915_gem_object_make_unshrinkable - Hide the object from the shrinker. By

 * default all object types that support shrinking(see IS_SHRINKABLE), will also

 * make the object visible to the shrinker after allocating the system memory

 * pages.

 * @obj: The GEM object.

 *

 * This is typically used for special kernel internal objects that can't be

 * easily processed by the shrinker, like if they are perma-pinned.

 */

void i915_gem_object_make_unshrinkable(struct drm_i915_gem_object *obj)

{

	struct drm_i915_private *i915 = obj_to_i915(obj);
@@ -513,12 +523,33 @@ static void __i915_gem_object_make_shrinkable(struct drm_i915_gem_object *obj, 
	spin_unlock_irqrestore(&i915->mm.obj_lock, flags);

}



/**

 * i915_gem_object_make_shrinkable - Move the object to the tail of the

 * shrinkable list. Objects on this list might be swapped out. Used with

 * WILLNEED objects.

 * @obj: The GEM object.

 *

 * MUST only be called on objects which have backing pages.

 *

 * MUST be balanced with previous call to i915_gem_object_make_unshrinkable().

 */

void i915_gem_object_make_shrinkable(struct drm_i915_gem_object *obj)

{

	__i915_gem_object_make_shrinkable(obj,

					  &obj_to_i915(obj)->mm.shrink_list);

}



/**

 * i915_gem_object_make_purgeable - Move the object to the tail of the purgeable

 * list. Used with DONTNEED objects. Unlike with shrinkable objects, the

 * shrinker will attempt to discard the backing pages, instead of trying to swap

 * them out.

 * @obj: The GEM object.

 *

 * MUST only be called on objects which have backing pages.

 *

 * MUST be balanced with previous call to i915_gem_object_make_unshrinkable().

 */

void i915_gem_object_make_purgeable(struct drm_i915_gem_object *obj)

{

	__i915_gem_object_make_shrinkable(obj,