diff mbox series

[v10,20/23] drm/i915/vm_bind: Render VM_BIND documentation

Message ID 20230118071609.17572-21-niranjana.vishwanathapura@intel.com (mailing list archive)
State New, archived
Headers show
Series drm/i915/vm_bind: Add VM_BIND functionality | expand

Commit Message

Niranjana Vishwanathapura Jan. 18, 2023, 7:16 a.m. UTC 
Update i915 documentation to include VM_BIND changes
and render all VM_BIND related documentation.

Reviewed-by: Matthew Auld <matthew.auld@intel.com>
Signed-off-by: Niranjana Vishwanathapura <niranjana.vishwanathapura@intel.com>
---
 Documentation/gpu/i915.rst | 78 ++++++++++++++++++++++++++++----------
 1 file changed, 59 insertions(+), 19 deletions(-)

Comments

Andi Shyti Feb. 2, 2023, 4:38 p.m. UTC | #1 
Hi Niranjana,

On Tue, Jan 17, 2023 at 11:16:06PM -0800, Niranjana Vishwanathapura wrote:
> Update i915 documentation to include VM_BIND changes
> and render all VM_BIND related documentation.
> 
> Reviewed-by: Matthew Auld <matthew.auld@intel.com>
> Signed-off-by: Niranjana Vishwanathapura <niranjana.vishwanathapura@intel.com>

looks good!

Reviewed-by: Andi Shyti <andi.shyti@linux.intel.com>

Andi

> ---
>  Documentation/gpu/i915.rst | 78 ++++++++++++++++++++++++++++----------
>  1 file changed, 59 insertions(+), 19 deletions(-)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 60ea21734902..01429a8f0d6c 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -283,15 +283,18 @@ An Intel GPU has multiple engines. There are several engine types.
>  
>  The Intel GPU family is a family of integrated GPU's using Unified
>  Memory Access. For having the GPU "do work", user space will feed the
> -GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2`
> -or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will
> -instruct the GPU to perform work (for example rendering) and that work
> -needs memory from which to read and memory to which to write. All memory
> -is encapsulated within GEM buffer objects (usually created with the ioctl
> -`DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU
> -to create will also list all GEM buffer objects that the batchbuffer reads
> -and/or writes. For implementation details of memory management see
> -`GEM BO Management Implementation Details`_.
> +GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2`,
> +`DRM_IOCTL_I915_GEM_EXECBUFFER2_WR` or `DRM_IOCTL_I915_GEM_EXECBUFFER3`.
> +Most such batchbuffers will instruct the GPU to perform work (for example
> +rendering) and that work needs memory from which to read and memory to
> +which to write. All memory is encapsulated within GEM buffer objects
> +(usually created with the ioctl `DRM_IOCTL_I915_GEM_CREATE`). In vm_bind mode
> +(see `VM_BIND mode`_), the batch buffer and all the GEM buffer objects that
> +it reads and/or writes should be bound with vm_bind ioctl before submitting
> +the batch buffer to GPU. In legacy (non-VM_BIND) mode, an ioctl providing a
> +batchbuffer for the GPU to create will also list all GEM buffer objects that
> +the batchbuffer reads and/or writes. For implementation details of memory
> +management see `GEM BO Management Implementation Details`_.
>  
>  The i915 driver allows user space to create a context via the ioctl
>  `DRM_IOCTL_I915_GEM_CONTEXT_CREATE` which is identified by a 32-bit
> @@ -309,8 +312,9 @@ In addition to the ordering guarantees, the kernel will restore GPU
>  state via HW context when commands are issued to a context, this saves
>  user space the need to restore (most of atleast) the GPU state at the
>  start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer
> -work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1)
> -to identify what context to use with the command.
> +work can pass that ID (drm_i915_gem_execbuffer3::ctx_id, or in the lower
> +bits of drm_i915_gem_execbuffer2::rsvd1) to identify what context to use
> +with the command.
>  
>  The GPU has its own memory management and address space. The kernel
>  driver maintains the memory translation table for the GPU. For older
> @@ -318,14 +322,14 @@ GPUs (i.e. those before Gen8), there is a single global such translation
>  table, a global Graphics Translation Table (GTT). For newer generation
>  GPUs each context has its own translation table, called Per-Process
>  Graphics Translation Table (PPGTT). Of important note, is that although
> -PPGTT is named per-process it is actually per context. When user space
> -submits a batchbuffer, the kernel walks the list of GEM buffer objects
> -used by the batchbuffer and guarantees that not only is the memory of
> -each such GEM buffer object resident but it is also present in the
> -(PP)GTT. If the GEM buffer object is not yet placed in the (PP)GTT,
> -then it is given an address. Two consequences of this are: the kernel
> -needs to edit the batchbuffer submitted to write the correct value of
> -the GPU address when a GEM BO is assigned a GPU address and the kernel
> +PPGTT is named per-process it is actually per context. In legacy
> +(non-vm_bind) mode, when user space submits a batchbuffer, the kernel walks
> +the list of GEM buffer objects used by the batchbuffer and guarantees that
> +not only is the memory of each such GEM buffer object resident but it is
> +also present in the (PP)GTT. If the GEM buffer object is not yet placed in
> +the (PP)GTT, then it is given an address. Two consequences of this are: the
> +kernel needs to edit the batchbuffer submitted to write the correct value
> +of the GPU address when a GEM BO is assigned a GPU address and the kernel
>  might evict a different GEM BO from the (PP)GTT to make address room
>  for another GEM BO. Consequently, the ioctls submitting a batchbuffer
>  for execution also include a list of all locations within buffers that
> @@ -407,6 +411,15 @@ objects, which has the goal to make space in gpu virtual address spaces.
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c
>     :internal:
>  
> +VM_BIND mode
> +------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_vm_bind_object.c
> +   :doc: VM_BIND/UNBIND ioctls
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_vm_bind_object.c
> +   :internal:
> +
>  Batchbuffer Parsing
>  -------------------
>  
> @@ -419,11 +432,38 @@ Batchbuffer Parsing
>  User Batchbuffer Execution
>  --------------------------
>  
> +Client state
> +~~~~~~~~~~~~
> +
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_context_types.h
>  
> +User command execution
> +~~~~~~~~~~~~~~~~~~~~~~
> +
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c
>     :doc: User command execution
>  
> +User command execution in vm_bind mode
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer3.c
> +   :doc: User command execution in vm_bind mode
> +
> +Common execbuff utilities
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer_common.h
> +   :internal:
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer_common.c
> +   :internal:
> +
> +Execbuf3 ioctl path
> +~~~~~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer3.c
> +   :internal:
> +
>  Scheduling
>  ----------
>  .. kernel-doc:: drivers/gpu/drm/i915/i915_scheduler_types.h
> -- 
> 2.21.0.rc0.32.g243a4c7e27
diff mbox series

Patch

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 60ea21734902..01429a8f0d6c 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -283,15 +283,18 @@  An Intel GPU has multiple engines. There are several engine types.
 
 The Intel GPU family is a family of integrated GPU's using Unified
 Memory Access. For having the GPU "do work", user space will feed the
-GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2`
-or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will
-instruct the GPU to perform work (for example rendering) and that work
-needs memory from which to read and memory to which to write. All memory
-is encapsulated within GEM buffer objects (usually created with the ioctl
-`DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU
-to create will also list all GEM buffer objects that the batchbuffer reads
-and/or writes. For implementation details of memory management see
-`GEM BO Management Implementation Details`_.
+GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2`,
+`DRM_IOCTL_I915_GEM_EXECBUFFER2_WR` or `DRM_IOCTL_I915_GEM_EXECBUFFER3`.
+Most such batchbuffers will instruct the GPU to perform work (for example
+rendering) and that work needs memory from which to read and memory to
+which to write. All memory is encapsulated within GEM buffer objects
+(usually created with the ioctl `DRM_IOCTL_I915_GEM_CREATE`). In vm_bind mode
+(see `VM_BIND mode`_), the batch buffer and all the GEM buffer objects that
+it reads and/or writes should be bound with vm_bind ioctl before submitting
+the batch buffer to GPU. In legacy (non-VM_BIND) mode, an ioctl providing a
+batchbuffer for the GPU to create will also list all GEM buffer objects that
+the batchbuffer reads and/or writes. For implementation details of memory
+management see `GEM BO Management Implementation Details`_.
 
 The i915 driver allows user space to create a context via the ioctl
 `DRM_IOCTL_I915_GEM_CONTEXT_CREATE` which is identified by a 32-bit
@@ -309,8 +312,9 @@  In addition to the ordering guarantees, the kernel will restore GPU
 state via HW context when commands are issued to a context, this saves
 user space the need to restore (most of atleast) the GPU state at the
 start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer
-work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1)
-to identify what context to use with the command.
+work can pass that ID (drm_i915_gem_execbuffer3::ctx_id, or in the lower
+bits of drm_i915_gem_execbuffer2::rsvd1) to identify what context to use
+with the command.
 
 The GPU has its own memory management and address space. The kernel
 driver maintains the memory translation table for the GPU. For older
@@ -318,14 +322,14 @@  GPUs (i.e. those before Gen8), there is a single global such translation
 table, a global Graphics Translation Table (GTT). For newer generation
 GPUs each context has its own translation table, called Per-Process
 Graphics Translation Table (PPGTT). Of important note, is that although
-PPGTT is named per-process it is actually per context. When user space
-submits a batchbuffer, the kernel walks the list of GEM buffer objects
-used by the batchbuffer and guarantees that not only is the memory of
-each such GEM buffer object resident but it is also present in the
-(PP)GTT. If the GEM buffer object is not yet placed in the (PP)GTT,
-then it is given an address. Two consequences of this are: the kernel
-needs to edit the batchbuffer submitted to write the correct value of
-the GPU address when a GEM BO is assigned a GPU address and the kernel
+PPGTT is named per-process it is actually per context. In legacy
+(non-vm_bind) mode, when user space submits a batchbuffer, the kernel walks
+the list of GEM buffer objects used by the batchbuffer and guarantees that
+not only is the memory of each such GEM buffer object resident but it is
+also present in the (PP)GTT. If the GEM buffer object is not yet placed in
+the (PP)GTT, then it is given an address. Two consequences of this are: the
+kernel needs to edit the batchbuffer submitted to write the correct value
+of the GPU address when a GEM BO is assigned a GPU address and the kernel
 might evict a different GEM BO from the (PP)GTT to make address room
 for another GEM BO. Consequently, the ioctls submitting a batchbuffer
 for execution also include a list of all locations within buffers that
@@ -407,6 +411,15 @@  objects, which has the goal to make space in gpu virtual address spaces.
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c
    :internal:
 
+VM_BIND mode
+------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_vm_bind_object.c
+   :doc: VM_BIND/UNBIND ioctls
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_vm_bind_object.c
+   :internal:
+
 Batchbuffer Parsing
 -------------------
 
@@ -419,11 +432,38 @@  Batchbuffer Parsing
 User Batchbuffer Execution
 --------------------------
 
+Client state
+~~~~~~~~~~~~
+
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_context_types.h
 
+User command execution
+~~~~~~~~~~~~~~~~~~~~~~
+
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c
    :doc: User command execution
 
+User command execution in vm_bind mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer3.c
+   :doc: User command execution in vm_bind mode
+
+Common execbuff utilities
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer_common.h
+   :internal:
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer_common.c
+   :internal:
+
+Execbuf3 ioctl path
+~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer3.c
+   :internal:
+
 Scheduling
 ----------
 .. kernel-doc:: drivers/gpu/drm/i915/i915_scheduler_types.h