Hack images, store outputs in git again for now

Easier to track what each script change does if we keep the before and
after versions of the markdown in git too.  Clean this up eventually,
but simplifies development.

1 files changed, 98 insertions, 0 deletions

diff --git a/markdown/UsingSTLink.md b/markdown/UsingSTLink.md
new file mode 100644
index 0000000..02cc21e
--- /dev/null
+++ b/markdown/UsingSTLink.md
@@ -0,0 +1,98 @@
+# Using ST-LINK
+
+ST-LINK is STM's implementation of the [| Serial Wire Debug (SWD)](https://developer.arm.com/products/architecture/cpu-architecture/debug-visibility-and-trace/coresight-architecture/serial-wire-debug) protocol.
+Think of it as JTAG if you're more comfortable with that.
+
+## Getting an ST-LINK programmer
+
+ST-LINK is built into all(?) of STM's Nucleo and Discovery evaluation
+boards, which can be had for as little as US$10 from [Mouser](http://mouser.com)
+or [element14] ([http://newark.com Newark](http://element14.com) in
+the Americas, [Farnell](http://farnell.com) in Europe).
+
+We have tested with STM32F0DISCOVERY and STM32F4DISCOVERY (both with ST-LINK
+v2.0) and NUCLEO-F411RE (with ST-LINK v2.1).
+
+### Connecting the ST-LINK programmer to the Alpha
+
+On the STM board, remove the pair of ST-LINK jumpers (CN4 on the F4DISCO,
+CN2 on the F0DISCO and NUCLEO). Then locate the 6-pin SWD header (CN3 on
+the F0DISCO, CN2 on the F4DISCO, CN4 on the NUCLEO), and connect it to J1
+on the Alpha board (top, just left of center).
+
+This photo shows the correct orientation of the cables (both boards
+oriented so that the logo is right-side up):
+
+[[Image(IMG_20170512_205557_s.jpg)]]
+
+NOTE: The STM boards have an unfortunate tendency to short unexpectedly, so
+I recommend putting them in an enclosure. In this case, I've cut holes in
+the original packaging.
+
+## Install OpenOCD and the debugger
+
+```
+$ apt-get install gdb-arm-none-eabi openocd
+```
+
+## Get the `debug` and `flash-target` scripts
+
+If you don't already have a cryptech source tree somewhere, get the source distribution, e.g.
+```
+$ apt-get source cryptech-alpha
+```
+
+The scripts are in `sw/stm32/bin`.
+
+## Re-flashing the Alpha
+
+### To reflash with our binary firmware
+```
+$ tar xfz /usr/share/cryptech-alpha-firmware.tar.gz
+$ flash-target hsm
+```
+
+
+What you should see is something like:
+```
+** Programming Started **
+auto erase enabled
+Info : device id = 0x20016419
+Info : flash size = 2048kbytes
+Info : Dual Bank 2048 kiB STM32F42x/43x/469/479 found
+target halted due to breakpoint, current mode: Thread
+xPSR: 0x61000000 pc: 0x20000046 msp: 0x2002fffc
+wrote 524288 bytes from file projects/hsm/hsm.elf in 12.344705s (41.475 KiB/s)
+** Programming Finished **
+** Verify Started **
+target halted due to breakpoint, current mode: Thread
+xPSR: 0x61000000 pc: 0x2000002e msp: 0x2002fffc
+target halted due to breakpoint, current mode: Thread
+xPSR: 0x61000000 pc: 0x2000002e msp: 0x2002fffc
+verified 509100 bytes in 0.953672s (521.320 KiB/s)
+** Verified OK **
+** Resetting Target **
+Info : Unable to match requested speed 2000 kHz, using 1800 kHz
+Info : Unable to match requested speed 2000 kHz, using 1800 kHz
+adapter speed: 1800 kHz
+shutdown command invoked
+```
+
+
+### To reflash with firmware you built from source
+
+See BuildingFromSource.
+
+## Debugging the Alpha
+
+This site shows several ways to use various debuggers to debug the
+firmware in an STM32:
+
+    http://fun-tech.se/stm32/OpenOCD/gdb.php
+
+There is a shell script called 'bin/debug' that starts an OpenOCD server
+and GDB:
+
+```
+$ sw/stm32/bin/debug projects/hsm/hsm
+```