Usage.scala 16.6 KB
Newer Older
1
package de.tu_darmstadt.cs.esa.tapasco.parser
2
3

object Usage {
4
5
  private final val logger = de.tu_darmstadt.cs.esa.tapasco.Logging.logger(getClass)

6
7
  def apply(): String = usage

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
  def apply(topic: Option[String]) {
    logger.info(helpTopics.get((topic getOrElse "usage" toLowerCase)).map(_.apply()) getOrElse usage)
    System.exit(0)
  }

  private final val helpTopics: Map[String, () => String] = Map(
    "jobsfile"   -> jobsFile _,
    "configfile" -> configFile _,
    "globals"    -> globals _,
    "bulkimport" -> bulkimport _,
    "compose"    -> compose _,
    "corestats"  -> corestats _,
    "import"     -> importzip _,
    "hls"        -> hls _,
    "explore"    -> explore _,
    "composition"-> composition _,
    "features"   -> features _,
    "topics"     -> topics _,
    "manpage"    -> manpage _
  )

  private def topics() = helpTopics.keys.toSeq.sorted
    .filterNot(_ equals "manpage") mkString ", "

  private def configFile() = """
  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).

    You can generate an empty configuration via `tapasco -n config.json`.
  """

  private def jobsFile() = """
  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`.
  """

  private def globals()    = """
  Global Options:
53
54
55
    -v | --verbose [MODE]     Verbose mode, log outputs of subprocesses;
                              Optional MODE is a quoted string selecting the
                              output mode (default: 'verbose')
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
    -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.
  """

  private def composition() = """
  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:

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

    Examples:                   [ precision_counter x 128 ]
                                [arrayupdate x 4, arraysum x 8]
  """

  private def features() = """
  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)
  """

  private def bulkimport() = """
  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. 

    SYNTAX:                   bulkimport <CSV>
      where
      CSV                     Path to file in comma-separated values (CSV) format,
                              must contain the following header line and columns:
117
118

      "Zip, ID, Description, Architecture, Platform, Avg Runtime (clock cycles)"
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
  private def compose()    = """
  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

      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)

    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`).

    SYNTAX:                   compose <COMPOSITION> @ <NUM> MHz [option]*
     where
     COMPOSITION              Composition spec, see `tapasco -h composition`
     NUM                      target operating frequency for PEs in MHz

    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

    NOTE: Currently the  total number of PEs must be <= 128.
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

  private def corestats()  = """
  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
  """
  private def importzip()  = """
  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
  """

  private def hls()        = """
  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.
  """

  private def explore()    = """
  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.
  """

  private def shortJobs() = """
  Jobs:                       see `tapasco -h <job>` for details
    bulkimport                Bulk import of IP-XACT core .zips.
    compose                   Generate bitstream for a single Composition.
    corestats                 Generate a .csv file with synth data for Cores.
    explore                   Perform a design space exploration.
    hls                       Perform high-level synthesis for PEs.
    import                    Import a single IP-XACT core .zip.
  """

  private def shortTopics() = {
    val ts = helpTopics.keys.toSeq.sorted
    val  n = ts.length / 2
    val  f = ts.take(n).mkString(", ")
    val  s = ts.drop(n).mkString(", ")
    s"""
  Help topics:
    $f
    $s
    """
  }
  
  private def overview() = """
Tapasco - Usage: tapasco [global option]* [job]*
             or: tapasco -h | --help [TOPIC]
  """

  private def usage() = Seq(
    overview(),
    globals,
    shortJobs,
    shortTopics
  ) mkString

  private def manpage() = (Seq(overview, globals) ++
    (topics.split(", ").filterNot(_ equals "topics") map (k => helpTopics(k)()))
  ).mkString
359
}