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>

1 files changed, 207 insertions, 156 deletions

diff --git a/util/autoport/readme.md b/util/autoport/readme.md
index 226fcda590..4683d8dd10 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.
-
-## How to use
-
-* 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
+likely to miss EC support. SuperIO support on desktops is more likely to
+work out of the box than any EC.
+
+## How to use autoport
+
+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
-
-* 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.
-
-* 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.
-
-* 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.
-
-* Compile coreboot with console enabled (EHCI debug or serial if present are recommended)
-
-* For recent Intel chipsets you need to avoid overwriting ME firmware. Recommended procedure is
-(replace 8 with your flash size in MiB):
-
-		cp backup.rom flash.rom
-		dd if=coreboot/build/coreboot.rom skip=$[8-1] seek=$[8-1] bs=1M of=flash.rom
-
-* 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.
+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.
+
+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 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.
+
+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!
+
+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!
+
+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.
+
+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.
+
+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:
-
-	phcoder@sid:~/coreboot/util/autoport$ sudo modprobe i2c-dev
-	phcoder@sid:~/coreboot/util/autoport$ sudo i2cdetect -l
+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:
+
+	$ 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.
-
-As this is used only to present information to users then when it matches
-your board and definitions it is correct.
-
-* 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.
+`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:
+
+* `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.
+
+* `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