Added some tech details

1 files changed, 51 insertions, 0 deletions

diff --git a/upgrade/technical details.txt b/upgrade/technical details.txt
new file mode 100644
index 0000000..45fa7ee
--- /dev/null
+++ b/upgrade/technical details.txt
@@ -0,0 +1,51 @@
+Technical Details
+=================
+
+A summary of how 'upgrade' works
+
+
+-- build process:
+
+1) Manually run the generate-data.rb ruby script with the new bootloader's hex file:
+     ruby generate-data.rb new_firmware.hex
+   If you have trouble running it, make sure you're using ruby version 1.9. 1.8 is too old!
+   
+   generate-data.rb creates the bootloader_data.c file, which defines some variables containing
+   the entire raw byte data of the bootloader as an array stored in flash memory. It also
+   calculates and writes in the start address of the bootloader. The hex file supplied can be any
+   bootloader which works similarly to USBaspLoader-tiny85 - which is most (all?) tiny85 bootloaders
+   and likely some for other avr chips which lack hardware bootloader stuff.
+   
+2) Generate the hex file using make:
+     make clean; make
+   
+   The upgrader hex file is built in the usual way, then combined with upgrade-prefix.hex (which
+   I wrote by hand) to prefix a fake interrupt vector table in the start of the upgrader. This is
+   necessary because bootloaders like micronucleus and Fast Tiny & Mega Bootloader only work with
+   firmwares which begin with an interrupt vector table, because of the way they mangle the table
+   to forward some interrupts to themselves.
+   
+3) Upload the resulting upgrade.hex file to a chip you have some means of recovering. If all works
+   correctly, consider now uploading it to other chips which maybe more difficult to recover but are
+   otherwise identical.
+
+
+-- how it works:
+
+Taking inspiration from computer viruses, when upgrade runs it goes through this process:
+
+1) Brick the chip:
+   The first thing upgrade does is erase the ISR vector table. Erasing it sets the first page to
+   0xFF bytes - creating a NOP sled. If the chip looses power or otherwise resets, it wont enter
+   the bootloader, sliding in to the upgrader restarting the process.
+
+2) erase and write bootloader:
+   The flash pages for the new bootloader are erased and rewritten from start to finish.
+   
+3) install the trampoline:
+   The fake ISR table which was erased in step one is now written to - a trampoline is added, simply
+   forwarding any requests to the new bootloader's interrupt vector table. At this point the viral
+   upgrader has completed it's life cycle and has disabled itself. It should never run again, booting
+   directly in to the bootloader instead.
+
+