Add support for load testing device

[jonnew]

Relevant ONI datasheet:

https://open-ephys.github.io/onix-docs/Hardware%20Guide/Datasheets/load-test.html

This device exists on ONIX PCIe controller, but is not exposed in the library currently. I don't think it should be integrated into the breakout board MultiDeviceFactory, but only as a single, manually configured device for development and "hard mode" diagnostic use.

[jonnew]

This device is somewhat interesting because it exposes a feature that is not currently used in the library: variable sized frames. The size of the read frame is determined, following reset, by the value of the DT0H16_WORDS register. Currently Bonsai.Onix1 DataFrames are generated by defining an internal, fixed size struct, called <Device>Payload with well defined memory layout. Within an unsafe constructor, an explicit cast is used to convert the oni's frame_t 's void *data pointer into a <Device>Payload *payload. The strongly data members can be accessed easly and efficiently from this pointer. Large, fixed size blocks of data are encoded using e.g. fixed ushort data[N] members within the payload structure.

For the load testing device, the size of the data block is not known at compile time and thus cannot be directly included in the payload struct. @aacuevas I see two, essentially identical paths for dealing with this that are semantically different with different package dependencies and I want feedback on these:

Pointer Arithmetic

using System.Runtime.InteropServices;

namespace OpenEphys.Onix1
{
    /// <summary>
    /// The time of a load tester frame.
    /// </summary>
    public class LoadTesterDataFrame : DataFrame
    {
        public ulong HubClockDelta { get; }

        public ushort[] Counter { get; }

        /// <summary>
        /// Initializes a new instance of the <see cref="LoadTesterDataFrame"/> class.
        /// </summary>
        /// <param name="frame">A data frame produced by a load tester device.</param>
        /// <param name="receivedWords">The number of counter words that appear at the end of the load test data frame. This number is determined by the value of <see cref="ConfigureLoadTester.ReceivedWords"/>.</param>
        public unsafe LoadTesterDataFrame(oni.Frame frame, int receivedWords)
            : base(frame.Clock)
        {

            var payload = (LoadTesterPayload*)frame.Data.ToPointer();

            HubClock = payload->HubClock;
            HubClockDelta = payload->HubClockDelta;
            Counter = new ushort[receivedWords];

            fixed (ushort* destPtr = Counter)
            {
                ushort* srcPtr = (ushort*)payload + sizeof(LoadTesterPayload);
                ushort* destEnd = destPtr + receivedWords;
                ushort* dest = destPtr;

                while (dest < destEnd)
                {
                    *dest++ = *srcPtr++;
                }
            }
        }
    }

    [StructLayout(LayoutKind.Sequential, Pack = 1)]
    struct LoadTesterPayload
    {
        public ulong HubClock;
        public ulong HubClockDelta;
        // NB: The ushort counter array may or may not reside here. It size is determined by ReceivedWords.
    }
}

Spans (requires System.Memory nuget package for Framework based project)

using System;
using System.Runtime.InteropServices;

namespace OpenEphys.Onix1
{
    /// <summary>
    /// The time of a load tester frame.
    /// </summary>
    public class LoadTesterDataFrame : DataFrame
    {
        public ulong HubClockDelta { get; }

        public ushort[] Counter { get; }

        /// <summary>
        /// Initializes a new instance of the <see cref="LoadTesterDataFrame"/> class.
        /// </summary>
        /// <param name="frame">A data frame produced by a load tester device.</param>
        /// <param name="receivedWords">The number of counter words that appear at the end of the load test data frame. This number is determined by the value of <see cref="ConfigureLoadTester.ReceivedWords"/>.</param>
        public unsafe LoadTesterDataFrame(oni.Frame frame, int receivedWords)
            : base(frame.Clock)
        {

            var payload = (LoadTesterPayload*)frame.Data.ToPointer();
            var counterPtr = (ushort*)((byte*)payload + sizeof(LoadTesterPayload));

            HubClock = payload->HubClock;
            HubClockDelta = payload->HubClockDelta;
            Counter = new Span<ushort>(counterPtr, receivedWords).ToArray();
        }
    }

    [StructLayout(LayoutKind.Sequential, Pack = 1)]
    struct LoadTesterPayload
    {
        public ulong HubClock;
        public ulong HubClockDelta;
        // NB: The ushort counter array may or may not reside here. It size is determined by ReceivedWords.
    }
}

[aacuevas]

Personally, I lean towards the Span implementation.
Yes, requiring an extra dependency is not ideal. However, I feel it's a cleaner and more C#-like option over manual pointer code.

Also, it is probably going to be faster. I don't know how well the compiler will optimize the pointer copy loop, but the span ToArray() method most probably uses platform-optimized vector operations.

[jonnew]

Cool, I'll go the span route. Also, well now have access to them in the library. They basically implement the Array API and are thus a very high performance addition to the language.