[Cryptech Tech] Updated README - and discussion on needed documentation

[Rob Austein]

At Fri, 07 Nov 2014 15:20:00 +0100, Joachim Strömbergson wrote:
> 
> I've updated the README.md for the sha1 core in a feeble attempt at
> making it more understandable. It is also an attempt at having something
> to discuss around in terms of what we want to rapidly provide in terms
> of documentation.
> 
> Rob, can you look at this and see if it makes any sense for you as a SW
> guy looking at writing driver and HAL:
> 
> https://trac.cryptech.is/browser/core/sha1/README.md
> 
> What critical stuff are you missing, what is confusing?
> 
> And yes, the API description can be expanded a lot, but this is just to
> have something to discuss around.

Other than the missing documentation, this is pretty good, as far as
it goes.

Nit: The description of toolruns/ is kind of circular, and assumes one
knows what kind of tools one wants to run there.  I think maybe you
mean "test tools" or something like that, since as far as I can tell
everything there is running stuff that in a software world one might
lump under "make test".

The big thing that's missing from all of this (not the SHA-1 core in
particular) is a description of how the existing cores (crypto and
otherwise) fit together, what the requirements are for hooking them up
to form something useful, what we expect the user to supply, and so
forth.  The verilator-derived dependency graphs were my feeble attempt
at trying to get something to draw me a picture of all of this so I
could see how the pieces fit together.

If these were software libraries, I'd say that what's missing is the
API documentation.  Not sure quite what the translation of that into
the Verilog universe would be, but I suspect you get the idea: while
the ability to audit all of this is critical, a software engineer
trying to use this stuff just wants to know how to talk to it.

One overall thing that confuses me: at present we're hooking just
about everything up into coretest, which makes sense, but when
somebody integrates this, aren't they going to need something that
fills the same role as coretest does for us?  Is that thing going to
look significantly different from coretest or is coretest just
misnamed or ...?  See previous "how does it all fit together", and
expand that to "how should this all fit together?"