Documentation/mainboard/purism/librem_mini.md

   1 # Purism Librem Mini (v1, v2)
   2
   3 This page describes how to run coreboot on the [Purism Librem Mini].
   4
   5 ```eval_rst
   6 +------------------+--------------------------------------------------+
   7 | CPU              | Intel Core i7-8565U/8665U (v1)                   |
   8 |                  | Intel Core i7-10510U      (v2)                   |
   9 +------------------+--------------------------------------------------+
  10 | PCH              | Whiskey Lake / Cannon Point LP       (v1)        |
  11 |                  | Comet Lake LP Premium (Comet Lake-U) (v2)        |
  12 +------------------+--------------------------------------------------+
  13 | Super I/O, EC    | ITE IT8528E                                      |
  14 +------------------+--------------------------------------------------+
  15 | Coprocessor      | Intel Management Engine (CSME 12.x) (v1)         |
  16 |                  | Intel Management Engine (CSME 14.x) (v2)         |
  17 +------------------+--------------------------------------------------+
  18 ```
  19
  20 ![](librem_mini.jpg)
  21 ![](librem_mini_flash.jpg)
  22
  23 ## Required proprietary blobs
  24
  25 To build a minimal working coreboot image some blobs are required (assuming
  26 only the BIOS region is being modified).
  27
  28 ```eval_rst
  29 +-----------------+---------------------------------+---------------------+
  30 | Binary file     | Apply                           | Required / Optional |
  31 +=================+=================================+=====================+
  32 | FSP-M, FSP-S    | Intel Firmware Support Package  | Required            |
  33 +-----------------+---------------------------------+---------------------+
  34 | microcode       | CPU microcode                   | Required            |
  35 +-----------------+---------------------------------+---------------------+
  36 | vgabios         | VGA Option ROM                  | Optional            |
  37 +-----------------+---------------------------------+---------------------+
  38 ```
  39
  40 FSP-M and FSP-S are obtained after splitting the FSP binary (done automatically
  41 by the coreboot build system and included into the image; Coffee Lake for v1,
  42 Comet Lake for v2) from the `3rdparty/fsp` submodule.
  43
  44 Microcode updates are automatically included into the coreboot image by the build
  45 system from the `3rdparty/intel-microcode` submodule. Official Purism release
  46 images may include newer microcode, which is instead pulled from Purism's
  47 [purism-blobs] repository.
  48
  49 VGA Option ROM is not required to boot, but if one needs graphics in pre-OS
  50 stage, it should be included (if not using FSP/GOP display init). It can
  51 be extracted via cbfstool from the existing board firmware or pulled from
  52 the [purism-blobs] repository.
  53
  54 ## Intel Management Engine
  55
  56 The Librem Mini uses version 12.x (v1) or 14.x (v2) of the Intel Management
  57 Engine (ME) / Converged Security Engine (CSE). The ME/CSE is disabled using
  58 the High Assurance Platform (HAP) bit, which puts the ME into a disabled state
  59 after platform bring-up (BUP) and disables all PCI/HECI interfaces.
  60 This can be verified via the coreboot cbmem utility:
  61
  62     `sudo ./cbmem -1 | grep 'ME:'`
  63
  64 provided coreboot has been modified to output the ME status even when
  65 the PCI device is not visible/active (as it is in Purism's release builds).
  66
  67 ## Flashing coreboot
  68
  69 ### Internal programming
  70
  71 The main SPI flash can be accessed using [flashrom]. The first version
  72 supporting the chipset is flashrom v1.2 (v1.2-107-gb1f858f or later needed
  73 for the Mini v2). Firmware an be easily flashed with internal programmer
  74 (either BIOS region or full image).
  75
  76 ### External programming
  77
  78 The system has an internal flash chip which is a 8 MiB soldered SOIC-8 chip,
  79 and has a diode attached to the VCC line for in-system programming.
  80 This chip is located on the bottom side of the board under the CPU heatsink,
  81 in line with the front USB 2.0 ports.
  82
  83 One has to remove all screws (in order):
  84
  85  * 2 top cover screws
  86  * 4 screws securing the mainboard to the chassis
  87  * 4 screws securing the heatsink/fan assembly to the mainboard (under the SODIMMs)
  88
  89 The m.2 SSD will need to be removed if the Wi-Fi antenna are connected to
  90 an internal Wi-Fi/BT module. Use a SOIC-8 chip clip to program the chip.
  91 Specifically, it's a Winbond W25Q128JV (3.3V) - [datasheet][W25Q128JV].
  92
  93 The EC firmware is stored on a separate SOIC-8 chip (a Winbond W25Q80DV),
  94 but is not protected by a diode and therefore cannot be read/written to without
  95 desoldering it from the mainboard.
  96
  97 ## Known issues
  98
  99  * SeaBIOS can be finicky with detecting USB devices
 100  * Mode switching with VGA option ROM display init can be slow and sometimes hangs
 101  * Some SATA devices on the 2.5" interface can have issues operating at 6 Gbps,
 102    despite the HSIO PHY settings being set optimally via experimentation. These devices
 103    may show errors in dmesg and drop down to 3 Gbps, but should not fail to boot.
 104    The same issue is present on the AMI vendor firmware.
 105
 106 ## Working
 107
 108  * External displays via HDMI/DisplayPort with VGA option ROM or FSP/GOP init
 109    (no libgfxinit support yet)
 110  * SeaBIOS (1.14), edk2 (CorebootPayloadPkg), Heads (Purism downstream) payloads
 111  * Ethernet, m.2 2230 Wi-Fi
 112  * System firmware updates via flashrom
 113  * PCIe NVMe
 114  * m.2 and SATA III
 115  * Audio via front 3.5mm jack, HDMI, and DisplayPort
 116  * SMBus (reading SPD from DIMMs)
 117  * Initialization with FSP 2.0 (CFL for v1, CML for v2)
 118  * S3 Suspend/Resume
 119  * Booting PureOS 10.x, Debian 11.x, Qubes 4.1.0-alpha1, Linux Mint 20, Windows 10 2004
 120
 121 ## Not working / untested
 122
 123  * ITE IT8528E Super IO functions
 124
 125
 126 [Purism Librem Mini]: https://puri.sm/products/librem-mini/
 127 [purism-blobs]: https://source.puri.sm/coreboot/purism-blobs
 128 [W25Q128JV]: https://www.winbond.com/resource-files/w25q128jv%20revf%2003272018%20plus.pdf
 129 [flashrom]: https://flashrom.org/Flashrom