1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
|
<!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)</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</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><br>
4 bytes: <i>max time in dump</i><br>
<br>
<i>n</i> 4-byte positional delta entries follow<br>
<i>n</i> 4-byte time delta entries follow<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="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, int timeval)</tt></b><br>
</div>
<tt><br>
</tt>This is how time is dynamically updated in the LXT file. Note
that 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.
<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>
|
