INTRO
=====

This is the documentation for the .pbsim file format, generated by "pb_parse -g".

These logs are designed to record the output of a simulated pulseblaster, for replay into a simulator of the target hardware 
(the device connected to the PulseBlaster). This allows correctness-testing of an entire chain of software.
So, they contain a very simple, parseable format, containing the OUTPUT and the LENGTH. The logfile is similar to
the piano-roll output, in that it contains a version of what the PulseBlaster will do, rather than the code that drives it.

These files are potentially very large (if the PulseBlaster program doesn't terminate, the file is potentially infinite!),
and it may be advisable to use a named-pipe, or at least invoke the parser with "-u" to limit the number of steps.

For an example that uses this, see hawaiisim (which also contains a C parser for the pbsim format).


FILE FORMAT
===========

In general, this is quite similar to the .vliw file format.

0. Blank lines should be ignored.

1. Comments. A line beginning with '//' is a comment. Comments usually belong in the header, but
   may be inserted later.

2. All other lines contain data, on exactly 2 columns, separated by whitespace.

     Output	Length

3. The output is the value output by the parser. This is a 24-bit value, which will be output in Hex format, and may be parsed as an unsigned_long  (uint32).
   Similarly to the pulseblaster, this is big-endian.

4. The length is the time for which this output is asserted. This is a ~ 60-bit value, which will be output in Decimal, and may be parsed as an unsigned_long_long (uint64).
   The length is given in ns (nanoseconds), NOT in pulseblaster ticks, since this logfile should be independent of the device once generated.
   It is normally shorter than uint64, but could be this big (pulseblaster delay is 32-bit, x 24-bit arg for longdelay, x conversion from ticks to ns).

5. MARK opcodes insert the timestamps of breakpoints. These are formatted as special comments with the magic prefix "MARK:"  (because the feature was added after the format was first defined).
   Within this line, the sections are given as name=value, separated by tabs. Thus:
      //MARK:  \t  step=...  \t  ticks=...  \t  ns=...  \t  pc=...  \t  visit=...  \t  length=...  \t  out=...  \t  cmt=//...


EXAMPLE FILE
============


//This log file was generated by pb_parse from source file source.pbsrc on date 2011-01-12.
//File format: output (uint32), length (uint64). Note that length is in ns, not ticks.
//Mark opcode: '//MARK:  \t  step=...  \t  ticks=...  \t  ns=...  \t  pc=...  \t  visit=...  \t  length=...  \t  out=...  \t  cmt=//... \n'.
0x000001	1000000000
0x000002	1000000000
0x000003	1000000000
0x000004	1000000000
//MARK: step=4  ticks=400000000        ns=4000000000  pc=4    visit=0 length=100000000       out=0x000005      cmt=//Name of this mark.
0x000005	1000000000




NOTES
=====

* Repeated outputs:
	Each line probably corresponds to one pulseblaster instruction, because of the log implementation.
	However, repeated lines should really be combined. Don't rely on whether identical outputs are combined.
	After all, if the PulseBlaster outputs 0x1, 0x1, 0x2, the target hardware can't distinguish this from 0x1, 0x2.
	[On the other hand, multiple repeated long-delays can't be added without an overflow in the uint64!]

* STOP opcodes:
	A stop opcode does NOT change the output. No line will appear in the log. It will then EOF the log, and close the file.
	[Not like .vliw, where "-" is printed]

* WAIT opcodes:
	The vliw instruction "output, wait(-), length" does "Outputs, wait-for-retrigger, THEN delay length.
	The output in this logfile will be two consecutive lines.

		output	0
		output  length

	Therefore, the logfile can be read as if the wait never happened but simply auto-continued.
	Alternatively, by knowing that a length of zero can't happen in real-life, the WAIT-instruction can be inferred,
	and the log-reader can take some specific action.

* MARK opcodes:
	Mark is used to denote a breakpoint - it's useful for making measurements of precisely the interval between two points
	in a relatively complex program, where this needs to be simulated and calculated for subsequent purposes.
  	Apart from triggering the "MARK" message, this opcode is basically the same as CONT.

* Other opcodes:
	From the point of view of the attached hardware, and of this logfile, there is no distinction between the
	pulseblaster opcodes, excepting the special-cases on STOP and WAIT.


* Tips:
	When generating a logfile, the "-g" option implies -f. (In turn, this means the simlator won't necessarily terminated).
	If the program would never terminate, consider limiting the length of the log by using -u.

	The options -l, -p, t, z, j  are all possile, but not needed. -w will delay generation of logfiles without user-input.