drm/i915: DocBook integration for frontbuffer tracking

I shouldn't ask everyone to do this and fail myself ...

This extracts all the frontbuffer tracking functions into
intel_frontbuffer.c, adds a DOC overview section and also adds the
missing kerneldoc for i915_gem_track_fb and also pulls it into the
same section for convenience.

v2: Don't forget about the header files.

v3: Oops, might check compilation next time around. To make my life
easier drop the increase_pllclock from set_base_atomic since really,
it doesn't matter if you see your Oops or kgdb with a tiny bit of lag.

v4: Try to better explain how to actually use this, requested by Paulo
on irc.

v5: Explain invalidate/flush a bit clearer.

v6: s/business/busyness/

Acked-by: Paulo Zanoni <paulo.r.zanoni@intel.com>
Cc: Paulo Zanoni <paulo.r.zanoni@intel.com>
Cc: Vandana Kannan <vandana.kannan@intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>

drivers/gpu/drm/i915/i915_gem.c

@@ -5077,6 +5077,15 @@ int i915_gem_open(struct drm_device *dev, struct drm_file *file)
 	return ret;
 }
 
+/**
+ * i915_gem_track_fb - update frontbuffer tracking
+ * old: current GEM buffer for the frontbuffer slots
+ * new: new GEM buffer for the frontbuffer slots
+ * frontbuffer_bits: bitmask of frontbuffer slots
+ *
+ * This updates the frontbuffer tracking bits @frontbuffer_bits by clearing them
+ * from @old and setting them in @new. Both @old and @new can be NULL.
+ */
 void i915_gem_track_fb(struct drm_i915_gem_object *old,
 		       struct drm_i915_gem_object *new,
 		       unsigned frontbuffer_bits)