summaryrefslogtreecommitdiff
path: root/Documentation/gfx/libgfxinit.md
diff options
context:
space:
mode:
authorNico Huber <nico.h@gmx.de>2017-03-30 22:12:43 +0200
committerStefan Reinauer <stefan.reinauer@coreboot.org>2017-06-06 18:08:17 +0200
commitb40e5c72b727211752a6e18156280edf067cddce (patch)
tree9fc84fb456975c9acbb9edae14bd26cfbabe412f /Documentation/gfx/libgfxinit.md
parentaf83db2659948ea39fa9fb1473cfca7f2d3f6cfd (diff)
downloadcoreboot-b40e5c72b727211752a6e18156280edf067cddce.tar.xz
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>
Diffstat (limited to 'Documentation/gfx/libgfxinit.md')
-rw-r--r--Documentation/gfx/libgfxinit.md133
1 files changed, 133 insertions, 0 deletions
diff --git a/Documentation/gfx/libgfxinit.md b/Documentation/gfx/libgfxinit.md
new file mode 100644
index 0000000000..8e7473df89
--- /dev/null
+++ b/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.