[Cryptech Tech] Documentation, I2C, and an embarrassment of options

[Rob Austein]

So I'm most of the way through writing a Cryptlib HAL to plug into the
current set of Cryptech digest cores on the Novena using the I2C bus.
Silly me, I thought that it would make sense to start with the test
code associated with the documented build path for the FPGA image and
work outwards from there.

It seems that we have (at least) two different I2C interfaces to the
digest cores on the Novena, with very different APIs:

- There's the stuff that's (sort of) documented in the Novena build
  instructions, in the core/novena repository, using a very chatty
  protocol to talk to all the digest cores using a single I2C slave.

- Then there's the stuff in core/novena_i2c_simple, which implements a
  streamlined protocol using a separate I2C slave for each core.  This
  looks pretty nice, but there's no documentation on how to build
  the FPGA image for it.

At the risk of channeling Randy: what is a developer trying to use
this stuff supposed to do here?  Which I2C interface should I use, and
how do I build the FPGA image?  Why do we have multiple APIs, and
under what circumstances would I want to use the other one?

I think we are going to have to bump the priority of documentation.
We really need descriptions of current state, how to build, and advice
in cases where we're offering multiple ways of doing the same thing.

I am also puzzled by the repository naming scheme.  I thought we were
trying for something where we had some separation between
device-independent cores and board-support stuff, but it all seems to
be jumbled together in the core/ directory, along with at least four
separate test frameworks.

Last, I noticed that, at present, there seems to be no I2C interface
to any of the TRNG stuff.  This is a pity, as we've put a lot of work
into the TRNG and the HAL API really wants a source of randomness.
I'd consider volunteering to do something about this, but I suspect
that the TRNG would be a particularly bad first Verilog project, since
the output is supposed to be (very high quality) garbage.

For the moment, I will press on with the chatty I2C API, since that
seems to be the one for which I know how to build the FPGA image.
Advice on what else I should do would be welcome.