add openfhe tracer (w/ end-to-end example)

Note: `run_tracing_example` target works up to expected functional modeler issue `key not found: partQHatInvModq_0_0`
which is due to the fact that partQHatInvModq is no longer present in recent OpenFHE versions.

Author: AlexanderViand

.typos.toml

@@ -8,6 +8,8 @@
 # variation of params
 parms = "parms"
 bload = "bload"
+ser = "ser"
+SerType = "SerType"
 
 [files]
 extend-exclude = [

p-isa_tools/CMakeLists.txt

@@ -22,12 +22,15 @@ else()
   set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "Choose the type of Build" FORCE)
 endif()
 
-option(ENABLE_DATA_FORMATS "Enable support for the data formats library" OUTPUT_NAME_<CONFIG>)
+option(ENABLE_DATA_FORMATS "Enable support for the data formats library" ON)
 message(ENABLE_DATA_FORMATS="${ENABLE_DATA_FORMATS}")
 
 option(ENABLE_FUNCTIONAL_MODELER "Enable building of functional modeler" ON)
 message(ENABLE_FUNCTIONAL_MODELER="${ENABLE_FUNCTIONAL_MODELER}")
 
+option(ENABLE_KERNGEN "Enable kerngen (dependencies only)" ON)
+message(ENABLE_KERNGEN="${ENABLE_KERNGEN}")
+
 option(ENABLE_PROGRAM_MAPPER "Enable building of program mapper" ON)
 message(ENABLE_PROGRAM_MAPPER="${ENABLE_PROGRAM_MAPPER}")
 
@@ -63,6 +66,9 @@ file(GLOB_RECURSE IDE_HEADERS program_mapper/*.h functional_modeler/*.h dependen
 
 # Build sub-directories
 add_subdirectory(common)
+if(ENABLE_KERNGEN)
+add_subdirectory(kerngen)
+endif()
 if(ENABLE_DATA_FORMATS)
 add_subdirectory(data_formats)
 endif()

p-isa_tools/data_formats/CMakeLists.txt

@@ -50,3 +50,8 @@ add_custom_command(
   POST_BUILD
   COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_LIST_DIR}/python ${PROJECT_BINARY_DIR}/python/
 )
+
+option(ENABLE_OPENFHE_TRACER "Build the OpenFHE tracer" ON)
+if(ENABLE_OPENFHE_TRACER)
+add_subdirectory(tracers/openfhe)
+endif()

p-isa_tools/data_formats/tracers/openfhe/CMakeLists.txt

@@ -0,0 +1,68 @@
+# Include FetchContent module
+include(FetchContent)
+
+# Add OpenFHE via FetchContent
+FetchContent_Declare(
+    OpenFHE
+    GIT_REPOSITORY https://github.com/AlexanderViand/openfhe-development.git
+    GIT_TAG 7e2eafc49b6b4c1a0000b1722a8749797ec277d9  # head of `tracing` branch (2025-08-07)
+)
+
+# Set OpenFHE build options before making it available
+set(BUILD_UNITTESTS OFF CACHE BOOL "" FORCE)
+set(BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+set(BUILD_BENCHMARKS OFF CACHE BOOL "" FORCE)
+set(ENABLE_TRACER ON CACHE BOOL "" FORCE)
+
+message(STATUS "Fetching OpenFHE, this may take a while...")
+FetchContent_MakeAvailable(OpenFHE)
+message(STATUS "Finished configuring OpenFHE")
+
+FetchContent_GetProperties(openfhe)
+
+# Create executable from tracing_example.cpp
+add_executable(tracing_example tracing_example.cpp tracer.h)
+# Set C++ standard
+target_compile_features(tracing_example PRIVATE cxx_std_17)
+# Link with OpenFHE libraries
+target_link_libraries(tracing_example PRIVATE HERACLES_DATA_FORMATS::heracles_data_formats OPENFHEcore OPENFHEpke OPENFHEbinfhe)
+
+target_include_directories(tracing_example PRIVATE
+    # Third Party Includes
+    $<BUILD_INTERFACE:${openfhe_SOURCE_DIR}/third-party/include>
+    $<BUILD_INTERFACE:${openfhe_SOURCE_DIR}/third-party/cereal/include>
+    $<BUILD_INTERFACE:${openfhe_SOURCE_DIR}/third-party/google-test/googletest>
+    $<BUILD_INTERFACE:${openfhe_SOURCE_DIR}/third-party/google-test/googletest/include>
+    # public headers that sit in the repo
+    $<BUILD_INTERFACE:${openfhe_SOURCE_DIR}/src/core/include>
+    $<BUILD_INTERFACE:${openfhe_SOURCE_DIR}/src/pke/include>
+    $<BUILD_INTERFACE:${openfhe_SOURCE_DIR}/src/binfhe/include>
+    # generated header  (configure_file → config_core.h)
+    $<BUILD_INTERFACE:${openfhe_BINARY_DIR}/src/core>)
+
+
+# Set compiler flags for optimization and debug info
+target_compile_options(tracing_example PRIVATE
+    $<$<CONFIG:Release>:-O3>
+    $<$<CONFIG:Debug>:-g -O0>
+)
+
+
+# define a custom target that runs tracing, then submits the trace to the program mapper, finally sending the pisa and mem file to the functional modeler
+add_custom_target(
+  run_tracing_example
+  # Run the actual example, which will generate the traces as end-to-end-test/tracing_example.bin and end-to-end-test/tracing_example_data.bin
+  COMMAND tracing_example
+  # Run the program mapper on the instruction trace, generating end-to-end-test/tracing_example.bin.csv
+  COMMAND env VIRTUAL_ENV=${VENV_PATH} PATH=${VENV_PATH}/bin:$ENV{PATH} PYTHONPATH=${VENV_SITE_PACKAGES}:$ENV{PYTHONPATH} $<TARGET_FILE:program_mapper> ${CMAKE_BINARY_DIR}/end-to-end-test/tracing_example.bin ${CMAKE_SOURCE_DIR}/kerngen/kerngen.py
+  COMMAND $<TARGET_FILE:functional_modeler> ${CMAKE_BINARY_DIR}/end-to-end-test/tracing_example_pisa.csv --verbose --hec_dataformats_mode --hec_dataformats_poly_program_location ${CMAKE_BINARY_DIR}/end-to-end-test/tracing_example.bin --hec_dataformats_data ${CMAKE_BINARY_DIR}/end-to-end-test/tracing_example_data.bin
+  # TODO: Next step: assemble the *.pisa.csv and the *tw.mem using the assembler from https://github.com/IntelLabs/HERACLES-HGCF
+  # TODO: Then it's a dead end :( as we don't have any tooling that can support non-toy sized workloads
+  DEPENDS tracing_example program_mapper functional_modeler create-end-to-end-test-dir
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/end-to-end-test
+)
+
+add_custom_target(create-end-to-end-test-dir
+  COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_BINARY_DIR}/end-to-end-test
+  COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/end-to-end-test
+)

p-isa_tools/data_formats/tracers/openfhe/README.md

@@ -0,0 +1,88 @@
+# OpenFHE Tracer
+
+This directory contains the HERACLES tracer implementation for OpenFHE, which enables extraction of FHE computation traces for use with the p-ISA tools.
+
+## Overview
+
+The OpenFHE tracer captures homomorphic encryption operations performed by OpenFHE and generates trace files that can be processed by the p-ISA toolchain. This enables:
+
+- Extraction of FHE instruction sequences
+- Generation of data traces for polynomial operations
+- End-to-end compilation from FHE programs to hardware accelerator instructions
+
+## Files
+
+- `tracer.h` - Main tracer implementation that hooks into OpenFHE's tracing infrastructure
+- `tracing_example.cpp` - Example program demonstrating tracer usage with basic FHE operations
+- `CMakeLists.txt` - Build configuration that fetches OpenFHE with tracing support enabled
+
+## Building
+
+From the repository root:
+
+```bash
+# Configure the project
+mkdir -p build
+cmake -B build -S p-isa_tools
+
+# Build the tracing example
+cmake --build build --target tracing_example
+```
+
+## Running the Example
+
+To run the complete end-to-end tracing pipeline:
+
+```bash
+cmake --build build --target run_tracing_example
+```
+
+This will:
+1. Execute the tracing example, generating trace files in `build/end-to-end-test/`:
+   - `tracing_example.bin` - FHE instruction trace
+   - `tracing_example_data.bin` - Data trace with polynomial values
+2. Run the program mapper on the instruction trace to generate `tracing_example.bin.csv`
+   (this internally uses the kernel generator)
+3. Run the functional modeler to process the traces (see note below)
+
+### Output Files
+
+After running, you'll find the following in `build/end-to-end-test/`:
+- `tracing_example.bin` - Binary FHE instruction trace
+- `tracing_example_data.bin` - Binary data trace
+- `tracing_example.bin.csv` - Mapped instruction sequence
+- `tracing_example_pisa.csv` - p-ISA instructions (if functional modeler succeeds)
+
+## Known Issues
+
+> **Note:** The functional modeler may fail with an error about missing `partQHatInvModq`. This is currently expected as recent versions of OpenFHE no longer use this parameter internally, but the p-isa_tools still expect it.
+
+## Usage in Your Own Code
+
+To use the tracer in your OpenFHE application:
+
+```cpp
+#include "tracer.h"
+
+// After creating your CryptoContext
+auto cc = GenCryptoContext(parameters);
+
+// Create and attach the tracer
+IF_TRACE(auto tracer = std::make_shared<HeraclesTracer<DCRTPoly>>("output_name", cc));
+IF_TRACE(cc->setTracer(tracer));
+
+// Your FHE operations will now be traced
+auto result = cc->EvalAdd(cipher1, cipher2);
+
+// Save trace files
+IF_TRACE(tracer->saveBinaryTrace());
+IF_TRACE(tracer->saveJsonTrace()); // for debugging/manual inspection
+```
+
+## Dependencies
+
+Note: these are automatically fetched/created by CMake when using `run_tracing_example`
+
+- OpenFHE
+- HERACLES_DATA_FORMATS library (built as part of p-isa_tools)
+- Python environment with kerngen for program mapping