Re: [Simulavr-devel] doRun() and doStep() - how to use it?

[ThomasK]

Hi Andrey,

just to have a quick answer:

> Try to use simulavr to unit-testing my firmware. In example folder found python 
> examples, but - found absolutely no documentation about python API. Is it means 
> that there is no such documentation, only source code?

Unfortunately yes! I'm responsible for the most python code in examples 
and a part in regress directory. And, you're right, it's just source and 
sometimes a few comments in python code. So, it's not really a good 
start for somebody with not much knowledge about C++ and python.

What do you need to know to understand this? Python interface is made by 
SWIG, this is a tool, that transforms C++ interface, classes and 
functions to a python interface. So, the python api, which is build by 
SWIG reflects the C++ api! Above this I wrote some utility functions and 
classes to make live easier. So, everything starts by understanding C++ 
interface.

I think, your snippet is from example.py in examples/python directory. 
So I'll try to comment some lines to get a little bit help:

> import pysimulavr

This is the import of simulavr SWIG interface!

> from ex_utils import SimulavrAdapter

Just some utility classes ...

Ok, I hope, you have a little bit knowledge about unit tests?

> def setUp(self):
> proc, elffile = argv[1].split(":")
> self.device = self.loadDevice(proc, elffile)

This creates the "processor", but you need not the second line, this is 
only to get processor type and path to elf file out from a commandline 
argument.

> def tearDown(self):
> del self.device

Shutdown DUT

Now a test case:

> def test_03(self):
> "check PC and PC size"
> self.assertEqual(self.device.PC_size, 2)
> self.doRun(0)
> self.assertEqual(self.device.PC, 0x8c / 2)

What's made here: check size of PC, just to be sure, in the original 
example are 2 step commands, you have replaced it with "self.doRun(0)", 
doRun runs your code till a stop time. You have set it to 0, so it stops 
immediately. And then we check, if the PC has arrived a expected value. 
In case of my example, this is 0x8c, divided by 2, because every 
microcode on processor is build by 2 byte and PC holds word count not 
byte count!

> AssertionError: 0 != 70.

That's the result for your first run, you've made 0 steps (because of 
doRun argument 0, see above) and the PC is 0

> AssertionError: 34 != 70

Here you've made one step (I think) and arrived the address of init 
label. (as you wrote) If you replace your "doRun(0)" by 2 "doStep()" or 
one "doStep(2)", you would go 2 processor steps. Maybe replace the 
"assertEqual" statement, which is to test the expected values by a print 
statement: "print self.device.PC", so you would get the PC after this 2 
steps. And, if you run, for example, 100 steps, you should be only in 
your main loop. And you could also get "processor system time" in clocks 
by "print self.GetCurrentTime()".

Hope, this helps a little bit.

cu, Thomas