[Libre-soc-bugs] [Bug 325] create POWER9 TRAP pipeline

[bugzilla-daemon at libre-soc.org]

https://bugs.libre-soc.org/show_bug.cgi?id=325

--- Comment #94 from Luke Kenneth Casson Leighton <lkcl at lkcl.net> ---
ok so let's go through how you could have determined, for yourself,
if the additions "would break" something.  there are two approaches:

1) run all unit tests.  that means all of them.  this basically means
   "nosetests3" at the top level.

   however this is only useful in cases where the unit tests all work
   already and where they do not take several days to complete
   (such as the ieee754fpu ones).

   therefore, perhaps a sensible thing to do would be to run
   *relevant* unit tests and only run the full lot perhaps once a week.

2) track the function that you're writing through (using source code
   grep and by asking questions) to see if it is actually used.


for (2) here, we can do this:

a) function is called TRAP therefore let us grep -r TRAP all python source.

   decoder/isa/caller.py:    def TRAP(self, trap_addr=0x700):
   decoder/isa/caller.py:        print ("TRAP: TODO")
   decoder/isa/fixedtrap.py:        if lt(a, EXTS(SI)) & TO[0]:self.TRAP()
   decoder/isa/fixedtrap.py:        if gt(a, EXTS(SI)) & TO[1]:self.TRAP()
   ...
   ...

b) the only location appears to be fixedtrap.py therefore we inspect that
   file.

   turns out it is called *only* by op_twi, op_tw, op_tdi or op_td.

c) now we need to work out how _those_ get called (we already know the
   answer, from our knowledge of the purpose of the simulator,
   but let's walk through it)

d) where does the class fixedtrap get used?  grep -r "fixedtrap" shows:

    decoder/isa/all.py:from soc.decoder.isa.fixedtrap import fixedtrap
    decoder/isa/all.py:class ISA(ISACaller, comparefixed, 
             fixedarith, fixedload, fixedstore, condition,
---->>       fixedtrap, fixedshift, stringldst, bcd, system,
             branch, fixedlogical, sprset):

   (a better way to have done that would be to grep by import as well:
    grep -r "fixedtrap" | grep import)

e) now we open all.py and find that it contains a class ISA which is
   multiply-derived from something that includes ISACaller

ah ha!

and, also, we noted some dictionaries from (d) which added op_tdi etc.
etc. to a dictionary fixedtrap_instrs

and that in all.py that dictionary merges into self.instrs.

f) therefore, we now focus our attention on ISACaller, looking for
   self.instrs.

    def call(self, name):
--->     info = self.instrs[name]  <----

g) therefore let us check where call() is called...

        def execute_one(self):
            opname = code.split(' ')[0]
--->        yield from self.call(opname)  <----

h) therefore we now grep -r for execute_one:

simulator/test_sim.py:                yield from simulator.execute_one()
fu/compunits/test/test_compunit.py:   yield from sim.execute_one()


and TA-DAAAAA!  now we know which unit tests to call!

or, we can continue with further examination of the chain (and also
check if ISACaller.call() is also used somewhere - which i believe
it is).  and part of that continued investigation will find
(grep -r "test_compunit") that test_compunit.py contains a base class
from which multiple unit tests derive or import and consequently we
need to examine those (or just simply run them).

if we _did_ examine them we would find that ABSOLUTELY NONE of the unit
tests make an assembly code call "tdi", or "twi" and so on.

and we know this also because we have been discussing adding them and
*have not yet done so*.

therefore our examination of the trail happens to link back up with our
internal knowledge and expectations.

with zero of the unit tests calling "trap" opcodes, we **KNOW** that the
ISACaller.TRAP() function cannot be called, and that, therefore, no matter
what we put in it there *can be no quotes damage quotes whatsoever*

despite appearances this task did not take long.  perhaps a couple of minutes.
however it determined *for ourselves* that there can be no "damage".

this skill - the willingness to apply this technique - is something that
you really must develop for yourself, and i describe it in summary form
in the HDL_workflow.

in addition, you will notice how many files were opened up during that
process.  a *lot*.

and *this* is also why it is so essential to have the code respect the 80
char limit, because if you have 6, 8, 10 files open and are working with
them or referring to them all the time, you *need* as many terminals
on-screen as you can possibly get.

if those files "wrap" over it becomes a readability headache that
significantly decreases everyone's productivity.

-- 
You are receiving this mail because:
You are on the CC list for the bug.