NEWS ==== ## 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.
README ====== ## 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 interfaces: 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 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 `firmware2/start/Makefile`. ## 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 “email@example.com”: * firstname.lastname@example.org – OpenSpin is a compiler for the Spin/PASM language * email@example.com – Convert Spin code to C, C++, or PASM code * firstname.lastname@example.org – 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.
# define _CFG_FLASHROM # define _CFG_CONNECT # define _CFG_TERMINAL../src/ASCII.spin.txt.html
“Zerocat Chipflasher Documentation” as of Sat, 14 Nov 2020 22:04:04 +0100