[PATCH 5/6] Documentation/gpu: Create a GC entry in the amdgpu documentation

[Christian König]

Am 25.03.25 um 18:18 schrieb Rodrigo Siqueira:
> GC is a large block that plays a vital role for amdgpu; for this reason,
> this commit creates one specific page for GC and adds extra information
> about the CP component.
>
> Signed-off-by: Rodrigo Siqueira <siqueira at igalia.com>

Acked-by: <christian.koenig at amd.com>

> ---
>  Documentation/gpu/amdgpu/driver-core.rst | 30 ++-------------
>  Documentation/gpu/amdgpu/gc/index.rst    | 48 ++++++++++++++++++++++++
>  Documentation/gpu/amdgpu/index.rst       |  1 +
>  3 files changed, 53 insertions(+), 26 deletions(-)
>  create mode 100644 Documentation/gpu/amdgpu/gc/index.rst
>
> diff --git a/Documentation/gpu/amdgpu/driver-core.rst b/Documentation/gpu/amdgpu/driver-core.rst
> index 746fd081876f..2af1e919d76a 100644
> --- a/Documentation/gpu/amdgpu/driver-core.rst
> +++ b/Documentation/gpu/amdgpu/driver-core.rst
> @@ -67,38 +67,16 @@ GC (Graphics and Compute)
>      This is the graphics and compute engine, i.e., the block that
>      encompasses the 3D pipeline and and shader blocks.  This is by far the
>      largest block on the GPU.  The 3D pipeline has tons of sub-blocks.  In
> -    addition to that, it also contains the CP microcontrollers (ME, PFP,
> -    CE, MEC) and the RLC microcontroller.  It's exposed to userspace for
> -    user mode drivers (OpenGL, Vulkan, OpenCL, etc.)
> +    addition to that, it also contains the CP microcontrollers (ME, PFP, CE,
> +    MEC) and the RLC microcontroller.  It's exposed to userspace for user mode
> +    drivers (OpenGL, Vulkan, OpenCL, etc.). More details in :ref:`Graphics (GFX)
> +    and Compute <amdgpu-gc>`.
>  
>  VCN (Video Core Next)
>      This is the multi-media engine.  It handles video and image encode and
>      decode.  It's exposed to userspace for user mode drivers (VA-API,
>      OpenMAX, etc.)
>  
> -Graphics and Compute Microcontrollers
> --------------------------------------
> -
> -CP (Command Processor)
> -    The name for the hardware block that encompasses the front end of the
> -    GFX/Compute pipeline.  Consists mainly of a bunch of microcontrollers
> -    (PFP, ME, CE, MEC).  The firmware that runs on these microcontrollers
> -    provides the driver interface to interact with the GFX/Compute engine.
> -
> -    MEC (MicroEngine Compute)
> -        This is the microcontroller that controls the compute queues on the
> -        GFX/compute engine.
> -
> -    MES (MicroEngine Scheduler)
> -        This is a new engine for managing queues.  This is currently unused.
> -
> -RLC (RunList Controller)
> -    This is another microcontroller in the GFX/Compute engine.  It handles
> -    power management related functionality within the GFX/Compute engine.
> -    The name is a vestige of old hardware where it was originally added
> -    and doesn't really have much relation to what the engine does now.
> -
> -
>  GFX, Compute, and SDMA Overall Behavior
>  =======================================
>  
> diff --git a/Documentation/gpu/amdgpu/gc/index.rst b/Documentation/gpu/amdgpu/gc/index.rst
> new file mode 100644
> index 000000000000..f8128cca7028
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu/gc/index.rst
> @@ -0,0 +1,48 @@
> +.. _amdgpu-gc:
> +
> +========================================
> + drm/amdgpu - Graphics and Compute (GC)
> +========================================
> +
> +The relationship between the CPU and GPU can be described as the
> +producer-consumer problem, where the CPU fills out a buffer with operations
> +(producer) to be executed by the GPU (consumer). The requested operations in
> +the buffer are called Command Packets, which can be summarized as a compressed
> +way of transmitting command information to the graphics controller.
> +
> +The component that acts as the front end between the CPU and the GPU is called
> +the Command Processor (CP). This component is responsible for providing greater
> +flexibility to the GC since CP makes it possible to program various aspects of
> +the GPU pipeline. CP also coordinates the communication between the CPU and GPU
> +via a mechanism named **Ring Buffers**, where the CPU appends information to
> +the buffer while the GPU removes operations. It is relevant to highlight that a
> +CPU can add a pointer to the Ring Buffer that points to another region of
> +memory outside the Ring Buffer, and CP can handle it; this mechanism is called
> +**Indirect Buffer (IB)**. CP receives and parses the Command Streams (CS), and
> +according to the parser result, the CP writes the request for operations in the
> +correct block.
> +
> +Graphics (GFX) and Compute Microcontrollers
> +-------------------------------------------
> +
> +GC is a large block, and as a result, it has multiple firmware associated with
> +it. Some of them are:
> +
> +CP (Command Processor)
> +    The name for the hardware block that encompasses the front end of the
> +    GFX/Compute pipeline. Consists mainly of a bunch of microcontrollers
> +    (PFP, ME, CE, MEC). The firmware that runs on these microcontrollers
> +    provides the driver interface to interact with the GFX/Compute engine.
> +
> +    MEC (MicroEngine Compute)
> +        This is the microcontroller that controls the compute queues on the
> +        GFX/compute engine.
> +
> +    MES (MicroEngine Scheduler)
> +        This is the engine for managing queues.
> +
> +RLC (RunList Controller)
> +    This is another microcontroller in the GFX/Compute engine. It handles
> +    power management related functionality within the GFX/Compute engine.
> +    The name is a vestige of old hardware where it was originally added
> +    and doesn't really have much relation to what the engine does now.
> diff --git a/Documentation/gpu/amdgpu/index.rst b/Documentation/gpu/amdgpu/index.rst
> index 7e9d60754287..1624f4b588c5 100644
> --- a/Documentation/gpu/amdgpu/index.rst
> +++ b/Documentation/gpu/amdgpu/index.rst
> @@ -10,6 +10,7 @@ Next (GCN), Radeon DNA (RDNA), and Compute DNA (CDNA) architectures.
>     driver-core
>     amd-hardware-list-info
>     module-parameters
> +   gc/index
>     display/index
>     flashing
>     xgmi