Update and expand README

1 files changed, 103 insertions, 60 deletions

diff --git a/README.md b/README.md
index 6d813ef..e2c10a8 100644
--- a/README.md
+++ b/README.md
@@ -1,80 +1,127 @@
-STM32 software for dev-bridge/Alpha board
-=========================================
+STM32 firmware for Cryptech Alpha board
+=======================================
 
-The dev-bridge board is a daughterboard for the Novena, which talks to the
-Novena's FPGA through the high-speed expansion connector.
+The Alpha board is our first full prototype for an open-source hardware
+security module (HSM). It is a custom board with an STM32 Cortex-M4
+microcontroller and an Artix-7 FPGA, flash-based keystore, separate memory
+for the Key Encryption Key, etc. See the `hardware` repository for
+schematics and production files. See the wiki for design documents.
 
-The Alpha board is a stand-alone board with an Artix-7 FPGA, a STM32 Cortex-M4
-microcontroller, two USB interfaces etc.
-
-See user/ft/stm32-dev-bridge/hardware/rev01 for schematics of the bridge
-board. There will be more information on the wiki shortly.
+The code in this repository builds the firmware that provides the HSM
+functionality on the Alpha board.
 
+There is some residual code here to support the "dev-bridge" board, a
+daughterboard for the Novena, which talks to the Novena's FPGA through the
+high-speed expansion connector. Only a few of these boards were ever made,
+and all development/testing ceased as soon as the Alpha became available,
+so the dev-bridge should be considered deprecated, and support may be
+removed in the future.
 
 Copyrights
 ==========
 
 The license for all work done on this in the CrypTech project is a
-3-clause BSD license (see LICENSE.txt for details). Some files have
-been generated using the STMicroelectronics initialization code
-generator STM32CubeMX and thus have additional copyright header(s).
+3-clause BSD license.
+
+Third-party components, as well as code generated using the
+STMicroelectronics initialization code generator STM32CubeMX, or adapted
+from STM example/support code, may have different licensing, detailed
+below.
+
+Components
+==========
+
+Libraries
+---------
+
+* `mbed` - A stripped down copy of the ARM CMSIS library, copied from the
+  mbed github (see `libraries/mbed/README.txt` for details). The bulk of
+  this library is covered under 3-clause BSD licenses from either ARM or
+  STMicroelectronics, but one file is covered under an Apache license from
+  ARM.
+
+* `libhal` - Build directory for our own Hardware Adaption Library
+  (hardware-independent Cryptech components). Source is expected to be in
+  `sw/libhal`.
+
+* `libtfm` - Build directory for "Tom's Fast Math", which is used heavily
+  for bignum math in the RSA and ECDSA code. This code is covered under an
+  unrestricted public domain license, and source is expected to be in
+  `sw/thirdparty/libtfm`.
+
+* `libcli` - Build directory for a third-party Command Line Interface
+  library. The source is not currently under `sw/thirdparty` because the
+  license is LGPLv2.1; we are negotiating to see if we can get a
+  BSD-compatible license for it.
+
+* `libprof` - A port of the `gmon` profiling package, to be used in
+  development only, not in production code (obviously). The licensing is a
+  mix of BSD and "Cygwin license", which now seems to be LGPLv3.
+
+Projects
+--------
 
-The "Noise generator" and "Amplifier" parts of the circuit diagram are
-copied from Benedikt Stockebrand's ARRGH project. ARRGH copyright
-statement is included in LICENSE.txt.
+These directories build different firmware images for the Alpha board.
 
-A stripped down copy of the ARM CMSIS library version 3.20 is included
-in the Drivers/CMSIS/ directory. Unused parts (and documentation etc.)
-have been removed, but every attempt have been made to keep any
-licensing information intact. See in particular the file
-Drivers/CMSIS/CMSIS END USER LICENCE AGREEMENT.pdf.
+* `hsm` - Firmware providing HSM functionality. Clients communicate via
+  RPC requests on the USER USB port, or interactively on the MGMT USB
+  port.
 
-A full copy of the STM32F4xx HAL Drivers is included in the
-Drivers/STM32F4xx_HAL_Driver/ directory.
+* `bootloader` - The first thing that runs on the device. It either starts
+  the primary firmware, or installs new firmware.
 
+* `board-test` - Tests of hardware components.
+
+* `cli-test` - Test of the CLI itself, plus some interactive tests of
+  hardware components. Duplicates way too much of the HSM CLI.
+
+* `libhal-test` - A framework for running the libhal component
+  tests. Hasn't been run in a while, probably still works.
 
 Building
 ========
 
-The following packages need to be installed (on Ubuntu 14.04):
+Our primary build environments are Debian and Ubuntu, but this should work
+on any system with Gnu tools installed.
 
-  apt-get install gcc-arm-none-eabi gdb-arm-none-eabi openocd
+The following packages need to be installed:
 
-To build the source code, issue "make" from the top level directory
-(where this file is). The first time, this will build the complete STM
-CMSIS library. A subsequent "make clean" will *not* clean away the CMSIS
-library, but a "make distclean" will.
+    $ apt-get install gcc-arm-none-eabi gdb-arm-none-eabi openocd
 
+The Makefile assumes that all Cryptech repositories have been fetched into
+a canonical directory structure, e.g. `libhal` and `thirdparty` are
+siblings to this directory, under `sw`.
+
+To build the source code, issue `make` from the top level directory
+(where this file is). The first time, this will build the complete STM
+CMSIS library. A subsequent `make clean` will *not* clean away the CMSIS
+library, but a `make distclean` will.
 
 Installing
 ==========
 
-Do "bin/flash-target" from the top level directory (where this file is)
+Do `bin/flash-target` from the top level directory (where this file is)
 to flash a built image into the microcontroller. See the section ST-LINK
 below for information about the actual hardware programming device needed.
 
-Example loading the bootloader and the led-test firmware to get some LEDs
-flashing:
+Example loading the HSM firmware:
 
-  $ make bootloader board-test
-  $ ./bin/flash-target projects/board-test/led-test
-  $ ./bin/flash-target projects/bootloader/bootloader
+    $ make hsm
+    $ ./bin/flash-target projects/hsm/hsm
 
 At this point, the STM32 will reset into the bootloader which flashes the
-blue LED five times in one second, and then execution of the LED test
-firmware will begin. The LED test firmware will flash the green, yellow,
-red and blue LEDs in order until the end of time.
+blue LED five times in one second, and then jumps to the primary firmware.
 
 Once the bootloader is installed, regular firmware can be loaded without
 an ST-LINK cable like this:
 
-  $ ./bin/dfu projects/board-test/led-test.bin
+    $ cryptech_upload --firmware -i projects/hsm/hsm.bin
 
 Then reboot the Alpha board.
 
-
 ST-LINK
-=======
+-------
+
 To program the MCU, an ST-LINK adapter is used. The cheapest way to get
 one is to buy an evaluation board with an ST-LINK integrated, and pinouts
 to program external chips. This should work with any evaluation board from
@@ -86,7 +133,7 @@ printed on the circuit board. The pin-outs is shown on the circuit board
 (follow the thin white line from J1 to the white box with STM32_SWD
 written in it). From left to right, the pins are
 
-  3V3, CLK, GND, I/O, NRST and N/C
+    3V3, CLK, GND, I/O, NRST and N/C
 
 This matches the pin-out on the DISCO and NUCLEO boards we have tried.
 
@@ -94,34 +141,30 @@ First remove the pair of ST-LINK jumpers (CN4 on the DISCO, CN2 on the
 NUCLEO). Then find the 6-pin SWD header on the left of the STM board (CN2
 on the DISCO, CN4 on the NUCLEO), and connect them to the Alpha board:
 
-    NUCLEO / DISCO       CRYPTECH ALPHA
-    --------------       --------------
-* 1 VDD_TARGET      <->  3V3
-* 2 SWCLK / T_JTCK  <->  CLK
-* 3 GND             <->  GND
-* 4 SWDIO / T_JTMS  <->  IO
-* 5 NRST / T_NRST   <->  NRST
-
-N/C (pin 6) means Not Connected.
+    NUCLEO / DISCO           CRYPTECH ALPHA
+    --------------           --------------
+    * 1 VDD_TARGET      <->  3V3
+    * 2 SWCLK / T_JTCK  <->  CLK
+    * 3 GND             <->  GND
+    * 4 SWDIO / T_JTMS  <->  IO
+    * 5 NRST / T_NRST   <->  NRST
+    * 6 N/C
 
 The Alpha board should be powered on before attempting to flash it.
 
-
 Debugging the firmware
-======================
-
-This site shows several ways to use various debuggers to debug the
-firmware in an STM32:
+----------------------
 
-  http://fun-tech.se/stm32/OpenOCD/gdb.php
+[This site](http://fun-tech.se/stm32/OpenOCD/gdb.php) shows several ways
+to use various debuggers to debug the firmware in an STM32.
 
 There is a shell script called 'bin/debug' that starts an OpenOCD server
 and GDB. Example:
 
-  $ ./bin/debug projects/board-test/led-test
+    $ ./bin/debug projects/hsm/hsm
 
-Once in GDB, issue "monitor reset halt" to reset the STM32 before debugging.
+Once in GDB, issue `monitor reset halt` to reset the STM32 before debugging.
 
 Remember that the first code to run will be the bootloader, but if you do
-e.g. "break main" and "continue" you will end up in led-test main() after
-the bootloader has jumped there.
+e.g. `break main` and `continue` you will end up in main() after the
+bootloader has jumped there.