Zerocat Chipflasher: Kick2
– The second firmware, and its interface to flashrom.

Copyright (C) 2020, 2021, 2022 Kai Mertens kmx@posteo.net

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 the license is included in the section entitled "GNU Free Documentation License".

NEWS

2022/06/29

• Operation of the chipflasher per flashrom utility is now supported!

2022/06/11

• Maintain Makefile compatibility with dash, as used on Trisquel.
• Increase POWERUP_SPI to 30ms, as chip SST25VF016B needs more time.
• Adapt Makefiles for buggy GNU Make < 4.3: Finalize commands within $(shell) functions with semicolon.
• Fix database match report if no match occurs.
• Use a second command set register, filter chip specific commands.
• Support chip AT25DF/26DF641, as found on ThinkPad X220.
• Add and fix support for volatile chips, as found on ThinkPad T60 models. Support Auto Address Increment Word Program. Update main documentation.
• Control SPI Bus Power with new menu option key.

2022/05/18

• Add pauses on SPI Bus, interactively, to support chipflasher PCB with poor cooling, targeting a ThinkPad T60.
• Address verification error upon register write action: Add delay.
• Chipspec maintenance: Remove BP3 of Register 0 for MX25L1605D/06E.

2022/05/10

• Update documentation as of: Zerocat Project Template v0.0.19
• Refine headers and license notices within Spin code files.
• Fix GNU GPL license headers.
• Drop collected, project-wide authorship and copyright. Use individual copyright statements instead.
• Fix position of license notices.

2022/04/19

• Apply fixes in accordance to: Zerocat Project Template v0.0.17

2022/15/01

• Improve Makefiles, sort utility checks, rename macros consistently.

• Crosslink documentations.

• Upgrade documentation system according to: Zerocat Project Template v0.0.12

2021/12/26

• Finalize the firmware review.

  Based on tests and experiences made with kick2, firmware kick has greatly been improved and even advanced beyond kick2’s capabilities.

  However, firmware kick2 is a fully operational alternative to firmware kick. It is coded in Spin/PASM and offers plenty of available RAM to ease development of new features. In contrast to kick, access to lockbits and Macronix’ SOTP regions is not yet implemented.

2021/11/27

• Chip readouts better match generated files by srec_cat, such that diff -y can be used to verify data, manually. See ../../firmware2/doc/TODO.md.

• Compiler warning for connect has been fixed.

• Error detection within connect has been fixed.

• The documentation system has been updated according to: Zerocat Project Template v0.0.9

• Manifest files carry guix channel information.

• File ../../firmware2/doc/TODO.md has been updated.

• Firmware kick2 allows to select the type of End-of-Write-Cycle detection (WIP check), e.g.: polling (default) or timeout

  This eases chip erase and chip write options on Lenovo T530 and W530 laptop targets.

• Chip erase and write options are now implemented.

• Some minor bugs have been fixed.

2021/10/01

• Firmware kick2 comes with improved status report, configuration options and more menu options for the connect utility.

• The field of read operations should now be complete, using real chip data. Results are fine, but execution speed is slow.

• The field of write/erase operations is missing only one, last entry.

• The documentation is build via simple Makefile, using Zerocat Project Template rather than Doxygen.

• File ../../firmware2/doc/TODO.md has been updated with some next tasks.

• File ../../firmware2/util/manifest.scm has been renamed to ../../firmware2/guix/manifest.scm.

2021/06/28

Interface configuration has been put under user’s control, via make -C ../../firmware2/src/ <config-target>. Per default, the kick2 firmware has no interface enabled, just the bare program skeleton will be compiled and documented.

2021/06/27

Firmware kick2 now comes with improved read operations for the connect utility, however still using fake data. File ../../firmware2/doc/TODO.md lists related things that should be addressed next.

• Screen output is properly structured, consistently.
• Hexdump: Still fixed to 16 bytes payload.
• Motorola-S: Full record length of 255 character pairs is supported.
• Numbered screen prompts reflect the level of input same as LED D1.
• Dialogues are processing the cancel action upon “q” keystroke.
• Numbers are shown with base 10 or 16, whatever is most convenient.
• Optional pausing between block reads allows device to cool down.
• Data blocks (bytes, pages, blocks, whole chip) are read in single or batch mode.

2021/04/29

• Firmware kick2 now displays the correct project number.
• Makefiles are more readable, robust and secure.
• The SRecord Program Collection is available as a GNU Guix package.

2021/04/04

• Command guix environment --pure is now supported by two manifest files, ../../host/util/manifest.scm and ../../firmware2/util/manifest.scm. However, SRecord Program Collection still needs to be compiled manually.

2021/03/31

• Memorandum of Understanding 2019-06-065 is now signed by both parties, Bob Goudriaan, representing the NLnet Foundation, and Kai Mertens.

2020/11/14

• File ../../firmware2/doc/Software-Bill-of-Material.md is now part of the documentation.
• The project should now be ready to be run on GNU Guix System.
• Version v0.4.10 of branch master merges into the sources.

2020/10/09

• The documentation supports handheld devices.
• File ../../firmware2/start/Makefile now offers a reset target, which can be used to quit the serprog object and to restart the device.

2020/10/07

• Documentation Build is supported via Makefile
• Flashrom’s “Serial Flasher Protocol Specification V1” has been set up, first cut
• Transmission kick2->connect works fine (with random data)
• Both, kick2.binary as well as kick2.eeprom load files are available
• The kick2 top object now comes with flexible configuration options
• Program Status is displayed at Status LED D1
• Error Codes are displayed at Status LED D2
• Serial outgoing communication is display at Status LED D3
• The ledstat Spin Object has been reviewed and improved
• Slow Spin Code has been replaced by fast PASM Code (linehexdump, linemotsbin)
• Line Data is fully buffered, up to full length of a Motorola-S Record
• Communication Object pccom has been set up
• Adapted Parallax Full-Duplex Serial Driver is in use
• Payload Size can be modified fromout the menu
• $FF Data Handling can be modified fromout the menu
• The menu has been set up as a Spin Object, it offers a handshake method
• Line Specifications have been set up as a Spin Object
• Chip Specifications have been set up as a Spin Object
• Spin top object kick2 has been set up
• Documentation Files are downloaded via Makefile

January 2020 (as of)

Branch ‘flashrom-interface’ is dedicated to enrich the chipflasher with an interface for the widely used flashrom utility.

Flashrom carries its own protocol specification for devices attached to the serial port of your computer. See Documentation/serprog-protocol.txt within the flashrom source tree for detailed information.

Coding the interface goes along with the chipflasher’s firmware review. This work is done on branch firmware2-wip, and – as a side effect – will offer results on branches flashrom-interface and firmware1-wip as well.

The final results will merge into branch master.

README

Project Goal

The Chipflasher’s second firmware kick2 is going to be enriched by an interface for the external flashrom utility: Zerocat Chipflasher Flashrom Interface

While maintaining the menu interface for the project’s own connect utility on branch firmware2-wip, the integration of an interface for flashrom will be set up on branch flashrom-interface.

Code Review

The firmware review process is done by transforming the original firmware written in C, into Spin code. Spin code is loaded into controller’s RAM, and then interpreted by one cog who is running the on-chip Spin Interpreter. As a result, the controller’s RAM is used in an efficient way, but execution speed is slow. In order to speed up important loops, parts of the Spin code will be replaced by PASM code later on, which is then executed by additional cogs fromout their faster cog-RAM. As a proof of concept, this has been done for Spin objects txline_HEXD and txline_SREC. In the end, the overall execution speed will hopefully reach that of the fast PASM code compiled from C sources.

Coding in Spin/PASM gives us some main benefits:

• frugal software requirements
• high source code readability
• efficient RAM usage, space for advanced features
• objects with hidden data, public and private methods
• high execution speed where essential
• lean documentation output
• flexibility through replacable Spin/PASM objects

Hardware Requirements

Requirements are frugal:

• Chipflasher

  • Device board-edition-1 (PCB board-v1.1.0), RYF-certified
  • or Device with upgraded PCB
  • or Device with handmade circuit board

• PC or Laptop

  • two USB slots for power
  • one RS232 serial port, /dev/ttyS0 or alike, for data
  • recommended: free/libre operating system
  • recommended: free/libre firmware like libreboot or coreboot

Paths

All paths within this document are relative in respect to the original location of this source file, which is located in the project’s firmware2/doc/ folder, e.g.: ../../firmware2/doc/

Prerequisites

This is additional software and documentation.

It is assumed, that you have started with the project’s main README file ../../doc/README.md to learn how to set up requirements and how to generate the project’s root documentation ../../doc/index.html. Your current directory is ../../doc/.

Now change into this project’s second documentation folder ../../firmware2/doc/:

    cd ../firmware2/doc/

P8X32A Documents and Application Notes

The Propeller Chip is well documented, let’s take a bunch of documents as a common starting point. See ../../firmware2/doc/Makefile for targets P1-Documents and P1-Application-Notes. They will help us to get files downloaded, e.g.:

    make -C ../../firmware2/doc P1-Documents

Interfaces

Interfacing the Connect Utility

This project comes with its own PC utility called connect, which is supported via the menu Spin/PASM object:

Interfacing the Flashrom Utility

The flashrom utility comes with its own protocol specification, made for external flasher devices attached to the serial port of your computer. See Documentation/serprog-protocol.txt within the flashrom source tree. This protocol is/will be supported via the serprog Spin/PASM object. Once the serprog object is more elaborated, we will switch the default interface.

Interfacing a Terminal

In case flashrom or connect are not available, you might still start a propeller terminal and use it with a terminal on the host side. However, features are heavily stripped, you cannot do something real. Again, use the menu Spin/PASM object.

Interface Configuration

The kick2 top object might be configured to run one of the following interfaces:

1. Connect
2. Flashrom (Default)
3. Propeller Terminal
4. No Interface

The configuration will not only affect the compiled output, but the generated documentation as well.

Instead of editing the source by hand, better run make, e.g.:

    make -C ../../firmware2/src config-flashrom

You can get an overview of targets with:

    make -C ../../firmware2/src help

Code

To build the firmware, type:

    make -C ../../firmware2/src

You can get an overview of targets with:

    make -C ../../firmware2/src help

You might want to adjust macro settings in ../../firmware2/src/kick2.spin and ../../firmware2/src/pccom.spin before running make.

Code Upload

To load the firmware onto the Controller Board, see options of ../../firmware2/start/Makefile:

    make -C ../../firmware2/start help

It might be a good idea to upload into Free-design RAM:

    make -C ../../firmware2/start loadram

Operate the Device

To operate the device, see options of ../../firmware2/start/Makefile:

    make -C ../../firmware2/start help

The Makefile promotes usage of the interface to the connect utility and offers a bunch of targets, e.g.:

    make -C ../../firmware2/start start

Testing the interface to flashrom can be done with target flashrom-probe, which has been added as a proof of concept: Synchronization, initialization and probing do work fine:

    make -C ../../firmware2/start flashrom-probe

Finally, the interface to the Propeller Terminal can get uploaded and started:

    make -C ../../firmware2/start terminal

Operate the Device with Flashrom

Instead of using the Makefile, feel free to operate the chipflasher with the flashrom utility. Here are some invocation examples as executed in ../../firmware2/start/:

Probe

    flashrom -p serprog:dev=tty_port_pointer:57600

Probe MX25L6405D (as found on ThinkPad X230, Chip #1)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L6405D" -V
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    flashrom was built with libpci 3.7.0, GCC 7.5.0, little endian
    Command line (5 args): flashrom -p serprog:dev=tty_port_pointer:57600 -c MX25L6405D -V
    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    Initializing serprog programmer
    serprog: connected - attempting to synchronize
    .
    serprog: Synchronized
    serprog: Interface version ok.
    serprog: Bus support: parallel=off, LPC=off, FWH=off, SPI=on
    serprog: Maximum write-n length is 256
    serprog: Maximum read-n length is 4096
    serprog: Programmer name is "Zerocat!"
    serprog: Serial buffer size is 16
    serprog: operation buffer size is 300
    serprog: Output drivers enabled
    The following protocols are supported: SPI.
    Probing for Macronix MX25L6405D, 8192 kB: probe_spi_rdid_generic: id1 0xc2, id2 0x2017
    Found Macronix flash chip "MX25L6405D" (8192 kB, SPI) on serprog.
    Chip status register is 0x00.
    Chip status register: Status Register Write Disable (SRWD, SRP, ...) is not set
    Chip status register: Bit 6 is not set
    Chip status register: Block Protect 3 (BP3) is not set
    Chip status register: Block Protect 2 (BP2) is not set
    Chip status register: Block Protect 1 (BP1) is not set
    Chip status register: Block Protect 0 (BP0) is not set
    Chip status register: Write Enable Latch (WEL) is not set
    Chip status register: Write In Progress (WIP/BUSY) is not set
    This chip may contain one-time programmable memory. flashrom cannot read
    and may never be able to write it, hence it may not be able to completely
    clone the contents of this chip (see man page for details).
    No operations were specified.
    serprog: Output drivers disabled

Read MX25L6405D (as found on ThinkPad X230, Chip #1)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L6405D" -r chip1.bin
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    serprog: Programmer name is "Zerocat!"
    Found Macronix flash chip "MX25L6405D" (8192 kB, SPI) on serprog.
    Reading flash... done.

Verify MX25L6405D (as found on ThinkPad X230, Chip #1)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L6405D" -v chip1.bin
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    serprog: Programmer name is "Zerocat!"
    Found Macronix flash chip "MX25L6405D" (8192 kB, SPI) on serprog.
    Verifying flash... VERIFIED.

Erase MX25L6405D (as found on ThinkPad X230, Chip #1)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L6405D" -E
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    serprog: Programmer name is "Zerocat!"
    Found Macronix flash chip "MX25L6405D" (8192 kB, SPI) on serprog.
    Erasing and writing flash chip... Erase/write done.

Write MX25L6405D (as found on ThinkPad X230, Chip #1)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L6405D" -w chip1.bin
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    serprog: Programmer name is "Zerocat!"
    Found Macronix flash chip "MX25L6405D" (8192 kB, SPI) on serprog.
    Reading old flash chip contents... done.
    Erasing and writing flash chip...
    Erase/write done.
    Verifying flash... VERIFIED.

Probe MX25L3205D (as found on ThinkPad X230, Chip #2)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L3205D/MX25L3208D" -V
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    flashrom was built with libpci 3.7.0, GCC 7.5.0, little endian
    Command line (5 args): flashrom -p serprog:dev=tty_port_pointer:57600 -c MX25L3205D/MX25L3208D -V
    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    Initializing serprog programmer
    serprog: connected - attempting to synchronize
    .
    serprog: Synchronized
    serprog: Interface version ok.
    serprog: Bus support: parallel=off, LPC=off, FWH=off, SPI=on
    serprog: Maximum write-n length is 256
    serprog: Maximum read-n length is 4096
    serprog: Programmer name is "Zerocat!"
    serprog: Serial buffer size is 16
    serprog: operation buffer size is 300
    serprog: Output drivers enabled
    The following protocols are supported: SPI.
    Probing for Macronix MX25L3205D/MX25L3208D, 4096 kB: probe_spi_rdid_generic: id1 0xc2, id2 0x2016
    Found Macronix flash chip "MX25L3205D/MX25L3208D" (4096 kB, SPI) on serprog.
    Chip status register is 0x00.
    Chip status register: Status Register Write Disable (SRWD, SRP, ...) is not set
    Chip status register: Bit 6 is not set
    Chip status register: Block Protect 3 (BP3) is not set
    Chip status register: Block Protect 2 (BP2) is not set
    Chip status register: Block Protect 1 (BP1) is not set
    Chip status register: Block Protect 0 (BP0) is not set
    Chip status register: Write Enable Latch (WEL) is not set
    Chip status register: Write In Progress (WIP/BUSY) is not set
    This chip may contain one-time programmable memory. flashrom cannot read
    and may never be able to write it, hence it may not be able to completely
    clone the contents of this chip (see man page for details).
    No operations were specified.
    serprog: Output drivers disabled

Read MX25L3205D (as found on ThinkPad X230, Chip #2)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L3205D/MX25L3208D" -r chip2.bin
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    serprog: Programmer name is "Zerocat!"
    Found Macronix flash chip "MX25L3205D/MX25L3208D" (4096 kB, SPI) on serprog.
    Reading flash... done.

Verify MX25L3205D (as found on ThinkPad X230, Chip #2)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L3205D/MX25L3208D" -v chip2.bin
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    serprog: Programmer name is "Zerocat!"
    Found Macronix flash chip "MX25L3205D/MX25L3208D" (4096 kB, SPI) on serprog.
    Verifying flash... VERIFIED.

Erase MX25L3205D (as found on ThinkPad X230, Chip #2)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L3205D/MX25L3208D" -E
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    serprog: Programmer name is "Zerocat!"
    Found Macronix flash chip "MX25L3205D/MX25L3208D" (4096 kB, SPI) on serprog.
    Erasing and writing flash chip... Erase/write done.

Write MX25L3205D (as found on ThinkPad X230, Chip #2)

    flashrom -p serprog:dev=tty_port_pointer:57600 -c "MX25L3205D/MX25L3208D" -w chip2.bin
    ---------------------------------------------------------------------------------------------
    flashrom v1.2 on Linux 5.17.14-gnu (x86_64)
    flashrom is free software, get the source code at https://flashrom.org

    Using clock_gettime for delay loops (clk_id: 1, resolution: 1ns).
    serprog: Programmer name is "Zerocat!"
    Found Macronix flash chip "MX25L3205D/MX25L3208D" (4096 kB, SPI) on serprog.
    Reading old flash chip contents... done.
    Erasing and writing flash chip... Erase/write done.
    Verifying flash... VERIFIED.

TODO

While working on the kick2 Spin/PASM code, these things should be fixed, soon:

• The hexadecimal dump lines generated by kick2 differ from output generated by srec_cat in respect to spaces preceeding the line feed character. The firmware writes spaces, but srec_cat does not. Data bytes however, do not differ.

  Use sed -r -e 's/[ ]*$//;' -i chip2file.txt to adjust the firmware’s file for direct comparison via diff -y.

• Do we need a verify routine for erase options?

• Very occasionally, the connect utility fails to put all characters send by kick2 onto screen, what results in an erroneous display of menu options and dialogues. Boot your host with radio devices disabled, that frees up resources and should help.

Software Bill of Material

Note this branch is developed on a GNU Guix System, which helps to list up exact package names, software versions and brief descriptions via guix show.

In addition to the project’s initial software requirements listed in ../../doc/software-tools.md, this branch will focus on Spin/PASM related tools, that ship with package propeller-development-suite@4.6.1-2.4c46ecbe7:

• openspin@1.00.78 – OpenSpin is a compiler for the Spin/PASM language
• spin2cpp@3.6.4 – Convert Spin code to C, C++, or PASM code
• spinsim@0.75-1.66915a7ad – Simulator and simple debugger for Spin programs

Furthermore, the flashrom utility is required:

• flashrom – Identify, read, write, erase, and verify ROM/flash chips

The documentation is supplemented by zipped files, downloaded with the wget utility:

• wget – Non-interactive command-line utility for downloading files
• unzip – Decompression and file extraction utility