[Intel-gfx] [PATCH i-g-t 2/2] lib/igt_kms: Short description between Intel/DRM terminology.

[Ville Syrjälä]

On Fri, Jan 15, 2016 at 11:06:42AM +0200, Marius Vlad wrote:
> lib/igt_kms: Briefly describe Intel-to-DRM mapping between pipes, encoders and
> connectors.
> 
> Signed-off-by: Marius Vlad <marius.c.vlad at intel.com>
> ---
>  lib/igt_kms.c | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 82 insertions(+)
> 
> diff --git a/lib/igt_kms.c b/lib/igt_kms.c
> index c7a0b77..caa8837 100644
> --- a/lib/igt_kms.c
> +++ b/lib/igt_kms.c
> @@ -68,6 +68,88 @@
>   * functions have all igt_ prefixes. This part is still very much work in
>   * progress and so also lacks a bit documentation for the individual functions.
>   *
> + * Intel/DRM terminology and display connections:
> + *
> + * Intel documentation describes the road from memory to an output connector as
> + * follows:
> + *
> + * |[!<-- language="C" -->
> + * .--------.     .-------.     .-------------.     .-----.
> + * | Memory |---->| Pipes |---->| Transcoders |---->| DDI |
> + * '--------'     '-------'     '-------------'     '-----'
> + * ]|
> + *
> + * Pipes represent the front-end of the display contain the planes, blending,
> + * and color correction, while the transcoders contain timing generators,
> + * encoders, A/V mixers and PSR (Panel-Self Refresh) controllers. Finally the
> + * DDI represent the connectors attached to the display.
> + *
> + *
> + *  In DRM we have the following:
> + *
> + * |[!<-- language="C" -->
> + * .-----------.     .-------.     .-----------.     .------------.
> + * | Framebuff |---->| Pipes |---->| Encoders  |---->| Connectors |
> + * '-----------'     '-------'     '-----------'     '------------'

"Framebuff"?

Also should this say crtc instead of pipe?

> + * ]|
> + *
> + *
> + * The frame buffer ties a reference to a memory object and provides a pointer
> + * to the actual data.
> + *
> + * The pipe is used to set the display mode, timings and gamma tables. On some
> + * hardware models this is tied with the transcoder.  In DRM-parlance this is
> + * referred as a CRTC.
> + *
> + * Each pipe has multiple planes. On older hardware these planes where known as
> + * primary plane, overlay/sprite plane, and cursor plane. From GEN9 (SKL/BXT)
> + * each pipe has three planes and a cursor plane.

Not quite true.

> Each plane can be used as a
> + * primary, as a sprite or as an overlay plane. The planes are the ones that
> + * retrieve the pixels from memory and pushes them to the encoder.
> + *
> + * A pipe prior to GEN9:

Really more like g4x-bdw. Before g4x it was totally different, and gen4 was
sort of mix of both the old and the new. And vlv/chv have two sprites on
each pipe.

So given all the variations in the hardware, and the fact that it keeps
changing all the time, I'm not convinced there's any point in
documenting this in igt. It'll get stale real quick, and there are
efforts to decouple igt from i915 as much as possible, so next thing you
know someone else will want to docuemnt their favorite hardware here as
well.

So if we do want to document this stuff, then I think it should be
somewhere in the kernel modeset code (around crtc/plane init I suppose).

> + *
> + * |[!<-- language="C" -->
> + * .--------.
> + * | Memory |             .--------.
> + * |        |------------>| Cursor |------>...
> + * |        |             '--------'
> + * |        |
> + * |        |         .--------.
> + * |        |-------->| Sprite |---------->...
> + * |        |         '--------'
> + * |        |
> + * |        |      .---------.
> + * |        |----->| Primary |------------>...
> + * |        |      '---------'
> + * '--------'
> + * ]|
> + *
> + * A pipe with universal planes:
> + *
> + * |[!<-- language="C" -->
> + * .--------.
> + * | Memory |             .--------.
> + * |        |------------>| Cursor |------>...
> + * |        |             '--------'
> + * |        |
> + * |        |         .-------.
> + * |        |-------->| Plane |---------->...
> + * |        |         '-------'
> + * |        |
> + * |        |      .-------.
> + * |        |----->| Plane |------------>...
> + * |        |      '-------'
> + * '--------'
> + * ]|
> + *
> + * The encoder is used to convert, depending on the output, pixels from pipes
> + * to signals understood by the connector.
> + *
> + * The connector will connect to the output display. This contains information
> + * about the attached display such as EDID, DPMS and information about modes
> + * supported by the display.
> + *
>   * Note that this library's header pulls in the [i-g-t
>   * framebuffer](intel-gpu-tools-Framebuffer.html) library as a
>   * dependency.
> -- 
> 2.6.2
> 
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Ville Syrjälä
Intel OTC