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>
This commit is contained in:
Nico Huber
Stefan Reinauer
parent
af83db2659
commit
b40e5c72b7
|
|
@ -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.
|
||||
Loading…
Reference in New Issue