drm/gpuvm: fix various typos in .c and .h gpuvm file

 * mapping's backing &drm_gem_object buffers.

 *

 * &drm_gem_object buffers maintain a list of &drm_gpuva objects representing

 * all existent GPU VA mappings using this &drm_gem_object as backing buffer.

 * all existing GPU VA mappings using this &drm_gem_object as backing buffer.

 *

 * GPU VAs can be flagged as sparse, such that drivers may use GPU VAs to also

 * keep track of sparse PTEs in order to support Vulkan 'Sparse Resources'.

 * but it can also be a 'dummy' object, which can be allocated with

 * drm_gpuvm_resv_object_alloc().

 *

 * In order to connect a struct drm_gpuva its backing &drm_gem_object each

 * In order to connect a struct drm_gpuva to its backing &drm_gem_object each

 * &drm_gem_object maintains a list of &drm_gpuvm_bo structures, and each

 * &drm_gpuvm_bo contains a list of &drm_gpuva structures.

 *

 * This is ensured by the API through drm_gpuvm_bo_obtain() and

 * drm_gpuvm_bo_obtain_prealloc() which first look into the corresponding

 * &drm_gem_object list of &drm_gpuvm_bos for an existing instance of this

 * particular combination. If not existent a new instance is created and linked

 * particular combination. If not present, a new instance is created and linked

 * to the &drm_gem_object.

 *

 * &drm_gpuvm_bo structures, since unique for a given &drm_gpuvm, are also used

 * sequence of operations to satisfy a given map or unmap request.

 *

 * Therefore the DRM GPU VA manager provides an algorithm implementing splitting

 * and merging of existent GPU VA mappings with the ones that are requested to

 * and merging of existing GPU VA mappings with the ones that are requested to

 * be mapped or unmapped. This feature is required by the Vulkan API to

 * implement Vulkan 'Sparse Memory Bindings' - drivers UAPIs often refer to this

 * as VM BIND.

 * execute in order to integrate the new mapping cleanly into the current state

 * of the GPU VA space.

 *

 * Depending on how the new GPU VA mapping intersects with the existent mappings

 * Depending on how the new GPU VA mapping intersects with the existing mappings

 * of the GPU VA space the &drm_gpuvm_ops callbacks contain an arbitrary amount

 * of unmap operations, a maximum of two remap operations and a single map

 * operation. The caller might receive no callback at all if no operation is

 * one unmap operation and one or two map operations, such that drivers can

 * derive the page table update delta accordingly.

 *

 * Note that there can't be more than two existent mappings to split up, one at

 * Note that there can't be more than two existing mappings to split up, one at

 * the beginning and one at the end of the new mapping, hence there is a

 * maximum of two remap operations.

 *

 * Analogous to drm_gpuvm_sm_map() drm_gpuvm_sm_unmap() uses &drm_gpuvm_ops to

 * call back into the driver in order to unmap a range of GPU VA space. The

 * logic behind this function is way simpler though: For all existent mappings

 * logic behind this function is way simpler though: For all existing mappings

 * enclosed by the given range unmap operations are created. For mappings which

 * are only partically located within the given range, remap operations are

 * created such that those mappings are split up and re-mapped partically.

 * are only partially located within the given range, remap operations are

 * created such that those mappings are split up and re-mapped partially.

 *

 * As an alternative to drm_gpuvm_sm_map() and drm_gpuvm_sm_unmap(),

 * drm_gpuvm_sm_map_ops_create() and drm_gpuvm_sm_unmap_ops_create() can be used

 * provided helper functions drm_gpuva_map(), drm_gpuva_remap() and

 * drm_gpuva_unmap() instead.

 *

 * The following diagram depicts the basic relationships of existent GPU VA

 * The following diagram depicts the basic relationships of existing GPU VA

 * mappings, a newly requested mapping and the resulting mappings as implemented

 * by drm_gpuvm_sm_map() - it doesn't cover any arbitrary combinations of these.

 *

 *

 *

 * 4) Existent mapping is a left aligned subset of the requested one, hence

 *    replace the existent one.

 *    replace the existing one.

 *

 *    ::

 *

 *       and/or non-contiguous BO offset.

 *

 *

 * 5) Requested mapping's range is a left aligned subset of the existent one,

 * 5) Requested mapping's range is a left aligned subset of the existing one,

 *    but backed by a different BO. Hence, map the requested mapping and split

 *    the existent one adjusting its BO offset.

 *    the existing one adjusting its BO offset.

 *

 *    ::

 *

 *	new: |-----|-----| (a.bo_offset=n, a'.bo_offset=n+1)

 *

 *

 * 7) Requested mapping's range is a right aligned subset of the existent one,

 * 7) Requested mapping's range is a right aligned subset of the existing one,

 *    but backed by a different BO. Hence, map the requested mapping and split

 *    the existent one, without adjusting the BO offset.

 *    the existing one, without adjusting the BO offset.

 *

 *    ::

 *

 *

 * 9) Existent mapping is overlapped at the end by the requested mapping backed

 *    by a different BO. Hence, map the requested mapping and split up the

 *    existent one, without adjusting the BO offset.

 *    existing one, without adjusting the BO offset.

 *

 *    ::

 *

 *	 new: |-----|-----------| (a'.bo_offset=n, a.bo_offset=n+1)

 *

 *

 * 11) Requested mapping's range is a centered subset of the existent one

 * 11) Requested mapping's range is a centered subset of the existing one

 *     having a different backing BO. Hence, map the requested mapping and split

 *     up the existent one in two mappings, adjusting the BO offset of the right

 *     up the existing one in two mappings, adjusting the BO offset of the right

 *     one accordingly.

 *

 *     ::

 *	 new: |-----|-----|-----| (a.bo_offset=n,b.bo_offset=m,a'.bo_offset=n+2)

 *

 *

 * 12) Requested mapping is a contiguous subset of the existent one. Split it

 * 12) Requested mapping is a contiguous subset of the existing one. Split it

 *     up, but indicate that the backing PTEs could be kept.

 *

 *     ::

 *

 *

 * 13) Existent mapping is a right aligned subset of the requested one, hence

 *     replace the existent one.

 *     replace the existing one.

 *

 *     ::

 *

 *

 *

 * 14) Existent mapping is a centered subset of the requested one, hence

 *     replace the existent one.

 *     replace the existing one.

 *

 *     ::

 *

 *

 * 15) Existent mappings is overlapped at the beginning by the requested mapping

 *     backed by a different BO. Hence, map the requested mapping and split up

 *     the existent one, adjusting its BO offset accordingly.

 *     the existing one, adjusting its BO offset accordingly.

 *

 *     ::

 *

 * make use of them.

 *

 * The below code is strictly limited to illustrate the generic usage pattern.

 * To maintain simplicitly, it doesn't make use of any abstractions for common

 * code, different (asyncronous) stages with fence signalling critical paths,

 * To maintain simplicity, it doesn't make use of any abstractions for common

 * code, different (asynchronous) stages with fence signalling critical paths,

 * any other helpers or error handling in terms of freeing memory and dropping

 * previously taken locks.

 *

 *	// Allocates a new &drm_gpuva.

 *	struct drm_gpuva * driver_gpuva_alloc(void);

 *

 *	// Typically drivers would embedd the &drm_gpuvm and &drm_gpuva

 *	// Typically drivers would embed the &drm_gpuvm and &drm_gpuva

 *	// structure in individual driver structures and lock the dma-resv with

 *	// drm_exec or similar helpers.

 *	int driver_mapping_create(struct drm_gpuvm *gpuvm,

 *		.sm_step_unmap = driver_gpuva_unmap,

 *	};

 *

 *	// Typically drivers would embedd the &drm_gpuvm and &drm_gpuva

 *	// Typically drivers would embed the &drm_gpuvm and &drm_gpuva

 *	// structure in individual driver structures and lock the dma-resv with

 *	// drm_exec or similar helpers.

 *	int driver_mapping_create(struct drm_gpuvm *gpuvm,

 *

 * This helper is here to provide lockless list iteration. Lockless as in, the

 * iterator releases the lock immediately after picking the first element from

 * the list, so list insertion deletion can happen concurrently.

 * the list, so list insertion and deletion can happen concurrently.

 *

 * Elements popped from the original list are kept in a local list, so removal

 * and is_empty checks can still happen while we're iterating the list.

}

/**

 * drm_gpuvm_prepare_objects() - prepare all assoiciated BOs

 * drm_gpuvm_prepare_objects() - prepare all associated BOs

 * @gpuvm: the &drm_gpuvm

 * @exec: the &drm_exec locking context

 * @num_fences: the amount of &dma_fences to reserve

EXPORT_SYMBOL_GPL(drm_gpuvm_prepare_range);

/**

 * drm_gpuvm_exec_lock() - lock all dma-resv of all assoiciated BOs

 * drm_gpuvm_exec_lock() - lock all dma-resv of all associated BOs

 * @vm_exec: the &drm_gpuvm_exec wrapper

 *

 * Acquires all dma-resv locks of all &drm_gem_objects the given

 * &drm_gpuvm contains mappings of.

 *

 * Addionally, when calling this function with struct drm_gpuvm_exec::extra

 * Additionally, when calling this function with struct drm_gpuvm_exec::extra

 * being set the driver receives the given @fn callback to lock additional

 * dma-resv in the context of the &drm_gpuvm_exec instance. Typically, drivers

 * would call drm_exec_prepare_obj() from within this callback.

}

/**

 * drm_gpuvm_exec_lock_array() - lock all dma-resv of all assoiciated BOs

 * drm_gpuvm_exec_lock_array() - lock all dma-resv of all associated BOs

 * @vm_exec: the &drm_gpuvm_exec wrapper

 * @objs: additional &drm_gem_objects to lock

 * @num_objs: the number of additional &drm_gem_objects to lock

EXPORT_SYMBOL_GPL(drm_gpuvm_bo_find);

/**

 * drm_gpuvm_bo_obtain() - obtains and instance of the &drm_gpuvm_bo for the

 * drm_gpuvm_bo_obtain() - obtains an instance of the &drm_gpuvm_bo for the

 * given &drm_gpuvm and &drm_gem_object

 * @gpuvm: The &drm_gpuvm the @obj is mapped in.

 * @obj: The &drm_gem_object being mapped in the @gpuvm.

EXPORT_SYMBOL_GPL(drm_gpuvm_bo_obtain);

/**

 * drm_gpuvm_bo_obtain_prealloc() - obtains and instance of the &drm_gpuvm_bo

 * drm_gpuvm_bo_obtain_prealloc() - obtains an instance of the &drm_gpuvm_bo

 * for the given &drm_gpuvm and &drm_gem_object

 * @__vm_bo: A pre-allocated struct drm_gpuvm_bo.

 *

 * @vm_bo: the &drm_gpuvm_bo to add or remove

 * @evict: indicates whether the object is evicted

 *

 * Adds a &drm_gpuvm_bo to or removes it from the &drm_gpuvms evicted list.

 * Adds a &drm_gpuvm_bo to or removes it from the &drm_gpuvm's evicted list.

 */

void

drm_gpuvm_bo_evict(struct drm_gpuvm_bo *vm_bo, bool evict)

 * drm_gpuva_remove() - remove a &drm_gpuva

 * @va: the &drm_gpuva to remove

 *

 * This removes the given &va from the underlaying tree.

 * This removes the given &va from the underlying tree.

 *

 * It is safe to use this function using the safe versions of iterating the GPU

 * VA space, such as drm_gpuvm_for_each_va_safe() and

 *

 * This function iterates the given range of the GPU VA space. It utilizes the

 * &drm_gpuvm_ops to call back into the driver providing the operations to

 * unmap and, if required, split existent mappings.

 * unmap and, if required, split existing mappings.

 *

 * Drivers may use these callbacks to update the GPU VA space right away within

 * the callback. In case the driver decides to copy and store the operations for

 *    required without the earlier DRIVER_OP_MAP.  This is safe because we've

 *    already locked the GEM object in the earlier DRIVER_OP_MAP step.

 *

 * Returns: 0 on success or a negative error codec

 * Returns: 0 on success or a negative error code

 */

int

drm_gpuvm_sm_map_exec_lock(struct drm_gpuvm *gpuvm,

 * @req_offset: the offset within the &drm_gem_object

 *

 * This function creates a list of operations to perform splitting and merging

 * of existent mapping(s) with the newly requested one.

 * of existing mapping(s) with the newly requested one.

 *

 * The list can be iterated with &drm_gpuva_for_each_op and must be processed

 * in the given order. It can contain map, unmap and remap operations, but it

 * also can be empty if no operation is required, e.g. if the requested mapping

 * already exists is the exact same way.

 * already exists in the exact same way.

 *

 * There can be an arbitrary amount of unmap operations, a maximum of two remap

 * operations and a single map operation. The latter one represents the original

	} va;

	/**

	 * @gem: structure containing the &drm_gem_object and it's offset

	 * @gem: structure containing the &drm_gem_object and its offset

	 */

	struct {

		/**

	} va;

	/**

	 * @gem: structure containing the &drm_gem_object and it's offset

	 * @gem: structure containing the &drm_gem_object and its offset

	 */

	struct {

		/**

	/**

	 * @sm_step_unmap: called from &drm_gpuvm_sm_map and

	 * &drm_gpuvm_sm_unmap to unmap an existent mapping

	 * &drm_gpuvm_sm_unmap to unmap an existing mapping

	 *

	 * This callback is called when existent mapping needs to be unmapped.

	 * This callback is called when existing mapping needs to be unmapped.

	 * This is the case when either a newly requested mapping encloses an

	 * existent mapping or an unmap of an existent mapping is requested.

	 * existing mapping or an unmap of an existing mapping is requested.

	 *

	 * The &priv pointer matches the one the driver passed to

	 * &drm_gpuvm_sm_map or &drm_gpuvm_sm_unmap, respectively.