On 12/5/2014 12:11 PM, Tvrtko Ursulin wrote:
> From: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
>
> A short section describing background, implementation and intended usage.
>
> For: VIZ-4544
> Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
> ---
>   Documentation/DocBook/drm.tmpl      |  5 ++++
>   drivers/gpu/drm/i915/i915_gem_gtt.c | 60 +++++++++++++++++++++++++++++++++++++
>   2 files changed, 65 insertions(+)
>
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 56e2a9b..c975f26 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -4033,6 +4033,11 @@ int num_ioctls;</synopsis>
>   !Pdrivers/gpu/drm/i915/intel_lrc.c Logical Rings, Logical Ring Contexts and Execlists
>   !Idrivers/gpu/drm/i915/intel_lrc.c
>         </sect2>
> +      <sect2>
> +        <title>Global GTT views</title>
> +!Pdrivers/gpu/drm/i915/i915_gem_gtt.c Global GTT views
Isn't it missing the _(GGTT)_ of the DOC: section title?
i.e. !Pdrivers/gpu/drm/i915/i915_gem_gtt.c Global GTT views (GGTT)

> +!Idrivers/gpu/drm/i915/i915_gem_gtt.c
> +      </sect2>
>       </sect1>
>   
>       <sect1>
> diff --git a/drivers/gpu/drm/i915/i915_gem_gtt.c b/drivers/gpu/drm/i915/i915_gem_gtt.c
> index 73c1c0b..0953369 100644
> --- a/drivers/gpu/drm/i915/i915_gem_gtt.c
> +++ b/drivers/gpu/drm/i915/i915_gem_gtt.c
> @@ -30,6 +30,66 @@
>   #include "i915_trace.h"
>   #include "intel_drv.h"
>   
> +/**
> + * DOC: Global GTT views (GGTT)
> + *
> + * Background and previous state
> + *
> + * Historically objects could exists (be bound) in global GTT space only as
> + * singular instances with a view representing all of the object's backing pages
> + * in a linear fashion. This view will be called a normal view.
> + *
> + * To support multiple views of the same object, where the number of mapped
> + * pages is not equal to the backing store, or where the layout of the pages
> + * is not linear, concept of a GGTT view was added.
> + *
> + * One example of an alternative view is a stereo display driven by a single
> + * image. In this case we would have a framebuffer looking like this
> + * (2x2 pages):
> + *
> + *    12
> + *    34
> + *
> + * Above would represent a normal GGTT view as normally mapped for GPU or CPU
> + * rendering. In contrast, fed to the display engine would be an alternative
> + * view which could look something like this:
> + *
> + *   1212
> + *   3434
> + *
> + * In this example both the size and layout of pages in the alternative view is
> + * different from the normal view.
> + *
> + * Implementation and usage
> + *
> + * GGTT views are implemented using VMAs and are distinguished via enum
> + * i915_ggtt_view_type and struct i915_ggtt_view.
> + *
> + * A new flavour of core GEM functions which work with GGTT bound objects were
> + * added with the _view suffix. They take the struct i915_ggtt_view parameter
> + * encapsulating all metadata required to implement a view.
> + *
> + * As a helper for callers which are only interested in the normal view,
> + * globally const i915_ggtt_view_normal singleton instance exists. All old core
> + * GEM API functions, the ones not taking the view parameter, are operating on,
> + * or with the normal GGTT view.
> + *
> + * Code wanting to add or use a new GGTT view needs to:
> + *
> + * 1. Add a new enum with a suitable name.
> + * 2. Extend the metadata in the i915_ggtt_view structure if required.
> + * 3. Add support to i915_get_vma_pages().
> + *
> + * New views are required to build a scatter-gather table from within the
> + * i915_get_vma_pages function. This table is stored in the vma.ggtt_view and
> + * exists for the lifetime of an VMA.
> + *
> + * Core API is designed to have copy semantics which means that passed in
> + * struct i915_ggtt_view does not need to be persistent (left around after
> + * calling the core API functions).
> + *
> + */
> +
>   const struct i915_ggtt_view i915_ggtt_view_normal;
>   
>   static void bdw_setup_private_ppat(struct drm_i915_private *dev_priv);
Apart from that,
Reviewed-by: Michel Thierry <michel.thierry@intel.com>