From b40e5c72b727211752a6e18156280edf067cddce Mon Sep 17 00:00:00 2001 From: Nico Huber Date: Thu, 30 Mar 2017 22:12:43 +0200 Subject: Documentation: Describe libgfxinit hook-up Change-Id: Ieeb53a1694193cd19b5e9aa5bee25e36a60e56bd Signed-off-by: Nico Huber Reviewed-on: https://review.coreboot.org/19054 Tested-by: build bot (Jenkins) Reviewed-by: Stefan Reinauer --- Documentation/gfx/libgfxinit.md | 133 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 Documentation/gfx/libgfxinit.md (limited to 'Documentation/gfx') diff --git a/Documentation/gfx/libgfxinit.md b/Documentation/gfx/libgfxinit.md new file mode 100644 index 000000000000..8e7473df89c9 --- /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. -- cgit v1.2.3