[Intel-gfx] [PATCH] drm/i915: Try to clarify the function and file naming

[Chris Wilson]

To the casual observer, our naming is a mess. However, we did have a plan
for how our functions should be named, just we were lax and let cruft
accrue. Explain how it was meant to look in the hope that someday it
will all make sense.

Signed-off-by: Chris Wilson <chris at chris-wilson.co.uk>
---
 drivers/gpu/drm/i915/README |   76 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 76 insertions(+), 0 deletions(-)
 create mode 100644 drivers/gpu/drm/i915/README

diff --git a/drivers/gpu/drm/i915/README b/drivers/gpu/drm/i915/README
new file mode 100644
index 0000000..4aef49b
--- /dev/null
+++ b/drivers/gpu/drm/i915/README
@@ -0,0 +1,76 @@
+General notes on function naming
+--------------------------------
+
+The goal is prefix the function names with the first chipset that work with.
+So we have:
+  intel_ -> general functions, used by all
+  i8xx_ -> gen2
+  i915_ -> gen3 (915/945)
+  [NB: do not confuse with i915_gem which should be intel_gem by this logic!]
+  g33_, pineview_ -> gen3 (blk/pnv) # perhaps just g33 as pnv = g33 + mobile?
+  i965_ -> gen4 (brw/crl)
+  g4x_ -> gen4 (egl/ctg)
+  ironlake_, sandybridge_, ivybridge_ -> etc
+
+So ironlake can call a g4x function, but never vice versa. Note that different
+generations share different components, but we may generalise and say
+that:
+
+* sandybridge/ivybridge are roughly equivalent with a little overlap with
+ironlake.
+
+* ironlake and g4x share a few common components.
+
+* g4x was a fairly distinct departure for the display engine from i965
+(though it shares almost the same render engine).
+
+* g33 included some of the same display engine reconfiguration as g4x, but
+in its own unique fashion on top of i915.
+
+* i915 and i8xx are fairly independent, and each gen2 chipset subtly
+different from each other.
+
+Also note that there is also a split between desktop versions of the
+chipsets and their mobile variants. The differences are usually common
+on all generations, but their implementation vary.
+
+General notes on file naming
+----------------------------
+
+File naming is a little more complex due to hysterical raisons that we
+have not overcome yet. Originally the driver was a small interface for
+DRI1, essentially to allow shared ringbuffer usage but all command
+execution and memory management was done in userspace.
+
+This is the bulk of i915_dma.c, with the saving of state for suspend and
+resume in i915_suspend.c.
+
+Then we introduced GEM and built a very solid buffer manager with an
+entirely new interface for DRI2.
+
+These files live in i915_gem*.c, but they overlap somewhat with
+i915_dma.c - a ceaseless source of unamusing bugs. When adding new
+functionality, please do consider clearly segregating it and putting the
+fundamental features into the core GEM namespace.
+
+* i915_gem.c is the core buffer management and domain tracking,
+providing facilities for the rest of GEM
+
+* i915_gem_execbuffer.c is solely tasked with performing the relocations
+on the incoming commands and submitting them to the ring.
+
+* i915_gem_evict.c contains the LRU fair-eviction policy.
+
+* i915_gem_gtt.c is the interface through which we program the GTT for
+the translation of the buffer objects from the physical pages into the
+GPU virtual addresses.
+
+* i915_gem_tiling.c is to centralise the complexity of device specific
+programming and limitations of fences.
+
+Files prefixed with intel_* support (and abstract in some cases) common
+features found across many generations, such as the ringbuffers for
+command submission and the display engine. The core of the display
+engine, the central driver for modesetting, is intel_display.c with
+encoder specific functionality living in intel_dvo.c (i8xx-only digital
+video out), intel_sdvo.c, intel_hdmi.c, intel_dp.c.
-- 
1.7.4.4