<!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 (0x0004)<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 04</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>
<b>NOTE: The sourcecode lxt-write.[ch] and lxt.[ch] in GTKWave may be considered
a definitive "reference implementation" of this specification. If this specification
is at odds with the sourcecode, unless it is an obvious software bug (one-off,
buffer overrun, etc.), the sourcecode may be assumed to be "correct".</b><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)<br>
</tt>
<p> <tt> #define LT_SECTION_ZFACNAME_PREDEC_SIZE (10)<br>
#define LT_SECTION_ZFACNAME_SIZE
(11)<br>
#define LT_SECTION_ZFACNAME_GEOMETRY_SIZE (12)<br>
#define LT_SECTION_ZSYNC_SIZE
(13)<br>
#define LT_SECTION_ZTIME_TABLE_SIZE
(14)<br>
#define LT_SECTION_ZCHG_PREDEC_SIZE
(15)<br>
#define LT_SECTION_ZCHG_SIZE
(16)</tt><br>
<br>
(*) Note that the Z sections 10-16 are optional and are used to
indicate the compressed (PREDECompressed) and uncompressed section sizes of
a given section in order to provide hints to the gzip decompression and memory
allocation routines. Their mere presence implies that the section under
question (e.g., SYNC) is compressed. If absent, the section under question
is not compressed.<br>
</p>
<p><tt>#define LT_SECTION_ZDICTIONARY
(17)<br>
#define LT_SECTION_ZDICTIONARY_SIZE
(18)</tt><br>
</p>
<p>These two are involved with dictionary compression of MVL_2 facilities.
The LT_SECTION_ZDICTIONARY is a hybrid uncompressed/compressed section.
Sections 17-18 are optional.<br>
</p>
<p> 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>
</p>
<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>
<br>
<u><b><big>17: LT_SECTION_ZDICTIONARY / 18: LT_SECTION_ZDICTIONARY_SIZE</big></b></u><br>
<br>
This section is only created if "dictionary packing" is turned on (via <tt>lt_set_dict_compress()</tt>
in the lxt-write API). Its purpose is to provide a central grouping
for all the MVL_2 values in a simulation run which are greater than a specific
bitwidth. This is used to take advantage of the fact that a signal in
a model may take on the same value several times during simulation and this
may be more efficiently referred to via an index rather than an explicit value.
Careless use of dictionary packing may needlessly increase the size
of an LXT file.<br>
<br>
4 bytes: <i>number of dictionary entries (n)</i><br>
4 bytes: <i>amount of memory required to store decompressed dictionary</i><br>
4 bytes: <i>dict_16_offset</i> (Position in file where dictionary indices
require 16 bits of storage).<br>
4 bytes: <i>dict_24_offset</i> (Position in file where dictionary
indices require 24 bits of storage.)<br>
4 bytes: <i>dict_32_offset</i> (Position in file where dictionary
indices require 32 bits of storage.)<br>
4 bytes: <i>minimum width of signal which forces it into dictionary
storage</i><br>
<i>n</i> gzip compressed null terminated ASCII dictionary entries (e.g.,
"101110") follow consuming the memory specified by LT_SECTION_ZDICTIONARY_SIZE.<br>
<br>
The way that dictionary packing works is that for MVL_2 entries in LT_SECTION_CHG,
if the bitwidth of the facility being dumped is greater than the minimum width
specified (offset 20), then instead of dumping the explicit value, its
index in the compressed dictionary entries table is written to the file. To
increase compression of this table, all leading zeros and the first '1' after
the leading zeros are stripped in the compressed section starting at offset
24.<br>
<br>
The <i>dict_16_offset</i> indicates the position in the file where 16 bits
are required to store index values. All indices from that byte forward
are stored in two bytes (before this offset only one byte is required).<br>
<br>
<i>dict_24_offset</i> and <i>dict_32_offset</i> follow the same format.
<br>
<br>
It is suggest that this section is read again after reading 01: LT_SECTION_CHG
in order to fully understand dictionary packing.<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;<br> unsigned int res = base + (j/2)*rle_delta[1] + ((j/2)+(j&1))*rle_delta[0];<br></pre>
For a sequence of: <tt>7B 7C 7D 7E 7F 80 81 82</tt> ...
<pre> base = 82<br> rle_delta[1] = 82 - 81 == 01<br> rle_delta[0] = 81 - 80 == 01<br></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>
<br>
...the exception to storing values directly is for MVL_2 value change entries
when dictionary packing is enabled. See 17: LT_SECTION_ZDICTIONARY for
more information.<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">
<div align="center"><b><tt> void lt_set_chg_compress(struct lt_trace *lt);
</tt></b><br>
</div>
<tt><br>
</tt>Enables gzip compression on trace data for the current trace. It
must be specified before any trace data is dumped. This cannot be turned
off once it is on. This is only available in version 3 and greater of the
writer API.
<hr width="25%" size="2">
<div align="center"><b><tt> void lt_set_dict_compress(struct lt_trace *lt,
unsigned int minwidth); </tt></b><br>
</div>
<tt><br>
</tt>Enables dictionary compression on MVL_2 trace data for the current
trace. It must be specified before any trace data is dumped. This
cannot be turned off once it is on. This is only available in version 4 and
greater of the writer API.
<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">31Dec02 <a href="mailto:bybell@linux-workshop.com">bybell@linux-workshop.com</a><br>
</div>
<br>
<br>
</body>
</html>
