Laptops

Why laptops are difficult

Laptops, notebooks and netbooks are difficult to support and we recommend to use the vendor flashing utility. The embedded controller (EC) in these machines often interacts badly with flashing, either by blocking all read/write access to the flash chip or by crashing (it may power off the machine or mess with the battery or cause system instability).

We have the goal of supporting every machine out there with flashrom, but ECs are particularly difficult besides blocking access and crashing:

• Almost all ECs do not have public datasheets with programming information.
• Even if the programming information for an EC is public, the errata (often needed to use the EC for flashing) are not.
• Even if you have the datasheets with programming information (under NDA or by convincing the EC vendor to release them), the following problems remain:
  • flashrom has to detect/probe the EC. For this, it writes a magic byte sequence to a magic port. The bad news is that a laptop vendor can customize the magic sequence and the magic port and the response to that, so even if you try all magic sequences mentioned in the datasheet on all magic ports mentioned in the datasheet, it will either not react (because the laptop vendor came up with its own secret magic sequence/port or because the laptop vendor decided to disable all detection support) or it will respond with a non-default ID which is not present in any table. If you are really extremely lucky, the EC will react to the probing sequence mentioned in the datasheet and respond with the ID mentioned in the datasheet.
  • Most ECs support 3-5 different interfaces to the flash chip. Depending on the software running on the EC, none, some or all of them can be disabled. So if you want to support a given embedded controller with reasonable reliability, you have to write code for all flash interfaces (usually vastly different from each other).
  • During a flash erase/read/write, flashrom competes with the EC for flash access. The EC usually executes its software directly from flash (no RAM involved) and starving the EC instruction decoder may crash the EC. If you erase the part of the flash chip where the EC fetches its instructions from, the EC will execute garbage and crash/misbehave. When (not if, it always happens) the flash chip is in ID mode during flash probing, the EC will mistake the ID data for instructions and execute them, resulting in a crash.
  • You have to find a way to let the EC software run for some time without requiring flash access. This can be achieved by writing a loop (not really a loop, but this is just to illustrate the point) to EC-internal tiny RAM and then jumping there. Only during that time you can access the flash chip reliably without side effects.
  • After flashing, you have to reset the EC so that it can resume running normally. This is not optional because the EC controls battery charging (among others) and you want that to work.

Adding support for laptops

That said, adding support for an EC is doable. Here is a cheat sheet on what to do.

• Find out which flash chip you have by physical inspection of the board (or by looking at the internal docs of the manufacturer or the repair manual).
• Find out the controller where the flash chip is attached to. Can be the EC (likely), SuperI/O (somewhat likely), Southbridge (pretty unlikely, if it were, you wouldn't be reading this). This is a job done by physical inspection of the board (or by looking at the internal docs of the manufacturer which sometimes only the ODM and not even the laptop vendor has).
• Tell the flashrom list that you plan to work on your EC, mention the exact EC model (and laptop model) and ask if someone has public docs for the EC, knows how to get them under NDA or has vendor contacts at the EC vendor. With some luck, you might even get docs (some vendors are more friendly than others).
• Get hold of a BIOS image for your laptop (flashrom dump in force mode won't work reliably here). Locate the EC code in the BIOS image. The EC often is 8051 compatible or has an architecture with similar limitations. The EC code will be uncompressed in flash. Download BIOS images for other laptops with the same EC and try to compare the EC code. It may be 100% vanilla code directly from the EC manufacturer (which makes your task rather easy) or a heavily customized variant of the original code (bad, because you have to analyze it).
• Cross-check the EC code with the EC docs to find out which interfaces for detecting the EC and which interfaces for flashing are enabled and working.
• The above two steps can be skipped if you get that information from the laptop vendor.
• Make sure your flash chip is removable in case something goes wrong. If it is not removable, look for an in-system-programming header on the board and check if it is supported by flashrom (or your hardware programmer of choice). If there is no header and the chip is soldered, desolder it and solder a socket in place.
• Dump the old firmware via the programming header or via reading the chip in an external programmer and store it safely (backup on a readonly medium like CD-ROM). It contains your laptop serial number, your MAC address, and sometimes your Windows preactivation keys.
• (optional) Disconnect the battery. You don't know how the EC behaves if it crashes and batteries are expensive and prone to unwanted reactions.
• Start implementing and testing EC detection code. We recommend to do this either as external programmer driver init code (and have the code return 1 to make sure flashrom aborts after init) or in a standalone program (this helps you keep an overview).
• Mail your code to the flashrom mailing list. Even at this stage, the code is useful because it can help flashrom detect that it runs on a laptop and issue a warning to the user.
• Ask if anyone else is working on a similar EC or if anyone else wants to help you. (We've seen a few instances of duplicated effort and this is frustrating for all parties.)
• Start implementing flasher support for your EC. The best way to do this is an external programmer driver.
• Mail your code to the flashrom mailing list even if it does not work or is unfinished. Please. We mean it. Too many developers lost code because their laptop (including the USB disk with the backup) was stolen or the harddisk died. Having your code on the list acts as backup and allows others to contribute.
• Complete the code and post a patch to the list. Enjoy being celebrated as a hero.

Public documentation

Flashing memory for Renesas H8 controllers:

• http://documentation.renesas.com/eng/products/mpumcu/apn/reg05b0027_h8sap.pdf
• http://documentation.renesas.com/eng/products/mpumcu/apn/reg05b0022_mcuap.pdf

Flashing memory for ITE 8051 controllers:

Flashing memory for Ene controllers:

KB38xx/KB39xx