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.