Skip to main content

Vivado Writer

Status:PreliminaryIn progress
Tags:Hls4mlImplementationTraining
Last modified:

Role

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:

MethodOutput
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:

  1. top-level function signature from model inputs and outputs;
  2. HLS IO pragmas;
  3. weight loading code;
  4. local intermediate tensor declarations;
  5. each layer's function_cpp;
  6. trace calls when enabled.

The parameters writer emits:

  1. include headers collected from layers;
  2. weight includes;
  3. 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.

Keep writer changes narrow and generic:

Insertion pointWriter responsibility
Header signatureIf model.config.is_trainable(), append resolved trainable top-level ports from model metadata.
IO pragmasApply pragmas to resolved trainable ports.
IncludesInclude model-level and layer-level trainable headers already attached by passes.
DefinesEmit model-level trainable typedefs and constants already generated by passes.
ParametersEmit 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 assetsCopy 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:

AttributeMeaning
trainable_header_argsExtra top-level function arguments.
trainable_io_variablesExtra variables needing IO pragmas.
trainable_include_headerModel-level include headers.
trainable_defines_cppBatch/controller/global typedefs and constants.
loss_config_cppLoss config structs.
loss_function_cppLoss calls and output-gradient seeds.
controller_config_cppController state/config structs.
controller_function_cppController update computation.
update_function_cppFinal global update application if separate from backpass.

This lets the writer remain a formatter.

Testbench Impact​

Trainable signatures also affect:

  • myproject_test.cpp
  • myproject_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.dat and tb_output_predictions.dat
  • a per-epoch shuffled order controlled by Model.Training.Shuffle and ShuffleSeed
  • 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.