update bootloader documentation

docs/bootloader.md

@@ -1,17 +1,50 @@
 #TREZOR Core Bootloader
 
-All multibyte integer values are little endian!
+Bootloader code is split into two stages. See [Memory Layout](memory.md) for more info about in which sectors the code is stored.
 
-##Firmware File Format
+First stage checks the integrity and signatures of second stage and runs it if everything is OK.
+However, if first stage bootloader finds a valid second stage bootloader on the SD card (in raw format, no filesystem), it will replace the internal second stage, allowing an upgrade of the second stage.
 
-TREZOR Core firmware file consists of 3 parts:
+First stage is stored in write-protected area, which means only upgrade of the second stage bootloader is allowed.
+
+##Common notes
+
+* Hash function used is SHA-256 and signature system is Ed25519 (allows combining signatures by multiple keys into one).
+* All multibyte integer values are little endian.
+
+##Bootloader Format
+
+TREZOR Core (second stage) bootloader consists of 2 parts:
+
+1. bootloader header
+2. bootloader code
+
+###Bootloader Header
+
+Total length of bootloader header is 256 bytes.
+
+| offset | length | name | description |
+|-------:|-------:|------|-------------|
+| 0x0000 | 4      | magic | firmware magic `TRZB` |
+| 0x0004 | 4      | hlen | length of the bootloader header |
+| 0x0008 | 4      | expiry | valid until timestamp (0=infinity) |
+| 0x000C | 4      | codelen | length of the bootloader code |
+| 0x0010 | 1      | vmajor | version (major) |
+| 0x0011 | 1      | vminor | version (minor) |
+| 0x0012 | 1      | vpatch | version (patch) |
+| 0x0013 | 1      | vbuild | version (build) |
+| 0x0014 | 1      | slsigidx | SatoshiLabs signature indexes (bitmap) |
+| 0x0015 | 64     | slsig | SatoshiLabs signature |
+| 0x0079 | 135    | reserved | not used yet |
+
+##Firmware Format
+
+TREZOR Core firmware consists of 3 parts:
 
 1. vendor header
 2. firmware header
 3. firmware code
 
-Hash function used is SHA-256 and signature system is Ed25519 (allows combining signatures by multiple keys into one).
-
 ###Vendor Header
 
 Total length of vendor header is 82 + 32 * (number of pubkeys) + (length of vendor string) + (length of vendor image) bytes rounded up to the closest multiply of 256 bytes.
@@ -20,7 +53,7 @@ Total length of vendor header is 82 + 32 * (number of pubkeys) + (length of vend
 |-------:|-------:|------|-------------|
 | 0x0000 | 4      | magic | firmware magic `TRZV` |
 | 0x0004 | 4      | hlen | length of the vendor header |
-| 0x0008 | 4      | expiry | valid until timestamp |
+| 0x0008 | 4      | expiry | valid until timestamp (0=infinity) |
 | 0x000C | 1      | vsig_m | number of signatures needed to run the firmware from this vendor |
 | 0x000D | 1      | vsig_n | number of pubkeys vendor wants to use for signing |
 | 0x000E | 2      | reserved | not used yet |
@@ -41,7 +74,7 @@ Total length of firmware header is 256 bytes.
 |-------:|-------:|------|-------------|
 | 0x0000 | 4      | magic | firmware magic `TRZF` |
 | 0x0004 | 4      | hlen | length of the firmware header |
-| 0x0008 | 4      | expiry | valid until timestamp |
+| 0x0008 | 4      | expiry | valid until timestamp (0=infinity) |
 | 0x000C | 4      | codelen | length of the firmware code |
 | 0x0010 | 1      | vmajor | version (major) |
 | 0x0011 | 1      | vminor | version (minor) |