Documentation for “Zerocat Chipflasher: Kick2”
Generated on: Sat, 18 Jun 2022 21:45:49 +0200
Repository: git://zerocat.org/zerocat/projects/chipflasher
Version: v0.6.9
Branch: master

Zerocat Chipflasher: Kick2
– The second firmware approach, coded in Spin/PASM.

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

Section #../../firmware2/doc/NEWS.md

NEWS

2022/06/11

2022/05/18

2022/05/10

2022/04/19

2022/15/01

2021/12/26

2021/11/27

2021/10/01

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.

2021/04/29

2021/04/04

2021/03/31

2020/11/14

2020/10/09

2020/10/07

Section #../../firmware2/doc/README.md

README

Project Goal

The Chipflasher’s firmware kick is going to be reviewed and rewritten in Spin/PASM language: kick2

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

Hardware Requirements

Requirements are frugal:

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:

../../firmware2/images/screenshot-20211224-140916.png

Interface to `connect`, coded in Spin/PASM

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 (Default)
  2. Flashrom
  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-connect

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 (fake data) 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
Section #../../firmware2/doc/TODO.md

TODO

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

Section #../../firmware2/doc/Software-Bill-of-Material.md

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:

Furthermore, the flashrom utility is required:

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