Documentation/gfx/libgfxinit.md

   1 libgfxinit - Native Graphics Initialization
   2 ===========================================
   3
   4 Introduction and Current State in coreboot
   5 ------------------------------------------
   6
   7 *libgfxinit* is a library of full-featured graphics initialization
   8 (aka. modesetting) drivers. It's implemented in SPARK (a subset of
   9 Ada with formal verification features). While not restricted to in
  10 any way, it currently only supports Intel's integrated graphics
  11 controllers (GMA).
  12
  13 Currently, it supports the Intel Core i3/i5/i7 processor line, HDMI
  14 and DP on the Apollo Lake processors and everything but SDVO on G45
  15 and GM45 chipsets. At the time of writing, G45, GM45, everything
  16 from Arrandale to Coffee Lake, and Apollo Lake are verified to work
  17 within *coreboot*.
  18
  19 GMA: Framebuffer Configuration
  20 ------------------------------
  21
  22 *coreboot* supports two different framebuffer setups. The default
  23 enables the legacy VGA plane in textmode. Due to legacy hardware
  24 constraints, only the first found display is enabled in this mode.
  25 (cf. `src/drivers/intel/gma/text_fb/gma.adb`).
  26
  27 The second option sets up a high-resolution framebuffer with the
  28 native resolution of the display if only one is detected, or the
  29 smallest of all resolutions (per dimension) if multiple displays
  30 are detected. This option is selected by
  31 `CONFIG_FRAMEBUFFER_KEEP_VESA_MODE`.
  32 (cf. `src/drivers/intel/gma/hires_fb/gma.adb`).
  33
  34 In any case, a smaller framebuffer is up-scaled to each display's
  35 native resolution while keeping aspect ratio.
  36
  37 GMA: Hook-up in Chipset Initialization
  38 --------------------------------------
  39
  40 Both configurations described above implement a procedure
  41 `GMA.gfxinit()`:
  42
  43     procedure gfxinit (lightup_ok : out int);
  44
  45 This procedure is exported as the C function `gma_gfxinit()` as
  46 follows:
  47
  48     void gma_gfxinit(int *lightup_ok);
  49
  50 * `lightup_ok`: returns whether the initialization succeeded `1` or
  51                 failed `0`. Currently, only the case that no display
  52                 could be found counts as failure. A failure at a
  53                 later stage (e.g. failure to train a DP) is not
  54                 propagated.
  55
  56 GMA: Per Board Configuration
  57 ----------------------------
  58
  59 In order to set up the display panel, see the
  60 [display panel-specific documentation](/gfx/display-panel.md).
  61
  62 There are a few Kconfig symbols to consider. To indicate that a
  63 board can initialize graphics through *libgfxinit*:
  64
  65     select MAINBOARD_HAS_LIBGFXINIT
  66
  67 Internal ports share some hardware blocks (e.g. backlight, panel
  68 power sequencer). Therefore, each system with an integrated panel
  69 should set `GFX_GMA_PANEL_1_PORT` to the respective port, e.g.:
  70
  71     config GFX_GMA_PANEL_1_PORT
  72             default "DP3"
  73
  74 For the most common cases, LVDS and eDP, exists a shorthand, one
  75 can select either:
  76
  77     select GFX_GMA_PANEL_1_ON_EDP       # the default, or
  78     select GFX_GMA_PANEL_1_ON_LVDS
  79
  80 Some newer chips feature a second block of panel control logic.
  81 For this, `GFX_GMA_PANEL_2_PORT` can be set.
  82
  83 Boards with a DVI-I connector share the DDC (I2C) pins for both
  84 analog and digital displays. In this case, *libgfxinit* needs to
  85 know through which interface the EDID can be queried:
  86
  87     select GFX_GMA_ANALOG_I2C_HDMI_B    # or
  88     select GFX_GMA_ANALOG_I2C_HDMI_C    # or
  89     select GFX_GMA_ANALOG_I2C_HDMI_D
  90
  91 *libgfxinit* needs to know which ports are implemented on a board
  92 and should be probed for displays. There are two mechanisms to
  93 constrain the list of ports to probe, 1. port presence straps on
  94 the mainboard, and 2. a list of ports provided by *coreboot* (see
  95 below).
  96
  97 Presence straps are configured via the state of certains pins of
  98 the chipset at reset time. They are documented in the chipset's
  99 datasheets. By default, *libgfxinit* honors these straps for
 100 safety. However, some boards don't implement the straps correctly.
 101 If ports are not strapped as implemented by error, one can select
 102 an option to ignore the straps:
 103
 104     select GFX_GMA_IGNORE_PRESENCE_STRAPS
 105
 106 In the opposite case, that ports are strapped as implemented,
 107 but are actually unconnected, one has to make sure that the
 108 list of ports in *coreboot* omits them.
 109
 110 The mapping between the physical ports and these entries depends on
 111 the hardware implementation and can be recovered by testing or
 112 studying the output of `intelvbttool` or `intel_vbt_decode`.
 113 Each board has to implement the package `GMA.Mainboard` with a list:
 114
 115     ports : HW.GFX.GMA.Display_Probing.Port_List;
 116
 117 or a function returning such a list:
 118
 119     function ports return HW.GFX.GMA.Display_Probing.Port_List;
 120
 121 You can select from the following Ports:
 122
 123     type Port_Type is
 124       (Disabled,        -- optionally terminates the list
 125        LVDS,
 126        eDP,
 127        DP1,
 128        DP2,
 129        DP3,
 130        HDMI1,           -- also DVI-D, or HDMI over DP++
 131        HDMI2,
 132        HDMI3,
 133        Analog);         -- legacy VGA port, or analog part of DVI-I
 134
 135 Each `DPx` and `HDMIx` pair share pins. If they are exposed as DP
 136 ports, they are usually DP++ (aka. dual-mode DP) ports that can
 137 also output HDMI signals through passive adapters. In this case,
 138 both DPx and HDMIx should be listed.
 139
 140 A good example is the mainboard Kontron/KTQM77, it features two
 141 DP++ ports (DP2/HDMI2, DP3/HDMI3), one DVI-I port (HDMI1/Analog),
 142 eDP and LVDS. It defines `ports` as follows:
 143
 144     ports : constant Port_List :=
 145       (DP2,
 146        DP3,
 147        HDMI1,
 148        HDMI2,
 149        HDMI3,
 150        Analog,
 151        LVDS,
 152        eDP,
 153        others => Disabled);
 154
 155 The `GMA.gfxinit()` procedure probes for display EDIDs in the
 156 given order until all available pipes are taken. That's 1 pipe
 157 in VGA textmode, 2 pipes in high-resolution mode until Sandy
 158 Bridge, 3 pipes from Ivy Bridge on.