diff mbox

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

Message ID 1452848802-8041-2-git-send-email-marius.c.vlad@intel.com (mailing list archive)
State New, archived
Headers show

Commit Message

Marius Vlad Jan. 15, 2016, 9:06 a.m. UTC
lib/igt_kms: Briefly describe Intel-to-DRM mapping between pipes, encoders and
connectors.

Signed-off-by: Marius Vlad <marius.c.vlad@intel.com>
---
 lib/igt_kms.c | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

Comments

Ville Syrjälä Jan. 15, 2016, 12:46 p.m. UTC | #1
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@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@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Marius Vlad Jan. 19, 2016, 3:04 p.m. UTC | #2
On Fri, Jan 15, 2016 at 02:46:45PM +0200, Ville Syrjälä wrote:
> 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@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?
Right, pipe indeed.
> 
> > + * ]|
> > + *
> > + *
> > + * 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).

Yes, it might make more sense to be in the kernel. What I wanted to achieve
with this small intro was to bridge the gap between DRM terminology and
the one in Intel 01.org PRM for igt. For a first timer is rather tedious to
identify software/hadware abstraction when looking at the PRMs and when
looking in igt -- I know for a fact that I'm still having trouble
identifying those parts.

Daniel has already suggested to add some documention between
DRM-to-Intel Mappings in the kernel.

Do you suggest that we should document all platforms?


> 
> > + *
> > + * |[!<-- 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@lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/intel-gfx
> 
> -- 
> Ville Syrjälä
> Intel OTC
Ville Syrjälä Jan. 19, 2016, 3:18 p.m. UTC | #3
On Tue, Jan 19, 2016 at 05:04:33PM +0200, Marius Vlad wrote:
> On Fri, Jan 15, 2016 at 02:46:45PM +0200, Ville Syrjälä wrote:
> > 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@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?
> Right, pipe indeed.
> > 
> > > + * ]|
> > > + *
> > > + *
> > > + * 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).
> 
> Yes, it might make more sense to be in the kernel. What I wanted to achieve
> with this small intro was to bridge the gap between DRM terminology and
> the one in Intel 01.org PRM for igt. For a first timer is rather tedious to
> identify software/hadware abstraction when looking at the PRMs and when
> looking in igt -- I know for a fact that I'm still having trouble
> identifying those parts.
> 
> Daniel has already suggested to add some documention between
> DRM-to-Intel Mappings in the kernel.
> 
> Do you suggest that we should document all platforms?

I'd either keep it fairly generic, or document all of them. What you
had here seemed like something in between.

> 
> 
> > 
> > > + *
> > > + * |[!<-- 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@lists.freedesktop.org
> > > http://lists.freedesktop.org/mailman/listinfo/intel-gfx
> > 
> > -- 
> > Ville Syrjälä
> > Intel OTC
Daniel Vetter Jan. 19, 2016, 7:45 p.m. UTC | #4
On Tue, Jan 19, 2016 at 05:18:09PM +0200, Ville Syrjälä wrote:
> On Tue, Jan 19, 2016 at 05:04:33PM +0200, Marius Vlad wrote:
> > On Fri, Jan 15, 2016 at 02:46:45PM +0200, Ville Syrjälä wrote:
> > > 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@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?
> > Right, pipe indeed.
> > > 
> > > > + * ]|
> > > > + *
> > > > + *
> > > > + * 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).
> > 
> > Yes, it might make more sense to be in the kernel. What I wanted to achieve
> > with this small intro was to bridge the gap between DRM terminology and
> > the one in Intel 01.org PRM for igt. For a first timer is rather tedious to
> > identify software/hadware abstraction when looking at the PRMs and when
> > looking in igt -- I know for a fact that I'm still having trouble
> > identifying those parts.
> > 
> > Daniel has already suggested to add some documention between
> > DRM-to-Intel Mappings in the kernel.
> > 
> > Do you suggest that we should document all platforms?
> 
> I'd either keep it fairly generic, or document all of them. What you
> had here seemed like something in between.

Yeah I still think bridging the terminology gap in igt/drm would be good,
but indeed a bit more high-level might work better. And I agree with Ville
that the detailed docs are probably best in the kernel, next to the actual
paltform support code.
-Daniel

> 
> > 
> > 
> > > 
> > > > + *
> > > > + * |[!<-- 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@lists.freedesktop.org
> > > > http://lists.freedesktop.org/mailman/listinfo/intel-gfx
> > > 
> > > -- 
> > > Ville Syrjälä
> > > Intel OTC
> 
> 
> 
> -- 
> Ville Syrjälä
> Intel OTC
diff mbox

Patch

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.