Vivado Writer
The Vivado writer copies template files into a project and fills insertion points. For trainable ENABOL, it should gain small generic insertion points, not training-specific inference logic.
What hls4ml Does Todayβ
hls4ml/writer/vivado_writer.py writes:
| Method | Output |
|---|---|
write_project_dir() | Project folder skeleton. |
write_project_cpp() | Main architecture source file. |
write_project_header() | Main function header. |
write_weights() | Weight headers and text files. |
write_defines() | Type definitions and layer numbers. |
write_parameters() | Includes, weights, and layer config structs. |
write_test_bench() | C++ testbench. |
write_bridge() | Python/C bridge. |
write_build_script() | Build scripts. |
write_nnet_utils() | Static utility headers. |
write_generated_code() | Generated helper code. |
write_yml() | Serialized hls4ml config. |
The main source writer emits:
- top-level function signature from model inputs and outputs;
- HLS IO pragmas;
- weight loading code;
- local intermediate tensor declarations;
- each layer's
function_cpp; - trace calls when enabled.
The parameters writer emits:
- include headers collected from layers;
- weight includes;
- each layer's
config_cpp.
Old Trainable Writer Behaviorβ
The deprecated trainable writer added the right generated artifacts, but in the wrong layer of abstraction:
- top-level ground-truth, loss, train, apply-update, batch-size, and learning-rate arguments;
- IO pragmas for ground-truth buffers;
- trainable headers;
- batch-size and learning-rate constants;
- loss typedefs and loss config structs;
- backward gradient buffers;
- reverse layer traversal;
- layer-specific backpass calls;
- optimizer hyperparameter header generation;
- trace/log helper hooks.
This made the writer depend on layer semantics and config internals.
Recommended Writer Changesβ
Keep writer changes narrow and generic:
| Insertion point | Writer responsibility |
|---|---|
| Header signature | If model.config.is_trainable(), append resolved trainable top-level ports from model metadata. |
| IO pragmas | Apply pragmas to resolved trainable ports. |
| Includes | Include model-level and layer-level trainable headers already attached by passes. |
| Defines | Emit model-level trainable typedefs and constants already generated by passes. |
| Parameters | Emit loss_config_cpp, controller_config_cpp, and backward_config_cpp strings. |
| Project C++ | Emit loss seed code, forward code, backward code, and controller/update code in resolved order. |
| Static assets | Copy trainable/common, trainable/losses, trainable/backprop, trainable/optimizers, and trainable/controllers headers. |
The writer can still ask one high-level question:
if model.config.is_trainable():
...
It should not ask what kind of loss or layer it is emitting.
Suggested Model-Level Generated Attributesβ
Passes can attach these to the model or config object:
| Attribute | Meaning |
|---|---|
trainable_header_args | Extra top-level function arguments. |
trainable_io_variables | Extra variables needing IO pragmas. |
trainable_include_header | Model-level include headers. |
trainable_defines_cpp | Batch/controller/global typedefs and constants. |
loss_config_cpp | Loss config structs. |
loss_function_cpp | Loss calls and output-gradient seeds. |
controller_config_cpp | Controller state/config structs. |
controller_function_cpp | Controller update computation. |
update_function_cpp | Final global update application if separate from backpass. |
This lets the writer remain a formatter.
Testbench Impactβ
Trainable signatures also affect:
myproject_test.cppmyproject_bridge.cpp- Python bridge/predict path
The first implementation keeps predict() inference-only by calling the top function with train=false and dummy loss/ground-truth buffers.
For C simulation, trainable projects now get a generated trainable testbench through the same write_test_bench() entry point. The normal inference testbench remains unchanged for non-trainable models. When Model.Training.Trainable is true, the writer emits:
- all samples loaded from
tb_input_features.datandtb_output_predictions.dat - a per-epoch shuffled order controlled by
Model.Training.ShuffleandShuffleSeed - an epoch loop controlled by
Model.Training.Epochs - batch reset/end flags derived from rounded
Model.Training.BatchSize - prediction output to the ordinary CSIM result log
- compact console progress logs such as
Epoch [1/2] - sample 1/128: loss 2.02597, alpha: 1 - metadata-bearing trainable traces under
tb_data/training/
The first trainable trace files are:
| File | Cadence | Columns |
|---|---|
| tb_data/training/loss.dat | every logged training sample | epoch,sample,global_step,sample_index,loss |
| tb_data/training/alpha.dat | every logged training sample | epoch,sample,global_step,sample_index,alpha |
| tb_data/training/controller.dat | every batch end | epoch,sample,global_step,sample_index,raw_update_norm_sq,controlled_update_norm_sq,actual_update_norm_sq,dgrad_norm_sq,dtheta_for_control_sq,stability_lhs_raw,stability_lhs_ctrl,stability_rhs,alpha_feasible,alpha_state,alpha_code,alpha_min,controller_feasible |
| tb_data/training/<layer>/weights.dat | once per epoch | epoch,sample,global_step,sample_index,weight_<input>_<output>,... |
| tb_data/training/<layer>/biases.dat | once per epoch | epoch,sample,global_step,sample_index,bias_<output>,... |
Each trace file repeats the index columns because future traces will not all have the same cadence. For example, loss may be logged every sample while weights are logged once per epoch.
controller.dat is the global-throttle diagnostic file. The writer exposes the controller metrics as explicit top-level output arrays so the generated testbench can log the same values that were produced by the firmware call. The controller uses raw optimizer update geometry for the law: raw_update_norm_sq and dtheta_for_control_sq are ||Delta theta_raw||^2, where SGD already included the learning rate in Delta theta_raw = -eta G. controlled_update_norm_sq is the alpha-scaled proposed movement, and actual_update_norm_sq is measured after the fixed-point assignment back into stored parameters. controller_feasible is 0 when no candidate satisfied the inequality and the nonzero alpha_min fallback was used.
Per-layer parameter traces keep layers separate so readers can load or plot only one layer. Dense weights use hls4ml's row-major dense convention: weight_<input>_<output> maps to flat index input * n_out + output.
The trace metadata comments are generated by the emitted C++ testbench. Static fields are injected by the Python writer; runtime fields such as user, host, and date are read when CSIM runs.
Longer term, expose a separate train_step() interface from generated bridges.