You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

238 lines
11 KiB

6 years ago
  1. # Skulls - [Thinkpad X230](https://pcsupport.lenovo.com/en/products/laptops-and-netbooks/thinkpad-x-series-laptops/thinkpad-x230).
  2. ![seabios_bootmenu](front.jpg)
  3. ## Latest release
  4. * Get it from our [release page](https://github.com/merge/coreboot-x230/releases)
  5. * __coreboot__: We take coreboot's master branch at the time we build a release image.
  6. * __microcode update__: revision `1f` from 2018-02-07 see package [20180312](https://downloadcenter.intel.com/download/27591) under [Intel's license](LICENSE.microcode)
  7. * __SeaBIOS__: version [1.11.1](https://seabios.org/Releases) from 2018-03-19
  8. * The only proprietary binary, the VGA BIOS is executed in "secure" mode ([PCI_OPTION_ROM_RUN_YABEL](https://www.coreboot.org/Coreboot_Options))
  9. ## table of contents
  10. * [TL;DR](#tldr)
  11. * [First-time installation](#firsttime-installation)
  12. * [Updating](#updating)
  13. * [Moving to Heads](#moving-to-heads)
  14. * [Why does this work](#why-does-this-work)
  15. ## TL;DR
  16. 1. run `sudo ./x230_before_first_install.sh` on your current X230 Linux system
  17. 2. Power down, remove the battery. Remove the keyboard and palmrest. Connect
  18. a hardware flasher to an external PC (or a Raspberry Pi with a SPI 8-pin chip clip
  19. can directly be used), and run
  20. `sudo ./external_install_bottom.sh` on the lower chip
  21. and `sudo ./external_install_top.sh` on the top chip of the two.
  22. 3. For updating later, run `./x230_skulls.sh`. No need to disassemble.
  23. And always use the latest [released](https://github.com/merge/coreboot-x230/releases)
  24. package. This will be tested. The git master
  25. branch is _not_ meant to be stable. Use it for testing only.
  26. ## First-time installation
  27. #### before you begin
  28. Before starting, run Linux on your X230, install `dmidecode` and run
  29. `sudo ./x230_before_first_install.sh`. It simply prints system information and helps
  30. you find out your RAM voltage. Make sure you have RAM that uses 1,5V, not 1,35V.
  31. #### original BIOS update / EC firmware (optional)
  32. Before flashing coreboot, consider doing one original Lenovo upgrade process
  33. in case you're not running the latest version. This is not supported anymore,
  34. once you're running coreboot (You'd have to manually flash back your backup
  35. images first, see later chapters).
  36. Also, this updates the BIOS _and_ Embedded Controller (EC) firmware. The EC
  37. is not updated anymore, when running coreboot. The latest EC version is 1.14
  38. and that's unlikely to change.
  39. In case you're not running the latest BIOS version, either
  40. * use [the latest original CD](https://support.lenovo.com/at/en/downloads/ds029188) and burn it, or
  41. * use the same, only with a patched EC firmware that allows using any aftermarket-battery:
  42. By default, only original Lenovo batteries are allowed.
  43. Thanks to [this](http://zmatt.net/unlocking-my-lenovo-laptop-part-3/)
  44. [project](https://github.com/eigenmatt/mec-tools) we can use Lenovo's bootable
  45. upgrade image, change it and create a bootable _USB_ image, with an EC update
  46. that allows us to use any 3rd party aftermarket battery:
  47. sudo apt-get install build-essential git mtools libssl-dev
  48. git clone https://github.com/hamishcoleman/thinkpad-ec && cd thinkpad-ec
  49. make patch_disable_keyboard clean
  50. make patch_enable_battery clean
  51. make patched.x230.img
  52. That's it. You can create a bootable USB stick: `sudo dd if=patched.x230.img of=/dev/sdx`
  53. and boot from it. Alternatively, burn `patched.x230.iso` to a CD. And make sure
  54. you have "legacy" boot set, not "UEFI" boot.
  55. #### preparation: required hardware
  56. * An 8 Pin SOIC Clip, for example from
  57. [Pomona electronics](https://www.pomonaelectronics.com/products/test-clips/soic-clip-8-pin)
  58. (for availability, check
  59. [aliexpress](https://de.aliexpress.com/item/POMONA-SOIC-CLIP-5250-8pin-eeprom-for-tacho-8pin-cable-for-pomana-soic-8pin/32814247676.html) or
  60. [elsewhere](https://geizhals.eu/?fs=pomona+test+clip+5250))
  61. or alternatively hooks like
  62. [E-Z-Hook](http://catalog.e-z-hook.com/viewitems/test-hooks/e-z-micro-hooks-single-hook-style)
  63. * 6 [female](https://electronics.stackexchange.com/questions/37783/how-can-i-create-a-female-jumper-wire-connector)
  64. [jumper wires](https://en.wikipedia.org/wiki/Jump_wire) like
  65. [these](https://geizhals.eu/jumper-cable-female-female-20cm-a1471094.html)
  66. to connect the clip to a hardware flasher (if not included with the clip)
  67. * a hardware flasher
  68. [supported by flashrom](https://www.flashrom.org/Flashrom/0.9.9/Supported_Hardware#USB_Devices), see below for the examples we support
  69. #### open up the X230
  70. Remove the 7 screws of your X230 to remove the keyboard (by pushing it towards the
  71. screen before lifting) and the palmrest. You'll find the chips using the photo
  72. below. This is how the SPI connection looks on both of the X230's chips:
  73. Screen (furthest from you)
  74. __
  75. MOSI 5 --| |-- 4 GND
  76. CLK 6 --| |-- 3 N/C
  77. N/C 7 --| |-- 2 MISO
  78. VCC 8 --|__|-- 1 CS
  79. Edge (closest to you)
  80. ... choose __one of the following__ supported flashing hardware examples:
  81. #### Hardware Example: Raspberry Pi 3
  82. A Raspberry Pi can directly be a flasher through it's I/O pins, see below.
  83. Use a test clip or hooks, see [required hardware](#preparation-required-hardware).
  84. On the RPi we run [Raspbian](https://www.raspberrypi.org/downloads/raspbian/)
  85. and have the following setup:
  86. * Connect to the console: Either
  87. * connect a screen and a keyboard, or
  88. * Use the [Serial connection](https://elinux.org/RPi_Serial_Connection) using a
  89. USB-to-serial cable (like [Adafruit 954](http://www.adafruit.com/products/954),
  90. [FTDI TTL-232R-RPI](http://www.ftdichip.com/Products/Cables/RPi.htm) or
  91. [others](https://geizhals.eu/usb-to-ttl-serial-adapter-cable-a1461312.html)) and
  92. picocom (`picocom -b 115200 /dev/ttyUSB0`) or minicom
  93. * in the SD Cards's `/boot/config.txt` file `enable_uart=1` and `dtparam=spi=on`
  94. * [For flashrom](https://www.flashrom.org/RaspberryPi) we put `spi_bcm2835`
  95. and `spidev` in /etc/modules
  96. * [Connect to a wifi](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md)
  97. or ethernet to `sudo apt-get install flashrom`
  98. * connect the Clip to the Raspberry Pi 3 (there are
  99. [prettier images](https://github.com/splitbrain/rpibplusleaf) too):
  100. Edge of pi (furthest from you)
  101. (UART)
  102. L GND TX RX CS
  103. E | | | |
  104. F +---------------------------------------------------------------------------------+
  105. T | x x x x x x x x x x x x x x x x x x x x |
  106. | x x x x x x x x x x x x x x x x x x x x |
  107. E +----------------------------------^---^---^---^-------------------------------^--+
  108. D | | | | |
  109. G 3.3V MOSIMISO| GND
  110. E (VCC) CLK
  111. Body of Pi (closest to you)
  112. ![Raspberry Pi at work](rpi_clip.jpg)
  113. Now copy the Skulls release tarball over to the Rasperry Pi and
  114. [continue](#unpack-the-skulls-release-archive) on the Pi.
  115. #### Hardware Example: CH341A based
  116. The CH341A from [Winchiphead](http://www.wch.cn/), a USB interface chip,
  117. is used by some cheap memory programmers.
  118. The one we describe can be bought at
  119. [aliexpress](http://www.aliexpress.com/item/Free-Shipping-CH341A-24-25-Series-EEPROM-Flash-BIOS-DVD-USB-Programmer-DVD-programmer-router-Nine/32583059603.html),
  120. but it's available [elsewhere](https://geizhals.eu/?fs=ch341a) too.
  121. * Connect the programmer to your PC's USB port
  122. * Connect your clip or hooks to the programmer's SPI pins
  123. TODO description and foto
  124. #### unpack the Skulls release archive
  125. mkdir skulls
  126. tar -xf skulls-x230-<version>.tar.xz -C skulls
  127. cd skulls
  128. #### ifd unlock and me_cleaner: the 8MB chip
  129. The [Intel Management Engine](https://en.wikipedia.org/wiki/Intel_Management_Engine)
  130. resides on the 8MB chip (at the bottom, closer to you).
  131. We don't need to touch it for coreboot-upgrades in the future, but to
  132. enable internal flashing, we need to unlock it once, and remove the Management
  133. Engine for
  134. [security reasons](https://en.wikipedia.org/wiki/Intel_Management_Engine#Security_vulnerabilities):
  135. sudo ./external_install_bottom.sh -m -k <backup.bin>
  136. That's it. Keep the backup safe.
  137. Background (just so you know):
  138. * The `-m` option above also runs `me_cleaner -S` before flashing back, see [me_cleaner](https://github.com/corna/me_cleaner).
  139. * The `-l` option will (re-)lock your flash ROM, in case you want to force
  140. yourself (and others) to hardware-flashing.
  141. * Connecting an ethernet cable as a power-source for SPI (instead of the VCC pin)
  142. is not necessary (some other flashing how-to guides mention this).
  143. Setting a fixed (and low) SPI speed for flashrom offeres the same stability.
  144. Our scripts do this for you.
  145. #### BIOS: the 4MB chip
  146. sudo ./external_install_top.sh -i <release-image-file>.rom -k <backup>
  147. That's it. Keep the backup safe, assemble and turn on the X230. coreboot will
  148. do hardware init and start SeaBIOS.
  149. ## Updating
  150. Only the "upper" 4MB chip has to be written.
  151. You can again flash externally, using `external_install_top.sh` just like the
  152. first time, see above.
  153. Instead you can run the update directly on your X230
  154. using Linux. That's of course very convenient - just install flashrom from your
  155. Linux distribution - but according to the
  156. [flashrom manpage](https://manpages.debian.org/stretch/flashrom/flashrom.8.en.html)
  157. this is very dangerous:
  158. 1. boot Linux with the `iomem=relaxed` boot parameter (for example in /etc/default/grub `GRUB_CMDLINE_LINUX_DEFAULT`)
  159. 2. [download](https://github.com/merge/skulls/releases) the latest Skulls release tarball and unpack it
  160. 3. run `sudo ./x230_skulls.sh` for generating all necessary files and instructions
  161. ## Moving to Heads
  162. [Heads](http://osresearch.net/) is an alternative BIOS system with advanced
  163. security features. It's more complicated to use though. When having Skulls
  164. installed, installing Heads is as easy as updating Skulls. You can directly
  165. start using it:
  166. * [build Heads](https://github.com/osresearch/heads)
  167. * boot Linux with the `iomem=relaxed` boot parameter
  168. * copy Heads' 12M image file `build/x230/coreboot.rom` to Skulls' x230 diretory
  169. * run `sudo ./x230_heads.sh`
  170. That's it. Heads is a completely different project. Please read the
  171. [documentation](http://osresearch.net/) for how to use it and report bugs
  172. [over there](https://github.com/osresearch/heads/issues)
  173. Switching back to Skulls is the same as [updating](#updating). Just run
  174. `./x230_skulls.sh`.
  175. ## Why does this work?
  176. On the X230, there are 2 physical "BIOS" chips. The "upper" 4MB
  177. one holds the actual bios we can generate using coreboot, and the "lower" 8MB
  178. one holds the rest that you can [modify yourself once](#flashing-for-the-first-time),
  179. if you like, but strictly speaking, you
  180. [don't need to touch it at all](https://www.coreboot.org/Board:lenovo/x230#Building_Firmware).
  181. What's this "rest"?
  182. Mainly a tiny binary used by the Ethernet card and the Intel Management Engine.