feat(task2): add dsp_fixture native test — float* + struct-out-param patterns

Copilot · web-flow · commit e3ddc2c37971 · 2026-06-20T04:45:57.000Z
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
@@ -16,8 +16,13 @@ include(cmake/ferrum_helpers.cmake)
 # without any external consumer source.  A real consumer would instead call
 #   ferrum_add_static_library(my_lib SOURCES ...) from their own CMakeLists.
 # ---------------------------------------------------------------------------
-option(FERRUM_BUILD_TEST_STUB "Build the in-tree add() test stub" ON)
+option(FERRUM_BUILD_TEST_STUB    "Build the in-tree add() test stub"    ON)
+option(FERRUM_BUILD_DSP_FIXTURE  "Build the in-tree DSP test fixture"   ON)
 
 if(FERRUM_BUILD_TEST_STUB)
     add_subdirectory(test_stub)
 endif()
+
+if(FERRUM_BUILD_DSP_FIXTURE)
+    add_subdirectory(dsp_fixture)
+endif()
diff --git a/native/dsp_fixture/CMakeLists.txt b/native/dsp_fixture/CMakeLists.txt
@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.21)
+project(ferrum_dsp_fixture LANGUAGES C)
+
+include(../cmake/ferrum_helpers.cmake)
+
+ferrum_add_static_library(ferrum_dsp_fixture
+    SOURCES src/ferrum_dsp.c
+    INCLUDES include
+)
+
+include(GNUInstallDirs)
+install(TARGETS ferrum_dsp_fixture
+        ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
+)
+install(DIRECTORY include/ DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
diff --git a/native/dsp_fixture/include/ferrum_dsp.h b/native/dsp_fixture/include/ferrum_dsp.h
@@ -0,0 +1,52 @@
+/**
+ * ferrum_dsp.h — Second test fixture for the Ferrum codegen/build pipeline.
+ *
+ * This header exercises the two real-consumer patterns that ferrum_add(int,int)
+ * cannot cover:
+ *   1. A function that takes a float* buffer with an int length.
+ *   2. A function that writes a result through a struct out-parameter.
+ *
+ * Both patterns appear constantly in audio, signal, and ML processing ABIs and
+ * must round-trip through ferrum-codegen without error.
+ *
+ * This file is NOT domain-specific application logic; it is framework test
+ * infrastructure that validates the plumbing.
+ */
+#ifndef FERRUM_DSP_H
+#define FERRUM_DSP_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Fixed-layout, blittable statistics summary.
+ * All fields are 32-bit; no padding needed on any supported ABI.
+ */
+typedef struct {
+    float   min_val; /**< Minimum value in the buffer.  */
+    float   max_val; /**< Maximum value in the buffer.  */
+    float   mean;    /**< Arithmetic mean of the buffer.*/
+    int32_t count;   /**< Number of elements processed. */
+} FerrumDspStats;
+
+/**
+ * Multiplies every element in buf[0..len-1] by factor in-place.
+ * Validates the (float* buf, int32_t len) parameter pattern.
+ */
+void ferrum_dsp_scale(float* buf, int32_t len, float factor);
+
+/**
+ * Computes min, max, mean, and count of buf[0..len-1] and writes
+ * the result through the out-parameter.
+ * Validates the const-float* input + blittable-struct-out-parameter pattern.
+ */
+void ferrum_dsp_stats(const float* buf, int32_t len, FerrumDspStats* result);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* FERRUM_DSP_H */
diff --git a/native/dsp_fixture/src/ferrum_dsp.c b/native/dsp_fixture/src/ferrum_dsp.c
@@ -0,0 +1,34 @@
+/*
+ * ferrum_dsp.c — Implementation of the Ferrum DSP test fixture.
+ * See ferrum_dsp.h for documentation.
+ */
+#include "ferrum_dsp.h"
+
+void ferrum_dsp_scale(float* buf, int32_t len, float factor)
+{
+    for (int32_t i = 0; i < len; ++i)
+        buf[i] *= factor;
+}
+
+void ferrum_dsp_stats(const float* buf, int32_t len, FerrumDspStats* result)
+{
+    if (len <= 0 || !buf || !result)
+        return;
+
+    float min_val = buf[0];
+    float max_val = buf[0];
+    float sum     = 0.0f;
+
+    for (int32_t i = 0; i < len; ++i)
+    {
+        float v = buf[i];
+        if (v < min_val) min_val = v;
+        if (v > max_val) max_val = v;
+        sum += v;
+    }
+
+    result->min_val = min_val;
+    result->max_val = max_val;
+    result->mean    = sum / (float)len;
+    result->count   = len;
+}
diff --git a/src/Framework.Tests/Codegen/DspFixtureCodegenTests.cs b/src/Framework.Tests/Codegen/DspFixtureCodegenTests.cs
@@ -0,0 +1,253 @@
+using Xunit;
+using Ferrum.Codegen.Emitter;
+using Ferrum.Codegen.Parser;
+
+namespace Ferrum.Framework.Tests.Codegen;
+
+/// <summary>
+/// Exercises ferrum-codegen against the DSP fixture header, which contains two
+/// real-consumer patterns not covered by the trivial <c>ferrum_add(int,int)</c>
+/// test stub:
+/// <list type="bullet">
+///   <item>A function taking a <c>float*</c> buffer and an <c>int32_t</c> length.</item>
+///   <item>A function with a blittable struct out-parameter.</item>
+/// </list>
+/// </summary>
+public sealed class DspFixtureCodegenTests
+{
+    // ── Inline copy of native/dsp_fixture/include/ferrum_dsp.h ───────────────
+    // Using an inline copy makes the tests self-contained and runnable without
+    // requiring the native tree to be present in the test working directory.
+    private const string DspHeader = @"
+#ifndef FERRUM_DSP_H
+#define FERRUM_DSP_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern ""C"" {
+#endif
+
+typedef struct {
+    float   min_val;
+    float   max_val;
+    float   mean;
+    int32_t count;
+} FerrumDspStats;
+
+void ferrum_dsp_scale(float* buf, int32_t len, float factor);
+void ferrum_dsp_stats(const float* buf, int32_t len, FerrumDspStats* result);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+";
+
+    private readonly HeaderParser _parser = new();
+
+    // ── Struct extraction ─────────────────────────────────────────────────────
+
+    [Fact]
+    public void Parse_DspFixture_ExtractsOneStruct()
+    {
+        var header = _parser.Parse(DspHeader);
+        Assert.Single(header.Structs);
+        Assert.Equal("FerrumDspStats", header.Structs[0].Name);
+    }
+
+    [Fact]
+    public void Parse_DspFixture_StructHasFourFields()
+    {
+        var header = _parser.Parse(DspHeader);
+        Assert.Equal(4, header.Structs[0].Fields.Count);
+    }
+
+    [Fact]
+    public void Parse_DspFixture_StructFloatFieldsMapped()
+    {
+        var header = _parser.Parse(DspHeader);
+        var s = header.Structs[0];
+        Assert.Equal("float", s.Fields[0].Type.TypeName); // min_val
+        Assert.Equal("float", s.Fields[1].Type.TypeName); // max_val
+        Assert.Equal("float", s.Fields[2].Type.TypeName); // mean
+    }
+
+    [Fact]
+    public void Parse_DspFixture_StructInt32FieldMapped()
+    {
+        var header = _parser.Parse(DspHeader);
+        var s = header.Structs[0];
+        Assert.Equal("int", s.Fields[3].Type.TypeName); // count (int32_t → int)
+        Assert.Equal("count", s.Fields[3].Name);
+    }
+
+    // ── Function extraction ───────────────────────────────────────────────────
+
+    [Fact]
+    public void Parse_DspFixture_ExtractsTwoFunctions()
+    {
+        var header = _parser.Parse(DspHeader);
+        Assert.Equal(2, header.Functions.Count);
+    }
+
+    [Fact]
+    public void Parse_DspFixture_ScaleFunction_FloatBufferParam()
+    {
+        var header = _parser.Parse(DspHeader);
+        var fn = header.Functions.Single(f => f.Name == "ferrum_dsp_scale");
+        Assert.Equal("float*", fn.Parameters[0].Type.TypeName);
+        Assert.True(fn.Parameters[0].Type.IsPointer);
+        Assert.Equal("buf", fn.Parameters[0].Name);
+    }
+
+    [Fact]
+    public void Parse_DspFixture_ScaleFunction_LenParam()
+    {
+        var header = _parser.Parse(DspHeader);
+        var fn = header.Functions.Single(f => f.Name == "ferrum_dsp_scale");
+        Assert.Equal("int", fn.Parameters[1].Type.TypeName);
+        Assert.Equal("len", fn.Parameters[1].Name);
+    }
+
+    [Fact]
+    public void Parse_DspFixture_ScaleFunction_FactorParam()
+    {
+        var header = _parser.Parse(DspHeader);
+        var fn = header.Functions.Single(f => f.Name == "ferrum_dsp_scale");
+        Assert.Equal("float", fn.Parameters[2].Type.TypeName);
+        Assert.Equal("factor", fn.Parameters[2].Name);
+    }
+
+    [Fact]
+    public void Parse_DspFixture_StatsFunction_ConstFloatPointerParam()
+    {
+        var header = _parser.Parse(DspHeader);
+        var fn = header.Functions.Single(f => f.Name == "ferrum_dsp_stats");
+        // const float* maps to float* (const is stripped — no MarshalAs, blittable only)
+        Assert.True(fn.Parameters[0].Type.IsPointer);
+        Assert.Equal("buf", fn.Parameters[0].Name);
+    }
+
+    [Fact]
+    public void Parse_DspFixture_StatsFunction_StructOutParam()
+    {
+        var header = _parser.Parse(DspHeader);
+        var fn = header.Functions.Single(f => f.Name == "ferrum_dsp_stats");
+        Assert.Equal("FerrumDspStats*", fn.Parameters[2].Type.TypeName);
+        Assert.True(fn.Parameters[2].Type.IsPointer);
+        Assert.Equal("result", fn.Parameters[2].Name);
+    }
+
+    [Fact]
+    public void Parse_DspFixture_BothFunctionsReturnVoid()
+    {
+        var header = _parser.Parse(DspHeader);
+        foreach (var fn in header.Functions)
+        {
+            Assert.Equal("void", fn.ReturnType.TypeName);
+            Assert.True(fn.ReturnType.IsVoid);
+        }
+    }
+
+    // ── Emitter round-trip ────────────────────────────────────────────────────
+
+    [Fact]
+    public void Emit_DspFixture_ContainsStructLayout()
+    {
+        var header = _parser.Parse(DspHeader);
+        var emitter = new BindingEmitter(new EmitterOptions
+        {
+            Namespace   = "Ferrum.Tests.Generated",
+            ClassName   = "DspBindings",
+            LibraryName = "__Internal",
+        });
+        string output = emitter.Emit(header);
+
+        Assert.Contains("[StructLayout(LayoutKind.Sequential)]", output);
+        Assert.Contains("public unsafe struct FerrumDspStats", output);
+    }
+
+    [Fact]
+    public void Emit_DspFixture_ContainsLibraryImportForBothFunctions()
+    {
+        var header = _parser.Parse(DspHeader);
+        var emitter = new BindingEmitter(new EmitterOptions
+        {
+            Namespace   = "Ferrum.Tests.Generated",
+            ClassName   = "DspBindings",
+            LibraryName = "__Internal",
+        });
+        string output = emitter.Emit(header);
+
+        Assert.Contains("ferrum_dsp_scale", output);
+        Assert.Contains("ferrum_dsp_stats", output);
+        Assert.Contains("[LibraryImport(LibraryName)]", output);
+    }
+
+    [Fact]
+    public void Emit_DspFixture_UsesInternalModifier()
+    {
+        var header = _parser.Parse(DspHeader);
+        var emitter = new BindingEmitter(new EmitterOptions
+        {
+            Namespace   = "Ferrum.Tests.Generated",
+            ClassName   = "DspBindings",
+            LibraryName = "__Internal",
+        });
+        string output = emitter.Emit(header);
+
+        // Generated class must be internal (not public) to follow least-privilege convention
+        Assert.Contains("internal static unsafe partial class DspBindings", output);
+    }
+
+    [Fact]
+    public void Emit_DspFixture_OutputMatchesCommittedBindings()
+    {
+        // Regression guard: the pre-generated FerrumDspBindings.cs committed to
+        // the repo must stay in sync with what the tool would actually produce.
+        // If this test fails, re-run ferrum-codegen against the fixture header
+        // and commit the updated output.
+        var header = _parser.Parse(DspHeader, "ferrum_dsp.h");
+        var emitter = new BindingEmitter(new EmitterOptions
+        {
+            Namespace   = "Ferrum.Tests.Generated",
+            ClassName   = "DspBindings",
+            LibraryName = "__Internal",
+        });
+        string generated = emitter.Emit(header);
+
+        // Load the committed file
+        string committedPath = FindCommittedBindingsFile();
+        string committed = File.ReadAllText(committedPath);
+
+        Assert.Equal(
+            committed.ReplaceLineEndings("\n"),
+            generated.ReplaceLineEndings("\n"),
+            StringComparer.Ordinal);
+    }
+
+    // ── Helpers ───────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Locates the committed <c>FerrumDspBindings.cs</c> by walking up from the
+    /// test assembly's directory until the repo root is found.
+    /// </summary>
+    private static string FindCommittedBindingsFile()
+    {
+        string dir = AppContext.BaseDirectory;
+        while (!string.IsNullOrEmpty(dir))
+        {
+            string candidate = Path.Combine(
+                dir,
+                "src", "Framework.Tests", "Codegen", "Generated", "FerrumDspBindings.cs");
+            if (File.Exists(candidate))
+                return candidate;
+            dir = Path.GetDirectoryName(dir)!;
+        }
+        throw new FileNotFoundException(
+            "Cannot locate FerrumDspBindings.cs. "
+            + "Ensure the repo root is an ancestor of the test output directory.");
+    }
+}
diff --git a/src/Framework.Tests/Codegen/Generated/FerrumDspBindings.cs b/src/Framework.Tests/Codegen/Generated/FerrumDspBindings.cs
