Skip to content

README.md

Latest commit

 

History

History
100 lines (66 loc) · 4.44 KB

README.md

File metadata and controls

100 lines (66 loc) · 4.44 KB

HERACLES Code Generation Framework (Reference Implementation)

The tools in this directory are the reference implementation of and Assembler codegenerator that takes a pre-generated Polynomial Instruction Set Architecture (P-ISA) program containing instructions that use an abstract, flat memory model for polynomial operations, such as those applied in homomorphic encryption (HE), and maps them to a corresponding set of instructions compatible with the HERACLES architecture, accounting for hardware restrictions, including memory management for the HERACLES memory model.

Table of Contents

  1. Dependencies
  2. Inputs
  3. Outputs
    1. Assembler Instruction Specs
  4. Executing the Assembler
    1. Running for a Pre-Generated Kernel
  5. Debug Tools

Dependencies

This project is Python based. Dependencies for the project are as follows:

  • Python 3.10 or newer (Tested with 3.10)

  • Python pip 22.0 or newer

  • Requirements for the Python environment listed in file requirements.txt.

    Install with pip:

    pip3 install -r requirements.txt

It is recommended to install Python dependencies and run inside a Python virtual environment to avoid polluting the global Python.

Inputs

The assembler framework requires two inputs:

  • Abstract P-ISA kernel: a kernel of instructions in abstract P-ISA where the memory model is abstracted with a flat, infinite structure.

  • Memory mapping metadata: metadata information indicating the location where variable identifiers from the kernel are stored in the HERACLES HBM.

Kernels and metadata are structured in comma-separated value (csv) files.

P-ISA kernels, along with corresponding memory metadata required as input to the assembler, are generated by the upper layers in the Encrypted Computing SDK stack, e.g. the Program Mapper component of the p-ISA tools.

Outputs

On a successful run, given a P-ISA kernel in file filename.csv (and corresponding memory metadata file), the assmebler generates three files:

  • filename.minst: contains the list of instructions for the MINST queue.
  • filename.cinst: contains the list of instructions for the CINST queue.
  • filename.xinst: contains the list of instructions for the XINST queue.

Assembler Output Instruction Specs

The format for the output files and instruction set can be found at HCGF Instruction Specification.

Executing the Assembler

Running for a Pre-Generated Kernel

Given a P-ISA kernel (filename.csv) and corresponding memory mapping file (filename.mem), there are three steps to assemble them into HERACLES code.

  1. Pre-process the P-ISA input kernel using he_prep.py.
# pre-process kernel: outputs filename.tw.csv
python3 he_prep.py filename.csv
  1. Assemble the pre-processed result using he_as.py.
# use output from pre-processing as input to asm:
# outputs filename.tw.minst, filename.tw.cinst, filename.tw.xinst
python3 he_as.py filename.tw.csv --input_mem_file filename.mem
  1. Link the assembler output into a HERACLES program using he_link.py.
# link assembled output (input prefix: filename.tw)
# outputs filename.minst, filename.cinst, filename.xinst
python3 he_link.py filename.tw --input_mem_file filename.mem --output_prefix filename

This will generate the main three output files in the same directory as the input file:

  • filename.minst: contains the list of instructions for the MINST queue.
  • filename.cinst: contains the list of instructions for the CINST queue.
  • filename.xinst: contains the list of instructions for the XINST queue.

Intermediate files, if any, are kept as well.

The linker program is able to link several assembled kernels into a single HERACLES program, given a correct memory mapping for the resulting program.

This version of executing is intended for the assembler to be usable as part of a compilation pipeline.

Use commands below for more configuration information, including changing output directories, input and output filenames, etc.

python3 he_prep.py -h
python3 he_as.py -h
python3 he_link.py -h