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

[Joachim Strömbergson]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Aloha!

Thanks for the reply. This is a good discussion.

Rob Austein wrote:
> Other than the missing documentation, this is pretty good, as far as 
> it goes.

Ok. Lets start by discussing and decide what documentation we need for
design objects and systems.

To me a design object is a separate piece of design. For example a
HW-core or a SW-library, a set of schematics, a sub system etc. A design
object is stored as a separate repo in the repo server. The object may
have dependencies on other design objects. But in terms of
documentation, the design object should be self contained. That is, if I
clone a repo for an object I should find enough info in the repo to know
what it does, how to build and use it. This includes info about what
other objects to clone and what environment the object assumes.

To me the README file I presented is a first attempt at providing that
kind of information. But a README is rarely the complete documentation
but rather a short introduction to the object and the repo itself.

We should therefore in my opinion have somegthing like a doc/ dir in
each repo for the real documentation. What is available there will vary
with the specific object (object type - HW core, SW-lib, SW tool etc).

For a HW-core the general documentation is normally called Design
Specification or Data Sheet. Sometimes you also have a Programmers
Reference or similar (if the object is a CPU). Sometimes one also has a
Product Prief or Flyer that gives a fast intro with key points and a
nice illustration. A bit like the README, but more focused on the object
itself. And prettier.

I would like to have to write as few documents as possible and would
therefore have a single technical document unless it becomes cumbersome.
Refactor when needed basically.

I my view, for a HW-core the prio order is:

(1) README with a short intro.
(2) Data Sheet - with expanded stuff from READMEs, missing stuff.
(3) Flyer

And then we have the Wiki that at least should contain something close
to the README and the Flyer and then a link to the doc/ in the object repo.


We also need to discuss what the Data Sheet needs to contain. My attempt
at the README was an attempt at doing that. Your comment on the missing
API tells me I failed pretty hard. ;-)

Finally, bikeshedding, what document formats to use? My suggestions are:

(1) README in either plain text (UTF-8) or Markdown.

(2) Data Sheet and Flyer as PDF. With source in ODT or Tex stored in
doc/ too. That is two files for each type of file.



> 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".

No. To me, toolruns/ is where all tools are executed. This includes
compilers, simulators, linters, synthesis tools etc. When I for example
build the TRNG for the two different TerasIC boards I use I have:

  trng/toolruns/quartus/terasic_de0/
  trng/toolruns/quartus/terasic_c5g/

That is, I have a subdir for the build tool Quartus and then a separate
subdir for each specific target (and thus Quartus project).

If I were to run the simular ModelSim I would create:

  trng/toolruns/quartus/modelsim/

And allow the tool to do its magic in there.

As you have seen from using ISE, FPGA tools have a tendency to generate
a huge number of files and dirs. This way of using toolruns makes it
possible to keep it under control. This is esp important since one often
uses 3, 4, 5 or more tools. Right now I'm for example using Icarus
Verilog, ModelSim, Altera Quartus, Xilinx ISE (and several of its
separate tools) and Verilator.

One isse here is how to handle tools specific input files such as design
constraint files, but also project files (that defines files to
include). Right now I add these to the repo where the tool uses them,
for example in the quartus/terasic_c5g dir. But this might not be the
best place. My view is that they are related to the specific target and
thus belongs there.


Another issue is generated implementations such as a bitfile for a
Xilinx based design. I think that we want to provide ready made files
and notforce people to always build their own bitfiles. I think these
files should be in the repo and in the specifc platform subdir in the
repo. Others are hardline on never checking in generated files.


> 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.

I agree. And and is missing is multi-pronged thing:

(1) Each object needs to describe what it does, how to use it and what
it assumes to be possible to use.

(2) For subssystems, it also needs info on how it relates to other cores.

Here we have an important thing to decide - the relation between HW
cores and SW drivers. Should drivers be a separate design object or part
of the HW-object? I assume they can be different as long as the objects
points to each other.

Graphs are good.


> 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.

My README and esp the table was a first attempt at that. What you
normally have for a core is:

(1) A description of logical and possibly even the electrical interface
including timing access reastrictions.

(2) A memory map with all memories and registers. The memory map
describes what each register do, how you may access it (Read/Write),
preconditions and postcoditions including side effects, possible errors,
intrerrupts that can be caused etc.

(1) was very badly described. (2) was started in the table. My hope was
this would be good enough to get feedback on to improve, not just
"missing". ;-)

Lets flip it around - when you talk about an API, what are you
expecting. You are the consumer here and the HW description should
support you.


> 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?"

Yes. No. Possibly. It depends. ;-)

Coretest is as it name implies something I developed to allow us to test
one or more of our cores on one of our platforms by hooking the cores to
coretest and coretest to an extrernal interface. And then you possibly
have another level on top of this to connect all these cores together
and to ports that are mapped to real wires on the specific platform.

Depending on what we our any Cryptech user wants to call a Cryptech
system and what platform is used, coretest might be exactly everything
that is needed. If one wants a SHA-256 hash engine via I2C on Novena,
the top level Cryptech HW entity will be what we have today.

But if we want to have a more intelligent, self contained Cryptech, the
top level might be something completely else with an internal CPU core
that talks to the core. The core access arbiter for the CPU might still
look very much like coretest, but might also be something very
different. One such could be an ARM AHB bus.

For Novena with EIM, my guess is that we will need to develop a little
bit smarter coretest that handles batches of commands and data. But what
it actually will be is to a large degree decided by you based on how you
want to see and access the HW. If you want a lot of registers visible in
a memory map you will get something close to coretest.

If you instead want a higher level access solution with commands and
data in one or more blocks, the parser in the HW will be more complex
and at least have some sort of translation layer above coretest.

Fredrik has talked about a co-op with Yubico on defining a SW/HW access
layer for HSMs, which is what we are talking about here. This may be the
opportune moment to start doing that.

Fredrik - any news and thoughts about this?


Now I need to get back to coding.
- -- 
Med vänlig hälsning, Yours

Joachim Strömbergson - Alltid i harmonisk svängning.
========================================================================
 Joachim Strömbergson          Secworks AB          joachim at secworks.se
========================================================================
-----BEGIN PGP SIGNATURE-----
Version: GnuPG/MacGPG2 v2.0.22 (Darwin)
Comment: GPGTools - http://gpgtools.org
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQIcBAEBCAAGBQJUZdTWAAoJEF3cfFQkIuyNepwP/i/3PS9YK8xlEYbyhMlo0YCc
e8/U2IyDkOruu2pqizlMtVy3BGsE8RWIp4mrAjtJtLktrnHIxhic0vQRostUE5nD
TSzTsWqJnvruTtx2OW+pymmJoAEj3SyKwhR4QPOam2+4LZys2p8XLeGSrdtCBYxr
79hVyXxpsPhTtHdgn07V2H6c8qTNkZmReb63KPzl5JtoCxoLeZZl0oCm24vq/w4B
TEAYbqimbmlyMnJ41BzdQfLIu6AgA2N9Zt+SccdKeosqIUsoFkaRS9kq1YxJ/C98
HN5hiCpmLjbyKEqwGh5VvnNlSyA3y+djo3hZf7ep3Qztc6TKUEhwxnIp1WZ6bI8Y
hEQf42xPeaYhpwH3PbzRhzL7kRZB5/gaAhE+4bmf+1xGUnQTjLg/Q9iQOSBEaZGZ
wX9kP42tE+Yk/Zmc+vlyC+ayAGMJpIvM1GERntwGNJPeO9KVjDaOmcvw5RXkKztE
I9wD54q5M5Wka6nkx2T4P50efECWvBuOQerQnYWZz6RZC/MTBPLdQCviva41FlZI
mdXWcDqc8xFOKcbyJZCIIdWU+EwqEZXOzGLzDdmkG9qO8POkV3HlpUZWpNMLpGPn
oDCHKOU4DR9wk+Mi3pJ75YcU/ksST1RpnDqRVthLxWw812/tO+UBFHul9FZB8u+R
uj9MCs/ZGpG4hFTX26Ed
=9kTj
-----END PGP SIGNATURE-----