Auto: twincat-2.1 — ADS Sum-read / Sum-write

Closes #310

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCATSumCommandPerfTests.cs

@@ -0,0 +1,93 @@
+using System.Diagnostics;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests;
+
+/// <summary>
+///     PR 2.1 perf gate — verifies the bulk Sum-read path is materially faster than the
+///     equivalent serial per-tag <see cref="TwinCAT.Ads.AdsClient.ReadValueAsync(string, Type, System.Threading.CancellationToken)"/>
+///     loop on a real XAR runtime. The driver's <see cref="TwinCATDriver.ReadAsync"/>
+///     already routes through the bulk path; the baseline calls through a hand-rolled
+///     loop so we're comparing apples to apples on the same wire.
+/// </summary>
+/// <remarks>
+///     Requires the perf fixture: <c>GVL_Perf.aTags : ARRAY[1..1000] OF DINT</c> per
+///     <c>TwinCatProject/README.md §Performance scenarios</c>. Skipped unless
+///     <c>TWINCAT_PERF=1</c> is set.
+/// </remarks>
+[Collection("TwinCATXar")]
+[Trait("Category", "Performance")]
+[Trait("Simulator", "TwinCAT-XAR")]
+public sealed class TwinCATSumCommandPerfTests(TwinCATXarFixture sim)
+{
+    private const int TagCount = 1000;
+
+    [TwinCATPerfFact]
+    public async Task Driver_sum_read_1000_tags_beats_loop_baseline_by_5x()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+
+        var deviceAddress = $"ads://{sim.TargetNetId}:{sim.AmsPort}";
+        var tags = new TwinCATTagDefinition[TagCount];
+        var refs = new string[TagCount];
+        for (var i = 0; i < TagCount; i++)
+        {
+            // GVL_Perf.aTags is 1-based per IEC 61131-3 ARRAY declaration.
+            var name = $"Perf{i + 1}";
+            refs[i] = name;
+            tags[i] = new TwinCATTagDefinition(
+                Name: name,
+                DeviceHostAddress: deviceAddress,
+                SymbolPath: $"GVL_Perf.aTags[{i + 1}]",
+                DataType: TwinCATDataType.DInt);
+        }
+
+        var options = new TwinCATDriverOptions
+        {
+            Devices = [new TwinCATDeviceOptions(deviceAddress, "XAR-VM")],
+            Tags = tags,
+            UseNativeNotifications = false,
+            Timeout = TimeSpan.FromSeconds(15),
+            Probe = new TwinCATProbeOptions { Enabled = false },
+        };
+
+        // ---- Bulk (PR 2.1) measurement ----
+        await using var bulkDrv = new TwinCATDriver(options, "tc3-perf-bulk");
+        await bulkDrv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        // Warm-up: prime symbol-handle caches in the XAR runtime so the timed run
+        // measures sum-read steady state, not first-touch handle resolution.
+        await bulkDrv.ReadAsync(refs, TestContext.Current.CancellationToken);
+
+        var bulkSw = Stopwatch.StartNew();
+        var bulkResults = await bulkDrv.ReadAsync(refs, TestContext.Current.CancellationToken);
+        bulkSw.Stop();
+
+        // ---- Loop baseline measurement ----
+        // Use a fresh driver instance so the cache state matches the bulk run on first
+        // call. Single-tag-per-call across the full set is what PR 2.1 replaces.
+        await using var loopDrv = new TwinCATDriver(options, "tc3-perf-loop");
+        await loopDrv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+        // Warm-up against the same refs.
+        for (var i = 0; i < TagCount; i++)
+            _ = await loopDrv.ReadAsync([refs[i]], TestContext.Current.CancellationToken);
+
+        var loopSw = Stopwatch.StartNew();
+        for (var i = 0; i < TagCount; i++)
+            _ = await loopDrv.ReadAsync([refs[i]], TestContext.Current.CancellationToken);
+        loopSw.Stop();
+
+        // Sanity: bulk path must produce TagCount snapshots all Good.
+        bulkResults.Count.ShouldBe(TagCount);
+        bulkResults.ShouldAllBe(s => s.StatusCode == TwinCATStatusMapper.Good);
+
+        // Conservative ratio — on the dev box bulk is ~10-20× the loop, target is 5×.
+        // Lower bound exists so the test is robust to noisy CI / VM scheduling.
+        var ratio = (double)loopSw.ElapsedMilliseconds / Math.Max(1, bulkSw.ElapsedMilliseconds);
+        ratio.ShouldBeGreaterThan(5.0,
+            $"Bulk Sum-read should be >5x faster than per-tag loop; got bulk={bulkSw.ElapsedMilliseconds}ms, loop={loopSw.ElapsedMilliseconds}ms (ratio={ratio:F2})");
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCATXarFixture.cs

@@ -134,3 +134,24 @@ public sealed class TwinCATTheoryAttribute : TheoryAttribute
                    "for setup; typical cause is the trial license expired or TWINCAT_TARGET_NETID is unset.";
     }
 }
+
+/// <summary>
+///     Perf-tier <c>[Fact]</c> equivalent. Runs only when the XAR runtime is reachable
+///     <em>and</em> <c>TWINCAT_PERF=1</c> is set. Perf tests are gated separately because
+///     they exercise the wire heavily (1000+ tags) + can extend test runs by tens of
+///     seconds — the operator opts in.
+/// </summary>
+public sealed class TwinCATPerfFactAttribute : FactAttribute
+{
+    public TwinCATPerfFactAttribute()
+    {
+        if (!TwinCATXarFixture.IsRuntimeAvailable())
+        {
+            Skip = "TwinCAT XAR not reachable. See docs/drivers/TwinCAT-Test-Fixture.md " +
+                   "for setup; typical cause is the trial license expired or TWINCAT_TARGET_NETID is unset.";
+            return;
+        }
+        if (Environment.GetEnvironmentVariable("TWINCAT_PERF") != "1")
+            Skip = "Perf tier disabled. Set TWINCAT_PERF=1 to run; see docs/drivers/TwinCAT-Test-Fixture.md §Performance.";
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/GVLs/GVL_Perf.TcGVL

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.0">
+  <GVL Name="GVL_Perf" Id="{00000000-0000-0000-0000-000000000201}">
+    <Declaration><![CDATA[// PR 2.1 Sum-read perf fixture. 1000 DINTs read in one ADS sum-read by
+// TwinCATSumCommandPerfTests; FB_PerfChurn rotates a few values each cycle so
+// the wire isn't reading static data the runtime can short-circuit.
+//
+// Required by the perf-tier integration test
+// Driver_sum_read_1000_tags_beats_loop_baseline_by_5x. See
+// TwinCatProject/README.md §Performance scenarios.
+VAR_GLOBAL
+    aTags : ARRAY[1..1000] OF DINT;
+    fbPerfChurn : FB_PerfChurn;
+END_VAR
+]]></Declaration>
+  </GVL>
+</TcPlcObject>

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/PLC/POUs/FB_PerfChurn.TcPOU

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.0">
+  <POU Name="FB_PerfChurn" Id="{00000000-0000-0000-0000-000000000202}" SpecialFunc="None">
+    <Declaration><![CDATA[// Rotating writer for GVL_Perf.aTags so the perf integration test isn't
+// reading completely static data — keeps the runtime's symbol caches honest.
+// Increments each tag's value at MAIN-task cadence; touches all 1000 entries
+// over the 1000 cycles spanning ~10s at the default 10ms PlcTask period.
+FUNCTION_BLOCK FB_PerfChurn
+VAR
+    nIndex : INT := 1;
+END_VAR
+]]></Declaration>
+    <Implementation>
+      <ST><![CDATA[GVL_Perf.aTags[nIndex] := GVL_Perf.aTags[nIndex] + 1;
+nIndex := nIndex + 1;
+IF nIndex > 1000 THEN
+    nIndex := 1;
+END_IF
+]]></ST>
+    </Implementation>
+  </POU>
+</TcPlcObject>

tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCatProject/README.md

@@ -71,6 +71,70 @@ GVL_Fixture.nCounter := GVL_Fixture.nCounter + 1;
 - `PlcTask` — cyclic, 10 ms interval, priority 20
 - Assigned to `MAIN`
 
+## Performance scenarios
+
+PR 2.1 (ADS Sum-read / Sum-write) ships an opt-in perf-tier integration test
+(`TwinCATSumCommandPerfTests.Driver_sum_read_1000_tags_beats_loop_baseline_by_5x`)
+that reads 1000 DINTs in one shot and asserts the bulk path beats the per-tag
+loop by ≥ 5×. The fixture state required by that test is:
+
+### Global Variable List: `GVL_Perf`
+
+```st
+VAR_GLOBAL
+    // 1000-DINT array — exercised by the bulk Sum-read benchmark.
+    aTags       : ARRAY[1..1000] OF DINT;
+    fbPerfChurn : FB_PerfChurn;
+END_VAR
+```
+
+The XAE-form GVL ships at `PLC/GVLs/GVL_Perf.TcGVL`; import it into the PLC
+project alongside `GVL_Fixture`.
+
+### POU: `FB_PerfChurn`
+
+```st
+FUNCTION_BLOCK FB_PerfChurn
+VAR
+    nIndex : INT := 1;
+END_VAR
+
+GVL_Perf.aTags[nIndex] := GVL_Perf.aTags[nIndex] + 1;
+nIndex := nIndex + 1;
+IF nIndex > 1000 THEN
+    nIndex := 1;
+END_IF
+```
+
+The XAE-form POU ships at `PLC/POUs/FB_PerfChurn.TcPOU`. Wire it into `MAIN`
+so a value rotates each cycle:
+
+```st
+PROGRAM MAIN
+VAR
+END_VAR
+
+// existing GVL_Fixture line:
+GVL_Fixture.nCounter := GVL_Fixture.nCounter + 1;
+
+// PR 2.1 — keep aTags moving so caches don't short-circuit the read.
+GVL_Perf.fbPerfChurn();
+```
+
+### Running the perf tier
+
+```powershell
+$env:TWINCAT_TARGET_HOST  = '10.0.0.42'
+$env:TWINCAT_TARGET_NETID = '5.23.91.23.1.1'
+$env:TWINCAT_PERF         = '1'
+dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests `
+    --filter "Category=Performance"
+```
+
+Without `TWINCAT_PERF=1` the perf test skips via `[TwinCATPerfFact]` even when
+the runtime is reachable — perf runs are opt-in to keep the default integration
+pass fast.
+
 ### Runtime ID
 
 - TC3 PLC runtime 1 (AMS port `851`) — the smoke-test fixture defaults