README.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97


Cryptech build environment under Docker
This is an attempt to Dockerize the Cryptech build environment.
The ten zillion Debian packages are tedious but straightforward.
The tricky bit is the XiLinx toolchain:

You need to download the Xilinx ISE Design Suite distribution tarball.
You need to get a license key from XiLinx before you can use ISE.
You have to run GUI installation tools to install and configure it.

There's not much we can do about the first two, so we assume that
you've obtained a tarball and a license key file, and that you've
dropped them into this directory with the filenames we expect.
The third...is fun, in a demented sort of way.
The Xilinx tools are serious disk hogs: VMs for this need at least
30-40 GB of disk space.  The build process for this Dockerized
environment is even worse: 60GB appears to be just barely enough.
To get a license, go to
http://www.xilinx.com/products/design-tools/ise-design-suite/ise-webpack.htm
and click on the Licensing Solutions link. On the resulting page,
expand the section "Obtain a license for Free or Evaluation
product". To download the ISE Webpack, you should have created an
account, so now you can go to the Licensing Site and use that account
to create a Certificate Based License.
You do not need to go through the HostID dance, just say "Do It". You
will then receive a certificate in email (not an X.509 certificate)
which you will be able to use.
Some URLs which might be useful:
* http://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/design-tools.html
* http://www.xilinx.com/products/design-tools/ise-design-suite/ise-webpack.htm
* http://www.armadeus.com/wiki/index.php?title=ISE_WebPack_installation_on_Linux
Once you've downloaded the ISE installation tarball and the license
file, you should place copies of them in this directory (the one with
all the dockerization stuff).  Since these were probably painful to
obtain, you might want to store the files somewhere else (eg, the
parent directory), chmod them 444, and hard link them into this
directory.
After you've added those files to this directory, typing make
should, in theory, build the whole thing.  It takes a ridiculously
long time to build, but we dont' expect this to happen often.
Legal caveat
Note that the resulting Docker image contains a licensed copy of the
build environment, so passing it around to your friends or installing
it on more machines than the license allows is a no-no.  We're not
attempting to circumvent XiLinx's licensing system, just make it
possible to run builds which require ISE in a reproducable Dockerized
environment.
Grotty details
Readers familiar with Docker wiil notice that this build environment
is...kind of weird.  Partly that's because of the size of some of the
files involved, but mostly it's because the Xvfb/ratpoison hack we're
using to drive ISE installation doesn't work under docker build.
Don't know why, don't really care (so many windmills, so little time).
Current status


Building the bitstream and the HSM firmware works.


Building the fimrware tarball doesn't work yet, because
  releng/alpha/Makefile assumes it can use the releng PGP key.  This
  will require a minor change to releng/alpha/Makefile and the
  supporting scripts, deferred until we figure out what other changes
  are needed for anyone other than the rleease engineer to use this.


Building the host-side source packages (tarball, .dsc, .rb)
  should work once firmware tarball problem solved.


Running pbuilder within Docker does not look practical.  There are
  several Docker-friendly alternatives, eg whalebuilder, but nested
  Docker is a bad idea, so either we'd have to work out the socket
  hack for automated Docker-next-to-Docker or we'd leave building
  binary packages for the user.  Not clear that ordinary user really
  wants us to spend the time building binary packages for every
  supported Debian and Ubuntu release anyway.


So we have some restructuring to do in releng/alpha/, probably with
some automated conditional tests to see whether we have the releng PGP
key, etc, with things rearranges so to make it easier for an
ordinary user to run the dockerized stuff and further conditionals and
make variables to let the user specify which binary packages to build
(if any).