From 4897dc2139ba128e6542e74e967e985042fde683 Mon Sep 17 00:00:00 2001
From: mcudev <29890609+mcudev@users.noreply.github.com>
Date: Tue, 10 Oct 2017 14:56:15 -0400
Subject: [PATCH] doc: STLINK_VER and boardloader description (#35)

---
 README.md          |  2 +-
 docs/bootloader.md | 16 +++++++++++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 9339f8e92..0b1ca44f4 100644
--- a/README.md
+++ b/README.md
@@ -83,7 +83,7 @@ Not supported yet ...
 ### Linux
 
 For flashing firmware to blank device (without bootloader) use `make flash`,
-or `make flash STLINKv21=1` if using a ST-LINK/V2.1 interface.
+or `make flash STLINK_VER=v2-1` if using a ST-LINK/V2.1 interface.
 
 #### Debian/Ubuntu
 
diff --git a/docs/bootloader.md b/docs/bootloader.md
index 6c7069ce6..eff466c76 100644
--- a/docs/bootloader.md
+++ b/docs/bootloader.md
@@ -1,6 +1,6 @@
 # TREZOR Core Bootloader
 
-TREZOR initialization in split into two stages.
+TREZOR initialization is split into two stages.
 See [Memory Layout](memory.md) for info about in which sectors each stage is stored.
 
 First stage (boardloader) is stored in write-protected area, which means it is non-upgradable.
@@ -15,6 +15,20 @@ If first stage boardloader finds a valid second stage bootloader image
 on the SD card (in raw format, no filesystem), it will replace the internal
 second stage, allowing a second stage update via SD card.
 
+The boardloader is special in that it is the device's write protected embedded code.
+The primary purpose for write protecting the boardloader is to make it the
+immutable portion that can defend against code-based attacks (e.g.- BadUSB)
+and bugs that would reprogram any/all of the embedded code.
+It assures that only verified signed embedded code is run on the device
+(and that the intended code is run, and not skipped).
+The write protection also provides some defense against attacks where the
+attacker has physical control of the device.
+
+The boardloader must include an update mechanism for later stage code because
+if it did not, then a corruption/erasure of later stage flash memory would
+leave the device unusable (only the boardloader could run and it would not
+pass execution to a later stage that fails signature validation).
+
 ## Second Stage - Bootloader
 
 Second stage checks the integrity and signatures of the firmware and runs