From 694b5db58ca7c4e06caa17f1a49adbee1636357b Mon Sep 17 00:00:00 2001 From: Pomian Date: Tue, 1 Jun 2021 13:31:55 +0200 Subject: [PATCH] Initial internal documentation (#391) Thanks to @Pomianowski --- LibreHardwareMonitorLib/Hardware/Computer.cs | 59 ++++ LibreHardwareMonitorLib/Hardware/IComputer.cs | 3 + LibreHardwareMonitorLib/Hardware/IElement.cs | 13 +- LibreHardwareMonitorLib/Hardware/IGroup.cs | 13 + LibreHardwareMonitorLib/Hardware/IHardware.cs | 38 +++ LibreHardwareMonitorLib/Hardware/ISensor.cs | 48 +++ LibreHardwareMonitorLib/Hardware/IVisitor.cs | 3 + LibreHardwareMonitorLib/Hardware/SMBios.cs | 274 +++++++++++++++--- 8 files changed, 413 insertions(+), 38 deletions(-) diff --git a/LibreHardwareMonitorLib/Hardware/Computer.cs b/LibreHardwareMonitorLib/Hardware/Computer.cs index c435a16..93e0120 100644 --- a/LibreHardwareMonitorLib/Hardware/Computer.cs +++ b/LibreHardwareMonitorLib/Hardware/Computer.cs @@ -22,6 +22,9 @@ using LibreHardwareMonitor.Hardware.Storage; namespace LibreHardwareMonitor.Hardware { + /// + /// Stores all hardware groups and decides which devices should be enabled and updated. + /// public class Computer : IComputer { public event HardwareEventHandler HardwareAdded; @@ -50,6 +53,11 @@ namespace LibreHardwareMonitor.Hardware _settings = settings ?? new Settings(); } + /// + /// Gets a list of all known after calling . + /// Can be updated by . + /// + /// List of all enabled devices. public IList Hardware { get @@ -66,6 +74,10 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Gets or sets a value indicating whether collecting information about devices should be enabled and updated. + /// + /// if a given category of devices is already enabled. public bool IsCpuEnabled { get { return _cpuEnabled; } @@ -83,6 +95,18 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Gets or sets a value indicating whether collecting information about: + /// + /// + /// + /// + /// + /// + /// + /// devices should be enabled and updated. + /// + /// if a given category of devices is already enabled. public bool IsControllerEnabled { get { return _controllerEnabled; } @@ -112,6 +136,10 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Gets or sets a value indicating whether collecting information about or devices should be enabled and updated. + /// + /// if a given category of devices is already enabled. public bool IsGpuEnabled { get { return _gpuEnabled; } @@ -135,6 +163,10 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Gets or sets a value indicating whether collecting information about devices should be enabled and updated. + /// + /// if a given category of devices is already enabled. public bool IsMemoryEnabled { get { return _memoryEnabled; } @@ -152,6 +184,10 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Gets or sets a value indicating whether collecting information about devices should be enabled and updated. + /// + /// if a given category of devices is already enabled. public bool IsMotherboardEnabled { get { return _motherboardEnabled; } @@ -169,6 +205,10 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Gets or sets a value indicating whether collecting information about devices should be enabled and updated. + /// + /// if a given category of devices is already enabled. public bool IsNetworkEnabled { get { return _networkEnabled; } @@ -186,6 +226,10 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Gets or sets a value indicating whether collecting information about devices should be enabled and updated. + /// + /// if a given category of devices is already enabled. public bool IsStorageEnabled { get { return _storageEnabled; } @@ -203,6 +247,10 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Generates full LibreHardwareMonitor report for devices that have been enabled. + /// + /// A formatted text string with library, OS and hardware information. public string GetReport() { lock (_lock) @@ -279,6 +327,10 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Triggers the method for the given observer. + /// + /// Observer who call to devices. public void Accept(IVisitor visitor) { if (visitor == null) @@ -288,6 +340,10 @@ namespace LibreHardwareMonitor.Hardware visitor.VisitComputer(this); } + /// + /// Triggers the method with the given visitor for each device in each group. + /// + /// Observer who call to devices. public void Traverse(IVisitor visitor) { lock (_lock) @@ -384,6 +440,9 @@ namespace LibreHardwareMonitor.Hardware Remove(group); } + /// + /// If hasn't been opened before, opens , , and triggers the private method depending on which categories are enabled. + /// public void Open() { if (_open) diff --git a/LibreHardwareMonitorLib/Hardware/IComputer.cs b/LibreHardwareMonitorLib/Hardware/IComputer.cs index 07abe71..2696f29 100644 --- a/LibreHardwareMonitorLib/Hardware/IComputer.cs +++ b/LibreHardwareMonitorLib/Hardware/IComputer.cs @@ -10,6 +10,9 @@ namespace LibreHardwareMonitor.Hardware { public delegate void HardwareEventHandler(IHardware hardware); + /// + /// Basic abstract with methods for the class which can store all hardware and decides which devices are to be checked and updated. + /// public interface IComputer : IElement { bool IsCpuEnabled { get; } diff --git a/LibreHardwareMonitorLib/Hardware/IElement.cs b/LibreHardwareMonitorLib/Hardware/IElement.cs index 552be59..34d131f 100644 --- a/LibreHardwareMonitorLib/Hardware/IElement.cs +++ b/LibreHardwareMonitorLib/Hardware/IElement.cs @@ -6,12 +6,21 @@ namespace LibreHardwareMonitor.Hardware { + /// + /// Abstract parent with logic for the abstract class that stores data. + /// public interface IElement { - // accept visitor on this element + /// + /// Accepts the observer for this instance. + /// + /// Computer observer making the calls. void Accept(IVisitor visitor); - // call accept(visitor) on all child elements (called only from visitors) + /// + /// Call the method for all child instances (called only from visitors). + /// + /// Computer observer making the calls. void Traverse(IVisitor visitor); } } diff --git a/LibreHardwareMonitorLib/Hardware/IGroup.cs b/LibreHardwareMonitorLib/Hardware/IGroup.cs index ac7e873..dbcc4bd 100644 --- a/LibreHardwareMonitorLib/Hardware/IGroup.cs +++ b/LibreHardwareMonitorLib/Hardware/IGroup.cs @@ -8,12 +8,25 @@ using System.Collections.Generic; namespace LibreHardwareMonitor.Hardware { + /// + /// A group of devices from one category in one list. + /// internal interface IGroup { + /// + /// Gets a list that stores information about in a given group. + /// IReadOnlyList Hardware { get; } + /// + /// Report containing most of the known information about all in this . + /// + /// A formatted text string with hardware information. string GetReport(); + /// + /// Stop updating this group in the future. + /// void Close(); } } diff --git a/LibreHardwareMonitorLib/Hardware/IHardware.cs b/LibreHardwareMonitorLib/Hardware/IHardware.cs index 6faf48e..5f09e59 100644 --- a/LibreHardwareMonitorLib/Hardware/IHardware.cs +++ b/LibreHardwareMonitorLib/Hardware/IHardware.cs @@ -8,6 +8,9 @@ namespace LibreHardwareMonitor.Hardware { public delegate void SensorEventHandler(ISensor sensor); + /// + /// Reflects what category the device is. + /// public enum HardwareType { Motherboard, @@ -22,26 +25,61 @@ namespace LibreHardwareMonitor.Hardware EmbeddedController } + /// + /// An abstract object that stores information about a device. All sensors are available as an array of . + /// public interface IHardware : IElement { + /// + /// + /// HardwareType HardwareType { get; } + /// + /// Gets unique hardware identifier obtained from the computer. + /// Identifier Identifier { get; } + /// + /// Gets or sets device name. + /// string Name { get; set; } + /// + /// Gets the device that is the parent of the current hardware. For example, the motherboard is the parent of SuperIO. + /// IHardware Parent { get; } + /// + /// Gets an array of all sensors such as temperature, clocks, load etc. + /// ISensor[] Sensors { get; } + /// + /// Gets child devices, e.g. SuperIO of the motherboard. + /// IHardware[] SubHardware { get; } + /// + /// Report containing most of the known information about the current device. + /// + /// A formatted text string with hardware information. string GetReport(); + /// + /// Refreshes the information stored in array. + /// void Update(); + /// + /// An that will be triggered when a new sensor appears. + /// event SensorEventHandler SensorAdded; + /// + /// An that will be triggered when one of the sensors is removed. + /// + /// event SensorEventHandler SensorRemoved; } } diff --git a/LibreHardwareMonitorLib/Hardware/ISensor.cs b/LibreHardwareMonitorLib/Hardware/ISensor.cs index 2fe2b32..48b903a 100644 --- a/LibreHardwareMonitorLib/Hardware/ISensor.cs +++ b/LibreHardwareMonitorLib/Hardware/ISensor.cs @@ -9,6 +9,9 @@ using System.Collections.Generic; namespace LibreHardwareMonitor.Hardware { + /// + /// Category of what type the selected sensor is. + /// public enum SensorType { Voltage, // V @@ -28,49 +31,94 @@ namespace LibreHardwareMonitor.Hardware Throughput // B/s } + /// + /// Stores the readed value and the time in which it was recorded. + /// public struct SensorValue { + /// of the sensor. + /// The time code during which the was recorded. public SensorValue(float value, DateTime time) { Value = value; Time = time; } + /// + /// Gets the value of the sensor + /// public float Value { get; } + /// + /// Gets the time code during which the was recorded. + /// public DateTime Time { get; } } + /// + /// Stores information about the readed values and the time in which they were collected. + /// public interface ISensor : IElement { IControl Control { get; } + /// + /// + /// IHardware Hardware { get; } Identifier Identifier { get; } + /// + /// Gets the unique identifier of this sensor for a given . + /// int Index { get; } bool IsDefaultHidden { get; } + /// + /// Gets a maximum value recorded for the given sensor. + /// float? Max { get; } + /// + /// Gets a minimum value recorded for the given sensor. + /// float? Min { get; } + /// + /// Gets or sets a sensor name. + /// By default determined by the library. + /// string Name { get; set; } IReadOnlyList Parameters { get; } + /// + /// + /// SensorType SensorType { get; } + /// + /// Gets the last recorded value for the given sensor. + /// float? Value { get; } + /// + /// Gets a list of recorded values for the given sensor. + /// IEnumerable Values { get; } TimeSpan ValuesTimeWindow { get; set; } + /// + /// Resets a value stored in . + /// void ResetMin(); + /// + /// Resets a value stored in . + /// void ResetMax(); } } diff --git a/LibreHardwareMonitorLib/Hardware/IVisitor.cs b/LibreHardwareMonitorLib/Hardware/IVisitor.cs index 1cc6d7a..872fad5 100644 --- a/LibreHardwareMonitorLib/Hardware/IVisitor.cs +++ b/LibreHardwareMonitorLib/Hardware/IVisitor.cs @@ -6,6 +6,9 @@ namespace LibreHardwareMonitor.Hardware { + /// + /// Base interface for creating observers who call to devices. + /// public interface IVisitor { void VisitComputer(IComputer computer); diff --git a/LibreHardwareMonitorLib/Hardware/SMBios.cs b/LibreHardwareMonitorLib/Hardware/SMBios.cs index 17a3807..89e9f68 100644 --- a/LibreHardwareMonitorLib/Hardware/SMBios.cs +++ b/LibreHardwareMonitorLib/Hardware/SMBios.cs @@ -13,10 +13,9 @@ using System.Text; namespace LibreHardwareMonitor.Hardware { - /* - * DSP0134 System Management BIOS (SMBIOS) Reference Specification v.3.3.0 - * Chapter 7.4.3 - */ + /// + /// Chassis security status based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.4.3. + /// public enum ChassisSecurityStatus { Other = 1, @@ -26,10 +25,9 @@ namespace LibreHardwareMonitor.Hardware ExternalInterfaceEnabled } - /* - * DSP0134 System Management BIOS (SMBIOS) Reference Specification v.3.3.0 - * Chapter 7.4.2 - */ + /// + /// Chassis state based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.4.2. + /// public enum ChassisStates { Other = 1, @@ -40,10 +38,9 @@ namespace LibreHardwareMonitor.Hardware NonRecoverable } - /* - * DSP0134 System Management BIOS (SMBIOS) Reference Specification v.3.3.0 - * Chapter 7.4.1 - */ + /// + /// Chassis type based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.4.1. + /// public enum ChassisType { Other = 1, @@ -84,10 +81,9 @@ namespace LibreHardwareMonitor.Hardware StickPC } - /* - * DSP0134 System Management BIOS (SMBIOS) Reference Specification v.3.3.0 - * Chapter 7.5.2 - */ + /// + /// Processor family based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.5.2. + /// [SuppressMessage("ReSharper", "InconsistentNaming")] [SuppressMessage("ReSharper", "IdentifierTypo")] public enum ProcessorFamily @@ -305,10 +301,9 @@ namespace LibreHardwareMonitor.Hardware VideoProcessor } - /* - * DSP0134 System Management BIOS (SMBIOS) Reference Specification v.3.3.0 - * Chapter 7.5.1 - */ + /// + /// Processor type based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.5.1. + /// public enum ProcessorType { Other = 1, @@ -319,10 +314,9 @@ namespace LibreHardwareMonitor.Hardware VideoProcessor } - /* - * DSP0134 System Management BIOS (SMBIOS) Reference Specification v.3.3.0 - * Chapter 7.5.5 - */ + /// + /// Processor socket based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.5.5. + /// public enum ProcessorSocket { Other = 1, @@ -382,6 +376,9 @@ namespace LibreHardwareMonitor.Hardware Lga4189 } + /// + /// System wake-up type based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.2.2. + /// public enum SystemWakeUp { Reserved, @@ -395,18 +392,9 @@ namespace LibreHardwareMonitor.Hardware ACPowerRestored } - public enum CacheDesignation - { - Other, - L1, - L2, - L3 - } - - /* - * DSP0134 System Management BIOS (SMBIOS) Reference Specification v.3.4.0 - * Chapter 7.8.5 - */ + /// + /// Cache associativity based on DMTF SMBIOS Reference Specification v.3.3.0, Chapter 7.8.5. + /// public enum CacheAssociativity { Other = 1, @@ -425,6 +413,17 @@ namespace LibreHardwareMonitor.Hardware _20Way, } + /// + /// Processor cache level. + /// + public enum CacheDesignation + { + Other, + L1, + L2, + L3 + } + public class InformationBase { private readonly byte[] _data; @@ -470,6 +469,9 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Motherboard BIOS information obtained from the SMBIOS table. + /// public class BiosInformation : InformationBase { internal BiosInformation(string vendor, string version, string date = null, ulong? size = null) : base(0x00, 0, null, null) @@ -488,12 +490,24 @@ namespace LibreHardwareMonitor.Hardware Size = CalculateBiosRomSize(); } + /// + /// Gets the BIOS release date. + /// public DateTime? Date { get; } + /// + /// Gets the size of the physical device containing the BIOS. + /// public ulong? Size { get; } + /// + /// Gets the string number of the BIOS Vendor’s Name. + /// public string Vendor { get; } + /// + /// Gets the string number of the BIOS Version. This value is a free-form string that may contain Core and OEM version information. + /// public string Version { get; } private ulong? CalculateBiosRomSize() @@ -539,6 +553,9 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// System information obtained from the SMBIOS table. + /// public class SystemInformation : InformationBase { internal SystemInformation @@ -562,19 +579,41 @@ namespace LibreHardwareMonitor.Hardware WakeUp = (SystemWakeUp)GetByte(0x18); } + /// + /// Gets the family associated with system. + /// This text string identifies the family to which a particular computer belongs. A family refers to a set of computers that are similar but not identical from a hardware or software point of view. Typically, a family is composed of different computer models, which have different configurations and pricing points. Computers in the same family often have similar branding and cosmetic features. + /// public string Family { get; } + /// + /// Gets the manufacturer name associated with system. + /// public string ManufacturerName { get; } + /// + /// Gets the product name associated with system. + /// public string ProductName { get; } + /// + /// Gets the serial number string associated with system. + /// public string SerialNumber { get; } + /// + /// Gets the version string associated with system. + /// public string Version { get; } + /// + /// Gets + /// public SystemWakeUp WakeUp { get; } } + /// + /// Chassis information obtained from the SMBIOS table. + /// public class ChassisInformation : InformationBase { internal ChassisInformation(byte type, ushort handle, byte[] data, string[] strings) : base(type, handle, data, strings) @@ -594,33 +633,76 @@ namespace LibreHardwareMonitor.Hardware SecurityStatus = (ChassisSecurityStatus)GetByte(0x0C); } + /// + /// Gets the asset tag associated with the enclosure or chassis. + /// public string AssetTag { get; } + /// + /// Gets + /// public ChassisStates BootUpState { get; } + /// + /// Gets + /// public ChassisType ChassisType { get; } + /// + /// Gets or sets the chassis lock. + /// + /// Chassis lock is present if . Otherwise, either a lock is not present or it is unknown if the enclosure has a lock. public bool LockDetected { get; set; } + /// + /// Gets the string describing the chassis or enclosure manufacturer name. + /// public string ManufacturerName { get; } + /// + /// Gets the number of power cords associated with the enclosure or chassis. + /// public int PowerCords { get; } + /// + /// Gets the state of the enclosure’s power supply (or supplies) when last booted. + /// public ChassisStates PowerSupplyState { get; } + /// + /// Gets the height of the enclosure, in 'U's. A U is a standard unit of measure for the height of a rack or rack-mountable component and is equal to 1.75 inches or 4.445 cm. A value of 0 indicates that the enclosure height is unspecified. + /// public int RackHeight { get; } + /// + /// Gets the physical security status of the enclosure when last booted. + /// public ChassisSecurityStatus SecurityStatus { get; set; } + /// + /// Gets the string describing the chassis or enclosure serial number. + /// public string SerialNumber { get; } + /// + /// Gets the string describing the chassis or enclosure SKU number. + /// public string SKU { get; } + /// + /// Gets the thermal state of the enclosure when last booted. + /// public ChassisStates ThermalState { get; } + /// + /// Gets the number of null-terminated string representing the chassis or enclosure version. + /// public string Version { get; } } + /// + /// Motherboard information obtained from the SMBIOS table. + /// public class BaseBoardInformation : InformationBase { internal BaseBoardInformation(string manufacturerName, string productName, string version, string serialNumber) : base(0x02, 0, null, null) @@ -639,15 +721,30 @@ namespace LibreHardwareMonitor.Hardware SerialNumber = GetString(0x07).Trim(); } + /// + /// Gets the value that represents the manufacturer's name. + /// public string ManufacturerName { get; } + /// + /// Gets the value that represents the motherboard's name. + /// public string ProductName { get; } + /// + /// Gets the value that represents the motherboard's serial number. + /// public string SerialNumber { get; } + /// + /// Gets the value that represents the motherboard's revision number. + /// public string Version { get; } } + /// + /// Processor information obtained from the SMBIOS table. + /// public class ProcessorInformation : InformationBase { internal ProcessorInformation(byte type, ushort handle, byte[] data, string[] strings) : base(type, handle, data, strings) @@ -670,33 +767,76 @@ namespace LibreHardwareMonitor.Hardware Family = (ProcessorFamily)(family == 254 ? GetWord(0x28) : family); } + /// + /// Gets the value that represents the number of cores per processor socket. + /// public int CoreCount { get; } + /// + /// Gets the value that represents the number of enabled cores per processor socket. + /// public int CoreEnabled { get; } + /// + /// Gets the external Clock Frequency, in MHz. If the value is unknown, the field is set to 0. + /// public int ExternalClock { get; } + /// + /// Gets the value that represents the maximum processor speed (in MHz) supported by the system for this processor socket. + /// public int MaxSpeed { get; } + /// + /// Gets the value that represents the current processor speed (in MHz). + /// public int CurrentSpeed { get; } + /// + /// Gets the value that represents the string number for the serial number of this processor. + /// This value is set by the manufacturer and normally not changeable. + /// public string Serial { get; } + /// + /// Gets + /// public ProcessorType ProcessorType { get; } + /// + /// Gets + /// public ProcessorSocket Socket { get; } + /// + /// Gets + /// public ProcessorFamily Family { get; } + /// + /// Gets the string number for Reference Designation. + /// public string SocketDesignation { get; } + /// + /// Gets the string number of Processor Manufacturer. + /// public string ManufacturerName { get; } + /// + /// Gets the value that represents the number of threads per processor socket. + /// public int ThreadCount { get; } + /// + /// Gets the value that represents the string number describing the Processor. + /// public string Version { get; } } + /// + /// Processor cache information obtained from the SMBIOS table. + /// public class ProcessorCache : InformationBase { internal ProcessorCache(byte type, ushort handle, byte[] data, string[] strings) : base(type, handle, data, strings) @@ -720,13 +860,25 @@ namespace LibreHardwareMonitor.Hardware return CacheDesignation.Other; } + /// + /// Gets + /// public CacheDesignation Designation { get; } + /// + /// Gets + /// public CacheAssociativity Associativity { get; } + /// + /// Gets the value that represents the installed cache size. + /// public int Size { get; } } + /// + /// Memory information obtained from the SMBIOS table. + /// public class MemoryDevice : InformationBase { internal MemoryDevice(byte type, ushort handle, byte[] data, string[] strings) : base(type, handle, data, strings) @@ -743,20 +895,45 @@ namespace LibreHardwareMonitor.Hardware Size += GetWord(0x1C); } + /// + /// Gets the string number of the string that identifies the physically labeled bank where the memory device is located. + /// public string BankLocator { get; } + /// + /// Gets the string number of the string that identifies the physically-labeled socket or board position where the memory device is located. + /// public string DeviceLocator { get; } + /// + /// Gets the string number for the manufacturer of this memory device. + /// public string ManufacturerName { get; } + /// + /// Gets the string number for the part number of this memory device. + /// public string PartNumber { get; } + /// + /// Gets the string number for the serial number of this memory device. + /// public string SerialNumber { get; } + /// + /// Gets the the value that identifies the maximum capable speed of the device, in megatransfers per second (MT/s). + /// public int Speed { get; } + + /// + /// Gets the size of the memory device. If the value is 0, no memory device is installed in the socket. + /// public int Size { get; } } + /// + /// Reads and processes information encoded in an SMBIOS table. + /// public class SMBios { private readonly byte[] _raw; @@ -887,18 +1064,39 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Gets + /// public BiosInformation Bios { get; } + /// + /// Gets + /// public BaseBoardInformation Board { get; } + /// + /// Gets + /// public ChassisInformation Chassis { get; } + /// + /// Gets + /// public MemoryDevice[] MemoryDevices { get; } + /// + /// Gets + /// public ProcessorCache[] ProcessorCaches { get; } + /// + /// Gets + /// public ProcessorInformation Processor { get; } + /// + /// Gets + /// public SystemInformation System { get; } private static string ReadSysFs(string path) @@ -919,6 +1117,10 @@ namespace LibreHardwareMonitor.Hardware } } + /// + /// Report containing most of the information that could be read from the SMBIOS table. + /// + /// A formatted text string with computer information and the entire SMBIOS table. public string GetReport() { StringBuilder r = new StringBuilder();