diff --git a/src/System.Device.Gpio/System/Device/Spi/Drivers/UnixSpiDevice.Linux.cs b/src/System.Device.Gpio/System/Device/Spi/Drivers/UnixSpiDevice.Linux.cs index 251f3a31e0..5130dde1ca 100644 --- a/src/System.Device.Gpio/System/Device/Spi/Drivers/UnixSpiDevice.Linux.cs +++ b/src/System.Device.Gpio/System/Device/Spi/Drivers/UnixSpiDevice.Linux.cs @@ -6,22 +6,37 @@ namespace System.Device.Spi.Drivers { + /// + /// Represents an SPI communication channel running on Unix. + /// public class UnixSpiDevice : SpiDevice { - private const string Default_Device_Path = "/dev/spidev"; + private const string DefaultDevicePath = "/dev/spidev"; private const uint SPI_IOC_MESSAGE_1 = 0x40206b00; private int _deviceFileDescriptor = -1; private readonly SpiConnectionSettings _settings; - private static readonly object s_InitializationLock = new object(); - + private static readonly object s_initializationLock = new object(); + + /// + /// Initializes new instance of UnixSpiDevice that will use the specified settings to communicate with the SPI device. + /// + /// + /// The connection settings of a device on a SPI bus. + /// public UnixSpiDevice(SpiConnectionSettings settings) { _settings = settings; - DevicePath = Default_Device_Path; + DevicePath = DefaultDevicePath; } + /// + /// Path to SPI resources located on the platform. + /// public string DevicePath { get; set; } + /// + /// The connection settings of a device on a SPI bus. + /// public override SpiConnectionSettings ConnectionSettings => _settings; private unsafe void Initialize() @@ -30,7 +45,7 @@ private unsafe void Initialize() { return; } - lock (s_InitializationLock) + lock (s_initializationLock) { string deviceFileName = $"{DevicePath}{_settings.BusId}.{_settings.ChipSelectLine}"; if (_deviceFileDescriptor >= 0) @@ -40,7 +55,7 @@ private unsafe void Initialize() _deviceFileDescriptor = Interop.open(deviceFileName, FileOpenFlags.O_RDWR); if (_deviceFileDescriptor < 0) { - throw new IOException($"Cannot open Spi device file '{deviceFileName}'"); + throw new IOException($"Can not open SPI device file '{deviceFileName}'."); } UnixSpiMode mode = SpiModeToUnixSpiMode(_settings.Mode); @@ -49,7 +64,7 @@ private unsafe void Initialize() int result = Interop.ioctl(_deviceFileDescriptor, (uint)SpiSettings.SPI_IOC_WR_MODE, nativePtr); if (result == -1) { - throw new IOException($"Cannot set Spi mode to {_settings.Mode}"); + throw new IOException($"Can not set SPI mode to {_settings.Mode}."); } byte dataLengthInBits = (byte)_settings.DataBitLength; @@ -58,7 +73,7 @@ private unsafe void Initialize() result = Interop.ioctl(_deviceFileDescriptor, (uint)SpiSettings.SPI_IOC_WR_BITS_PER_WORD, nativePtr); if (result == -1) { - throw new IOException($"Cannot set Spi data bit length to {_settings.DataBitLength}"); + throw new IOException($"Can not set SPI data bit length to {_settings.DataBitLength}."); } int clockFrequency = _settings.ClockFrequency; @@ -67,7 +82,7 @@ private unsafe void Initialize() result = Interop.ioctl(_deviceFileDescriptor, (uint)SpiSettings.SPI_IOC_WR_MAX_SPEED_HZ, nativePtr); if (result == -1) { - throw new IOException($"Cannot set Spi clock frequency to {_settings.ClockFrequency}"); + throw new IOException($"Can not set SPI clock frequency to {_settings.ClockFrequency}."); } } } @@ -85,10 +100,14 @@ private UnixSpiMode SpiModeToUnixSpiMode(SpiMode mode) case SpiMode.Mode3: return UnixSpiMode.SPI_MODE_3; default: - throw new ArgumentException("Invalid SpiMode", nameof(mode)); + throw new ArgumentException("Invalid SPI mode.", nameof(mode)); } } + /// + /// Reads a byte from the SPI device. + /// + /// A byte read from the SPI device. public override unsafe byte ReadByte() { Initialize(); @@ -100,6 +119,13 @@ public override unsafe byte ReadByte() return result; } + /// + /// Reads data from the SPI device. + /// + /// + /// The buffer to read the data from the SPI device. + /// The length of the buffer determines how much data to read from the SPI device. + /// public override unsafe void Read(Span buffer) { Initialize(); @@ -110,6 +136,10 @@ public override unsafe void Read(Span buffer) } } + /// + /// Writes a byte to the SPI device. + /// + /// The byte to be written to the SPI device. public override unsafe void WriteByte(byte data) { Initialize(); @@ -118,6 +148,12 @@ public override unsafe void WriteByte(byte data) Transfer(&data, null, length); } + /// + /// Writes data to the SPI device. + /// + /// + /// The buffer that contains the data to be written to the SPI device. + /// public override unsafe void Write(Span data) { Initialize(); @@ -127,19 +163,27 @@ public override unsafe void Write(Span data) Transfer(dataPtr, null, data.Length); } } + + /// + /// Writes and reads data from the SPI device. + /// + /// The buffer that contains the data to be written to the SPI device. + /// The buffer to read the data from the SPI device. public override unsafe void TransferFullDuplex(Span writeBuffer, Span readBuffer) { Initialize(); if (writeBuffer.Length != readBuffer.Length) { - throw new ArgumentException($"Parameters '{nameof(writeBuffer)}' and '{nameof(readBuffer)}' must have the same length"); + throw new ArgumentException($"Parameters '{nameof(writeBuffer)}' and '{nameof(readBuffer)}' must have the same length."); } fixed (byte* writeBufferPtr = writeBuffer) - fixed (byte* readBufferPtr = readBuffer) { - Transfer(writeBufferPtr, readBufferPtr, writeBuffer.Length); + fixed (byte* readBufferPtr = readBuffer) + { + Transfer(writeBufferPtr, readBufferPtr, writeBuffer.Length); + } } } @@ -158,7 +202,7 @@ private unsafe void Transfer(byte* writeBufferPtr, byte* readBufferPtr, int buff int result = Interop.ioctl(_deviceFileDescriptor, SPI_IOC_MESSAGE_1, new IntPtr(&tr)); if (result < 1) { - throw new IOException("Error while performing the Spi data transfer."); + throw new IOException("Error performing SPI data transfer."); } } diff --git a/src/System.Device.Gpio/System/Device/Spi/Drivers/Windows10SpiDevice.Windows.cs b/src/System.Device.Gpio/System/Device/Spi/Drivers/Windows10SpiDevice.Windows.cs index 2628a7fe44..9e83d61088 100644 --- a/src/System.Device.Gpio/System/Device/Spi/Drivers/Windows10SpiDevice.Windows.cs +++ b/src/System.Device.Gpio/System/Device/Spi/Drivers/Windows10SpiDevice.Windows.cs @@ -7,11 +7,20 @@ namespace System.Device.Spi.Drivers { + /// + /// Represents an SPI communication channel running on Windows 10 IoT. + /// public class Windows10SpiDevice : SpiDevice { private readonly SpiConnectionSettings _settings; private WinSpi.SpiDevice _winDevice; + /// + /// Initializes new instance of Windows10SpiDevice that will use the specified settings to communicate with the SPI device. + /// + /// + /// The connection settings of a device on a SPI bus. + /// public Windows10SpiDevice(SpiConnectionSettings settings) { _settings = settings; @@ -28,14 +37,21 @@ public Windows10SpiDevice(SpiConnectionSettings settings) DeviceInformationCollection deviceInformationCollection = DeviceInformation.FindAllAsync(deviceSelector).WaitForCompletion(); if (deviceInformationCollection.Count == 0) { - throw new ArgumentException($"No SPI device exists for BusId {settings.BusId}", $"{nameof(settings)}.{nameof(settings.BusId)}"); + throw new ArgumentException($"No SPI device exists for bus ID {settings.BusId}.", $"{nameof(settings)}.{nameof(settings.BusId)}"); } _winDevice = WinSpi.SpiDevice.FromIdAsync(deviceInformationCollection[0].Id, winSettings).WaitForCompletion(); } + /// + /// The connection settings of a device on a SPI bus. + /// public override SpiConnectionSettings ConnectionSettings => _settings; + /// + /// Reads a byte from the SPI device. + /// + /// A byte read from the SPI device. public override byte ReadByte() { byte[] buffer = new byte[1]; @@ -43,6 +59,13 @@ public override byte ReadByte() return buffer[0]; } + /// + /// Reads data from the SPI device. + /// + /// + /// The buffer to read the data from the SPI device. + /// The length of the buffer determines how much data to read from the SPI device. + /// public override void Read(Span buffer) { byte[] byteArray = new byte[buffer.Length]; @@ -50,21 +73,36 @@ public override void Read(Span buffer) new Span(byteArray).CopyTo(buffer); } + /// + /// Writes a byte to the SPI device. + /// + /// The byte to be written to the SPI device. public override void WriteByte(byte data) { _winDevice.Write(new[] { data }); } + /// + /// Writes data to the SPI device. + /// + /// + /// The buffer that contains the data to be written to the SPI device. + /// public override void Write(Span data) { _winDevice.Write(data.ToArray()); } + /// + /// Writes and reads data from the SPI device. + /// + /// The buffer that contains the data to be written to the SPI device. + /// The buffer to read the data from the SPI device. public override void TransferFullDuplex(Span writeBuffer, Span readBuffer) { if (writeBuffer.Length != readBuffer.Length) { - throw new ArgumentException($"Parameters '{nameof(writeBuffer)}' and '{nameof(readBuffer)}' must have the same length"); + throw new ArgumentException($"Parameters '{nameof(writeBuffer)}' and '{nameof(readBuffer)}' must have the same length."); } byte[] byteArray = new byte[readBuffer.Length]; _winDevice.TransferFullDuplex(writeBuffer.ToArray(), byteArray); @@ -91,7 +129,7 @@ private static WinSpi.SpiMode ToWinMode(SpiMode mode) case SpiMode.Mode3: return WinSpi.SpiMode.Mode3; default: - throw new ArgumentException($"SPI mode not supported: {mode}", nameof(mode)); + throw new ArgumentException($"SPI mode {mode} not supported.", nameof(mode)); } } } diff --git a/src/System.Device.Gpio/System/Device/Spi/SpiDevice.cs b/src/System.Device.Gpio/System/Device/Spi/SpiDevice.cs index 7445cdcd09..a25a104fa8 100644 --- a/src/System.Device.Gpio/System/Device/Spi/SpiDevice.cs +++ b/src/System.Device.Gpio/System/Device/Spi/SpiDevice.cs @@ -4,13 +4,50 @@ namespace System.Device.Spi { + /// + /// The communications channel to a device on a SPI bus. + /// public abstract class SpiDevice : IDisposable { + /// + /// The connection settings of a device on a SPI bus. + /// public abstract SpiConnectionSettings ConnectionSettings { get; } + + /// + /// Reads a byte from the SPI device. + /// + /// A byte read from the SPI device. public abstract byte ReadByte(); + + /// + /// Reads data from the SPI device. + /// + /// + /// The buffer to read the data from the SPI device. + /// The length of the buffer determines how much data to read from the SPI device. + /// public abstract void Read(Span buffer); + + /// + /// Writes a byte to the SPI device. + /// + /// The byte to be written to the SPI device. public abstract void WriteByte(byte data); + + /// + /// Writes data to the SPI device. + /// + /// + /// The buffer that contains the data to be written to the SPI device. + /// public abstract void Write(Span data); + + /// + /// Writes and reads data from the SPI device. + /// + /// The buffer that contains the data to be written to the SPI device. + /// The buffer to read the data from the SPI device. public abstract void TransferFullDuplex(Span writeBuffer, Span readBuffer); public void Dispose()