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.

272 lines
13 KiB

4 years ago
4 years ago
4 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/skulls/releases)
  5. * __coreboot__: We take coreboot's master branch at the time we build a release image.
  6. * __microcode update__: revision `0x21` from 2019-02-13
  7. * __SeaBIOS__: version [1.14.0](https://seabios.org/Releases) from 2020-08-10
  8. ### release images to choose from
  9. We release multiple different, but _very similar_ images you can choose from.
  10. They all should work on all versions of the X230. These are the
  11. differences; (xxxxxxxxxx stands for random characters in the filename):
  12. * `x230_coreboot_seabios_xxxxxxxxxx_top.rom` includes the _proprietary_
  13. [VGA BIOS](https://en.wikipedia.org/wiki/Video_BIOS) from [Intel](https://www.intel.com/content/www/us/en/intelligent-systems/intel-embedded-graphics-drivers/faq-bios-firmware.html)
  14. which is non-free software. It is executed in "secure" mode.
  15. * `x230_coreboot_seabios_free_xxxxxxxxxx_top.rom` includes the
  16. [VGA BIOS](https://en.wikipedia.org/wiki/Video_BIOS)
  17. [SeaVGABIOS](https://www.seabios.org/SeaVGABIOS) which is free software.
  18. While technically more interesting, visually this is currently not as
  19. beautiful:
  20. * The [bootspash image is not shown](https://github.com/merge/skulls/issues/59).
  21. * Early boot console messages (after your HDD's bootloader has started a kernel) might be [missing](https://github.com/merge/skulls/issues/46).
  22. ## table of contents
  23. * [TL;DR](#tldr)
  24. * [First-time installation](#first-time-installation)
  25. * [Updating](#updating)
  26. * [Moving to Heads](#moving-to-heads)
  27. * [Why does this work](#why-does-this-work)
  28. * [How to rebuild](#how-to-reproduce-the-release-images)
  29. ## TL;DR
  30. 1. run `sudo ./x230_skulls.sh` on your current X230 Linux system
  31. 2. Power down, remove the battery. Remove the keyboard and palmrest. Connect
  32. a hardware flasher to an external PC (or a Raspberry Pi with a SPI 8-pin chip clip
  33. can directly be used), and run
  34. `sudo ./external_install_bottom.sh` on the lower chip
  35. and `sudo ./external_install_top.sh` on the top chip of the two.
  36. 3. For updating later, run `./x230_skulls.sh`. No need to disassemble.
  37. And always use the latest [released](https://github.com/merge/skulls/releases)
  38. package. This will be tested. The git master
  39. branch is _not_ meant to be stable. Use it for testing only.
  40. ## First-time installation
  41. #### before you begin
  42. Run Linux on your X230, install `dmidecode` and run
  43. `sudo ./x230_skulls.sh`. It simply prints system information and
  44. helps you to be up to date.
  45. Make sure you have the latest skulls-x230 package release by running
  46. `./x230_skulls.sh -U`.
  47. #### original BIOS update / EC firmware (optional)
  48. If the script, `sudo ./x230_skulls.sh` says "The installed original BIOS is very
  49. old.", it means that you have a BIOS version that may include an EC version
  50. older than 1.14.
  51. If that's the case, consider doing one original Lenovo upgrade process. This is not
  52. supported anymore, once you're running coreboot (You'd have to manually
  53. flash back your backup images first, see later chapters).
  54. This updates the BIOS _and_ Embedded Controller (EC) firmware. The EC
  55. is not updated anymore, when running coreboot. Since official BIOS release 2.77 and
  56. its EC version 1.15 Lenovo includes a digital signature check, which prevents
  57. further firmware patching.
  58. You have 2 options:
  59. * use [the latest original CD](https://pcsupport.lenovo.com/us/en/products/laptops-and-netbooks/thinkpad-x-series-laptops/thinkpad-x230/downloads/ds029187) and burn it, or
  60. * use the same, only with a patched EC firmware that allows using any aftermarket-battery:
  61. (this is only possible up to EC Firmware 1.14)
  62. By default, only original Lenovo batteries are allowed.
  63. Thanks to [this](http://zmatt.net/unlocking-my-lenovo-laptop-part-3/)
  64. [project](https://github.com/eigenmatt/mec-tools) we can use Lenovo's bootable
  65. upgrade image, change it and create a bootable _USB_ image (even with EC updates
  66. that allows one to use 3rd party aftermarket batteries). For this, follow instructions
  67. at [github.com/hamishcoleman/thinkpad-ec](https://github.com/hamishcoleman/thinkpad-ec).
  68. #### preparation: required hardware
  69. * An 8 Pin SOIC Clip, for example from
  70. [Pomona electronics](https://www.pomonaelectronics.com/products/test-clips/soic-clip-8-pin)
  71. (for availability, check
  72. [aliexpress](https://de.aliexpress.com/item/POMONA-SOIC-CLIP-5250-8pin-eeprom-for-tacho-8pin-cable-for-pomana-soic-8pin/32814247676.html) or
  73. [elsewhere](https://geizhals.eu/?fs=pomona+test+clip+5250))
  74. or alternatively hooks like
  75. [E-Z-Hook XKM](https://e-z-hook.com/test-hooks/micro-hook/xkm/)
  76. * 6 [female](https://electronics.stackexchange.com/questions/37783/how-can-i-create-a-female-jumper-wire-connector)
  77. [jumper wires](https://en.wikipedia.org/wiki/Jump_wire) like
  78. [these](https://geizhals.eu/jumper-cable-female-female-20cm-a1471094.html)
  79. to connect the clip to a hardware flasher (if not included with the clip)
  80. * a hardware flasher
  81. [supported by flashrom](https://www.flashrom.org/Flashrom/0.9.9/Supported_Hardware#USB_Devices), see below for the examples we support
  82. #### open up the X230
  83. Remove the 7 screws of your X230 to remove the keyboard (by pushing it towards the
  84. screen before lifting) and the palmrest. You'll find the chips using the photo
  85. below. This is how the SPI connection looks like on both of the X230's chips:
  86. Screen (furthest from you)
  87. ![ ______
  88. MOSI 5 --| |-- 4 GND
  89. CLK 6 --| |-- 3 N/C
  90. N/C 7 --| |-- 2 MISO
  91. VCC 8 --|______|-- 1 CS](soic8.png)
  92. Edge (closest to you)
  93. ... choose __one of the following__ supported flashing hardware examples:
  94. #### Hardware Example: Raspberry Pi 3
  95. A Raspberry Pi can directly be a flasher through it's I/O pins, see below.
  96. Use a test clip or hooks, see [required hardware](#preparation-required-hardware).
  97. On the RPi we run [Raspbian](https://www.raspberrypi.org/downloads/raspbian/)
  98. and have the following setup:
  99. * Connect to the console: Either
  100. * connect a screen and a keyboard, or
  101. * Use the [Serial connection](https://elinux.org/RPi_Serial_Connection) using a
  102. USB-to-serial cable (like [Adafruit 954](http://www.adafruit.com/products/954),
  103. [FTDI TTL-232R-RPI](http://www.ftdichip.com/Products/Cables/RPi.htm) or
  104. [others](https://geizhals.eu/usb-to-ttl-serial-adapter-cable-a1461312.html)) and
  105. picocom (`picocom -b 115200 /dev/ttyUSB0`) or minicom
  106. * in the SD Cards's `/boot/config.txt` file `enable_uart=1` and `dtparam=spi=on`
  107. * [For flashrom](https://www.flashrom.org/RaspberryPi) we put `spi_bcm2835`
  108. and `spidev` in /etc/modules
  109. * [Connect to a wifi](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md)
  110. or ethernet to `sudo apt-get install flashrom`
  111. * connect the Clip to the Raspberry Pi 3 (there are
  112. [prettier images](https://github.com/splitbrain/rpibplusleaf) too):
  113. Edge of pi (furthest from you)
  114. (UART)
  115. L GND TX RX CS
  116. E | | | |
  117. F +---------------------------------------------------------------------------------+
  118. T | x x x x x x x x x x x x x x x x x x x x |
  119. | x x x x x x x x x x x x x x x x x x x x |
  120. E +----------------------------------^---^---^---^-------------------------------^--+
  121. D | | | | |
  122. G 3.3V MOSIMISO| GND
  123. E (VCC) CLK
  124. Body of Pi (closest to you)
  125. ![Raspberry Pi at work](rpi_clip.jpg)
  126. Now copy the Skulls release tarball over to the Rasperry Pi and
  127. [continue](#unpack-the-skulls-release-archive) on the Pi.
  128. #### Hardware Example: CH341A based
  129. The CH341A from [Winchiphead](http://www.wch.cn/), a USB interface chip,
  130. is used by some cheap memory programmers.
  131. The one we describe can be bought at
  132. [aliexpress](http://www.aliexpress.com/item/Free-Shipping-CH341A-24-25-Series-EEPROM-Flash-BIOS-DVD-USB-Programmer-DVD-programmer-router-Nine/32583059603.html),
  133. but it's available [elsewhere](https://geizhals.eu/?fs=ch341a) too.
  134. This means you need a different computer running a Linux based system here.
  135. Also, we don't use the included 3,3V power output (provides too little power),
  136. but a separate power supply. If you don't have any, consider getting a AMS1117
  137. based supply for a second USB port (like [this](https://de.aliexpress.com/item/1PCS-AMS1117-3-3V-Mini-USB-5V-3-3V-DC-Perfect-Power-Supply-Module/32785334595.html) or [this](https://www.ebay.com/sch/i.html?_nkw=ams1117+usb)).
  138. * Leave the P/S Jumper connected (programmer mode, 1a86:5512 USB device)
  139. * Connect 3,3V from your external supply to the Pomona clip's (or hook) VCC
  140. * Connect GND from your external supply to GND on your CH341A programmer
  141. * Connect your clip or hooks to the rest of the programmer's SPI pins
  142. * Connect the programmer (and power supply, if USB) to your PC's USB port
  143. ![ch341a programmer with extra USB power supply](ch341a.jpg)
  144. #### unpack the Skulls release archive
  145. tar -xf skulls-x230-<version>.tar.xz
  146. cd skulls-x230-<version>
  147. #### ifd unlock and me_cleaner: the 8MB chip
  148. Flashing the bottom chip (closer to you) is optional. It has the same pinout
  149. than the upper chip. This allows you to enable/disable in-system flashing
  150. (without disassembling the Thinkpad) and/or to neuter the
  151. [Intel Management Engine](https://en.wikipedia.org/wiki/Intel_Management_Engine)
  152. for [security reasons](https://en.wikipedia.org/wiki/Intel_Management_Engine#Security_vulnerabilities).
  153. sudo ./external_install_bottom.sh -m -k <backup-file-to-create>
  154. That's it. Keep the backup safe. Here are the options (just so you know):
  155. * The `-m` option applies `me_cleaner -S -d` before flashing back, see
  156. [me_cleaner](https://github.com/corna/me_cleaner).
  157. * The `-l` option will (re-)lock your flash ROM, in case you want to force
  158. yourself (and others) to hardware-flashing, see [updating](#updating).
  159. #### Your BIOS choice: the 4MB chip
  160. Now it's time to make your choice! Choose one of the images included in our
  161. release and select it during running:
  162. sudo ./external_install_top.sh -k <backup-file-to-create>
  163. This selects and flashes it and that's it.
  164. Keep the backup safe, assemble and
  165. turn on the X230. coreboot will do hardware init and start SeaBIOS.
  166. ## Updating
  167. If you have locked your flash (i.e. `./external_install_bottom -l`) you can
  168. flash externally using `external_install_top.sh` just like the
  169. first time, see above. Only the "upper" 4MB chip has to be written.
  170. It is recommended to do the the update directly on your X230 using Linux
  171. though. This is considered more safe for your hardware and is very convenient -
  172. just install the "flashrom" program and run `./x230_skulls.sh`, see below.
  173. 1. boot Linux with the `iomem=relaxed` boot parameter (for example in /etc/default/grub `GRUB_CMDLINE_LINUX_DEFAULT`)
  174. 2. [download](https://github.com/merge/skulls/releases) the latest Skulls release tarball and unpack it or check for updates by running `./x230_skulls.sh -U`.
  175. 3. run `sudo ./x230_skulls.sh` and choose the image to flash.
  176. Hint: In case your Linux distribution's GRUB bootloader doesn't use the full
  177. screen, put the line `GRUB_GFXMODE=1366x768x32` in your `/etc/default/grub` file
  178. (and run `update_grub`).
  179. ## Moving to Heads
  180. [Heads](http://osresearch.net/) is an alternative BIOS system with advanced
  181. security features. It's more complicated to use though. When having Skulls
  182. installed, installing Heads is as easy as updating Skulls. You can directly
  183. start using it:
  184. * [build Heads](https://github.com/osresearch/heads)
  185. * boot Linux with the `iomem=relaxed` boot parameter
  186. * copy Heads' 12M image file `build/x230/coreboot.rom` to Skulls' x230 directory
  187. * run `sudo ./x230_heads.sh`
  188. That's it. Heads is a completely different project. Please read the
  189. [documentation](http://osresearch.net/) for how to use it and report bugs
  190. [over there](https://github.com/osresearch/heads/issues)
  191. Switching back to Skulls is the same as [updating](#updating). Just run
  192. `./x230_skulls.sh`.
  193. ## Why does this work?
  194. On the X230, there are 2 physical "BIOS" chips. The "upper" 4MB
  195. one holds the actual bios we can generate using coreboot, and the "lower" 8MB
  196. one holds the rest that you can [modify yourself once](#first-time-installation),
  197. if you like, but strictly speaking, you
  198. [don't need to touch it at all](https://www.coreboot.org/Board:lenovo/x230#Building_Firmware).
  199. What's this "rest"?
  200. Mainly a tiny binary used by the Ethernet card and the Intel Management Engine.
  201. Read the [coreboot documentation](https://doc.coreboot.org/mainboard/lenovo/xx30_series.html)
  202. for more details.
  203. ## how to reproduce the release images
  204. * `git clone https://github.com/merge/skulls`
  205. * `cd skulls/x230`
  206. * `git checkout 0.1.5` for the release you want to build. In this example 0.1.5.
  207. * `./build.sh` and choose the configuration you want to build
  208. ### replace the splashscreen image
  209. In order to create your own splashscreen image, before building,
  210. overwrite the `splashscreen.jpg` with your own JPEG, using
  211. * "Progressive" turned off, and
  212. * "4:2:0 (chroma quartered)" Subsampling