summaryrefslogtreecommitdiff
path: root/util/autoport/readme.md
diff options
context:
space:
mode:
authorVladimir Serbinenko <phcoder@gmail.com>2014-10-15 21:51:47 +0200
committerVladimir Serbinenko <phcoder@gmail.com>2015-05-29 11:26:29 +0200
commit3129f792f77e310ea246503f8b68b76fc269cfd2 (patch)
tree9f7538131d0cbb87e39f19be9c9d0c56fbf80107 /util/autoport/readme.md
parentb06a249c3b766531ca247bb1278d34875f0d86e4 (diff)
downloadcoreboot-3129f792f77e310ea246503f8b68b76fc269cfd2.tar.xz
autoport: Write autoport together with porting guide for sandy/ivybridge.
This should be able to generate bootable ports for sandy/ivy, possible with minor fixes. Howto is in readme.md Change-Id: Ia126cf0939ef2dc2cdbb7ea100d2b63ea6b02f28 Signed-off-by: Vladimir Serbinenko <phcoder@gmail.com> Reviewed-on: http://review.coreboot.org/7131 Tested-by: build bot (Jenkins) Reviewed-by: Edward O'Callaghan <edward.ocallaghan@koparo.com>
Diffstat (limited to 'util/autoport/readme.md')
-rw-r--r--util/autoport/readme.md383
1 files changed, 383 insertions, 0 deletions
diff --git a/util/autoport/readme.md b/util/autoport/readme.md
new file mode 100644
index 0000000000..4f535fd026
--- /dev/null
+++ b/util/autoport/readme.md
@@ -0,0 +1,383 @@
+# Porting coreboot using autoport
+
+## Supported platforms
+
+### Chipset.
+For any sandybridge or ivybridge platform generated result should
+be bootable, possibly with minor fixes.
+
+### EC
+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 target machine and enable all the device.
+This will allow autoport to detect as much as possible
+* Boot into target machine under GNU/Linux
+* Make sure you have GCC and golang installed
+* Grab coreboot tree
+* Execute following commands starting from coreboot tree
+
+ cd util/ectool
+ make
+ cd ../inteltool
+ make
+ cd ../autoport
+ go build
+ ./autoport --input_log=logs --make_logs --coreboot_dir=../..
+
+* Look for output unknown 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 you machine. Instead keep this new port and logs
+from `util/autoport/logs` somewhere safe
+
+* Disassemble your laptop and locate flash chip <http://flashrom.org/Technology>
+is a great resource. 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 external flasher and read it. Twice. Compare
+the results and retry if they differ. Save the result somewhere safe, in preference
+copy 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.
+
+## 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 `early_southbridge.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
+ i2c-0 i2c i915 gmbus ssc I2C adapter
+ i2c-1 i2c i915 gmbus vga I2C adapter
+ i2c-2 i2c i915 gmbus panel I2C adapter
+ i2c-3 i2c i915 gmbus dpc I2C adapter
+ i2c-4 i2c i915 gmbus dpb I2C adapter
+ i2c-5 i2c i915 gmbus dpd I2C adapter
+ i2c-6 i2c DPDDC-B I2C adapter
+ 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
+ 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.
+ Continue? [Y/n] y
+ 0 1 2 3 4 5 6 7 8 9 a b c d e f
+ 00: -- -- -- -- -- 08 -- -- -- -- -- -- --
+ 10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 20: -- -- -- -- 24 -- -- -- -- -- -- -- -- -- -- --
+ 30: 30 31 -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 50: 50 -- -- -- 54 55 56 57 -- -- -- -- 5c 5d 5e 5f
+ 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:
+
+ void mainboard_get_spd(spd_raw_data *spd) {
+ read_spd (&spd[0], 0x50);
+ read_spd (&spd[1], 0x51);
+ read_spd (&spd[2], 0x52);
+ read_spd (&spd[3], 0x53);
+ }
+
+You can and should omit lines which correspond to
+slots not present on your machine.
+
+This way works well if your RAM is socketed. For soldered RAM if you see
+its SPD, you're in a luck and can proceed the same way although you may have to
+guess some entries due to RAM not being removable.
+
+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:
+
+ /* SPD matching current mode: */
+ /* CH0S0 */
+ 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
+ 30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 65 00
+ 40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 6d 17
+ 80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ c0: 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
+ f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ /* CH1S0 */
+ 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
+ 30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 65 00
+ 40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 6d 17
+ 80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ c0: 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
+ 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:
+
+ 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
+ 30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 65 00
+ 40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 6d 17
+ 80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ c0: 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
+ f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ EOF
+
+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)
+
+ 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:
+
+ 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_get_file_content(CBFS_DEFAULT_MEDIA, "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);
+ }
+
+If several slots are soldered there are 3 ways of doing things:
+
+* 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
+
+### `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.
+
+### `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
+<http://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.
+
+### `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.
+
+If default ROM size when slecting the board is right one than this value
+is correct.
+
+### `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.
+
+## 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.
+
+## `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
+
+* 1 = VGA
+* 2 = TV
+* 3 = DVI
+* 4 = LCD
+
+## `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.
+
+## `install_intel_vga_int15_handler`
+
+This is used to configure int15 hook used by vga bios. 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
+
+## 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:
+
+* Create files `cmos.layout` and `cmos.default`
+* Enable `HAVE_OPTION_TABLE` and `HAVE_CMOS_DEFAULT` in `Kconfig`
+
+## EC (lenovo)
+
+You need to set `has_keyboard_backlight` (backlit keyboard like X230),
+`has_power_management_beeps` (optional beeps when e.g. plugging the cord
+in) and `has_uwb` (third MiniPCIe slot) in accordance to functions available
+on your machine
+
+In rare cases autoport is unable to detect GPE. You can detect it from
+dmesg or ACPI tables. Look for line in dmesg like
+
+ ACPI: EC: GPE = 0x11, I/O: command/status = 0x66, data = 0x62
+
+This means that GPE is `0x11` in ACPI notation. This is the correct
+value for `THINKPAD_EC_GPE`. To get the correct value for `GPE_EC_SCI`
+you need to substract `0x10`, so value for it is `1`.
+
+The pin used to wake the machine from EC is guessed. If your machine doesn't
+wake on lid open and pressing of Fn, change `GPE_EC_WAKE`.
+
+Keep `GPE_EC_WAKE` and `GPE_EC_SCI` in sync with `gpi*_routing`.
+`gpi*_routing` matching `GPE_EC_WAKE` or `GPE_EC_SCI` is set to `2`
+and all others are absent.
+
+If your dock has LPC wires or needs some special treatement you
+need to fill `h8_mainboard_init_dock` and add support code to
+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:
+
+* Control of power and rfkill to different component
+* Keyboard (PS/2) interface implementation
+* Battery, AC, LID and thermal information exporting
+* Hotkey support
+
+autoport automatically attempts to restore the dumped config but it
+may or may not work and may even lead to a hang or powerdown. If your
+machine stops at `Replaying EC dump ...` try commenting EC replay out
+
+autoport tries to detect if machine has PS/2 interface and if so calls
+`pc_keyboard_init` and exports relevant ACPI objects. If detection fails
+you may have to add them yourself
+
+ACPI methods `_PTS` (prepare to sleep) and `_WAK` (wake) are executed
+when transitioning to sleep or wake state respectively. You may need to
+add power-related calls there to either shutdown some components or to
+add a workaround to stop giving OS thermal info until next refresh.
+
+For exporting the battery/AC/LID/hotkey/thermal info you need to write
+`acpi/ec.asl`. For an easy example look into `apple/macbook21` or
+`packardbell/ms2290`. For information about needed methods consult
+relevant ACPI specs. Tracing which EC events can be done using
+[dynamic debug](https://wiki.ubuntu.com/Kernel/Reference/ACPITricksAndTips)
+
+EC GPE needs to be routed to SCI in order for OS in order to receive
+EC events like "hotkey X pressed" or "AC plugged". autoport attempts
+to detect GPE but in rare cases may fail. You can detect it from
+dmesg or ACPI tables. Look for line in dmesg like
+
+ ACPI: EC: GPE = 0x11, I/O: command/status = 0x66, data = 0x62
+
+This means that GPE is `0x11` in ACPI notation. This is the correct
+value for `_GPE`.
+
+Keep GPE in sync with `gpi*_routing`.
+`gpi*_routing` matching `GPE - 0x10` is set to `2`
+and all others are absent. If EC has separate wake pin
+then this GPE needs to be routed as well