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

[Thomas Hellström]

On 5/5/23 21:45, Rodrigo Vivi wrote:
> 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>

Reviewed-by: Thomas Hellström <thomas.hellstrom at linux.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
>>