Documentation/gpu: Add a VM_BIND async document
Subsystems (3)
RFC PATCH 1/1 Documentation/gpu: Add a VM_BIND async document
Add a motivation for and description of asynchronous VM_BIND operation
v2:
- Fix typos (Nirmoy Das)
- Improve the description of a memory fence (Oak Zeng)
- Add a reference to the document in the Xe RFC.
- Add pointers to sample uAPI suggestions
v3:
- Address review comments (Danilo Krummrich)
- Formatting fixes
v4:
- Address typos (Francois Dugast)
- Explain why in-fences are not allowed for VM_BIND operations for long- running workloads (Matthew Brost)
v5:
- More typo- and style fixing
- Further clarify the implications of disallowing in-fences for VM_BIND operations for long-running workloads (Matthew Brost)
v6:
- Point out that a gpu_vm is a virtual GPU Address space. (Danilo Krummrich)
- For an explanation of dma-fences point to the dma-fence documentation. (Paolo Zanoni)
- Clarify that VM_BIND errors are reported synchronously. (Paulo Zanoni)
- Use an rst doc reference when pointing to the async vm_bind document from the xe merge plan.
- Add the VM_BIND documentation to the drm documentation table-of-content, using an intermediate "Misc DRM driver uAPI- and feature implementation guidelines"
v7:
- Update the error handling documentation to remove the VM error state.
--- Documentation/gpu/drm-vm-bind-async.rst | 309 ++++++++++++++++++ .../gpu/implementation_guidelines.rst | 9 + Documentation/gpu/index.rst | 1 + Documentation/gpu/rfc/xe.rst | 4 +- 4 files changed, 321 insertions(+), 2 deletions(-) create mode 100644 Documentation/gpu/drm-vm-bind-async.rst create mode 100644 Documentation/gpu/implementation_guidelines.rst
Documentation/gpu/drm-vm-bind-async.rst new file +309 -0
@@ -0,0 +1,309 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT) + +==================== +Asynchronous VM_BIND +==================== + +Nomenclature: +============= + +* ``VRAM``: On-device memory. Sometimes referred to as device local memory. + +* ``gpu_vm``: A virtual GPU address space. Typically per process, but + can be shared by multiple processes. + +* ``VM_BIND``: An operation or a list of operations to modify a gpu_vm using + an IOCTL. The operations include mapping and unmapping system- or + VRAM memory. + +* ``syncobj``: A container that abstracts synchronization objects. The + synchronization objects can be either generic, like dma-fences or + driver specific. A syncobj typically indicates the type of the + underlying synchronization object. + +* ``in-syncobj``: Argument to a VM_BIND IOCTL, the VM_BIND operation waits + for these before starting. + +* ``out-syncobj``: Argument to a VM_BIND_IOCTL, the VM_BIND operation + signals these when the bind operation is complete. + +* ``dma-fence``: A cross-driver synchronization object. A basic + understanding of dma-fences is required to digest this + document. Please refer to the ``DMA Fences`` section of the + :doc:`dma-buf doc </driver-api/dma-buf>`. + +* ``memory fence``: A synchronization object, different from a dma-fence. + A memory fence uses the value of a specified memory location to determine + signaled status. A memory fence can be awaited and signaled by both + the GPU and CPU. Memory fences are sometimes referred to as + user-fences, userspace-fences or gpu futexes and do not necessarily obey + the dma-fence rule of signaling within a "reasonable amount of time". + The kernel should thus avoid waiting for memory fences with locks held. + +* ``long-running workload``: A workload that may take more than the + current stipulated dma-fence maximum signal delay to complete and + which therefore needs to set the gpu_vm or the GPU execution context in + a certain mode that disallows completion dma-fences. + +* ``exec function``: An exec function is a function that revalidates all + affected gpu_vmas, submits a GPU command batch and registers the + dma_fence representing the GPU command's activity with all affected + dma_resvs. For completeness, although not covered by this document, + it's worth mentioning that an exec function may also be the + revalidation worker that is used by some drivers in compute / + long-running mode. + +* ``bind context``: A context identifier used for the VM_BIND + operation. VM_BIND operations that use the same bind context can be + assumed, where it matters, to complete in order of submission. No such + assumptions can be made for VM_BIND operations using separate bind contexts. + +* ``UMD``: User-mode driver. + +* ``KMD``: Kernel-mode driver. + + +Synchronous / Asynchronous VM_BIND operation +============================================ + +Synchronous VM_BIND +___________________ +With Synchronous VM_BIND, the VM_BIND operations all complete before the +IOCTL returns. A synchronous VM_BIND takes neither in-fences nor +out-fences. Synchronous VM_BIND may block and wait for GPU operations; +for example swap-in or clearing, or even previous binds. + +Asynchronous VM_BIND +____________________ +Asynchronous VM_BIND accepts both in-syncobjs and out-syncobjs. While the +IOCTL may return immediately, the VM_BIND operations wait for the in-syncobjs +before modifying the GPU page-tables, and signal the out-syncobjs when +the modification is done in the sense that the next exec function that +awaits for the out-syncobjs will see the change. Errors are reported +synchronously. +In low-memory situations the implementation may block, performing the +VM_BIND synchronously, because there might not be enough memory +immediately available for preparing the asynchronous operation. + +If the VM_BIND IOCTL takes a list or an array of operations as an argument, +the in-syncobjs needs to signal before the first operation starts to +execute, and the out-syncobjs signal after the last operation +completes. Operations in the operation list can be assumed, where it +matters, to complete in order. + +Since asynchronous VM_BIND operations may use dma-fences embedded in +out-syncobjs and internally in KMD to signal bind completion, any +memory fences given as VM_BIND in-fences need to be awaited +synchronously before the VM_BIND ioctl returns, since dma-fences, +required to signal in a reasonable amount of time, can never be made +to depend on memory fences that don't have such a restriction. + +The purpose of an Asynchronous VM_BIND operation is for user-mode +drivers to be able to pipeline interleaved gpu_vm modifications and +exec functions. For long-running workloads, such pipelining of a bind +operation is not allowed and any in-fences need to be awaited +synchronously. The reason for this is twofold. First, any memory +fences gated by a long-running workload and used as in-syncobjs for the +VM_BIND operation will need to be awaited synchronously anyway (see +above). Second, any dma-fences used as in-syncobjs for VM_BIND +operations for long-running workloads will not allow for pipelining +anyway since long-running workloads don't allow for dma-fences as +out-syncobjs, so while theoretically possible the use of them is +questionable and should be rejected until there is a valuable use-case. +Note that this is not a limitation imposed by dma-fence rules, but +rather a limitation imposed to keep KMD implementation simple. It does +not affect using dma-fences as dependencies for the long-running +workload itself, which is allowed by dma-fence rules, but rather for +the VM_BIND operation only. + +An asynchronous VM_BIND operation may take substantial time to +complete and signal the out_fence. In particular if the operation is +deeply pipelined behind other VM_BIND operations and workloads +submitted using exec functions. In that case, UMD might want to avoid a +subsequent VM_BIND operation to be queued behind the first one if +there are no explicit dependencies. In order to circumvent such a queue-up, a +VM_BIND implementation may allow for VM_BIND contexts to be +created. For each context, VM_BIND operations will be guaranteed to +complete in the order they were submitted, but that is not the case +for VM_BIND operations executing on separate VM_BIND contexts. Instead +KMD will attempt to execute such VM_BIND operations in parallel but +leaving no guarantee that they will actually be executed in +parallel. There may be internal implicit dependencies that only KMD knows +about, for example page-table structure changes. A way to attempt +to avoid such internal dependencies is to have different VM_BIND +contexts use separate regions of a VM. + +Also for VM_BINDS for long-running gpu_vms the user-mode driver should typically +select memory fences as out-fences since that gives greater flexibility for +the kernel mode driver to inject other operations into the bind / +unbind operations. Like for example inserting breakpoints into batch +buffers. The workload execution can then easily be pipelined behind +the bind completion using the memory out-fence as the signal condition +for a GPU semaphore embedded by UMD in the workload. + +There is no difference in the operations supported or in +multi-operation support between asynchronous VM_BIND and synchronous VM_BIND. + +Multi-operation VM_BIND IOCTL error handling and interrupts +=========================================================== + +The VM_BIND operations of the IOCTL may error for various reasons, for +example due to lack of resources to complete and due to interrupted +waits. +In these situations UMD should preferably restart the IOCTL after +taking suitable action. +If UMD has over-committed a memory resource, an -ENOSPC error will be +returned, and UMD may then unbind resources that are not used at the +moment and rerun the IOCTL. On -EINTR, UMD should simply rerun the +IOCTL and on -ENOMEM user-space may either attempt to free known +system memory resources or fail. In case of UMD deciding to fail a +bind operation, due to an error return, no additional action is needed +to clean up the failed operation, and the VM is left in the same state +as it was before the failing IOCTL. +Unbind operations are guaranteed not to return any errors due to +resource constraints, but may return errors due to, for example, +invalid arguments or the gpu_vm being banned. +In the case an unexpected error happens during the asynchronous bind +process, the gpu_vm will be banned, and attempts to use it after banning +will return -ENOENT. + +Example: The Xe VM_BIND uAPI +============================ + +Starting with the VM_BIND operation struct, the IOCTL call can take +zero, one or many such operations. A zero number means only the +synchronization part of the IOCTL is carried out: an asynchronous +VM_BIND updates the syncobjects, whereas a sync VM_BIND waits for the +implicit dependencies to be fulfilled. + +.. code-block:: c + + struct drm_xe_vm_bind_op { + /** + * @obj: GEM object to operate on, MBZ for MAP_USERPTR, MBZ for UNMAP + */ + __u32 obj; + + /** @pad: MBZ */ + __u32 pad; + + union { + /** + * @obj_offset: Offset into the object for MAP. + */ + __u64 obj_offset; + + /** @userptr: user virtual address for MAP_USERPTR */ + __u64 userptr; + }; + + /** + * @range: Number of bytes from the object to bind to addr, MBZ for UNMAP_ALL + */ + __u64 range; + + /** @addr: Address to operate on, MBZ for UNMAP_ALL */ + __u64 addr; + + /** + * @tile_mask: Mask for which tiles to create binds for, 0 == All tiles, + * only applies to creating new VMAs + */ + __u64 tile_mask; + + /* Map (parts of) an object into the GPU virtual address range. + #define XE_VM_BIND_OP_MAP 0x0 + /* Unmap a GPU virtual address range */ + #define XE_VM_BIND_OP_UNMAP 0x1 + /* + * Map a CPU virtual address range into a GPU virtual + * address range. + */ + #define XE_VM_BIND_OP_MAP_USERPTR 0x2 + /* Unmap a gem object from the VM. */ + #define XE_VM_BIND_OP_UNMAP_ALL 0x3 + /* + * Make the backing memory of an address range resident if + * possible. Note that this doesn't pin backing memory. + */ + #define XE_VM_BIND_OP_PREFETCH 0x4 + + /* Make the GPU map readonly. */ + #define XE_VM_BIND_FLAG_READONLY (0x1 << 16) + /* + * Valid on a faulting VM only, do the MAP operation immediately rather + * than deferring the MAP to the page fault handler. + */ + #define XE_VM_BIND_FLAG_IMMEDIATE (0x1 << 17) + /* + * 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. In + * the future, the NULL flags will only be valid for XE_VM_BIND_OP_MAP + * operations, the BO handle MBZ, and the BO offset MBZ. This flag is + * intended to implement VK sparse bindings. + */ + #define XE_VM_BIND_FLAG_NULL (0x1 << 18) + /** @op: Operation to perform (lower 16 bits) and flags (upper 16 bits) */ + __u32 op; + + /** @mem_region: Memory region to prefetch VMA to, instance not a mask */ + __u32 region; + + /** @reserved: Reserved */ + __u64 reserved[2]; + }; + + +The VM_BIND IOCTL argument itself, looks like follows. Note that for +synchronous VM_BIND, the num_syncs and syncs fields must be zero. Here +the ``exec_queue_id`` field is the VM_BIND context discussed previously +that is used to facilitate out-of-order VM_BINDs. + +.. code-block:: c + + struct drm_xe_vm_bind { + /** @extensions: Pointer to the first extension struct, if any */ + __u64 extensions; + + /** @vm_id: The ID of the VM to bind to */ + __u32 vm_id; + + /** + * @exec_queue_id: exec_queue_id, must be of class DRM_XE_ENGINE_CLASS_VM_BIND + * and exec queue must have same vm_id. If zero, the default VM bind engine + * is used. + */ + __u32 exec_queue_id; + + /** @num_binds: number of binds in this IOCTL */ + __u32 num_binds; + + /* If set, perform an async VM_BIND, if clear a sync VM_BIND */ + #define XE_VM_BIND_IOCTL_FLAG_ASYNC (0x1 << 0) + + /** @flag: Flags controlling all operations in this ioctl. */ + __u32 flags; + + union { + /** @bind: used if num_binds == 1 */ + struct drm_xe_vm_bind_op bind; + + /** + * @vector_of_binds: userptr to array of struct + * drm_xe_vm_bind_op if num_binds > 1 + */ + __u64 vector_of_binds; + }; + + /** @num_syncs: amount of syncs to wait for or to signal on completion. */ + __u32 num_syncs; + + /** @pad2: MBZ */ + __u32 pad2; + + /** @syncs: pointer to struct drm_xe_sync array */ + __u64 syncs; + + /** @reserved: Reserved */ + __u64 reserved[2]; + };
Documentation/gpu/implementation_guidelines.rst new file +9 -0
@@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT) + +=========================================================== +Misc DRM driver uAPI- and feature implementation guidelines +=========================================================== + +.. toctree:: + + drm-vm-bind-async
Documentation/gpu/index.rst +1 -0
@@ -18,6 +18,7 @@ GPU Driver Developer's Guide vga-switcheroo vgaarbiter automated_testing + implementation_guidelines todo rfc/index
Documentation/gpu/rfc/xe.rst +2 -2
@@ -97,8 +97,8 @@ memory fences. Ideally with helper support so people don't get it wrong in all possible ways. As a key measurable result, the benefits of ASYNC VM_BIND and a discussion of -various flavors, error handling and a sample API should be documented here or in -a separate document pointed to by this document. +various flavors, error handling and sample API suggestions are documented in +:doc:`The ASYNC VM_BIND document </gpu/drm-vm-bind-async>`. Userptr integration and vm_bind -------------------------------
Signature · 1 line
2.41.0
Quoted 15 lines · Thomas Hellström
Add a motivation for and description of asynchronous
VM_BINDoperationv2:
- Fix typos (Nirmoy Das)
- Improve the description of a memory fence (Oak Zeng)
- Add a reference to the document in the Xe RFC.
- Add pointers to sample uAPI suggestions
v3:
- Address review comments (Danilo Krummrich)
- Formatting fixes
v4:
- Address typos (Francois Dugast)
- Explain why in-fences are not allowed forVM_BINDoperations for long- running workloads (Matthew Brost)
v5:
Quoted 8 lines
- More typo- and style fixing
- Further clarify the implications of disallowing in-fences forVM_BINDoperations for long-running workloads (Matthew Brost)
v6:
- Point out that agpu_vmis a virtual GPU Address space. (Danilo Krummrich)
- For an explanation of dma-fences point to the dma-fence documentation. (Paolo Zanoni)
s/Paolo/Paulo/
Quoted 10 lines
- Clarify that
VM_BINDerrors are reported synchronously. (Paulo Zanoni)
- Use an rst doc reference when pointing to the asyncvm_binddocument from the xe merge plan.
- Add theVM_BINDdocumentation to the drm documentation table-of-content, using an intermediate "Misc DRM driver uAPI- and feature implementation guidelines"
v7:
- Update the error handling documentation to remove the VM error state.Cc Paulo R Zanoni <[email protected]>
Quoted 371 lines
Signed-off-by Thomas Hellström <[email protected]>Acked-by Nirmoy Das <[email protected]>Reviewed-by Danilo Krummrich <[email protected]>Reviewed-by Matthew Brost <[email protected]>Reviewed-by Rodrigo Vivi <[email protected]>--- Documentation/gpu/drm-vm-bind-async.rst | 309 ++++++++++++++++++ .../gpu/implementation_guidelines.rst | 9 + Documentation/gpu/index.rst | 1 + Documentation/gpu/rfc/xe.rst | 4 +- 4 files changed, 321 insertions(+), 2 deletions(-) create mode 100644 Documentation/gpu/drm-vm-bind-async.rst create mode 100644 Documentation/gpu/implementation_guidelines.rstDocumentation/gpu/drm-vm-bind-async.rst new file +309
-0@@ -0,0 +1,309 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT) + +==================== +Asynchronous VM_BIND +==================== + +Nomenclature: +============= + +* ``VRAM``: On-device memory. Sometimes referred to as device local memory. + +* ``gpu_vm``: A virtual GPU address space. Typically per process, but + can be shared by multiple processes. + +* ``VM_BIND``: An operation or a list of operations to modify a gpu_vm using + an IOCTL. The operations include mapping and unmapping system- or + VRAM memory. + +* ``syncobj``: A container that abstracts synchronization objects. The + synchronization objects can be either generic, like dma-fences or + driver specific. A syncobj typically indicates the type of the + underlying synchronization object. + +* ``in-syncobj``: Argument to a VM_BIND IOCTL, the VM_BIND operation waits + for these before starting. + +* ``out-syncobj``: Argument to a VM_BIND_IOCTL, the VM_BIND operation + signals these when the bind operation is complete. + +* ``dma-fence``: A cross-driver synchronization object. A basic + understanding of dma-fences is required to digest this + document. Please refer to the ``DMA Fences`` section of the + :doc:`dma-buf doc </driver-api/dma-buf>`. + +* ``memory fence``: A synchronization object, different from a dma-fence. + A memory fence uses the value of a specified memory location to determine + signaled status. A memory fence can be awaited and signaled by both + the GPU and CPU. Memory fences are sometimes referred to as + user-fences, userspace-fences or gpu futexes and do not necessarily obey + the dma-fence rule of signaling within a "reasonable amount of time". + The kernel should thus avoid waiting for memory fences with locks held. + +* ``long-running workload``: A workload that may take more than the + current stipulated dma-fence maximum signal delay to complete and + which therefore needs to set the gpu_vm or the GPU execution context in + a certain mode that disallows completion dma-fences. + +* ``exec function``: An exec function is a function that revalidates all + affected gpu_vmas, submits a GPU command batch and registers the + dma_fence representing the GPU command's activity with all affected + dma_resvs. For completeness, although not covered by this document, + it's worth mentioning that an exec function may also be the + revalidation worker that is used by some drivers in compute / + long-running mode. + +* ``bind context``: A context identifier used for the VM_BIND + operation. VM_BIND operations that use the same bind context can be + assumed, where it matters, to complete in order of submission. No such + assumptions can be made for VM_BIND operations using separate bind contexts. + +* ``UMD``: User-mode driver. + +* ``KMD``: Kernel-mode driver. + + +Synchronous / Asynchronous VM_BIND operation +============================================ + +Synchronous VM_BIND +___________________ +With Synchronous VM_BIND, the VM_BIND operations all complete before the +IOCTL returns. A synchronous VM_BIND takes neither in-fences nor +out-fences. Synchronous VM_BIND may block and wait for GPU operations; +for example swap-in or clearing, or even previous binds. + +Asynchronous VM_BIND +____________________ +Asynchronous VM_BIND accepts both in-syncobjs and out-syncobjs. While the +IOCTL may return immediately, the VM_BIND operations wait for the in-syncobjs +before modifying the GPU page-tables, and signal the out-syncobjs when +the modification is done in the sense that the next exec function that +awaits for the out-syncobjs will see the change. Errors are reported +synchronously. +In low-memory situations the implementation may block, performing the +VM_BIND synchronously, because there might not be enough memory +immediately available for preparing the asynchronous operation. + +If the VM_BIND IOCTL takes a list or an array of operations as an argument, +the in-syncobjs needs to signal before the first operation starts to +execute, and the out-syncobjs signal after the last operation +completes. Operations in the operation list can be assumed, where it +matters, to complete in order. + +Since asynchronous VM_BIND operations may use dma-fences embedded in +out-syncobjs and internally in KMD to signal bind completion, any +memory fences given as VM_BIND in-fences need to be awaited +synchronously before the VM_BIND ioctl returns, since dma-fences, +required to signal in a reasonable amount of time, can never be made +to depend on memory fences that don't have such a restriction. + +The purpose of an Asynchronous VM_BIND operation is for user-mode +drivers to be able to pipeline interleaved gpu_vm modifications and +exec functions. For long-running workloads, such pipelining of a bind +operation is not allowed and any in-fences need to be awaited +synchronously. The reason for this is twofold. First, any memory +fences gated by a long-running workload and used as in-syncobjs for the +VM_BIND operation will need to be awaited synchronously anyway (see +above). Second, any dma-fences used as in-syncobjs for VM_BIND +operations for long-running workloads will not allow for pipelining +anyway since long-running workloads don't allow for dma-fences as +out-syncobjs, so while theoretically possible the use of them is +questionable and should be rejected until there is a valuable use-case. +Note that this is not a limitation imposed by dma-fence rules, but +rather a limitation imposed to keep KMD implementation simple. It does +not affect using dma-fences as dependencies for the long-running +workload itself, which is allowed by dma-fence rules, but rather for +the VM_BIND operation only. + +An asynchronous VM_BIND operation may take substantial time to +complete and signal the out_fence. In particular if the operation is +deeply pipelined behind other VM_BIND operations and workloads +submitted using exec functions. In that case, UMD might want to avoid a +subsequent VM_BIND operation to be queued behind the first one if +there are no explicit dependencies. In order to circumvent such a queue-up, a +VM_BIND implementation may allow for VM_BIND contexts to be +created. For each context, VM_BIND operations will be guaranteed to +complete in the order they were submitted, but that is not the case +for VM_BIND operations executing on separate VM_BIND contexts. Instead +KMD will attempt to execute such VM_BIND operations in parallel but +leaving no guarantee that they will actually be executed in +parallel. There may be internal implicit dependencies that only KMD knows +about, for example page-table structure changes. A way to attempt +to avoid such internal dependencies is to have different VM_BIND +contexts use separate regions of a VM. + +Also for VM_BINDS for long-running gpu_vms the user-mode driver should typically +select memory fences as out-fences since that gives greater flexibility for +the kernel mode driver to inject other operations into the bind / +unbind operations. Like for example inserting breakpoints into batch +buffers. The workload execution can then easily be pipelined behind +the bind completion using the memory out-fence as the signal condition +for a GPU semaphore embedded by UMD in the workload. + +There is no difference in the operations supported or in +multi-operation support between asynchronous VM_BIND and synchronous VM_BIND. + +Multi-operation VM_BIND IOCTL error handling and interrupts +=========================================================== + +The VM_BIND operations of the IOCTL may error for various reasons, for +example due to lack of resources to complete and due to interrupted +waits. +In these situations UMD should preferably restart the IOCTL after +taking suitable action. +If UMD has over-committed a memory resource, an -ENOSPC error will be +returned, and UMD may then unbind resources that are not used at the +moment and rerun the IOCTL. On -EINTR, UMD should simply rerun the +IOCTL and on -ENOMEM user-space may either attempt to free known +system memory resources or fail. In case of UMD deciding to fail a +bind operation, due to an error return, no additional action is needed +to clean up the failed operation, and the VM is left in the same state +as it was before the failing IOCTL. +Unbind operations are guaranteed not to return any errors due to +resource constraints, but may return errors due to, for example, +invalid arguments or the gpu_vm being banned. +In the case an unexpected error happens during the asynchronous bind +process, the gpu_vm will be banned, and attempts to use it after banning +will return -ENOENT. + +Example: The Xe VM_BIND uAPI +============================ + +Starting with the VM_BIND operation struct, the IOCTL call can take +zero, one or many such operations. A zero number means only the +synchronization part of the IOCTL is carried out: an asynchronous +VM_BIND updates the syncobjects, whereas a sync VM_BIND waits for the +implicit dependencies to be fulfilled. + +.. code-block:: c + + struct drm_xe_vm_bind_op { + /** + * @obj: GEM object to operate on, MBZ for MAP_USERPTR, MBZ for UNMAP + */ + __u32 obj; + + /** @pad: MBZ */ + __u32 pad; + + union { + /** + * @obj_offset: Offset into the object for MAP. + */ + __u64 obj_offset; + + /** @userptr: user virtual address for MAP_USERPTR */ + __u64 userptr; + }; + + /** + * @range: Number of bytes from the object to bind to addr, MBZ for UNMAP_ALL + */ + __u64 range; + + /** @addr: Address to operate on, MBZ for UNMAP_ALL */ + __u64 addr; + + /** + * @tile_mask: Mask for which tiles to create binds for, 0 == All tiles, + * only applies to creating new VMAs + */ + __u64 tile_mask; + + /* Map (parts of) an object into the GPU virtual address range. + #define XE_VM_BIND_OP_MAP 0x0 + /* Unmap a GPU virtual address range */ + #define XE_VM_BIND_OP_UNMAP 0x1 + /* + * Map a CPU virtual address range into a GPU virtual + * address range. + */ + #define XE_VM_BIND_OP_MAP_USERPTR 0x2 + /* Unmap a gem object from the VM. */ + #define XE_VM_BIND_OP_UNMAP_ALL 0x3 + /* + * Make the backing memory of an address range resident if + * possible. Note that this doesn't pin backing memory. + */ + #define XE_VM_BIND_OP_PREFETCH 0x4 + + /* Make the GPU map readonly. */ + #define XE_VM_BIND_FLAG_READONLY (0x1 << 16) + /* + * Valid on a faulting VM only, do the MAP operation immediately rather + * than deferring the MAP to the page fault handler. + */ + #define XE_VM_BIND_FLAG_IMMEDIATE (0x1 << 17) + /* + * 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. In + * the future, the NULL flags will only be valid for XE_VM_BIND_OP_MAP + * operations, the BO handle MBZ, and the BO offset MBZ. This flag is + * intended to implement VK sparse bindings. + */ + #define XE_VM_BIND_FLAG_NULL (0x1 << 18) + /** @op: Operation to perform (lower 16 bits) and flags (upper 16 bits) */ + __u32 op; + + /** @mem_region: Memory region to prefetch VMA to, instance not a mask */ + __u32 region; + + /** @reserved: Reserved */ + __u64 reserved[2]; + }; + + +The VM_BIND IOCTL argument itself, looks like follows. Note that for +synchronous VM_BIND, the num_syncs and syncs fields must be zero. Here +the ``exec_queue_id`` field is the VM_BIND context discussed previously +that is used to facilitate out-of-order VM_BINDs. + +.. code-block:: c + + struct drm_xe_vm_bind { + /** @extensions: Pointer to the first extension struct, if any */ + __u64 extensions; + + /** @vm_id: The ID of the VM to bind to */ + __u32 vm_id; + + /** + * @exec_queue_id: exec_queue_id, must be of class DRM_XE_ENGINE_CLASS_VM_BIND + * and exec queue must have same vm_id. If zero, the default VM bind engine + * is used. + */ + __u32 exec_queue_id; + + /** @num_binds: number of binds in this IOCTL */ + __u32 num_binds; + + /* If set, perform an async VM_BIND, if clear a sync VM_BIND */ + #define XE_VM_BIND_IOCTL_FLAG_ASYNC (0x1 << 0) + + /** @flag: Flags controlling all operations in this ioctl. */ + __u32 flags; + + union { + /** @bind: used if num_binds == 1 */ + struct drm_xe_vm_bind_op bind; + + /** + * @vector_of_binds: userptr to array of struct + * drm_xe_vm_bind_op if num_binds > 1 + */ + __u64 vector_of_binds; + }; + + /** @num_syncs: amount of syncs to wait for or to signal on completion. */ + __u32 num_syncs; + + /** @pad2: MBZ */ + __u32 pad2; + + /** @syncs: pointer to struct drm_xe_sync array */ + __u64 syncs; + + /** @reserved: Reserved */ + __u64 reserved[2]; + };Documentation/gpu/implementation_guidelines.rst new file +9
-0@@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT) + +=========================================================== +Misc DRM driver uAPI- and feature implementation guidelines +=========================================================== + +.. toctree:: + + drm-vm-bind-asyncDocumentation/gpu/index.rst +1
-0@@ -18,6 +18,7 @@ GPU Driver Developer's Guide vga-switcheroo vgaarbiter automated_testing + implementation_guidelines todo rfc/indexDocumentation/gpu/rfc/xe.rst +2
-2@@ -97,8 +97,8 @@ memory fences. Ideally with helper support so people don't get it wrong in all possible ways. As a key measurable result, the benefits of ASYNC VM_BIND and a discussion of -various flavors, error handling and a sample API should be documented here or in -a separate document pointed to by this document. +various flavors, error handling and sample API suggestions are documented in +:doc:`The ASYNC VM_BIND document </gpu/drm-vm-bind-async>`. Userptr integration and vm_bind -------------------------------
Quoted 45 lines · Paulo R
Quoted 19 lines · Thomas Hellström
Add a motivation for and description of asynchronous
VM_BINDoperationv2:
- Fix typos (Nirmoy Das)
- Improve the description of a memory fence (Oak Zeng)
- Add a reference to the document in the Xe RFC.
- Add pointers to sample uAPI suggestions
v3:
- Address review comments (Danilo Krummrich)
- Formatting fixes
v4:
- Address typos (Francois Dugast)
- Explain why in-fences are not allowed forVM_BINDoperations for long-
running workloads (Matthew Brost)
v5:
- More typo- and style fixing
- Further clarify the implications of disallowing in-fences forQuoted 8 lines
VM_BIND
operations for long-running workloads (Matthew Brost) v6:
- Point out that agpu_vmis a virtual GPU Address space. (Danilo Krummrich)
- For an explanation of dma-fences point to the dma-fence documentation.
(Paolo Zanoni)s/Paolo/Paulo/
Quoted 14 lines
- Clarify that
VM_BINDerrors are reported synchronously. (Paulo Zanoni)
- Use an rst doc reference when pointing to the asyncvm_binddocument
from the xe merge plan.
- Add theVM_BINDdocumentation to the drm documentation table-of- content,
using an intermediate "Misc DRM driver uAPI- and feature implementation
guidelines"
v7:
- Update the error handling documentation to remove the VM error state.
Quoted 3 lines
Quoted 1 line
Cc Paulo R Zanoni <[email protected]>Reviewed-by Paulo Zanoni <[email protected]>
Thanks for the review and the feedback, Paulo.
/Thomas
Quoted 472 lines
Quoted 471 lines
Signed-off-by Thomas Hellström <[email protected]>Acked-by Nirmoy Das <[email protected]>Reviewed-by Danilo Krummrich <[email protected]>Reviewed-by Matthew Brost <[email protected]>Reviewed-by Rodrigo Vivi <[email protected]>---
Documentation/gpu/drm-vm-bind-async.rst | 309
++++++++++++++++++
.../gpu/implementation_guidelines.rst | 9 + Documentation/gpu/index.rst | 1 + Documentation/gpu/rfc/xe.rst | 4 +-4 files changed, 321 insertions(+), 2 deletions(-)create mode 100644
Documentation/gpu/drm-vm-bind-async.rstcreate mode 100644Documentation/gpu/implementation_guidelines.rstDocumentation/gpu/drm-vm-bind-async.rst new file +10
-0@@ -0,0 +1,309 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT) + +==================== +Asynchronous VM_BIND +==================== + +Nomenclature: +============= + +* ``VRAM``: On-device memory. Sometimes referred to as devicelocal memory.
Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+ +* ``gpu_vm``: A virtual GPU address space. Typically per process,but
+ can be shared by multiple processes.Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+ +* ``VM_BIND``: An operation or a list of operations to modify a
gpu_vmusing
+ an IOCTL. The operations include mapping and unmapping system- or
+ VRAM memory.Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+ +* ``syncobj``: A container that abstracts synchronization objects.The
+ synchronization objects can be either generic, like dma-fences or
+ driver specific. A syncobj typically indicates the type of the + underlying synchronization object.Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+ +* ``in-syncobj``: Argument to a VM_BIND IOCTL, the VM_BINDoperation waits
+ for these before starting.Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+ +* ``out-syncobj``: Argument to a VM_BIND_IOCTL, the VM_BINDoperation
+ signals these when the bind operation is complete.Documentation/gpu/drm-vm-bind-async.rst new file +7
-0+ +* ``dma-fence``: A cross-driver synchronization object. A basic + understanding of dma-fences is required to digest this + document. Please refer to the ``DMA Fences`` section of the + :doc:`dma-buf doc </driver-api/dma-buf>`. + +* ``memory fence``: A synchronization object, different from adma-fence.
+ A memory fence uses the value of a specified memory location to determine
+ signaled status. A memory fence can be awaited and signaled by both
+ the GPU and CPU. Memory fences are sometimes referred to as + user-fences, userspace-fences or gpu futexes and do not necessarily obey
+ the dma-fence rule of signaling within a "reasonable amount of time".
+ The kernel should thus avoid waiting for memory fences with locks held.Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+ +* ``long-running workload``: A workload that may take more thanthe
+ current stipulated dma-fence maximum signal delay to complete and
+ which therefore needs to set thegpu_vmor the GPU execution context in
+ a certain mode that disallows completion dma-fences.Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+ +* ``exec function``: An exec function is a function thatrevalidates all
+ affectedgpu_vmas, submits a GPU command batch and registers the +dma_fencerepresenting the GPU command's activity with all affected
+dma_resvs. For completeness, although not covered by this document,
+ it's worth mentioning that an exec function may also be the + revalidation worker that is used by some drivers in compute / + long-running mode.Documentation/gpu/drm-vm-bind-async.rst new file +3
-0+ +* ``bind context``: A context identifier used for the VM_BIND + operation. VM_BIND operations that use the same bind context canbe
+ assumed, where it matters, to complete in order of submission. No such
+ assumptions can be made forVM_BINDoperations using separate bind contexts.Documentation/gpu/drm-vm-bind-async.rst new file +12
-0+ +* ``UMD``: User-mode driver. + +* ``KMD``: Kernel-mode driver. + + +Synchronous / Asynchronous VM_BIND operation +============================================ + +Synchronous VM_BIND +___________________ +With Synchronous VM_BIND, the VM_BIND operations all completebefore the
Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+IOCTL returns. A synchronous VM_BIND takes neither in-fences nor +out-fences. Synchronous VM_BIND may block and wait for GPUoperations;
Documentation/gpu/drm-vm-bind-async.rst new file +5
-0+for example swap-in or clearing, or even previous binds. + +Asynchronous VM_BIND +____________________ +Asynchronous VM_BIND accepts both in-syncobjs and out-syncobjs.While the
+IOCTL may return immediately, theVM_BINDoperations wait for the in-syncobjs
+before modifying the GPU page-tables, and signal the out-syncobjs when
+the modification is done in the sense that the next exec function that
+awaits for the out-syncobjs will see the change. Errors are reportedDocumentation/gpu/drm-vm-bind-async.rst new file +2
-0+synchronously. +In low-memory situations the implementation may block, performingthe
Documentation/gpu/drm-vm-bind-async.rst new file +4
-0+VM_BIND synchronously, because there might not be enough memory +immediately available for preparing the asynchronous operation. + +If the VM_BIND IOCTL takes a list or an array of operations as anargument,
+the in-syncobjs needs to signal before the first operation starts toDocumentation/gpu/drm-vm-bind-async.rst new file +2
-0+execute, and the out-syncobjs signal after the last operation +completes. Operations in the operation list can be assumed, whereit
Documentation/gpu/drm-vm-bind-async.rst new file +3
-0+matters, to complete in order. + +Since asynchronous VM_BIND operations may use dma-fences embeddedin
Documentation/gpu/drm-vm-bind-async.rst new file +4
-0+out-syncobjs and internally in KMD to signal bind completion, any +memory fences given as VM_BIND in-fences need to be awaited +synchronously before the VM_BIND ioctl returns, since dma-fences, +required to signal in a reasonable amount of time, can never bemade
Documentation/gpu/drm-vm-bind-async.rst new file +4
-0+to depend on memory fences that don't have such a restriction. + +The purpose of an Asynchronous VM_BIND operation is for user-mode +drivers to be able to pipeline interleaved gpu_vm modificationsand
+exec functions. For long-running workloads, such pipelining of a bindDocumentation/gpu/drm-vm-bind-async.rst new file +3
-0+operation is not allowed and any in-fences need to be awaited +synchronously. The reason for this is twofold. First, any memory +fences gated by a long-running workload and used as in-syncobjsfor the
+VM_BIND operation will need to be awaited synchronously anyway (seeDocumentation/gpu/drm-vm-bind-async.rst new file +2
-0+above). Second, any dma-fences used as in-syncobjs for VM_BIND +operations for long-running workloads will not allow forpipelining
Documentation/gpu/drm-vm-bind-async.rst new file +3
-0+anyway since long-running workloads don't allow for dma-fences as +out-syncobjs, so while theoretically possible the use of them is +questionable and should be rejected until there is a valuable use-case.
Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+Note that this is not a limitation imposed by dma-fence rules, but +rather a limitation imposed to keep KMD implementation simple. Itdoes
Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+not affect using dma-fences as dependencies for the long-running +workload itself, which is allowed by dma-fence rules, but ratherfor
Documentation/gpu/drm-vm-bind-async.rst new file +4
-0+the VM_BIND operation only. + +An asynchronous VM_BIND operation may take substantial time to +complete and signal the out_fence. In particular if the operationis
Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+deeply pipelined behind other VM_BIND operations and workloads +submitted using exec functions. In that case, UMD might want toavoid a
Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+subsequent VM_BIND operation to be queued behind the first one if +there are no explicit dependencies. In order to circumvent such aqueue-up, a
Documentation/gpu/drm-vm-bind-async.rst new file +2
-0+VM_BIND implementation may allow for VM_BIND contexts to be +created. For each context, VM_BIND operations will be guaranteedto
+complete in the order they were submitted, but that is not the case
+forVM_BINDoperations executing on separateVM_BINDcontexts. Instead
+KMD will attempt to execute suchVM_BINDoperations in parallel butDocumentation/gpu/drm-vm-bind-async.rst new file +2
-0+leaving no guarantee that they will actually be executed in +parallel. There may be internal implicit dependencies that onlyKMD knows
Documentation/gpu/drm-vm-bind-async.rst new file +5
-0+about, for example page-table structure changes. A way to attempt +to avoid such internal dependencies is to have different VM_BIND +contexts use separate regions of a VM. + +Also for VM_BINDS for long-running gpu_vms the user-mode drivershould typically
+select memory fences as out-fences since that gives greater flexibility forDocumentation/gpu/drm-vm-bind-async.rst new file +2
-0+the kernel mode driver to inject other operations into the bind / +unbind operations. Like for example inserting breakpoints intobatch
+buffers. The workload execution can then easily be pipelined behind
+the bind completion using the memory out-fence as the signal conditionDocumentation/gpu/drm-vm-bind-async.rst new file +4
-0+for a GPU semaphore embedded by UMD in the workload. + +There is no difference in the operations supported or in +multi-operation support between asynchronous VM_BIND andsynchronous
VM_BIND.Documentation/gpu/drm-vm-bind-async.rst new file +5
-0+ +Multi-operation VM_BIND IOCTL error handling and interrupts +=========================================================== + +The VM_BIND operations of the IOCTL may error for various reasons,for
+example due to lack of resources to complete and due to interruptedDocumentation/gpu/drm-vm-bind-async.rst new file +4
-0+waits. +In these situations UMD should preferably restart the IOCTL after +taking suitable action. +If UMD has over-committed a memory resource, an -ENOSPC error willbe
+returned, and UMD may then unbind resources that are not used at theDocumentation/gpu/drm-vm-bind-async.rst new file +4
-0+moment and rerun the IOCTL. On -EINTR, UMD should simply rerun the +IOCTL and on -ENOMEM user-space may either attempt to free known +system memory resources or fail. In case of UMD deciding to fail a +bind operation, due to an error return, no additional action isneeded
+to clean up the failed operation, and the VM is left in the same stateDocumentation/gpu/drm-vm-bind-async.rst new file +5
-0+as it was before the failing IOCTL. +Unbind operations are guaranteed not to return any errors due to +resource constraints, but may return errors due to, for example, +invalid arguments or the gpu_vm being banned. +In the case an unexpected error happens during the asynchronousbind
+process, thegpu_vmwill be banned, and attempts to use it after banningDocumentation/gpu/drm-vm-bind-async.rst new file +6
-0+will return -ENOENT. + +Example: The Xe VM_BIND uAPI +============================ + +Starting with the VM_BIND operation struct, the IOCTL call cantake
Documentation/gpu/drm-vm-bind-async.rst new file +3
-0+zero, one or many such operations. A zero number means only the +synchronization part of the IOCTL is carried out: an asynchronous +VM_BIND updates the syncobjects, whereas a sync VM_BIND waits forthe
Documentation/gpu/drm-vm-bind-async.rst new file +7
-0+implicit dependencies to be fulfilled. + +.. code-block:: c + + struct drm_xe_vm_bind_op { + /** + * @obj: GEM object to operate on, MBZ for MAP_USERPTR, MBZfor UNMAP
+ */
+ __u32 obj;Documentation/gpu/drm-vm-bind-async.rst new file +11
-0+ + /** @pad: MBZ */ + __u32 pad; + + union { + /** + * @obj_offset: Offset into the object for MAP. + */ + __u64 obj_offset; + + /** @userptr: user virtual address for MAP_USERPTR*/
+ __u64 userptr;
+ };
+
+ /**
+ * @range: Number of bytes from the object to bind to addr, MBZ forUNMAP_ALL
+ */
+ __u64 range;Documentation/gpu/drm-vm-bind-async.rst new file +6
-0+ + /** @addr: Address to operate on, MBZ for UNMAP_ALL */ + __u64 addr; + + /** + * @tile_mask: Mask for which tiles to create binds for, 0== All tiles,
+ * only applies to creating new VMAs
+ */
+ __u64tile_mask;
+
+ /* Map (parts of) an object into the GPU virtual address range.
+ #define XE_VM_BIND_OP_MAP 0x0
+ /* Unmap a GPU virtual address range */
+ #define XE_VM_BIND_OP_UNMAP 0x1
+ /*
+ * Map a CPU virtual address range into a GPU virtual + * address range.
+ */
+ #define XE_VM_BIND_OP_MAP_USERPTR 0x2
+ /* Unmap a gem object from the VM. */
+ #define XE_VM_BIND_OP_UNMAP_ALL 0x3
+ /*
+ * Make the backing memory of an address range resident if + * possible. Note that this doesn't pin backing memory. + */
+ #define XE_VM_BIND_OP_PREFETCH 0x4
+
+ /* Make the GPU map readonly. */
+ #define XE_VM_BIND_FLAG_READONLY (0x1 << 16)
+ /*
+ * Valid on a faulting VM only, do the MAP operation immediately rather
+ * than deferring the MAP to the page fault handler. + */
+ #define XE_VM_BIND_FLAG_IMMEDIATE (0x1 << 17)
+ /*
+ * 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. In
+ * the future, the NULL flags will only be valid forXE_VM_BIND_OP_MAP
+ * operations, the BO handle MBZ, and the BO offset MBZ. This flag is
+ * intended to implement VK sparse bindings.
+ */
+ #define XE_VM_BIND_FLAG_NULL (0x1 << 18)
+ /** @op: Operation to perform (lower 16 bits) and flags (upper 16 bits) */
+ __u32 op;
+
+ /** @mem_region: Memory region to prefetch VMA to, instance not a mask */
+ __u32 region;Documentation/gpu/drm-vm-bind-async.rst new file +7
-0+ + /** @reserved: Reserved */ + __u64 reserved[2]; + }; + + +The VM_BIND IOCTL argument itself, looks like follows. Note thatfor
+synchronousVM_BIND, thenum_syncsand syncs fields must be zero. Here
+the ``exec_queue_id`` field is theVM_BINDcontext discussed previouslyDocumentation/gpu/drm-vm-bind-async.rst new file +6
-0+that is used to facilitate out-of-order VM_BINDs. + +.. code-block:: c + + struct drm_xe_vm_bind { + /** @extensions: Pointer to the first extension struct, ifany */
+ __u64 extensions;Documentation/gpu/drm-vm-bind-async.rst new file +6
-0+ + /** @vm_id: The ID of the VM to bind to */ + __u32 vm_id; + + /** + * @exec_queue_id: exec_queue_id, must be of class
DRM_XE_ENGINE_CLASS_VM_BIND
+ * and exec queue must have samevm_id. If zero, the default VM bind engine
+ * is used.
+ */
+ __u32exec_queue_id;Documentation/gpu/drm-vm-bind-async.rst new file +5
-0+ + /** @num_binds: number of binds in this IOCTL */ + __u32 num_binds; + + /* If set, perform an async VM_BIND, if clear a sync
VM_BIND*/
+ #define XE_VM_BIND_IOCTL_FLAG_ASYNC (0x1 << 0) +
+ /** @flag: Flags controlling all operations in this ioctl. */
+ __u32 flags;Documentation/gpu/drm-vm-bind-async.rst new file +13
-0+ + union { + /** @bind: used if num_binds == 1 */ + struct drm_xe_vm_bind_op bind; + + /** + * @vector_of_binds: userptr to array of struct + * drm_xe_vm_bind_op if num_binds > 1 + */ + __u64 vector_of_binds; + }; + + /** @num_syncs: amount of syncs to wait for or to signal oncompletion. */
+ __u32num_syncs;Documentation/gpu/drm-vm-bind-async.rst new file +10
-0+ + /** @pad2: MBZ */ + __u32 pad2; + + /** @syncs: pointer to struct drm_xe_sync array */ + __u64 syncs; + + /** @reserved: Reserved */ + __u64 reserved[2]; + };Documentation/gpu/implementation_guidelines.rst new file +9
-0@@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT) + +=========================================================== +Misc DRM driver uAPI- and feature implementation guidelines +=========================================================== + +.. toctree:: + + drm-vm-bind-asyncDocumentation/gpu/index.rst +0
-0@@ -18,6 +18,7 @@ GPU Driver Developer's Guidevga-switcheroo
vgaarbiter
automated_testing
+implementation_guidelines
todo
rfc/indexDocumentation/gpu/rfc/xe.rst +0
-0@@ -97,8 +97,8 @@ memory fences. Ideally with helper support sopeople don't get it wrong in all
possible ways.
As a key measurable result, the benefits of ASYNCVM_BINDand a discussion of
-various flavors, error handling and a sample API should be documented here or inDocumentation/gpu/rfc/xe.rst +1
-1-a separate document pointed to by this document. +various flavors, error handling and sample API suggestions aredocumented in
+:doc:The ASYNC VM_BIND document </gpu/drm-vm-bind-async>.
Userptr integration andvm_bind
-------------------------------