How google/gematria works
Project type and purpose
– Gematria is an open-source framework for machine learning on machine code. It provides:
• Data ingestion and feature extraction for basic blocks of machine code
• Two ML models (GRANITE GNN and hierarchical LSTM) for predicting basic-block throughput
• Training and inference pipelines in Python and C++ (via pybind11)
• Optional integration into LLVM as an external project (the llvm-cm tool)
Key directories and architectural patterns
Top‐level build & config
• WORKSPACE, BUILD.bazel, CMakeLists.txt, Dockerfile, Bazel/CMake build scripts
• .github/workflows for CI
gematria/… - modular C++ + Python code
• basic_block – core basic-block abstraction & protos + Python wrappers
• datasets – importers, converters, TFRecord pipelines (C++ + Python)
• granite – graph builder & GRANITE model (C++ + Python)
• sequence – Ithemal LSTM model (Python only)
• model – shared model utilities (inference, training scaffolding)
• io – file‐system and TFRecord utilities (Python)
• llvm – parsers/canonicalizers/disassemblers leveraging LLVM
• tflite – custom ops for TensorFlow Lite
• proto – .proto definitions for annotations, throughput, blocks
• utils – general C++/Python helpers (flags, timer, string)
• testing – shared test harness code and lit integration
llvm_cm/… – standalone C++ tool (llvm-cm) that uses gematria libraries inside LLVM
System components & data flow
– Data Ingestion & Preprocessing (gematria/datasets + io)
• Reads binaries or IR → extracts basic-blocks → serializes to TFRecord
– Feature Extraction & Representation
• basic_block module defines canonical block representation via protos
• llvm module parses/disassembles code and normalizes instructions
– Model Training (Python driver in model/python + C++ heavy lifting)
• GRANITE: graph‐builder (C++), GNN training in TensorFlow 2.x
• Sequence model: hierarchical LSTM implemented in Python/TensorFlow
– Model Artifacts
• Saved TensorFlow checkpoints,/or exported TFLite models (tflite module)
– Inference APIs
• Python inference wrapper (pybind11) calling into C++ graph builder + TF runtime
• C++ inference API (gematria/granite-inference-api.md)
– Optional integration into LLVM as an external project tool (llvm-cm)
Architectural patterns & design principles
– Layered modular design: separate data, representation, model, utils, and CLI/tools
– Cross‐language bindings: pybind11 exposes performance‐critical C++ to Python drivers
– Protocol buffers for stable on‐disk interchange between stages
– Build‐system abstraction: Bazel for full monorepo, CMake for LLVM subproject
Putting it all together
[Binary/IR sources] → (llvm parser, basic_block) → [Proto TFRecords] → (training driver) → [TF Checkpoints/TFLite] → (inference API) → [Predictions]
Underneath, annotate build/integration layers: Bazel and pybind11 connecting C++ ↔ Python, and optional LLVM external project path (llvm-cm).