Updated: March 5, 2023

Introduction

In the last two months I received at least a couple of dozens of emails regarding my work of porting coreboot to some MacBook Pro and Air models. Although such a sudden surge of interest to this remains a mystery to me, some of the emails were started with clear explanation: people were writing me because of the warning I left on top of archived repository of mmga.

Since the questions people asked were mostly the same, I noticed I just keep repeating same things over and over, so in this post, I'll try to cover this topic in full: what is the current state of coreboot on MacBooks, what is mmga and why it's archived, answer to frequently asked questions about flashing, what works, what doesn't, what devices are supported and so on. I'll try keeping this post updated in case anything changes (new board gets supported, something's fixed, etc.) until (if ever) my coreboot patches will be merged into coreboot master.

History and background

I should probably introduce myself. My name is Evgeny, I am from Russia. Since 2007, when I started as a full-stack web developer with particular interest in backend development of high-load Linux systems and administration of such systems, the focus of my interests have been swiftly shifting towards more specific or low-level areas, such as networking and protocols, system programming and drivers development, firmware and embedded stuff, reverse-engineering, etc etc.

In 2018 or so, I became interested in coreboot, as a hobby. Started as a user by flashing it on my daily-driver laptop (ThinkPad X220 at the time), I then added support for another ThinkPad I had, W530 (which wasn't a big deal, thanks to autoport and others work on similar ThinkPads), contributed some other stuff here and there and finally ported coreboot to a few MacBook models I had lying around. During that period I also wrote a couple of articles about it here, stumbled upon a neat security hole in MacBooks' stock firmware and created a tool called mmga.

mmga ("Make MacBook Great Again") is an utility (a bash script, actually) that has appeared as a byproduct of the work on porting coreboot to MacBooks and discovering a vulnerability in Apple's firmware on those MacBooks. The essence of the vulnerability lies in incorrect approaches to protecting Intel Firmware Descriptor in particular (and bugs in general).

mmga was a proof of concept on how one can exploit it and, combining with some other tricks, totally rewrite content on the SPI flash. Of course, it was aiming at flashing coreboot, so it was a tool for coreboot (and, maybe, security) enthusiasts and it's my bad that I somehow managed to market it as a ready-to-use tool to coreboot MacBooks with a few commands in linux terminal, although I never wanted nor meant that.

At least some people, indeed, managed to flash working coreboot ROMs on their machines by using mmga. And I, personally, have never bricked anything with it, it worked like a charm. But some people (probably most) ended up bricking their laptops and were forced to use external SPI flashers and other tools to recover. Worst of all, almost none of those people paid attention to the output of coreboot build, and none of them saved it for further analysis.

Don't get me wrong, I don't blame people. They found "magical" tool claiming that it can flash coreboot without even touching a screwdriver (which was true, by the way), and just... trusted it, without understanding the fragile hacks behind that "magic". Now I think I shouldn't have had it released on GitHub in the first place.

There are several reasons for that:

• mmga was, as I stated eariler, a PoC tool, and it was almost unmaintained. But it uses coreboot utils to do most of its "magic". coreboot, on the other hand, is actively developed, and it's quite possible that at some point in time some incompatibility appeared, maybe in the build process or toolchain, or some utility or payload was updated, and as a result, the ROM that was built in the end, wasn't working. It's just a hypothesis.

• mmga, obviously, doesn't have nearly enough safety checks that allow to proceed or stop the process before it's too late.

• The hack mmga does is, obviously, too fragile to blindly trust it to a script written by some random guy.

• 3 of 4 supported by mmga MacBook models have soldered RAM, which means coreboot must have SPD dumps to make it work. Despite the fact there is a table of supported RAM right there on the mmga GitHub page and a separate script that helps you identifying your RAM as supported or unsupported, some users did not pay attention to it.

So now, given all that, please, DO NOT use mmga if you just want to install coreboot on your macbook, even if it's listed as supported. Maybe one day, when my coreboot patches gets merged to the master, it'll become an official tool that helps with internal flashing process, but for that to happen it needs to be completely redesigned anyway. For now, let it just be there for the history.

Instead, you can use the same internal flashing method, but by executing commands manually, controlling every step, or flash externally.

Internal flashing

You can read the complete and comprehensive instructions here (or here, which is actually the same text, but at least it's been reviewed by coreboot maintainers).

Here I'll only briefly discuss the idea behind the method I developed while working on coreboot for sandy/ivy MacBooks generation. It's not unique, we discussed something similar on #coreboot and #libreboot IRC channels in the context of software flashing of X200/X201 ThinkPads, but on those ThinkPads you had to use "pinmod" (intel's feature allowing you to override permissions set in IFD by asserting HDA_SDO high (or GPIO33 low, on older platforms) at boot and make IFD writable for that one boot). (Check this out for an example.) One user on the channel even succeeded at this and flashed his X201.

On MacBooks, though, you don't need to mess with hardware. Apple's firmware on MacBooks of that sandy/ivy period has two flaws interesting for us:

1. They do not properly configure IFD permission bits that control access to the IFD region itself and the ME region, for whatever reason they keep them both r/w in production, and instead use SPI Protected Range Registers and set protection over the IFD region programmatically. As for the ME region, they don't protect it at all.

2. They failed at that and IFD region is not protected by PRx registers after cold boot (but becomes protected after wakeup from S3.)

So after cold boot we have ~1.6 MiB of writable space, including IFD and ME regions. Since there's me_cleaner, we can shrink the ME firmware to ~90 KiB and use the freed space for a small but working coreboot image. We also need to change SPI flash layout accordingly and move the reset vector to where our small coreboot ROM will reside. That would be the first stage of a two-stage hack.

Then we power off, wait a few seconds, power on (reboot won't work because new IFD becomes active only on cold boot), boot into some Linux distro, and flash full ROM as there are now no protections. This is stage two. Then repeat the power off/power on cycle and it's done.

In practice, this procedure is very fragile. I think, we need to create pre-compiled ROMs at least for stage 1 (could be reproducible coreboot builds) with different payloads and different configurations, something like libreboot does for its releases, otherwise there's high chance that something will go wrong and the result of stage 1 will be a brick. If/when we do this, this could be a new chance for mmga to be a reliable tool for internal flashing. Until then, either use this method with great caution or don't use it all. And in any case, backup everything and prepare tools for external flashing, it won't hurt.

External flashing commons

You have several options of external flashing, but not all of them are always available on one specific MacBook model.

ISP

In-System Programming. It's when you flash a chip that's already installed on the motherboard. It's quite popular among coreboot users, but few people actually think or know that not all boards were designed for ISP.

And here I have to say: none of the MacBook boards discussed here were designed for ISP. None of them have a diode on the SPI flash power rail, so when you're supplying power to the chip, you're also powering other components on the board through that rail, in a way that wasn't designed by vendor. And when you do that, all sorts of unexpected shit might happen, from flashing instability to board damage.

Nevertheless, on some boards it works, and below I'll show such examples. But you should keep in mind that these mainboards were not designed for ISP and it's unsafe, you do this on your own risk and I'm not responsible for any potential damages.

Now, there are two ways of performing ISP on MacBooks:

• if the flash chip package is SOIC-8, you can just use a clip, like Pomona 5250;

• if it's WSON-8, it's very hard or often impossible to use a clip, but most MacBooks have a special dedicated "debug port" that exposes some of SPI pins (at least CS, CLK, MISO and MOSI). Although it doesn't seem to be intended way of flashing BIOS (intended by Apple, I mean), it's widely adopted and even advertised, and you can find lots of different adapters sold for this purpose in online markets like Amazon or Aliexpress.

  Sometimes, these adapters can't power the flash chip good enough (because of the lack of direct connection between VCC pin of SPI flash and the debug port and the lack of the diode, because it wasn't designed for this in the first place), so it either powers it indirectly via some other power rail (which usually works unstable at best), or you have to find other tricky ways to power the chip like I shown in this article on 5,2 Air. At the time, I figured it out myself. But, as I said in the beginning, I came working on coreboot having a background of software engineer and didn't know much about the hardware side of all of it.

  It was very funny to discover just recently that some sellers even provide people with documentation of sorts, with pictures of different MacBook boards and arrows pointing to some pins you need to apply 3.3V to in order to power the flash chip, just like I did in my old article. Just look at this beauty:

  I'm showing all this to demonstrate the obvious: when you have some "adapter for flashing EFI", and in order to make it work, you also have to carefully apply 3.3V to some other tiny little pin on the board, this is just ridiculous and clearly it's not what the debug port was designed for.

  What was it designed for then? See the "Apple external flash boot feature" section below.

Soldering

Another option that's always there is soldering. It's very easy with SOIC-8 chips, not as easy but still not a rocket science with WSON-8 chips, although it may require additional tools.

Apple external flash boot feature

This text was written by swiftgeek, another coreboot contributor (and libreboot maintainer in the past), hardware enthusiast and researcher, a person much more experienced with hardware than me.

Practical application of this feature is WIP.

While MacBooks do NOT support ISP flashing (no diode on SPI flash rail), they DO support booting from external flash, similarly to MSI desktop motherboards, with additional GPIO for override.

820-3209 example (IVB + PPT) here (adapter pictures and pinout).

J5100 exposes SPI lines:

• SPI_ALT_CS_L
• SPI_ALT_MISO
• SPI_ALT_MOSI
• SPI_ALT_CLK

J5100 also exposes 3v3/5V rails:

• PP3V3_S5_LPCPLUS
• PP5V_S0_LPCPLUS

J5100 also exposes a toggle to disable onboard flash and use external flash instead (and override from target's software once booted):

• SPIROM_USE_MLB / PCH GPIO57

To boot from external flash (already flashed with known good image for that flash part¹):

• Connect VCC of external flash to 3v3 (TODO: how should it be provided? PP3V3_S5_LPCPLUS? Is that good enough for Intel ME?)
• Hook up J5100 SPI lines to external flash
• Pull /WP and /HOLD of external flash high to make it operational, with eg. 100kΩ resistors.
• Pull SPIROM_USE_MLB low with eg. 1kΩ resistor (not too low so GPIO57 can override it, once booted from external flash)
• (Optional) connect SPIROM_USE_MLB to inverter (NOT gate) and connect output of gate to /HOLD of external flash

Once booted, to reflash onboard flash:

• if NOT gate was not used, pull /HOLD of external flash with 1kΩ resistor (perhaps by using a jumper/switch on breadboard/protoboard) to disable external flash.

• Configure GPIO57 to output 1 - high state (using eg. adurbin's iotools), which achieve following:

  • disable external flash (only if NOT gate is used)
  • enable onboard flash

• Run flashrom -p internal as usual.

Potential issues:

• RTC NVRAM vs Intel ME state
• ¹ Flash part needs to exist in VSCC table

Alternative use cases:

• Upgrading capacity of boot flash, eg. from 8 MiB (onboard) to 16 MiB (max supported) without reworking target board - by simply plugging in new module.

• Dual BIOS solution, using external/internal flash chips flash A/B.

  • Selecting between A/B can happen based on reset counter (LPCPLUS_RESET_L), and could be implemented with cheap low pin count MCU, and could be backed by EEPROM or supercap backed SRAM.

  • Configuring MCU (like counter threshold, or which flash should be fallback one) could happen over SPI bus, using unimplemented commands (which are to be ignored by 25xx flash)

SPI programmer recommendations

Don't use CH341A. Don't buy it, don't use it, throw it away and forget about it. Especially the black one, but this stands for any CH341A variant. If you can't flash something with CH341A, try using saner flasher first before reporting anything.

If you have a Raspberry Pi, use that instead. It's better than CH341A.

FTDI FT232H (also FT2232H, FT4232H) is very good. FT2232H mini module is also very small and handy. These are not as cheap though.

stm32-vserprog is cheap and nice too.

Devices

To the best of my knowledge, this is a comprehensive list of MacBook models supported in coreboot, either merged to master or as WIP patches on Gerrit:

• MacBook Air 4,2 (A1369), 13'', Mid 2011, board number 820-3023

• MacBook Air 5,2 (A1466), 13'', Mid 2012, board number 820-3209

• MacBook Pro 8,1 (A1278), 13'', Early 2011, board number 820-2936

• MacBook Pro 10,1 (A1398), 15'' Retina Display, Mid 2012, Early 2013, board number 820-3332

• MacBook2,1: some ancient model, been supported for ages and not by me, and that's all I know about it. It's out of the scope of this article.

MacBook Air 4,2

Model number: A1369
Board number: 820-3023
Marketing name: MacBook Air 13'' Mid 2011

This one wasn't actually tested nor ported by me, but I added EC support here and fixed some bugs, and later received a positive response from a person who owns and tested it.

It's merged to master, not because it's well supported or at least supported better than other ones, but because in the past coreboot had quite low standards for accepting patches, as opposed to current times, and you could just push autoported stuff to the master. Just like that. (It didn't even had working display, but know cared, it was enough for news outlets.)

Status

I can't really tell what's working and what's not on this one because I don't have it. But given the similarity between the 4,2 and 5,2, I'd lean towards the list for 5,2, which you can find below.

RAM

RAM is soldered on this board. According to schematics, there may be 6 different variants (page 5):

RAM variants support
🚫 2g_hynix
🚫 4g_hynix
🚫 2g_samsung
✅ 4g_samsung
🚫 2g_micron
🚫 4g_elpida

The spd.bin file in macbookair4_2's port tree actually covers only the 4g_samsung option.

See here how to check your RAM or help supporting it.

Flashing

Same story, I don't have the board, so I can't say much for sure. What I can say, though:

• Internal flashing works.

• External boot should work, but wasn't tested yet.

• SPI flash is in WSON-8 package and is located on the other side of the board (similar to MacBook Air 5,2). It's possible to find an adapter for the J5100 debug port that exposes SPI pins, but I can't recommend any specific one. Here's the picture of the debug port:

  The photo provided by one of users interested in corebooting his MBA

  I have a report from a user confirming that flashrom sees the chip and they can at least dump flash content reliably (or so it seems) by using the adapter they bought online:

  There are still some issues with writing though, probably caused by bad wiring or just CH341A. I'll update when they figure that out.

Docs

820-3023-a.brd MacBook Air 4,2 boardview 508.36 KiB

MacBook Air 5,2

Model number: A1466
Board number: 820-3209
Marketing name: MacBook Air 13'' Mid 2012

Patch in Gerrit: #33151

Status

Tested and works:

• Linux 4.9, Linux 5.10
• Wi-Fi
• S3 suspend and resume
• Both USB ports
• Trackpad
• Graphics (libgfxinit)
• me_cleaner
• Soft Temp Intel ME Disable Mode
• Speakers
• ACPI support for battery, AC, lid (lid wakeup also works)
• SD card reader
• Camera
• Mic
• usbdebug (USB port on the left side)

Doesn't work:

• Thunderbolt

Known issues:

• Bad sound in headphones

RAM

RAM is soldered on this board. According to schematics, there may be 6 (in reality, at least 7¹, probably more) different variants (page 5):

RAM variants support
✅ 4g_hynix
✅ 4g_micron
🚫 8g_hynix
✅ 4g_samsung
🚫 8g_samsung
✅ 4g_elpida
✅ 8g_elpida

See here how to check your RAM or help supporting it.

---

¹ The "J13 BOM GROUPS" table on page 5 of the schematics doesn't mention following configuration that's been found in the wild:

RAMCFG0:H,RAMCFG1:L,RAMCFG2:L,RAMCFG3:L.

It's a board with two 2 GiB DDR3 modules, 4 GiB in total.

dmidecode, launched under stock firmware, detects manufacturer 0x802C, which means Micron.

There's a table named "DRAM CFG CHART" at the bottom of page 5, according to which RAMCFG0=1,RAMCFG1=0 is indeed Micron. Though it's the only place in the whole document mentioning Micron.

Flashing

• Internal flashing works.

• External boot should work, but wasn't tested yet.

• Unsafe ISP way. SPI flash is in WSON-8 package and is located on the other side of the board. It's possible to find an adapter for the J5100 debug port that exposes SPI pins. I personally have the one, see this post, though it's not an advertisement or anything like that.

  Location of the J5100:

  My adapter always failed to power the flash chip reliably so instead of using its VCC pin, I found the nearest pin on the power rail to SPI chip's VCC on the board and did this:

  This way it always worked reliable for me with RPi 3 and FT2232H mini module as programmers. One more reason to not use CH341A: it's very slow compared to them, and when flashing this way, you need to hold your hand still in one position during whole process.

Docs

820-3209-a.brd MacBook Air 5,2 boardview 532.52 KiB

MacBook Pro 8,1

Model number: A1278
Board number: 820-2936
Marketing name: MacBook Pro 13'' Early 2011

Patch in Gerrit: #33151

Status

Tested and works:

• Both DIMMs
• Graphics (libgfxinit)
• Linux 4.15, Linux 5.10
• Wi-Fi
• Bluetooth
• ACPI support for lid, battery and AC
• S3 suspend and resume
• Keyboard and touchpad
• USB 2.0 ports
• SD card reader
• Speakers and headphones
• Microphone
• Camera
• CD-ROM
• Ethernet

Doesn't work:

• Thunderbolt

Not tested:

• FireWire
• usbdebug

Flashing

• Internal flashing works.

• External boot should work, but wasn't tested yet.

• SPI flash is in SOIC-8 package:

• Since it's SOIC-8, it's quite easy to desolder the chip, flash it while it's not installed on the board and solder it back.

  It's better than the next paragraph.

• ISP doesn't work. Better don't even bother.

  Disclaimer: what I'm describing below is dangerous, utterly wrong and there's high probability that you will damage the board.

  ---

  If you're reckless enough (like me), you might get a chance of flashing it via a clip if you attach it without supplying external power to the VCC pin, then power up the machine and put it to S3. Be aware that Intel ME is still active in S3, and this adventure might not end up very well.

  Note that there are tiny little capacitor and resistor very close to the VCC pin of SPI flash, which you can break easily without even noticing, when attaching a clip. Modify your clip like this to avoid that (cut a piece of plastic in that corner):

  Even if you're lucky, didn't break or short anything, and even somehow managed to flash it and ME didn't mess with you – you only had one shot.

  If you reboot and it doesn't work, game's over, and let me repeat: ISP doesn't work on this board.

Docs

k90i-820-2936_07.brd MacBook Pro 8,1 boardview 551.52 KiB

MacBook Pro 10,1

Model number: A1398
Board number: 820-3332
Marketing names:

• MacBook Pro 15'' Retina Mid 2012
• MacBook Pro 15'' Retina Early 2013

Patch in Gerrit: #32673
Also relevant to this board: #32719

Status

Tested and works:

• Graphics (both libgfxinit and VGA ROM)
• Integrated GPU
• Discrete GPU
• Linux 4.9, Linux 5.8, Linux 5.15
• Wi-Fi
• Bluetooth
• Both USB ports
• Trackpad
• me_cleaner
• Soft Temp Intel ME Disable Mode
• Integrated/Discrete graphics switch via CMOS
• Camera
• Microphone
• SD card reader
• Speaker
• usbdebug (the USB port on the right side)
• Backlight control via gmux (/sys/class/backlight/gmux_backlight), worked out of box on Ubuntu 20.04

Doesn't work:

• Thunderbolt

Untested:

• FireWire

RAM

RAM is soldered, the laptop comes with 15 different memory module configurations (page 5 of schematics):

RAM variants support
🚫 4g_hynix_1600s
🚫 1g_samsung_1600
🚫 4g_samsung_1600s
🚫 1g_hynix_1600
🚫 4g_elpida_1600s
🚫 2g_samsung_1600
🚫 2g_samsung_1333
✅ 2g_hynix_1600
🚫 4g_samsung_1600
✅ 4g_hynix_1600
🚫 2g_elpida_1600s
🚫 2g_elpida_1600
🚫 4g_elpida_1600
🚫 2g_samsung_1600s
🚫 2g_hynix_1600s

See here how to check your RAM or help supporting it.

GPU

It is known that stock firmware forces discrete GPU when you try to boot anything but macOS. People suffered: to force Intel GPU, hacks like these were required to be added to grub config:

outb 0x7c2 1
outb 0x7d4 0x28
outb 0x7c2 2
outb 0x7d4 0x10
outb 0x7c2 2
outb 0x7d4 0x40

coreboot removes the need of all this nonsense and Just Works™, as Steve Jobs bequeathed.

By default, it enables integrated GPU. If you want to use discrete GPU, you need to extract VGA ROM for the NVIDIA GPU from stock firmware dump, add it to CBFS and change corresponding CMOS option. How to extract VGA ROM and correctly add it to CBFS is probably out of the scope of this text, at least now. If anybody will ever need that, I'll describe the process.

Flashing

• Internal flashing works.

• External boot should work, but wasn't tested yet.

• ISP works. SPI flash is in SOIC-8 package. Do not forget to detach the battery connector.

• Soldering is also easy and handy.

Docs

820-3332-a.brd MacBook Pro 10,1 boardview 937.48 KiB

Payloads

Tianocore

I briefly tested it on MBP 10,1 and MBA 5,2 and it worked. Not much else I can say.

SeaBIOS

Updated: March 5, 2023: SeaBIOS is tested on MBA 5,2, the keyboard works!

* * * * *

Back in 2018 or 2019, the built-in keyboard didn't work in SeaBIOS. The reason was that on these MacBooks the keyboard is connected via the USB bus, but they use non-standard packet sizes (10 bytes for packet instead of 8 bytes, if I recall correctly). At that time, I manually patched SeaBIOS to make it work. I reported the issue on the SeaBIOS mailing list, and later in the release notes of some SeaBIOS release I saw something probably related.

What's the current status, I don't know. Maybe they fixed it, maybe not. It needs testing and I don't have time for it just now. As I promised in the beginning, I'll keep this page updated when new information arrives.

GRUB

The keyboard works in GRUB, but GRUB throws some errors on the screen, something about unexpected keycodes or something. Must be the same non-standard USB packet size issue, but at least, the keyboard works.

Tools

Here I list some of the tools you might find useful if you're using coreboot on a MacBook or just planning to do it.

smctool

smctool is a small utility to directly query SMC keys. Some information about SMC keys you can find, for example, here.

get_macbook_ramcfg

If your device has soldered RAM, get_macbook_ramcfg helps you to determine whether your RAM is supported or not. It requires inteltool (util/inteltool from coreboot repository). See README for more info.

inteltool

inteltool is a coreboot utility to dump some intel chipset registers, MSRs and other stuff.

Help supporting your soldered RAM

If your device is supported but its RAM isn't, you can help supporting it by using inteltool!

• build inteltool (on Linux, of course) and install dmidecode
• run three commands:
  • sudo inteltool -g
  • sudo inteltool -m
  • sudo dmidecode --type 17
• email me an output of those commands together with information about your hardware.

it2gpio

A script that reads inteltool -g output from stdin and dumps all GPIO values. I created it to manually compare GPIO values from the dump with values from Apple docs.

FAQ

I have a MacBook that's listed as supported but get_macbook_ramcfg script detects my RAM as not supported, what should I do/how can I help?

See here.

I got MacBook Air 4,1 or 5,1, it's almost the same as 4,2 or 5,2, will it work if I flash ROMs for those boards?

It's completely different boards and it will not work.

I have some other MacBook model that's not listed here, can you support it or help me supporting it?

Depends. Contact me.

Will macOS work after I flash coreboot?

No. At least not natively. It should be possible to run it like a hackintosh though, using Tianocore as coreboot payload and OpenCore or Clover (or what do people use for this purpose nowadays?) to boot macOS.

Will Windows work?

Unknown. Probably yes, with same issues as on similar other coreboot-supported boards, but it's not tested. Anyway, why would somebody install a free firmware and then use spy/bloatware like Windows or macOS?

How can I support you?

BTC: 3HG43KgahGNZpfvVycMi1751TatRedHZCq

BCH: qz9pwad2u9usxx03c0k7wscg6ns85l2t6qdaqz7cfc

ETH (ERC20): 0x767D101CC774F5507A80bab67CDD70c29eb1B2F1

XMR: 49vQyEvpJVFBPf7BWg9A2gM7K6gd6jHJviTzSavJHKevj7AkauEvdqDjFnGjmusCxM5NPD8aWBvCP5ehfiz9Dq9wVLY7YaC

TRX (TRC20): TCL5K1AY1Y4mc9yx2Rpferz9dck89MJD8n

BNB (BSC20): 0x767D101CC774F5507A80bab67CDD70c29eb1B2F1

Updates

March 5, 2023

• Added information about the 4g_micron RAM configuration found on MBA 5,2, added support in coreboot, updated get_macbook_ramcfg script accordingly. Thanks to mrlager for providing the logs.

• Updated the Help supporting your soldered RAM section (added dmidecode --type 17 output request).

• Updated info about the state of keyboard in SeaBIOS, thanks to mrlager for testing.