Data Snapshots - 2024.2 English - UG1076

AI Engine Tools and Flows User Guide (UG1076)

Document ID
UG1076
Release Date
2024-11-28
Version
2024.2 English

The x86simulator --dump data snapshot feature allows users to dump and inspect data traffic at kernel ports without using the debugger. This feature does not require any instrumentation of kernel code. It also helps diagnose simulation result mismatches between two versions of the same design with x86simulator. Data snapshots are supported for kernel ports including streams, windows, packet streams, cascade streams, and RTP ports. This feature is also supported for all platform level ports like PLIO, GMIO, RTP ports, as well as for PS accesses into a specific RTP port.

For input window ports, a data snapshot is taken each time the kernel acquires the window and the snapshot includes the margin. For output window ports, a snapshot is taken each time the kernel releases the window and it excludes the margin. In either case the snapshot consists of the kernel iteration count and sample data. One text file per kernel port is generated. In addition, the iteration count of the kernel is also recorded.

For example, a data snapshot for a graph with a chain of two kernels with window ports where the first window has a non-zero margin is as follows.

$x86simulator --pkg-dir=./Work --i=.. --dump
INFO: Reading options file './Work/options/x86sim.options'.
Processing './x86simulator_output/dump/x86sim_dump.data'
File Port direction Port type Data type Kernel or platform port
------------------------ -------------- --------- ---------
-----------------------
platform_src_0.txt out window cint16 platform.src[0]
mygraph_first_in_0.txt in window cint16 mygraph.first.in[0]
mygraph_second_out_0.txt out window cint16 mygraph.second.out[0]
platform_sink_0.txt in window cint16 platform.sink[0]
mygraph_first_out_0.txt out window cint16 mygraph.first.out[0]
mygraph_second_in_0.txt in window cint16 mygraph.second.in[0]
Wrote './x86simulator_output/dump/platform_src_0.txt'
Wrote './x86simulator_output/dump/mygraph_first_in_0.txt'
Wrote './x86simulator_output/dump/mygraph_second_out_0.txt'
Wrote './x86simulator_output/dump/platform_sink_0.txt'
Wrote './x86simulator_output/dump/mygraph_first_out_0.txt'
Wrote './x86simulator_output/dump/mygraph_second_in_0.txt'
Simulation completed successfully returning zero
$> more ./x86simulator_output/dump/mygraph_first_in_0.txt
# port: mygraph.first.in[0]
# port_dir: in
# port_type: window
# data_type: cint16
# Iteration 1; snapshot 1
0 0
0 0
0 0
0 0
0 0
0 0
0 0
0 0
0 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
# Iteration 2; snapshot 2
48 49
50 51
52 53
54 55
56 57
58 59
60 61
62 63
1 0
3 2
5 4
7 6
9 8
11 10
13 12
15 14
17 16
19 18
21 20
23 22
25 24
27 26
29 28
31 30
33 32
35 34
37 36
39 38
41 40
43 42
45 44
47 46
49 48
51 50
53 52
55 54
57 56
59 58
61 60
63 62

For stream ports, a data snapshot is taken for each chunk of four bytes of data. Each snapshot includes the value of TLAST and the kernel iteration count. For cascade stream ports, the granularity is eight bytes.

For example, a data snapshot for a graph with three kernels connected via stream ports is as follows.

$ x86simulator --pkg-dir=./Work --i=.. --dump
INFO: Reading options file './Work/options/x86sim.options'.
Processing './x86simulator_output/dump/x86sim_dump.data'


File Port direction Port type Data type Kernel or platform port
-------------------------- -------------- --------- --------- -----------------------
platform_src_0.txt out stream int32 platform.src[0] 
fifo_graph_dist_in_0.txt in stream int32 fifo_graph.dist.in[0] 
fifo_graph_aggr_out_0.txt out stream int32 fifo_graph.aggr.out[0] 
platform_sink_0.txt in stream int32 platform.sink[0] 
fifo_graph_comp0_in_0.txt in stream int32 fifo_graph.comp0.in[0] 
fifo_graph_comp1_in_0.txt in stream int32 fifo_graph.comp1.in[0] 
fifo_graph_dist_out_0.txt out stream int32 fifo_graph.dist.out[0] 
fifo_graph_comp0_out_0.txt out stream int32 fifo_graph.comp0.out[0]
fifo_graph_aggr_in_0.txt in stream int32 fifo_graph.aggr.in[0] 
fifo_graph_comp1_out_0.txt out stream int32 fifo_graph.comp1.out[0]
fifo_graph_aggr_in_1.txt in stream int32 fifo_graph.aggr.in[1] 


Wrote './x86simulator_output/dump/platform_src_0.txt'
Wrote './x86simulator_output/dump/fifo_graph_dist_in_0.txt'
Wrote './x86simulator_output/dump/fifo_graph_aggr_out_0.txt'
Wrote './x86simulator_output/dump/platform_sink_0.txt'
Wrote './x86simulator_output/dump/fifo_graph_comp0_in_0.txt'
Wrote './x86simulator_output/dump/fifo_graph_comp1_in_0.txt'
Wrote './x86simulator_output/dump/fifo_graph_dist_out_0.txt'
Wrote './x86simulator_output/dump/fifo_graph_comp0_out_0.txt'
Wrote './x86simulator_output/dump/fifo_graph_aggr_in_0.txt'
Wrote './x86simulator_output/dump/fifo_graph_comp1_out_0.txt'
Wrote './x86simulator_output/dump/fifo_graph_aggr_in_1.txt'
Simulation completed successfully returning zero


$ more ./x86simulator_output/dump/fifo_graph_dist_in_0.txt
# port: fifo_graph.dist.in[0]
# port_dir: in
# port_type: stream
# data_type: int32
# Iteration 1
0
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
...

The compiler generates the configuration file ./Work/options/x86sim_dump.config to specify what data to dump when running x86simulator --dump. Following is an example of compiler generated ./Work/options/x86sim_dump.config:

kernel=yes
gr.k[0].in[0]=yes
gr.k[0].out[0]=yes
gr.k[0].out[1]=yes
gr.k[1].in[0]=yes
gr.k[1].in[1]=yes
gr.k[1].out[0]=yes

platform_io=no
gr.in.out[0]=no
gr.dataout.in[0]=no
Following categories based on the design are supported in the configuration file:
Table 1. X86simulator Dump Configurations
No. Category Default Dump Configuration Nodes / Ports under the Category
1 kernel yes Input/Output ports of all the kernels
2 shared_buffer yes Shared buffer as a whole
3 external_buffer yes External buffer as a whole
4 shared_buffer_port no Ports of all the shared buffers
5 external_buffer_port no Ports of all the external buffers
6 platform_io no PLIO, GMIO, FileIO, PS:RTP
7 pktmerge no Pkt merge ports
8 pktsplit no Pkt split ports
9 bypass no Bypass port

If the dump configuration is set to yes, all entries under the category are dumped, irrespective of their control value.

If the dump configuration is set to no, partial entries under the category can be selected to be dumped to save disk space and running time. For example, following configurations will only to dump gr.k[0].in[0]:

kernel=no
gr.k[0].in[0]=yes
gr.k[0].out[0]=no
gr.k[0].out[1]=no
gr.k[1].in[0]=no
gr.k[1].in[1]=no
gr.k[1].out[0]=no
If no dump configuration is set to a category, the value of the previous category will be inherited. For example, the following entries g.ifm1 and g.wts1 are under the category shared_buffer. However, the dump configuration for shared_buffer is not specified. So, the value of the previous category kernel which is yes is inherited. Then, the entries g.ifm1 and g.wts1 are all dumped.
kernels=yes
g.k1.in[0]=yes
g.k1.in[1]=yes
g.k1.out[0]=yes

g.ifm1=yes
g.wts1=no