fix(s7): validate span-read options at parse time; document the over-PDU degradation

2026-08-17 03:45:14 -04:00
parent f06cbe16d9
commit acb3772426
3 changed files with 135 additions and 10 deletions
@@ -88,10 +88,11 @@ public sealed class S7DriverOptions
    /// </summary>
    /// <remarks>
    ///     <para>
-    ///         <b>Any value <c>&lt;= -1</c> disables span grouping entirely</b> — every tag is read
-    ///         on its own, exactly as the driver behaved before grouping existed. That is the
-    ///         escape hatch for a CPU that dislikes wide block reads, and the control arm the
-    ///         parity tests read through.
+    ///         <b><c>-1</c> disables span grouping entirely</b> — every tag is read on its own,
+    ///         exactly as the driver behaved before grouping existed. That is the escape hatch for a
+    ///         CPU that dislikes wide block reads, and the control arm the parity tests read through.
+    ///         <c>-1</c> is the floor: <c>S7DriverFactoryExtensions.ParseOptions</c> rejects anything
+    ///         below it, so a config cannot express "disabled" by accident with an arbitrary negative.
    ///     </para>
    ///     <para>
    ///         Grouping cannot make a read fail where the per-tag reads would have succeeded: a
@@ -121,6 +122,13 @@ public sealed class S7DriverOptions
    ///     one enormous request that is mostly padding. The 220-byte default sits just under the
    ///     usable payload of the common 240-byte S7-300/400 PDU, so a typical span is one request
    ///     on the wire.
+    ///     <para>
+    ///         There is deliberately <b>no upper bound</b>: the negotiated PDU size is opaque inside
+    ///         S7.Net, so a value above it cannot be detected — it stays legal and simply degrades to
+    ///         multi-request chunking inside S7.Net, costing extra wire round-trips per span rather
+    ///         than failing. <c>S7DriverFactoryExtensions.ParseOptions</c> therefore validates only the
+    ///         lower bound (<c>&gt;= 1</c>); a non-positive cap can never admit a single block read.
+    ///     </para>
    /// </remarks>
    [Display(Name = "Span read max span (bytes)",
        Description = "Largest single planned block read. Bounds wasted-gap amplification, not correctness.",