Welcome to Pydrofoil’s documentation!

Pydrofoil is an experimental emulator-generator for ISA models written in Sail. It can generate emulators for RISC-V, ARM, CHERIoT based on their respective Sail models. The Pydrofoil-generated emulators achieve fast performance by doing dynamic binary translation (aka just-in-time compilation) from guest instructions into host machine instructions. It’s built on top of the RPython meta-jit compiler and reuses all its optimizations, backends, etc. Performance is typically an order of magnitude better than the emulators generated by Sail.

To get started with the RISC-V emulator, please consult Building Pydrofoil from source.

To read a more thorough description of how the project works, please refer to our preprint. To cite this work, please use the following BibTex snippet:

@article{Bolz-Tereick2025-au,
  title         = "Pydrofoil: accelerating Sail-based instruction set
                   simulators",
  author        = "Bolz-Tereick, CF and Panayi, Luke and McKeogh,
                   Ferdia and Spink, Tom and Berger, Martin",
  abstract      = "We present Pydrofoil, a multi-stage compiler that generates
                   instruction set simulators (ISSs) from processor instruction
                   set architectures (ISAs) expressed in the high-level,
                   verification-oriented ISA specification language Sail.
                   Pydrofoil shows a > 230x speedup over the C-based ISS
                   generated by Sail on our benchmarks, and is based on the
                   following insights. (i) An ISS is effectively an interpreter
                   loop, and tracing just-in-time (JIT) compilers have proven
                   effective at accelerating those, albeit mostly for
                   dynamically typed languages. (ii) ISS workloads are highly
                   atypical, dominated by intensive bit manipulation
                   operations. Conventional compiler optimisations for
                   general-purpose programming languages have limited impact
                   for speeding up such workloads. We develop suitable
                   domain-specific optimisations. (iii) Neither tracing JIT
                   compilers, nor ahead-of-time (AOT) compilation alone, even
                   with domain-specific optimisations, suffice for the
                   generation of performant ISSs. Pydrofoil therefore
                   implements a hybrid approach, pairing an AOT compiler with a
                   tracing JIT built on the meta-tracing PyPy framework. AOT
                   and JIT use domain-specific optimisations. Our benchmarks
                   demonstrate that combining AOT and JIT compilers provides
                   significantly greater performance gains than using either
                   compiler alone.",
  month         =  mar,
  year          =  2025,
  archivePrefix = "arXiv",
  primaryClass  = "cs.PL",
  eprint        = "2503.04389"
}