Zerocat Chipflasher  v0.4.10-182-333b622f
Flash free firmware to BIOS chips, kick the Management Engine.
README

About

When it comes to flash a coreboot or libreboot machine, the Zerocat Chipflasher is a very special tool:

  • it runs with free-software
  • it comes with free documentation
  • it uses a free-design microcontroller
  • its board layout is free-design hardware

...and you can solder your own device, it is a do-it-yourself project!

The projects mentioned above provide free firmware replacements, which usually require to externally flash onboard SPI flash chips of selected targets. Machines like the Lenovo ThinkPad X200 or X220 Notebook are high quality products which are well supported.

These projects aim to support user freedom, but often suffer to be dependent on external flashers which are not compatible in that point. The Zerocat Chipflasher is meant to fill that gap.

Project’s Naming Convention

The project’s internal name simply is chipflasher.
It is hosted under the umbrella of the Zerocat Label.
In public, please use the name Zerocat Chipflasher.

Basically, the project comes with three subprojects, which are all part of just one documentation:

  • The electronic hardware,
  • its firmware kick,
  • and a host program called connect, as kick needs someone to talk to.

Please note that both programs, kick and connect, have their main functions called main(), so please don’t get confused.

Please note that there are two different change log files, one for hardware, one for software: Board Version History and Version History.

Internet Resources

Websites

The webpage of the Zerocat Chipflasher is a part of the Zerocat Website.

Shop

We offer products and services in Berlin (Germany), as like:

  • free-design devices and microcontrollers
  • coreboot and libreboot flash services
  • pre-flashed laptops and desktop boards
  • workshops and more...

Please check shop information, portfolio and prices on the Zerocat Website.

Email

Please send your questions, feedback, bug reports or product requests to zerocat@posteo.de. A public OpenPGP key is available for mail encryption.

Mailing List

The Zerocat Label is using encrypted email for its mailing list; currently, we don’t have a general address for it. If you want to contact the ML, please write an email to zerocat@posteo.de and your mail will be forwarded.

Git Repository

  • Zerocat Chipflasher Repository
      git://zerocat.org/zerocat/projects/chipflasher
    

Prerequisites

Recommended Hardware

As the chipflasher is operated over a serial port, we recommend to use a host computer with RS232 port, running with libreboot or blobless coreboot BIOS. We are able to provide you with the ZC-X60 or ZC-T400, for instance.

GNU/Linux OS and Requirements

We assume that you are running a GNU/Linux-libre Operating System like Trisquel, for example. Your system should have access to an RS232 serial port.

Essential tools that allow building the documentation and programs should be installed first, see Software Tools for details.

Clone Repository

As a next step, please open a terminal, create a zerocat project folder and clone the public git repository onto your harddrive:

$ mkdir -p ~/zerocat/projects/
$ cd ~/zerocat/projects/
$ git clone git://zerocat.org/zerocat/projects/chipflasher

Now you should have a folder ~/zerocat/projects/ with subfolder chipflasher/.

Version Checkout

Instead of using the default tip of branch master which could leave you with inconsistent sources, you should find the most recent version tag and perform a git checkout:

$ cd ~/zerocat/projects/chipflasher/
$ git describe --abbrev=0

This will give you the most recent version tag <chipflasher-version-tag>.

$ git checkout <chipflasher-version-tag>
Note
If you want to match the version of your specific physical device, lookup the version tag on its front-panel sticker. You may use $ git tag to get an overview of available tags and see if one matches. Example: In case your device carries the info 'Version: board-v1.2.0', please perform a corresponding checkout like so: $ git checkout board-v1.2.0
If you want to try a different version tag with your specific device, note that it is up to you to verify that your hardware is still compatible with the sources. Version History and Board Version History will hopefully help you to figure that out.
For instance, care has been taken to keep the software compatible with the hardware of tag board-edition-1, so please feel free to upgrade your firmware in case you own the RYF-certified chipflasher device “board-edition-1”.

Generate the Chipflasher Documentation

Change into your local zerocat/projects/chipflasher/doc folder and type make:

$ cd ~/zerocat/projects/chipflasher/doc/
$ make

This will use doxygen to generate the documentation in folder generated-documentation/html. Please open the index.html with your favorite browser. You will find a reference to this README on that page as well as on the navigation bar under Related Pages. In case you prefer to read documentation source files, make sure to start with frontpage.md instead of the generated index.html.

Get Started

You should now be ready to proceed with How To Use.

Licenses

The files that ship with the Zerocat Chipflasher fall into five categories:

  1. hardware design sources (files from gEDA-gschem, PCB-Designer, OpenSCAD, LibreCAD, etc.)
  2. code sources (text files with syntax of C, ASM, Makefile, Propeller-Load Configuration, Doxyfile, bash, scheme, etc.)
  3. documentation files (markdown, simple text)
  4. graphics and photos (files made with Scribus, Inkscape, Gimp, etc.)
  5. logo files (files made with Scribus, Inkscape, Gimp, etc.)

In general, the following rules apply:

  • If not otherwise stated within this project, all files are copyrighted:
      Copyright (C) 2015–2020  Kai Mertens <kmx@posteo.net>
    
  • A license header is placed within the files if applicable.
  • "1. hardware design sources" and "2. code sources" are licensed under the GNU GPLv3 or later. The license itself is shipped with COPYING.
  • "3. documentation files" are licensed under GNU FDL 1.3 or later, without invariant sections, front-cover texts or back-cover texts. This license is shipped with COPYING-DOCUMENTATION.
  • "4. graphics and photos" are released under the CC BY-SA 4.0 International Public License. The URL to the license text is shipped with COPYING-GRAPHICS.
  • "5. logo files" are released under the Zerocat Logo License. This license is shipped with COPYING-LOGO.

Development

The development started by playing around with a ThinkPad X60 motherboard in 2015. Please note that the project itself is developed on a liberated ThinkPad X60 with a preflashed libreboot image on it, thus forming a quite complete free software workbench.

In March 2016, a first bunch of Thinkpad X200 laptops with Macronix and Winbond chips have been flashed successfully. Since then, the chipflasher has been used for more targets, and its adaption of code, board circuits and documentation went straight-forward into the public git repository. Supported Devices gives you a full list of tested targets.

The Team

The project had been initiated by Kai Mertens, who soon received valuable help from other developers as like Tomás Zerolo, Holger Kienle and Ricardo Wurmus in 2017 and 2018. Kevin Keijzer from www.librepractice.org spent a bunch of testboards, was testing the chipflasher, and was liberally sharing his coreboot experiences with the team. Since the project had successfully passed the FSF’s Respect-Your-Freedom Certification Program in May 2018, the project is maintained by Kai Mertens only. Pioneer customers are invited to share their experiences.

First Sale

A number of ten (10) RYF-certified, signed devices started to be online for sale in May 2018. Since then, a chipflasher was sold every two months, in average. The sale of the last item in stock took place in January 2020. A total sum of 2990 Euros has been collected in this time span, which can be regarded as a coverage of development expenses, roughly.

Your Support

You can help to improve and support the chipflasher in different situations:

  • Buy one and provide feedback.
  • Build your own and tell us how to improve the documentation.
  • Provide your coreboot compatible device for testing purposes.
  • Your donations are very welcome! Please see www.zerocat.org/bank-account.html for bank account details.
  • Last but not least: Spread the word, tell people about it!

Free System Distribution Guidelines (GNU FSDG)

We check the Zerocat Chipflasher distribution according to the GNU FSDG.
If you discover mistakes, please report to zerocat@posteo.de and we will fix them.