apple-gmux: Add initial documentation

Document what I've learned so far about the gmux so that we can
collaboratively reverse-engineer its remaining unknown bits
without everyone having to start from scratch.

The DOC sections are bound together in the gpu.tmpl DocBook
under a new vga_switcheroo "Handlers" chapter. Eventually
this should be amended with documentation about the four other
handlers that exist so far (nouveau v1 DSM, nouveau Optimus DSM,
radeon ATPX, amdgpu ATPX).

Requires kernel-doc with asciidoc support.

The EFI variable was reverse-engineered by Bruno Bierbaumer
<bruno@bierbaumer.net> and Andreas Heider <andreas@meetr.de>.

Some of the remaining open questions:

* How are vblank intervals synchronized on retinas to achieve seamless
  switching? Is the DP mux capable of this? It's not mentioned in the
  data sheets. Or is it done at the OS level, i.e. do we have to
  synchronize vblank intervals between DRM drivers? There's a signal
  coming from the panel connector and going into gmux, could this be
  the vblank signal as received by the panel to properly time the
  switch?

* On retinas there's an I2C bus between gmux and the connector of the
  right I/O board, apparently leading to the Parade PS8401A HDMI
  repeater. What is this for, is it controlled via gmux registers?
  Data sheet:
  http://www.paradetech.com/products/jitter-cleaning-repeaters/ps8401/

* On retinas there's an I2C bus between gmux and the LED driver.
  Pre-retinas connected the LED driver to SMBUS. Are there additional
  gmux registers on retinas to control it?

* The MacPro6,1 2013 also has a gmux, the same Renesas R4F2113 as the
  retina MacBook Pro. The Mac Pro doesn't have a built-in display,
  so what is its purpose? Power control of the dual FirePro GPUs?
  Switching of the external DP/Thunderbolt ports? The iFixit teardown
  clearly shows one TI HD3SS212 DisplayPort mux on the logic board next
  to one of the three Thunderbolt controllers. However six muxes would
  be necessary to switch all six ports between GPUs. The mux is probably
  necessary for one of the display configurations allowed by Apple,
  but which one?
  https://www.ifixit.com/Teardown/Mac+Pro+Late+2013+Teardown/20778
  https://d3nevzfk7ii3be.cloudfront.net/igi/fELBTnt31QhnDsqq.huge
  https://support.apple.com/en-us/HT202801

* Registers we haven't decoded yet:
  0x700 32 Bit configmap?
  0x708 32 Bit power sequence?
  0x712  8 Bit status of clock from panel on retinas?
  0x713  8 Bit dito?
  0x724 16 Bit backlight, raw value?
  0x760 32 Bit backlight
  0x764 32 Bit backlight
  0x768  8 Bit backlight
  0x76a 16 Bit backlight
  0x76c 16 Bit backlight
  0x76e 16 Bit backlight
  0x77f        edp/dp/hdmi probe? retina only.

* Addition by Bruno Prémont <bonbons@linux-vserver.org>:
  "Missing is also precise knowledge as to what the gmux depends on.
  From behavioral reports, it is somehow sensitive to VGA IO/MEM
  routing (it apparently needs the routing to go to integrated GPU,
  not discrete GPU).
  When the routing is inappropriate backlight control IO just reads back
  as 0xFF (and eventually gmux IO in general does so)."

Signed-off-by: Lukas Wunner <lukas@wunner.de>
Acked-by: Darren Hart <dvhart@linux.intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/da309e436fbeac886477d80376457b7d83ea4b2d.1452431795.git.lukas@wunner.de
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

1 files changed, 22 insertions, 0 deletions

diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
index faa5e0d4208d..a8669330b456 100644
--- a/Documentation/DocBook/gpu.tmpl
+++ b/Documentation/DocBook/gpu.tmpl
@@ -3470,8 +3470,30 @@ int num_ioctls;</synopsis>
     </sect1>
   </chapter>
 
+  <chapter id="handlers">
+    <title>Handlers</title>
+    <sect1>
+      <title>apple-gmux Handler</title>
+!Pdrivers/platform/x86/apple-gmux.c Overview
+!Pdrivers/platform/x86/apple-gmux.c Interrupt
+      <sect2>
+        <title>Graphics mux</title>
+!Pdrivers/platform/x86/apple-gmux.c Graphics mux
+      </sect2>
+      <sect2>
+        <title>Power control</title>
+!Pdrivers/platform/x86/apple-gmux.c Power control
+      </sect2>
+      <sect2>
+        <title>Backlight control</title>
+!Pdrivers/platform/x86/apple-gmux.c Backlight control
+      </sect2>
+    </sect1>
+  </chapter>
+
 !Cdrivers/gpu/vga/vga_switcheroo.c
 !Cinclude/linux/vga_switcheroo.h
+!Cdrivers/platform/x86/apple-gmux.c
 </part>
 
 </book>