Documentation for “Zerocat Chipflasher: Kick2”
Generated on: Wed, 29 Jun 2022 23:26:29 +0200
Repository: git://zerocat.org/zerocat/projects/chipflasher
Version: v0.6.9-264-5784d78b
Branch: flashrom-interface
Ready to fly: Chipflasher has an 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".
flashrom
utility is now supported!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.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
.
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.
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-flashrom
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 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
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/
:
flashrom -p serprog:dev=tty_port_pointer:57600
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
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.
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.
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.
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.
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
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.
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.
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.
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.
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: