[Intel-gfx] [PATCH v2 1/1] i915: additional GEM documentation

[Rogovin, Kevin]

Hi,

 Thankyou for the very thorough read and comments, this is exactly what is needed to give it polish and become a good intro to GEM in i915; I just wished I had waited on posting a v3 just a few more hours and I would have been able to use all this for v3. I will use all of your comments in v4 though.

Some comments on just a few of the comments (with massive snipping):

>> +Access. For having the GPU "do work", user space will feed the GPU 
>> +batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2` 
>> +or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR` (the ioctl 
>> +`DRM_IOCTL_I915_GEM_EXECBUFFER`

>It is actually the same ioctl from i915 point of view. It used to be read-only (from the i915 point of view) and when fences were added
> (AFAIR) it needed to be made writable as well.

What would be better: to call out the individual IOCTL values (DRM_IOCTL_I915_GEM_) or the pre-ioctl values (DRM_I915_) for the purpose
of documentation? In truth the legacy DRM_I915 _GEM_EXECBUFFER implementation is really just a wrapper over the DRM_I915 _GEM_EXECBUFFER2
implementation. Any advice is appreciated.

>>    * Motivation:
>>    * GEN8 brings an expansion of the HW contexts: "Logical Ring Contexts".
>>    * These expanded contexts enable a number of new abilities, 
>> especially
>> - * "Execlists" (also implemented in this file).
>> + * "Execlists" (also implemented in this file,
>> + * drivers/gpu/drm/i915/intel_lrc.c).

> Why is self-reference to filename required?

The document gets included in the html (or pdf) made with make htmldocs (resp. pdfdocs) and I'd like for the documentation
made to also act as a way for new developers to quickly know what file mainly does what (indeed this is something I am myself
still working on).

-Kevin