Documentation: Describe libgfxinit hook-up

Change-Id: Ieeb53a1694193cd19b5e9aa5bee25e36a60e56bd
Signed-off-by: Nico Huber <nico.h@gmx.de>
Reviewed-on: https://review.coreboot.org/19054
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>

Documentation/gfx/libgfxinit.md

@@ -0,0 +1,133 @@
+libgfxinit - Native Graphics Initialization
+===========================================
+
+Introduction and Current State in coreboot
+------------------------------------------
+
+*libgfxinit* is a library of full-featured graphics initialization
+(aka. modesetting) drivers. It's implemented in SPARK (a subset of
+Ada with formal verification features). While not restricted to in
+any way, it currently only supports Intel's integrated gfx control-
+lers (GMA).
+
+Currently, it supports the Intel Core i3/i5/i7 processor line and
+will support HDMI and DP on the Atom successor Apollo Lake. At the
+time of writing, Sandy Bridge, Ivy Bridge, and Haswell are veri-
+fied to work within *coreboot*.
+
+GMA: Framebuffer Configuration
+------------------------------
+
+*coreboot* supports two different framebuffer setups. The default
+enables the legacy VGA plane in textmode. Due to legacy hardware
+constraints, only the first found display is enabled in this mode.
+(cf. `src/drivers/intel/gma/text_fb/gma.adb`).
+
+The second option sets up a high-resolution framebuffer with the
+native resolution of the display if only one is detected, or the
+smallest of all resolutions (per dimension) if multiple displays
+are detected. This option is selected by
+`CONFIG_FRAMEBUFFER_KEEP_VESA_MODE`.
+(cf. `src/drivers/intel/gma/hires_fb/gma.adb`).
+
+In any case, a smaller framebuffer is up-scaled to each display's
+native resolution while keeping aspect ratio.
+
+GMA: Hook-up in Chipset Initialization
+--------------------------------------
+
+Both configurations described above implement a procedure
+`GMA.gfxinit()`:
+
+    procedure gfxinit
+      (mmio_base   : in     word64;
+       linear_fb   : in     word64;
+       phys_fb     : in     word32;
+       lightup_ok  :    out int);
+
+This procedure is exported as the C function `gma_gfxinit()` as
+follows:
+
+    void gma_gfxinit(uint64_t mmio_base, uint64_t linear_fb,
+                     uint32_t phys_fb, int *lightup_ok);
+
+* `mmio_base`:  the base address of the GMA's MMIO resource
+* `linear_fb`:  the base address of the GMA's GTT window resource
+* `phys_fb`:    the physical address where the framebuffer should be
+                stored (usually the GMA's stolen memory)
+* `lightup_ok`: returns whether the initialization succeeded `1` or
+                failed `0`. Currently, only the case that no display
+                could be found counts as failure. A failure at a la-
+                ter stage (e.g. failure to train a DP) is not propa-
+                gated.
+
+GMA: Per Board Configuration
+----------------------------
+
+There are a few Kconfig symbols to consider. To indicate that a
+board can initialize graphics through *libgfxinit*:
+
+    select MAINBOARD_HAS_LIBGFXINIT
+
+Internal ports share some hardware blocks (e.g. backlight, panel
+power sequencer). Therefore, each board has to select either eDP
+or LVDS as the internal port, if any:
+
+    select GFX_GMA_INTERNAL_IS_EDP	# the default, or
+    select GFX_GMA_INTERNAL_IS_LVDS
+
+Boards with a DVI-I connector share the DDC (I2C) pins for both
+analog and digital displays. In this case, *libgfxinit* needs to
+know through which interface the EDID can be queried:
+
+    select GFX_GMA_ANALOG_I2C_HDMI_B	# or
+    select GFX_GMA_ANALOG_I2C_HDMI_C	# or
+    select GFX_GMA_ANALOG_I2C_HDMI_D
+
+Beside Kconfig options, *libgfxinit* needs to know which ports are
+implemented on a board and should be probed for displays. Each
+board has to implement the package `GMA.Mainboard` with a list:
+
+    ports : HW.GFX.GMA.Display_Probing.Port_List;
+
+or a function returning such a list:
+
+    function ports return HW.GFX.GMA.Display_Probing.Port_List;
+
+You can select from the following Ports:
+
+    type Port_Type is
+      (Disabled,	-- optionally terminates the list
+       Internal,	-- either eDP or LVDS as selected in Kconfig
+       DP1,
+       DP2,
+       DP3,
+       HDMI1,		-- also DVI-D, or HDMI over DP++
+       HDMI2,
+       HDMI3,
+       Analog);		-- legacy VGA port, or analog part of DVI-I
+
+Each `DPx` and `HDMIx` pair share pins. If they are exposed as DP
+ports, they are usually DP++ (aka. dual-mode DP) ports that can
+also output HDMI signals through passive adapters. In this case,
+both DPx and HDMIx should be listed.
+
+A good example is the mainboard Kontron/KTQM77, it features two
+DP++ ports (DP2/HDMI2, DP3/HDMI3), one DVI-I port (HDMI1/Analog),
+eDP and LVDS. Due to the constraints mentioned above, only one of
+eDP and LVDS can be enabled. It defines `ports` as follows:
+
+    ports : constant Port_List :=
+      (DP2,
+       DP3,
+       HDMI1,
+       HDMI2,
+       HDMI3,
+       Analog,
+       Internal,
+       others => Disabled);
+
+The `GMA.gfxinit()` procedure probes for display EDIDs in the
+given order until all available pipes are taken. That's 1 pipe
+in VGA textmode, 2 pipes in high-resolution mode until Sandy
+Bridge, 3 pipes from Ivy Bridge on.