Commit 1914aec8 authored by Jens Korinth's avatar Jens Korinth
Browse files

Fix broken main man page and update

* man tapasco page is broken, was too optimistic that man would be able
  to parse the ASCII format directly (works on Darwin)
* replaced hard-coded strings with mini-markup language
* Formatters can produce any kind of representation
* same code is used to produce CLI output and man pages
* will simplify the updates in the future
parent 3959bfb3
Tapasco - Usage: tapasco [global option]* [job]* .TH tapasco 1 2017.1 MAN(1)
or: tapasco -h | --help [TOPIC] .SH SYNOPSIS
tapasco [global option]* [job]*
Global Options: or: tapasco \-h | \-\-help [TOPIC]
-n | --dryRun FILE Dry run, do not execute, only dump Json into FILE.
--archDir PATH Base directory for architecture descriptions .SH GLOBAL OPTIONS
--compositionDir PATH Output base directory for Compose jobs .RS
--coreDir PATH Output base directory for HLS jobs, synthesized cores \-v | \-\-verbose [MODE]
--kernelDir PATH Base directory for kernel descriptions (HLS) .RS
--platformDir PATH Base directory for platform descriptions Verbose mode, log outputs of subprocesses; optional MODE is a quoted string selecting the output mode
--logFile FILE Path to output log file (default: 'verbose')
--configFile FILE Path to Json file with Configuration .RE
--jobsFile FILE Path to Json file with Jobs array .RE
--slurm Activate SLURM cluster execution (requires sbatch) .RS
--parallel Execute all jobs in parallel (careful!) \-n | \-\-dryRun FILE
--maxThreads NUM Limit internal parallelism of activities (e.g., Vivado) .RS
to the given number of threads. Dry run, do not execute, only dump Json into FILE.
.RE
Bulk Import Job: .RE
Bulk import jobs can import multiple IP-XACT core .zip files in row. The .RS
required import parameters are given a CSV file instead of manually via the \-\-archDir PATH
command line. .RS
Base directory for architecture descriptions
SYNTAX: bulkimport <CSV> .RE
where .RE
CSV Path to file in comma-separated values (CSV) format, .RS
must contain the following header line and columns: \-\-compositionDir PATH
.RS
"Zip, ID, Description, Architecture, Platform, Avg Runtime (clock cycles)" Output base directory for Compose jobs
.RE
Compose Job: .RE
Generate a full-system bitstream from spec. Compose jobs are the core of .RS
TaPaSCo and comprise the construction of the system design, synthesis and \-\-coreDir PATH
place-and-route, as well as high-level synthesis of cores (if necessary). .RS
Output base directory for HLS jobs, synthesized cores
To generate a design, one needs to specify .RE
.RE
1) the Composition (see below) .RS
2) the Architecture (i.e., organization of PEs in the design) \-\-kernelDir PATH
3) the Platform (i.e., target hardware) .RS
4) the target design frequency (operating frequency of the PEs) Base directory for kernel descriptions (HLS)
.RE
If Architecture or Platform selection is ommitted, TaPaSCo will build .RE
bitstreams for all available Architectures and Platforms in parallel. .RS
Resource restrictions apply normally (e.g., won't launch more runs than \-\-platformDir PATH
CPUs available, etc.). The resulting projects and bitstreams can be found .RS
in the directory hierarchy below the currently configured Composition Base directory for platform descriptions
directory (see `tapasco -h globals`). .RE
.RE
SYNTAX: compose <COMPOSITION> @ <NUM> MHz [option]* .RS
where \-\-logFile FILE
COMPOSITION Composition spec, see `tapasco -h composition` .RS
NUM target operating frequency for PEs in MHz Path to output log file
.RE
followed optionally by: .RE
-a | --architectures A+ list of Architectures to compose for, e.g., .RS
-a axi4mm, myarch \-\-configFile FILE
-p | --platforms P+ list of Platforms to compose for, e.g., .RS
-p vc709, pynq Path to Json file with Configuration
--implementation NAME selects a tool for synthesis, place-and-route .RE
defualt: "Vivado" .RE
--features FEATURES configures Features, see `tapasco -h features` .RS
syntax: FEATURE [, FEATURE]* \-\-jobsFile FILE
--debugMode NAME dry run, no composition is executed; modes: .RS
r generate random result values Path to Json file with Jobs array
f generate only timing failures .RE
p generate only placer errors .RE
o generate only other errors .RS
\-\-slurm
NOTE: Currently the total number of PEs must be <= 128. .RS
Activate SLURM cluster execution (requires sbatch)
Composition Syntax: .RE
A Composition specifies the number and kind of processing elements (PEs) that .RE
are present in the design. The basic command line syntax is as follows: .RS
\-\-parallel
COMPOSITION '[' <KERNEL> x <COUNT> [, <KERNEL> x <COUNT>]* ']' .RS
KERNEL name of kernel/core, a quoted/unquoted string Execute all jobs in parallel (careful!)
COUNT number of instances (0 < x <= 128) .RE
.RE
Examples: [ precision_counter x 128 ] .RS
[arrayupdate x 4, arraysum x 8] \-\-maxThreads NUM
.RS
Config Files: Limit internal parallelism of activities (e.g., Vivado) to the given number of threads.
A config file is a Json (http://json.org) file consisting of a single .RE
configuration object. A configuration object can contain all parameters .RE
available on the command line, including the jobs, which are represented .SH BULK IMPORT JOB
by an array of Job elements (same format as --jobsFile, see --help jobsFile Bulk import jobs can import multiple IP\-XACT core .zip files in row. The
for more info). required import parameters are given a CSV file instead of manually via the
command line.
You can generate an empty configuration via `tapasco -n config.json`.
.RS
Core Statistics Job: Syntax
Evaluation helper job that automatically gathres the out-of-context results .RS
for all Cores, Architectures and Platforms in one .csv file per Architecture bulkimport <CSV>
and Platform combination. Useful for quick overviews over the available PEs. .RE
.RE
SYNTAX: corestats [option]* .RS
where
followed optionally by: .RS
-a | --architectures A+ list of Architectures , e.g., CSV
-a axi4mm, myarch .RS
-p | --platforms P+ list of Platforms , e.g., Path to file in comma\-separated values (CSV) format, must contain the following header line and columns:
-p vc709, pynq .RE
--prefix STRING file names of generated .csv files will be of the .RE
format STRING<ARCH>@<PLATFORM>.csv
Zip, ID, Description, Architecture, Platform, Avg Runtime (clock cycles)
Design Space Exploration Job: .RE
Even simple hardware designs often require a surprisingly high number of .SH COMPOSE JOB
design choices. It is difficult to estimate the impact of each choice on Generate a full\-system bitstream from spec. Compose jobs are the core of
the total result. TaPaSCo supports the designer by offering an automated TaPaSCo and comprise the construction of the system design, synthesis and
Design Space Exploration (DSE): TaPaSCo designs can primarily be varied in place\-and\-route, as well as high\-level synthesis of cores (if necessary).
three dimensions:
To generate a design, one needs to specify
1) Area / Utilization primarily determined by the number of PEs.
2) Target Frequency chosen operating frequency .RS
3) Alternatives a choice of alternative hardware implementations 1) the Composition (see below)
for a kernel (identified by their ID, see 2) the Architecture (i.e., organization of PEs in the design)
`tapasco -h import`) 3) the Platform (i.e., target hardware)
4) the target design frequency (operating frequency of the PEs)
TaPaSCo's DSE mode can automatically explore this design space using a user- .RE
selectable performance heuristic. The default heuristic approximates the
maximal job throughput of the system: Current operating frequency and the If Architecture or Platform selection is ommitted, TaPaSCo will build bitstreams
average clock cycles per job execution of each PE in the design are forr all available Architectures and Platforms in parallel. Resource
extrapolated with the instance numbers to yield an upper bound on the total restrictions apply normally (e.g., won't launch more runs than CPUs available,
job throughput of the system. This number is used as a relative "fitness" etc.). The resulting projects and bitstreams can be found in the directory
indicator for the comparison of different Compositions. The design space can hierarchy below the currently configured Composition directory (see `tapasco \-h
be linearized by descending value for each element. globals`)..
TaPaSCo explores the design space by batches: Each batch consists of a .RS
configurable number of design space elements (i.e., Composition + frequency Syntax
pairs); all elements are run in parallel via 'compose'. The successful .RS
element with the highest heuristic value is returned. compose <COMPOSITION> @ <NUM> MHz [option]*
.RE
In case of errors, three cases must be distinguished: .RE
.RS
1) Placer errors affect all design space elements with the same or a higher where
number of PEs; none of them will be placeable and they will therefore .RS
be pruned from the design space. COMPOSITION
2) Timing failures affect only the given element, but generate a feedback .RS
element: A new design space element is generated for the same Composition spec, see `tapasco \-h composition`
Composition, but with a lower target frequency. The frequency is .RE
computed from the 'worst negative slack' reported by the composer tools. .RE
I.e., a failed Composition with 100 MHz target frequency and 0.9ns WNS .RS
would give a new element with 97.74 MHz (T=10.9ns) frequency. NUM
3) Other errors: This encompasses all other errors, e.g., missing licenses, .RS
system crashes, out-of-memory problems, etc. target operating frequency for PEs in MHz
.RE
TaPaSCo can run explorations in any combination of the three dimensions. To .RE
get a better idea of each dimension, you can use `itapasco` to configure DSE .RE
and get a preview of each active dimension.
followed optionally by:
SYNTAX: explore <COMPOSITION> [<FREQ>] in <DIMS> [option]* .RS
COMPOSITION Composition spec, see `tapasco -h composition` .RS
FREQ '@' <NUM> [MHz] \-a | \-\-architectures A+
initial design frequency in MHz, optional .RS
DIMS list of active dimensions, e.g., list of Architectures to compose for, e.g., \-a axi4mm, myarch
area, frequency, alternatives .RE
.RE
followed optionally by: .RS
-a | --architectures A+ list of Architectures , e.g., \-p | \-\-platforms P+
-a axi4mm, myarch .RS
-p | --platforms P+ list of Platforms , e.g., list of Platforms to compose for, e.g., \-p vc709, pynq
-p vc709, pynq .RE
--basePath PATH output base path for DSE results, including .RE
config files, projects and bitstreams .RS
default: DSE_<CURRENT DATE> \-\-implementation NAME
--batchSize NUM number of elements in each batch .RS
default: number of CPUs selects a tool for synthesis, place\-and\-route
--debugMode NAME dry run, no compositions are executed, see default: "Vivado"
`tapasco -h compose` .RE
--features FEATURES configures Features, see `tapasco -h features` .RE
syntax: FEATURE [, FEATURE]* .RS
--heuristic NAME select heuristic function \-\-features FEATURES
default: 'job throughput' .RS
--implementation NAME selects a tool for synthesis, place-and-route configures Features, see `tapasco \-h features`
default: "Vivado" syntax: FEATURE [, FEATURE]*
.RE
NOTE: All HLS kernels are located in the directories below the currently .RE
configured Kernel directory (see `tapasco -h globals`). Each kernel .RS
requires a description in a simple Json format, examples can be found \-\-debugMode NAME
in $TAPASCO_HOME/kernel. .RS
dry run, no composition is executed; modes:
Features Syntax: .RE
The hardware designs generated by TaPaSCo offer a great amount of flexibility .RE
using a dynamic plug-in interface; a plug-in can extend or modify the .RS
resulting design. By default, most plug-ins are disabled and must be activated .RS
by the user. This is done via a Feature specification: A Feature contains the r
configuration parameters for a plug-in. The basic command line syntax is as .RS
follows: generate random result values
.RE
FEATURE <NAME> <BEGIN> [<KEYVALUE> [, <KEYVALUE>]*] <END> .RE
NAME any quoted or unquoted string .RS
BEGIN one of '[', '{' or '(' f
END one of ']', '}, or ')' .RS
KEYVALUE <KEY> <ASSIGN> <VALUE> generate only timing failures
KEY any quoted or unquoted string .RE
ASSIGN either '->', '=', ':=' or ':' .RE
VALUE any quoted or unquoted string .RS
p
Examples: 'OLED' [enabled -> true] .RS
'LEDS' { enabled: true, inputs: "/system/LED_*" } generate only placer errors
'BlueDMA' (enabled = true) .RE
.RE
Global Options: .RS
-n | --dryRun FILE Dry run, do not execute, only dump Json into FILE. o
--archDir PATH Base directory for architecture descriptions .RS
--compositionDir PATH Output base directory for Compose jobs generate only other errors
--coreDir PATH Output base directory for HLS jobs, synthesized cores .RE
--kernelDir PATH Base directory for kernel descriptions (HLS) .RE
--platformDir PATH Base directory for platform descriptions .RE
--logFile FILE Path to output log file .RE
--configFile FILE Path to Json file with Configuration
--jobsFile FILE Path to Json file with Jobs array NOTE: Currently the total number of PEs must be <= 128.
--slurm Activate SLURM cluster execution (requires sbatch) .SH COMPOSITION SYNTAX
--parallel Execute all jobs in parallel (careful!) A Composition specifies the number and kind of processing elements (PEs) that
--maxThreads NUM Limit internal parallelism of activities (e.g., Vivado) are present in the design. The basic command line syntax is as follows:
to the given number of threads.
.RS
High-Level Synthesis Job: COMPOSITION
TaPaSCo facilitates rapid prototyping for FPGA accelerators by directly .RS
supporting hardware written in C/C++ via HLS. The hls job is used to trigger '[' <KERNEL> x <COUNT> [, <KERNEL> x <COUNT>]* ']'
the HLS tool and synthesize hardware for a given Architecture and Platform. .RE
.RE
If Architecture or Platform selection is ommitted, TaPaSCo will build .RS
cores for all available Architectures and Platforms in parallel. .RS
Resource restrictions apply normally (e.g., won't launch more runs than KERNEL
CPUs available, etc.). The resulting cores can be found in the directory .RS
hierarchy below the currently configured Core directory name of kernel/core, a quoted/unquoted string
(see `tapasco -h globals`). .RE
.RE
SYNTAX: hls <KERNELS> [option]* .RS
KERNELS all | <KERNEL> [, <KERNEL]* COUNT
where KERNEL is a kernel name as quoted or .RS
unquoted string; special target 'all' builds all number of instances (0 < x <= 128)
available kernels. .RE
.RE
followed optionally by: .RE
-a | --architectures A+ list of Architectures , e.g.,
-a axi4mm, myarch .RS
-p | --platforms P+ list of Platforms , e.g., Examples:
-p vc709, pynq .RS
--implementation NAME selects a HLS tool by name [ precision_counter x 128 ]
default: "VivadoHLS" [arrayupdate x 4, arraysum x 8]
.RE
NOTE: All HLS kernels are located in the directories below the currently .RE
configured Kernel directory (see `tapasco -h globals`). Each kernel .SH CONFIG FILES
requires a description in a simple Json format, examples can be found 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).
in $TAPASCO_HOME/kernel.
You can generate an empty configuration via `tapasco \-n config.json`.
Import Job: .SH CORE STATISTICS JOB
TaPaSCo supports the use of High-Level Synthesis (HLS) tools (such as Xilinx Evaluation helper job that automatically gathres the out\-of\-context results
Vivado HLS) for the synthesis of processing element hardware modules from for all Cores, Architectures and Platforms in one .csv file per Architecture and
C/C++ automatically (see `tapasco -h hls`). To make existing IP available as Platformm combination. Useful for quick overviews over the available PEs.
PEs in TaPaSCo, you can use the import command:
.RS
SYNTAX: import <ZIP> as <ID> [option]* Syntax
ZIP path to .zip file containing an IP-XACT .RS
description (e.g., component.xml and Verilog/VHDL corestats [option]*
sources); can be generated, e.g., via Xilinx .RE
Vivado, menu Tools -> Create and package IP. .RE
ID any integer > 0; this ID is used to identify the
PEs in the hardware and software layers of TaPaSCo followed optionally by:
Core with the same ID are considered to be .RS
alternative implementations of the same interface .RS
and should be exchangeable (see `tapasco -h \-a | \-\-architectures A+
explore`). .RS
list of Architectures , e.g., \-a axi4mm, myarch
followed optionally by: .RE
-a | --architectures A+ list of Architectures , e.g., .RE
-a axi4mm, myarch .RS
-p | --platforms P+ list of Platforms , e.g., \-p | \-\-platforms P+
-p vc709, pynq .RS
--description TEXT any quoted or unquoted string containing list of Platforms , e.g., \-p vc709, pynq
additional information about the core .RE
--averageClockCycles N any integer > 0; number of clock cycles in an .RE
"average" execution of the PE; used to estimate .RS
the maximal throughput \-\-prefix STRING
.RS
Jobs files: file names of generated .csv files will be of the format STRING<ARCH>@<PLATFORM>.csv
Jobs files are Json (http://json.org) files consisting of an array of Job .RE
definitions. See $TAPASCO_HOME/json-examples/jobs/Jobs.json for an example .RE
containing one instance of each job. Alternatively, generate an empty .RE
configuration via `tapasco -n config.json`. .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