|
| 1 | +# P-ISA Tools |
| 2 | + |
| 3 | +## Table of Contents |
| 4 | +1. [Requirements](#requirements) |
| 5 | +2. [Build Configuration](#build-configuration) |
| 6 | + 1. [Build Type](#build-type) |
| 7 | + 1. [Third-Party Components](#third-party-components) |
| 8 | +3. [Building](#building) |
| 9 | +4. [Running the Program Mapper](#running-the-program-mapper) |
| 10 | +5. [Running the Functional Modelere](#running-the-functional-modeler) |
| 11 | +6. [Code Formatting](#code-formatting) |
| 12 | + |
| 13 | +## Requirements |
| 14 | + |
| 15 | +Currently, our build system uses `CMake`. |
| 16 | + |
| 17 | +### Currently tested configuration(s) |
| 18 | +- Ubuntu 22.04 (also tested on WSL2) |
| 19 | +- C++17 |
| 20 | +- GCC == 11.3.x   ***This version is a hard requirement at the moment*** |
| 21 | +- CMake >= 3.22.1 |
| 22 | +- SNAP (used to support graph features) |
| 23 | +- JSON for Modern CPP >= 3.11 |
| 24 | + |
| 25 | +## Build Configuration |
| 26 | + |
| 27 | +The current build system is minimally configurable but will be improved with |
| 28 | +time. The project directory is laid out as follows |
| 29 | + |
| 30 | +- __program_mapper__ *src directory for the Program mapper* |
| 31 | +- __kerngen__ *src directory for the Kernel generator* |
| 32 | +- __functional_modeler__ *src directory for the Functional modeler* |
| 33 | +- __common__ *Common code used by p-isa tools* |
| 34 | + |
| 35 | +**NOTE:** If using an IDE then it is recommended to set the `INC_HEADERS` flag |
| 36 | +to include the header files in the project filesystem. This can be done |
| 37 | +via `-DINC_HEADERS=TRUE`. |
| 38 | + |
| 39 | +### Build Type |
| 40 | + |
| 41 | +If no build type is specified, the build system will build in <b>Debug</b> |
| 42 | +mode. Use `-DCMAKE_BUILD_TYPE` configuration variable to set your preferred |
| 43 | +build type: |
| 44 | + |
| 45 | +- `-DCMAKE_BUILD_TYPE=Debug` : debug mode (default if no build type is specified). |
| 46 | +- `-DCMAKE_BUILD_TYPE=Release` : release mode. Compiler optimizations for release enabled. |
| 47 | +- `-DCMAKE_BUILD_TYPE=RelWithDebInfo` : release mode with debug symbols. |
| 48 | +- `-DCMAKE_BUILD_TYPE=MinSizeRel` : release mode optimized for size. |
| 49 | + |
| 50 | +#### Third-Party Components <a name="third-party-components"></a> |
| 51 | +The P-ISA tools require the following third party components: |
| 52 | + |
| 53 | +- [SNAP](https://github.com/snap-stanford/snap.git) |
| 54 | +- [JSON for modern c++](https://github.com/nlohmann/json) |
| 55 | + |
| 56 | +These external dependencies are fetched and built at configuration time by |
| 57 | +`cmake`, see below how to build the project. |
| 58 | + |
| 59 | +## Building |
| 60 | +Always build from the top level of p-isa-tools with Cmake as follows: |
| 61 | + |
| 62 | +```bash |
| 63 | +cmake -S . -B build -DCMAKE_BUILD_TYPE=Release |
| 64 | +cmake --build build -j |
| 65 | +``` |
| 66 | + |
| 67 | +Build type can also be changed to `Debug` depending on current needs (Debug |
| 68 | +should be used if the tool is being used to actively debug failing kernels). |
| 69 | + |
| 70 | +**NOTE:** Once the build completes, you will find the ***program_mapper*** and |
| 71 | +the ***functional_modeler*** executables in `build/bin` directory. |
| 72 | + |
| 73 | +## Running the Program Mapper |
| 74 | + |
| 75 | +The ***program_mapper*** is used to generate a graph of combined p-isa instructions |
| 76 | +with a supplementary memory file, and a combined p-isa kernel from a program |
| 77 | +trace. The program accepts a number of commandline options to control its usage. |
| 78 | + |
| 79 | +A typical run is of the form |
| 80 | +```bash |
| 81 | +program_mapper <program_trace.csv> <path-to-kerngen.py> |
| 82 | +``` |
| 83 | + |
| 84 | +The standard list of currently supported options are listed below. |
| 85 | +```bash |
| 86 | +Usage: |
| 87 | + program_mapper program_trace kerngen_loc OPTIONS |
| 88 | + |
| 89 | +POSITIONAL ARGUMENTS: 2 |
| 90 | +program_trace |
| 91 | + Location of a file containing a list in csv format for p_isa instructions |
| 92 | + |
| 93 | +kerngen_loc |
| 94 | + Location of the kerngen.py file |
| 95 | + |
| 96 | +OPTIONS: |
| 97 | +--cache_dir, --cache, -c <name of the kernel cache directory> |
| 98 | + Sets the name of the kernel cache directory [Default: ./kernel_cache] |
| 99 | + |
| 100 | +--disable_cache, --no_cache, -dc |
| 101 | + Disables the use of a cache for Ninja kernels |
| 102 | + |
| 103 | +--disable_graphs, --graphs, -g |
| 104 | + Disables graph building and features |
| 105 | + |
| 106 | +--disable_namespace, --nns, -n |
| 107 | + Disables applying register name spacing on PISAKernel nodes |
| 108 | + |
| 109 | +--dot_file_name, -df <name of the dot file to output> |
| 110 | + Sets the name of the output dot file |
| 111 | + |
| 112 | +--enable_memory_bank_output, --banks, -b |
| 113 | + Will output P-ISA programs with registers that include hard coded memory banks when enabled |
| 114 | + |
| 115 | +--export_dot, -ed |
| 116 | + Export seal trace and p_isa graphs to dot file format |
| 117 | + |
| 118 | +--out_dir, --out, -o <name of the output directory> |
| 119 | + Sets the location for all output files [Default: ./] |
| 120 | + |
| 121 | +--remove_cache, --rm_cache, -rc |
| 122 | + Remove the kernel cache directory at the end of the program |
| 123 | + |
| 124 | +--verbose, -v |
| 125 | + Enables more verbose execution reporting to std out |
| 126 | + |
| 127 | +-h, /h, \h, --help, /help, \help |
| 128 | + Shows this help. |
| 129 | +``` |
| 130 | + |
| 131 | +## Running the Functional Modeler |
| 132 | + |
| 133 | +The ***functional_modeler*** is used to functionally test p-isa kernels |
| 134 | +against a data trace (currently only obtained by tracing the excution of |
| 135 | +the MS-SEAL library) and debug kernel execution. In addition, the |
| 136 | +***functional_modeler*** can also generate a graph of the p-isa kernels, |
| 137 | +render such graphs into a visible graph, and estimates the perfomance of |
| 138 | +such kernels based on configurable HW models. |
| 139 | + |
| 140 | +The program accepts a number of commandline options to control its usage. |
| 141 | + |
| 142 | +A typical run is of the form |
| 143 | +```bash |
| 144 | +./functional_modeler <he_op.csv> --strace <he_op_trace_v0.json> |
| 145 | +``` |
| 146 | + |
| 147 | +The full list of currently supported options are listed below. |
| 148 | +```bash |
| 149 | +Usage: |
| 150 | + functional_modeler p_isa_op OPTIONS |
| 151 | + |
| 152 | +POSITIONAL ARGUMENTS: 1 |
| 153 | +p_isa_op |
| 154 | + Location of a file containing a list in CSV format for p_isa instructions |
| 155 | + |
| 156 | +OPTIONS: |
| 157 | + --json_data, --json, -jd Location of a json data file containing HEC formatted data |
| 158 | + --input_memory_file, --imem, -im Location of a memory file to be read and set as input before executing any instructions |
| 159 | + --output_memory_file, --omem, -om Location to write a memory file containing all device memory after all instructions have been executed |
| 160 | + --program_inputs_file, --pif, -if Location to a file containing program inputs in csv format. Loaded after any memory file(s) and data file but before execution |
| 161 | + --program_outputs_file, --pof, -of Location to write a file containing program outputs in csv format. Written after program execution |
| 162 | + --graph_file_name, --gn, -gf Sets the name of the file for the output graph image [ default=<p_isa_op_file_prefix>.png ] |
| 163 | + --hardware_model, -hwm Available hardware models - (HEC-relaxed-mem,HEC-strict-mem,example) |
| 164 | + --hec_dataformats_data, --hdd, -hd Location of HEC data-formats data manifest file |
| 165 | + --hec_dataformats_poly_program_location, --hdp, -pp Location of HEC data-formats poly program file |
| 166 | + --verbose, -v Enables more verbose execution reporting to stdout |
| 167 | + --render_graph, -rg Enables rendering of p_isa graph in PNG and DOT file formats |
| 168 | + --export_inputs, -ei Exports program inputs file to the file specified by --program_inputs_file or program_inputs.csv if none specified |
| 169 | + --advanced_performance_analysis, -apa Enables advanced performance analysis and cycle count prediction |
| 170 | + --verbose_output_checking, -voc Enables functional validation of functional execution |
| 171 | + --validate_intermediate_results, -vir Enables functional validation of intermediates - if --disable_function_validation, this will be automatically set to false |
| 172 | + --enable_advanced_debug_tracing, -dt Enables advanced debug execution and tracing. Warning: May significantly increase memory usage and reduce performance |
| 173 | + --hec_dataformats_mode, --hdfm, -hm Uses hec data-formats execution pipeline |
| 174 | + --disable_graphs, --graphs, -g Disables graph building and features |
| 175 | + --disable_functional_execution, --nofunctional Disable functional execution of instruction stream |
| 176 | + --disable_functional_validation, --novalidate, -nfv Disables functional validation of functional execution |
| 177 | + |
| 178 | +-h, /h, \h, --help, /help, \help |
| 179 | + Shows this help. |
| 180 | +``` |
| 181 | +
|
| 182 | +## Code Formatting |
| 183 | +The repository includes `pre-commit` and `clang-format` hooks to help ensure |
| 184 | +code consistency. It is recommended to install `pre-commit` and `pre-commit |
| 185 | +hooks` prior to committing to the repository. |
0 commit comments