or1ktrace
				=========

About:
======
This is a library intended to be used by OpenRISC 1000 simulation models to 
generate execution traces.

It's handy because you don't have to write a disassembler in every single
model you have - just link to this guy and generate consistent traces across
all models, which makes them easy to debug and compare.

That's the idea, anyway.

Building:
=========

So far, the library builds and the basic disassembly test runs. But it is not
automated or pretty.

* prerequisites
  Make sure that libbfd.so and libopcodes.so are available. These libraries
  can be built by setting --enable-shared when building binutils.

* Configuring
  Run ./configure but also pass the location of a binutils compile directory
  so it can pickup the libbfd and libopcodes archives and headers it contains.

      ./configure \
      BINUTILS_BLD_DIR=$<path to toolchain>/x86_64-unknown-linux-gnu/or1k-elf

  Next, run make to build the libraries and a test program.

      make

  If make complains about libor1ktrace.Tpo, make sure to run autoreconf -i prior
  to configure
Testing:
=======

  Run the disassembly test executable with:

      ./testasm

Using:
=====

The trace library must be initialised to set up pointers and the like:

* Init

    or1ktrace_init( unsigned long int  (*get_mem32)(unsigned long int),
		     unsigned long int  (*get_gpr)(int),
		     unsigned long int  (*get_spr)(int),
		     int or1ktrace_debug_on);

get_mem32 is a function to read 32-bit memory values from the simulated models'
memory system. The read data is returned via the function's return value.

get_gpr is a function to read the CPU's general purpose registers (GPRs).
get_spr is a function to read the CPU's special purpose registers (SPRs).

or1ktrace_debug_on should be set to non-zero to generate debug information
to stdout. It's not advised it's used.

get_mem32 is always mandatory, but get_gpr and get_spr are only required for
full execution trace generation.

* Instruction disassembly

There's a function to return just the binary instruction's disassembly string.

	int or1ktrace_gen_insn_string(unsigned long int addr, 
	    				       char* insn_string_ptr);

Should be simple enough - pass the address of the instruction and expect the
string pointed to by insn_string_ptr to have the disassembly in it. The length
of the string is returned by the return value of the function.

* Trace generation

A full execution trace line can be generated with the following function:

  int or1ktrace_gen_trace_string(unsigned long int addr, 
      					  char* trace_string_ptr);

This outputs a line indicating:
     * user/supervisor mode as per the supervision register
     * current PC (actually just the addr value)
     * current instruction binary value
     * current instruction disassembly
     * result of instruction (SPR write, destination register or memory store)
     * flag

It works the same as the gen_insn_string function, but just generates a 
different output.

* Installing:
=============

I wouldn't do this yet...

TODO:
=====

 * Plumb it into or1ksim for starters, and check the full trace line works.
   Next try to get it into Verilog and cycle accurate RTL models.
 * Double check whether all the callbacks are really needed.
 * Maybe add a binary trace option where we sort out a data structure that 
   can be dumped to a file for greater speed. This would also involve somehow
   decoding the function back into trace lines.