<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<title>LXT Explained</title>
</head>
<body text="#000000" bgcolor="#ffffff" link="#0000ee" vlink="#551a8b" alink="#0000ee">
<b><u><big><big>LXT File Format:</big></big></u></b><br>
<br>
This document will use lxt_write.h (as found in src/helpers) as its source for various constant
definitions. The three most important values in an LXT(interLaced
eXtensible Trace) file are the following:<br>
<br>
<tt>#define LT_HDRID (0x0138)<br>
#define LT_VERSION (0x0001)<br>
#define LT_TRLID (0xB4)</tt><br>
<br>
An LXT file starts with a two byte LT_HDRID with the two byte version
number LT_VERSION concatenated onto it. The last byte in the file
is the LT_TRLID. These five bytes are the only "absolutes" in an
LXT file.<br>
<br>
<tt>01 38 00 01</tt> <i>...file body...</i> <tt>B4</tt><br>
<br>
As one may guess from the example above, <i>all</i> integer values
represented in LXT files are stored in big endian order.<br>
<br>
<hr width="100%" size="2"><br>
<u><b><big><big>LXT Section Pointers:</big></big></b></u><br>
Preceeding the trailing ID byte B4 is a series of tag bytes which
themselves are preceeded by 32-bit offsets into the file which indicate
where the sections pointed to by the tags are located. The exception
is tag 00 (LT_SECTION_END) which indicates that no more tags/sections are
specified:<br>
<br>
<tt>00</tt> <i>... offset_for_tag_2, tag_2, offset_for_tag_1, tag_1,</i>
<tt>B4</tt><br>
<br>
Currently defined tags are:<br>
<br>
<tt>#define LT_SECTION_END
(0)<br>
#define LT_SECTION_CHG
(1)<br>
#define LT_SECTION_SYNC_TABLE
(2)<br>
#define LT_SECTION_FACNAME
(3)<br>
#define LT_SECTION_FACNAME_GEOMETRY (4)<br>
#define LT_SECTION_TIMESCALE
(5)<br>
#define LT_SECTION_TIME_TABLE
(6)<br>
#define LT_SECTION_INITIAL_VALUE
(7)<br>
#define LT_SECTION_DOUBLE_TEST
(8)<br>
#define LT_SECTION_TIME_TABLE64
(9)</tt><br>
<br>
Let's put this all together with an example:<br>
<br>
The first tag encountered is 08 (<tt>LT_SECTION_DOUBLE_TEST</tt>)
at 339. Its offset value indicates the position of the double sized
floating point comparison testword. Thus, the section location for
the testword is at 0309 from the beginning of the file.<br>
<br>
<tt>00000300: XX XX XX XX XX XX XX XX XX 6e 86 1b f0 f9 21 09
.........n....!.<br>
</tt><tt>00000310: 40 00 00 00 00 04 01 00 00 02 4b 02 00 00 00 be
@.........K.....<br>
00000320: 03 00 00 01 4b 04 00 00 03 08 05 00 00 02 8b 06 ....K...........<br>
00000330: 00 00 03 07 07 <b><u>00 00 03 09</u> 08 </b>b4 -- -- --
-- -- ...........</tt><br>
<br>
The next tag encountered is 07 (<tt>LT_SECTION_INITIAL_VALUE</tt>)
at 334. Its offset value indicates the position of the simulation initial
value. Even though this value is a single byte, its own section is defined.
The reasoning behind this is that older versions of LXT readers would
be able to skip unknown sections without needing to know the size of the
section, how it functions, etc.<br>
<br>
<tt>00000300: XX XX XX XX XX XX XX XX XX 6e 86 1b f0 f9 21 09
.........n....!.<br>
</tt><tt>00000310: 40 00 00 00 00 04 01 00 00 02 4b 02 00 00 00 be
@.........K.....<br>
00000320: 03 00 00 01 4b 04 00 00 03 08 05 00 00 02 8b 06 ....K...........<br>
00000330: <b><u>00 00 03 07</u> 07</b> 00 00 03 09 08 b4 -- -- --
-- -- ...........</tt><br>
<br>
The next tag encountered is 06 (<tt>LT_SECTION_TIME_TABLE</tt>) at
32F. Its offset value (the underlined four byte number) indicates the
position of the time table which stores the time value vs positional offset
for the value change data.<br>
<br>
<tt>00000300: XX XX XX XX XX XX XX XX XX 6e 86 1b f0 f9 21 09
.........n....!.<br>
</tt><tt>00000310: 40 00 00 00 00 04 01 00 00 02 4b 02 00 00 00 be
@.........K.....<br>
00000320: 03 00 00 01 4b 04 00 00 03 08 05 <b><u>00 00 02 8b</u>
06</b> ....K...........<br>
00000330: 00 00 03 07 07 00 00 03 09 08 b4 -- -- -- -- -- ...........</tt><br>
<br>
The next tag encountered is 05 (<tt>LT_SECTION_TIMESCALE</tt>) at
32A. Its offset value indicates the position of the timescale byte.
<br>
<br>
<tt>00000300: XX XX XX XX XX XX XX XX XX 6e 86 1b f0 f9 21 09
.........n....!.<br>
</tt><tt>00000310: 40 00 00 00 00 04 01 00 00 02 4b 02 00 00 00 be
@.........K.....<br>
00000320: 03 00 00 01 4b 04 <b><u>00 00 03 08</u> 05</b> 00 00 02
8b 06 ....K...........<br>
00000330: 00 00 03 07 07 00 00 03 09 08 b4 -- -- -- -- -- ...........</tt><br>
<br>
The next tag encountered is 04 (<tt>LT_SECTION_FACNAME_GEOMETRY</tt>
) at 325. Its offset value indicates the geometry (array/msb/lsb/type/etc)
of the dumped facilities (signals) in the file.<br>
<br>
<tt>00000300: XX XX XX XX XX XX XX XX XX 6e 86 1b f0 f9 21 09
.........n....!.<br>
</tt><tt>00000310: 40 00 00 00 00 04 01 00 00 02 4b 02 00 00 00 be
@.........K.....<br>
00000320: 03 <b><u>00 00 01 4b</u> 04</b> 00 00 03 08 05 00 00 02
8b 06 ....K...........<br>
00000330: 00 00 03 07 07 00 00 03 09 08 b4 -- -- -- -- -- ...........</tt><br>
<br>
The next tag encountered is 03 (<tt>LT_SECTION_FACNAME</tt>) at 320.
Its offset value indicates where the compressed facility names are
stored.<br>
<br>
<tt>00000300: XX XX XX XX XX XX XX XX XX 6e 86 1b f0 f9 21 09
.........n....!.<br>
</tt><tt>00000310: 40 00 00 00 00 04 01 00 00 02 4b 02 <u><b>00 00
00 be</b></u> @.........K.....<br>
00000320: <b>03</b> 00 00 01 4b 04 00 00 03 08 05 00 00 02 8b 06
....K...........<br>
00000330: 00 00 03 07 07 00 00 03 09 08 b4 -- -- -- -- -- ...........</tt><br>
<br>
The next tag encountered is 02 (<tt>LT_SECTION_SYNC_TABLE</tt>) at
31B. Its offset value points to a table where the final value changes
for each facility may be found.<br>
<br>
<tt>00000300: XX XX XX XX XX XX XX XX XX 6e 86 1b f0 f9 21 09
.........n....!.<br>
</tt><tt>00000310: 40 00 00 00 00 04 01 <b><u>00 00 02 4b</u> 02</b>
00 00 00 be @.........K.....<br>
00000320: 03 00 00 01 4b 04 00 00 03 08 05 00 00 02 8b 06 ....K...........<br>
00000330: 00 00 03 07 07 00 00 03 09 08 b4 -- -- -- -- -- ...........</tt><br>
<br>
The next tag encountered is 01 (<tt>LT_SECTION_CHG</tt>) at 316. Its
offset value points to the actual value changes in the file.<br>
<br>
<tt>00000300: XX XX XX XX XX XX XX XX XX 6e 86 1b f0 f9 21 09
.........n....!.<br>
</tt><tt>00000310: 40 00 <b><u>00 00 00 04</u> 01</b> 00 00 02 4b
02 00 00 00 be @.........K.....<br>
00000320: 03 00 00 01 4b 04 00 00 03 08 05 00 00 02 8b 06 ....K...........<br>
00000330: 00 00 03 07 07 00 00 03 09 08 b4 -- -- -- -- -- ...........</tt><br>
<br>
The final tag encountered is 00 at 311. It signifies that there
are no more tags.<br>
<br>
<tt>00000300: XX XX XX XX XX XX XX XX XX 6e 86 1b f0 f9 21 09
.........n....!.<br>
</tt><tt>00000310: 40 <b>00</b> 00 00 00 04 01 00 00 02 4b 02 00 00
00 be @.........K.....<br>
00000320: 03 00 00 01 4b 04 00 00 03 08 05 00 00 02 8b 06 ....K...........<br>
00000330: 00 00 03 07 07 00 00 03 09 08 b4 -- -- -- -- -- ...........</tt><br>
<br>
Note that with the exception of the termination tag 00, tags may be
encountered in any order. The fact that they are encountered in monotonically
decreasing order in the example above is an implementation detail of the
lxt_write dumper. Code which processes LXT files should be able to
handle tags which appear in any order. For tags which are defined
multiple times, it is to be assumed that the tag instance closest to the
termination tag is the one to be used unless each unique instantiation possesses
a special meaning. Currently, repeated tags have no special semantics.<br>
<br>
<hr width="100%" size="2"><br>
<b><u><big><big>LXT Section Definitions:</big></big></u></b><br>
<br>
The body of each section (as currently defined) will now be explained
in detail.<br>
<br>
<hr width="50%" size="2"><br>
<u><b><big>08: LT_SECTION_DOUBLE_TEST</big></b></u><br>
<br>
This section is only present if double precision floating point data
is to be found in the file. In order to resolve byte ordering issues
across various platforms, a rounded version of <i>pi</i> (3.14159) is stored
in eight consecutive bytes. This value was picked because each of
its eight bytes are unique. It is the responsibility of an LXT reader
to compare the byte ordering found in the LT_SECTION_DOUBLE_TEST section
to that of the same rounded version of <i>pi</i> as represented by reader's
processor. By comparing the position on the host and in the file,
it may be determined how the values stored in the LXT file need to be rearranged.
The following bit of code shows one possible implementation for this:<br>
<br>
<tt>static char double_mask[8]={0,0,0,0,0,0,0,0};<br>
static char double_is_native=0;<br>
<br>
static void create_double_endian_mask(double *pnt)<br>
{<br>
static double p = 3.14159;<br>
double d;<br>
int i, j;<br>
<br>
d= *pnt;<br>
if(p==d)<br>
{<br>
double_is_native=1;<br>
}<br>
else<br>
{<br>
char *remote, *here;<br>
<br>
remote = (char *)&d;<br>
here = (char *)&p;<br>
for(i=0;i<8;i++)<br>
{<br>
for(j=0;j<8;j++)<br>
{<br>
if(here[i]==remote[j])<br>
{<br>
double_mask[i]=j;<br>
break;<br>
}<br>
}<br>
}<br>
}<br>
}</tt><br>
<br>
If <tt>double_is_native</tt> is zero, the following function will then
be needed to be called to rearrange the file byte ordering to match the
host every time a double is encountered in the value change data:<br>
<br>
<tt>static char *swab_double_via_mask(double *d)<br>
{<br>
char swapbuf[8];<br>
char *pnt = malloc(8*sizeof(char));<br>
int i; <br>
<br>
memcpy(swapbuf, (char *)d, 8);<br>
for(i=0;i<8;i++)<br>
{ <br>
pnt[i]=swapbuf[double_mask[i]];<br>
}<br>
<br>
return(pnt);<br>
}<br>
</tt><br>
<hr width="50%" size="2"><br>
<u><b><big>07: LT_SECTION_INITIAL_VALUE</big></b></u><br>
This section is used as a "shortcut" representation to flash all facilities
in a dumpfile to a specific value at the initial time. Permissible
values are '0', '1', 'Z', 'X', 'H', 'U', 'W', 'L', and '-' stored as the byte values 00 through
08 in the LXT file.<br>
<br>
<hr width="50%" size="2"><br>
<u><b><big>06: LT_SECTION_TIME_TABLE / 08: LT_SECTION_TIME_TABLE64</big></b></u><br>
<br>
This section marks the time vs positional data for the LXT file. It
is represented in the following format:<br>
<br>
4 bytes: <i>number of entries (n)</i><br>
4 bytes: <i>min time in dump</i> (8 bytes for LT_SECTION_TIME_TABLE64)<br>
4 bytes: <i>max time in dump</i> (8 bytes for LT_SECTION_TIME_TABLE64)<br>
<br>
<i>n</i> 4-byte positional delta entries follow<br>
<i>n</i> 4-byte time delta entries follow (8 byte entries for LT_SECTION_TIME_TABLE64)<br>
<br>
It is assumed that the delta values are represented as <i>current_value
- previous_value</i>, which means that deltas should always be positive.
In addition, the <i>previous_value</i> for delta number zero for both
position and time is zero. This will allow for sanity checking between
the time table and the min/max time fields if it is so desired or if the min/max
fields are needed before the delta entries are traversed.<br>
<br>
Example:<br>
<br>
<tt>00000005</tt> 5 entries are in the table<br>
<tt>00000000</tt> Min time of simulation is 0<br>
<tt>00000004</tt> Max time of simulation is 4.<br>
<br>
<tt>00000000</tt> time[0]=0<br>
<tt>00000001</tt> time[1]=1<br>
<tt>00000001</tt> time[2]=2<br>
<tt>00000001</tt> time[3]=3<br>
<tt>00000001</tt> time[4]=4<br>
<br>
<tt>00000004</tt> pos[0]=0x4<br>
<tt>00000010</tt> pos[1]=0x14<br>
<tt>00000020</tt> pos[2]=0x34<br>
<tt>00000002</tt> pos[3]=0x36<br>
<tt>00000300</tt> pos[4]=0x336<br>
<br>
<hr width="50%" size="2"><br>
<u><b><big>05: LT_SECTION_TIMESCALE</big></b></u><br>
This section consists of a single signed byte. Its value (<i>x</i>
) is the exponent of a base-10 timescale. Thus, each increment of
'1' in the time value table represented in the previous section represents
10<i><sup> x</sup></i> seconds. Use -9 for nanoseconds, -12 for picoseconds,
etc. Any eight-bit signed value (-128 to +127) is permissible, but
in actual practice only a handful are useful.<br>
<br>
<hr width="50%" size="2"><br>
<u><b><big>03: LT_SECTION_FACNAME</big></b></u><br>
<br>
No, section 04: LT_SECTION_FACNAME_GEOMETRY hasn't been forgotten. It's
more logical to cover the facilities themselves before their geometries.<br>
<br>
4 bytes: <i>number of facilities (n)</i><br>
4 bytes: <i>amount of memory required in bytes for the decompressed facilities</i><br>
<br>
<i> n</i> compressed facilities follow, where a compressed facility
consists of two values:<br>
<br>
2 bytes: <i>number of prefix bytes</i> (min=0, max=65535)<br>
zero terminated string: <i>suffix bytes</i><br>
<br>
An example should clarify things (prefix lengths are in bold):<br>
<br>
<tt>00000020: <u>00 00 00 04</u> <u>00 00 00 1d</u></tt><tt> <b>00 00</b>
61 6c 70 68 61 00 ..........alpha.<br>
00000030: <b>00 01</b> 70 70 6c 65 00 <b>00 04</b> 69 63 61 74 69 6f 6e
..pple...ication<br>
00000040: 00 <b>00 00</b> 7a 65 72 6f 00 00 00 00 01 00 00 00 00
...zero.........</tt><br>
<br>
Four facilities (underlined) are defined and they occupy 0x0000001d bytes
(second underlined value).<br>
<br>
This first prefix length is 0000 (offset 28).<br>
The first suffix is "alpha", therefore the first facility is "alpha".
This requires six bytes.<br>
<br>
The second prefix length is 0001 (offset 30).<br>
The second suffix is "pple", therefore the second facility is "apple".
This requires six bytes.<br>
<br>
The third prefix length is 0004 (offset 37).<br>
The third suffix is "ication", therefore the third facility is "application".
This requires twelve bytes.<br>
<br>
The fourth prefix length is 0000 (offset 41).<br>
The fourth suffix is "zero", therefore the fourth facility is "zero".
This requires five bytes.<br>
<br>
6 + 6 + 12 + 5 = 29 which indeed is 0x1d.<br>
<br>
It is suggested that the facilities are dumped out in alphabetically sorted
order in order to increase the compression ratio of this section.<br>
<br>
<hr width="50%" size="2"><br>
<u><b><big>04: LT_SECTION_FACNAME_GEOMETRY</big></b></u><br>
<br>
This section consists of a repeating series of sixteen byte entries. Each
entry corresponds in order with a facility as defined in 03: LT_SECTION_FACNAME.
As such there is a 1:1 in-order correspondence between the two sections.<br>
<br>
4 bytes: <i>rows</i> (typically zero,
only used when defining arrays: this indicates the max row value+1)<br>
4 bytes: <i>msb</i><br>
4 bytes: <i>lsb</i><br>
4 bytes: <i>flags</i><br>
<br>
<i>flags</i> are defined as follows:<br>
<br>
<tt> #define LT_SYM_F_BITS
(0)<br>
#define LT_SYM_F_INTEGER
(1<<0)<br>
#define LT_SYM_F_DOUBLE
(1<<1)<br>
#define LT_SYM_F_STRING
(1<<2)<br>
#define LT_SYM_F_ALIAS
(1<<3)</tt><br>
<br>
When an LT_SYM_F_ALIAS is encountered, it indicates that the rows field
instead means "alias this to facility number <i>rows</i>", there the facility
number corresponds to the definition order in 03: LT_SECTION_FACNAME and
starts from zero. <br>
<br>
<hr width="50%" size="2"><br>
<br>
<u><b><big>02: LT_SECTION_SYNC_TABLE</big></b></u><br>
<br>
This section indicates where the final value change (as a four-byte offset
from the beginning of the file) for every facility is to be found. Facilities
which do not change value contain a value of zero for their final value change.
This section is necessary as value changes are stored as a linked list of
backward directed pointers. There is a 1:1 in-order correspondence
between this section and the definitions found in LT_SECTION_FACNAME.<br>
<br>
4 bytes: <i>final offset for facility</i> (repeated for each facility in
order as they were defined)<br>
<br>
<hr width="50%" size="2"><br>
<u><b><big>01: LT_SECTION_CHG</big></b></u><br>
<br>
This section is usually the largest section in a file as is composed of value
changes, however its structure is set up such that individual facilities
can be quickly accessed without the necessity of reading in the entire file.
In spite of this format, this does not prevent one from stepping through
the entire section <i>backwards</i> in order to process it in one pass. The
method to achieve this will be described later.<br>
<br>
The final offset for a value change for a specific facility is found in 02:
LT_SECTION_SYNC_TABLE. Since value changes for a facility are linked
together, one may follow pointers backward from the sync value offset for
a facility in order to read in an entire trace. This is used to accelerate
sparse reads of an LXT file's change data such as those that a visualization
tool such as a wave viewer would perform. <br>
<br>
The format for a value change is as follows:<br>
<br>
<i>command_byte, delta_offset_of_previous_change[, [row_changed,] change_data
]</i><br>
<hr width="25%" size="2"><u><b>Command Bytes:</b></u><br>
<br>
The <i>command_byte</i> is broken into two (as currently defined) bitfields:
bits [5:4] contain a byte count (minus one) required for the <i>delta_offset_of_previous_change</i>
(thus a value from one to four bytes), and bits [3:0] contain the command
used to determine the format of the change data (if any change data is necessary
as dictated by the command byte).<br>
<br>
Bits [3:0] of the <i>command_byte </i>are defined as follows. Note
that this portion of the <i>command_byte</i> is ignored for strings and doubles
and typically x0 is placed in the dumpfile in those cases:<br>
<br>
<tt>0</tt> MVL_2 [or default (for datatype) value change
follows]<br>
<tt>1</tt> MVL_4<br>
<tt>2</tt> MVL_9<br>
<tt>3</tt> flash whole value to 0s<br>
<tt>4</tt> flash whole value to 1s<br>
<tt>5</tt> flash whole value to Zs<br>
<tt>6</tt> flash whole value to Xs<br>
<tt>7</tt> flash whole value to Hs<br>
<tt>8</tt> flash whole value to Us<br>
<tt>9</tt> flash whole value to Ws<br>
<tt>A</tt> flash whole value to Ls<br>
<tt>B</tt> flash whole value to -s<br>
<tt>C</tt> clock compress use 1 byte repeat count<br>
<tt>D</tt> clock compress use 2 byte repeat count<br>
<tt>E</tt> clock compress use 3 byte repeat count<br>
<tt>F</tt> clock compress use 4 byte repeat count<br>
<br>
Commands x3-xB only make sense for MVL_2/4/9 (and integer in the case for x3
and x4 when an integer is 0 or ~0) facilities. They are provided as
a space saving device which obviates the need for dumping value change data
when all the bits in a facility are set to the same exact value. For
single bit facilities, these commands suffice in all cases.<br>
<br>
Command x0 is used when <i>change_data</i> can be stored as MVL_2. Bits
defined in MVL_2 are '0' and '1' and as such, one bit of storage in an LXT
file corresponds to one bit in the facility value.<br>
<br>
Command x1 is used when <i>change_data</i> can't be stored as MVL_2 but can
stored as MVL_4. Bits defined in MVL_4 are '0', '1', 'Z', and
'X' are stored in an LXT file as the two-bit values 00, 01, 10, and 11.<br>
<br>
Command x2 is used when change_data can't be stored as either MVL_2 or MVL_4
but can be stored as MVL_9. Bits defined in MVL_9 are '0', '1', 'Z',
'X', 'H', 'U', 'W', 'L', and '-' corresponding to the four-bit values 0000
through 1000.<br>
<br>
Commands xC-xF are used to repeat a clock. It is assumed that at least two
clock phase changes are present before the current command. Their time values
are subtracted in order to obtain a delta. The delta is used as the change time
between future phase changes with respect to the time value of the previous command which is
used as a "base time" and "base value" for repeat_count+1 phase changes.<br>
<hr width="12%" size="2"><br>
Note that these repeat command nybbles <i>also</i> are applicable to multi-bit facilities which
are 32-bits or less and MVL_2 in nature. In this case, the preceeding two deltas are
subtracted such that a recurrence equation can reconstruct any specific item of the compressed data:
<br>
<pre>
unsigned int j = item_in_series_to_create + 1;
unsigned int res = base + (j/2)*rle_delta[1] + ((j/2)+(j&1))*rle_delta[0];
</pre>
For a sequence of: <tt>7B 7C 7D 7E 7F 80 81 82</tt> ...
<pre>
base = 82
rle_delta[1] = 82 - 81 == 01
rle_delta[0] = 81 - 80 == 01
</pre>
Two deltas are used in order to handle the case where a vector which changes value by a constant XOR. In that case,
the <tt>rle_delta</tt> values will be different. In this way, one command encoding can handle both XOR and incrementer/decrementer
type compression ops.
<br>
<hr width="25%" size="2"><u><b>Delta Offsets:</b></u><br>
<br>
Delta offsets indicate where the preceeding change may be found with respect
to the beginning of the LXT file. In order to calculate where the preceeding
change for a facility is, take the offset of the <i>command_byte</i>, subtract
the <i>delta_offset_of_previous_change</i> from it, then subtract 2 bytes
more. As an example:<br>
<br>
<tt>00001000: 13 02 10</tt> ...<br>
<br>
The command byte is 13. Since bits [5:4] are "01", this means that
the <i>delta_offset_of_previous_change</i> is two bytes since 1 + 1 = 2.<br>
<br>
The next two bytes are 0210, so 1000 - 0210 - 2 = 0DEE. Hence, the
preceeding value change can be found at 0DEE. This process is to be
continued until a value change offset of 0 is obtained. This is impossible
because of the existance of the LXT header bytes.<br>
<hr width="25%" size="2"><u><b>Row Changed:</b></u><br>
<br>
This field is <i>only</i> present in value changes for arrays. The
value is 2, 3, or 4 bytes depending on the magnitude of the array size: greater
than 16777215 rows requires 4 bytes, greater than 65535 requires 3 bytes,
and so on down to one byte. Note that any value type can be part of
an array.<br>
<hr width="25%" size="2"><u><b>Change Data:</b></u><br>
<br>
This is only present for <i>command_byte</i>s x0-x2 for MVL_2, MVL_4, and
MVL_9 data, and any <i>command_byte</i> for strings and doubles. Strings
are stored in zero terminated format and doubles are stored as eight bytes
in machine-native format with 08: LT_SECTION_DOUBLE_TEST being used to resolve
possible differences in endianness on the machine reading the LXT file.<br>
<br>
Values are stored left justified in big endian order and unused bits are
zeroed out. Examples with "_" used to represent the boundary between
consecutive bytes:<br>
<br>
MVL_2: "0101010110101010" (16 bits) is stored as 01010101_10101010<br>
MVL_2: "011" (3 bits) is stored as 01100000<br>
MVL_2: "11111110011" (11 bits) is stored as 11111110_01100000<br>
<br>
MVL_4: "01ZX01ZX" (8 bits) is stored as 00011011_00011011<br>
MVL_4: "ZX1" (3 bits) is stored as 10110100<br>
MVL_4: "XXXXZ" (5 bits) is stored as 11111111_10000000<br>
<br>
MVL_9: "01XZHUWL-" (9 bits) is stored as 00000001_00100011_01000101_01100111_10000000
<br>
<hr width="25%" size="2"><u><b>Correlating Time Values to Offsets:</b></u><br>
<br>
This is what the purpose of 06: LT_SECTION_TIME_TABLE is. Given the
offset of a <i>command_byte</i>, <tt>bsearch(3)</tt> an array of ascending
position values (not deltas) and pick out the maximum position value which
is less than or equal to the offset of the <i>command_byte</i>. The
following code sequence illustrates this given two arrays <tt>positional_information[]</tt>
and <tt>time_information[]</tt>. Note that <tt>total_cycles</tt> corresponds
to <i>number_of_entries</i> as defined in 06: LT_SECTION_TIME_TABLE.<br>
<br>
<tt>static int max_compare_time_tc, max_compare_pos_tc;<br>
static int compar_mvl_timechain(const void *s1, const void *s2)<br>
{ <br>
int key, obj, delta;<br>
int rv;<br>
<br>
key=*((int *)s1);<br>
obj=*((int *)s2); <br>
<br>
if((obj<=key)&&(obj>max_compare_time_tc))<br>
{<br>
max_compare_time_tc=obj;<br>
max_compare_pos_tc=(int *)s2 -
positional_information;<br>
}<br>
<br>
delta=key-obj;<br>
if(delta<0) rv=-1; <br>
else if(delta>0) rv=1;<br>
else rv=0;<br>
<br>
return(rv);<br>
}<br>
<br>
static int bsearch_position_versus_time(int key)<br>
{<br>
max_compare_time_tc=-1; max_compare_pos_tc=-1;<br>
<br>
bsearch((void *)&key, (void *)positional_information, total_cycles, sizeof(int),
compar_mvl_timechain);<br>
if((max_compare_pos_tc<=0)||(max_compare_time_tc<0))<br>
{<br>
max_compare_pos_tc=0; /* aix bsearch
fix */<br>
}<br>
<br>
return(time_information[max_compare_pos_tc]);<br>
}</tt><br>
<hr width="25%" size="2"><u><b>Reading All Value Changes in One Pass:</b></u><br>
<br>
This requires a little bit more work but it can be done. Basically
what you have to do is the following:
<ol>
<li>Read in all the sync offsets from 02: LT_SECTION_SYNC_TABLE and put
each in a structure which contains the sync offset and the facility index.
All of these structures will compose an array that is as large as the
number of facilities which exist.</li>
<li>Heapify the array such that the topmost element of the heap has the
largest positional offset.</li>
<li>Change the topmost element's offset to its preceeding offset (as determined
by examining the <i>command_byte</i>, bits [5:4] and calculating the preceeding
offset by subtracting the <i>delta_offset_of_previous_change</i> then subtracting
2 bytes.</li>
<li>Continue with step 2 until the topmost element's offset is zero after
performing a heapify().<br>
</li>
</ol>
<hr width="50%" size="2"><br>
<u><b><big>00: LT_SECTION_END</big></b></u><br>
<br>
As a section pointer doesn't exist for this, there's no section body either.<br>
<hr width="100%" size="2"><br>
<u><b><big><big>The lxt_write API:</big></big></b></u><br>
<br>
In order to facilitate the writing of LXT files, an API has been provided
which does most of the hard work. <br>
<hr width="25%" size="2">
<div align="Center"><b><tt> struct lt_trace *lt_init(const char
*name)</tt></b><br>
</div>
<tt><br>
</tt>This opens an LXT file. The pointer returned by this function
is NULL if unsuccessful. If successful, the pointer is to be used as
a "context" for all the remaining functions in the API. In this way,
multiple LXT files may be generated at once.<tt><br>
</tt>
<hr width="25%" size="2">
<div align="Center"><b><tt>void lt_close(struct lt_trace *lt)</tt></b><br>
</div>
<tt><br>
</tt>This fixates and closes an LXT file. This is extremely important
because if the file is not fixated, it will be impossible to use the value
change data in it! For this reason, it is recommended that the function
be placed in an <tt>atexit(3)</tt> handler in environments where trace generation
can be interrupted through program crashes or external signals such as control-C.<tt><br>
</tt>
<hr width="25%" size="2"><tt> <br>
</tt>
<div align="Center"><b><tt>struct lt_symbol *lt_symbol_add(struct lt_trace
*lt, const char *name, </tt><br>
<tt>unsigned int rows, int msb, int lsb, int flags)</tt></b><br>
</div>
<br>
This creates a facility. Since the facility and related tables are
written out during fixation, one may arbitrarily add facilities up until
the very moment that lt_close() is called. For facilities which are
not arrays, a value of 0 or 1 for rows. As such, only values 2 and
greater are used to signify arrays. Flags are defined above as in 04:
LT_SECTION_FACNAME_GEOMETRY.<br>
<hr width="25%" size="2"><tt><br>
</tt>
<div align="Center"><b><tt>struct lt_symbol *lt_symbol_find(struct lt_trace
*lt, const char *name)</tt></b><br>
</div>
<tt><br>
</tt>This finds if a symbol has been previously defined. If returns
non-NULL on success. It actually returns a symbol pointer, but you
shouldn't be deferencing the fields inside it unless you know what you are
doing.
<hr width="25%" size="2"><tt><br>
</tt>
<div align="Center"><b><tt>struct lt_symbol *lt_symbol_alias(struct lt_trace
*lt, const char *existing_name,</tt><br>
<tt>const char *alias, int msb, int lsb)</tt></b><br>
</div>
<tt><br>
</tt>This assigns an alias to an existing facility. This is to create
signals which traverse multiple levels of hierarchy, but are the same net,
possibly with different MSB and LSB values (though the distance between them
will be the same).<tt><br>
</tt>
<hr width="25%" size="2"><tt><br>
</tt>
<div align="Center"><b><tt>void lt_symbol_bracket_stripping(struct lt_trace
*lt, int doit)</tt></b><br>
</div>
<tt><br>
</tt>This is to be used when facilities are defined in Verilog format such
that exploded bitvectors are dumped as x[0], x[1], x[2], etc. If doit
is set to a nonzero value, the bracketed values will be stripped off. In
order to keep visualization and other tools from becoming confused, the MSB/LSB
values must be unique for every bit. The tool <tt>vcd2lxt</tt> shows
how this works and should be used. If vectors are dumped atomically,
this function need not be called.<tt><br>
</tt>
<hr width="25%" size="2"><tt><br>
</tt>
<div align="Center"><b><tt>void lt_set_timescale(struct lt_trace *lt, int
timescale)</tt></b><br>
</div>
<tt><br>
</tt>This sets the simulation timescale to 10<sup>timescale</sup> seconds
where timescale is an 8-bit signed value. As such, negative values
are the only useful ones.<br>
<hr width="25%" size="2"><tt><br>
</tt>
<div align="Center"><b><tt>void lt_set_initial_value(struct lt_trace *lt,
char value)</tt></b><br>
</div>
<tt><br>
</tt>This sets the initial value of every MVL (bitwise) facility to whatever
the value is. Permissible values are '0', '1', 'Z', 'X', 'H', 'U',
'W', 'L', and '-'.<br>
<hr width="25%" size="2">
<div align="Center">
<b><tt>int lt_set_time(struct lt_trace *lt, unsigned int timeval)</tt></b><br>
<b><tt>int lt_inc_time_by_delta(struct lt_trace *lt, unsigned int timeval)</tt></b><br>
<b><tt>int lt_set_time64(struct lt_trace *lt, lxttime_t timeval)</tt></b><br>
<b><tt>int lt_inc_time_by_delta64(struct lt_trace *lt, lxttime_t timeval)</tt></b><br>
</div>
<tt><br>
</tt>This is how time is dynamically updated in the LXT file. Note
that for the non-delta functions, timeval changes are expected to be monotonically increasing. In
addition, time values dumped to the LXT file are coalesced if there are no
value changes for a specific time value. (Note: lxttime_t is defined as an unsigned long long.)
<hr width="25%" size="2">
<div align="Center"><b><tt>void lt_set_clock_compress(struct lt_trace *lt)</tt></b><br>
</div>
<tt><br>
</tt>Enables clock compression heuristics for the current trace. This cannot be turned off once it is on.
<hr width="25%" size="2"><tt> <br>
</tt>
<div align="Center"><b><tt>int lt_emit_value_int(struct lt_trace *lt, struct
lt_symbol *s, </tt><br>
<tt>unsigned int row, int value)</tt></b><br>
</div>
<tt><br>
</tt>This dumps an MVL_2 value for a specific facility which is 32-bits or less. Note that this
does not work for strings or doubles.<tt><br>
</tt>
<hr width="25%" size="2"><tt><br>
</tt>
<div align="Center"><b><tt> int lt_emit_value_double(struct lt_trace
*lt, struct lt_symbol *s, </tt><br>
<tt>unsigned int row, double value)</tt></b><br>
<br>
</div>
This dumps a double value for a specific facility. Note that this only
works for doubles.<br>
<hr width="25%" size="2"><tt><br>
</tt>
<div align="Center"><b><tt>int lt_emit_value_string(struct lt_trace *lt,
struct lt_symbol *s, </tt><br>
<tt>unsigned int row, char *value)</tt></b><br>
</div>
<br>
This dumps a string value for a specific facility. Note that this only
works for strings.<br>
<hr width="25%" size="2"><br>
<div align="Center"><b><tt>int lt_emit_value_bit_string(struct lt_trace *lt,
struct lt_symbol *s, <br>
unsigned int row, char *value)</tt></b><br>
<br>
<div align="Left">This dumps an MVL_2, MVL_4, or MVL_9 value out to the LXT
file for a specific facility. Note that the value is parsed in order
to determine how to optimally represent it in the file. In addition,
note that if the value's string length is shorter than the facility length,
it will be left justified with the rightmost character will be propagated
to the right in order to pad the value string out to the correct length.
Therefore, "10x" for 8-bits becomes "10xxxxxx" and "z" for 8-bits becomes
"zzzzzzzz".<br>
<hr width="100%" size="2"></div>
</div>
<div align="Center">21Nov01 <a href="mailto:bybell@linux-workshop.com">bybell@linux-workshop.com</a>
/ <a href="mailto:%20bybell@pagecreator.com">bybell@pagecreator.com</a>
<br>
</div>
</body>
</html>
