[PATCH v1 11/14] drm/xe/uapi: Add block diagram of a device

[Souza, Jose]

On Thu, 2023-12-07 at 13:50 +0000, Francois Dugast wrote:
> In order to make proper use the uAPI, a prerequisite is to understand
> some key concepts about the discrete GPU devices which are supported
> by the Xe driver. For example, some structs defined in the uAPI are an
> abstraction of a hardware component with a specific role.
> 
> This diagram helps to build a mental representation of a device how it
> is seen by the Xe driver. As written in the documentation, it does not
> intend to be a literal representation of an existing device. A lot
> more information could be added but the intention for the overview is
> to keep it simple, and go into detail as needed in other sections.
> 
> v2: Add GT1 inside Tile0 (José Roberto de Souza)
> 

Reviewed-by: José Roberto de Souza <jose.souza at intel.com>

> Signed-off-by: Francois Dugast <francois.dugast at intel.com>
> ---
>  include/uapi/drm/xe_drm.h | 39 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 39 insertions(+)
> 
> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
> index 73e9d00a2111..b5117bc1f13c 100644
> --- a/include/uapi/drm/xe_drm.h
> +++ b/include/uapi/drm/xe_drm.h
> @@ -25,6 +25,45 @@ extern "C" {
>   *   6. PMU
>   */
>  
> +/**
> + * DOC: Xe Device Block Diagram
> + *
> + * The diagram below represents a high-level simplification of a discrete
> + * GPU supported by the Xe driver. It shows some device components which
> + * are necessary to understand this API, as well as how their relations
> + * to each other. This diagram does not represent real hardware::
> + *
> + *   ┌──────────────────────────────────────────────────────────────────┐
> + *   │ ┌──────────────────────────────────────────────────┐ ┌─────────┐ │
> + *   │ │        ┌───────────────────────┐   ┌─────┐       │ │ ┌─────┐ │ │
> + *   │ │        │         VRAM0         ├───┤ ... │       │ │ │VRAM1│ │ │
> + *   │ │        └───────────┬───────────┘   └─GT1─┘       │ │ └──┬──┘ │ │
> + *   │ │ ┌──────────────────┴───────────────────────────┐ │ │ ┌──┴──┐ │ │
> + *   │ │ │ ┌─────────────────────┐  ┌─────────────────┐ │ │ │ │     │ │ │
> + *   │ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
> + *   │ │ │ │ │EU│ │EU│ │EU│ │EU│ │  │ │RCS0 │ │BCS0 │ │ │ │ │ │     │ │ │
> + *   │ │ │ │ └──┘ └──┘ └──┘ └──┘ │  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
> + *   │ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
> + *   │ │ │ │ │EU│ │EU│ │EU│ │EU│ │  │ │VCS0 │ │VCS1 │ │ │ │ │ │     │ │ │
> + *   │ │ │ │ └──┘ └──┘ └──┘ └──┘ │  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
> + *   │ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
> + *   │ │ │ │ │EU│ │EU│ │EU│ │EU│ │  │ │VECS0│ │VECS1│ │ │ │ │ │ ... │ │ │
> + *   │ │ │ │ └──┘ └──┘ └──┘ └──┘ │  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
> + *   │ │ │ │ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
> + *   │ │ │ │ │EU│ │EU│ │EU│ │EU│ │  │ │CCS0 │ │CCS1 │ │ │ │ │ │     │ │ │
> + *   │ │ │ │ └──┘ └──┘ └──┘ └──┘ │  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
> + *   │ │ │ └─────────DSS─────────┘  │ ┌─────┐ ┌─────┐ │ │ │ │ │     │ │ │
> + *   │ │ │                          │ │CCS2 │ │CCS3 │ │ │ │ │ │     │ │ │
> + *   │ │ │ ┌─────┐ ┌─────┐ ┌─────┐  │ └─────┘ └─────┘ │ │ │ │ │     │ │ │
> + *   │ │ │ │ ... │ │ ... │ │ ... │  │                 │ │ │ │ │     │ │ │
> + *   │ │ │ └─DSS─┘ └─DSS─┘ └─DSS─┘  └─────Engines─────┘ │ │ │ │     │ │ │
> + *   │ │ └───────────────────────────GT0────────────────┘ │ │ └─GT2─┘ │ │
> + *   │ └────────────────────────────Tile0─────────────────┘ └─ Tile1──┘ │
> + *   └─────────────────────────────Device0───────┬──────────────────────┘
> + *                                               │
> + *                        ───────────────────────┴────────── PCI bus
> + */
> +
>  /**
>   * DOC: Xe uAPI Overview
>   *