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