HPVM User-Facing Tools

HPVM Provides the following user-facing tools: hpvm-clang, hcc, hpvm2fpga, keras_frontend, hpvm-dse, and torch2hpvm. These tools are described in detail below.

hpvm-clang

This is the main end-to-end compiler for HPVM. Accepts either HPVM-C or Hetero-C++ as input, and can compile the code to any supported back end, including Tensor back ends.

Usage

usage: hpvm-clang [-h] [-x language] [-b LINK_BITCODE [LINK_BITCODE ...]] [-t {tensor,cudnn}] [--conf-file CONF_FILE] [--hpvm-target {cpu,gpu,fpga}]
                  [--hetero-cc] [-d WORKING_DIR] [-I dir] [-D <macro>=<value>] [-f flag] [-O level] [--std STD] [-L dir] [-l name] [-F fpga_opt] [-v]
                  hpvm_src output_file

positional arguments:
  hpvm_src              HPVM-C/Hetero-C++ code to compile. HPVM-C code must be single file, but additional bitcode file can be linked together. See
                        option -b for that.
  output_file           Path to generate binary to

optional arguments:
  -h, --help            show this help message and exit
  -x language           Treat input file as having type <language>
  -b LINK_BITCODE [LINK_BITCODE ...], --link-bitcode LINK_BITCODE [LINK_BITCODE ...]
                        Additional bitcode (.ll/.bc) files to link to
  -t {tensor,cudnn}, --tensor-target {tensor,cudnn}
                        Backend to use for tensor operators
  --conf-file CONF_FILE
                        File to approximation configurations; required for tensor target 'tensor'
  --hpvm-target {cpu,gpu,fpga}
                        Backend to use for HPVM compilation
  --hetero-cc           Compile input file using the hetero-c++ frontend
  -d WORKING_DIR, --working-dir WORKING_DIR
                        Directory to generate temp files in
  -I dir, --include dir
                        [clang emit-llvm] Add directory to include search path
  -D <macro>=<value>    [clang emit-llvm] Define macro
  -f flag               [clang emit-llvm] clang++ flags (such as -ffastmath)
  -O level              [clang emit-llvm] Optimization level. Note that default is -O1.
  --std STD             [clang emit-llvm] Language standard to compile for. Double dashes (--std, not -std).
  -L dir                [clang linker] Add directory to library search path
  -l name               [clang linker] Link library (such as -lpthread)
  -F fpga_opt           [hpvm2fpga opt flags] Forward optimization flags to hpvm2fpga
  -v, --verbose         Print out all clang/opt/llvm-link commands used

hcc

This is the Hetero-C++ compiler. It can be used for compiling Hetero-C++ code to one of the supported HPVM targets (CPU, GPU, FPGA). It can be used instead of hpvm-clang.

Usage

hcc [options] <input bitcode file>

OPTIONS:


General options:

  --declsfile=<string>                              - HPVM-C declarations file

Generic Options:

  --help                                            - Display available options (--help-hidden for more)
  --help-list                                       - Display list of available options (--help-list-hidden for more)
  --version                                         - Display the version of this program

hcc Options:

  --control-only                                    - Only run the control-task pipeline in the HPVMCGenPass
  --dot-dfg                                         - Write final dataflow-graph graph to dot file
  --extract-only                                    - Only run the extract-task pipeline in the HPVMCGenPass
  -f                                                - Enable binary output on terminals
  --no-return-sizes                                 - Only propogate pointers through edges
  -o=<filename>                                     - Specify output filename
  --remove-dummy                                    - Remove redundant nodes in DFG and directly connect edges
  --sanitise-funcs                                  - Remove the . character from function names and replace them with _
  --use0D                                           - Create a 0D node in createNode instead of a 1D node with replication factor 1

hpvm2fpga

This tool invokes the end-to-end fpga compiler and optimizer for HPVM. It is used internally by hcc and hpvm-clang when targeting the FPGA. The tool uses the HPVM DFG and non-DFG transformations to optimize applications based on user-provided flags. The output of the tool is:

1. The LLVM module for the host code (to be compiled using LLVM’s X86 backend),

2. An OpenCL file containing the optimized FPGA kernels.

3. Optionally, the FPGA bitstream that gets generated by synthesizing the kernels using aoc.

Additionally, the tool can support compiling with full synthesis, partial syntehsis (i.e. RTL generation), or emulation using the Intel FPGA SDK for OpenCL Emulator.

Usage

The snipped below shows the usage of the hpvm2fpga tool with the most common command line flags. Please see hpvm2fpga --help for a full list of command line options.

hpvm2fpga [OPTIONS] <input>

    <input>: Input bitcode file (.ll or .bc) corresponding
             to the output of clang.

    OPTIONS:

    --help,         Print a help message that shows all options.
    --board=<s>,    Specify FPGA board. Default: "a10gx".
    Aailable Optimizaitons:
        --bufferin,     Perform input buffering.
        --argpriv,      Perform argument privatization.
        --unroll,       Perform loop unrolling.
        --fuse,         Perform loop fusion.
        --nodefuse,     Perform node fusion.
    --uf=<int>,     Set the unroll factor.
    --run-aoc,      Run ``aoc`` to generate ``.aocx`` file.
    --emu,          Enable Emulation mode. i.e. ``aocx`` file
                    and host binary will be configured to use
                    the Intel FPGA Emulator.
    --rtl,          Only perform partial ``aoc`` compilation
                    to generate RTL and compilation reports.

hpvm-dse

This tool invokes the design space exploration (DSE) framework that tunes Hetero-C++ applications automatically using the DFG and non-DFG transformations. The tool can be used to target FPGA or GPU. The DSE framework uses HyperMapper (HM) <https://github.com/luinardi/hypermapper> to traverse the design space.

Usage

The snipped below shows the usage of the hpvm-dse tool with the most common command line flags. Please see hpvm-dse --help for a full list of command line options.

hpvm-dse [OPTIONS] <input>

<input>: Input bitcode file (.ll or .bc) corresponding
         to the output of clang.

OPTIONS:

--help,                     Print a help message that shows all options.
Target Device for DSE (only one can be selected):
    --fpga,                 Specify FPGA target. Default.
    --gpu,                  Specify GPU target.
-b=<s>,                     Specify target FPGA board. Default: "a10gx".
--batch=<n>,                Set the batch size for DSE processing. Default: 1.
--custom-evaluator=<path>,  Path to script that evaluates objective for a
                            given target. Not needed for FPGA target.
--doe-multiplier=<n>,       Sets multiplier for DOE samples for HM.
                            Num DoE Samples =
                                "N x #Pramas if N > 1"
                                "#Pramas + 1 if N = 1".
                            Default: 1.
--dse-iter=<n>,             Set number of DSE iterations to perform.
                            Default: 20.
--max-uf=<n>,               Maximum unroll factor to use in DSE.
                            Default: 10.
--max-uf-options=<n>,       Maximum number of options to select for each
                            unrolling parameter. Default: 3.
-o=<folder>,                Specify output folder name.
--synth,                    Automatically run synthesis at the end of DSE.
                            Default: false.
--timeout=<int>,            Set the timeout (in sec) for each evaluation.
                            An evaluation that times out will be invalid.
                            Default: 900.

keras_frontend

See Keras Frontend for usage and examples.

torch2hpvm

See PyTorch Frontend for HPVM for usage and examples.