aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md156
1 files changed, 110 insertions, 46 deletions
diff --git a/README.md b/README.md
index e3f3eff..cca2619 100644
--- a/README.md
+++ b/README.md
@@ -1,66 +1,130 @@
Alpha Releng
============
-Release engineering stuff for Cryptech Alpha.
+Release engineering stuff for Cryptech Alpha board and support software.
-Work in progress, currently a merge in progress of two separate
-release engineering repositories, one for HSM firmware, one for host
-software.
-This README is probably obsolete by the time you're reading it.
+## Overview ##
-## Old Firmware README ##
+The Makefiles and scripts in this repository attempt to automate the
+process of building packaged versions of the firmware and software for
+the Cryptech Alpha board. At a high level, this consists of two main
+phases:
-Preliminary release engineering super-repository for building firmware
-for the Cryptech "Alpha" board.
+1. Building a firmware package (Verilog and C code which runs on the
+ Alpha board itself, regardless the host system to which the Alpha
+ is connected); and
-Primary tasks here are to build a bitstream for the FPGA and the
-"bootstrap" and "hsm" images for the Alpha's CPU.
+2. Building software packages (code which runs on the host to which
+ the Alpha is connected).
-Eventually there will be a lot of packaging and versioning glorp here,
-but let's start with basic build and clean targets.
+Since the firmware is the same for any given version of the Cryptech
+source code, and since the process of building the firmware binaries
+is both time-consuming and involves tools like the XiLinx Verilog
+synthesis toolkit and cross-compilers for multiple CPUs (the Alpha's
+Cortex M4 ARM CPU and the Atmel AVR ATtiny828 MCU used to implement
+the anti-tampering logic for the master key memory), we include a
+signed tarball containing pre-built binaries for all the firmware as
+part of the source tarball for the software packages.
-Current repository structure is, um, complicated. On the RTL side, we
-have a tree of simple subrepositories, each representing one RTL core.
+You are of course free to build all of this for yourself, with or
+without modification, the pre-built versions are just a convenience.
-On the software side, we have a subrepository which has several
-subrepositories of its own: current thinking is that this should
-probably be replaced by separate repositories and Makefile VPATH
-magic, but this is what we have today so it's what we build with
-today.
-This README is probably obsolete by the time you're reading it.
+## Source Tree ##
-## Old Software README ##
+The source code itself, for both the firmware and the software, is in
+the source/ directory, with names corresponding to the canonical names
+of the relevant git repositories. At the time this document was
+written, a few of the repositories in question had not yet been
+promoted to their expected permanent homes in the core/ or sw/ trees,
+but we expect this to be temporary. Regardless, directory names
+within the source/ directory tree are intended to track the canonical
+names of the git repositories, whatever they may be at any given time.
-Preliminary release engineering super-repository for building software
-to work with the Cryptech "Alpha" board.
-Primary task here is to build the PKCS #11 library and any needed
-support tools for whichever platforms we support. This will involve
-some packaging voodoo.
+## Firmware Build Process ##
-Our first targets for this are Debian and Ubuntu, probably the Jessie
-and Xenial releases, respectively. If we really need to support
-multiple releases for each of these platforms, the packaging mechanics
-become more complicated, so we may just stop here for these platforms
-and assume we can fill any odd corners using the associated source
-package.
+The firmware build process consists of five main phases:
-Our next target for this is likely to be Mac OS X. This should be
-relatively straightforward so long as we only have to support Homebrew
-and we don't have to produce Homebrew "bottles" (binary packages). If
-we do need to bottle, we either need one or more Mac build machines or
-we need some kind of cross-compilation scheme (eg,
-https://github.com/tpoechtrager/osxcross).
+1. Building a "shadow" directory tree populated with symlinks back to
+ the source tree. This allows us to preserve binaries between
+ compilation runs where appropriate, without cluttering up the
+ source tree with various intermediate files which don't belong
+ there. In particular, this allows to skip the Verilog synthesis
+ stage when nothing there has changed, which makes the overall
+ build process run significantly faster.
-Supporting Homebrew at all requires a bit of extra voodoo on top of
-supporting Debian packaging, but none of it looks particularly
-difficult, and the Debian packaging will produce the source tarball we
-need for the Homebrew formula, so integrating production of these two
-kinds of packaging makes some sense.
+2. Synthesizing the Verilog source code into a bitstream. This phase
+ generates a single bitstream file, suitable for loading into the
+ Alpha's FPGA chip.
-Windoze is not currently on the radar. In theory, MinGW would suffice
-as a cross compiler if and when we have to do something about it.
+3. Cross-compiling C code for the Alpha's ARM processor. This
+ produces two images: the bootloader, and the HSM firmware itself.
-This README is probably obsolete by the time you're reading it.
+4. Cross compiling C code for the Alpha's AVR MCU. This produces a
+ single image, which runs the tamper-response controller.
+
+5. Packaging all of the firmware created in the above steps into a
+ tarball, with some meta-data describing the package, including
+ SHA-2 digests of all of the firmware image files and a signature
+ over the entire meta-data block.
+
+The precise formats which show up in the firmware tarball are subject
+to change. At the moment, they consist of:
+
+* A raw bitstream (".bit" file) for the Xilinx Artix-7 FPGA.
+
+* ELF and raw binary image files for the Cortex M4 ARM CPU; we supply
+ both .elf and .bin files because some tools want one format, some
+ want the other.
+
+* A ".hex" image for the AVR MCU.
+
+The overall packaging for the firmware tarball is intentionally pretty
+boring: tar, gzip, gpg, and JSON. The intent is that users be able to
+use our firmware tarball even if the scripts we provide are unsuitable
+for some reason.
+
+The final result of the firmware build process is the firmware
+tarball, which is written into the source/ tree for inclusion by the
+software packaging phase.
+
+
+## Software Build Process ##
+
+The software build process also consists of several phases, but is a
+bit more open-ended than the firmware build process. Phases in the
+current build process:
+
+1. Building a source tarball and Debian source package (".dsc").
+ The Debian and Ubuntu Linux distributions are our primary
+ development platforms, so we need to produce packages for them in
+ any case, and the process of producing a Debian-family source
+ package produces a source tarball as one of its outputs, so we get
+ that for free by doing this step first.
+
+2. Running "pbuilder" to generate clean binary packages for the
+ "i386" and "amd64" architectures for Debian Jessie and Ubuntu
+ Xenial.
+
+3. Loading all of the Debian and Ubuntu packages produced above into
+ the staging instances of a set of APT repositories.
+
+4. Uploading changes from the staging repositories to our public APT
+ repositories.
+
+Planned, but missing from the above, is generation of a Homebrew
+formula for Mac OS X and loading that formula along with the
+corresponding source tarball to a public Homebrew "tap". At least the
+initial version of this will likely be a source-only formula; in
+theory, it would be possible for us to cross-compile Mac OS X binaries
+without needing an expensive build farm (eg, using
+https://github.com/tpoechtrager/osxcross), but we haven't sorted
+through either the technical or licensing issues.
+
+In theory, it would also be possible to produce Windows binaries using
+the MinGW cross-compilation environment, but Windows is sufficiently
+different from all other platforms that even minimal Windows support
+would almost certainly require extensive source code changes, so we
+have not put any serious thought into build issues for Windows.