DRAFT: Upgrade the Snitch Cluster version and add Verilator Model

.github/workflows/_select-env.yml

@@ -34,7 +34,11 @@ jobs:
           elif [[ "${{ github.ref_name }}" == "main" ]]; then
             IMAGE="ghcr.io/pulp-platform/deeploy:main"
           else
-            IMAGE="ghcr.io/pulp-platform/deeploy:devel"
+            # REVERT BEFORE MERGE: this branch bumps snitch_cluster and adds
+            # Verilator, so it cannot build against the published devel image.
+            # Restore ghcr.io/pulp-platform/deeploy:devel once the image has
+            # been rebuilt from this branch.
+            IMAGE="ghcr.io/gamzeisl/deeploy:snitch-upgrade"
           fi
           echo "image=${IMAGE}" >> "$GITHUB_OUTPUT"
 

CHANGELOG.md

@@ -22,6 +22,7 @@ This file contains the changelog for the Deeploy project. The changelog is divid
 - Add support for Operators for Generic target needed in MAGIA [#193]( https://github.com/pulp-platform/Deeploy/pull/193)
 - Fix GAP9 L3 Board Tests: readfs Flash Ordering and Duplicate Input Data [#196](https://github.com/pulp-platform/Deeploy/pull/196)
 - Add SoCDAML Part III: hands-on lab for adding a new int8 operator [#194](https://github.com/pulp-platform/Deeploy/pull/194)
+- Upgrade the Snitch Cluster [#TODO](https://github.com/pulp-platform/Deeploy/pull/TODO)
 
 ### Added
 - tests for Regular and DW Conv2D with 3x3 kernel
@@ -37,6 +38,7 @@ This file contains the changelog for the Deeploy project. The changelog is divid
 - GAP9 Container Support with ARM64 architecture support
 - `zsh` and `oh-my-zsh` plugin installation in containers
 - Shell Format pre-commit hook
+- Verilator simulation for Snitch. `make snitch_verilator` builds the cluster model and `add_snitch_cluster_verilator_simulation` registers the CMake target. The Deeploy container carries Verilator v5.034, the version `snitch_cluster` pins in its own container.
 - Add integer MaxPool1D for Generic platform and RQSConv1D support for PULPOpen, with corresponding kernel tests.
 - Added GAP9 Platform Support: Deployer, Bindings, Templates, Tiler, DMA (L3Dma/MchanDma), target library, CI workflows
 - Per-layer microbenchmarking on PULPOpen via `--profileMicrobenchmark`: new `PULPMicrobenchmark` code-transformation pass + `perf_utils.h` helpers report cycles, instructions, stalls and cache misses per layer in `RunNetwork`
@@ -62,8 +64,24 @@ This file contains the changelog for the Deeploy project. The changelog is divid
 - Aligned CLI commands across the project
 - Added @runwangdl as a code owner
 - Skip emitting duplicate `testInputVector` data for inputs placed in L3 (loaded at runtime from the readfs hex instead), reducing test binary size
+- Bump the pinned `snitch_cluster` from `e02cc9e` (April 2024) to `5b2fccd` (September 2025). Deliberately not the latest upstream commit: `7c2bdd9` replaces the hardware-barrier CSR with a symbolic name that the pinned LLVM cannot assemble, and `de5251b` raises the Python floor to 3.12, while Deeploy targets 3.10.
+- Adapt the Snitch build system to the current `snitch_cluster` layout (`sw/snRuntime` to `sw/runtime`, `target/snitch_cluster` to `target/sim`, and the removal of `sw/math` and `sw/runtime/{common,rtl,banshee}`). The runtime is now built with the namespaced `sn-runtime` target and `SN_LLVM_BINROOT`.
+- Compile the Snitch target library, platform sources and generated `Network.c` as C++. `sw/runtime/src/sync.h` gives `snrt_inter_cluster_sw_barrier` a default argument, which is not valid C and is reached by every translation unit including `snrt.h`.
+- Update the Snitch runtime API calls: `snrt_l1alloc`/`snrt_l3alloc` become `snrt_l1_alloc`/`snrt_l3_alloc`, and performance counters are selected by index with configuration separated from starting.
+- Only register the banshee simulation target and `BANSHEE_CONFIG` when `BANSHEE_INSTALL_DIR` is set. Recent `snitch_cluster` runtimes no longer support banshee, and previously the Snitch platform could not be configured without it.
+- Enable `Xdiv_sqrt` in the cluster configuration Deeploy builds against, since its FP32 kernels emit `fdiv` and `fsqrt`.
+- Run the Snitch tests on Verilator rather than GVSoC. GVSoC's model of the cluster peripherals predates the bumped hardware: the peripheral region moved from `0x10020000` to `0x10021000`, four `SCRATCH` registers were added ahead of the CLINT and shift every subsequent register by `0x20`, and the registers are now 64-bit where the model still generates 32-bit ones.
 
 ### Fixed
+- Declare the Snitch kernels used from generated code. `SnitchAdd` and `snitch_nn_add_i8_i8_i8` had no declaration in any header, and `kernel/iSoftmax.h` declared `StnichSoftmax_i8_u8` for a kernel named `SnitchSoftmax_i8_u8` in a header that was never included. All three relied on implicit declarations, which C++ does not have.
+- Give the Generic target library headers C linkage, so that calls into it from the C++-compiled Snitch platform resolve against the C definitions.
+- Do not emit `sizeof(void)` for Snitch transient buffers, whose size is already expressed in bytes. It relies on a GNU C extension and is invalid in C++.
+- Use `memcpy` rather than the iDMA for the L3 input copies in the Snitch test harness. Both sides of that transfer are in L3, and the iDMA has a single AXI master port, so it requires one side to be TCDM.
+- Insert `snrt_fpu_fence()` before the cluster barriers emitted for Snitch. Floating-point results were not ordered with respect to the barrier, so the DM core could read a tile out of L1 before the values had landed.
+- Fix a pointer type mismatch in `snitch_nn_add_i8_i8_i8`, where scratch variables declared `int` had their addresses assigned to `int8_t` pointers.
+- Wait for all outstanding Snitch DMA transfers before the cluster barrier instead of waiting on an individual transaction ID. `completed_id` advances when the iDMA ND midend observes `burst_rsp.last`, which is upstream of the write datapath, so the compute cores could be released onto a tile the DMA had not finished writing.
+- Constrain the Snitch GEMM tile sizes in both parallelised dimensions. The kernels stream the output width in groups of 8 through the SSRs with no remainder path, so a tile of `O` below 8 makes `O / unroll` zero and, since the SSR bound is written as `bound - 1`, wraps it to `0xFFFFFFFF`: the streamer never goes idle and the next SSR configuration write never retires. The `M` constraint was only a `PerformanceHint` and so was dropped under memory pressure, which is not merely slower but wrong, since `M / compute_num` truncates and the rows in the remainder are never computed.
+- Preserve a scalar second operand for the Snitch `Add` and `Mul` layers. The Generic layers rewrite the shorter operand's shape to the longer one in `computeShapes`, which expresses broadcasting notionally but materialises no data, so the `is_scalar` flag the parser derives from the shape comes out false, the buffer is allocated for the full tensor, and the kernel reads elements that were never written.
 - Fix Neureka's output-channels subtile size (in ConvTemplate) and Dense/DW/PW tile constraints
 - in `NetworkContainer._createIOBindings`, set `_live = True` on network input and output buffers so that any buffer aliasing a network I/O tensor is no longer deallocated while the I/O tensor is still in use.
 - Fix latent bug in `VariableBuffer.has_live_aliases` where `visited` variable was storing buffer names as a set of characters instead of strings.

CMakeLists.txt

@@ -267,7 +267,7 @@ if(platform STREQUAL Snitch)
 
   include(${CMAKE_CURRENT_LIST_DIR}/cmake/snitch/snitch_cluster/snitch_cluster.cmake)
 
-  project(deeploy LANGUAGES C ASM)
+  project(deeploy LANGUAGES C CXX ASM)
 
   message(STATUS "============================= ${platform} Configuration ============================")
   message(STATUS "[cMake  ]   Number of total cores  = " ${NUM_CORES})

Container/Dockerfile.deeploy

@@ -2,8 +2,13 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-########## Stage 1: Large image to build toolchains and emulator ##########
 ARG BASE_IMAGE=ghcr.io/pulp-platform/deeploy-toolchain
+ARG VERILATOR_VERSION=v5.034
+
+########## Stage 0: Verilator for RTL simulation ##########
+FROM verilator/verilator:${VERILATOR_VERSION} AS verilator
+
+########## Stage 1: Large image to build toolchains and emulator ##########
 FROM ${BASE_IMAGE} AS toolchain
 
 # Intermediate Stage
@@ -16,6 +21,8 @@ ENV DEBIAN_FRONTEND=noninteractive
 ENV TZ=Etc/UTC
 ENV LANG=C.UTF-8
 ENV LC_ALL=C.UTF-8
+COPY --from=verilator /usr/local/bin/verilator /usr/local/bin/verilator_bin /usr/local/bin/
+COPY --from=verilator /usr/local/share/verilator /usr/local/share/verilator
 ENV PATH="/app/install/bender:${PATH}"
 ENV DEEPLOY_INSTALL_DIR=/app/install
 ENV LLVM_INSTALL_DIR=/app/install/llvm
@@ -62,6 +69,12 @@ RUN --mount=type=cache,target=/ccache \
     make snitch_runtime && \
     ccache -s
 
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends device-tree-compiler && \
+    rm -rf /var/lib/apt/lists/* && \
+    make snitch_verilator && \
+    rm -rf /app/install/snitch_cluster/target/sim/build/work-vlt
+
 # Remove toolchain to make the container lighter
 WORKDIR /app
 RUN rm -rf /app/build
@@ -107,6 +120,7 @@ RUN apt-get update && \
     python3.10-venv \
     python3.10-distutils \
     gcc \
+    g++ \
     zsh && \
     curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py && \
     python get-pip.py && \

Deeploy/Targets/Snitch/CodeTransformationPasses/SnitchClusterSynch.py

@@ -8,6 +8,7 @@
     NodeTemplate, _NoVerbosity
 
 _synchTemplate = NodeTemplate("""
+        snrt_fpu_fence();
         snrt_cluster_hw_barrier();
 """)
 

Deeploy/Targets/Snitch/DMA/SnitchDma.py

@@ -5,7 +5,7 @@
 from typing import Dict, Tuple
 
 from Deeploy.DeeployTypes import NetworkContext, NodeTemplate, OperatorRepresentation, VariableBuffer
-from Deeploy.TilingExtension.AsyncDma import AsyncDma, DmaDirection, Future, PerTensorWaitingStrategy
+from Deeploy.TilingExtension.AsyncDma import AsyncDma, BarrierWaitingStrategy, DmaDirection, Future
 
 
 class SnitchBarrierFuture(Future):
@@ -33,13 +33,26 @@ class SnitchDma(AsyncDma):
         2:
             NodeTemplate("""
             if (snrt_is_dm_core()) {
-                ${future} = snrt_dma_start_2d(${dest}, ${src}, ${size}, ${stride_dest}, ${stride_src}, ${repeat});
-                // WIESEP: Hack as otherwise the last commited DMA transaction ID can never be resolved.
-                snrt_dma_start_2d(${dest}, ${dest}, 1, 0, 0, 0);
+                snrt_dma_start_2d(${dest}, ${src}, ${size}, ${stride_dest}, ${stride_src}, ${repeat});
             }
             """),
     }
-    _waitingStrategy = PerTensorWaitingStrategy(SnitchFuture)
+    # Wait for all outstanding transfers rather than for an individual one.
+    #
+    # snrt_dma_wait compares against completed_id, which idma advances when the
+    # ND midend sees burst_rsp.last. That is upstream of the write datapath, so
+    # it can move before the transferred data is visible, and the barrier that
+    # follows then releases the compute cores onto a tile the DMA has not
+    # finished writing. snrt_dma_wait_all instead polls the busy flag, which
+    # covers every pipeline stage.
+    #
+    # Two further details make per-transfer waiting unusable here: dmcpyi
+    # returns the same ID for transfers issued back to back.
+    #
+    # This also drops the self-copy that used to follow every transfer: it
+    # existed to bump completed_id past the last transaction ID, which the
+    # strictly-greater comparison in the previously pinned runtime required.
+    _waitingStrategy = BarrierWaitingStrategy(SnitchBarrierFuture, "dma_barrier")
 
     def __init__(self, transferTemplates: Dict[int, NodeTemplate] = _transferTemplates) -> None:
         super().__init__(transferTemplates)

Deeploy/Targets/Snitch/Layers.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: 2026 ETH Zurich and University of Bologna
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Tuple
+
+import numpy as np
+
+from Deeploy.DeeployTypes import Shape
+from Deeploy.Targets.Generic.Layers import AddLayer, MulLayer
+
+
+class _ScalarPreservingShapeMixin:
+    """Keep a single-element second operand at its original shape.
+
+    The Generic Add and Mul layers rewrite the shorter operand's shape to the
+    longer one, which expresses broadcasting notionally but does not
+    materialise any data. For a genuine scalar that is harmful on Snitch: the
+    kernels broadcast input2[0] themselves, selected by the is_scalar flag the
+    parser derives from the operand shape. Once the shape has been rewritten
+    the flag comes out false, the buffer is allocated for the full tensor, and
+    the kernel reads elements that were never written.
+    """
+
+    def computeShapes(self, inputShapes: Shape, outputShapes: Shape, operatorRepresentation,
+                      channels_first) -> Tuple[Shape, Shape]:
+
+        if len(inputShapes) > 1 and np.prod(inputShapes[1]) == 1:
+            return (inputShapes, [inputShapes[0]])
+
+        return super().computeShapes(inputShapes, outputShapes, operatorRepresentation, channels_first)
+
+
+class SnitchAddLayer(_ScalarPreservingShapeMixin, AddLayer):
+    pass
+
+
+class SnitchMulLayer(_ScalarPreservingShapeMixin, MulLayer):
+    pass

Deeploy/Targets/Snitch/Platform.py

@@ -12,8 +12,8 @@
 from Deeploy.Targets.Generic.Bindings import BasicLayerNormBindings, BasicPad1DBindings, BasicPad2DBindings, \
     BasicRQIntegerDivBinding
 from Deeploy.Targets.Generic.Layers import AddLayer, ConcatLayer, DivLayer, GatherLayer, GEMMLayer, HardSwishLayer, \
-    LayerNormLayer, MatMulLayer, MulLayer, PadLayer, ReshapeLayer, RMSNormLayer, RQGEMMLayer, RQIntegerDivLayer, \
-    SoftmaxLayer, TransposeLayer, iNoNormLayer
+    LayerNormLayer, MatMulLayer, PadLayer, ReshapeLayer, RMSNormLayer, RQGEMMLayer, RQIntegerDivLayer, SoftmaxLayer, \
+    TransposeLayer, iNoNormLayer
 from Deeploy.Targets.Generic.Parsers import ConcatParser, GatherParser, MatMulParser, Pad1DParser, Pad2DParser, \
     ReshapeParser, RQAddParser, RQIntegerDivParser, SoftmaxParser, TransposeParser, UnsqueezeParser, iLayerNormParser, \
     iNoNormParser, iSoftmaxParser
@@ -22,6 +22,7 @@
     IntegerDivRequantMergePass, MergeConstAddAndRequantPass, MergeTrueIntegerDivRequantShiftPass, RQSSplitPass, \
     SkipEmptyConcatPass, SkipUnityRequantPass, iGELURequantMergePass, iHardswishRequantMergePass
 from Deeploy.Targets.PULPOpen.Platform import RQAddMapper
+from Deeploy.Targets.Snitch.Layers import SnitchAddLayer, SnitchMulLayer
 from Deeploy.Targets.Snitch.Parsers import SnitchAddParser, SnitchDivParser, SnitchGEMMParser, SnitchHardSwishParser, \
     SnitchMulParser, SnitchRMSNormParser, SnitchRQGEMMParser
 from Deeploy.Targets.Snitch.Templates import AllocateTemplate, FreeTemplate
@@ -69,11 +70,11 @@
     'iNoNorm': iNoNormLayer([iNoNormMapper]),
     'iLayerNorm': LayerNormLayer([iLayerNormMapper]),
     'RequantizedAdd': AddLayer([RQAddMapper]),
-    'Add': AddLayer([AddMapper]),
+    'Add': SnitchAddLayer([AddMapper]),
     'RMSNorm': RMSNormLayer([RMSNormMapper]),
     'HardSwish': HardSwishLayer([HardSwishMapper]),
     'Div': DivLayer([DivMapper]),
-    'Mul': MulLayer([MulMapper]),
+    'Mul': SnitchMulLayer([MulMapper]),
     'Reshape': ReshapeLayer([ReshapeMapper]),
     'Transpose': TransposeLayer([TransposeMapper]),
     'Concat': ConcatLayer([ConcatMapper]),

Deeploy/Targets/Snitch/Templates/AllocateTemplate.py

@@ -9,10 +9,10 @@
 snitchL1InitTemplate = NodeTemplate("${type.typeName} ${name};\n")
 
 snitchL2AllocateTemplate = NodeTemplate(
-    "${name} = (${type.typeName}) snrt_l3alloc(sizeof(${type.referencedType.typeName}) * ${size});\n")
+    "${name} = (${type.typeName}) snrt_l3_alloc(sizeof(${type.referencedType.typeName}) * ${size});\n")
 
 snitchL1AllocateTemplate = NodeTemplate(
-    "${name} = (${type.typeName}) snrt_l1alloc(sizeof(${type.referencedType.typeName}) * ${size});\n")
+    "${name} = (${type.typeName}) snrt_l1_alloc(sizeof(${type.referencedType.typeName}) * ${size});\n")
 
 snitchL2GlobalInitTemplate = NodeTemplate("static ${type.referencedType.typeName} ${name}[${size}] = {${values}};\n")
 
@@ -46,11 +46,20 @@
 """)
 
 snitchGenericGuardedAllocate = NodeTemplate("""
+<%
+# TransientBuffers are void pointers whose size is already expressed in bytes.
+# sizeof(void) is a GNU C extension that evaluates to 1; it is invalid in C++,
+# which the Snitch platform is compiled as.
+if type.referencedType.typeName == "void":
+    allocSize = f"{size}"
+else:
+    allocSize = f"sizeof({type.referencedType.typeName}) * {size}"
+%>
 % if _memoryLevel == "L1":
-if (snrt_is_dm_core()) { ${name} = (${type.typeName}) snrt_l1alloc(sizeof(${type.referencedType.typeName}) * ${size}); }
+if (snrt_is_dm_core()) { ${name} = (${type.typeName}) snrt_l1_alloc(${allocSize}); }
 snrt_cluster_hw_barrier();\n
 % else:
-if (snrt_is_dm_core()) { ${name} = (${type.typeName}) snrt_l3alloc(sizeof(${type.referencedType.typeName}) * ${size}); }
+if (snrt_is_dm_core()) { ${name} = (${type.typeName}) snrt_l3_alloc(${allocSize}); }
 snrt_cluster_hw_barrier();\n
 % endif
 """)

Deeploy/Targets/Snitch/Templates/iSoftmaxTemplate.py

@@ -16,5 +16,5 @@
 else:
     signatureString += '_u8'
 %>
-SnitchSoftmax${signatureString}(${data_in}, ${data_out}, ${lastDimBuffer}, ${size}, ${lastDimLength}, ${coeffB}, ${coeffC}, ${log2});
+SnitchSoftmax${signatureString}(${data_in}, ${data_out}, (uint32_t *) ${lastDimBuffer}, ${size}, ${lastDimLength}, ${coeffB}, ${coeffC}, ${log2});
 """)

Deeploy/Targets/Snitch/TileConstraints/GemmTileConstraint.py

@@ -9,7 +9,7 @@
 from Deeploy.DeeployTypes import NetworkContext, OperatorRepresentation
 from Deeploy.TilingExtension.MemoryConstraints import NodeMemoryConstraint
 from Deeploy.TilingExtension.TileConstraint import TileConstraint
-from Deeploy.TilingExtension.TilerModel import PerformanceHint, TilerModel
+from Deeploy.TilingExtension.TilerModel import TilerModel
 from Deeploy.TilingExtension.TilingCodegen import AbsoluteHyperRectangle, HyperRectangle, TilingSchedule, \
     VariableReplacementScheme
 
@@ -89,13 +89,20 @@ def addPolicyConstraint(tilerModel: TilerModel, parseDict: Dict, ctxt: NetworkCo
         # Full inner dimension
         tilerModel.addConstraint(AWidthDimVar == AWidthDimVar.Max())
 
-        # We parallelize over the output height dimension so try to keep it divisible by the number of cores (8)
-        if parseDict["M"] > 8:
-            tilerModel.addTileSizeDivisibleConstraint(parseDict,
-                                                      "M",
-                                                      YHeightDimVar,
-                                                      8,
-                                                      strategy = PerformanceHint(priority = 1))
+        # We parallelize over the output height dimension by handing each of the 8
+        # compute cores M / 8 rows, so a tile of M that is not a multiple of 8 is
+        # invalid.
+        if parseDict["M"] >= 8:
+            tilerModel.addTileSizeDivisibleConstraint(parseDict, "M", YHeightDimVar, 8)
+
+        # The kernels stream the output width in groups of `unroll` (8) through the
+        # SSRs and have no remainder path, so they require a tile of O that is a
+        # multiple of 8. A smaller tile makes `O / unroll` zero, and since the SSR
+        # bound is written as `bound - 1` it wraps to 0xFFFFFFFF: the streamer is
+        # told to produce ~4 billion elements while the consuming loop runs zero
+        # times, so it never goes idle and the next SSR config write never retires.
+        if parseDict["O"] >= 8:
+            tilerModel.addTileSizeDivisibleConstraint(parseDict, "O", YWidthDimVar, 8)
 
         return tilerModel
 

DeeployTest/CMakeLists.txt

@@ -6,6 +6,9 @@ include_directories(${GENERATED_SOURCE})
 
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
+if(DEEPLOY_ARCH STREQUAL SNITCH)
+  set_source_files_properties(${GENERATED_SOURCE}/Network.c PROPERTIES LANGUAGE CXX)
+endif()
 add_library(network OBJECT ${GENERATED_SOURCE}/Network.c)
 target_link_libraries(network PUBLIC deeploylib)