Patrick Georgi has submitted this change and it was merged. ( https://review.coreboot.org/c/coreboot/+/30969 )
Change subject: util/autoport: Rewrite readme.md ......................................................................
util/autoport: Rewrite readme.md
The last part of the file has not been modified much.
Change-Id: Icc45824d5d1298146f459d75f0a5121dbdd70d41 Signed-off-by: Angel Pons th3fanbus@gmail.com Reviewed-on: https://review.coreboot.org/c/coreboot/+/30969 Reviewed-by: Patrick Georgi pgeorgi@google.com Tested-by: build bot (Jenkins) no-reply@coreboot.org --- M util/autoport/readme.md 1 file changed, 195 insertions(+), 144 deletions(-)
Approvals: build bot (Jenkins): Verified Patrick Georgi: Looks good to me, approved
diff --git a/util/autoport/readme.md b/util/autoport/readme.md index 226fcda..4683d8d 100644 --- a/util/autoport/readme.md +++ b/util/autoport/readme.md @@ -6,23 +6,27 @@ For any Sandy Bridge or Ivy Bridge platform the generated result should be bootable, possibly with minor fixes.
-### EC +### EC / SuperIO EC support is likely to work on Intel-based thinkpads. Other laptops are -likely to miss EC support. +likely to miss EC support. SuperIO support on desktops is more likely to +work out of the box than any EC.
-## How to use +## How to use autoport
-* Go into BIOS setup on the target machine and enable all devices. -This will allow autoport to detect as much as possible. -* Boot into target machine under GNU/Linux -* Make sure that the following components are installed: - * GCC - * golang - * lspci - * dmidecode - * acpidump -* Grab coreboot tree -* Execute following commands starting from coreboot tree +Enable as many devices as possible in the firmware setup of your system. +This is useful to detect as many devices as possible and make the port +more complete, as disabled devices cannot be detected. + +Boot into target machine under any Linux-based distribution and install +the following tools on it: +* `gcc` +* `golang` +* `lspci` +* `dmidecode` +* `acpidump` (part of `acpica` on some distros) + +Clone the coreboot tree and `cd` into it. For more detailed steps, refer +to Rookie Guide, Lesson 1. Afterwards, run these commands:
cd util/ectool make @@ -34,60 +38,89 @@ go build sudo ./autoport --input_log=logs --make_logs --coreboot_dir=../..
- Note: in case you have problems getting gcc and golang to target machine - you can just compile on another machine and transfer the binaries - `autoport`, `inteltool` and `ectool`. You'll still need other prerequisites - but you may place them in the same directory as autoport. + Note: in case you have problems getting gcc and golang on the target + machine, you can compile the utilities on another computer and copy + the binaries to the target machine. You will still need the other + listed programs on the target machine, but you may place them in the + same directory as autoport.
-* Look for output unknown PCI devices. E.g. +Check for unknown detected PCI devices, e.g.:
Unknown PCI device 8086:0085, assuming removable
-If autoport says `assuming removable` then you're fine. If it doesn't -then you may want to add relevant PCIIDs to autoport. When rerunning -you can skip argument `--make_logs` to reuse the same logs +If autoport says `assuming removable`, you are fine. If it doesn't, +you may want to add the relevant PCI IDs to autoport. Run `lspci -nn` +and check which device this is using the PCI ID. Devices which are not +part of the chipset, such as GPUs or network cards, can be considered +removable, whereas devices inside the CPU or the PCH such as integrated +GPUs and bus controllers (SATA, USB, LPC, SMBus...) are non-removable.
-* At this point the new board is added to the tree but don't flash it -yet as it will brick your machine. Instead keep this new port and the logs -from `util/autoport/logs` somewhere safe. +Your board has now been added to the tree. However, do not flash it +in its current state. It can brick your machine. Instead, keep this +new port and the logs from `util/autoport/logs` somewhere safe. The +following steps will back up your current firmware, which is always +recommended, since coreboot may not boot on the first try.
-* Disassemble your laptop and locate flash chip http://flashrom.org/Technology -is a great resource. The flash chip is usually in `SOIC-8` (2x4 pins) or `SOIC-16` -(2x8 chips). You'll probably have several candidates. Look up what's written on -them and look up what's this chip on the web. +Disassemble your computer and find the flash chip(s). Since there could be +more than one, this guide will refer to "flash chips" as one or more chips. +Refer to http://flashrom.org/Technology as a reference. The flash chip is +usually in a `SOIC-8` (2x4 pins, 200mil) or `SOIC-16` (2x8 pins) package. As +it can be seen on flashrom's wiki, the former package is like any other 8-pin +chip on the mainboard, but it is slightly larger. The latter package is much +easier to locate. Always make sure it is a flash chip by looking up what its +model, printed on it, refers to.
-* Once you know what's the chip is, get an external flasher and read it. Twice. Compare -the results and retry if they differ. Save the result somewhere safe, in preference -copy it to read-only storage as backup. +There may be a smaller flash chip for the EC on some laptops, and other chips +such as network cards may use similar flash chips. These should be left as-is. +If in doubt, ask!
-* Compile coreboot with console enabled (EHCI debug or serial if present are recommended) +Once located, use an external flasher to read the flash chips with `flashrom -r`. +Verify with `flashrom -v` several times that reading is consistent. If it is not, +troubleshoot your flashing setup. Save the results somewhere safe, preferably on +media that cannot be easily overwritten and on several devices. You may need this +later. The write process erases the flash chips first, and erased data on a flash +chip is lost for a very long time, usually forever!
-* For recent Intel chipsets you need to avoid overwriting ME firmware. Recommended procedure is -(replace 8 with your flash size in MiB): +Compile coreboot for your ported mainboard with some console enabled. The most +common ones are EHCI debug, serial port and SPI flash console as a last resort. +If your system is a laptop and has a dedicated video card, you may need to add +a video BIOS (VBIOS) to coreboot to be able to see any video output. Desktop +video cards, as well as some MXM video cards, have this VBIOS on a flash chip +on the card's PCB, so this step is not necessary for them.
- cp backup.rom flash.rom - dd if=coreboot/build/coreboot.rom skip=$[8-1] seek=$[8-1] bs=1M of=flash.rom +Flash coreboot on the machine. On recent Intel chipsets, the flash space is split +in several regions. Only the one known as "BIOS region" should be flashed. If +there is only one flash chip present, this is best done by adding the `--ifd` +and `-i bios` parameters flashrom has (from v1.0 onwards) to specify what flash +descriptor region it should operate on. If the ME (Management Engine) region is +not readable, which is the case on most systems, use the `--noverify-all` +parameter as well.
-* Flash the result -* Boot and grab the log and fix the issues. See next section for useful info. -* grep your board for FIXME. autoport adds comments when it's unsure. Sometimes it's just -a minor check and sometimes it needs more involvment. See next section. -* Send new board to review.coreboot.org. I mean it, your effort is very appreciated. +For systems with two flash chips, this is not so easy. It is probably better to +ask in coreboot or flashrom communication channels, such as via IRC or on the +mailing lists. + +Once flashed, try to boot. Anything is possible. If a log is generated, save it +and use it to address any issues. See the next section for useful information. +Find all the sections marked with `FIXME` and correct them. + +Send your work to review.coreboot.org. I mean it, your effort is very appreciated. +Refer to Rookie Guide, Lesson 2 for instructions on how to submit a patch.
## Manual fixes ### SPD -If you're able to use full memory with any combination of inserted modules than this is -most likely correct. In order to initialize the memory coreboot needs to know RAM timings. -For socketed RAM it's stored in a small EEPROM chip which can be accessed through SPD. Unfortunately -mapping between SPD addresses and RAM slots differs and cannot always be detected automatically. -Resulting SPD map is encoded in function `mainboard_get_spd` in `romstage.c`. -autoport uses the most common map `0x50, 0x51, 0x52, 0x53` except for lenovos which are -known to use `0x50, 0x52, 0x51, 0x53`. To detect the correct memory map the easiest way is with -vendor BIOS to boot with just one module in channel 0 slot 0 and then see where does it show -up in SPD. Under Linux you can see present SPD addresses with following commands: +In order to initialize the RAM memory, coreboot needs to know its timings, which vary between +modules. Socketed RAM has a small EEPROM chip, which is accessible via SMBus and contains the +timing data. This data is usually known as SPD. Unfortunately, the SMBus addresses may not +correlate with the RAM slots and cannot always be detected automatically. The address map is +encoded in function `mainboard_get_spd` in `romstage.c`. By default, autoport uses the most +common map `0x50, 0x51, 0x52, 0x53` on everything except for Lenovo systems, which are known +to use `0x50, 0x52, 0x51, 0x53`. To detect the correct memory map, the easiest way is to boot +on the vendor firmware with just one module in channel 0, slot 0, and check the SMBus address +the EEPROM has. Under Linux, you can use these commands to see what is on SMBus:
- phcoder@sid:~/coreboot/util/autoport$ sudo modprobe i2c-dev - phcoder@sid:~/coreboot/util/autoport$ sudo i2cdetect -l + $ sudo modprobe i2c-dev + $ sudo i2cdetect -l i2c-0 i2c i915 gmbus ssc I2C adapter i2c-1 i2c i915 gmbus vga I2C adapter i2c-2 i2c i915 gmbus panel I2C adapter @@ -98,7 +131,8 @@ i2c-7 i2c DPDDC-C I2C adapter i2c-8 i2c DPDDC-D I2C adapter i2c-9 smbus SMBus I801 adapter at 0400 SMBus adapter - phcoder@sid:~/coreboot/util/autoport$ sudo i2cdetect 9 + + $ sudo i2cdetect 9 WARNING! This program can confuse your I2C bus, cause data loss and worse! I will probe file /dev/i2c-9. I will probe address range 0x03-0x77. @@ -113,10 +147,11 @@ 60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 70: -- -- -- -- -- -- -- --
-Make sure to replace `9` with whatever bus is marked as SMBus. Here in an example -you see SPD at address `0x50`. Since we've booted with just the module in C0S0, so -the first entry in SPD map has to be `0x50`. Once you have SPD map your -`mainboard_get_spd` should look something like: +Make sure to replace the `9` on the last command with the bus number for SMBus on +your system. Here, there is a module at address `0x50`. Since only one module was +installed on the first slot of the first channel, we know the first position of +the SPD array must be `0x50`. After testing all the slots, your `mainboard_get_spd` +should look similar to this:
void mainboard_get_spd(spd_raw_data *spd) { read_spd (&spd[0], 0x50); @@ -125,18 +160,20 @@ read_spd (&spd[3], 0x53); }
-You can and should omit lines which correspond to -slots not present on your machine. +Note that there should be one line per memory slot on the mainboard.
Note: slot labelling may be missing or unreliable. Use `inteltool` to see which slots have modules in them.
-This way works well if your RAM is socketed. For soldered RAM if you see -its SPD, you're in luck and can proceed the same way although you may have to -guess some entries due to RAM not being removable. +This procedure is ideal, if your RAM is socketed. If you have soldered RAM, +remove any socketed memory modules and check if any EEPROM appears on SMBus. +If this is the case, you can proceed as if the RAM was socketed. However, +you may have to guess some entries if there multiple EEPROMs appear.
-Most cases of soldered RAM don't have EEPROM chip. In this case you'd have to create -fake SPD. Look in `inteltool.log`. You'll see something like: +Most of the time, soldered RAM does not have an EEPROM. Instead, the SPD data is +inside the main flash chip where the firmware is. If this is the case, you need +to generate the SPD data to use with coreboot. Look at `inteltool.log`. There +should be something like this:
/* SPD matching current mode: */ /* CH0S0 */ @@ -174,12 +211,12 @@ e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-This is not completely exact represantation of RAM -capablities as it lists only the mode currently used -and lacks minor info like serial number. Using `xxd` -you can create binary represantation of this SPD: +This is not a full-fledged SPD dump, as it only lists +the currently-used speed configuration, and lacks info +such as a serial number, vendor and model. Use `xxd` +to create a binary file with this SPD data:
- cat | xxd -r > spd.bin <<EOF + $ cat | xxd -r > spd.bin <<EOF 00: 92 11 0b 03 04 00 00 09 03 52 01 08 0a 00 80 00 10: 6e 78 6e 32 6e 11 18 81 20 08 3c 3c 00 f0 00 00 20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 @@ -196,109 +233,114 @@ d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 - EOF + EOF (press Ctrl + D)
-Then you can place this file into mainboard directory -and hook it up into build system by adding following -lines to `Makefile.inc` (creating a new file if needed) +Then, move the generated file into your mainboard's directory +and hook it up to the build system by adding the following +lines to `Makefile.inc`:
cbfs-files-y += spd.bin spd.bin-file := spd.bin spd.bin-type := raw
-And then make coreboot actually use this SPD. Following -example shows a hybrid situation with one module -soldered and another is socketed: +Now we need coreboot to use this SPD file. The following example +shows a hybrid configuration, in which one module is soldered and +the other one is socketed:
void mainboard_get_spd(spd_raw_data *spd) { void *spd_file; size_t spd_file_len = 0; - /* C0S0 is a soldered RAM with no real SPD. Use stored SPD. */ - spd_file = cbfs_boot_map_with_leak( "spd.bin", CBFS_TYPE_RAW, + /* C0S0 is a soldered RAM with no real SPD. Use stored SPD. */ + spd_file = cbfs_boot_map_with_leak("spd.bin", CBFS_TYPE_RAW, &spd_file_len); if (spd_file && spd_file_len >= 128) memcpy(&spd[0], spd_file, 128); - /* C0S0 is a DIMM slot. */ - read_spd(&spd[1], 0x51); + + /* C1S0 is a physical slot. */ + read_spd(&spd[2], 0x52); }
-If several slots are soldered there are 3 ways of doing things: +If several slots are soldered there are two ways to handle them:
-* If all of them are the same use the same file. Don't forget to copy -it to all array elements. -* Use several files (recommended). Name them e.g. spd1, spd2,... -* Concatenate it into a single file and split into several -array elements on runtime. Not recommended +* If all use the same SPD data, use the same file for all the slots. Do + not forget to copy the data on all the array elements that need it. +* If they use different data, use several files.
### `board_info.txt`
-`board_info.txt` is a simple text file used to generate wiki page -listing supported boards. Some of the info can't be detected automatically. +`board_info.txt` is a text file used in the board status page to list all +the supported boards and their specifications. Most of the information +cannot be detected by autoport. Common entries are:
-As this is used only to present information to users then when it matches -your board and definitions it is correct. +* `ROM package`, `ROM protocol` and `ROM socketed`: + These refer to the flash chips you found earlier. You can visit + http://flashrom.org/Technology for more information.
-* Which package is used for ROM and whether it's socketed, as well -as release year. For ROM package refer to http://flashrom.org/Technology -and compare it with ROM you found at the beginning of the port. Set -`ROM package`, `ROM socketed` and other variables mentioned in FIXME. -* Release year, just go to web and find that information. -* Category. It's difficult to make difference between desktop and similar -categories from inside the computer. Valid categories are: - * `desktop`. Desktops and workstations. - * `server`. Servers - * `laptop`. Laptops. - * `half`. Embedded / PC/104 / Half-size boards. - * `mini`. Mini-ITX / Micro-ITX / Nano-ITX - * `settop`. Set-top-boxes / Thin clients. - * `eval`. Devel/Eval Boards - * `sbc`. Single-Board computer. - * `emulation`. Virtual machines and emulators. May require especial care - as they often behave differently from real counterparts. - * `misc`. Anything not fitting the categories above. You probably shouldn't use - this. +* `Release year`: Use the power of Internet to find that information. +* `Category`: This describes the type of mainboard you have. + Valid categories are: + * `desktop`. Desktops and workstations. + * `server`. Servers. + * `laptop`. Laptops, notebooks and netbooks. + * `half`. Embedded / PC/104 / Half-size boards. + * `mini`. Mini-ITX / Micro-ITX / Nano-ITX + * `settop`. Set-top-boxes / Thin clients. + * `eval`. Development / Evaluation Boards. + * `sbc`. Single-Board computer. + * `emulation`: Virtual machines and emulators. May require especial care + as they often behave differently from real counterparts. + * `misc`. Anything not fitting the categories above. Not recommended. + +* `Flashrom support`: This means whether the internal programmer is usable. + If flashing coreboot internally works, this should be set to `y`. Else, + feel free to investigate why it is not working.
### `USBDEBUG_HCD_INDEX`
-Which controller the most easily accessible USB debug port is. On intel -1 is for `00:1d.0` and 2 is `00:1a.0` (yes, it's reversed). See +Which controller the most easily accessible USB debug port is. On Intel, +1 is for `00:1d.0` and 2 is for `00:1a.0` (yes, it's reversed). Refer to https://www.coreboot.org/EHCI_Debug_Port for more info.
-If you're able to use EHCI debug port without setting HCD index manually -in config this is correct. +If you are able to use EHCI debug without setting the HCD index manually, +this is correct.
### `BOARD_ROMSIZE_KB_2048`
-Default rom size should be detected automatically but sometimes isn't. -If yours weren't detected put correct rom size here to serve as sane -default when configuring coreboot. +This parameter refers to the total size of the flash chips coreboot will be in. +This value must be correct for S3 resume to work properly. This parameter also +defines the size of the generated coreboot image, but that is not a major issue +since tools like `dd` can be used to cut fragments of a coreboot image to flash +on smaller chips.
-If default ROM size when slecting the board is right one than this value -is correct. +This should be detected automatically, but it may not be detected properly in +some cases. If it was not detected, put the correct total size here to serve +as a sane default when configuring coreboot.
### `DRAM_RESET_GATE_GPIO`
-When machine is going to S3 in order not to reset the RAM modules, the -reset signal must be filtered out from reachin RAM. This is done by -powering down a special gate. Most manufacturers put this gate on -GPIO 60 but Lenovo is knowon to put it on GPIO 10. If you're able to -go to S3 and back than this value is correct. +When the computer is suspended to RAM (ACPI S3), the RAM reset signal must not +reach the RAM modules. Otherwise, the computer will not resume and any opened +programs will be lost. This is done by powering down a MOSFET, which disconnects +the reset signal from the RAM modules. Most manufacturers put this gate on GPIO +60 but Lenovo is known to put it on GPIO 10. If suspending and resuming works, +this value is correct. This can also be determined from the board's schematics.
## GNVS
-`acpi_create_gnvs` sets values in GNVS which in turn is used by ACPI for -various power-related functions. Normally there is no need to modify it -but it makes sense to proofread it. +`acpi_create_gnvs` sets values in GNVS, which then ACPI makes use of for +various power-related functions. Normally, there is no need to modify it +on laptops (desktops have no "lid"!) but it makes sense to proofread it.
## `gfx.ndid` and `gfx.did`
Those describe which video outputs are declared in ACPI tables. -Normally there is no need to adjust but if you miss some nonstandard output -you can declare it there. Bit 31 is set to indicate presence of the output. -Byte 1 is the type and byte 0 is used for disambigution so that ID composed of -byte 1 and 0 is unique. Types are +Normally, there is no need to adjust these values, but if you miss some +non-standard video output, you can declare it there. Bit 31 is set to +indicate the presence of the output. Byte 1 is the type and byte 0 is +used for disambigution so that ID composed of byte 1 and 0 is unique.
+Types are: * 1 = VGA * 2 = TV * 3 = DVI @@ -306,22 +348,31 @@
## `c*_acpower` and `c*_battery`
-Which mwait states to match to which ACPI levels. Normally no need to modify unless -your device has very special power saving requirements. +Which mwait states to match to which ACPI levels. Normall, there is no +need to modify anything unless your device has very special power +saving requirements.
## `install_intel_vga_int15_handler`
-This is used to configure int15 hook used by vgabios. Parameters 2 and 3 usually -shouldn't be modified as vgabios is quite ok to figure panel fit and active -output by itself. Last number is the numerical ID of display type. If you -don't get any output with vgabios you should try different values for 4th -parameter. If it doesn't help try different values for first parameter as well +This is used with the Intel VGA BIOS, which is not the default option. +It is more error-prone than open-source graphics initialization, so do +not bother with this until your mainboard boots. This is a function +which takes four parameters: +1. Which type of LCD panel is connected. +2. Panel fit. +3. Boot display. +4. Display type. + +Refer to `src/drivers/intel/gma/int15.h` to see which values can be used. +For desktops, there is no LCD panel directly connected to the Intel GPU, +so the first parameter should be `GMA_INT15_ACTIVE_LFP_NONE`. On other +mainboards, it depends.
## CMOS options
-Due to horrible state of CMOS support in coreboot tree, autoport doesn't support it and -this probably won't change until format in the tree improves. If you really care about -CMOS options: +Due to the poor state of CMOS support in coreboot, autoport does not +support it and this probably won't change until the format in the tree +improves. If you really care about CMOS options:
* Create files `cmos.layout` and `cmos.default` * Enable `HAVE_OPTION_TABLE` and `HAVE_CMOS_DEFAULT` in `Kconfig` @@ -355,9 +406,9 @@
## EC (generic laptop)
-Almost any laptop has an embedded controller. In nutshell it's a small -low-powered computer specialised on managing power for laptop. Exact -functionality differs between macines but of interest to us is mainly: +Almost any laptop has an embedded controller. In a nutshell, it's a +small, low-powered computer designed to be used on laptops. Exact +functionality differs between machines. Its main functions include:
* Control of power and rfkill to different component * Keyboard (PS/2) interface implementation