[Intel-xe] [PATCH v2 30/30] drm/xe: Add kerneldoc description of multi-tile devices

[Matt Roper]

On Fri, May 26, 2023 at 03:52:16PM -0700, Lucas De Marchi wrote:
> On Fri, May 19, 2023 at 04:18:27PM -0700, Matt Roper wrote:
> > Signed-off-by: Matt Roper <matthew.d.roper at intel.com>
> > ---
> > Documentation/gpu/xe/index.rst   |  1 +
> > Documentation/gpu/xe/xe_tile.rst | 14 ++++++++
> > drivers/gpu/drm/xe/xe_tile.c     | 57 ++++++++++++++++++++++++++++++++
> > 3 files changed, 72 insertions(+)
> > create mode 100644 Documentation/gpu/xe/xe_tile.rst
> > 
> > diff --git a/Documentation/gpu/xe/index.rst b/Documentation/gpu/xe/index.rst
> > index 2fddf9ed251e..5c4d6bb370f3 100644
> > --- a/Documentation/gpu/xe/index.rst
> > +++ b/Documentation/gpu/xe/index.rst
> > @@ -21,3 +21,4 @@ DG2, etc is provided to prototype the driver.
> >    xe_wa
> >    xe_rtp
> >    xe_firmware
> > +   xe_tile
> > diff --git a/Documentation/gpu/xe/xe_tile.rst b/Documentation/gpu/xe/xe_tile.rst
> > new file mode 100644
> > index 000000000000..c33f68dd95b6
> > --- /dev/null
> > +++ b/Documentation/gpu/xe/xe_tile.rst
> > @@ -0,0 +1,14 @@
> > +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> > +
> > +==================
> > +Multi-tile Devices
> > +==================
> > +
> > +.. kernel-doc:: drivers/gpu/drm/xe/xe_tile.c
> > +   :doc: Multi-tile Design
> > +
> > +Internal API
> > +============
> > +
> > +.. kernel-doc:: drivers/gpu/drm/xe/xe_tile.c
> > +   :internal:
> > diff --git a/drivers/gpu/drm/xe/xe_tile.c b/drivers/gpu/drm/xe/xe_tile.c
> > index 908eec5c17d9..d2654b78cfb4 100644
> > --- a/drivers/gpu/drm/xe/xe_tile.c
> > +++ b/drivers/gpu/drm/xe/xe_tile.c
> > @@ -12,6 +12,63 @@
> > #include "xe_tile.h"
> > #include "xe_ttm_vram_mgr.h"
> > 
> > +/**
> > + * DOC: Multi-tile Design
> > + *
> > + * Different vendors use the term "tile" a bit differently, but in the Intel
> > + * world, a 'tile' is pretty close to what most people would think of as being
> > + * a complete GPU.  When multiple GPUs are placed behind a single PCI device,
> > + * that's what is referred to as a "multi-tile device."  In such cases, pretty
> > + * much all hardware is replicated per-tile, although certain responsibilities
> > + * like PCI communication, reporting of interrupts to the OS, etc. are handled
> > + * solely by the "root tile."  A multi-tile platform takes care of tying the
> 
> ". instead of ."

Actually this one is correct as-is; periods at the end of sentences
always go inside the quotation marks (at least in English; not sure
about other languages).
https://www.grammar.com/periods-with-quotation-marks/

> 
> > + * tiles together in a way such that interrupt notifications from remote tiles
> > + * are forwarded to the root tile, the per-tile vram is combined into a single
> > + * address space, etc.
> > + *
> > + * In contrast, a "GT" (which officially stands for "Graphics Technology") is
> > + * the subset of a GPU/tile that is responsible for implementing graphics
> > + * and/or media operations.  The GT is where a lot of the driver implementation
> > + * happens since it's where the hardware engines, the execution units, and the
> > + * GuC all reside.
> > + *
> > + * Historically most Intel devices were single-tile devices that contained a
> > + * single GT.  PVC is an example of an Intel platform built on a multi-tile
> > + * design (i.e., multiple GPUs behind a single PCI device); each PVC tile only
> > + * has a single GT.  In contrast, platforms like MTL that have separate chips
> > + * for render and media IP are still only a single logical GPU, but the
> > + * graphics and media IP blocks are exposed each exposed as a separate GT
> 
> too many exposed words here

Good catch, thanks.


Matt

> 
> other than that,
> 
> 	
> Reviewed-by: Lucas De Marchi <lucas.demarchi at intel.com>
> 
> thanks
> Lucas De Marchi
> 
> > + * within that single GPU.  This is important from a software perspective
> > + * because multi-GT platforms like MTL only replicate a subset of the GPU
> > + * hardware and behave differently than multi-tile platforms like PVC where
> > + * nearly everything is replicated.
> > + *
> > + * Per-tile functionality (shared by all GTs within the tile):
> > + *  - Complete 4MB MMIO space (containing SGunit/SoC registers, GT
> > + *    registers, display registers, etc.)
> > + *  - Global GTT
> > + *  - VRAM (if discrete)
> > + *  - Interrupt flows
> > + *  - Migration context
> > + *  - kernel batchbuffer pool
> > + *  - Primary GT
> > + *  - Media GT (if media version >= 13)
> > + *
> > + * Per-GT functionality:
> > + *  - GuC
> > + *  - Hardware engines
> > + *  - Programmable hardware units (subslices, EUs)
> > + *  - GSI subset of registers (multiple copies of these registers reside
> > + *    within the complete MMIO space provided by the tile, but at different
> > + *    offsets --- 0 for render, 0x380000 for media)
> > + *  - Multicast register steering
> > + *  - TLBs to cache page table translations
> > + *  - Reset capability
> > + *  - Low-level power management (e.g., C6)
> > + *  - Clock frequency
> > + *  - MOCS and PAT programming
> > + */
> > +
> > /**
> >  * xe_tile_alloc - Perform per-tile memory allocation
> >  * @tile: Tile to perform allocations for
> > -- 
> > 2.40.0
> > 

-- 
Matt Roper
Graphics Software Engineer
Linux GPU Platform Enablement
Intel Corporation