Zerocat Chipflasher Flashrom Interface Documentation



## 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

## 2021/03/31

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

## 2020/11/14

* File “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

## (as of) January 2020

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`.


See source file for copyright information.



## Branches and Workflow

The “Zerocat Chipflasher Flashrom Interface” project is promoted on
branch ‘flashrom-interface’. This branch should be regarded as the
project’s front door, but not necessarily as the place of hacking.

Hacking starts on branch ‘firmware2-wip’, which is dedicated to the
actual firmware review and the integration of the new interface.

Branch ‘firmware1-wip’ serves as a collecting point for cherry-picked
fixes, that might apply to the old firmware as we go.

## Kick2 --- The Second Firmware Approach, Coded in Spin/PASM

The Chipflasher’s firmware is going to be reviewed and rewritten in
Spin/PASM language. While maintaining the menu interface for the
project’s own `connect` utility, the integration of an interface for
the external `flashrom` utility will be set up in parallel.

## 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 `linehexdump` and `linemotsbin`. 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

## Requirements

Requirements are frugal:

* RYF-certified Chipflasher Board `board-edition-1` aka `board-v1.1.0`
* PC/Laptop
    - two USB-Slots for power
    - one Serial Port `/dev/ttyS0` or alike, for data

See “Software-Bill-of-Material.md” for required software.

## Interface Configuration

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

1. Flashrom
2. Connect
3. Propeller Terminal
4. No Interface

The configuration will not only affect the compiled output, but the
generated documentation as well. In order to get a full set of files,
just enable all interface macros within the object during the
documentation build or use the dedicated Makefile target, see section

### 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.

### 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 Propeller Terminal

In case `flashrom` or `connect` are not available, you might still use
a propeller terminal as fallback. However, features are heavily
stripped, you cannot do something real. This terminal is as well
supported via the `menu` Spin/PASM object.

## 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.

## Documentation

To build this documentation, use target `html` or `html-all` in
`firmware2/doc/Makefile`. The latter target will temporarily modify
macro settings within the top object in order to obtain a full set of
documentation files.

## Code

To build the firmware, use target `all` in `firmware2/src/Makefile`.
You might want to adjust macro settings in `firmware2/src/kick2.spin`
and `firmware2/src/pccom.spin`, first.

## Code Upload

To load the firmware onto the Controller Board, see options of

## Operate the Device

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

The Makefile promotes usage of the Connect Interface. However, target
`flashrom-probe` has been added as a proof of concept: Synchronization,
initialization and probing (fake data) do work fine.


See source file for copyright information.


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

In order to set up your environment on GNU Guix System, type:

    guix environment --pure \
        -m host/util/manifest.scm \
        -m firmware2/util/manifest.scm


See source file for copyright information.

Compiler Documentation Output

These documentation files have been build according to the following top object’s interface configuration:
#   define _CFG_FLASHROM
# 	 define _CFG_CONNECT
# 	 define _CFG_TERMINAL

“Zerocat Chipflasher Flashrom Interface Documentation” as of Sat, 01 May 2021 14:52:51 +0200
Repository: git://zerocat.org/zerocat/projects/chipflasher
Version: v0.4.10-732-9a3cc90b
Branch: flashrom-interface