826312befe
Clears CommentChecker findings in src/ (3,280 -> 209, the remainder being false positives like PLC-5/IEEE-754/M0.0) by adding missing summaries/params/returns, normalising inheritdoc usage, and removing Gitea/review tracking IDs while keeping the rationale they annotated. Comment-only: comment-stripped sources are identical to the parent commit.
138 lines
6.6 KiB
C#
138 lines
6.6 KiB
C#
using ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Wire;
|
|
|
|
namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS;
|
|
|
|
/// <summary>One PMC read the coalescer may merge — the caller's batch index plus the parsed address and type.</summary>
|
|
/// <param name="Index">Position in the caller's batch; results are sliced back to it.</param>
|
|
/// <param name="Letter">PMC area letter (<c>R</c>, <c>X</c>, ...), upper-case.</param>
|
|
/// <param name="Number">Byte address.</param>
|
|
/// <param name="Type">The tag's declared data type (decides slot width and decode).</param>
|
|
/// <param name="BitIndex">Bit index for a <see cref="FocasDataType.Bit"/> tag.</param>
|
|
internal readonly record struct FocasPmcReadItem(int Index, string Letter, int Number, FocasDataType Type, int? BitIndex);
|
|
|
|
/// <summary>
|
|
/// One planned <c>pmc_rdpmcrng</c> read covering <see cref="Members"/>. <see cref="End"/> is inclusive and is a
|
|
/// whole number of <see cref="SlotWidth"/>-byte slots from <see cref="Start"/>.
|
|
/// </summary>
|
|
internal sealed record FocasPmcRangePlan(
|
|
string Letter,
|
|
FocasDataType SlotType,
|
|
int SlotWidth,
|
|
int Start,
|
|
int End,
|
|
IReadOnlyList<FocasPmcReadItem> Members)
|
|
{
|
|
/// <summary>Stable key for the "this range was rejected, read members individually" memo.</summary>
|
|
public string Key => $"{Letter}:{SlotType}:{Start}-{End}";
|
|
|
|
/// <summary>Slot index (into the decoded range) that holds <paramref name="item"/>'s value.</summary>
|
|
/// <param name="item">A member of this plan.</param>
|
|
/// <returns>The zero-based slot index.</returns>
|
|
public int SlotOf(FocasPmcReadItem item) => (item.Number - Start) / SlotWidth;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Merges adjacent / near PMC reads in one poll batch into fewer <c>pmc_rdpmcrng</c> calls.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>Items are grouped by <c>(letter, slot width class)</c> and merged in address order while (a) the gap to
|
|
/// the previous member is at most <c>maxGapBytes</c> and (b) the whole range stays within <c>maxSpanBytes</c>.
|
|
/// A multi-byte member only joins a range when its offset from the range start is a multiple of its width — the
|
|
/// CNC splits a range into width-sized slots from the start, so an unaligned member would be decoded from the
|
|
/// wrong bytes. Members that cannot merge become single-member plans; the driver reads those through the
|
|
/// ordinary per-tag path, so the common "one tag per area" case is byte-for-byte unchanged.</para>
|
|
/// <para>Pure and deterministic: no I/O, no clock.</para>
|
|
/// </remarks>
|
|
internal static class FocasPmcCoalescer
|
|
{
|
|
/// <summary>Plans the reads for a batch.</summary>
|
|
/// <param name="items">The PMC reads in the batch (any order).</param>
|
|
/// <param name="maxSpanBytes">Largest range, in bytes, one coalesced read may cover (>= 1).</param>
|
|
/// <param name="maxGapBytes">Largest run of unrequested bytes tolerated between two members (>= 0).</param>
|
|
/// <returns>Range plans; every input item appears in exactly one plan.</returns>
|
|
public static IReadOnlyList<FocasPmcRangePlan> Plan(
|
|
IEnumerable<FocasPmcReadItem> items, int maxSpanBytes, int maxGapBytes)
|
|
{
|
|
maxSpanBytes = Math.Max(1, maxSpanBytes);
|
|
maxGapBytes = Math.Max(0, maxGapBytes);
|
|
var plans = new List<FocasPmcRangePlan>();
|
|
|
|
var groups = items
|
|
.GroupBy(i => (Letter: i.Letter.ToUpperInvariant(), Slot: SlotTypeOf(i.Type)))
|
|
.OrderBy(g => g.Key.Letter, StringComparer.Ordinal).ThenBy(g => g.Key.Slot);
|
|
|
|
foreach (var group in groups)
|
|
{
|
|
var width = FocasWireClient.PmcByteWidth((short)FocasPmcDataTypeLookup.FromFocasDataType(group.Key.Slot));
|
|
var sorted = group.OrderBy(i => i.Number).ThenBy(i => i.Index).ToList();
|
|
|
|
List<FocasPmcReadItem>? members = null;
|
|
var start = 0;
|
|
var end = 0; // inclusive
|
|
|
|
void Flush()
|
|
{
|
|
if (members is null) return;
|
|
// Round the range up to a whole number of slots so the CNC returns no partial trailing slot.
|
|
var bytes = end - start + 1;
|
|
var rounded = (bytes + width - 1) / width * width;
|
|
plans.Add(new FocasPmcRangePlan(group.Key.Letter, group.Key.Slot, width, start, start + rounded - 1, members));
|
|
members = null;
|
|
}
|
|
|
|
foreach (var item in sorted)
|
|
{
|
|
var itemEnd = item.Number + width - 1;
|
|
if (members is not null)
|
|
{
|
|
var gap = Math.Max(0, item.Number - (end + 1));
|
|
var aligned = (item.Number - start) % width == 0;
|
|
var newEnd = Math.Max(end, itemEnd);
|
|
// The span check is on the ROUNDED length a flush would produce.
|
|
var roundedSpan = (newEnd - start + 1 + width - 1) / width * width;
|
|
if (aligned && gap <= maxGapBytes && roundedSpan <= maxSpanBytes)
|
|
{
|
|
members.Add(item);
|
|
end = newEnd;
|
|
continue;
|
|
}
|
|
Flush();
|
|
}
|
|
members = [item];
|
|
start = item.Number;
|
|
end = itemEnd;
|
|
}
|
|
Flush();
|
|
}
|
|
return plans;
|
|
}
|
|
|
|
/// <summary>The data type whose wire width a read of <paramref name="type"/> uses (Bit and Byte share one).</summary>
|
|
/// <param name="type">The tag's declared type.</param>
|
|
/// <returns>The representative slot type.</returns>
|
|
public static FocasDataType SlotTypeOf(FocasDataType type) => type switch
|
|
{
|
|
FocasDataType.Bit or FocasDataType.Byte => FocasDataType.Byte,
|
|
_ => type,
|
|
};
|
|
|
|
/// <summary>
|
|
/// Decodes one raw PMC slot (as <c>pmc_rdpmcrng</c> parsed it) into the tag's published value. The single
|
|
/// decode authority for both the per-tag and the coalesced path.
|
|
/// </summary>
|
|
/// <param name="raw">The slot value.</param>
|
|
/// <param name="type">The tag's declared type.</param>
|
|
/// <param name="bitIndex">Bit index for a Bit tag.</param>
|
|
/// <returns>The boxed value.</returns>
|
|
public static object MapSlot(long raw, FocasDataType type, int? bitIndex) => type switch
|
|
{
|
|
FocasDataType.Bit => (object)(((raw >> (bitIndex ?? 0)) & 1L) != 0),
|
|
FocasDataType.Byte => (object)(sbyte)(raw & 0xFFL),
|
|
FocasDataType.Int16 => (object)(short)raw,
|
|
FocasDataType.Int32 => (object)(int)raw,
|
|
FocasDataType.Float32 => (object)BitConverter.Int32BitsToSingle((int)raw),
|
|
FocasDataType.Float64 => (object)BitConverter.Int64BitsToDouble(raw),
|
|
_ => (object)raw,
|
|
};
|
|
}
|