tapasco.1 15 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
Tapasco - Usage: tapasco [global option]* [job]*
             or: tapasco -h | --help [TOPIC]
  
  Global Options:
    -n | --dryRun FILE        Dry run, do not execute, only dump Json into FILE.
    --archDir PATH            Base directory for architecture descriptions
    --compositionDir PATH     Output base directory for Compose jobs
    --coreDir PATH            Output base directory for HLS jobs, synthesized cores
    --kernelDir PATH          Base directory for kernel descriptions (HLS)
    --platformDir PATH        Base directory for platform descriptions
    --logFile FILE            Path to output log file
    --configFile FILE         Path to Json file with Configuration
    --jobsFile FILE           Path to Json file with Jobs array
    --slurm                   Activate SLURM cluster execution (requires sbatch)
    --parallel                Execute all jobs in parallel (careful!)
    --maxThreads NUM          Limit internal parallelism of activities (e.g., Vivado)
                              to the given number of threads.
  
  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. 
Jens Korinth's avatar
Jens Korinth committed
23

24
25
26
27
    SYNTAX:                   bulkimport <CSV>
      where
      CSV                     Path to file in comma-separated values (CSV) format,
                              must contain the following header line and columns:
Jens Korinth's avatar
Jens Korinth committed
28

29
30
31
32
33
34
      "Zip, ID, Description, Architecture, Platform, Avg Runtime (clock cycles)"
  
  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).
Jens Korinth's avatar
Jens Korinth committed
35

36
    To generate a design, one needs to specify
Jens Korinth's avatar
Jens Korinth committed
37

38
39
40
41
      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)
Jens Korinth's avatar
Jens Korinth committed
42

43
44
45
46
47
48
    If Architecture or Platform selection is ommitted, TaPaSCo will build
    bitstreams 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 projects and bitstreams can be found
    in the directory hierarchy below the currently configured Composition
    directory (see `tapasco -h globals`).
Jens Korinth's avatar
Jens Korinth committed
49

50
51
52
53
    SYNTAX:                   compose <COMPOSITION> @ <NUM> MHz [option]*
     where
     COMPOSITION              Composition spec, see `tapasco -h composition`
     NUM                      target operating frequency for PEs in MHz
Jens Korinth's avatar
Jens Korinth committed
54

55
56
57
58
59
60
61
62
63
64
65
66
67
68
    followed optionally by:
     -a | --architectures A+  list of Architectures to compose for, e.g.,
                              -a axi4mm, myarch
     -p | --platforms P+      list of Platforms to compose for, e.g.,
                              -p vc709, pynq
     --implementation NAME    selects a tool for synthesis, place-and-route
                              defualt: "Vivado"
     --features FEATURES      configures Features, see `tapasco -h features`
                              syntax: FEATURE [, FEATURE]*
     --debugMode NAME         dry run, no composition is executed; modes:
                                r     generate random result values
                                f     generate only timing failures
                                p     generate only placer errors
                                o     generate only other errors
Jens Korinth's avatar
Jens Korinth committed
69

70
71
72
73
74
    NOTE: Currently the  total number of PEs must be <= 128.
  
  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:
Jens Korinth's avatar
Jens Korinth committed
75

76
77
78
       COMPOSITION              '[' <KERNEL> x <COUNT> [, <KERNEL> x <COUNT>]* ']'
         KERNEL                 name of kernel/core, a quoted/unquoted string
         COUNT                  number of instances (0 < x <= 128)
Jens Korinth's avatar
Jens Korinth committed
79

80
81
82
83
84
85
86
87
88
    Examples:                   [ precision_counter x 128 ]
                                [arrayupdate x 4, arraysum x 8]
  
  Config Files:
    A config file is a Json (http://json.org) file consisting of a single
    configuration object. A configuration object can contain all parameters
    available on the command line, including the jobs, which are represented
    by an array of Job elements (same format as --jobsFile, see --help jobsFile
    for more info).
Jens Korinth's avatar
Jens Korinth committed
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
    You can generate an empty configuration via `tapasco -n config.json`.
  
  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 Platform combination. Useful for quick overviews over the available PEs.

    SYNTAX:                   corestats [option]*

    followed optionally by:
     -a | --architectures A+  list of Architectures , e.g.,
                              -a axi4mm, myarch
     -p | --platforms P+      list of Platforms , e.g.,
                              -p vc709, pynq
     --prefix STRING          file names of generated .csv files will be of the
                              format STRING<ARCH>@<PLATFORM>.csv
  
  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:
    
      1) Area / Utilization     primarily determined by the number of PEs.
      2) Target Frequency       chosen operating frequency
      3) Alternatives           a choice of alternative hardware implementations
                                for a kernel (identified by their ID, see
                                `tapasco -h import`)
   
   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 with 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:

     1) 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.
     2) 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.
     3) Other errors: This encompasses all other errors, e.g., missing licenses,
        system crashes, out-of-memory problems, etc.

    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 a preview of each active dimension.

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

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

    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.
  
  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:

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

    Examples:                   'OLED' [enabled -> true]
                                'LEDS' { enabled: true, inputs: "/system/LED_*" }
                                'BlueDMA' (enabled = true)
  
  Global Options:
    -n | --dryRun FILE        Dry run, do not execute, only dump Json into FILE.
    --archDir PATH            Base directory for architecture descriptions
    --compositionDir PATH     Output base directory for Compose jobs
    --coreDir PATH            Output base directory for HLS jobs, synthesized cores
    --kernelDir PATH          Base directory for kernel descriptions (HLS)
    --platformDir PATH        Base directory for platform descriptions
    --logFile FILE            Path to output log file
    --configFile FILE         Path to Json file with Configuration
    --jobsFile FILE           Path to Json file with Jobs array
    --slurm                   Activate SLURM cluster execution (requires sbatch)
    --parallel                Execute all jobs in parallel (careful!)
    --maxThreads NUM          Limit internal parallelism of activities (e.g., Vivado)
                              to the given number of threads.
  
  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 HLS 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`).

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

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

    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.
  
  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:

    SYNTAX:                   import <ZIP> as <ID> [option]*
      ZIP                     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.
      ID                      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`).

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