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>
This commit is contained in:
Angel Pons 2019-01-16 20:51:01 +01:00 committed by Patrick Georgi
parent 08caa792e6
commit 22add8ea30
1 changed files with 195 additions and 144 deletions

View File

@ -6,23 +6,27 @@
For any Sandy Bridge or Ivy Bridge platform the generated result should For any Sandy Bridge or Ivy Bridge platform the generated result should
be bootable, possibly with minor fixes. be bootable, possibly with minor fixes.
### EC ### EC / SuperIO
EC support is likely to work on Intel-based thinkpads. Other laptops are 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. Enable as many devices as possible in the firmware setup of your system.
This will allow autoport to detect as much as possible. This is useful to detect as many devices as possible and make the port
* Boot into target machine under GNU/Linux more complete, as disabled devices cannot be detected.
* Make sure that the following components are installed:
* GCC Boot into target machine under any Linux-based distribution and install
* golang the following tools on it:
* lspci * `gcc`
* dmidecode * `golang`
* acpidump * `lspci`
* Grab coreboot tree * `dmidecode`
* Execute following commands starting from coreboot tree * `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 cd util/ectool
make make
@ -34,60 +38,89 @@ This will allow autoport to detect as much as possible.
go build go build
sudo ./autoport --input_log=logs --make_logs --coreboot_dir=../.. sudo ./autoport --input_log=logs --make_logs --coreboot_dir=../..
Note: in case you have problems getting gcc and golang to target machine Note: in case you have problems getting gcc and golang on the target
you can just compile on another machine and transfer the binaries machine, you can compile the utilities on another computer and copy
`autoport`, `inteltool` and `ectool`. You'll still need other prerequisites the binaries to the target machine. You will still need the other
but you may place them in the same directory as autoport. 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 Unknown PCI device 8086:0085, assuming removable
If autoport says `assuming removable` then you're fine. If it doesn't If autoport says `assuming removable`, you are fine. If it doesn't,
then you may want to add relevant PCIIDs to autoport. When rerunning you may want to add the relevant PCI IDs to autoport. Run `lspci -nn`
you can skip argument `--make_logs` to reuse the same logs 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 Your board has now been added to the tree. However, do not flash it
yet as it will brick your machine. Instead keep this new port and the logs in its current state. It can brick your machine. Instead, keep this
from `util/autoport/logs` somewhere safe. 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> Disassemble your computer and find the flash chip(s). Since there could be
is a great resource. The flash chip is usually in `SOIC-8` (2x4 pins) or `SOIC-16` more than one, this guide will refer to "flash chips" as one or more chips.
(2x8 chips). You'll probably have several candidates. Look up what's written on Refer to <http://flashrom.org/Technology> as a reference. The flash chip is
them and look up what's this chip on the web. 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 There may be a smaller flash chip for the EC on some laptops, and other chips
the results and retry if they differ. Save the result somewhere safe, in preference such as network cards may use similar flash chips. These should be left as-is.
copy it to read-only storage as backup. 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 Compile coreboot for your ported mainboard with some console enabled. The most
(replace 8 with your flash size in MiB): 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 Flash coreboot on the machine. On recent Intel chipsets, the flash space is split
dd if=coreboot/build/coreboot.rom skip=$[8-1] seek=$[8-1] bs=1M of=flash.rom 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 For systems with two flash chips, this is not so easy. It is probably better to
* Boot and grab the log and fix the issues. See next section for useful info. ask in coreboot or flashrom communication channels, such as via IRC or on the
* grep your board for FIXME. autoport adds comments when it's unsure. Sometimes it's just mailing lists.
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. 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 ## Manual fixes
### SPD ### SPD
If you're able to use full memory with any combination of inserted modules than this is In order to initialize the RAM memory, coreboot needs to know its timings, which vary between
most likely correct. In order to initialize the memory coreboot needs to know RAM timings. modules. Socketed RAM has a small EEPROM chip, which is accessible via SMBus and contains the
For socketed RAM it's stored in a small EEPROM chip which can be accessed through SPD. Unfortunately timing data. This data is usually known as SPD. Unfortunately, the SMBus addresses may not
mapping between SPD addresses and RAM slots differs and cannot always be detected automatically. correlate with the RAM slots and cannot always be detected automatically. The address map is
Resulting SPD map is encoded in function `mainboard_get_spd` in `romstage.c`. encoded in function `mainboard_get_spd` in `romstage.c`. By default, autoport uses the most
autoport uses the most common map `0x50, 0x51, 0x52, 0x53` except for lenovos which are common map `0x50, 0x51, 0x52, 0x53` on everything except for Lenovo systems, which are known
known to use `0x50, 0x52, 0x51, 0x53`. To detect the correct memory map the easiest way is with to use `0x50, 0x52, 0x51, 0x53`. To detect the correct memory map, the easiest way is to boot
vendor BIOS to boot with just one module in channel 0 slot 0 and then see where does it show on the vendor firmware with just one module in channel 0, slot 0, and check the SMBus address
up in SPD. Under Linux you can see present SPD addresses with following commands: 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 $ sudo modprobe i2c-dev
phcoder@sid:~/coreboot/util/autoport$ sudo i2cdetect -l $ sudo i2cdetect -l
i2c-0 i2c i915 gmbus ssc I2C adapter i2c-0 i2c i915 gmbus ssc I2C adapter
i2c-1 i2c i915 gmbus vga I2C adapter i2c-1 i2c i915 gmbus vga I2C adapter
i2c-2 i2c i915 gmbus panel I2C adapter i2c-2 i2c i915 gmbus panel I2C adapter
@ -98,7 +131,8 @@ up in SPD. Under Linux you can see present SPD addresses with following commands
i2c-7 i2c DPDDC-C I2C adapter i2c-7 i2c DPDDC-C I2C adapter
i2c-8 i2c DPDDC-D I2C adapter i2c-8 i2c DPDDC-D I2C adapter
i2c-9 smbus SMBus I801 adapter at 0400 SMBus 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! WARNING! This program can confuse your I2C bus, cause data loss and worse!
I will probe file /dev/i2c-9. I will probe file /dev/i2c-9.
I will probe address range 0x03-0x77. I will probe address range 0x03-0x77.
@ -113,10 +147,11 @@ up in SPD. Under Linux you can see present SPD addresses with following commands
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- -- 70: -- -- -- -- -- -- -- --
Make sure to replace `9` with whatever bus is marked as SMBus. Here in an example Make sure to replace the `9` on the last command with the bus number for SMBus on
you see SPD at address `0x50`. Since we've booted with just the module in C0S0, so your system. Here, there is a module at address `0x50`. Since only one module was
the first entry in SPD map has to be `0x50`. Once you have SPD map your installed on the first slot of the first channel, we know the first position of
`mainboard_get_spd` should look something like: 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) { void mainboard_get_spd(spd_raw_data *spd) {
read_spd (&spd[0], 0x50); read_spd (&spd[0], 0x50);
@ -125,18 +160,20 @@ the first entry in SPD map has to be `0x50`. Once you have SPD map your
read_spd (&spd[3], 0x53); read_spd (&spd[3], 0x53);
} }
You can and should omit lines which correspond to Note that there should be one line per memory slot on the mainboard.
slots not present on your machine.
Note: slot labelling may be missing or unreliable. Use `inteltool` to see Note: slot labelling may be missing or unreliable. Use `inteltool` to see
which slots have modules in them. which slots have modules in them.
This way works well if your RAM is socketed. For soldered RAM if you see This procedure is ideal, if your RAM is socketed. If you have soldered RAM,
its SPD, you're in luck and can proceed the same way although you may have to remove any socketed memory modules and check if any EEPROM appears on SMBus.
guess some entries due to RAM not being removable. 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 Most of the time, soldered RAM does not have an EEPROM. Instead, the SPD data is
fake SPD. Look in `inteltool.log`. You'll see something like: 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: */ /* SPD matching current mode: */
/* CH0S0 */ /* CH0S0 */
@ -174,12 +211,12 @@ fake SPD. Look in `inteltool.log`. You'll see something like:
e0: 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 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 This is not a full-fledged SPD dump, as it only lists
capablities as it lists only the mode currently used the currently-used speed configuration, and lacks info
and lacks minor info like serial number. Using `xxd` such as a serial number, vendor and model. Use `xxd`
you can create binary represantation of this SPD: 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 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 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 20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
@ -196,109 +233,114 @@ you can create binary represantation of this SPD:
d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 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 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 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 Then, move the generated file into your mainboard's directory
and hook it up into build system by adding following and hook it up to the build system by adding the following
lines to `Makefile.inc` (creating a new file if needed) lines to `Makefile.inc`:
cbfs-files-y += spd.bin cbfs-files-y += spd.bin
spd.bin-file := spd.bin spd.bin-file := spd.bin
spd.bin-type := raw spd.bin-type := raw
And then make coreboot actually use this SPD. Following Now we need coreboot to use this SPD file. The following example
example shows a hybrid situation with one module shows a hybrid configuration, in which one module is soldered and
soldered and another is socketed: the other one is socketed:
void mainboard_get_spd(spd_raw_data *spd) void mainboard_get_spd(spd_raw_data *spd)
{ {
void *spd_file; void *spd_file;
size_t spd_file_len = 0; size_t spd_file_len = 0;
/* C0S0 is a soldered RAM with no real SPD. Use stored SPD. */ /* 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 = cbfs_boot_map_with_leak("spd.bin", CBFS_TYPE_RAW,
&spd_file_len); &spd_file_len);
if (spd_file && spd_file_len >= 128) if (spd_file && spd_file_len >= 128)
memcpy(&spd[0], spd_file, 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 * If all use the same SPD data, use the same file for all the slots. Do
it to all array elements. not forget to copy the data on all the array elements that need it.
* Use several files (recommended). Name them e.g. spd1, spd2,... * If they use different data, use several files.
* Concatenate it into a single file and split into several
array elements on runtime. Not recommended
### `board_info.txt` ### `board_info.txt`
`board_info.txt` is a simple text file used to generate wiki page `board_info.txt` is a text file used in the board status page to list all
listing supported boards. Some of the info can't be detected automatically. 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 * `ROM package`, `ROM protocol` and `ROM socketed`:
your board and definitions it is correct. 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 * `Release year`: Use the power of Internet to find that information.
as release year. For ROM package refer to <http://flashrom.org/Technology> * `Category`: This describes the type of mainboard you have.
and compare it with ROM you found at the beginning of the port. Set Valid categories are:
`ROM package`, `ROM socketed` and other variables mentioned in FIXME. * `desktop`. Desktops and workstations.
* Release year, just go to web and find that information. * `server`. Servers.
* Category. It's difficult to make difference between desktop and similar * `laptop`. Laptops, notebooks and netbooks.
categories from inside the computer. Valid categories are: * `half`. Embedded / PC/104 / Half-size boards.
* `desktop`. Desktops and workstations. * `mini`. Mini-ITX / Micro-ITX / Nano-ITX
* `server`. Servers * `settop`. Set-top-boxes / Thin clients.
* `laptop`. Laptops. * `eval`. Development / Evaluation Boards.
* `half`. Embedded / PC/104 / Half-size boards. * `sbc`. Single-Board computer.
* `mini`. Mini-ITX / Micro-ITX / Nano-ITX * `emulation`: Virtual machines and emulators. May require especial care
* `settop`. Set-top-boxes / Thin clients. as they often behave differently from real counterparts.
* `eval`. Devel/Eval Boards * `misc`. Anything not fitting the categories above. Not recommended.
* `sbc`. Single-Board computer.
* `emulation`. Virtual machines and emulators. May require especial care * `Flashrom support`: This means whether the internal programmer is usable.
as they often behave differently from real counterparts. If flashing coreboot internally works, this should be set to `y`. Else,
* `misc`. Anything not fitting the categories above. You probably shouldn't use feel free to investigate why it is not working.
this.
### `USBDEBUG_HCD_INDEX` ### `USBDEBUG_HCD_INDEX`
Which controller the most easily accessible USB debug port is. On intel 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 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. <https://www.coreboot.org/EHCI_Debug_Port> for more info.
If you're able to use EHCI debug port without setting HCD index manually If you are able to use EHCI debug without setting the HCD index manually,
in config this is correct. this is correct.
### `BOARD_ROMSIZE_KB_2048` ### `BOARD_ROMSIZE_KB_2048`
Default rom size should be detected automatically but sometimes isn't. This parameter refers to the total size of the flash chips coreboot will be in.
If yours weren't detected put correct rom size here to serve as sane This value must be correct for S3 resume to work properly. This parameter also
default when configuring coreboot. 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 This should be detected automatically, but it may not be detected properly in
is correct. 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` ### `DRAM_RESET_GATE_GPIO`
When machine is going to S3 in order not to reset the RAM modules, the When the computer is suspended to RAM (ACPI S3), the RAM reset signal must not
reset signal must be filtered out from reachin RAM. This is done by reach the RAM modules. Otherwise, the computer will not resume and any opened
powering down a special gate. Most manufacturers put this gate on programs will be lost. This is done by powering down a MOSFET, which disconnects
GPIO 60 but Lenovo is knowon to put it on GPIO 10. If you're able to the reset signal from the RAM modules. Most manufacturers put this gate on GPIO
go to S3 and back than this value is correct. 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 ## GNVS
`acpi_create_gnvs` sets values in GNVS which in turn is used by ACPI for `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 various power-related functions. Normally, there is no need to modify it
but it makes sense to proofread it. on laptops (desktops have no "lid"!) but it makes sense to proofread it.
## `gfx.ndid` and `gfx.did` ## `gfx.ndid` and `gfx.did`
Those describe which video outputs are declared in ACPI tables. Those describe which video outputs are declared in ACPI tables.
Normally there is no need to adjust but if you miss some nonstandard output Normally, there is no need to adjust these values, but if you miss some
you can declare it there. Bit 31 is set to indicate presence of the output. non-standard video output, you can declare it there. Bit 31 is set to
Byte 1 is the type and byte 0 is used for disambigution so that ID composed of indicate the presence of the output. Byte 1 is the type and byte 0 is
byte 1 and 0 is unique. Types are used for disambigution so that ID composed of byte 1 and 0 is unique.
Types are:
* 1 = VGA * 1 = VGA
* 2 = TV * 2 = TV
* 3 = DVI * 3 = DVI
@ -306,22 +348,31 @@ byte 1 and 0 is unique. Types are
## `c*_acpower` and `c*_battery` ## `c*_acpower` and `c*_battery`
Which mwait states to match to which ACPI levels. Normally no need to modify unless Which mwait states to match to which ACPI levels. Normall, there is no
your device has very special power saving requirements. need to modify anything unless your device has very special power
saving requirements.
## `install_intel_vga_int15_handler` ## `install_intel_vga_int15_handler`
This is used to configure int15 hook used by vgabios. Parameters 2 and 3 usually This is used with the Intel VGA BIOS, which is not the default option.
shouldn't be modified as vgabios is quite ok to figure panel fit and active It is more error-prone than open-source graphics initialization, so do
output by itself. Last number is the numerical ID of display type. If you not bother with this until your mainboard boots. This is a function
don't get any output with vgabios you should try different values for 4th which takes four parameters:
parameter. If it doesn't help try different values for first parameter as well 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 ## CMOS options
Due to horrible state of CMOS support in coreboot tree, autoport doesn't support it and Due to the poor state of CMOS support in coreboot, autoport does not
this probably won't change until format in the tree improves. If you really care about support it and this probably won't change until the format in the tree
CMOS options: improves. If you really care about CMOS options:
* Create files `cmos.layout` and `cmos.default` * Create files `cmos.layout` and `cmos.default`
* Enable `HAVE_OPTION_TABLE` and `HAVE_CMOS_DEFAULT` in `Kconfig` * Enable `HAVE_OPTION_TABLE` and `HAVE_CMOS_DEFAULT` in `Kconfig`
@ -355,9 +406,9 @@ DSDT. See the code for `x60`, `x200` or `x201`
## EC (generic laptop) ## EC (generic laptop)
Almost any laptop has an embedded controller. In nutshell it's a small Almost any laptop has an embedded controller. In a nutshell, it's a
low-powered computer specialised on managing power for laptop. Exact small, low-powered computer designed to be used on laptops. Exact
functionality differs between macines but of interest to us is mainly: functionality differs between machines. Its main functions include:
* Control of power and rfkill to different component * Control of power and rfkill to different component
* Keyboard (PS/2) interface implementation * Keyboard (PS/2) interface implementation