readme.md
1 # Porting coreboot using autoport 2 3 ## Supported platforms 4 5 ### Chipset 6 For any Sandy Bridge, Ivy Bridge, or Haswell platform the generated result 7 should be bootable, possibly with minor fixes. 8 9 ### EC / SuperIO 10 EC support is likely to work on Intel-based thinkpads. Other laptops are 11 likely to miss EC support. SuperIO support on desktops is more likely to 12 work out of the box than any EC. 13 14 ## How to use autoport 15 16 Enable as many devices as possible in the firmware setup of your system. 17 This is useful to detect as many devices as possible and make the port 18 more complete, as disabled devices cannot be detected. 19 20 Boot into target machine under any Linux-based distribution and install 21 the following tools on it: 22 * `gcc` 23 * `golang` 24 * `lspci` 25 * `dmidecode` 26 * `acpidump` (part of `acpica` on some distros) 27 28 Clone the coreboot tree and `cd` into it. For more detailed steps, refer 29 to Rookie Guide, Lesson 1. Afterwards, run these commands: 30 31 cd util/ectool 32 make 33 cd ../inteltool 34 make 35 cd ../superiotool 36 make 37 cd ../autoport 38 go build 39 sudo ./autoport --input_log=logs --make_logs --coreboot_dir=../.. 40 41 Note: in case you have problems getting gcc and golang on the target 42 machine, you can compile the utilities on another computer and copy 43 the binaries to the target machine. You will still need the other 44 listed programs on the target machine, but you may place them in the 45 same directory as autoport. 46 47 Check for unknown detected PCI devices, e.g.: 48 49 Unknown PCI device 8086:0085, assuming removable 50 51 If autoport says `assuming removable`, you are fine. If it doesn't, 52 you may want to add the relevant PCI IDs to autoport. Run `lspci -nn` 53 and check which device this is using the PCI ID. Devices which are not 54 part of the chipset, such as GPUs or network cards, can be considered 55 removable, whereas devices inside the CPU or the PCH such as integrated 56 GPUs and bus controllers (SATA, USB, LPC, SMBus...) are non-removable. 57 58 Your board has now been added to the tree. However, do not flash it 59 in its current state. It can brick your machine. Instead, keep this 60 new port and the logs from `util/autoport/logs` somewhere safe. The 61 following steps will back up your current firmware, which is always 62 recommended, since coreboot may not boot on the first try. 63 64 Disassemble your computer and find the flash chip(s). Since there could be 65 more than one, this guide will refer to "flash chips" as one or more chips. 66 Refer to <https://flashrom.org/Technology> as a reference. The flash chip is 67 usually in a `SOIC-8` (2x4 pins, 200mil) or `SOIC-16` (2x8 pins) package. As 68 it can be seen on flashrom's wiki, the former package is like any other 8-pin 69 chip on the mainboard, but it is slightly larger. The latter package is much 70 easier to locate. Always make sure it is a flash chip by looking up what its 71 model, printed on it, refers to. 72 73 There may be a smaller flash chip for the EC on some laptops, and other chips 74 such as network cards may use similar flash chips. These should be left as-is. 75 If in doubt, ask! 76 77 Once located, use an external flasher to read the flash chips with `flashrom -r`. 78 Verify with `flashrom -v` several times that reading is consistent. If it is not, 79 troubleshoot your flashing setup. Save the results somewhere safe, preferably on 80 media that cannot be easily overwritten and on several devices. You may need this 81 later. The write process erases the flash chips first, and erased data on a flash 82 chip is lost for a very long time, usually forever! 83 84 Compile coreboot for your ported mainboard with some console enabled. The most 85 common ones are EHCI debug, serial port and SPI flash console as a last resort. 86 If your system is a laptop and has a dedicated video card, you may need to add 87 a video BIOS (VBIOS) to coreboot to be able to see any video output. Desktop 88 video cards, as well as some MXM video cards, have this VBIOS on a flash chip 89 on the card's PCB, so this step is not necessary for them. 90 91 Flash coreboot on the machine. On recent Intel chipsets, the flash space is split 92 in several regions. Only the one known as "BIOS region" should be flashed. If 93 there is only one flash chip present, this is best done by adding the `--ifd` 94 and `-i bios` parameters flashrom has (from v1.0 onwards) to specify what flash 95 descriptor region it should operate on. If the ME (Management Engine) region is 96 not readable, which is the case on most systems, use the `--noverify-all` 97 parameter as well. 98 99 For systems with two flash chips, this is not so easy. It is probably better to 100 ask in coreboot or flashrom communication channels, such as via IRC or on the 101 mailing lists. 102 103 Once flashed, try to boot. Anything is possible. If a log is generated, save it 104 and use it to address any issues. See the next section for useful information. 105 Find all the sections marked with `FIXME` and correct them. 106 107 Send your work to review.coreboot.org. I mean it, your effort is very appreciated. 108 Refer to Rookie Guide, Lesson 2 for instructions on how to submit a patch. 109 110 ## Manual fixes 111 ### SPD 112 In order to initialize the RAM (memory), coreboot needs to know its timings, which vary between 113 modules. Socketed RAM has a small EEPROM chip, which is accessible via SMBus and contains the 114 timing data. This data is usually known as SPD. Unfortunately, the SMBus addresses may not 115 correlate with the RAM slots and cannot always be detected automatically. The address map is 116 usually in the devicetree, `register "spd_addresses"`. For mainboards with memory-down (where 117 the RAM chips are soldered directly to the mainboard), there is no EEPROM to get SPD data from, 118 so function `mb_get_spd_map` in `early_init.c` has to populate the SPD data from a file in CBFS. 119 120 By default, autoport uses the most common map `0x50, 0x51, 0x52, 0x53` on everything except for 121 Lenovo systems, which are known to use `0x50, 0x52, 0x51, 0x53`. To detect the correct memory 122 map, the easiest way is to boot on the vendor firmware with just one module in channel 0, slot 123 0, and check the SMBus address the EEPROM has. Under Linux, you can use these commands to see 124 which devices appear on SMBus: 125 126 $ sudo modprobe i2c-dev 127 $ sudo modprobe i2c-i801 128 $ sudo i2cdetect -l 129 i2c-0 i2c i915 gmbus ssc I2C adapter 130 i2c-1 i2c i915 gmbus vga I2C adapter 131 i2c-2 i2c i915 gmbus panel I2C adapter 132 i2c-3 i2c i915 gmbus dpc I2C adapter 133 i2c-4 i2c i915 gmbus dpb I2C adapter 134 i2c-5 i2c i915 gmbus dpd I2C adapter 135 i2c-6 i2c DPDDC-B I2C adapter 136 i2c-7 i2c DPDDC-C I2C adapter 137 i2c-8 i2c DPDDC-D I2C adapter 138 i2c-9 smbus SMBus I801 adapter at 0400 SMBus adapter 139 140 $ sudo i2cdetect 9 141 WARNING! This program can confuse your I2C bus, cause data loss and worse! 142 I will probe file /dev/i2c-9. 143 I will probe address range 0x03-0x77. 144 Continue? [Y/n] y 145 0 1 2 3 4 5 6 7 8 9 a b c d e f 146 00: -- -- -- -- -- 08 -- -- -- -- -- -- -- 147 10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 148 20: -- -- -- -- 24 -- -- -- -- -- -- -- -- -- -- -- 149 30: 30 31 -- -- -- -- -- -- -- -- -- -- -- -- -- -- 150 40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 151 50: 50 -- -- -- 54 55 56 57 -- -- -- -- 5c 5d 5e 5f 152 60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 153 70: -- -- -- -- -- -- -- -- 154 155 Note: if some devices appear as `UU`, it means a kernel module is loaded for this device, like 156 `at24` or `ee1004`. You can use the `decode-dimms` command to get more information about SPDs. 157 158 Make sure to replace the `9` on the last command with the bus number for SMBus on 159 your system. Here, there is a module at address `0x50`. Since only one module was 160 installed on the first slot of the first channel, we know the first position of 161 the SPD array must be `0x50`. After testing all the slots, your `spd_addresses` 162 should look similar to this: 163 164 register "spd_addresses" = "{0x50, 0, 0x52, 0}" # 2-slot mainboard / laptop 165 register "spd_addresses" = "{0x53, 0x52, 0x51, 0x50}" # 4-slot BTX mainboard 166 167 Note: slot labelling may be missing or unreliable. Use `inteltool` to see which slots have 168 modules in them. 169 170 This procedure is ideal, if your RAM is socketed. If you have soldered RAM, 171 remove any socketed memory modules and check if any EEPROM appears on SMBus. 172 If this is the case, you can proceed as if the RAM was socketed. However, 173 you may have to guess some entries if there multiple EEPROMs appear. 174 175 Most of the time, soldered RAM does not have an EEPROM. Instead, the SPD data is 176 inside the main flash chip where the firmware is. If this is the case, you need 177 to generate the SPD data to use with coreboot. Look at `inteltool.log`. There 178 should be something like this: 179 180 /* SPD matching current mode: */ 181 /* CH0S0 */ 182 00: 92 11 0b 03 04 00 00 09 03 52 01 08 0a 00 80 00 183 10: 6e 78 6e 32 6e 11 18 81 20 08 3c 3c 00 f0 00 00 184 20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 185 30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 65 00 186 40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 187 50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 188 60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 189 70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 6d 17 190 80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 191 90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 192 a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 193 b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 194 c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 195 d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 196 e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 197 f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 198 /* CH1S0 */ 199 00: 92 11 0b 03 04 00 00 09 03 52 01 08 0a 00 80 00 200 10: 6e 78 6e 32 6e 11 18 81 20 08 3c 3c 00 f0 00 00 201 20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 202 30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 65 00 203 40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 204 50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 205 60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 206 70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 6d 17 207 80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 208 90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 209 a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 210 b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 211 c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 212 d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 213 e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 214 f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 215 216 This is not a full-fledged SPD dump, as it only lists the currently-used speed configuration, 217 and lacks info such as a serial number, vendor and model. To create a SPD hex file, one has to 218 trim the offset numbers from the leftmost column: 219 220 $ cat | cut -d ' ' -f 2- > data.spd.hex 221 00: 92 11 0b 03 04 00 00 09 03 52 01 08 0a 00 80 00 222 10: 6e 78 6e 32 6e 11 18 81 20 08 3c 3c 00 f0 00 00 223 20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 224 30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 65 00 225 40: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 226 50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 227 60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 228 70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 6d 17 229 80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 230 90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 231 a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 232 b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 233 c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 234 d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 235 e0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 236 f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 237 EOF (press Ctrl + D) 238 239 Then, move the generated file into your mainboard's directory and hook it up to the build 240 system. It is recommended to check what other mainboards with soldered memory do. The main 241 switch to use SPD files is `select HAVE_SPD_IN_CBFS` in Kconfig. 242 243 Now we need coreboot to use this SPD file. The following example shows a hybrid configuration, 244 in which one module is soldered down and the other one is socketed: 245 246 void mb_get_spd_map(struct spd_info *spdi) 247 { 248 spdi->spd_index = 0; 249 /* C0S0 is soldered RAM, use stored SPD */ 250 spdi->addresses[0] = SPD_MEMORY_DOWN; 251 /* C1S0 is a physical slot, use SPD address on SMBus */ 252 spdi->addresses[2] = 0x52; 253 } 254 255 If several slots are soldered, the system only accounts for a single set of SPD data. So all 256 slots would need to use the same SPD data, if possible. If not possible, the API needs to be 257 adapted accordingly, which is significantly more involved. 258 259 If memory initialization is not working, in particular write training (timB) 260 on DIMM's second rank fails, try enabling rank 1 mirroring, which can't be 261 detected by inteltool. It is described by SPD field "Address Mapping from Edge 262 Connector to DRAM", byte `63` (`0x3f`). Bit 0 describes Rank 1 Mapping, 263 0 = standard, 1 = mirrored; set it to 1. Bits 1-7 are reserved. 264 265 ### `board_info.txt` 266 267 `board_info.txt` is a text file used in the board status page to list all 268 the supported boards and their specifications. Most of the information 269 cannot be detected by autoport. Common entries are: 270 271 * `ROM package`, `ROM protocol` and `ROM socketed`: 272 These refer to the flash chips you found earlier. You can visit 273 <https://flashrom.org/Technology> for more information. 274 275 * `Release year`: Use the power of Internet to find that information. 276 * `Category`: This describes the type of mainboard you have. 277 Valid categories are: 278 * `desktop`. Desktops and workstations. 279 * `server`. Servers. 280 * `laptop`. Laptops, notebooks and netbooks. 281 * `half`. Embedded / PC/104 / Half-size boards. 282 * `mini`. Mini-ITX / Micro-ITX / Nano-ITX 283 * `settop`. Set-top-boxes / Thin clients. 284 * `eval`. Development / Evaluation Boards. 285 * `sbc`. Single-Board computer. 286 * `emulation`: Virtual machines and emulators. May require especial care 287 as they often behave differently from real counterparts. 288 * `misc`. Anything not fitting the categories above. Not recommended. 289 290 * `Flashrom support`: This means whether the internal programmer is usable. 291 If flashing coreboot internally works, this should be set to `y`. Else, 292 feel free to investigate why it is not working. 293 294 ### `USBDEBUG_HCD_INDEX` 295 296 Which controller the most easily accessible USB debug port is. On Intel, 297 1 is for `00:1d.0` and 2 is for `00:1a.0` (yes, it's reversed). Refer to 298 <https://www.coreboot.org/EHCI_Debug_Port> for more info. 299 300 If you are able to use EHCI debug without setting the HCD index manually, 301 this is correct. 302 303 ### `BOARD_ROMSIZE_KB_2048` 304 305 This parameter refers to the total size of the flash chips coreboot will be in. 306 This value must be correct for S3 resume to work properly. This parameter also 307 defines the size of the generated coreboot image, but that is not a major issue 308 since tools like `dd` can be used to cut fragments of a coreboot image to flash 309 on smaller chips. 310 311 This should be detected automatically, but it may not be detected properly in 312 some cases. If it was not detected, put the correct total size here to serve 313 as a sane default when configuring coreboot. 314 315 ### `DRAM_RESET_GATE_GPIO` 316 317 When the computer is suspended to RAM (ACPI S3), the RAM reset signal must not 318 reach the RAM modules. Otherwise, the computer will not resume and any opened 319 programs will be lost. This is done by powering down a MOSFET, which disconnects 320 the reset signal from the RAM modules. Most manufacturers put this gate on GPIO 321 60 but Lenovo is known to put it on GPIO 10. If suspending and resuming works, 322 this value is correct. This can also be determined from the board's schematics. 323 324 ## GNVS 325 326 `mainboard_fill_gnvs` sets values in GNVS, which then ACPI makes use of for 327 various power-related functions. Normally, there is no need to modify it 328 on laptops (desktops have no "lid"!) but it makes sense to proofread it. 329 330 ## `gfx.ndid` and `gfx.did` 331 332 Those describe which video outputs are declared in ACPI tables. 333 Normally, there is no need to have these values, but if you miss some 334 non-standard video output, you can declare it there. Bit 31 is set to 335 indicate the presence of the output. Byte 1 is the type and byte 0 is 336 used for disambigution so that ID composed of byte 1 and 0 is unique. 337 338 Types are: 339 * 1 = VGA 340 * 2 = TV 341 * 3 = DVI 342 * 4 = LCD 343 344 ## `c*_acpower` and `c*_battery` 345 346 Which mwait states to match to which ACPI levels. Normally, there is no 347 need to modify anything unless your device has very special power saving 348 requirements. 349 350 ## `install_intel_vga_int15_handler` 351 352 This is used with the Intel VGA BIOS, which is not the default option. 353 It is more error-prone than open-source graphics initialization, so do 354 not bother with this until your mainboard boots. This is a function 355 which takes four parameters: 356 1. Which type of LCD panel is connected. 357 2. Panel fit. 358 3. Boot display. 359 4. Display type. 360 361 Refer to `src/drivers/intel/gma/int15.h` to see which values can be used. 362 For desktops, there is no LCD panel directly connected to the Intel GPU, 363 so the first parameter should be `GMA_INT15_ACTIVE_LFP_NONE`. On other 364 mainboards, it depends. 365 366 ## CMOS options 367 368 Due to the poor state of CMOS support in coreboot, autoport does not 369 support it and this probably won't change until the format in the tree 370 improves. If you really care about CMOS options: 371 372 * Create files `cmos.layout` and `cmos.default` 373 * Enable `HAVE_OPTION_TABLE` and `HAVE_CMOS_DEFAULT` in `Kconfig` 374 375 ## EC (lenovo) 376 377 You need to set `has_keyboard_backlight` (backlit keyboard like X230), 378 `has_power_management_beeps` (optional beeps when e.g. plugging the cord 379 in) and `has_uwb` (third MiniPCIe slot) in accordance to functions available 380 on your machine 381 382 In rare cases autoport is unable to detect GPE. You can detect it from 383 dmesg or ACPI tables. Look for line in dmesg like 384 385 ACPI: EC: GPE = 0x11, I/O: command/status = 0x66, data = 0x62 386 387 This means that GPE is `0x11` in ACPI notation. This is the correct 388 value for `THINKPAD_EC_GPE`. To get the correct value for `GPE_EC_SCI` 389 you need to substract `0x10`, so value for it is `1`. 390 391 The pin used to wake the machine from EC is guessed. If your machine doesn't 392 wake on lid open and pressing of Fn, change `GPE_EC_WAKE`. 393 394 Keep `GPE_EC_WAKE` and `GPE_EC_SCI` in sync with `gpi*_routing`. 395 `gpi*_routing` matching `GPE_EC_WAKE` or `GPE_EC_SCI` is set to `2` 396 and all others are absent. 397 398 If your dock has LPC wires or needs some special treatement you may 399 need to add codes to initialize the dock and support code to 400 DSDT. See the `init_dock()` for `x60`, `x200` or `x201`. 401 402 ## EC (generic laptop) 403 404 Almost any laptop has an embedded controller. In a nutshell, it's a 405 small, low-powered computer designed to be used on laptops. Exact 406 functionality differs between machines. Its main functions include: 407 408 * Control of power and rfkill to different component 409 * Keyboard (PS/2) interface implementation 410 * Battery, AC, LID and thermal information exporting 411 * Hotkey support 412 413 autoport automatically attempts to restore the dumped config but it 414 may or may not work and may even lead to a hang or powerdown. If your 415 machine stops at `Replaying EC dump ...` try commenting EC replay out 416 417 autoport tries to detect if machine has PS/2 interface and if so calls 418 `pc_keyboard_init` and exports relevant ACPI objects. If detection fails 419 you may have to add them yourself 420 421 ACPI methods `_PTS` (prepare to sleep) and `_WAK` (wake) are executed 422 when transitioning to sleep or wake state respectively. You may need to 423 add power-related calls there to either shutdown some components or to 424 add a workaround to stop giving OS thermal info until next refresh. 425 426 For exporting the battery/AC/LID/hotkey/thermal info you need to write 427 `acpi/ec.asl`. For an easy example look into `apple/macbook21` or 428 `packardbell/ms2290`. For information about needed methods consult 429 relevant ACPI specs. Tracing which EC events can be done using 430 [dynamic debug](https://wiki.ubuntu.com/Kernel/Reference/ACPITricksAndTips) 431 432 EC GPE needs to be routed to SCI in order for OS in order to receive 433 EC events like "hotkey X pressed" or "AC plugged". autoport attempts 434 to detect GPE but in rare cases may fail. You can detect it from 435 dmesg or ACPI tables. Look for line in dmesg like 436 437 ACPI: EC: GPE = 0x11, I/O: command/status = 0x66, data = 0x62 438 439 This means that GPE is `0x11` in ACPI notation. This is the correct 440 value for `_GPE`. 441 442 Keep GPE in sync with `gpi*_routing`. 443 `gpi*_routing` matching `GPE - 0x10` is set to `2` 444 and all others are absent. If EC has separate wake pin 445 then this GPE needs to be routed as well