<p>Patrick Rudolph has uploaded this change for <strong>review</strong>.</p><p><a href="https://review.coreboot.org/26781">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">[WIP]Documentation: Port graphics initialization from wiki<br><br>Change-Id: I3212af27fb44c6d975fe9def4864d4d027086003<br>Signed-off-by: Patrick Rudolph <siro@das-labor.org><br>---<br>A Documentation/device/graphics_init.md<br>A Documentation/device/index.md<br>A Documentation/device/lenovo_dual_graphics.md<br>R Documentation/device/libgfxinit.md<br>A Documentation/device/native_graphics_init.md<br>A Documentation/device/vga_option_roms.md<br>M Documentation/index.md<br>7 files changed, 640 insertions(+), 1 deletion(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://review.coreboot.org:29418/coreboot refs/changes/81/26781/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/Documentation/device/graphics_init.md b/Documentation/device/graphics_init.md</span><br><span>new file mode 100644</span><br><span>index 0000000..ace5f89</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/device/graphics_init.md</span><br><span>@@ -0,0 +1,166 @@</span><br><span style="color: hsl(120, 100%, 40%);">+# Graphics initialization</span><br><span style="color: hsl(120, 100%, 40%);">+Graphics init is the process to bring up an initial framebuffer to display the bootloader or OS.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Possible options in coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+There are multiple types of graphics init in coreboot, explained in detail below:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* None</span><br><span style="color: hsl(120, 100%, 40%);">+* VGA Option ROM</span><br><span style="color: hsl(120, 100%, 40%);">+ * On integrated GPUs (as part of firmware)</span><br><span style="color: hsl(120, 100%, 40%);">+ * On Plug&Play GPUs (stored on the card itself)</span><br><span style="color: hsl(120, 100%, 40%);">+* Native Graphics Init</span><br><span style="color: hsl(120, 100%, 40%);">+ * On integrated GPU (as part of firmware)</span><br><span style="color: hsl(120, 100%, 40%);">+* libgfxinit</span><br><span style="color: hsl(120, 100%, 40%);">+ * On integrated GPU (as part of firmware)</span><br><span style="color: hsl(120, 100%, 40%);">+* FSP PEIM GOP</span><br><span style="color: hsl(120, 100%, 40%);">+ * On integrated GPU (as part of firmware)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Terms</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* NGI : native graphics initialization</span><br><span style="color: hsl(120, 100%, 40%);">+* GFX init : graphics initialization</span><br><span style="color: hsl(120, 100%, 40%);">+* VBT: Video Bios Tables (Intel specific)</span><br><span style="color: hsl(120, 100%, 40%);">+* Video BIOS: The program to initialize the card and provide card specific information</span><br><span style="color: hsl(120, 100%, 40%);">+* VBIOS: Video BIOS</span><br><span style="color: hsl(120, 100%, 40%);">+* GOP: Graphics Output Protocol</span><br><span style="color: hsl(120, 100%, 40%);">+* FSP: Firmware Support Package</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Grahpics Init: None</span><br><span style="color: hsl(120, 100%, 40%);">+In this mode coreboot does no graphics initialization at all.</span><br><span style="color: hsl(120, 100%, 40%);">+It is up to the payload to init graphics.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Payloads that are able to init graphics on its own:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* SeaBIOS</span><br><span style="color: hsl(120, 100%, 40%);">+* Tianocore</span><br><span style="color: hsl(120, 100%, 40%);">+* GNU Linux</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Grahpics Init: VGA Option ROM</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```eval_rst</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| License | Unclear, might be incompatible to GPL |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| Source code | Not available |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| Debugging | Difficult, Run it in an emulator |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[VGA Option ROMs] contain 16bit real mode code and are meant to be run</span><br><span style="color: hsl(120, 100%, 40%);">+by x86 BIOS implementations. coreboot does include a yabel 16bit emulator</span><br><span style="color: hsl(120, 100%, 40%);">+to run [VGA Option ROMs]. On Plug&Play GPUs the Option ROM is stored</span><br><span style="color: hsl(120, 100%, 40%);">+on the card itself, but integrated cards or mobile cards store a copy of</span><br><span style="color: hsl(120, 100%, 40%);">+the [VGA Option ROM] in the firmware image. On those platforms you have to include</span><br><span style="color: hsl(120, 100%, 40%);">+the [VGA Option ROM] as part of the firmware build process.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Grahpics Init: Native graphics init</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```eval_rst</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| License | Compatible to GPL |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| Source code | Available |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| Debugging | Easy, console output available |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Is a driver, which is written in a high level language and open source implementation</span><br><span style="color: hsl(120, 100%, 40%);">+to initialize the graphics hardware on a specific platform. Redistribution is possible</span><br><span style="color: hsl(120, 100%, 40%);">+as the license grants those rights. It might implement only a subset of possible</span><br><span style="color: hsl(120, 100%, 40%);">+resolution ,when compared to [VGA Option ROM], a subset of possible color depth</span><br><span style="color: hsl(120, 100%, 40%);">+and work only on a subset of available connectors.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On some platforms the graphics can be initialized using C code.</span><br><span style="color: hsl(120, 100%, 40%);">+[Native Graphics Init] has lot's of limitations, like no support for eDP connectors.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Even though coreboot can run [VGA Option ROMs], those aren't called ___Native Graphics Init___.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Grahpics Init: libgfxinit</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```eval_rst</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| License | Compatible to GPL |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| Source code | Available |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| Debugging | Easy, console output available |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[libgfxinit] is a graphics initialization (aka modesetting) library for embedded</span><br><span style="color: hsl(120, 100%, 40%);">+environments. It currently supports only Intel hardware, more specifically</span><br><span style="color: hsl(120, 100%, 40%);">+the _Intel Core_ processor line.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It can query and set up most kinds of displays based on their [EDID] information.</span><br><span style="color: hsl(120, 100%, 40%);">+You can, however, also specify particular mode lines.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[libgfxinit] is written in [SPARK], an Ada subset with formal verification aspects.</span><br><span style="color: hsl(120, 100%, 40%);">+Absence of runtime errors can be proved automatically with SPARK GPL 2016.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+__Note:__ You have to compile the coreboot toolchain with ADA support to use [libgfxinit] !</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#### Benefits</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* No code execution at runtime</span><br><span style="color: hsl(120, 100%, 40%);">+* No BLOBs</span><br><span style="color: hsl(120, 100%, 40%);">+* Faster - As code isn't running in 16bit real mode</span><br><span style="color: hsl(120, 100%, 40%);">+* Debugging output</span><br><span style="color: hsl(120, 100%, 40%);">+* Known license</span><br><span style="color: hsl(120, 100%, 40%);">+* Redistributable</span><br><span style="color: hsl(120, 100%, 40%);">+* Extendable</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#### Limitations</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* [VGA Option ROMs] contain configuration data, that are not available if</span><br><span style="color: hsl(120, 100%, 40%);">+native graphics initialization is used. OS that rely on those configuration</span><br><span style="color: hsl(120, 100%, 40%);">+data won't work as expected.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* No resolution switching at runtime (affects Windows installer)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#### Closed source payloads/OS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Some payload and OS might not work at all, as they depend on runtime resolution switching</span><br><span style="color: hsl(120, 100%, 40%);">+or (legacy x86) text mode. Those cannot be fixed. You have to use a proper [VGA Option ROM].</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#### Opensource payloads/OS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If you find a software that doesn't work well, you can try to parse the</span><br><span style="color: hsl(120, 100%, 40%);">+coreboot tables to find the graphics mode or framebuffer in use.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+List of software that is already aware of coreboot's framebuffer:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Libpayload</span><br><span style="color: hsl(120, 100%, 40%);">+* SeaBIOS</span><br><span style="color: hsl(120, 100%, 40%);">+* TianoCore</span><br><span style="color: hsl(120, 100%, 40%);">+* GRUB</span><br><span style="color: hsl(120, 100%, 40%);">+* Linux</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Grahpics Init: FSP PEIM GOP</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```eval_rst</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| License | Same as Intel FSP |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| Source code | Not available |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+| Debugging | Difficult |</span><br><span style="color: hsl(120, 100%, 40%);">++---------------------+---------------------------------------+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The graphics init happens as part of the FSP phase. It uses the provided</span><br><span style="color: hsl(120, 100%, 40%);">+VBT to gather all information about the hardware.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Board specific graphics initialization</span><br><span style="color: hsl(120, 100%, 40%);">+Some vendors do have special hardware and software.</span><br><span style="color: hsl(120, 100%, 40%);">+Have a look at [Lenovo proprietary notebook graphics](lenovo_dual_graphics.md) for more details.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[EDID]: wiki/Extended_Display_Identification_Data</span><br><span style="color: hsl(120, 100%, 40%);">+[Libgfxinit]: libgfxinit.md</span><br><span style="color: hsl(120, 100%, 40%);">+[SPARK]: http://docs.adacore.com/spark2014-docs/html/lrm/</span><br><span style="color: hsl(120, 100%, 40%);">+[Native Graphics Init]: native_graphics_init.md</span><br><span style="color: hsl(120, 100%, 40%);">+[VGA Option ROMs]: vga_option_roms.md</span><br><span style="color: hsl(120, 100%, 40%);">+[VGA Option ROM]: vga_option_roms.md</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span>diff --git a/Documentation/device/index.md b/Documentation/device/index.md</span><br><span>new file mode 100644</span><br><span>index 0000000..4a93e20</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/device/index.md</span><br><span>@@ -0,0 +1,11 @@</span><br><span style="color: hsl(120, 100%, 40%);">+# Device-specific documentation</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This section contains documentation about coreboot device drivers.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Graphics</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* [Graphics initialization](graphics_init.md)</span><br><span style="color: hsl(120, 100%, 40%);">+* [Native Graphics Initialization with libgfxinit](libgfxinit.md)</span><br><span style="color: hsl(120, 100%, 40%);">+* [Native graphics initialization](native_graphics_init.md)</span><br><span style="color: hsl(120, 100%, 40%);">+* [VGA Option ROMs](vga_option_roms.md)</span><br><span style="color: hsl(120, 100%, 40%);">+* [Lenovo Dual graphics](lenovo_dual_graphics.md)</span><br><span>diff --git a/Documentation/device/lenovo_dual_graphics.md b/Documentation/device/lenovo_dual_graphics.md</span><br><span>new file mode 100644</span><br><span>index 0000000..ced2ff9</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/device/lenovo_dual_graphics.md</span><br><span>@@ -0,0 +1,143 @@</span><br><span style="color: hsl(120, 100%, 40%);">+# Proprietary notebook graphics</span><br><span style="color: hsl(120, 100%, 40%);">+## Terms</span><br><span style="color: hsl(120, 100%, 40%);">+* iGPU : integrated GPU</span><br><span style="color: hsl(120, 100%, 40%);">+* dGPU : discrete GPU</span><br><span style="color: hsl(120, 100%, 40%);">+* MUX : multiplexer</span><br><span style="color: hsl(120, 100%, 40%);">+* MUXed : Device that has got a MUX</span><br><span style="color: hsl(120, 100%, 40%);">+* MUXless : Device that hasn't got a MUX</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Nvidia Optimus™</span><br><span style="color: hsl(120, 100%, 40%);">+[Nvidia Optimus] is mainly an ACPI feature to control power of the dGPU.</span><br><span style="color: hsl(120, 100%, 40%);">+It also allows to toggle the MUX on ___Hybrid graphics___ capable devices at runtime.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+**Note:** Coreboot doesn't support ___Nvidia Optimus___.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Hybrid Graphics™ / Switchable Graphics™</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[Hybrid Graphics] is a feature used by a notebook that has two GPUs</span><br><span style="color: hsl(120, 100%, 40%);">+and a MUX to switch the notebook's panel to one of the GPUs.</span><br><span style="color: hsl(120, 100%, 40%);">+Only one GPU is active at time, allowing to save power and making</span><br><span style="color: hsl(120, 100%, 40%);">+display handling on software side easy.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+coreboot does support ___hybrid graphics___ and you can select the GPU</span><br><span style="color: hsl(120, 100%, 40%);">+to use at boot (using a CMOS setting, through nvramtool or nvramcui).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+__Supported Notebooks:__</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Lenovo T400/T500/W500</span><br><span style="color: hsl(120, 100%, 40%);">+* Lenovo T420/T520/T420s/W520</span><br><span style="color: hsl(120, 100%, 40%);">+* Lenovo T430/T530/T430s</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+___Switchable Graphics___ allows to toggle the MUX at runtime, but it needs</span><br><span style="color: hsl(120, 100%, 40%);">+complex graphics drivers handling and platform specific power management</span><br><span style="color: hsl(120, 100%, 40%);">+features like ___Nvidia Optimus___ or ___ATI PowerXpress___.</span><br><span style="color: hsl(120, 100%, 40%);">+You might need to install additional drivers or userspace software.</span><br><span style="color: hsl(120, 100%, 40%);">+See [Bumblebee on archlinux wiki] or [GitHub Bumblebee Project]</span><br><span style="color: hsl(120, 100%, 40%);">+for more details.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### For endusers</span><br><span style="color: hsl(120, 100%, 40%);">+The following steps have to be done to switch GPUs under coreboot:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Enable _CMOS layout_ in Kconfig</span><br><span style="color: hsl(120, 100%, 40%);">+* Change CMOS setting *hybrid_graphics_mode* during runtime using _nvramcui_ or _nvramtool_:</span><br><span style="color: hsl(120, 100%, 40%);">+ * 0 Integrated Only (default)</span><br><span style="color: hsl(120, 100%, 40%);">+ * 1 Discrete Only</span><br><span style="color: hsl(120, 100%, 40%);">+ * 2 Dual graphics (only T500 as of writing)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If the device doesn't have two GPUs the CMOS option does have no effect.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## ATI PowerXpress™ (Mobile)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+___ATI PowerXpress___ automatically switches the graphics depending on</span><br><span style="color: hsl(120, 100%, 40%);">+AC/battery state and user preference. It is ATI's solution to counter ___Nvidia Optimus___.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+**Note:** Coreboot doesn't support ___ATI PowerXpress___.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Dual graphics™</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+___Dual graphics___ is a feature used by a notebook that has two GPUs and where the</span><br><span style="color: hsl(120, 100%, 40%);">+iGPU is connected to the panel and where the dGPU used to offload rendering to.</span><br><span style="color: hsl(120, 100%, 40%);">+It can be used on MUXed devices and MUXless devices.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+__Warning__: Enabling two GPUs draws significantly more power ! You need ___Nvidia Optimus___</span><br><span style="color: hsl(120, 100%, 40%);">+or ___ATI PowerXpress___ to disable the dGPU's power when not in use!</span><br><span style="color: hsl(120, 100%, 40%);">+___Nvidia Optimus___ and ___ATI PowerXpress___ hasn't been implemented in coreboot.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Dual graphics ™ on Lenovo ThinkPads</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+__Requirements:__</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Active both GPUs at boot</span><br><span style="color: hsl(120, 100%, 40%);">+* Include the [VGA Option ROM] for the dGPU (important, as the VGA Option ROM contains configuration data)</span><br><span style="color: hsl(120, 100%, 40%);">+* Include the [VGA Option ROM] for the iGPU or use [Native Graphics Init]</span><br><span style="color: hsl(120, 100%, 40%);">+* On Linux you can use *DRI_PRIME=1* to offload 3D rendering to another GPU.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+__Supported Notebooks:__</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Lenovo T400/T500</span><br><span style="color: hsl(120, 100%, 40%);">+* Lenovo T420/T520/W520/T420s (since coreboot 4.8)</span><br><span style="color: hsl(120, 100%, 40%);">+* Lenovo T430/T530/T430s (since coreboot 4.8)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### For endusers</span><br><span style="color: hsl(120, 100%, 40%);">+The following steps have to be done to switch GPUs under coreboot:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Enable CMOS layout in Kconfig</span><br><span style="color: hsl(120, 100%, 40%);">+* Change CMOS setting *hybrid_graphics_mode* during runtime using nvramcui or nvramtool:</span><br><span style="color: hsl(120, 100%, 40%);">+ * 0 Integrated Only (default)</span><br><span style="color: hsl(120, 100%, 40%);">+ * 1 Discrete Only</span><br><span style="color: hsl(120, 100%, 40%);">+ * 2 Dual graphics</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If the device doesn't have two GPUs the CMOS option does have no effect.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### For developers</span><br><span style="color: hsl(120, 100%, 40%);">+* Select option *DRIVERS_LENOVO_HYBRID_GRAPHICS* in board's Kconfig</span><br><span style="color: hsl(120, 100%, 40%);">+* Add to board's devicetree.cb :</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Example configuration:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ chip drivers/lenovo/hybrid_graphics</span><br><span style="color: hsl(120, 100%, 40%);">+ device pnp ff.f on end # dummy</span><br><span style="color: hsl(120, 100%, 40%);">+ register "detect_gpio" = "21"</span><br><span style="color: hsl(120, 100%, 40%);">+ register "has_panel_hybrid_gpio" = "1"</span><br><span style="color: hsl(120, 100%, 40%);">+ register "panel_hybrid_gpio" = "52"</span><br><span style="color: hsl(120, 100%, 40%);">+ register "panel_integrated_lvl" = "1"</span><br><span style="color: hsl(120, 100%, 40%);">+ register "has_backlight_gpio" = "0"</span><br><span style="color: hsl(120, 100%, 40%);">+ register "has_dgpu_power_gpio" = "0"</span><br><span style="color: hsl(120, 100%, 40%);">+ register "has_thinker1" = "1"</span><br><span style="color: hsl(120, 100%, 40%);">+ end</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#### Devicetree settings:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+For detailed information, please check out the driver at *src/drivers/lenovo/hybrid_graphics*</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* ``detect_gpio`` is input GPIO on the southbridge to advertise support for hybrid graphics.</span><br><span style="color: hsl(120, 100%, 40%);">+* *has_panel_hybrid_gpio* is true if an GPIO on southbridge exists that is connected to a MUX.</span><br><span style="color: hsl(120, 100%, 40%);">+* *panel_hybrid_gpio* sets the GPIO on southbridge that is connected to a LVDS MUX.</span><br><span style="color: hsl(120, 100%, 40%);">+* *has_backlight_gpio* is true if an GPIO on southbridge exists that is connected to a backlight PWM MUX.</span><br><span style="color: hsl(120, 100%, 40%);">+* *backlight_gpio* sets the GPIO on southbridge that is connected to a backlight PWM MUX.</span><br><span style="color: hsl(120, 100%, 40%);">+* *has_dgpu_power_gpio* is true if an GPIO on southbridge exists that enabled dGPU power.</span><br><span style="color: hsl(120, 100%, 40%);">+* *dgpu_power_gpio* sets the GPIO on southbridge that is connected to dGPU power switch.</span><br><span style="color: hsl(120, 100%, 40%);">+* *has_thinker1* is true if the EC is compatible to "Thinker1" register set (T520 and possibly T530) to enable dGPU power.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#### CMOS setting</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Add CMOS setting *hybrid_graphics_mode*:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ * 0 Integrated Only</span><br><span style="color: hsl(120, 100%, 40%);">+ * 1 Discrete Only</span><br><span style="color: hsl(120, 100%, 40%);">+ * 2 Dual graphics</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Proprietary Option ROM usage</span><br><span style="color: hsl(120, 100%, 40%);">+Please note that you have to use the Nvidia/AMD [VGA Option ROM] to drive the second GPU.</span><br><span style="color: hsl(120, 100%, 40%);">+For the integrated Intel GPU you are free to use the [VGA Option ROM] or</span><br><span style="color: hsl(120, 100%, 40%);">+use [Native Graphics Init] or [libgfxinit] to use hybrid graphics.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[VGA Option ROM]: vga_option_roms.md</span><br><span style="color: hsl(120, 100%, 40%);">+[Native Graphics Init]: native_graphics_init.md</span><br><span style="color: hsl(120, 100%, 40%);">+[libgfxinit]: libgfxinit.md</span><br><span style="color: hsl(120, 100%, 40%);">+[Bumblebee on archlinux wiki]: https://wiki.archlinux.org/index.php/bumblebee</span><br><span style="color: hsl(120, 100%, 40%);">+[GitHub Bumblebee Project]: https://github.com/Bumblebee-Project/bbswitch/blob/master/README.md</span><br><span style="color: hsl(120, 100%, 40%);">+[Nvidia Optimus]: https://de.wikipedia.org/wiki/Nvidia_Optimus</span><br><span style="color: hsl(120, 100%, 40%);">+[Hybrid Graphics]: https://en.wikipedia.org/wiki/AMD_Hybrid_Graphics</span><br><span>diff --git a/Documentation/gfx/libgfxinit.md b/Documentation/device/libgfxinit.md</span><br><span>similarity index 100%</span><br><span>rename from Documentation/gfx/libgfxinit.md</span><br><span>rename to Documentation/device/libgfxinit.md</span><br><span>diff --git a/Documentation/device/native_graphics_init.md b/Documentation/device/native_graphics_init.md</span><br><span>new file mode 100644</span><br><span>index 0000000..2a5856e</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/device/native_graphics_init.md</span><br><span>@@ -0,0 +1,46 @@</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+# Native graphics init</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On some platforms the graphics can be initialized using C code.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The platform specific code is written in _C_.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Kconfig</span><br><span style="color: hsl(120, 100%, 40%);">+First do:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+$ make menuconfig</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Then go</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ Devices ---></span><br><span style="color: hsl(120, 100%, 40%);">+ Graphics initialization ---></span><br><span style="color: hsl(120, 100%, 40%);">+ (X) Use native graphics init</span><br><span style="color: hsl(120, 100%, 40%);">+ ( ) Use libgfxinit</span><br><span style="color: hsl(120, 100%, 40%);">+ ( ) Run VGA Option ROMs</span><br><span style="color: hsl(120, 100%, 40%);">+ ( ) None</span><br><span style="color: hsl(120, 100%, 40%);">+ Display ---></span><br><span style="color: hsl(120, 100%, 40%);">+ Framebuffer mode ---></span><br><span style="color: hsl(120, 100%, 40%);">+ ( ) Legacy VGA text mode</span><br><span style="color: hsl(120, 100%, 40%);">+ (X) Linear "high-resolution" framebuffer</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Payloads</span><br><span style="color: hsl(120, 100%, 40%);">+### SeaBIOS</span><br><span style="color: hsl(120, 100%, 40%);">+You can include an open source VGA Option ROM to advertise the NGI</span><br><span style="color: hsl(120, 100%, 40%);">+framebuffer to programs, that use BIOS calls instead of parsing</span><br><span style="color: hsl(120, 100%, 40%);">+coreboot tables. That might be legacy or closed source applications,</span><br><span style="color: hsl(120, 100%, 40%);">+that are able to use a VESA framebuffer.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+First do:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+$ make menuconfig</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Then go</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ Add a payload (SeaBIOS) ---></span><br><span style="color: hsl(120, 100%, 40%);">+ [*] Include generated option rom that implements legacy VGA BIOS</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span>diff --git a/Documentation/device/vga_option_roms.md b/Documentation/device/vga_option_roms.md</span><br><span>new file mode 100644</span><br><span>index 0000000..2b4171b</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/device/vga_option_roms.md</span><br><span>@@ -0,0 +1,273 @@</span><br><span style="color: hsl(120, 100%, 40%);">+# VGA Option ROMs</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Since coreboot v4 you can configure VGA initialization in Kconfig. For older versions of coreboot check the history of this page.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Kconfig</span><br><span style="color: hsl(120, 100%, 40%);">+If you want to run a VGA Option ROM in coreboot select the following Kconfig setting.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+First do:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+$ make menuconfig</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Then go</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ Devices ---></span><br><span style="color: hsl(120, 100%, 40%);">+ Graphics initialization ---></span><br><span style="color: hsl(120, 100%, 40%);">+ ( ) Use native graphics init</span><br><span style="color: hsl(120, 100%, 40%);">+ ( ) Use libgfxinit</span><br><span style="color: hsl(120, 100%, 40%);">+ (X) Run VGA Option ROMs</span><br><span style="color: hsl(120, 100%, 40%);">+ ( ) None</span><br><span style="color: hsl(120, 100%, 40%);">+ [ ] Re-run VGA Option ROMs on S3 resume</span><br><span style="color: hsl(120, 100%, 40%);">+ [X] Load Option ROMs on PCI devices</span><br><span style="color: hsl(120, 100%, 40%);">+ Option ROM execution type ---></span><br><span style="color: hsl(120, 100%, 40%);">+ (X) Native mode</span><br><span style="color: hsl(120, 100%, 40%);">+ ( ) Secure mode</span><br><span style="color: hsl(120, 100%, 40%);">+ Display ---></span><br><span style="color: hsl(120, 100%, 40%);">+ Framebuffer mode ---></span><br><span style="color: hsl(120, 100%, 40%);">+ (X) Legacy VGA text mode</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Alternatively you can choose the ```Secure mode``` to run the VGA Option ROM in a contained environment.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If you have no on-board graphics, you are done configuring coreboot at this point. You may exit configuration, and run make to get your VGA enabled coreboot image.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## On-board Video Devices</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If you run coreboot on a system with on-board graphics, you have to embed a VGA on the top level, enter the file name of your option rom and the PCI ID of the associated graphics device in the form <vendor_id>,<device_id>:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ Devices ---></span><br><span style="color: hsl(120, 100%, 40%);">+ [*] Add a VGA BIOS image</span><br><span style="color: hsl(120, 100%, 40%);">+ (oprom-0.rom) VGA BIOS path and filename</span><br><span style="color: hsl(120, 100%, 40%);">+ (8086,27a2) VGA device PCI IDs</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+That's it, exit configuration, and run make to get your VGA enabled coreboot image.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## How to retrieve a good video bios</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+There are various ways to get hold of the video bios blob and not all work equally good for all boards (rather the opposite).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The best way is to extract it from the vendor firmware.</span><br><span style="color: hsl(120, 100%, 40%);">+In the case of a traditional x86 BIOS this is rather easy and very reliable.</span><br><span style="color: hsl(120, 100%, 40%);">+On UEFI systems there does not seem to be a unified way of success but sometimes the steps below work.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Another category is downloading the blobs directly.</span><br><span style="color: hsl(120, 100%, 40%);">+Some vendors offer them in graphics driver packages etc. and you might even find them on enthusiasts website dedicated to firmware modding etc.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The most delicate ways are by dumping the blob from a running system.</span><br><span style="color: hsl(120, 100%, 40%);">+This might sound like the most reasonable way but the image present after boot might not be the same as it is (to be) stored in flash (e.g. if it is self modifying).</span><br><span style="color: hsl(120, 100%, 40%);">+However, in some cases this is the only way and then it is quite comfortable.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### RECOMMENDED: Extracting from your vendor BIOS image</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The recommended method is to take your mainboard vendor's BIOS image (if there is one) and extract the VGA BIOS using a tool called [[bios_extract]]. If your vendor ships an UEFI image, check out UEFI method below.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ $ git clone http://review.coreboot.org/p/bios_extract.git</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This is the most reliable way:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* You are guaranteed to get an image that fits to your onboard VGA</span><br><span style="color: hsl(120, 100%, 40%);">+* Even if your VGA BIOS uses self-modifying code you get a correct image</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Decompress your rom image with:</span><br><span style="color: hsl(120, 100%, 40%);">+ $ ./bios_extract hdmag217.rom</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If bios_decode fails with a message like</span><br><span style="color: hsl(120, 100%, 40%);">+ Using file "hdmag217.rom" (513kB)</span><br><span style="color: hsl(120, 100%, 40%);">+ Found Phoenix BIOS "Phoenix ServerBIOS 3 Release 6.0 "</span><br><span style="color: hsl(120, 100%, 40%);">+ Version "DEVEL4E0", created on 03/20/06 at 14:37:39.</span><br><span style="color: hsl(120, 100%, 40%);">+ Error: Invalid module signature at 0x80581</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+then you have to cut the flash chip description off the image. In this case the BIOS image is 512KB, so you do</span><br><span style="color: hsl(120, 100%, 40%);">+ $ dd if=hdmag217.rom of=hdma.rom bs=512k count=1</span><br><span style="color: hsl(120, 100%, 40%);">+ 1+0 records in</span><br><span style="color: hsl(120, 100%, 40%);">+ 1+0 records out</span><br><span style="color: hsl(120, 100%, 40%);">+ 524288 bytes transferred in 0.000883 secs (593688784 bytes/sec)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You will get an output similar to this:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ Using file "hdma.rom" (512kB)</span><br><span style="color: hsl(120, 100%, 40%);">+ Found Phoenix BIOS "Phoenix ServerBIOS 3 Release 6.0 "</span><br><span style="color: hsl(120, 100%, 40%);">+ Version "DEVEL4E0", created on 03/20/06 at 14:37:39.</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x715FC ( 27134 bytes) -> romexec_0.rom</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x6E1CB ( 13338 bytes) -> strings_0.rom (29401 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x6D65D ( 2899 bytes) -> display_0.rom (4128 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x6B62E ( 8208 bytes) -> update_0.rom</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x6B1E3 ( 1072 bytes) -> decompcode_0.rom [0x5000:0xB6D0]</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x6564F ( 23421 bytes) -> oprom_0.rom (36864 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x65608 ( 44 bytes) -> tcpa_H_0.rom (32 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x65592 ( 91 bytes) -> acpi_1.rom (116 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x65519 ( 94 bytes) -> acpi_2.rom (244 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x654ED ( 13 bytes) -> tcpa_*_0.rom</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x64D4F ( 1927 bytes) -> bioscode_0.rom (31382 bytes) [0xF000:0x856A]</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x60020 ( 19728 bytes) -> romexec_1.rom</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x570D9 ( 36656 bytes) -> oprom_1.rom (61440 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x4DB9D ( 38177 bytes) -> oprom_2.rom (63488 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x46493 ( 30447 bytes) -> oprom_3.rom (65536 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x41DAB ( 18125 bytes) -> logo_0.rom (310162 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x39CA5 ( 25439 bytes) -> oprom_4.rom (51200 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x36005 ( 15493 bytes) -> setup_0.rom (37682 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x325D7 ( 14867 bytes) -> template_0.rom (37728 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x2FA36 ( 11142 bytes) -> miser_0.rom (16208 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x2E63C ( 5087 bytes) -> tcpa_Q_0.rom (16096 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x2D7C3 ( 3678 bytes) -> acpi_0.rom (10464 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x1FA2A ( 41023 bytes) -> bioscode_1.rom (56080 bytes) [0xE000:0x40F0]</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x14FE0 ( 43567 bytes) -> bioscode_2.rom (62416 bytes) [0x6000:0xCC30]</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x0EB4C ( 25721 bytes) -> bioscode_3.rom (36976 bytes) [0x6000:0x3BC0]</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x0D0A0 ( 6801 bytes) -> bioscode_4.rom (31856 bytes) [0x5000:0xBF50]</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Now you can check the option roms (oprom_?.rom) with the tool romheaders which is part of the [FCode Suite](http://www.openfirmware.info/FCODE_suite) (in debian-based distros, you can get it by installing the '''fcode-utils''' package):</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ $ romheaders oprom_0.rom</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Image 1:</span><br><span style="color: hsl(120, 100%, 40%);">+ PCI Expansion ROM Header:</span><br><span style="color: hsl(120, 100%, 40%);">+ Signature: 0x55aa (Ok)</span><br><span style="color: hsl(120, 100%, 40%);">+ CPU unique data: 0x48 0xeb 0x7b 0x01 0x76 0x00 0x00 0x00</span><br><span style="color: hsl(120, 100%, 40%);">+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00</span><br><span style="color: hsl(120, 100%, 40%);">+ Pointer to PCI Data Structure: 0x017c</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ PCI Data Structure:</span><br><span style="color: hsl(120, 100%, 40%);">+ Signature: 0x50434952 'PCIR' (Ok)</span><br><span style="color: hsl(120, 100%, 40%);">+ Vendor ID: 0x1002</span><br><span style="color: hsl(120, 100%, 40%);">+ Device ID: 0x4752</span><br><span style="color: hsl(120, 100%, 40%);">+ Vital Product Data: 0x0000</span><br><span style="color: hsl(120, 100%, 40%);">+ PCI Data Structure Length: 0x0018 (24 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ PCI Data Structure Revision: 0x00</span><br><span style="color: hsl(120, 100%, 40%);">+ Class Code: 0x030000 (VGA Display controller)</span><br><span style="color: hsl(120, 100%, 40%);">+ Image Length: 0x0048 blocks (36864 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ Revision Level of Code/Data: 0x0421</span><br><span style="color: hsl(120, 100%, 40%);">+ Code Type: 0x00 (Intel x86)</span><br><span style="color: hsl(120, 100%, 40%);">+ Last-Image Flag: 0x80 (last image in rom)</span><br><span style="color: hsl(120, 100%, 40%);">+ Reserved: 0x0000</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Platform specific data for x86 compliant option rom:</span><br><span style="color: hsl(120, 100%, 40%);">+ Initialization Size: 0x48 (36864 bytes)</span><br><span style="color: hsl(120, 100%, 40%);">+ Entry point for INIT function: 0x80</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Congratulations, that's your option rom (compare PCI IDs and Class Code to find it among the option roms).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### UEFI Method</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+UEFI's format is more structured than that of a traditional flat binary BIOS. In order to extract the VBIOS Option ROM you will need</span><br><span style="color: hsl(120, 100%, 40%);">+to parse out the UEFI Volumes and sub-Volumes out the UEFI filesystem using the [UEFITool](https://github.com/LongSoft/UEFITool).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Look for the " CSMCORE " DXE Driver ? usually having the hash 'a062cf1f-8473-4aa3-8793-600bc4ffe9a8'?</span><br><span style="color: hsl(120, 100%, 40%);">+* Search for text "VGA Compatible BIOS" ('''uncheck unicode''')</span><br><span style="color: hsl(120, 100%, 40%);">+* Search for text "PCIR" ('''uncheck unicode''')</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Double clicking the matching line in the "Messages" section should select the appropriate RAW section. From the menu select "Action -> Section -> Extract Body...".</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Downloading</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+There are sites that have video BIOS ROMs on their website (with all implications of retrieving a binary from an unknown source and executing it...).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+For Intel onboard graphics you can download the VBIOS (VGA BIOS) from Intel's download section. The VBIOS is included with some versions of the graphics driver. The summary will say something like "NOTE:These materials are intended for use by developers.Includes VBIOS". The actual VBIOS file is the *.dat file included with the graphics driver.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Retrieval via Linux kernel</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Some Linux drivers (e.g. ___radeon___ for AMD) make option ROMs like the video blob available to user space via sysfs.</span><br><span style="color: hsl(120, 100%, 40%);">+To use that to get the blob you need to enable it first.</span><br><span style="color: hsl(120, 100%, 40%);">+To that end you need to determine the path within ```/sys``` corresponding to your graphics chip.</span><br><span style="color: hsl(120, 100%, 40%);">+It looks like this: ```/sys/devices/pci<domain>:<bus>/<domain>:<bus>:<slot>.<function>/rom```.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You can get the respective information with **lspci**, for example:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ # lspci -tv</span><br><span style="color: hsl(120, 100%, 40%);">+ -[0000:00]-+-00.0 Advanced Micro Devices, Inc. [AMD] Family 16h Processor Root Complex</span><br><span style="color: hsl(120, 100%, 40%);">+ +-01.0 Advanced Micro Devices, Inc. [AMD/ATI] Kabini [Radeon HD 8210]</span><br><span style="color: hsl(120, 100%, 40%);">+ ...</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Here the the needed bits (for the ROM of the Kabini device) are:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* PCI domain: (almost always) 0000</span><br><span style="color: hsl(120, 100%, 40%);">+* PCI bus: (also very commonly) 00</span><br><span style="color: hsl(120, 100%, 40%);">+* PCI slot: 01 (logical slot; different from any physical slots)</span><br><span style="color: hsl(120, 100%, 40%);">+* PCI function: 0 (a PCI device might have multiple functions... shouldn't matter here)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+**Important:** Enable the CSM in the firmware menu.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+To enable reading of the ROM you need to write 1 to the respective file, e.g.:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ echo 1 > /sys/devices/pci0000:00/0000:00:01.0/rom</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The same file should then contain the video blob and it should be possible to simply copy it, e.g.:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+ cp /sys/devices/pci0000:00/0000:00:01.0/rom vgabios.bin</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+**romheaders** should print reasonable output for this file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Intel Graphics supports this method. See [How to dump Video BIOS](https://01.org/linuxgraphics/documentation/development/how-dump-video-bios).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Extraction from mapped memory (if everything else fails)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+However you might be able to retrieve your on-board video BIOS with Linux as well.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Boot up a machine with a commercial BIOS (not coreboot) with the video card you wish to work under coreboot.</span><br><span style="color: hsl(120, 100%, 40%);">+* You can see where and how much your card's bios is using by doing a</span><br><span style="color: hsl(120, 100%, 40%);">+```grep 'Video ROM' /proc/iomem```</span><br><span style="color: hsl(120, 100%, 40%);">+* From the command line enter:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+dd if=/dev/mem of=vgabios.bin bs=1k count=64 skip=768</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This assumes you card's BIOS is cached at 0xc0000, and is 64K long.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+dd if=/dev/mem of=video.bios.bin.4 bs=65536 count=1 skip=12</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This works for many of the VIA Epia boards.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Alternatively you can automatically generate it using this nice script from Peter Stuge:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+cat /proc/iomem | grep 'Video ROM' | (read m; m=${m/ :*}; s=${m/-*}; e=${m/*-}; \</span><br><span style="color: hsl(120, 100%, 40%);">+dd if=/dev/mem of=vgabios.bin bs=1c skip=$[0x$s] count=$[$[0x$e]-$[0x$s]+1])</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* You (might) have a video BIOS image now. Check it at least with romheaders (as described above).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## YABEL</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* Yabel can be used to trace the VGA option rom.</span><br><span style="color: hsl(120, 100%, 40%);">+* However its ability to prevent the option rom to do nasty things is limited:</span><br><span style="color: hsl(120, 100%, 40%);">+Often the GPU offers a way (e.g. trough an IO BAR) to access arbitrary locations in RAM,</span><br><span style="color: hsl(120, 100%, 40%);">+so limiting access of the GPU's PCI device to the option rom wouldn't contain it completely.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Configuration data</span><br><span style="color: hsl(120, 100%, 40%);">+___VGA Option ROMs___ contain configuration data, that are not available if it's not included</span><br><span style="color: hsl(120, 100%, 40%);">+into the build firmware image. OS that rely on those configuration data won't work as expected.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Intel specific:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+On Intel platforms the [Video Bios Tables](https://en.wikipedia.org/wiki/Coreboot/VBT) can be</span><br><span style="color: hsl(120, 100%, 40%);">+added as separate binary data file, extracted from ___VGA Option ROM___ at runtime,</span><br><span style="color: hsl(120, 100%, 40%);">+or generated with minimal information required to run Linux.</span><br><span style="color: hsl(120, 100%, 40%);">+The table (not the whole ___VGA Option ROM___) is fetched via the ACPI OpRegion method.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### AMD specific:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The ___VGA Option ROM___ that include the Video Tables can be fetched via the ACPI ```VFCT``` tables.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Nvidia specific:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The ___VGA Option ROM___ that includes the Video Tables can be fetched via the ACPI method ```_ROM```.</span><br><span>diff --git a/Documentation/index.md b/Documentation/index.md</span><br><span>index afe892d..bebb60e 100644</span><br><span>--- a/Documentation/index.md</span><br><span>+++ b/Documentation/index.md</span><br><span>@@ -13,7 +13,7 @@</span><br><span> * [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)</span><br><span> * [ABI data consumption](abi-data-consumption.md)</span><br><span> * [GPIO toggling in ACPI AML](acpi/gpio.md)</span><br><span style="color: hsl(0, 100%, 40%);">-* [Native Graphics Initialization with libgfxinit](gfx/libgfxinit.md)</span><br><span style="color: hsl(120, 100%, 40%);">+* [Device-specific documentation](device/index.md)</span><br><span> * [Northbridge-specific documentation](northbridge/index.md)</span><br><span> * [System on Chip-specific documentation](soc/index.md)</span><br><span> * [Mainboard-specific documentation](mainboard/index.md)</span><br><span></span><br></pre><p>To view, visit <a href="https://review.coreboot.org/26781">change 26781</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://review.coreboot.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://review.coreboot.org/26781"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: coreboot </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>
<div style="display:none"> Gerrit-Change-Id: I3212af27fb44c6d975fe9def4864d4d027086003 </div>
<div style="display:none"> Gerrit-Change-Number: 26781 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: Patrick Rudolph <siro@das-labor.org> </div>