Set Clock Frequency

This guide explains how to configure the kernel clock frequency at build time and adjust it at runtime using the VRT Device API.

Prerequisites

  • The SLASH stack is installed.

  • A V80 board is visible (v80-smi list) and vrtd is running.

  • Familiarity with building a SLASH application. See Your First Kernel.

Where Clock Frequency Is Set

Clock frequency can be specified at three levels. Each level overrides the previous one at its respective stage.

Build-Time: HLS Configuration

The HLS .cfg file sets the synthesis target clock period:

clock=2ns

A period of 2ns targets 500 MHz; 4ns targets 250 MHz. This value drives the timing constraints during HLS compilation.

Build-Time: Linker Configuration

The config.cfg [clock] section sets the frequency recorded in the vrtbin’s system_map.xml:

[clock]
krnl=vadd_0
freqhz=400000000

This value (in Hz) is what the design reports as its clock frequency when inspected with v80-smi inspect.

Runtime: VRT Device API

After opening a device, you can read and change the frequency from your host application:

std::cout << "Current frequency: " << device.getFrequency() << " Hz\n";
std::cout << "Max frequency:     " << device.getMaxFrequency() << " Hz\n";

device.setFrequency(300000000);  // 300 MHz

std::cout << "New frequency:     " << device.getFrequency() << " Hz\n";

Build and Run the Example

Ensure you have sourced Vivado and Vitis HLS before building:

source <path-to-vivado>/settings64.sh
source <path-to-vitis-hls>/settings64.sh

Example 04_freq demonstrates all three levels:

cd examples/04_freq
cmake -B build -S . -G Ninja -DSLASH_USE_REPO=ON
cmake --build build
cmake --build build --target hls
cmake --build build --target freq_hw    # or freq_emu / freq_sim

Run:

./04_freq <BDF> freq_hw.vbin

Replace <BDF> with your board’s address from v80-smi list.

Frequency Guidelines

  • Frequencies are always specified in Hz (e.g. 300000000 for 300 MHz).

  • Do not exceed the value returned by getMaxFrequency().

  • Lower frequencies can improve timing closure for complex designs.

  • Higher frequencies increase throughput but may cause timing violations.

  • The user’s vrtd role must include the clock permission. See Configuration.

Asking for more than the design can reach

--clock-hz is the frequency the reconfigurable module is implemented against, not an upper bound to aim at. After routing, the linker measures the worst negative slack and records the frequency actually achieved in the vbin, so the runtime never clocks user logic faster than it was timed for.

Setting a target the design cannot reach is therefore counterproductive. An over-constrained implementation routes worse than an achievable one, and the recorded frequency is derated from that worse result. Measured on 00_axilite:

Shell

--clock-hz 200000000

--clock-hz 250000000

service

184 MHz delivered

146 MHz delivered

compute

200 MHz delivered (timing met)

161 MHz delivered

Asking for 250 MHz produced a slower device than asking for 200 MHz on both shells. When the target is missed the linker prints a warning naming the requested and recorded frequencies; treat it as a prompt to re-link at a lower target rather than as advisory noise. Raise --clock-hz incrementally and keep the highest value that still meets timing.

Next Steps