Backend Template Passes
Forward firmware calls are already generated by backend template passes. Backward firmware should use the same mechanism.
What hls4ml Does Todayβ
hls4ml templates are optimizer passes. The base classes are in hls4ml/backends/template.py:
| Class | Attribute generated |
|---|---|
LayerConfigTemplate | config_cpp |
FunctionCallTemplate | function_cpp and include_header |
For example, Vivado dense forward code is defined in backends/vivado/passes/core_templates.py:
DenseConfigTemplate
-> struct configN : nnet::dense_config { ... }
DenseFunctionTemplate
-> nnet::dense<input_t, output_t, configN>(input, output, w, b);
Convolution templates follow the same pattern, but may generate multiple config structs such as a convolution config plus a nested/mult config.
The writer does not know the meaning of dense or convolution. It emits whatever config_cpp, function_cpp, and headers the passes attach.
What Training Should Addβ
Create parallel template classes for trainable code:
DenseBackwardConfigTemplate
DenseBackwardFunctionTemplate
Conv1DBackwardConfigTemplate
Conv1DBackwardFunctionTemplate
Conv2DBackwardConfigTemplate
Conv2DBackwardFunctionTemplate
ActivationBackwardFunctionTemplate
ReshapeBackwardFunctionTemplate
PoolingBackwardFunctionTemplate
BatchNormalizationBackwardConfigTemplate
BatchNormalizationBackwardFunctionTemplate
These should attach different attributes so they do not interfere with forward code:
backward_config_cpp
backward_function_cpp
backward_include_header
The writer can then emit forward code and backward code separately.
Required Static Headersβ
The deprecated fork already had useful kernel headers under templates/vivado/autograd and templates/vivado/losses. In the new fork, those names should be treated as source material, not as the new layout.
Use one trainable umbrella folder:
| Header group | Purpose |
|---|---|
trainable/common/*.h | Shared fixed-point helpers, trainable config helpers, and small utilities. |
trainable/losses/*.h | Loss values and initial output-gradient seeds. |
trainable/backprop/*.h | Layer-local backward kernels such as Dense, activation, convolution, pooling, and layout backpasses. |
trainable/optimizers/*.h | Raw update proposal and optimizer-state update helpers such as SGD and Adam. |
trainable/controllers/*.h | Global throttle controllers, CTRL-NONE, and optional kappa safety-budget code. |
The static headers should be generic and template-driven. Per-model constants and typedefs should come from generated config structs.
The concrete file-by-file notes for the first static header tree live under this sidebar section in Trainable Vivado Templates.
Backward Function Shapeβ
For a dense layer, the generated call should be resolved by the template pass:
nnet::dense_backpass<configN>(
grad_in,
grad_out,
data_in,
weight,
bias,
apply_update,
batch_info,
controller_state
);
The exact signature may change, but the important rule is that the pass decides the arguments using layer attributes, not by parsing existing C++.
What Not To Doβ
Do not make the Vivado writer:
- inspect layer class names to decide backpass headers;
- regex-edit
config_cpp; - infer previous layer outputs;
- infer loss endpoints;
- synthesize optimizer typedefs;
- calculate controller state layout.
Those are pass/template responsibilities.