[PATCH drm-next v5 03/14] drm: manager to keep track of GPUs VA mappings

[Donald Robson]

Hi Danilo,
One comment below, but otherwise it looks great.  Thanks for adding the example!
Thanks,
Donald

On Tue, 2023-06-20 at 02:42 +0200, Danilo Krummrich wrote:
> 
> +/**
> + * DOC: Overview
> + *
> + * The DRM GPU VA Manager, represented by struct drm_gpuva_manager keeps track
> + * of a GPU's virtual address (VA) space and manages the corresponding virtual
> + * mappings represented by &drm_gpuva objects. It also keeps track of the
> + * 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.
> + *
> + * 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'.
> + *
> + * The GPU VA manager internally uses a &maple_tree to manage the
> + * &drm_gpuva mappings within a GPU's virtual address space.
> + *
> + * The &drm_gpuva_manager contains a special &drm_gpuva representing the
> + * portion of VA space reserved by the kernel. This node is initialized together
> + * with the GPU VA manager instance and removed when the GPU VA manager is
> + * destroyed.
> + *
> + * In a typical application drivers would embed struct drm_gpuva_manager and
> + * struct drm_gpuva within their own driver specific structures, there won't be
> + * any memory allocations of it's own nor memory allocations of &drm_gpuva
> + * entries.
> + *
> + * However, the &drm_gpuva_manager needs to allocate nodes for it's internal
> + * tree structures when &drm_gpuva entries are inserted. In order to support
> + * inserting &drm_gpuva entries from dma-fence signalling critical sections the
> + * &drm_gpuva_manager provides struct drm_gpuva_prealloc. Drivers may create
> + * pre-allocated nodes which drm_gpuva_prealloc_create() and subsequently insert
> + * a new &drm_gpuva entry with drm_gpuva_insert_prealloc().

I think it might be worth moving or repeating this paragraph to 'Split and Merge'
where I've added the other comment below.  I think these functions are only used
to set up for drm_gpuva_sm_map().  Please ignore me if I'm wrong.

> + */
> +
> +/**
> + * DOC: Split and Merge
> + *
> + * Besides it's capability to manage and represent a GPU VA space, the
> + * &drm_gpuva_manager also provides functions to let the &drm_gpuva_manager
> + * calculate a 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
> + * 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.
> + *
> + * Drivers can call drm_gpuva_sm_map() to receive a sequence of callbacks
> + * containing map, unmap and remap operations for a given newly requested
> + * mapping. The sequence of callbacks represents the set of operations to
> + * execute in order to integrate the new mapping cleanly into the current state
> + * of the GPU VA space.

Here

> + *
> + * Depending on how the new GPU VA mapping intersects with the existent mappings
> + * of the GPU VA space the &drm_gpuva_fn_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
> + * required, e.g. if the requested mapping already exists in the exact same way.
>