GNUBoot
/
coreboot-kgpe-d16
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

339
util/autoport/readme.md
View File

@ -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 @@ This will allow autoport to detect as much as possible.
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 @@ up in SPD. Under Linux you can see present SPD addresses with following commands
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 @@ up in SPD. Under Linux you can see present SPD addresses with following commands
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 @@ the first entry in SPD map has to be `0x50`. Once you have SPD map your
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 @@ 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
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 @@ 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
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 @@ byte 1 and 0 is unique. Types are
## `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 @@ DSDT. See the code for `x60`, `x200` or `x201`
## 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