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.

275 lines
12 KiB

6 years ago
6 years ago
6 years ago
  1. # coreboot-x230
  2. pre-built [coreboot](https://www.coreboot.org/) image and documentation on
  3. how to flash them for the
  4. [Thinkpad X230](https://pcsupport.lenovo.com/en/products/laptops-and-netbooks/thinkpad-x-series-laptops/thinkpad-x230).
  5. SeaBIOS is used, to be compatible with Windows and Linux, and to be easy to use:
  6. simply a boot menu and a few options to tick.
  7. ![seabios_bootmenu](front.jpg)
  8. We want to make it easy to "bootstrap" an X230 to a working, unlocked,
  9. up-to-date coreboot-based BIOS.
  10. ## Latest release (config overview and version info)
  11. * coreboot-x230 0.0.5 - see our [release page](https://github.com/merge/coreboot-x230/releases)
  12. * The only proprietary binary, the VGA BIOS is executed in "secure" mode ([PCI_OPTION_ROM_RUN_YABEL](https://www.coreboot.org/Coreboot_Options))
  13. ### coreboot
  14. * We simply take coreboot's current state in it's master branch at the time we build a release image.
  15. That's the preferred way to use coreboot. The git revision we use is always included in the release.
  16. ### Intel microcode
  17. * revision `1f` from 2018-02-07 (Intel package [20180312](https://downloadcenter.intel.com/download/27591) not yet in coreboot upstream) under [Intel's license](LICENSE.microcode)
  18. ### SeaBIOS
  19. * version [1.11.1](https://seabios.org/Releases) from 2018-03-19 (part of coreboot upstream)
  20. ## table of contents
  21. * [TL;DR](#tl-dr)
  22. * [Flashing for the first time](#flashing-for-the-first-time)
  23. * [How to update](#how-to-update)
  24. * [When do we do a release?](#when-do-we-do-a-release)
  25. * [How we build](#how-we-build)
  26. * [Why does this work](#why-does-this-work)
  27. * [Alternatives](#alternatives)
  28. ## TL;DR
  29. For first-time flashing, remove the keyboard and palmrest, and (using a
  30. Raspberry Pi with a SPI 8-pin chip clip connected), run
  31. `flashrom_rpi_bottom_unlock.sh` on the lower chip
  32. and `flashrom_rpi_top_write.sh` on the top chip of the two.
  33. For updating later, run `prepare_internal_flashing.sh` to get
  34. files and instructions about updating. No need to disassemble.
  35. ## Flashing for the first time
  36. Especially for the first time, you must flash externally. See below for the details
  37. for using a Rapberry Pi, for example.
  38. ### flashrom chip config
  39. We (or our scripts) use [flashrom](https://flashrom.org/) for flashing. Run
  40. `flashrom -p <your_hardware>` (for [example](#how-to-flash)
  41. `flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=128` for the
  42. Raspberry Pi) to let flashrom detect the chip.
  43. It will probably list a few you need to choose from when flashing
  44. (by adding `-c <chipname>`). Please review the chip model for your device.
  45. In case you are unsure what to specify, here's some examples we find out there:
  46. #### 4MB chip
  47. * `MX25L3206E` seems to mostly be in use
  48. #### 8MB chip
  49. * `MX25L6406E/MX25L6408E` is used in [this guide](https://github.com/mfc/flashing-docs/blob/master/walkthrough%20for%20flashing%20heads%20on%20an%20x230.md#neutering-me)
  50. * `MX25L3206E/MX25L3208E` is seen working with various X230 models.
  51. * `EN25QH64` is used sometimes
  52. ### EC firmware (optional)
  53. Enter Lenovo's BIOS with __F1__ and check the embedded controller (EC) version to be
  54. __1.14__ and upgrade using
  55. [the latest bootable CD](https://support.lenovo.com/at/en/downloads/ds029188)
  56. if it isn't. This updates BIOS and EC. The EC cannot be upgraded when coreboot
  57. is installed. (In case a newer version should ever be available (I doubt it),
  58. you could temporarily flash back the original Lenovo BIOS image from your
  59. backup)
  60. ### ifd unlock and me_cleaner: the 8MB chip
  61. The Intel Management Engine resides on the 8MB chip (at the bottom, closer to
  62. you). We don't need to touch it
  63. for coreboot-upgrades in the future, but to enable internal flashing, we need
  64. to unlock it once.
  65. We run [ifdtool](https://github.com/coreboot/coreboot/tree/master/util/ifdtool)
  66. and, while we are at it, [me_cleaner](https://github.com/corna/me_cleaner) on it:
  67. We support using a RPi, see below for the connection details.
  68. Move the release-tarball to the RPi (USB Stick or however) and unpack it
  69. (to the current directory and change into it):
  70. mkdir tarball_extracted
  71. tar -xf <tarball>.tar.xz -C tarball_extracted
  72. cd tarball_extracted
  73. And finally unlock the 8M chip by using the included script (be patient):
  74. sudo ./flashrom_rpi_bottom_unlock.sh -m -c <chipname> -k <backup.bin>
  75. That's it. Keep the backup safe.
  76. #### background (just so you know)
  77. * The `-m` option above also runs `me_cleaner -S` before flashing back.
  78. * The `-l` option will (re-)lock your flash ROM, in case you want to force
  79. yourself (and others) to hardware-flashing externally.
  80. * If you don't use a RPi, change the flashrom programmer to your needs.This
  81. is roughly what's going on:
  82. flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=128 -c "MX25L6406E/MX25L6408E" -r ifdmegbe.rom
  83. flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=128 -c "MX25L6406E/MX25L6408E" -r ifdmegbe2.rom
  84. diff ifdmegbe.rom ifdmegbe2.rom
  85. git clone https://github.com/corna/me_cleaner.git && cd me_cleaner
  86. ./me_cleaner.py -S -O ifdmegbe_meclean.rom ifdmegbe.rom
  87. ifdtool -u ifdmegbe_meclean.rom
  88. flashrom -p linux_spi:dev=/dev/spidev0.0,spispeed=128 -c "MX25L6406E/MX25L6408E" -w ifdmegbe_meclean.rom.new
  89. ### BIOS: the 4MB chip
  90. (internally, memory of the two chips is mapped together, the 8MB being the lower
  91. part, but we can essientially ignore that). Again, using a RPi is supported
  92. here. We assume you have the unpacked release tarball ready, see above. Use
  93. the following included script:
  94. sudo ./flashrom_rpi_top_write.sh -i x230_coreboot_seabios_<hash>_top.rom -c <chipname> -k <backup>
  95. That's it. Keep the backup safe.
  96. ## How to update
  97. When __upgrading__ to a new release, only the "upper" 4MB chip has to be written.
  98. Download the latest release image we provide and flash it:
  99. ### Example: internal
  100. CAUTION: THIS IS NOT ENCOURAGED
  101. * Only for _updating_! You have to have your 8MB chip flashed externally using
  102. our `flashrom_rpi_bottom_unlock.sh` script (`ifdtool -u`) before this, once
  103. * very convenient: just install flashrom on the X230 and software-update,
  104. but according to the
  105. [flashrom manpage](https://manpages.debian.org/stretch/flashrom/flashrom.8.en.html)
  106. this is very dangerous!
  107. * Boot Linux with the `iomem=relaxed` boot parameter (for example set in /etc/default/grub)
  108. * download the latest release tarball (4MB "top" BIOS image is included) and extract it
  109. * run `prepare_internal_flashing.sh` for generating all necessary files and printing all instructions
  110. * run the flashrom command you got from the script. That's it.
  111. ### Example: Raspberry Pi 3
  112. Here you'll flash externally, using a "Pomona 5250 8-pin SOIC test clip". You'll find
  113. one easily. This is how the X230's SPI connection looks on both chips:
  114. Screen (furthest from you)
  115. __
  116. MOSI 5 --| |-- 4 GND
  117. CLK 6 --| |-- 3 N/C
  118. N/C 7 --| |-- 2 MISO
  119. VCC 8 --|__|-- 1 CS
  120. Edge (closest to you)
  121. and with our release tarball unpacked, the command you need looks like so:
  122. flashrom_rpi_top_write.sh -i x230_coreboot_seabios_<release>_top.rom -c <chipname>
  123. We run [Raspbian](https://www.raspberrypi.org/downloads/raspbian/)
  124. and have the following setup
  125. * [Serial connection](https://elinux.org/RPi_Serial_Connection) using a "USB to Serial" UART Adapter and picocom or minicom
  126. * Yes, in this case you need a second PC connected to the RPi over UART
  127. * in the SD Cards's `/boot/config.txt` file `enable_uart=1` and `dtparam=spi=on`
  128. * [For flashrom](https://www.flashrom.org/RaspberryPi) we put `spi_bcm2835` and `spidev` in /etc/modules
  129. * [Connect to a wifi](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md) or to network over ethernet to `sudo apt-get flashrom`
  130. * only flash the top 4M chip
  131. * connect the Clip to the Raspberry Pi 3 (there are [prettier images](https://github.com/splitbrain/rpibplusleaf) too:
  132. Edge of pi (furthest from you)
  133. (UART)
  134. L GND TX RX CS
  135. E | | | |
  136. F +---------------------------------------------------------------------------------+
  137. T | x x x x x x x x x x x x x x x x x x x x |
  138. | x x x x x x x x x x x x x x x x x x x x |
  139. E +----------------------------------^---^---^---^-------------------------------^--+
  140. D | | | | |
  141. G 3.3V MOSIMISO| GND
  142. E (VCC) CLK
  143. Body of Pi (closest to you)
  144. Now copy our release tarball over to the Rasperry Pi.
  145. One way to copy, is convertig it to ascii using
  146. `uuencode` (part of Debian's sharutils package) described below. This is a
  147. direct, shady and slow way to transfer a file. Use a USB
  148. Stick or scp instead. :) (but you need even more hardware or a network).
  149. (convert)
  150. host$ uuencode <tarball> <tarball>.ascii > <tarball>.ascii
  151. (transfer)
  152. rpi$ cat > <tarball>.ascii
  153. host$ pv <tarball>.ascii > /dev/ttyUSBX
  154. (wait)
  155. rpi$ (CTRL-D)
  156. (convert back)
  157. rpi$ uudecode -o <tarball> <tarball>.ascii
  158. (verify)
  159. host$ sha1sum <tarball>
  160. rpi$ sha1sum <tarball>
  161. ![Raspberry Pi at work](rpi_clip.jpg)
  162. Now unpack it:
  163. mkdir tarball_extracted
  164. tar -xf <tarball> -C tarball_extracted
  165. cd tarball_extracted
  166. Check the SPI connection to the "top" chip to update, and run:
  167. sudo ./flashrom_rpi_top_write.sh -i x230_coreboot_seabios_<hash>_top.rom -c <chipname>
  168. That's it.
  169. #### background (just so you know)
  170. * Connecting an ethernet cable as a power-source for SPI (instead of the VCC pin)
  171. is not necessary (some other flashing how-to guides mention this).
  172. Setting a fixed (and low) SPI speed for flashrom offeres the same stability.
  173. Our scripts do this for you.
  174. ## When do we do a release?
  175. Either when
  176. * There is a new SeaBIOS release,
  177. * There is a new Intel microcode release (for our CPU model),
  178. * There is a coreboot issue that affects us, or
  179. * We change the config
  180. ## How we build
  181. * Everything necessary to build coreboot (while only the top 4MB are usable of course) is included here
  182. * The task of [building coreboot](https://www.coreboot.org/Build_HOWTO) is not too difficult
  183. * When doing a release here, we always try to upload to coreboot's [board status project](https://www.coreboot.org/Supported_Motherboards)
  184. * If we add out-of-tree patches, we always [post them for review](http://review.coreboot.org/) upstream
  185. ## Why does this work?
  186. On the X230, there are 2 physical "BIOS" chips. The "upper" 4MB
  187. one holds the actual bios we can generate using coreboot, and the "lower" 8MB
  188. one holds the rest that you can [modify yourself once](#flashing-for-the-first-time),
  189. if you like, but strictly speaking, you
  190. [don't need to touch it at all](https://www.coreboot.org/Board:lenovo/x230#Building_Firmware).
  191. What's this "rest"?
  192. Mainly a tiny binary used by the Ethernet card and the Intel Management Engine.
  193. ## Alternatives
  194. We aim to be the easiest possible coreboot distribution for the X230 - both
  195. to install and to use. And since our images are unlocked to enable easy
  196. software updates, it's easy to try alternative systems too:
  197. * [Heads](https://github.com/osresearch/heads/releases) - coreboot distribution
  198. with pre-built (or reproducibly buildable) flash images for the X230. Heads
  199. includes Linux, with tools to create a trusted boot chain using your GPG key
  200. and the TPM.
  201. * [libreboot](https://libreboot.org/) - also a coreboot distribution with pre-built
  202. image releases. But the X230 is currently not supported (the X200 is) - libreboot
  203. images are built from free software only and include the GRUB bootloader.