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

[Marius Vlad]

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 |
+ * '-----------'     '-------'     '-----------'     '------------'
+ * ]|
+ *
+ *
+ * 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. 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:
+ *
+ * |[!<-- 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