Zerocat Chipflasher Documentation



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

This branch 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.



## 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, an interface for the `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 exectued 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

## Scope of Changes

This firmware review is done on branch ‘firmware2-wip’. It will affect the
old firmware and the connect utility as well, as important improvements and
fixes are applied as we go. However, a different branch is used for these
changes, in order to keep things sorted: ‘firmware1-wip’

## 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
interfaces macros within the object during the documentation build or use the
dedicated Makefile target, see section “Documentation”.

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

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

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


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 Documentation” as of Tue, 23 Feb 2021 19:33:29 +0100
Repository: git://zerocat.org/zerocat/projects/chipflasher
Version: v0.4.10-516-geb4b67ca
Branch: flashrom-interface