From f45fda09308bc3d0c9d4c52fa1f02e1e8c31b71f Mon Sep 17 00:00:00 2001 From: Greg Ingram Date: Mon, 14 Jan 2019 19:12:53 -0500 Subject: [PATCH] Cleanup for I2C drivers (#143) * Added editconfig file * Cleanup for I2C drivers * Cleanup for I2C drivers * Updated wording * Updated for feedback --- .../Device/I2c/Drivers/UnixI2cDevice.Linux.cs | 59 +++++++++++++++---- .../I2c/Drivers/UnixI2cDevice.Windows.cs | 1 - .../I2c/Drivers/Windows10I2cDevice.Windows.cs | 52 ++++++++++++---- .../Device/I2c/I2cConnectionSettings.cs | 10 ++-- .../System/Device/I2c/I2cDevice.cs | 32 ++++++++++ 5 files changed, 127 insertions(+), 27 deletions(-) diff --git a/src/System.Device.Gpio/System/Device/I2c/Drivers/UnixI2cDevice.Linux.cs b/src/System.Device.Gpio/System/Device/I2c/Drivers/UnixI2cDevice.Linux.cs index a673a9d3..b95e5d1a 100644 --- a/src/System.Device.Gpio/System/Device/I2c/Drivers/UnixI2cDevice.Linux.cs +++ b/src/System.Device.Gpio/System/Device/I2c/Drivers/UnixI2cDevice.Linux.cs @@ -7,22 +7,37 @@ using System.Runtime.InteropServices; namespace System.Device.I2c.Drivers { + /// + /// Represents an I2C communication channel running on Unix. + /// public class UnixI2cDevice : I2cDevice { - private I2cConnectionSettings _settings; + private readonly I2cConnectionSettings _settings; private const string DefaultDevicePath = "/dev/i2c"; private int _deviceFileDescriptor = -1; private I2cFunctionalityFlags _functionalities; - private static readonly object s_InitializationLock = new object(); - + private static readonly object s_initializationLock = new object(); + + /// + /// Initializes new instance of UnixI2cDevice that will use the specified settings to communicate with the I2C device. + /// + /// + /// The connection settings of a device on an I2C bus. + /// public UnixI2cDevice(I2cConnectionSettings settings) { _settings = settings; DevicePath = DefaultDevicePath; } + /// + /// Path to I2C resources located on the platform. + /// public string DevicePath { get; set; } + /// + /// The connection settings of a device on an I2C bus. + /// public override I2cConnectionSettings ConnectionSettings => _settings; private unsafe void Initialize() @@ -33,7 +48,7 @@ namespace System.Device.I2c.Drivers } string deviceFileName = $"{DevicePath}-{_settings.BusId}"; - lock (s_InitializationLock) + lock (s_initializationLock) { if (_deviceFileDescriptor >= 0) { @@ -43,7 +58,7 @@ namespace System.Device.I2c.Drivers if (_deviceFileDescriptor < 0) { - throw new IOException($"Cannot open I2c device file '{deviceFileName}'"); + throw new IOException($"Can not open I2C device file '{deviceFileName}'."); } I2cFunctionalityFlags tempFlags; @@ -96,16 +111,16 @@ namespace System.Device.I2c.Drivers }; } - var tr = new i2c_rdwr_ioctl_data() + var msgset = new i2c_rdwr_ioctl_data() { msgs = messagesPtr, nmsgs = (uint)messageCount }; - int result = Interop.ioctl(_deviceFileDescriptor, (uint)I2cSettings.I2C_RDWR, new IntPtr(&tr)); + int result = Interop.ioctl(_deviceFileDescriptor, (uint)I2cSettings.I2C_RDWR, new IntPtr(&msgset)); if (result < 0) { - throw new IOException("Error when attempting to perform the I2c data transfer."); + throw new IOException("Error performing I2C data transfer."); } } @@ -114,7 +129,7 @@ namespace System.Device.I2c.Drivers int result = Interop.ioctl(_deviceFileDescriptor, (uint)I2cSettings.I2C_SLAVE_FORCE, (ulong)_settings.DeviceAddress); if (result < 0) { - throw new IOException("Error performing I2c data transfer"); + throw new IOException("Error performing I2C data transfer."); } if (writeBuffer != null) @@ -122,7 +137,7 @@ namespace System.Device.I2c.Drivers result = Interop.write(_deviceFileDescriptor, new IntPtr(writeBuffer), writeBufferLength); if (result < 0) { - throw new IOException("Error performing I2c data transfer"); + throw new IOException("Error performing I2C data transfer."); } } @@ -131,11 +146,15 @@ namespace System.Device.I2c.Drivers result = Interop.read(_deviceFileDescriptor, new IntPtr(readBuffer), readBufferLength); if (result < 0) { - throw new IOException("Error performing I2c data transfer"); + throw new IOException("Error performing I2C data transfer."); } } } + /// + /// Reads a byte from the I2C device. + /// + /// A byte read from the I2C device. public override unsafe byte ReadByte() { Initialize(); @@ -146,6 +165,13 @@ namespace System.Device.I2c.Drivers return result; } + /// + /// Reads data from the I2C device. + /// + /// + /// The buffer to read the data from the I2C device. + /// The length of the buffer determines how much data to read from the I2C device. + /// public override unsafe void Read(Span buffer) { Initialize(); @@ -156,6 +182,10 @@ namespace System.Device.I2c.Drivers } } + /// + /// Writes a byte to the I2C device. + /// + /// The byte to be written to the I2C device. public override unsafe void WriteByte(byte data) { Initialize(); @@ -164,6 +194,13 @@ namespace System.Device.I2c.Drivers Transfer(&data, null, length, 0); } + /// + /// Writes data to the I2C device. + /// + /// + /// The buffer that contains the data to be written to the I2C device. + /// The data should not include the I2C device address. + /// public override unsafe void Write(Span data) { Initialize(); diff --git a/src/System.Device.Gpio/System/Device/I2c/Drivers/UnixI2cDevice.Windows.cs b/src/System.Device.Gpio/System/Device/I2c/Drivers/UnixI2cDevice.Windows.cs index 1a92d749..bc309f77 100644 --- a/src/System.Device.Gpio/System/Device/I2c/Drivers/UnixI2cDevice.Windows.cs +++ b/src/System.Device.Gpio/System/Device/I2c/Drivers/UnixI2cDevice.Windows.cs @@ -2,7 +2,6 @@ // The .NET Foundation licenses this file to you under the MIT license. // See the LICENSE file in the project root for more information. - namespace System.Device.I2c.Drivers { public class UnixI2cDevice : I2cDevice diff --git a/src/System.Device.Gpio/System/Device/I2c/Drivers/Windows10I2cDevice.Windows.cs b/src/System.Device.Gpio/System/Device/I2c/Drivers/Windows10I2cDevice.Windows.cs index 32d8c585..add8ccd8 100644 --- a/src/System.Device.Gpio/System/Device/I2c/Drivers/Windows10I2cDevice.Windows.cs +++ b/src/System.Device.Gpio/System/Device/I2c/Drivers/Windows10I2cDevice.Windows.cs @@ -7,11 +7,18 @@ using WinI2c = Windows.Devices.I2c; namespace System.Device.I2c.Drivers { + /// + /// Represents an I2C communication channel running on Windows 10 IoT. + /// public class Windows10I2cDevice : I2cDevice { private readonly I2cConnectionSettings _settings; - private WinI2c.I2cDevice _winDevice; + private WinI2c.I2cDevice _winI2cDevice; + /// + /// Initializes new instance of Windows10I2cDevice that will use the specified settings to communicate with the I2C device. + /// + /// The connection settings of a device on an I2C bus. public Windows10I2cDevice(I2cConnectionSettings settings) { _settings = settings; @@ -23,46 +30,71 @@ namespace System.Device.I2c.Drivers DeviceInformationCollection deviceInformationCollection = DeviceInformation.FindAllAsync(deviceSelector).WaitForCompletion(); if (deviceInformationCollection.Count == 0) { - throw new ArgumentException($"No I2C device exists for BusId {settings.BusId}", $"{nameof(settings)}.{nameof(settings.BusId)}"); + throw new ArgumentException($"No I2C device exists for bus ID {settings.BusId}.", $"{nameof(settings)}.{nameof(settings.BusId)}"); } - _winDevice = WinI2c.I2cDevice.FromIdAsync(deviceInformationCollection[0].Id, winSettings).WaitForCompletion(); - if (_winDevice == null) + _winI2cDevice = WinI2c.I2cDevice.FromIdAsync(deviceInformationCollection[0].Id, winSettings).WaitForCompletion(); + if (_winI2cDevice == null) { throw new PlatformNotSupportedException($"I2C devices are not supported."); } } + /// + /// The connection settings of a device on an I2C bus. + /// public override I2cConnectionSettings ConnectionSettings => _settings; + /// + /// Reads a byte from the I2C device. + /// + /// A byte read from the I2C device. public override byte ReadByte() { byte[] buffer = new byte[1]; - _winDevice.Read(buffer); + _winI2cDevice.Read(buffer); return buffer[0]; } + /// + /// Reads data from the I2C device. + /// + /// + /// The buffer to read the data from the I2C device. + /// The length of the buffer determines how much data to read from the I2C device. + /// public override void Read(Span buffer) { byte[] byteArray = new byte[buffer.Length]; - _winDevice.Read(byteArray); + _winI2cDevice.Read(byteArray); new Span(byteArray).CopyTo(buffer); } + /// + /// Writes a byte to the I2C device. + /// + /// The byte to be written to the I2C device. public override void WriteByte(byte data) { - _winDevice.Write(new[] { data }); + _winI2cDevice.Write(new[] { data }); } + /// + /// Writes data to the I2C device. + /// + /// + /// The buffer that contains the data to be written to the I2C device. + /// The data should not include the I2C device address. + /// public override void Write(Span data) { - _winDevice.Write(data.ToArray()); + _winI2cDevice.Write(data.ToArray()); } public override void Dispose(bool disposing) { - _winDevice?.Dispose(); - _winDevice = null; + _winI2cDevice?.Dispose(); + _winI2cDevice = null; base.Dispose(disposing); } diff --git a/src/System.Device.Gpio/System/Device/I2c/I2cConnectionSettings.cs b/src/System.Device.Gpio/System/Device/I2c/I2cConnectionSettings.cs index 0e24983e..e2b1ae0f 100644 --- a/src/System.Device.Gpio/System/Device/I2c/I2cConnectionSettings.cs +++ b/src/System.Device.Gpio/System/Device/I2c/I2cConnectionSettings.cs @@ -5,7 +5,7 @@ namespace System.Device.I2c { /// - /// The connection settings of a device on a I2C bus. + /// The connection settings of a device on an I2C bus. /// public sealed class I2cConnectionSettings { @@ -14,8 +14,8 @@ namespace System.Device.I2c /// /// Initializes new instance of I2cConnectionSettings. /// - /// The bus ID the device is connected to. - /// The bus address of the device. + /// The bus ID the I2C device is connected to. + /// The bus address of the I2C device. public I2cConnectionSettings(int busId, int deviceAddress) { BusId = busId; @@ -23,12 +23,12 @@ namespace System.Device.I2c } /// - /// The bus ID the device is connected to. + /// The bus ID the I2C device is connected to. /// public int BusId { get; } /// - /// The bus address of the device. + /// The bus address of the I2C device. /// public int DeviceAddress { get; } } diff --git a/src/System.Device.Gpio/System/Device/I2c/I2cDevice.cs b/src/System.Device.Gpio/System/Device/I2c/I2cDevice.cs index cddaf35b..aed163fa 100644 --- a/src/System.Device.Gpio/System/Device/I2c/I2cDevice.cs +++ b/src/System.Device.Gpio/System/Device/I2c/I2cDevice.cs @@ -4,12 +4,44 @@ namespace System.Device.I2c { + /// + /// The communications channel to a device on an I2C bus. + /// public abstract class I2cDevice : IDisposable { + /// + /// The connection settings of a device on an I2C bus. + /// public abstract I2cConnectionSettings ConnectionSettings { get; } + + /// + /// Reads a byte from the I2C device. + /// + /// A byte read from the I2C device. public abstract byte ReadByte(); + + /// + /// Reads data from the I2C device. + /// + /// + /// The buffer to read the data from the I2C device. + /// The length of the buffer determines how much data to read from the I2C device. + /// public abstract void Read(Span buffer); + + /// + /// Writes a byte to the I2C device. + /// + /// The byte to be written to the I2C device. public abstract void WriteByte(byte data); + + /// + /// Writes data to the I2C device. + /// + /// + /// The buffer that contains the data to be written to the I2C device. + /// The data should not include the I2C device address. + /// public abstract void Write(Span data); public void Dispose() -- GitLab