Closes #46 - Man pages

* wrote man pages for all executable in bin/
* also wrote man pages for the basic API headers and libraries

man/man1/itapasco.1

+.TH itapasco 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+itapasco \- The Interactive Task Parallel System Composer
+.SH SYNOPSIS
+.B itapasco
+[global options]* [jobs]*
+.SH DESCRIPTION
+A Swing-based GUI for tapasco. See tapasco(1) for details on the options.
+.SH ENVIRONMENT
+.TP
+.B TAPASCO_HOME
+.RS
+Path to TaPaSCo root installation folder (where setup.sh is located).
+.RE
+.SH SEE ALSO
+tapasco(1)

man/man1/tapasco-build-libs.1

+.TH tapasco-build-libs 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+tapasco-build-libs \- Build all libraries and kernel modules for tapasco(1).
+.SH SYNOPSIS
+.B tapasco-build-libs
+[options]*
+.SH DESCRIPTION
+The TaPaSCo runtime consists of three parts:
+.PP
+1.
+.B libtapasco (.so/.a)
+.PP
+2.
+.B libplatform (.so/.a)
+.PP
+3.
+.B loadable kernel module (LKM)
+.PP
+.B
+tapasco-build-libs can be used on the host system to build all three components
+from source (see below for build requirements). The user space libraries
+libtapasco(3) and libplatform(3) will reside below in $TAPASCO_HOME/arch/lib and
+$TAPASCO_HOME/platform/lib, respectively. The loadable kernel module can be
+found in $TAPASCO_HOME/platform/[PLATFORM]/module.
+.SH OPTIONS
+.TP
+\-h|\-\-help
+.RS
+print help message and exit
+.RE
+.TP
+\-\-mode (clean | release | debug | driver_debug)
+.RS
+build mode (default: release):
+.RS
+.I clean
+removes all binaries and intermediate outputs
+.PP
+.I release
+builds libraries and kernel module with minimal logging
+.PP
+.I debug
+builds libraries with configurable logging enabled, kernel module w/minimal logging
+.PP
+.I driver_debug
+like debug, but activates kernel message output, see dmesg(1)
+.RS
+.B NOTE: THIS COMES WITH A SEVERE PERFORMANCE PENALTY, NEVER USE FOR MEASUREMENTS!
+.RE
+.RE
+.RE
+.TP
+\-\-rebuild
+.RS
+force rebuild of libraries / LKM
+.RE
+.SH REQUIREMENTS
+.SS libtapasco and libplatform
+Reqyire cmake and working C and C++ compilers; in some cases, libatomic may be
+also required.
+.SS loadable kernel module
+Requires linux kernel headers for the currently running kernel. Can be supplied
+by setting the $LINUX_HOME environment variable.
+.SH ENVIRONMENT
+.TP
+.B TAPASCO_HOME
+.RS
+Path to TaPaSCo root installation folder (where setup.sh is located).
+.RE
+.SH SEE ALSO
+tapasco(1)

man/man1/tapasco-logviewer.1

+.TH tapasco-logviewer 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+tapasco-logviewer \- Graphical viewer tool for design space exploration logs.
+.SH SYNOPSIS
+.B tapasco-logviewer [LOGFILE]
+.SH DESCRIPTION
+A Swing-based log viewing tool for TaPaSCo. Design space exploration runs write
+a file called
+.I dse.json
+in their base directory. This file is in human-readable Json format and can be
+parsed by this tool to show an interactive graph representation.
+.SH ENVIRONMENT
+.TP
+.B TAPASCO_HOME
+.RS
+Path to TaPaSCo root installation folder (where setup.sh is located).
+.RE
+.SH SEE ALSO
+tapasco(1), itapasco(1)

man/man1/tapasco-reportviewer.1

+.TH tapasco-reportviewer 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+tapasco-reportviewer \- Graphical viewer tool for TaPaSCo report files.
+.SH SYNOPSIS
+.B tapasco-logviewer [REPORTFILE]
+.SH DESCRIPTION
+Debugging tool, a Swing-based report viewing tool for TaPaSCo. Any report file
+format "understood" by TaPaSCo will be shown as a key-value table.
+.SH ENVIRONMENT
+.TP
+.B TAPASCO_HOME
+.RS
+Path to TaPaSCo root installation folder (where setup.sh is located).
+.RE
+.SH SEE ALSO
+tapasco(1), itapasco(1)

man/man1/tapasco.1

+.TH tapasco 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+tapasco \- The Task Parallel System Composer
+.SH SYNOPSIS
+.B tapasco
+[global options]* [jobs]*
+.SH DESCRIPTION
+The
+.B Task Parallel System Composer (TaPaSCo, or TPC)
+is an FPGA toolchain to compose a task parallel on\-chip microarchitecture for
+multiple instances of application\-specific processing elements (PEs). TaPaSCo
+features an automatic design space exploration approach: It can vary both target
+operating frequency, as well as number of PE instances to aim for the ideal
+trade\-off between area utilization and frequency (the performance sweet spot
+for FPGA architectures).
+
+." *****************************************************************************
+.SH GLOBAL OPTIONS
+Global options affect all jobs in this run of tapasco.
+.TP
+\-\-archDir [PATH]
+.RS
+Base directory for architecture descriptions
+.RE
+.TP
+\-\-compositionDir [PATH]
+.RS
+Output base directory for Compose jobs
+.RE
+.TP
+\-\-coreDir [PATH}
+.RS
+Output base directory for HLS jobs, synthesized cores
+.RE
+.TP
+\-\-kernelDir [PATH]
+.RS
+Base directory for kernel descriptions (HLS)
+.RE
+.TP
+\-\-platformDir [PATH]
+.RS
+Base directory for platform descriptions
+.RE
+.TP
+\-\-logFile [FILE]
+.RS
+Path to output log file
+.RE
+.TP
+\-\-configFile [FILE]
+.RS
+Path to Json file with Configuration
+.RE
+.TP
+\-\-jobsFile [FILE]
+.RS
+Path to Json file with Jobs array
+.RE
+.TP
+\-\-slurm
+.RS
+Activate SLURM cluster execution (requires SLURM/sbatch)
+.RE
+
+." *****************************************************************************
+.SH COMPOSITION SYNTAX
+Compositions are a sequence of pairs of processing elements and their instance
+count. They can be specified as separate Json files, or inline:
+.PP
+\'[\' [NAME] \'x\' [COUNT] (\',\' [NAME] \'x\' [COUNT])* \']\'
+.TP
+where NAME is a valid PE identifier and COUNT a positive number > 0.
+.SS Example
+[counter x 24, arrayinit x 42]
+
+." *****************************************************************************
+.SH JOBS
+A
+.B job
+is a set of parameters for one of the activities TaPaSCo can perform:
+bulkimport, compose, corestats, dse, hls, import.
+See below for descriptions of the jobs and their corresponding activities.
+.PP
+Any number of consecutive jobs can be specified and will be executed
+sequentially. There is a Json format for all jobs, and a
+.B job file
+containing a Json array of jobs can be specified instead.
+
+." -----------------------------------------------------------------------------
+.SS bulkimport \-\-csv [FILE]
+Parses a file in
+.I  CSV (comma-separated values)
+format containing the following header:
+.PP
+.SM "Zip, ID, Description, Architecture, Platform, Avg Runtime (clock cycles)"
+.PP
+where Zip is the path to zip file, ID is the TaPaSCO function ID (used to call
+the PE in the APIs), Description is an optional text, Architecture and Platform
+are the names of the import Target.
+.PP
+.TP
+bulkimport \-\-csv [FILE]
+.RS
+[FILE] should be in comma-separated values (CSV) format and must contain the
+header line.
+.RE
+
+." -----------------------------------------------------------------------------
+.SS compose [composition] [frequency] [implementation]? [options]*
+Composes a microarchitecture for the given Composition. Will produce a .bit
+bitstream file in the \-\-compositionDir.
+.PP
+.B Mandatory Arguments
+.TP
+\-\-composition {[FILE] | [DEF]}
+.RS
+Threadpool composition, either in a separate Json file, or inline as arguments
+(see COMPOSITION SYNTAX).
+.RE
+.TP
+\-\-designFrequency [NUM]
+.RS
+Target design frequency (PE clock) in MHz.
+.RE
+.TP
+\-\-implementation [NAME]
+Composer implementation (default: Vivado)
+.PP
+.B Options
+.TP
+\-\-architectures|\-a [NAME] (\',\' [NAME])*
+.RS
+Filter for Architectures, restrict set of Architectures to names.
+.RE
+.TP
+\-\-platforms|-p [NAME] (\',\' [NAME])*
+.RS
+Filter for Platforms, restrict set of Platforms to names.
+.RE
+.TP
+\-\-debugMode [NAME]
+.RS
+Activates the given debug mode; currently implemented modes are:
+.RS
+.PP
+\'r\' generates random results, ranging from Success, PlacerErrors to
+TimingFailures
+.PP
+\'p\' always generate PlacerError
+.PP
+\'t\' always generate TimingFailure and
+.PP
+\'s\' always generate a Success, w/o reports.
+.RE
+.RE
+
+." -----------------------------------------------------------------------------
+.SS corestats [options]
+Collects results for all Cores in in coreDir from different reports (synthesis,
+utilization, power, ...) and stores them in one CSV file per Target, i.e.,
+Architecture + Platform combination.
+.PP
+.B Options
+.TP
+\-\-prefix [PREFIX]
+.RS
+Prefix file names with [PREFIX]. Files will be called
+"[PREFIX][ARCH]@[PLATFORM].csv".
+.RE
+.TP
+\-\-architectures|\-a [NAME] (\',\' [NAME])*
+.RS
+Filter for Architectures, restrict set of Architectures to names.
+.RE
+.TP
+\-\-platforms|-p [NAME] (\',\' [NAME])*
+.RS
+Filter for Platforms, restrict set of Platforms to names.
+.RE
+
+." -----------------------------------------------------------------------------
+.SS dse [composition] [dimensions] [batch size] [options]*
+Perform automatic
+.I design space exploration (DSE)
+for the given Composition, Targets (Architecture + Platform) and dimensions.
+.PP
+.B Mandatory Arguments
+.TP
+\-\-composition {[FILE] | [DEF]}
+.RS
+Threadpool composition, either in a separate Json file, or inline as arguments
+(see COMPOSITION SYNTAX).
+.RE
+.TP
+\-\-dimensions [dimension] [\',\' [dimension]]* where [dimension] is one of
+.RS
+.I area
+activate utilization variation, i.e., linear scaling of PE instance counts
+.PP
+.I frequency
+activate frequency variation, i.e., automatic selection of PE clock frequency
+.PP
+.I alternatives
+activate alternative implementations, i.e., allow TaPaSCo to replace any PE with
+a PE with the same ID.
+.RS
+.PP
+Example:
+Let "counter" and "countdown" both have ID 14; then a Composition
+.RS
+[counter x 12]
+.RE
+may be changed by the DSE to be
+.RS
+[countdown x 12]
+.RE
+.RE
+.RE
+.TP
+\-\-batchSize [NUM]
+.RS
+Excute [NUM] runs in parallel in each batch; should not exceed the number of
+available processors and licences.
+.RE
+
+.PP
+.B Options
+.TP
+\-\-basePath [PATH]
+.RS
+Output base directory for all Compositions etc. (default: $TAPASCO_HOME/DSE_[TIMESTAMP]).
+.RE
+.TP
+\-\-heuristic [heuristic]
+Select design space ordering heuristic (default: job throughput).
+.TP
+\-\-frequency [NUM]
+.RS
+Initial target design frequency (PE clock) in MHz.
+.RE
+.TP
+\-\-implementation [NAME]
+.RS
+Composer implementation (default: Vivado)
+.RE
+.TP
+\-\-architectures|\-a [NAME] (\',\' [NAME])*
+.RS
+Filter for Architectures, restrict set of Architectures to names.
+.RE
+.TP
+\-\-platforms|-p [NAME] (\',\' [NAME])*
+.RS
+Filter for Platforms, restrict set of Platforms to names.
+.RE
+.TP
+\-\-debugMode [NAME]
+.RS
+Activates the given debug mode; see compose.
+.RE
+
+." -----------------------------------------------------------------------------
+.SS hls [options]*
+Execute High-Level Synthesis to turn Kernel into Core instances for the
+specified Targets (Architecture + Platform).
+.PP
+.B Options
+.TP
+\-\-implementation [NAME]
+.RS
+Composer implementation (default: VivadoHLS)
+.RE
+.TP
+\-\-kernels|-k [NAME] (\',\' [NAME])*
+.RS
+Filter for Kernels, restrict set of Kernels to names.
+.RE
+.TP
+\-\-architectures|\-a [NAME] (\',\' [NAME])*
+.RS
+Filter for Architectures, restrict set of Architectures to names.
+.RE
+.TP
+\-\-platforms|-p [NAME] (\',\' [NAME])*
+.RS
+Filter for Platforms, restrict set of Platforms to names.
+.RE
+
+." -----------------------------------------------------------------------------
+.SS import [options]*
+Imports a existing IP-XACT core archive into the core library of TaPaSCo for the
+specified Targets (Architecture + Platform). Will perform
+.I out-of-context (OOC) synthesis
+if existing reports cannot be found, to generate estimates for area utilization,
+max. operating frequency and power consumption.
+.PP
+.B Options
+.TP
+\-\-zip [FILE]
+.RS
+Path to .zip file containing IP-XACT core (sources + component.xml).
+.RE
+.TP
+\-\-id [NUM]
+.RS
+Kernel ID (> 0) for use in TaPaSCO (used by APIs).
+.RE
+.TP
+\-\-averageClockCycles [NUM]
+.RS
+Avg. clock cycles per execution (optional).
+.RE
+.TP
+\-\-description "[TEXT]"
+.RS
+Kernel description text (optional).
+.RE
+.TP
+\-\-architectures|\-a [NAME] (\',\' [NAME])*
+.RS
+Filter for Architectures, restrict set of Architectures to names.
+.RE
+.TP
+\-\-platforms|-p [NAME] (\',\' [NAME])*
+.RS
+Filter for Platforms, restrict set of Platforms to names.
+.RE
+.SH ENVIRONMENT
+.TP
+.B TAPASCO_HOME
+.RS
+Path to TaPaSCo root installation folder (where setup.sh is located).
+.RE
+
+.SH SEE ALSO
+itapasco(1), tapasco-build-libs(1), tapasco-logviewer(1),
+tapasco-reportviewer(1), tapasco-load-bitstream(8), libtapasco(3),
+libplatform(3), tapasco-api.h(3), tapasco-api.hpp(3), platform-api.h(3)

man/man3/libplatform.3

+.TH libplatform 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+libplatform \- User space library for TaPaSCO, the Task Parallel System Composer.
+.SH DESCRIPTION
+TaPaSCo microarchitectures consist of two parts: The
+.I Architecture
+and the
+.I Platform.
+Architecture is resonsible for the organization and wiring of the processing
+elements, as well as their control interface. Platform is responsible for the
+rest of the design, e.g., the communication to the host, access to memory,
+peripherals.
+.PP
+libplatform contains the Platform's implemenation of the Platform API (see
+platform-api.h(3)).
+.SH SEE ALSO
+tapasco(1), tapasco-api.h(3)

man/man3/libtapasco.3

+.TH libtapasco 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+libtapasco \- User space library for TaPaSCO, the Task Parallel System Composer.
+.SH DESCRIPTION
+TaPaSCo microarchitectures consist of two parts: The
+.I Architecture
+and the
+.I Platform.
+Architecture is resonsible for the organization and wiring of the processing
+elements, as well as their control interface. Platform is responsible for the
+rest of the design, e.g., the communication to the host, access to memory,
+peripherals.
+.PP
+libtapasco contains the Architecture's implementation of the Tapasco API (see
+tapasco-api.h(3)).
+.SH SEE ALSO
+tapasco(1), tapasco-api.h(3)

man/man3/platform-api.h.3

+.TH platform-api.h 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+platform-api.h \- Header include for libplatform(3), defines the Platform API.
+.SH DESCRIPTION
+TaPaSCo microarchitectures consist of two parts: The
+.I Architecture
+and the
+.I Platform.
+Architecture is resonsible for the organization and wiring of the processing
+elements, as well as their control interface. Platform is responsible for the
+rest of the design, e.g., the communication to the host, access to memory,
+peripherals.
+.PP
+platform-api.h defines the programming interface at Platform level. It should
+not be used directly, only implementations of tpc-api.h(3) should use it to
+implement their functionality in Platform-agnostic manner.
+.PP
+Platform API defines low-level interactions with the Platform, e.g., provides
+access to the memory and register spaces
+.PP
+Each Platform provides its own implementation of platform-api.h in
+libplatform(3).
+.SH SEE ALSO
+tapasco(1), libtapasco(3), tapasco-api.h(3), libplatform(3)

man/man3/tapasco-api.h.3

+.TH tapasco-api.h 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+tapasco-api.h \- Header include for libtapasco(3), define Tapasco API.
+.SH DESCRIPTION
+TaPaSCo microarchitectures consist of two parts: The
+.I Architecture
+and the
+.I Platform.
+Architecture is resonsible for the organization and wiring of the processing
+elements, as well as their control interface. Platform is responsible for the
+rest of the design, e.g., the communication to the host, access to memory,
+peripherals.
+.PP
+tpc-api.h defines the user-facing API for applications, i.e., the interface
+user applications program against to interface with TaPaSCo hardware. It defines
+methods to query bitstreams, transfer data from and to the device, configure and
+launch jobs, among other things (see inline documentation).
+.PP
+Each Architecture provides its own implementation of tapasco-api.h in
+libtapasco(3).
+.SH SEE ALSO
+tapasco(1), libtapasco(3)

man/man3/tapasco-api.hpp.3

+.TH tapasco-api.h 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+tapasco-api.h \- C++ header include for libtapasco(3), define Tapasco API.
+.SH DESCRIPTION
+TaPaSCo microarchitectures consist of two parts: The
+.I Architecture
+and the
+.I Platform.
+Architecture is resonsible for the organization and wiring of the processing
+elements, as well as their control interface. Platform is responsible for the
+rest of the design, e.g., the communication to the host, access to memory,
+peripherals.
+.PP
+tapasco-api.h(3) defines the user-facing API for applications, i.e., the 
+interface user applications program against to interface with TaPaSCo hardware.
+It defines methods to query bitstreams, transfer data from and to the device,
+configure and launch jobs, among other things (see inline documentation).
+.PP
+tapasco-api.hpp defines a convenient wrapper for tapasco-api.h(3), removing most
+of the boiler plate code. See inline documentation for details.
+.SH SEE ALSO
+tapasco(1), libtapasco(3)

man/man8/tapasco-load-bitstream.8

+.TH tapasco-load-bitstream 1 "May 11, 2017" "version 2017.1"  "USER COMMANDS"
+.SH NAME
+tapasco-load-bitstream \- Program FPGA with given bitstream.
+.SH SYNOPSIS
+.B tapasco-load-bitstream
+ [-h] [--reload-driver] [--verbose] BITSTREAM
+.SH DESCRIPTION
+Loads the given BITSTREAM file in .bit format and programs the currently
+selected device (see tpc-build-libs(1)). May require Vivado Design Suite,
+depending on the Platform.
+.SH OPTIONS
+.TP
+\-h|\-\-help
+.RS
+print help message and exit
+.RE
+.TP
+\-\-verbose
+.RS
+verbose output (default: false)
+.RE
+.TP
+\-\-reload\-driver
+.RS
+reload driver, if loaded (default: false)
+.RE
+.SH ENVIRONMENT
+.TP
+.B TAPASCO_HOME
+.RS
+Path to TaPaSCo root installation folder (where setup.sh is located).
+.RE
+.SH SEE ALSO
+tapasco(1), tapasco-build-libs(1)

setup.sh

 export TAPASCO_HOME=$PWD
 export PATH=$TAPASCO_HOME/bin:$PATH
+export MANPATH=$MANPATH:$TAPASCO_HOME/man
 # source ~/vivado_15.sh