[Intel-xe] [PATCH v2 31/31] drm/xe/uapi: Add some VM bind kernel doc

[Rodrigo Vivi]

On Mon, May 01, 2023 at 05:17:27PM -0700, Matthew Brost wrote:
> Try to explain how VM bind works in Xe.

We will need more doc and likely with examples and all...
but this is already something we need.

Reviewed-by: Rodrigo Vivi <rodrigo.vivi at intel.com>

> 
> Signed-off-by: Matthew Brost <matthew.brost at intel.com>
> ---
>  include/uapi/drm/xe_drm.h | 45 ++++++++++++++++++++++++++++++++++++---
>  1 file changed, 42 insertions(+), 3 deletions(-)
> 
> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
> index cb4debe4ebda..c7137db2cbe8 100644
> --- a/include/uapi/drm/xe_drm.h
> +++ b/include/uapi/drm/xe_drm.h
> @@ -148,7 +148,16 @@ struct drm_xe_engine_class_instance {
>  	 * Kernel only classes (not actual hardware engine class). Used for
>  	 * creating ordered queues of VM bind operations.
>  	 */
> +	/**
> +	 * @DRM_XE_ENGINE_CLASS_VM_BIND_ASYNC: VM bind engine which are allowed
> +	 * to use in / out syncs. The out sync indicates bind op(s) completion.
> +	 */
>  #define DRM_XE_ENGINE_CLASS_VM_BIND_ASYNC	5
> +	/**
> +	 * @DRM_XE_ENGINE_CLASS_VM_BIND_SYNC: VM bind engine which are not
> +	 * allowed to use in / out syncs, The IOCTL return indicates bind op(s)
> +	 * completion.
> +	 */
>  #define DRM_XE_ENGINE_CLASS_VM_BIND_SYNC	6
>  
>  	__u16 engine_instance;
> @@ -322,6 +331,7 @@ struct drm_xe_vm_create {
>  
>  #define DRM_XE_VM_CREATE_SCRATCH_PAGE	(0x1 << 0)
>  #define DRM_XE_VM_CREATE_COMPUTE_MODE	(0x1 << 1)
> +	/** @DRM_XE_VM_CREATE_ASYNC_DEFAULT: Default VM bind engine is async */
>  #define DRM_XE_VM_CREATE_ASYNC_DEFAULT	(0x1 << 2)
>  #define DRM_XE_VM_CREATE_FAULT_MODE	(0x1 << 3)
>  
> @@ -379,21 +389,44 @@ struct drm_xe_vm_bind_op {
>  	/** @mem_region: Memory region to prefetch VMA to, instance not a mask */
>  	__u32 region;
>  
> +	/** @XE_VM_BIND_OP_MAP: Map a buffer object */
>  #define XE_VM_BIND_OP_MAP		0x0
> +	/** @XE_VM_BIND_OP_UNMAP: Unmap a buffer object or userptr */
>  #define XE_VM_BIND_OP_UNMAP		0x1
> +	/** @XE_VM_BIND_OP_MAP_USERPTR: Map a userptr */
>  #define XE_VM_BIND_OP_MAP_USERPTR	0x2
> +	/**
> +	 * @XE_VM_BIND_OP_RESTART: Restart last bind operation that failed with
> +	 * -ENOSPC
> +	 */
>  #define XE_VM_BIND_OP_RESTART		0x3
> +	/**
> +	 * @XE_VM_BIND_OP_UNMAP_ALL: Unmap all mappings associated with a
> +	 * buffer ibject
> +	 */
>  #define XE_VM_BIND_OP_UNMAP_ALL		0x4
> +	/**
> +	 * @XE_VM_BIND_OP_PREFETCH: For a deferred bind (faulting VM)
> +	 * validate buffer object and (re)bind
> +	 */
>  #define XE_VM_BIND_OP_PREFETCH		0x5
> -
> +	/** @XE_VM_BIND_FLAG_READONLY: Set mapping to read only */
>  #define XE_VM_BIND_FLAG_READONLY	(0x1 << 16)
> +	/**
> +	 * @XE_VM_BIND_FLAG_ASYNC: Sanity check for if using async bind engine
> +	 * (in / out syncs) this set needs to be set.
> +	 */
>  #define XE_VM_BIND_FLAG_ASYNC		(0x1 << 17)
> -	/*
> +	/**
> +	 * @XE_VM_BIND_FLAG_IMMEDIATE:
> +	 *
>  	 * Valid on a faulting VM only, do the MAP operation immediately rather
>  	 * than differing the MAP to the page fault handler.
>  	 */
>  #define XE_VM_BIND_FLAG_IMMEDIATE	(0x1 << 18)
> -	/*
> +	/**
> +	 * @XE_VM_BIND_FLAG_NULL:
> +	 *
>  	 * When the NULL flag is set, the page tables are setup with a special
>  	 * bit which indicates writes are dropped and all reads return zero. The
>  	 * NULL flags is only valid for XE_VM_BIND_OP_MAP operations, the BO
> @@ -401,6 +434,12 @@ struct drm_xe_vm_bind_op {
>  	 * VK sparse bindings.
>  	 */
>  #define XE_VM_BIND_FLAG_NULL		(0x1 << 19)
> +	/**
> +	 * @XE_VM_BIND_FLAG_RECLAIM: Should be set when a VM is in an error
> +	 * state (bind op returns -ENOSPC), used with sync bind engines to issue
> +	 * UNMAP operations which hopefully free enough memory so when VM is
> +	 * restarted via @XE_VM_BIND_OP_RESTART the failed bind ops succeed.
> +	 */
>  #define XE_VM_BIND_FLAG_RECLAIM		(0x1 << 20)
>  
>  	/** @reserved: Reserved */
> -- 
> 2.34.1
>