[libre-riscv-dev] div/mod algorithm written in python

[Luke Kenneth Casson Leighton]

btw, jacob, there's a trade-off here, of python-code readability and
hardware-understandability.

the reason why the FP code (and the scoreboard code) is subdivided
into so many classes (and modules) is because the python code cannot
show you the connections that have been "lost" (not connected to
anything).

when adding the muxid it was flat-out impossible to track down... in
the *python* code... which variables had not yet been connected from
one stage to the next.

however by using yosys "show" on individual modules, it was IMMEDIATELY OBVIOUS.

the caveat was: if the nmigen module was so insanely large that not
even an 8k monitor would fit the graphviz with readable fonts, it was
just as impossible to even *find* the variables that had not been
connected.

thus it was *REQUIRED* to break down the code into smaller nmigen
modules that had as an absolute maximum (barely tolerable limit)
around 50 "boxes", with under 30 being much more acceptable but still
at an upper limit of readability.

the SIMD-splittable MUL code far exceeds that limit, comprising some
250 to 400 "boxes" that take something like one minute of 100% CPU
time to render.

that is not all: the consequences of the "unreadability" of larger
modules go well beyond compromising understandability, they will also
adversely impact the time it takes to create a layout.

if you look at the scoreboard dependency matrix code, it is very very
specifically subdivided into modules-of-modules.  the matrices are 2D,
however one module deals with 1 dimension, and *ANOTHER* module
creates an array of THOSE modules, to create the 2D.  ANOTHER module
joins the results (output) of each 1D array using OR (or NAND),
creating a 1-bit output that is then Cat'ed together to produce the
overall output from the DM.

*this is really important*.

so please: use graphviz to view the resultant code *every time you
save a file*, and if you can't read it, or the rendering of the
graphviz takes an unacceptably long time, take that as an absolute top
priority sign that the code *must* be split into separate nmigen
modules.

if you don't do that, i will have to do it.

after there are unit tests in place is fine, however it would be
better for each sub-module to have its own unit tests (just like in
samuel's work).

l.