| Message ID | 1417781506-1730-3-git-send-email-tvrtko.ursulin@linux.intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
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>
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 +!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);