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