= Using ST-LINK =

ST-LINK is STM's implementation of the [https://developer.arm.com/products/architecture/cpu-architecture/debug-visibility-and-trace/coresight-architecture/serial-wire-debug | Serial Wire Debug (SWD)] 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 [http://mouser.com Mouser]
or [http://element14.com element14] ([http://newark.com Newark] in
the Americas, [http://farnell.com Farnell] 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
}}}