summaryrefslogtreecommitdiffstats
path: root/upgrade/technical details.txt
blob: 45fa7ee09814af7d71bd4cf56a8897b4537acd99 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
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.