International Association for Cryptologic Research

International Association
for Cryptologic Research

Transactions on Cryptographic Hardware and Embedded Systems 2026

Pipelining FALCON’s Gaussian sampler:

Towards practical FALCON acceleration


README

CHES 2026: Pipelining FALCON's SamplerZ: Artifacts

This repository contains the artifacts for the included CHES 2026 paper.

Included are the HDL sources, IP definitions, project creation, implementation and deployment scripts, and some additional data and measurements.

Quick setup TLDR

Repository layout

Requirements

Note: There is a Vagrant+Virtualbox script available, which automates most of the installation and project creation in an isolated environment, see the VM section.

General dependencies:

For project creation, synthesis and simulation:

To regenerate DT overlay for the AXI-Lite peripheral on Linux:

Repository setup:

just clone-xilinx-devicetree # only needed for DT overlay generation

Vivado (and Vitis if needed) should be in PATH, e.g.:

source ${INSTALL_DIR}/2025.1/Vivado/settings64.sh
# -- OR --
source ${INSTALL_DIR}/2025.1/Vitis/settings64.sh

Just

Just can be obtained from github or installed with the convenience script:

curl https://just.systems/install.sh | bash -s -- --to ~/.local/bin
export PATH="$PATH:$HOME/.local/bin"

You can run just without arguments to list available commands and command groups, including descriptions. Inspect the justfile to see what is run, or use just -n to simulate a recipe without running anything.

You can chain multiple recipes in a single invocation:

just clean kria-project kria-implementation gui

Reproduce the ZCU104 out-of-context synthesis and simulation

This project is used to compare to prior works using this platform. Synthesis, implementation and simulation is possible, deployment is not (a Block Design for the platform would have to be created).

From the repository root:

# There is a helper to automate most of this:
just zcu # runs: clean, zcu-project, zcu-implementation, gui

just clean # Deletes ./vivado folder and others
# optionally: tweak options in ./scripts/{common,zcu-project}.tcl

just zcu-project # Creates the project in ./vivado
just gui # Opens the vivado GUI for the created project

# either synthetize and implement in the GUI, or:
just zcu-implementation # runs syn+impl
# or in the *Vivado TCL console*:
source ./zcu-implementation.tcl # or any other tcl script from ./scripts
# inspect netlist, report usage, timings, etc.

# either simulate in the GUI, or run any of:
just sim-samplerz # simulate samplerz_tb
just sim-samplerz-axi # simulate samplerz_axi_tb
# The simulations have tweakable constants inline, take a look.
# After running, inspect simulation outputs, and perhaps waveform.
# Alternatively:
# - simply `Set as Top` the desired module under `Simulation sources`
# - `Run Simulation`
# - `Run All` (F3)
# - select appropriate .wcfg tab for this module
# This has the benefit of automatically opening the simulation waveform
# in a scope, instead of only writing it to a .wdb file.

Vivado reports for an out-of-context run at 222 MHz on the ZCU104 are provided in out/reports/zcu104-samplerz/, including an extracted summary of the most important run results. You may re-generate these reports from a completed implementation run by running:

just zcu-report

Available tops for implementation:

Available tops for simulation:

Reproduce the KV260 hardware build

This project contains a Vivado Block Design for the full KV260 platform, to which the samplerz is connected as an AXI4-Lite peripheral, usable from Linux userspace via /dev/mem.

From the repository root:

# There is a helper to automate most of this:
just kria # runs: clean, kria-project, kria-implementation, gui

just clean
# optionally tweak settings in ./scripts/{common,kria-project}.tcl

just kria-project # creates project
just gui # opens project

# either run synthesis, implementation and bitstream generation manually, or:
just kria-implementation # runs syn+impl+bitstream on the design_1_wrapper top and exports results to ./out
# or in the *Vivado TCL console*:
source ./kria-implementation.tcl # or any other tcl script from ./scripts

The results are copied to ./out:

If you modify the memory map of the block design, you must re-generate the DT overlay using Vitis (XSCT):

just clone-xilinx-devicetree
just devicetree-vitis

This will recreate both out/samplerz.dtsi and out/samplerz.dtbo from the out/samplerz.xsa file. It is also possible to manually adjust the .dtsi and only recreate the .dtbo with dtc.

In this project, implementation for other tops and simulations can also be run, although this is not the primary use for this project.

Deploy on a KV260 Linux target

To get running with the KV260 platform, a Linux system must be imaged onto its SD card, which has the appropriate drivers and user-space tools for the FPGA PL device. We recommend Canonical's 'Ubuntu on AMD' images for this purpose: https://ubuntu.com/download/amd#kria-k26. Specifically, we used, Ubuntu Desktop 22.04 LTS, but Ubuntu Server 24.04 LTS could likely also be used.

After imaging, mount the root filesystem and ensure the following:

Then, boot the device, connect to it either over SSH or over the USB serial console and login, then:

just load # (re-)loads the samplerz.bit.bin to the FPGA PL and samplerz.dtbo into the kernel

just build # builds the userspace testing program

# if not running as root:
just perms # makes /dev/mem rw for the current user
just caps # gives the built binary cap_sys_rawio
# these are necessary to work with /dev/mem as a non-root user.

just run # run the samplerz tests

If the tests succeed, you may further exercise the module using the Falcon reference C implementation in sw/falcon_c, modified to use the accelerator via /dev/mem. By default, it uses the software sampler. Select the floating-point backend and enable FALCON_HW_SAMPLERZ in sw/falcon_c/config.h to use the accelerator. After changing the configuration, rebuild and run the tests and benchmark:

cd falcon_c
make clean
make
./test_falcon
./speed 0.01

Hardware execution requires root or cap_sys_rawio and access to /dev/mem, same as the samplerz tests.

Register regeneration

Only needed when changing the register map. From src/registers/, install the dependencies from requirements.txt and generate RTL, SV constants, HTML, C headers, then Python bindings:

just env
just gen # runs gen-sv gen-sv-const gen-html gen-c gen-py in order

Vivado VM

The vm/ directory supplies a recipe for an Ubuntu 24.04 desktop VM with Vivado 2025.1 on a persistent virtual disk. It requires Vagrant, VirtualBox, rsync, AMD credentials, approximately 24 GB RAM, and 110 GB of host disk.

This is the recommended way to reproduce this work, unless you already have Vivado 2025.1 installed.

Requirements:

Create ./vm/.env based on ./vm/.env.sample:

The AMD/Xilinx credentials are used inside the VM during provisioning to download the Vivado installer, and during the installation itself.

VM disks are placed in the ./vm/ directory:

Once the vm-vivado.vdi disk is created by a successful Vivado installation, it is not removed by vagrant destroy, and Vivado installation is not run again if it already exists. This allows for re-building the VM if needed, without re-downloading and re-installing Vivado each time.

To start the VM (and Vivado installation if not completed previously):

cd vm
vagrant up
# Other useful commands:
vagrant destroy -f
vagrant up --provision

The installation process is visible on the command-line. Do not interact with the VM until a logged-in desktop appears: in particular do not try to login before autologin is executed. The screen may turn black briefly while the gdm session is restarted, and this is fine.

If installing Vivado, the download link for the installer will be opened in Firefox inside the VM (but you will immediately be redirected to the AMD login form). The login form should be autofilled with the credentials you provided. Log in, confirm the US export regulation form, and start the download. Once the download is successful, the browser will automatically close and installation will start in the vagrant command line. Should there be any problems with this process, you may manually place the AMD Unified Installer for FPGAs & Adaptive SoCs 2025.1: Linux Self Extracting Web Installer .bin file inside /home/vagrant/Downloads/vivado_installer.

The installation is completed once the vagrant up command exits and can be verified by running e.g. which vivado inside a GUI terminal in the VM or inside a shell started by vagrant ssh.

The whole repository (except subfolders unnecessary for build) is copied into the VM automatically as /home/vagrant/Desktop/samplerz. If you wish to update the copy, you may run vagrant rsync at any time.

You may now manually proceed with setting up the project and running it inside the VM. The just tool is already installed.

Alternatively, you may run either of

vagrant provision --provision-with project-zcu
vagrant provision --provision-with project-kria

to start the project creation process from the host and open the GUI automatically.

LICENSE summary

Externally licensed files:

This work's original files: