osboot installation manual

Edit this page -- Back to previous index

Guidance for using flashrom

Flashrom complains about /dev/mem. What can I do?

If running flashrom -p internal for software based flashing, and you get an error related to /dev/mem access, you should reboot with iomem=relaxed kernel parameter before running flashrom, or use a kernel that has CONFIG_STRICT_DEVMEM not enabled.

Further guidance: externally re-programming Macronix chips on Lenovo X200/X200S/X200T

Use this modified version of Flashrom (version 0.9.9).

https://vimuser.org/hackrom.tar.xz

It contains a pre-compiled binary, along with source code, for running on a Raspberry pi. Use the --workaround-mx argument when running flashrom, if externally re-programming a Macronix flash chip. This will make the flashing much more reliable, otherwise you will encounter instability on those chips, on those boards.

(vimuser.org belongs to Leah Rowe, who is a developer of osboot and Libreboot)

Using flashrom internally

Internally means booting GNU+Linux or other OS, and running software directly on the target system (for flashing), to reprogram the boot flash.

On many systems, you can simply run flashrom from GNU+Linux running on said system, like so:

flashrom -p internal -w your.rom

You can also dump the chip contents:

flashrom -p internal -r dump.rom

If your flash is read-write this is perfectly acceptable, but please ensure that you’re flashing a correct image. On some systems, EC firmware shares main boot flash (e.g. on some rockchip ARM chromebooks), or an Intel Flash Descriptor is used with read-only regions, and/or Intel ME is used which will interfere with flashing to the Intel ME region in flash).

However, some systems require other considerations. For instance, on most newer Intel systems you must ensure either:

Information about systems

Where to find ROM images for installation

You can either use an available release (for your machine) or compile from the osboot Git repository.

Go to the download page

The download page links to releases, and to the Git repository with guidance on compiling ROM images from the source code.

What systems are compatible with osboot?

This is covered in the hardware section:

What systems are compatible with osboot?

Information about osboot ROM images

Jump to section

Information about ICH9M descriptors including changing the MAC address (X200 etc)

This is covered on the page about ich9utils:

Information about CPU microcode updates on x86 targets

This is especially useful to know for targets that Libreboot also supports:

Flashing via software methods, on system:

The term software method implies that you are running flashrom on the target system, probably on a running GNU+Linux system. It is contrary to a hardware method which involves physically accessing the boot flash and reprogramming it using external hardware.

On many systems, software based flashing is not possible until you’ve already replaced the default firmware. Therefore, most of these sections have to do with updating an existing osboot/Libreboot/coreboot ROM image that you have already flashed previously:

Apple Macbook2,1 and Macbook2,1

Learn how to internally flash Macbook2,1 or 1,1

ASUS KCMA-D8 (if already running coreboot/osboot/libreboot)

See: #flashrom

If you have the ASUS BIOS, refer to external flashing instructions here: ../hardware/kcma-d8.html

The ASUS BIOS restricts flash writes, so you need to use external hardware for flashing it the first time. Please use the link above, to learn more.

GM45 targets such as ThinkPad X200/X200S/X200T/T400/R500/W500/R400/X301/T500

NOTE: As of 17 March 2021, not all GM45 targets mentioned above are supported in osboot yet, but they all will be.

Jump to section

ThinkPad X220/T420/T420S (8MiB NOR flash, with 5MiB ifd+gbe+me and 3MiB BIOS)

If you’ve already flashed a coreboot/osboot ROM before, with the default 3MiB BIOS region setup, and you unlocked the flash using ifdtool --unlock

Jump to section

If you didn’t unlock, regardless of whether you neutered the ME, you can still flash it, using a layout file, to flash just the BIOS region but you cannot re-flash the entire chip. Use the above link to learn more.

ThinkPad X230/X230T/T440p (12MiB NOR flash, with 5MiB ifd+gbe+me and 7MiB BIOS)

If you’ve already flashed a coreboot/osboot ROM before, with the default 7MiB BIOS region setup, and you unlocked the flash using ifdtool --unlock

Jump to section

If you didn’tunlock, regardless of whether you neutered the ME, you can still flash it, using a layout file, to flash just the BIOS region but you cannot re-flash the entirechip. Usethe above link to learn more.

This guide works whether you neutered the ME or not, but it assumes that the ME region is not truncated and that you have the default flash region layout as per the Intel flash descriptor which is: 4KiB descriptor, then 8KiB GbE then up to 5MiB is the ME region, then the final 7MiB is the BIOS region.

The guide linked above is for X230 but will work for T440p ROMs aswell.

ThinkPad X60/X60S/X60T/T60 if already running osboot/coreboot

Jump to section

ThinkPad X60/X60S/X60T/T60 if running Lenovo BIOS

Jump to section

Setting up programmers, for external SPI flashing

With these, you access the physical boot flash containing firmware. You will reprogram them directly, using external flashing equipment.

Raspberry Pi

The Raspberry Pi is an excellent flasher, capable of reprogramming 25XX NOR flash via SPI protocol. Highly recommended for its reliability, although it’s not the cheapest option (not the most expensive, either).

Reprogramming 25XX NOR flash via SPI protocol with Raspberry Pi

DO NOT USE CH341A!!! It can damage your board/chip

Do not use CH341A. Here is why

Flashing via hardware methods, on system:

This method means that you are physically accessing the boot flash, so as to reprogramming it externally using specialized hardware.

Apple Macbook2,1 and Macbook2,1

Learn how to disassemble Macbook2,1 or Macbook1,1

ThinkPad X60/X60S

Learn how to disassemble X60/X60S

ThinkPad X60 Tablet

Learn how to disassemble X60T

ThinkPad T60 with Intel GPU

Ones with ATI GPU are not supported because it’s not legal to distribute the required ATI option ROM.

It might be OK to add support in osboot if we extract it from Lenovo recovery images. It’s on the TODO to look into this. Due to quirks with how the ATOM BIOS works, there are extra considerations. It configures ports and such, and Lenovo BIOS is modifying the ROM at boot time to accomplish that. However, coreboot has no ability to do that yet. We would need to download the recovery image from Lenovo, extract the correct VGA ROM, verify its checksum and then modify it at build time (so that it’s already configured, and then coreboot can just load that. Alternatively, modify coreboot to configure the ATOM BIOS at boot time).

Anyway:

Learn how to disassembly T60

ThinkPad X200 (NOT X200S/X200Tablet)

Learn how to disassemble ThinkPad X200

ThinkPad T400

Refer to this YouTube video for how to disassemble and flash it:

https://www.youtube.com/watch?v=lf3AJK56ZPw

If you don’t like non-free javascript, here’s the invidious link:

https://invidious.snopyta.org/watch?v=lf3AJK56ZPw

Refer to the RPi guide for how to flash the chip (it’s a SOIC8 or a SOIC16 near the RAM. 4MiB if SOIC8. 8MiB if SOIC16):

Reprogramming SPI 25XX NOR flash with Raspberry Pi

This machine puts the MAC address in the GbE region of the ROM, so you should change the default one that is in the osboot ROM. See: ich9utils.html

ThinkPad W500/T500

Read the installation instructions here: ../hardware/t500w500.html

R500

Very similar disassembly to the T400 (see above), but here is the HMM:

https://thinkpads.com/support/hmm/hmm_pdf/r500_hmm_en_43y6631_03.pdf

Read that to know disassembly. Flash chip is a 4MiB SOIC8 near the RAM. Read:

Reprogramming SPI 25XX NOR flash with Raspberry Pi

NOTE: No Intel PHY. Uses a broadcom gigabit NIC, so no need to mess with the MAC address in ich9gen. Just flash the ROM that osboot provided in the build system.

ThinkPad X200S / X200 Tablet

Jump to section

ThinkPad X220/X220S (8MiB NOR flash with 5MiB Intel ME)

Learn how to disassemble ThinkPad X220/X220S

ThinkPad T420/T420S

Learn how to disassemble ThinkPad T420/T420S

ThinkPad X230/X230T (NOT X230S. Guide+support will be added later to osboot)

Learn how to disassemble ThinkPad X230/X230T

Installing osboot onto ThinkPad X200S or X200 Tablet

Flash the same ROM image for X200 on your X200S or X200 Tablet. They are the same boards.

These laptops use WSON8 form factory for the NOR flash. It must be de-soldered, and replaced with a SO8/SOIC8 NOR flash.

X200S/X200Tablet not yet fully documented on osboot for external flash, but Leah Rowe has videos on her YouTube channel showing how to have Libreboot on these. First, watch this video:

https://www.youtube.com/watch?v=tguch_iPBZQ

Then watch this video:

https://www.youtube.com/watch?v=oUYHzOQXx80

Use youtube-dl to download these video, if you wish to avoid non-free JavaScript on youtube.com. The osboot project is currently setting up a video hosting site, which will run GNU MediaGoblin. However, this website is not yet available to the public.

The plan is to, over time, host all osboot related videos there. A separate virtual host is also being configured an that server, for Libreboot videos linked on libreboot.org.

When you have installed osboot on your X200S or X200 Tablet, using these instructions, internal flashing is possible (unless you flash a ROM with Intel Flash Descriptor that sets flash regions read-only, in which case external flashing is needed again but at that point, a regular SOIC8 test clip can be used rather than having to solder anything).

Most people who flash X200S or X200 Tablet solder 30awg kynar wires directly to the original WSON8, flash it and then de-solder them, and then boot up. This is NOT recommended by the osboot project and can in fact ruin your machine. The reason is simple: the WSON8 is a QFN type IC, and is therefore not designed to have modwires on it. You run the risk of causing discontinuity with the QFN/pads and where they lead to on the mainboard, and it means that you are mixing old solder with new solder. Mixing solder chemistries is never a good idea and can lead to cold joints.

Therefore, the osboot project recommends that you do it properly, using the instructions in the videos linked above. You will remove the original WSON using a hot air jet, then install the new SOIC8 using regular knife tip.

Use lots of flux! Use quality 60/40 leaded solder (none of that Rohs rubbish).

CPU microcode on Libreboot-compatible targets

Targets from Libreboot (such as X200/T400) contain CPU microcode updates when built using the osboot build system. To remove these, use cbfstool e.g.:

cbfstool x200.osboot.rom remove -n cpu_microcode_blob.bin

Then re-flash. When you do this, and the ROM has libgfxinit in the file name (rather than vgarom), it will be a ROM containing only 100% Free Software, like Libreboot.

Unlike Libreboot, osboot does not prohibit binary blobs in its build system. The CPU microcode updates are useful, because they fix bugs in the CPU. For example, power/thermal management is greatly improved on i945 laptops (X60/T60) and virtualization is enabled on GM45 laptops (X200/T400) not to mention, general system stability is greatly increased.

This has other benefits. For instance, Opteron 6300 CPUs are now fully stable on D16 when flashed with a osboot ROM, as opposed to Libreboot.

The only binary blobs added, in osboot, to systems that come from Libreboot, are:

Information about osboot ROM images

When ROM images are provided, by the osboot build system, they appear under the bin/ directory.

How to compile osboot ROM images

You do not have to build ROM images from the source code. In addition to that, you can also download one of the releases on the download page where pre-compiled ROM images are available. These ROM images are built using the exact same steps as defined in the link above.

If you wish to help with osboot development (for instance, adding a board to osboot that you have, which has coreboot support, and maintaining support for it in osboot), you should first familiarize yourself with the osboot build system. The entire build system is documented in the osboot maintenance manual

General rules about ROM file names:

Beyond this, the file name of your ROM will contain the name of the machine and the default coreboot payload (GRUB, SeaBIOS, Tianocore etc) in use.

Read the osboot maintenance manual

GM45 targets such as X200/T400/T500/W500/R400/R500/X301 if already running osboot/Libreboot

NOTE: This section also applies to W500/T500/T400/R400/X301 and other GM45 laptops, but for R500 you can ignore the notes below about MAC address.

For X200/X200S/X200T the ROM is the same. The only difference is which ROM you select based on the size of your boot flash (4MiB and 8MiB are most common, or 16MiB is typical if you are replacing the flash because that’s the maximum size supported on this machine).

Just use flashrom -p internal on a ROM supplied by the osboot project, or a ROM that you built using the osboot build system.

Use the -w argument. You can also specify a custom MAC address in the GbE region, by overwriting the default descriptor+GbE region using ich9gen and dd.

For instructions on changing your MAC address and on the ICH9 descriptors in general, refer to the ich9utils page.

Example:

flashrom -p internal -w x200.osboot.rom

NOTE: This won’t work if you flashed with an Intel Flash Descriptor that set the regions read-only in your boot flash.

X60/X60S/X60T/T60: How to update or install osboot (if you are already running osboot or coreboot)

Just use flashrom -p internal when flashing T60 if you already have a osboot/Libreboot/Coreboot ROM with the upper 64KiB bootblock flashed (either externally, or as a result of using the Libreboot 20160907 install scripts for first flash and second flash (see below on this page).

Example:

flashrom -p internal -w t60.osboot.rom

If flashrom complains about multiple chips detected, just do what it says and use the -c option to pick a chip. If it fails, pick another one.

You can find flashrom under the flashrom/ directory in the osboot source code release archives. Build it (from source) using the osboot build instructions page.

Updating/changing the X220/T420/T420S ROM if osboot already flashed

This assumes that you unlocked the regions using ifdtool, and ran me_cleaner, when installing osboot the first time. osboot currently does not provide pre-compiled utilities, but you can download the source code archive of osboot from the download page and build these utilities using the instructions at osboot build instructions page.

For X220 you will want to use a layout file in flashrom and only flash the BIOS region, which is the upper 3MiB region on the default descriptor configuration (unless you modified it to change region sizes and or move them).

For flashing the BIOS region, a custom flash layout file is included at:

resources/coreboot/x220/flash.layout

osboot includes 8MiB ROM images for X220, but only the upper 3MiB of it should be flashed, to the upper 3MiB of the flash chip. The low 5MiB of the ROM is all 0xFF which you should not flash; the lower 5MiB on the actual chip contains your Intel Flash Descriptor, GbE and Intel ME regions and it’s very important that these do not get overwritten.

Assuming that you compiled flashrom (from osboot build system), you can use the followang command to flash your ROM:

sudo ./flashrom/flashrom -l resources/coreboot/x220/flash.layout -i coreboot -w osboot.rom -p internal

NOTE: X220, T420 and T420S all have the same default region layout, so even though the above specifies a flash layout for X220, the actual flash layout included for T420/T420S are exactly the same in osboot. However, please make sure that you are flashing the correct ROM image!

In the above example, osboot.rom is your 8MiB ROM image. The -i coreboot option specifies that only the coreboot part should be flashed, and the -l argument specifying the flash layout defines that coreboot region as the upper 3MiB of the flash.

If your machine currently has Lenovo BIOS, OR has the default unmodified 5MiB descriptor+gbe+me in the 8MiB flash chip then you will need to re-flash externally using this guide:

How to flash ThinkPad X220 externally

The linked guide instructs you

That’s only if you want to also flash the descriptor, ME and/or GbE region. If coreboot/osboot is already running, you can re-flash internally if using a layout file specifying to flash only the upper 3MiB BIOS region but in that situation if ME is not neutered and/or ME/descriptor region is set read-only you must pass the following parameter as an argument in flashrom: --noverify-all

However you decided to flash, flashrom will say VERIFIED if it was a successful flash. After you flash, and it says VERIFIED, turn off the system, wait a few seconds and then boot up again. If it didn’t say VERIFIED, unless othewise stated by this documentation, you should NOT turn off your system and seek immediate help, for it may brick if you turn it off, so it may need to be fixed. (unless flashrom didn’t actually do anything because you typo’d the command or something, like specifying a non-existing ROM on your file system)

Updating/changing the X230/X230T/T440p ROM if osboot already flashed

This section assumes that you have a 12MiB NOR flash comprising of 8MiB and a 4MiB chip on the board, where the lower half of the 12MiB ROM is the 8MiB chip and the 4MiB is the upper section. In your OS, it is seen as a whole 12MiB of boot flash.

NOTE: This also applies to T440p, which has the same flash layout and physical chip configuration even if it’s a different platform overall. In terms of running me_cleaner, flashrom and using the layout file, it’s the same. Just make sure to use a T440p ROM. osboot cannot provide pre-compiled T440p ROMs because of mrc.bin (not allowed to distribute) but the build system in osboot can build ROMs and automatically extract mrc.bin from Google Peppy images available online.

If you have a T440p just substitute t440p whe reading about x230 below.

osboot provides separate ROM images for X230 and X230 Tablet. The instructions are the same for both, with the only difference being which ROM you use.

NOTE: osboot includes ROMs with 4mb in the file name, but these are for external flashing, for flashing just SPI2 (the 4MiB chip). If you’re doing internal flashing (flashrom on OS running on the X230), use the 7mb ROM. The ROM says 7mb in the file name, but the actual file size is 12MiB. This is because the ROM is compiled for the 12MiB of boot flash on your X230, but with CBFS size set to 7MiB. You will flash only the upper 7MiB of that ROM, to the upper 7MiB of the 12MiB boot flash on your X230.

Your X230 has two flash chips: 8MiB for the lower part and 4MiB for the upper part. Combined, this creates 12MiB of flash and this is what flashrom sees when using -p internal.

This guide that you unlocked the regions using ifdtool, and ran me_cleaner, when installing osboot the first time. osboot currently does not provide pre-compiled utilities, but you can download the source code archive of osboot from the download page and build these utilities using the instructions at osboot build instructions page.

For X230/X230T you will want to use a layout file in flashrom and only flash the BIOS region, which is the upper 7MiB region on the default descriptor configuration (unless you modified it to change region sizes and or move them); osboot provides the option to flash a 4MiB ROM (CBFS size 4MiB) with 3MiB lower section of the BIOS region unused, or a full 7MiB ROM (CBFS size 7MiB) with all of the BIOS region available to you in cbfstool.

The 4MiB ROM files are provided for external flashing, for flashing osboot the first time, to make things a little bit simpler (just dump the whole 8MiB NOR flash, run it through me_cleaner and ifdtool --unlock, flash it back, and then flash the 4MiB ROM to the 4MiB NOR flash).

The 7MiB ROM files are provided for internal flashing, after you flashed the first time using the 4MiB ROM externally. You can flash the 7MiB file externally but you have to split the lower 3MiB of the upper of the ROM image, and flash it (using a layout file) to the upper 3MiB of the 8MiB NOR flash. Then you flash the upper 4MiB of that 7MiB ROM, to the 4MiB NOR flash. It’s much simpler to just flash the 4MiB ROM to the 4MiB NOR flash, then boot and OS and run flashrom -p internal, with layout file, to flash the 7MiB file since the two flash chips are seen as one big 12MiB “chip” in your operating system.

Seriously. Just use the full 12MiB images marked 7mb and use the included layout file. Instructions are below.

For X230 if flashing a 7MiB ROM (7MiB CBFS size), a custom flash layout file is included here in the Git repository / archive, for internal flashing:

resources/coreboot/x230_7mb/flash.layout

These layout files, when used, specify that flashrom must only flash a certain region. When using flashrom -p internal running on e.g. GNU+Linux, the 8MiB and 4MiB NOR flash (on the X230 mainboard) are detected as a single, continuous 12MiB of flash, with the 8MiB flash being the lower section and 4MiB NOR flash being in the upper section of what it sees.

Flash the ROM with 7mb in the file name, and use the layout file included in osboot to flash just the upper 7MiB of that ROM to the upper 7MiB of the 12MiB boot flash:

sudo ./flashrom/flashrom -l resources/coreboot/x230_7mb/flash.layout -i coreboot -w osboot.rom -p internal

The -l parameter in flashrom specifies a layout file. In that layout file is specified an arbitrary set of regions. These regions can be within any boundaries you like.

The 7MiB layout file (for ROMs with 7mb in the file name) looks like this, inside:

00000000:004fffff intelstuff
00500000:00bfffff coreboot

These are boundaries in bytes, specified in hexademical.

The -i parameter in flashrom specifies which region (as per the layout file) should be flashed. NOTE: region, in this context, refers to flashrom layout file structure, not regions as defined in the Intel Flash Descriptor. So, -i coreboot specifies that only those boundaries in that ROM are to be flashed within those boundaries of the NOR flash.

BE SURE to flash ONLY the coreboot region, where the contents of the osboot ROM is what ends up being flashed there. If you mess this up, you could brick your machine (make it unbootable). The lower 5MiB of your boot flash is the Intel Flash Descriptor, Gbe and ME regions which should NOT be overwritten!

The above flashrom command for X230 will flash only the BIOS region. The file newosbootrom.rom could be a new osboot ROM, if you’re updating to a new version, or it could be that you are switching to a different ROM configuration on the same version of osboot. So long as its a coreboot image with flash size set to 12MiB, CBFS size set to 4MiB or lower and the 4MiB coreboot part spliced out after coreboot was built (e.g. using dd the way the osboot build system does it when building ROMs. See ROM building scripts under resources/scripts/build/roms/ for how osboot does it: it builds 12MiB coreboot ROMs but everything below the upper 4MiB is 0xFF and the upper 4MiB is the coreboot ROM with CBFS size to 4MiB size, on osboot ROMs).

If your X230 currently has Lenovo BIOS, OR has the default unmodified 8MiB descriptor+gbe+me in SPI1 (8MiB flash chip) you will need to re-flash externally using this guide:

How to flash ThinkPad X230 externally

However you decided to flash, flashrom will say VERIFIED if it was a successful flash. After you flash, and it says VERIFIED, turn off the system, wait a few seconds and then boot up again. If it didn’t say VERIFIED, unless othewise stated by this documentation, you should NOT turn off your system and seek immediate help, for it may brick if you turn it off, so it may need to be fixed. (unless flashrom didn’t actually do anything because you typo’d the command or something, like specifying a non-existing ROM on your file system)

ThinkPad X60/X60S/X60T/T60: Initial installation guide (if running the proprietary firmware)

For now, no integration exists in osboot for the first and second flash (you need to flash twice, when flashing from LenovoBIOS to osboot). Go and download the Libreboot 20160907 util release archive from https://libreboot.org/ and follow the instructions on the Libreboot website:

https://libreboot.org/docs/install/#flashrom_lenovobios

NOTE: The libreboot website doesn’t tell you to back up your Lenovo BIOS, but you should. Do it using this flashrom command:

sudo flashrom -p internal -r factory.bin

A 2MiB file named factory.bin will have been created. If flashrom complained about multiple flash chips detected, just do what it says and pick one using the -c option.

Libreboot supports T60/X60 that has Intel GPU, whereas osboot supports T60 that has ATI GPU.

However, the procedure for flashing osboot on your T60 when you have ATI GPU and you’re running Lenovo BIOS, is exactly the same as when you have an Intel T60 and flashing Libreboot from Lenovo BIOS.

Imagine that you’re flashing Libreboot on a T60 that has Intel GPU, and follow the instructions on that libreboot page, but use the T60 ROM that you compiled in the osboot build system. That T60 ROM has an ATOMBIOS VGA option ROM for the ATI Mobility Radeon X1400 GPU, and uses the SeaBIOS payload.

Edit this pageLicenseTemplateAuthorsDonateBuy preinstalled

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License Version 1.3 or any later version published by the Free Software Foundation with no Invariant Sections, no Front Cover Texts, and no Back Cover Texts. A copy of this license is found in /docs/fdl-1.3.html