Skip to main content

Backend Template Passes

Status:PreliminaryIn progress
Tags:Hls4mlImplementationTraining
Last modified:

Role

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:

ClassAttribute generated
LayerConfigTemplateconfig_cpp
FunctionCallTemplatefunction_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 groupPurpose
trainable/common/*.hShared fixed-point helpers, trainable config helpers, and small utilities.
trainable/losses/*.hLoss values and initial output-gradient seeds.
trainable/backprop/*.hLayer-local backward kernels such as Dense, activation, convolution, pooling, and layout backpasses.
trainable/optimizers/*.hRaw update proposal and optimizer-state update helpers such as SGD and Adam.
trainable/controllers/*.hGlobal 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.