util/autoport/readme.md

   1 # Porting coreboot using autoport
   2
   3 ## Supported platforms
   4
   5 ### Chipset
   6 For any Sandy Bridge or Ivy Bridge platform the generated result should
   7 be bootable, possibly with minor fixes.
   8
   9 ### EC
  10 EC support is likely to work on Intel-based thinkpads. Other laptops are
  11 likely to miss EC support.
  12
  13 ## How to use
  14
  15 * Go into BIOS setup on the target machine and enable all devices.
  16 This will allow autoport to detect as much as possible.
  17 * Boot into target machine under GNU/Linux
  18 * Make sure that the following components are installed:
  19   * GCC
  20   * golang
  21   * lspci
  22   * dmidecode
  23   * acpidump
  24 * Grab coreboot tree
  25 * Execute following commands starting from coreboot tree
  26
  27                 cd util/ectool
  28                 make
  29                 cd ../inteltool
  30                 make
  31                 cd ../superiotool
  32                 make
  33                 cd ../autoport
  34                 go build
  35                 sudo ./autoport --input_log=logs --make_logs --coreboot_dir=../..
  36
  37         Note: in case you have problems getting gcc and golang to target machine
  38         you can just compile on another machine and transfer the binaries
  39         `autoport`, `inteltool` and `ectool`. You'll still need other prerequisites
  40         but you may place them in the same directory as autoport.
  41
  42 * Look for output unknown PCI devices. E.g.
  43
  44                 Unknown PCI device 8086:0085, assuming removable
  45
  46 If autoport says `assuming removable` then you're fine. If it doesn't
  47 then you may want to add relevant PCIIDs to autoport. When rerunning
  48 you can skip argument `--make_logs` to reuse the same logs
  49
  50 * At this point the new board is added to the tree but don't flash it
  51 yet as it will brick your machine. Instead keep this new port and the logs
  52 from `util/autoport/logs` somewhere safe.
  53
  54 * Disassemble your laptop and locate flash chip <http://flashrom.org/Technology>
  55 is a great resource. The flash chip is usually in `SOIC-8` (2x4 pins) or `SOIC-16`
  56 (2x8 chips). You'll probably have several candidates. Look up what's written on
  57 them and look up what's this chip on the web.
  58
  59 * Once you know what's the chip is, get an external flasher and read it. Twice. Compare
  60 the results and retry if they differ. Save the result somewhere safe, in preference
  61 copy it to read-only storage as backup.
  62
  63 * Compile coreboot with console enabled (EHCI debug or serial if present are recommended)
  64
  65 * For recent Intel chipsets you need to avoid overwriting ME firmware. Recommended procedure is
  66 (replace 8 with your flash size in MiB):
  67
  68                 cp backup.rom flash.rom
  69                 dd if=coreboot/build/coreboot.rom skip=$[8-1] seek=$[8-1] bs=1M of=flash.rom
  70
  71 * Flash the result
  72 * Boot and grab the log and fix the issues. See next section for useful info.
  73 * grep your board for FIXME. autoport adds comments when it's unsure. Sometimes it's just
  74 a minor check and sometimes it needs more involvment. See next section.
  75 * Send new board to review.coreboot.org. I mean it, your effort is very appreciated.
  76
  77 ## Manual fixes
  78 ### SPD
  79 If you're able to use full memory with any combination of inserted modules than this is
  80 most likely correct. In order to initialize the memory coreboot needs to know RAM timings.
  81 For socketed RAM it's stored in a small EEPROM chip which can be accessed through SPD. Unfortunately
  82 mapping between SPD addresses and RAM slots differs and cannot always be detected automatically.
  83 Resulting SPD map is encoded in function `mainboard_get_spd` in `romstage.c`.
  84 autoport uses the most common map `0x50, 0x51, 0x52, 0x53` except for lenovos which are
  85 known to use `0x50, 0x52, 0x51, 0x53`. To detect the correct memory map the easiest way is with
  86 vendor BIOS to boot with just one module in channel 0 slot 0 and then see where does it show
  87 up in SPD. Under Linux you can see present SPD addresses with following commands:
  88
  89         phcoder@sid:~/coreboot/util/autoport$ sudo modprobe i2c-dev
  90         phcoder@sid:~/coreboot/util/autoport$ sudo i2cdetect -l
  91         i2c-0   i2c             i915 gmbus ssc                          I2C adapter
  92         i2c-1   i2c             i915 gmbus vga                          I2C adapter
  93         i2c-2   i2c             i915 gmbus panel                        I2C adapter
  94         i2c-3   i2c             i915 gmbus dpc                          I2C adapter
  95         i2c-4   i2c             i915 gmbus dpb                          I2C adapter
  96         i2c-5   i2c             i915 gmbus dpd                          I2C adapter
  97         i2c-6   i2c             DPDDC-B                                 I2C adapter
  98         i2c-7   i2c             DPDDC-C                                 I2C adapter
  99         i2c-8   i2c             DPDDC-D                                 I2C adapter
 100         i2c-9   smbus           SMBus I801 adapter at 0400              SMBus adapter
 101         phcoder@sid:~/coreboot/util/autoport$ sudo i2cdetect 9
 102         WARNING! This program can confuse your I2C bus, cause data loss and worse!
 103         I will probe file /dev/i2c-9.
 104         I will probe address range 0x03-0x77.
 105         Continue? [Y/n] y
 106              0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
 107         00:          -- -- -- -- -- 08 -- -- -- -- -- -- --
 108         10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
 109         20: -- -- -- -- 24 -- -- -- -- -- -- -- -- -- -- --
 110         30: 30 31 -- -- -- -- -- -- -- -- -- -- -- -- -- --
 111         40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
 112         50: 50 -- -- -- 54 55 56 57 -- -- -- -- 5c 5d 5e 5f
 113         60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
 114         70: -- -- -- -- -- -- -- --
 115
 116 Make sure to replace `9` with whatever bus is marked as SMBus. Here in an example
 117 you see SPD at address `0x50`. Since we've booted with just the module in C0S0, so
 118 the first entry in SPD map has to be `0x50`. Once you have SPD map your
 119 `mainboard_get_spd` should look something like:
 120
 121         void mainboard_get_spd(spd_raw_data *spd) {
 122                 read_spd (&spd[0], 0x50);
 123                 read_spd (&spd[1], 0x51);
 124                 read_spd (&spd[2], 0x52);
 125                 read_spd (&spd[3], 0x53);
 126         }
 127
 128 You can and should omit lines which correspond to
 129 slots not present on your machine.
 130
 131 Note: slot labelling may be missing or unreliable. Use `inteltool` to see
 132 which slots have modules in them.
 133
 134 This way works well if your RAM is socketed. For soldered RAM if you see
 135 its SPD, you're in luck and can proceed the same way although you may have to
 136 guess some entries due to RAM not being removable.
 137
 138 Most cases of soldered RAM don't have EEPROM chip. In this case you'd have to create
 139 fake SPD. Look in `inteltool.log`. You'll see something like:
 140
 141         /* SPD matching current mode:  */
 142         /* CH0S0  */
 143         00: 92 11 0b 03 04 00 00 09 03 52 01 08 0a 00 80 00
 144         10: 6e 78 6e 32 6e 11 18 81 20 08 3c 3c 00 f0 00 00
 145         20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 146         30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 65 00
 147         40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 148         50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 149         60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 150         70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 6d 17
 151         80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 152         90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 153         a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 154         b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 155         c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 156         d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 157         e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 158         f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 159         /* CH1S0  */
 160         00: 92 11 0b 03 04 00 00 09 03 52 01 08 0a 00 80 00
 161         10: 6e 78 6e 32 6e 11 18 81 20 08 3c 3c 00 f0 00 00
 162         20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 163         30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 65 00
 164         40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 165         50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 166         60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 167         70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 6d 17
 168         80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 169         90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 170         a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 171         b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 172         c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 173         d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 174         e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 175         f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 176
 177 This is not completely exact represantation of RAM
 178 capablities as it lists only the mode currently used
 179 and lacks minor info like serial number. Using `xxd`
 180 you can create binary represantation of this SPD:
 181
 182         cat | xxd -r > spd.bin  <<EOF
 183         00: 92 11 0b 03 04 00 00 09 03 52 01 08 0a 00 80 00
 184         10: 6e 78 6e 32 6e 11 18 81 20 08 3c 3c 00 f0 00 00
 185         20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 186         30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 65 00
 187         40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 188         50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 189         60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 190         70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 6d 17
 191         80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 192         90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 193         a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 194         b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 195         c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 196         d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 197         e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 198         f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 199         EOF
 200
 201 Then you can place this file into mainboard directory
 202 and hook it up into build system by adding following
 203 lines to `Makefile.inc` (creating a new file if needed)
 204
 205         cbfs-files-y += spd.bin
 206         spd.bin-file := spd.bin
 207         spd.bin-type := raw
 208
 209 And then make coreboot actually use this SPD. Following
 210 example shows a hybrid situation with one module
 211 soldered and another is socketed:
 212
 213         void mainboard_get_spd(spd_raw_data *spd)
 214         {
 215                 void *spd_file;
 216                 size_t spd_file_len = 0;
 217                 /* C0S0 is a soldered RAM with no real SPD. Use stored SPD.  */
 218                 spd_file = cbfs_boot_map_with_leak( "spd.bin", CBFS_TYPE_RAW,
 219                                                  &spd_file_len);
 220                 if (spd_file && spd_file_len >= 128)
 221                         memcpy(&spd[0], spd_file, 128);
 222                 /* C0S0 is a DIMM slot.  */
 223                 read_spd(&spd[1], 0x51);
 224         }
 225
 226 If several slots are soldered there are 3 ways of doing things:
 227
 228 * If all of them are the same use the same file. Don't forget to copy
 229 it to all array elements.
 230 * Use several files (recommended). Name them e.g. spd1, spd2,...
 231 * Concatenate it into a single file and split into several
 232 array elements on runtime. Not recommended
 233
 234 ### `board_info.txt`
 235
 236 `board_info.txt` is a simple text file used to generate wiki page
 237 listing supported boards. Some of the info can't be detected automatically.
 238
 239 As this is used only to present information to users then when it matches
 240 your board and definitions it is correct.
 241
 242 * Which package is used for ROM and whether it's socketed, as well
 243 as release year. For ROM package refer to <http://flashrom.org/Technology>
 244 and compare it with ROM you found at the beginning of the port. Set
 245 `ROM package`, `ROM socketed` and other variables mentioned in FIXME.
 246 * Release year, just go to web and find that information.
 247 * Category. It's difficult to make difference between desktop and similar
 248 categories from inside the computer. Valid categories are:
 249         * `desktop`. Desktops and workstations.
 250         * `server`. Servers
 251         * `laptop`. Laptops.
 252         * `half`. Embedded / PC/104 / Half-size boards.
 253         * `mini`. Mini-ITX / Micro-ITX / Nano-ITX
 254         * `settop`. Set-top-boxes / Thin clients.
 255         * `eval`. Devel/Eval Boards
 256         * `sbc`. Single-Board computer.
 257         * `emulation`. Virtual machines and emulators. May require especial care
 258         as they often behave differently from real counterparts.
 259         * `misc`. Anything not fitting the categories above. You probably shouldn't use
 260         this.
 261
 262 ### `USBDEBUG_HCD_INDEX`
 263
 264 Which controller the most easily accessible USB debug port is. On intel
 265 1 is for `00:1d.0` and 2 is `00:1a.0` (yes, it's reversed). See
 266 <https://www.coreboot.org/EHCI_Debug_Port> for more info.
 267
 268 If you're able to use EHCI debug port without setting HCD index manually
 269 in config this is correct.
 270
 271 ### `BOARD_ROMSIZE_KB_2048`
 272
 273 Default rom size should be detected automatically but sometimes isn't.
 274 If yours weren't detected put correct rom size here to serve as sane
 275 default when configuring coreboot.
 276
 277 If default ROM size when slecting the board is right one than this value
 278 is correct.
 279
 280 ### `DRAM_RESET_GATE_GPIO`
 281
 282 When machine is going to S3 in order not to reset the RAM modules, the
 283 reset signal must be filtered out from reachin RAM. This is done by
 284 powering down a special gate. Most manufacturers put this gate on
 285 GPIO 60 but Lenovo is knowon to put it on GPIO 10. If you're able to
 286 go to S3 and back than this value is correct.
 287
 288 ## GNVS
 289
 290 `acpi_create_gnvs` sets values in GNVS which in turn is used by ACPI for
 291 various power-related functions. Normally there is no need to modify it
 292 but it makes sense to proofread it.
 293
 294 ## `gfx.ndid` and `gfx.did`
 295
 296 Those describe which video outputs are declared in ACPI tables.
 297 Normally there is no need to adjust but if you miss some nonstandard output
 298 you can declare it there. Bit 31 is set to indicate presence of the output.
 299 Byte 1 is the type and byte 0 is used for disambigution so that ID composed of
 300 byte 1 and 0 is unique. Types are
 301
 302 * 1 = VGA
 303 * 2 = TV
 304 * 3 = DVI
 305 * 4 = LCD
 306
 307 ## `c*_acpower` and `c*_battery`
 308
 309 Which mwait states to match to which ACPI levels. Normally no need to modify unless
 310 your device has very special power saving requirements.
 311
 312 ## `install_intel_vga_int15_handler`
 313
 314 This is used to configure int15 hook used by vgabios. Parameters 2 and 3 usually
 315 shouldn't be modified as vgabios is quite ok to figure panel fit and active
 316 output by itself. Last number is the numerical ID of display type. If you
 317 don't get any output with vgabios you should try different values for 4th
 318 parameter. If it doesn't help try different values for first parameter as well
 319
 320 ## CMOS options
 321
 322 Due to horrible state of CMOS support in coreboot tree, autoport doesn't support it and
 323 this probably won't change until format in the tree improves. If you really care about
 324 CMOS options:
 325
 326 * Create files `cmos.layout` and `cmos.default`
 327 * Enable `HAVE_OPTION_TABLE` and `HAVE_CMOS_DEFAULT` in `Kconfig`
 328
 329 ## EC (lenovo)
 330
 331 You need to set `has_keyboard_backlight` (backlit keyboard like X230),
 332 `has_power_management_beeps` (optional beeps when e.g. plugging the cord
 333 in) and `has_uwb` (third MiniPCIe slot) in accordance to functions available
 334 on your machine
 335
 336 In rare cases autoport is unable to detect GPE. You can detect it from
 337 dmesg or ACPI tables. Look for line in dmesg like
 338
 339         ACPI: EC: GPE = 0x11, I/O: command/status = 0x66, data = 0x62
 340
 341 This means that GPE is `0x11` in ACPI notation. This is the correct
 342 value for `THINKPAD_EC_GPE`. To get the correct value for `GPE_EC_SCI`
 343 you need to substract `0x10`, so value for it is `1`.
 344
 345 The pin used to wake the machine from EC is guessed. If your machine doesn't
 346 wake on lid open and pressing of Fn, change `GPE_EC_WAKE`.
 347
 348 Keep `GPE_EC_WAKE` and `GPE_EC_SCI` in sync with `gpi*_routing`.
 349 `gpi*_routing` matching `GPE_EC_WAKE` or `GPE_EC_SCI` is set to `2`
 350 and all others are absent.
 351
 352 If your dock has LPC wires or needs some special treatement you
 353 need to fill `h8_mainboard_init_dock` and add support code to
 354 DSDT. See the code for `x60`, `x200` or `x201`
 355
 356 ## EC (generic laptop)
 357
 358 Almost any laptop has an embedded controller. In nutshell it's a small
 359 low-powered computer specialised on managing power for laptop. Exact
 360 functionality differs between macines but of interest to us is mainly:
 361
 362 * Control of power and rfkill to different component
 363 * Keyboard (PS/2) interface implementation
 364 * Battery, AC, LID and thermal information exporting
 365 * Hotkey support
 366
 367 autoport automatically attempts to restore the dumped config but it
 368 may or may not work and may even lead to a hang or powerdown. If your
 369 machine stops at `Replaying EC dump ...` try commenting EC replay out
 370
 371 autoport tries to detect if machine has PS/2 interface and if so calls
 372 `pc_keyboard_init` and exports relevant ACPI objects. If detection fails
 373 you may have to add them yourself
 374
 375 ACPI methods `_PTS` (prepare to sleep) and `_WAK` (wake) are executed
 376 when transitioning to sleep or wake state respectively. You may need to
 377 add power-related calls there to either shutdown some components or to
 378 add a workaround to stop giving OS thermal info until next refresh.
 379
 380 For exporting the battery/AC/LID/hotkey/thermal info you need to write
 381 `acpi/ec.asl`. For an easy example look into `apple/macbook21` or
 382 `packardbell/ms2290`. For information about needed methods consult
 383 relevant ACPI specs. Tracing which EC events can be done using
 384 [dynamic debug](https://wiki.ubuntu.com/Kernel/Reference/ACPITricksAndTips)
 385
 386 EC GPE needs to be routed to SCI in order for OS in order to receive
 387 EC events like "hotkey X pressed" or "AC plugged". autoport attempts
 388 to detect GPE but in rare cases may fail. You can detect it from
 389 dmesg or ACPI tables. Look for line in dmesg like
 390
 391         ACPI: EC: GPE = 0x11, I/O: command/status = 0x66, data = 0x62
 392
 393 This means that GPE is `0x11` in ACPI notation. This is the correct
 394 value for `_GPE`.
 395
 396 Keep GPE in sync with `gpi*_routing`.
 397 `gpi*_routing` matching `GPE - 0x10` is set to `2`
 398 and all others are absent. If EC has separate wake pin
 399 then this GPE needs to be routed as well