[libre-riscv-dev] Debug port (was Re: minimum viable ASIC)

[Luke Kenneth Casson Leighton]

On Wed, May 20, 2020 at 5:44 PM Staf Verhaegen <staf at fibraservi.eu> wrote:
>
> Luke Kenneth Casson Leighton schreef op vr 08-05-2020 om 23:19 [+0100]:
> > ---crowd-funded eco-conscious hardware: https://www.crowdsupply.com/eoma68
> >
> > On Fri, May 8, 2020 at 6:23 PM Staf Verhaegen <staf at fibraservi.eu> wrote:
> >
> > ah.  as a software engineer, the practice of using wildcard imports isan extremely bad one.  i strongly advocate *not* getting into thehabit of doing "from nmigen import *" everywhere - it will make yourlife - and other users lives - absolute hell when it comes to tryingto track and debug code.
> > minerva has a JTAG interface as well.  i corrected the practice ofusing "import *" in this one
>
> Would 'import nmigen as nm' work for you?

and then have everything as "x = nm.Signal()...." and so on?  yes that
would be really good.  i actually worked for a company that made it
mandatory to use the full explicit module name (and used this trick to
get round the issue of ridiculously long names).

they required:

import nmigen
x = nmigen.Signal()
...

however it gets very, very tedious.

import nmigen as nm
x = nm.Signal()

is actually a really good idea.  saves space, explicitly says where
the "thing" (Signal etc.) come from.


> I did not touch code for a few months and in the mean time I do use a more PEP compliant code style.
> But I am annoyed by the individual list of things to import.

Staf: trust me on this one.  the hell it creates for people other than
yourself is beyond measure.  the imports serve a secondary critically
important purpose of documenting _where_ a given variable (class) may
be located.

"import *" completely and utterly obliterates that trail, making
maintenance and code-readability by other people an absolute
nightmare.

> For nmigen or Hurricane there is typically a few lines of these includes.

you quickly get used to cut/pasting from other files.

> When I change for example a Pad to a Rectilinear I may have to update the import list.

and other people when they read that code will be able to track that
change.  i have absolutely no idea what Pad is, nor Rectilinear, for
example.

where should i start looking for it?

which module?

which *package* even?

are they in... nmigen?

are they in Hurricane?

are they in something else that has been wild-card imported?

i *literally* cannot tell, and that makes everyone's life absolute
hell.  we - as users of that code - *literally* have to do "grep -r
Pad" in MULTIPLE source code directories - for completely different
packages (QTY 2 in this one example alone) - to track down where the
definition of "Pad" and "Rectilinear" exist!


> I don't see value add of this and it annoys me a lot.

this is down to inexperience with collaborative python development.  i
say that with no disrespect: it's just that i've used python for 20
years and have seen a lot.

> So I am thinking of switching to 'import Hurricane as hur' and 'import nmigen as nm'

> To me the only valid reason for not using wild cards is that a later wild
> card import may replace something you did import before;

two things (both equally as important):

1. that is down to inexperience from developing python.  *nobody* who
is an experienced python developer uses wildcard imports except in
very, very special mitigating cases

2. you are absolutely correct: this is *another* important reason.

there are many more.

> this is avoided by namespacing the import with 'import ... as ...'.

yes, it is a good trick.

> > also provided a wishbone master interface:
> > https://git.libre-soc.org/?p=soc.git;a=blob;f=src/soc/minerva/units/debug/wbmaster.py;h=db02af95b4eb3ef8ac25b348f3abaa2bcbe7d96f;hb=a54adcb65bad37b398b11e33a824c7d08c5fe509
>
> That code seems to focus on the debugging protocol over the JTAG interface the lower level part seems to be missing.In debug/top.py:...
> # FIXME: figure out where JTAGTap is
> # from jtagtap import JTAGTap
>
>
> class JTAGTap:
>     def __init__(self):
>         raise NotImplementedError(
>             "jtagtap package not found: figure out where JTAGTap is")
> ...
>
> My JTAG interface does actually the low level part,

ahh that's very interesting to note.  ah that's then a really good
combination, of the two.  one is the external interface, the other
more internal.

> the protocol has to be done by the user on top of it. I do think I have a flexible way of adding extra shift registers and jtag commands. I also do provide boundary scan for the IO pins which should make PCB testing much easier (BTW, this was actually the original use case for JTAG).

ah, really appreciated.

l.