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