releng/alpha
============

Release engineering stuff for Cryptech Alpha board and support software.


## Overview ##

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:

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

2.  Building software packages (code which runs on the host to which
    the Alpha is connected).

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.

You are of course free to build all of this for yourself, with or
without modification, the pre-built versions are just a convenience.


## Source Tree ##

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.


## Firmware Build Process ##

The firmware build process consists of five main phases:

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.

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.

3.  Cross-compiling C code for the Alpha's ARM processor.  This
    produces two images: the bootloader, and the HSM firmware itself.

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.  Generation of a [Homebrew][] formula and committing that formula to
    the staging instance of a Homebrew "tap" (git repository), using the
    tarball created during the Debian source package stage as the
    source package.  The Homebrew formula is source-only (no "bottled"
    binary packages): creating binary packages would not be
    particularly difficult (one [osxcross][] instance per version of
    OSX we want to support would do it), but Apple's Xcode SDK license
    doesn't permit this unless we run our build farm on Apple
    hardware.

5.  Uploading changes from the staging repositories to our public
    repositories.

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.


[XiLinxTools]:		http://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/design-tools.html
[pbuilder]:		https://pbuilder.alioth.debian.org/
[Homebrew]:		http://brew.sh/
[osxcross]:		https://github.com/tpoechtrager/osxcross
[MinGW]:		http://www.mingw.org/