1 files changed, 160 insertions, 0 deletions
diff --git a/markdown/StateOfPlay.md b/markdown/StateOfPlay.md
new file mode 100644
index 0000000..b9b448b
--- /dev/null
+++ b/markdown/StateOfPlay.md
@@ -0,0 +1,160 @@
+[[PageOutline]]
+
+# A Completely Informal Snapshot Of The Current State Of The Cryptech Project As Of 2014-11-06
+
+This page contains a snapshot of the status in the project and will almost certainly be obsolete by the time you read it.  If you find something that's wrong, please fix it!
+
+
+## Cores
+We have a bunch of cores, primarily for FPGA implementation.  Some of them implement cryptographic
+algorithms or critical functionality like the TRNG. Other cores are support cores for implementation of the Cryptech HSM. Other cores are for developing the cores and the HW. Finally some are just test
+code.
+
+Cores that have been promoted to official cryptech HW cores:
+
+
+* `core/chacha` - The ChaCha stream cipher
+* `core/sha1` - FIPS 180-2 SHA-1 hash
+* `core/sha256` - FIPS 180-4 SHA-256 hash
+* `core/sha512` - FIPS 180-4 SHA-512/x hash
+* `core/trng` - The Cryptech TRNG sub system. Uses ChaCha, SHA-512 and entropy cores.
+* `core/avalanche_entropy` - Avalanche entropy provider core. Requires external avalanche noise source.
+* `core/rosc_entropy` - Digital ring oscillator based entropy provider core.
+
+
+Utility, test, board support:
+
+
+* `core/coretest` - Core for performing command/response operations to drive testing of a core.
+* `core/coretest_hashes` - Subsysem with coretest and the hash function cores as test objects.
+* `core/coretest_test_core` - Coretest with a simple test core
+* `core/i2c` - I2C interface core.
+* `core/novena`
+* `core/novena_eim`
+* `core/novena_i2c_simple`
+* `core/test_core`
+* `core/uart`- UART interface core to allow serial communication with FPGA functionality.
+* `core/vndecorrelator` - von Neumann decorrelation core.
+
+
+Documentation is very haphazard: some of the repositories have
+detailed README.md files, but in many cases the documentation, what
+there is of it, is probably meaningful only to the person who wrote
+it, not because of any lack of good intent, just because what's
+written assumes that the reader knows everything that the author does
+about the other cores, the rest of the environment, and how everything
+fits together.
+
+## Builds
+
+At this point I have figured out how to build two different FPGA
+images for the Novena PVT1.  In both cases, I'm using the Makefile
+rather than attempting to use the XiLinx GUI environment.
+
+
+* `core/novena` builds the current set of digest cores into a
+
+  framework that uses the "coretest" byte stream protocol over an I2C
+  bus.
+
+
+* `core/novena_i2c_simple` builds the current set of digest cores into
+
+  a framework that uses a simplfied write()/read() API over an I2C bus.
+
+There's a third build, `core/novena_eim`, which was only just updated
+today, and which is reported as not quite stable yet.  Will try
+building it soon and report here.
+
+Both working builds (and, almost certainly, any useful build) involve
+more than just the named repository.  `verilator`, when asked nicely,
+will draw a graph of Verilog module relationships.  Take this with
+salt, as I am a long way from getting `verilator` to run cleanly on
+any of this, but the current graphs may still be useful in visualizing
+what's happening here.
+
+At least some of the modules that `verilator` complains about not
+being able to find appear to come from XiLinx libraries that
+`verilator` doesn't know about.
+See [Libraries Guide for HDL Designs]]([http://www.xilinx.com/support/documentation/sw_manuals/xilinx12_1/spartan6_hdl.pdf|Spartan-6) for details.
+
+### Module relationships in core/novena build
+
+[[Image(novena__linkcells.svg)]]
+
+### Module relationships in core/novena_i2c_simple build
+
+[[Image(novena_i2c_simple__linkcells.svg)]]
+
+### Module relationships in core/novena_eim build
+
+[[Image(novena_eim__linkcells.svg)]]
+
+### Module relationships in cores/trng build
+
+By special request, here's a graph for the TRNG too, even though we
+don't yet have a way to speak to it from the Novena:
+
+[[Image(trng__linkcells.svg)]]
+
+## C Code
+
+Most of the cores have at least minimal test frameworks, written in a
+combination of Verilog, C, and Python, but there's also a preliminary
+port of Cryptlib to the Cryptech environment, in `sw/cryptlib`.  As of
+this writing, the only Cryptech-specific features of this port, other
+than a few makefile tricks, are:
+
+
+* A set of HALs that make use of the `core/novena` and
+
+  `core/novena_i2c_simple` FPGA builds, using the Linux /dev/i2c
+  device interface; and
+
+
+* Another Python script to test the resulting Cryptlib build, using
+
+  the stock Cryptlib Python bindings.
+
+No HAL for `core/novena_eim` yet.
+
+The Cryptlib Python bindings build kind of slowly on the Novena, sorry
+about that.
+
+## Hardware
+
+The hardware guys have done cool stuff with hardware entropy sources.
+I even have one of the noise boards, but until I have some way to
+connect C code to the TRNG, I don't have much use for it other than to
+admire the craftsmanship.  Soon, I hope.
+
+## Tools
+
+Already mentioned `verilator`.  In addition to generating GraphViz
+input, `verilator` has a `--lint` mode which looks interesting.
+
+(JS) Verilator is fairly usable, at least as a linter. Adding `-Wall` provides more warnings.
+Since we at least uses Icarus Verilog (iverilog), Altera Quartus and Xilinx ISE one would assume that they would provide all possible warnings. That is not the case. They all seem to fins different things to warn about. And Verilator provides even more. The more parsers and checkers the better. But we will not be able to, or want to fix all warnings. Some things are by design. We should probably document what we ignore.
+
+I haven't yet figured out whether we have any real use for
+`verilator`'s core function of synthesizing Verilog into C++.  I've
+been toying with the idea of a software-only development environment,
+where one simulates an embedded machine using two Unix processes: one
+would be a virtual FPGA generated by `verilator`, the other would be a
+classical deeply embedded system running as a single process.  The two
+processes would communicate via a `PF_UNIX` socket or something on
+that order.  It might be possible to jam everything into a single
+process, but I suspect it wouldn't be worth the trouble.
+
+Joachim has Makefiles which use `iverilog` to generate simulation
+images.  Installing `iverilog` is easy enough (`apt-get install`, etc)
+but I haven't yet figured out how to do anything interesting with the
+simulation images.  Joachim replies:
+
+    There is help in the Makefile.  You run the targets, either as
+    make sim-foo or just ./foo.sim.  Most if not all tests are self
+    testing with test cases and should report number of test cases and
+    how many passed.  Which should be all.
+
+As far as I know we've done nothing yet to deal with threats to the
+tool chain (Thompson attack, etc).