Adding bootloader and update program

[stefan-b-jakobsson]

Intro

This PR adds bootloader v3 and the SMCUPDATE program as an integral part of the x16-smc project.

Both these components need to be tightly integrated with the firmware, and it therefore makes sense to have them here.

The action that builds the project has been extended to build also the bootloader and the SMCUPDATE program.

Bootloader v3

The new bootloader version has improved safety features.

I2C communication does not depend on interrupts, and the bootloader no longer needs to add its own vectors to the first page of flash memory.

The new bootloader adds a possibility to recover a firmware update that went wrong. If you hold the Reset button when connecting the X16 to mains power, the X16 is powered on and the bootloader is activated. If you have stored the SMCUPDATE program on the SD card as AUTOBOOT.X16, it will update the firmware without user input.

The bootloader also supports a function to read the flash memory. This function can be used to verify that a firmware update was successful.

SMCUPDATE

The SMCUPDATE program is intended as a way to distribute new SMC firmware.

The firmware is embedded into the program file, and you need no other files. This also minimizes the program's dependency on Kernal functions, making it less error prone.

As mentioned above, the bootloader can be activated by holding down the Reset button when you connect the X16 to mains power. The SMCUPDATE program detects if the bootloader is already active when it is started, and if so, it will do the update after a 60 second countdown without user input.

If the bootloader was not activated on program start, it will ask the user to confirm the update.

If bootloader v3 is installed, the program will verify the flash memory after the update.

The program is compatible with bootloader versions 1, 2 and 3.

It also detects the bad bootloader v2 after the update, and instructs the user to reset the SMC and not power off the system.

Eirik's flash tools

I also added Eirik's flash tools and his bad v2 bootloader guides to the documentation. @stople would need to approve this before merging.

[stople]

I am on vacation one more week, but, this PR seems good (have not tested it yet). Thanks for reformatting the instructions in markdown. By the way, should we add the new bootloader v3 to the bootloader programming tools if you have not done that already? We can also do that in a later PR.

[stefan-b-jakobsson]

I think we need to look through the instructions once more before calling it a day. Some information will become obsolete if this PR is merged.

I'm not sure what's the best way to distribute your flash manipulation tools. We could store them in a repo folder. We could add them to the action artifact.

The bootloader is added to the artifact, both in hex and bin format.

We can get back after your vacation. Take care!

[stople]

Also, I find it a little bad that the flash manipulation tools, written in basic, are considered "binary", as that may make the source code less accessible. A better choice could be to keep the source files in ascii format. And "basload", or some other conversion script could turn "readable" ascii files to tokenized basic

[stople]

I think it is a good thing to include these tools and documentation into the repo. That said, I think the PR in its current state, with 37 commits, is a bit hard to comprehend for a regular developer.

• Can it be an idea to divide the PR into some smaller PRs, e.g. one for each new component, so that each PR becomes a manageable task?
• As you are introducing 3 new components (bootloader, SMCUPDATE, and bootloader upgrader tools), I suggest a better tracability to exactly what code (which version/commit) is added to this repo. For starters, decide which commit inside smc-bootloader and SMCUPDATE is the one you want to move into x16-smc, and make this tracable. A PR which introduces other components should do exactly that, and not introducing new changes (e.g. optimizing code size). I suggest to do one thing at a time, to reduce its complexity.
• One alternative to make a copy of a single commit in another repo (which also erases its history), is to merge the actual commit from the other repo, with its parents as well, into this repo, preserving the history of that component. I have done this on my day job when combining smaller repos into one bigger repo. I am not sure if this is desired in this case, but I can try to assist if you think this can be relevant.

[stople]

I see that the initial bootloader commit is not equal to anything in the bootloader repo, meaning that we do not have the history to how it became as it is, for tracability. That said, I see that its date is July 18th, and, it contains the macro CMD_SET_ADDR_PAGE added in the latest commit in the bootloader repo from July 16th. I actually see that this macro have been altered as well. Anyway, this makes it likely that the initial bootloader commit is derived from the newest commit inside bootloader repo, with a few additions.

On the topic of the macro/function: Do we need to spend 8 instructions to set a particular target address? Can it be an option to set target_addr (Z) to 0 always (a single movw instruction), and then increment it using read_flash instead? (If we should keep flash usage to a minimum)

[stefan-b-jakobsson]

OK, I can try to divide the changes.

As a first step, I pulled the bootloader code from this branch into my own bootloader repo. I also changed set target address to a rewind target address.

You find the current code here: https://github.com/stefan-b-jakobsson/x16-smc-bootloader/tree/20240711-v3

I will do the same with SMCUPDATE.

Maybe we can focus on adding one of these components at a time to the x16-smc repo.

Please note that I haven't even myself tested the v3 bootloader in my repo.

[stefan-b-jakobsson]

I now pushed the SMCUPDATE program v3 here: https://github.com/stefan-b-jakobsson/x16-smc-update/tree/20240711-bootloader3

In order for it to build without being part of x16-smc I had to remove some parts of the build script, most notably the parts that automatically fetched the firmware version number.