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
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".
dash
, as used on Trisquel.Improve Makefiles, sort utility checks, rename macros consistently.
Crosslink documentations.
Upgrade documentation system according to: Zerocat Project Template v0.0.12
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.
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.
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
.
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.
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.
kick2
now displays the correct project number.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.../../firmware2/doc/Software-Bill-of-Material.md
is now part of the
documentation.../../firmware2/start/Makefile
now offers a reset target, which can
be used to quit the serprog object and to restart the device.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.
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:
Requirements are frugal:
Chipflasher
PC or Laptop
/dev/ttyS0
or alike, for dataAll 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/
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/
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
This project comes with its own PC utility called connect
, which is
supported via the menu
Spin/PASM object:
Interface to `connect`, coded in Spin/PASM
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.
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.
The kick2
top object might be configured to run one of the following
interfaces:
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
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
.
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
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
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.
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: