tapasco.1 12.7 KB
Newer Older
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
.TH tapasco 1 2017.1 MAN(1)
.SH SYNOPSIS
    tapasco [global option]* [job]*
or: tapasco \-h | \-\-help [TOPIC]

.SH GLOBAL OPTIONS
.RS
\-v | \-\-verbose [MODE]
.RS
Verbose mode, log outputs of subprocesses; optional MODE is a quoted string selecting the output mode
(default: 'verbose')
.RE
.RE
.RS
\-n | \-\-dryRun FILE
.RS
Dry run, do not execute, only dump Json into FILE.
.RE
.RE
.RS
\-\-archDir PATH
.RS
Base directory for architecture descriptions
.RE
.RE
.RS
\-\-compositionDir PATH
.RS
Output base directory for Compose jobs
.RE
.RE
.RS
\-\-coreDir PATH
.RS
Output base directory for HLS jobs, synthesized cores
.RE
.RE
.RS
\-\-kernelDir PATH
.RS
Base directory for kernel descriptions (HLS)
.RE
.RE
.RS
\-\-platformDir PATH
.RS
Base directory for platform descriptions
.RE
.RE
.RS
\-\-logFile FILE
.RS
Path to output log file
.RE
.RE
.RS
\-\-configFile FILE
.RS
Path to Json file with Configuration
.RE
.RE
.RS
\-\-jobsFile FILE
.RS
Path to Json file with Jobs array
.RE
.RE
.RS
\-\-slurm
.RS
Activate SLURM cluster execution (requires sbatch)
.RE
.RE
.RS
\-\-parallel
.RS
Execute all jobs in parallel (careful!)
.RE
.RE
.RS
\-\-maxThreads NUM
.RS
Limit internal parallelism of activities (e.g., Vivado) to the given number of threads.
.RE
.RE
.SH BULK IMPORT JOB
Bulk import jobs can import multiple IP\-XACT core .zip files in row. The 
required import parameters are given a CSV file instead of manually via the 
command line.

.RS
Syntax
.RS
bulkimport <CSV>
.RE
.RE
.RS
where
.RS
CSV
.RS
Path to file in comma\-separated values (CSV) format, must contain the following header line and columns:
.RE
.RE

Zip, ID, Description, Architecture, Platform, Avg Runtime (clock cycles)
.RE
.SH COMPOSE JOB
Generate a full\-system bitstream from spec. Compose jobs are the core of 
TaPaSCo and comprise the construction of the system design, synthesis and 
place\-and\-route, as well as high\-level synthesis of cores (if necessary).

To generate a design, one needs to specify

.RS
1) the Composition (see below)
2) the Architecture (i.e., organization of PEs in the design)
3) the Platform (i.e., target hardware)
4) the target design frequency (operating frequency of the PEs)
.RE

If Architecture or Platform selection is ommitted, TaPaSCo will build bitstreams
forr all available Architectures and Platforms in parallel. Resource 
restrictions apply normally (e.g., won't launch more runs than CPUs available, 
etc.). The resulting projects and bitstreams can be found in the directory 
hierarchy below the currently configured Composition directory (see `tapasco \-h
globals`)..

.RS
Syntax
.RS
compose <COMPOSITION> @ <NUM> MHz [option]*
.RE
.RE
.RS
where
.RS
COMPOSITION
.RS
Composition spec, see `tapasco \-h composition`
.RE
.RE
.RS
NUM
.RS
target operating frequency for PEs in MHz
.RE
.RE
.RE

followed optionally by:
.RS
.RS
\-a | \-\-architectures A+
.RS
list of Architectures to compose for, e.g., \-a axi4mm, myarch
.RE
.RE
.RS
\-p | \-\-platforms P+
.RS
list of Platforms to compose for, e.g., \-p vc709, pynq
.RE
.RE
.RS
\-\-implementation NAME
.RS
selects a tool for synthesis, place\-and\-route
default: "Vivado"
.RE
.RE
.RS
\-\-features FEATURES
.RS
configures Features, see `tapasco \-h features`
syntax: FEATURE [, FEATURE]*
.RE
.RE
.RS
\-\-debugMode NAME
.RS
dry run, no composition is executed; modes:
.RE
.RE
.RS
.RS
  r
.RS
generate random result values
.RE
.RE
.RS
  f
.RS
generate only timing failures
.RE
.RE
.RS
  p
.RS
generate only placer errors
.RE
.RE
.RS
  o
.RS
generate only other errors
.RE
.RE
.RE
.RE

NOTE: Currently the  total number of PEs must be <= 128.
.SH COMPOSITION SYNTAX
A Composition specifies the number and kind of processing elements (PEs) that 
are present in the design. The basic command line syntax is as follows:

.RS
COMPOSITION
.RS
'[' <KERNEL> x <COUNT> [, <KERNEL> x <COUNT>]* ']'
.RE
.RE
.RS
.RS
KERNEL
.RS
name of kernel/core, a quoted/unquoted string
.RE
.RE
.RS
COUNT
.RS
number of instances (0 < x <= 128)
.RE
.RE
.RE

.RS
Examples:
.RS
[ precision_counter x 128 ]
[arrayupdate x 4, arraysum x 8]
.RE
.RE
.SH CONFIG FILES
A config file is a Json (http://json.org) file consisting of a singleconfiguration object. A configuration object can contain all parametersavailable on the command line, including the jobs, which are representedby an array of Job elements (same format as \-\-jobsFile, see \-\-help jobsFilefor more info).    

You can generate an empty configuration via `tapasco \-n config.json`.
.SH CORE STATISTICS JOB
Evaluation helper job that automatically gathres the out\-of\-context results 
for all Cores, Architectures and Platforms in one .csv file per Architecture and
Platformm combination. Useful for quick overviews over the available PEs.

.RS
Syntax
.RS
corestats [option]*
.RE
.RE

followed optionally by:
.RS
.RS
\-a | \-\-architectures A+
.RS
list of Architectures , e.g., \-a axi4mm, myarch
.RE
.RE
.RS
\-p | \-\-platforms P+
.RS
list of Platforms , e.g., \-p vc709, pynq
.RE
.RE
.RS
\-\-prefix STRING
.RS
file names of generated .csv files will be of the format STRING<ARCH>@<PLATFORM>.csv
.RE
.RE
.RE
.SH DESIGN SPACE EXPLORATION JOB
Even simple hardware designs often require a surprisingly high number of design 
choices. It is difficult to estimate the impact of each choice on the total 
result. TaPaSCo supports the designer by offering an automated Design Space 
Exploration (DSE): TaPaSCo designs can primarily be varied in three dimensions:

.RS
.RS
1) Area / Utilization
.RS
primarily determined by the number of PEs.
.RE
.RE
.RS
2) Target Frequency
.RS
chosen operating frequency
.RE
.RE
.RS
3) Alternatives
.RS
a choice of alternative hardware implementations for a kernel (identified by their ID, see `tapasco \-h import`)
.RE
.RE
.RE

TaPaSCo's DSE mode can automatically explore this design space using a 
user\-selectable performance heuristic. The default heuristic approximates the 
maximal job throughput of the system: Current operating frequency and the 
average clock cycles per job execution of each PE in the design are extrapolated
withh the instance numbers to yield an upper bound on the total job throughput 
of the system. This number is used as a relative "fitness" indicator for the 
comparison of different Compositions. The design space can be linearized by 
descending value for each element.

TaPaSCo explores the design space by batches: Each batch consists of a 
configurable number of design space elements (i.e., Composition + frequency 
pairs); all elements are run in parallel via 'compose'. The successful element 
with the highest heuristic value is returned.

In case of errors, three cases must be distinguished:

.RS
.I Placer errors
 affect all design space elements with the same or a higher 
number of PEs; none of them will be placeable and they will therefore be pruned 
from the design space.

.I Timing failures
 affect only the given element, but generate a feedback 
element: A new design space element is generated for the same Composition, but 
with a lower target frequency. The frequency is computed from the 'worst 
negative slack' reported by the composer tools. I.e., a failed Composition with 
100 MHz target frequency and 0.9ns WNS would give a new element with 97.74 MHz 
(T=10.9ns) frequency.

.I Other errors:
 This encompasses all other errors, e.g., missing licenses, 
system crashes, out\-of\-memory problems, etc.
.RE

TaPaSCo can run explorations in any combination of the three dimensions. To get 
a better idea of each dimension, you can use `itapasco` to configure DSE and get
aa preview of each active dimension.

.RS
Syntax
.RS
explore <COMPOSITION> [<FREQ>] in <DIMS> [option]*
.RE
.RE
.RS
.RS
COMPOSITION
.RS
Composition spec, see `tapasco \-h composition`
.RE
.RE
.RS
FREQ
.RS
'@' <NUM> [MHz]
initial design frequency in MHz, optional
.RE
.RE
.RS
DIMS
.RS
list of active dimensions, e.g., area, frequency, alternatives
.RE
.RE
.RE

followed optionally by:
.RS
.RS
\-a | \-\-architectures A+
.RS
list of Architectures , e.g., \-a axi4mm, myarch
.RE
.RE
.RS
\-p | \-\-platforms P+
.RS
list of Platforms , e.g., \-p vc709, pynq
.RE
.RE
.RS
\-\-basePath PATH
.RS
output base path for DSE results, including config files, projects and bitstreams
default: DSE_<CURRENT DATE>
.RE
.RE
.RS
\-\-batchSize NUM
.RS
number of elements in each batch
default: number of CPUs
.RE
.RE
.RS
\-\-debugMode NAME
.RS
dry run, no compositions are executed, see `tapasco \-h compose`
.RE
.RE
.RS
\-\-features FEATURES
.RS
configures Features, see `tapasco \-h features`
syntax: FEATURE [, FEATURE]*
.RE
.RE
.RS
\-\-heuristic NAME
.RS
select heuristic function
default: 'job throughput'
.RE
.RE
.RS
\-\-implementation NAME
.RS
selects a tool for synthesis, place\-and\-route
default: "Vivado"
.RE
.RE
.RE

.SH NOTE
All HLS kernels are located in the directories below the currently 
configured Kernel directory (see `tapasco \-h globals`). Each kernel 
requires a description in a simple Json format, examples can be found in 
$TAPASCO_HOME/kernel.
.SH FEATURES SYNTAX
The hardware designs generated by TaPaSCo offer a great amount of flexibility 
using a dynamic plug\-in interface; a plug\-in can extend or modify the 
resulting design. By default, most plug\-ins are disabled and must be activated 
by the user. This is done via a Feature specification: A Feature contains the 
configuration parameters for a plug\-in. The basic command line syntax is as 
follows:

.RS
FEATURE
.RS
<NAME> <BEGIN> [<KEYVALUE> [, <KEYVALUE>]*] <END>
.RE
.RE
.RS
.RS
NAME
.RS
any quoted or unquoted string
.RE
.RE
.RS
.RS
BEGIN
.RS
one of '[', '{' or '('
.RE
.RE
.RS
END
.RS
one of ']', '}, or ')'
.RE
.RE
.RE
.RS
KEYVALUE
.RS
<KEY> <ASSIGN> <VALUE>
.RE
.RE
.RS
.RS
KEY
.RS
any quoted or unquoted string
.RE
.RE
.RS
ASSIGN
.RS
either '\->', '=', ':=' or ':'
.RE
.RE
.RS
VALUE
.RS
any quoted or unquoted string
.RE
.RE
.RE
.RE

.RS
Examples:
.RS
'OLED' [enabled \-> true]
'LEDS' { enabled: true, inputs: "/system/LED_*" }
'BlueDMA' (enabled = true)
.RE
.RE
.SH HIGH-LEVEL SYNTHESIS JOB
TaPaSCo facilitates rapid prototyping for FPGA accelerators by directly 
supporting hardware written in C/C++ via HLS. The hls job is used to trigger the
HLSS tool and synthesize hardware for a given Architecture and Platform.

If Architecture or Platform selection is ommitted, TaPaSCo will build cores for 
all available Architectures and Platforms in parallel. Resource restrictions 
apply normally (e.g., won't launch more runs than CPUs available, etc.). The 
resulting cores can be found in the directory hierarchy below the currently 
configured Core directory (see `tapasco \-h globals`).

.RS
Syntax
.RS
hls <KERNELS> [option]*
.RE
.RE
.RS
where
.RS
KERNELS
.RS
all | <KERNEL> [, <KERNEL]*
where KERNEL is a kernel name as quoted or unquoted string; special target 'all' builds all available kernels.
.RE
.RE
.RE

followed optionally by:
.RS
.RS
\-a | \-\-architectures A+
.RS
list of Architectures , e.g., \-a axi4mm, myarch
.RE
.RE
.RS
\-p | \-\-platforms P+
.RS
list of Platforms , e.g., \-p vc709, pynq
.RE
.RE
.RS
\-\-implementation NAME
.RS
selects a HLS tool by name
default: "VivadoHLS"
.RE
.RE
.RE

.SH NOTE
All HLS kernels are located in the directories below the currently 
configured Kernel directory (see `tapasco \-h globals`). Each kernel 
requires a description in a simple Json format, examples can be found in 
$TAPASCO_HOME/kernel.
.SH IMPORT JOB
TaPaSCo supports the use of High\-Level Synthesis (HLS) tools (such as Xilinx 
Vivado HLS) for the synthesis of processing element hardware modules from C/C++ 
automatically (see `tapasco \-h hls`). To make existing IP available as PEs in 
TaPaSCo, you can use the import command:

.RS
Syntax
.RS
import <ZIP> as <ID> [option]*
.RE
.RE
.RS
where
.RS
ZIP
.RS
path to .zip file containing an IP\-XACT description (e.g., component.xml and Verilog/VHDL sources); can be generated, e.g., via Xilinx Vivado, menu Tools \-> Create and package IP.
.RE
.RE
.RS
ID
.RS
any integer > 0; this ID is used to identify the PEs in the hardware and software layers of TaPaSCo Core with the same ID are considered to be alternative implementations of the same interface and should be exchangeable (see `tapasco \-h explore`).
.RE
.RE
.RE

followed optionally by:
.RS
.RS
\-a | \-\-architectures A+
.RS
list of Architectures , e.g., \-a axi4mm, myarch
.RE
.RE
.RS
\-p | \-\-platforms P+
.RS
list of Platforms , e.g., \-p vc709, pynq
.RE
.RE
.RS
\-\-description TEXT
.RS
any quoted or unquoted string containing additional information about the core
.RE
.RE
.RS
\-\-averageClockCycles N
.RS
any integer > 0; number of clock cycles in an "average" execution of the PE; used to estimate the maximal throughput
.RE
.RE
.RE
.SH JOBS FILES
Jobs files are Json (http://json.org) files consisting of an array of Jobdefinitions. See $TAPASCO_HOME/json\-examples/jobs/Jobs.json for an examplecontaining one instance of each job. Alternatively, generate an emptyconfiguration via `tapasco \-n config.json`.