[reactos] 15/15: [COMPBATT] Document COMPBATT_BATTERY_DATA and COMPBATT_DEVICE_EXTENSION structures

[George Bișoc]

https://git.reactos.org/?p=reactos.git;a=commitdiff;h=13b394c1a7e0df384443a…

commit 13b394c1a7e0df384443a7c1caacf95ec13858a9
Author:     George Bișoc <george.bisoc(a)reactos.org>
AuthorDate: Mon Dec 16 17:20:33 2024 +0100
Commit:     George Bișoc <george.bisoc(a)reactos.org>
CommitDate: Wed Jan 8 23:20:09 2025 +0100

    [COMPBATT] Document COMPBATT_BATTERY_DATA and COMPBATT_DEVICE_EXTENSION structures
    
    CORE-18969
    CORE-19452
    CORE-19888
---
 drivers/bus/acpi/compbatt/compbatt.h | 92 ++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/drivers/bus/acpi/compbatt/compbatt.h b/drivers/bus/acpi/compbatt/compbatt.h
index 66307defbc4..58f812c5fd7 100644
--- a/drivers/bus/acpi/compbatt/compbatt.h
+++ b/drivers/bus/acpi/compbatt/compbatt.h
@@ -78,24 +78,73 @@
 //
 typedef struct _COMPBATT_BATTERY_DATA
 {
+    /* The linked battery with the Composite Battery */
     LIST_ENTRY BatteryLink;
+
+    /* I/O remove lock which protects the battery from being removed */
     IO_REMOVE_LOCK RemoveLock;
+
+    /*
+     * The associated device object (usually CMBATT) and the I/O battery packet
+     * which is used to transport and gather battery data.
+     */
     PDEVICE_OBJECT DeviceObject;
     PIRP Irp;
+
+    /*
+     * The Executive work item, which serves as a worker item for the
+     * IRP battery monitor worker.
+     */
     WORK_QUEUE_ITEM WorkItem;
+
+    /*
+     * Execution state mode of the individual battery. Only two modes are valid:
+     *
+     * COMPBATT_QUERY_TAG - The battery is currently waiting for a tag to get assigned;
+     * COMPBATT_READ_STATUS - The battery is querying battery status.
+     */
     UCHAR Mode;
+
+    /*
+     * The battery wait configuration settings, set up by the SetStatusNotify method.
+     * These values are used to instruct CMBATT when the battery status should be
retrieved.
+     */
     BATTERY_WAIT_STATUS WaitStatus;
+
+    /*
+     * A union that serves as the buffer which holds battery monitor IRP data,
specifically
+     * managed by CompBattMonitorIrpCompleteWorker, to avoid allocating separate memory
pools.
+     */
     union
     {
         BATTERY_WAIT_STATUS WorkerWaitStatus;
         BATTERY_STATUS WorkerStatus;
         ULONG WorkerTag;
     } WorkerBuffer;
+
+    /* The ID of the battery that associates the identification of this battery */
     ULONG Tag;
+
+    /*
+     * The battery flags that govern the behavior of the battery. The valid flags are:
+     *
+     * COMPBATT_BATTERY_INFORMATION_PRESENT - The static battery information ha been
+     * queried. Re-querying such information is not needed.
+     *
+     * COMPBATT_STATUS_NOTIFY_SET - The current notification wait settings are valid.
+     *
+     * COMPBATT_TAG_ASSIGNED - The battery has a tag assigned and it can be read.
+     */
     ULONG Flags;
+
+    /* The static battery information and battery status */
     BATTERY_INFORMATION BatteryInformation;
     BATTERY_STATUS BatteryStatus;
+
+    /* The interrupt time of which the battery status was last read */
     ULONGLONG InterruptTime;
+
+    /* A uniquely given name of the battery that associates it */
     UNICODE_STRING BatteryName;
 } COMPBATT_BATTERY_DATA, *PCOMPBATT_BATTERY_DATA;
 
@@ -104,18 +153,61 @@ typedef struct _COMPBATT_BATTERY_DATA
 //
 typedef struct _COMPBATT_DEVICE_EXTENSION
 {
+    /*
+     * The class data initialized and used by Battery Class. It contains information
+     * such as miniport data used for registration and communication between the
+     * Composite Battery and Battery Class, wait and context events, etc.
+     */
     PVOID ClassData;
+
+    /*
+     * The successor computed tag. This field is used when there are more upcoming
+     * batteries to be connected with the Composite Battery, of which the tag is
+     * incremented by 1 by each new battery that is connected.
+     */
     ULONG NextTag;
+
+    /* A list of linked batteries connected with the Composite Battery */
     LIST_ENTRY BatteryList;
+
+    /* A mutex lock which ensures proper synchronization of Composite Battery operations
*/
     FAST_MUTEX Lock;
+
+    /* The ID of the Composite Battery */
     ULONG Tag;
+
+    /*
+     * The battery flags that govern the behavior of the battery. The valid flags are:
+     *
+     * COMPBATT_BATTERY_INFORMATION_PRESENT - The static battery information has been
+     * queried. Re-querying such information is not needed.
+     *
+     * COMPBATT_STATUS_NOTIFY_SET - The current notification wait settings are valid.
+     *
+     * COMPBATT_TAG_ASSIGNED - The battery has a tag assigned and it can be read.
+     */
     ULONG Flags;
+
+    /*
+     * The Composite Battery static information, status and wait status settings.
+     * Note that both the battery information and status are combined, based upon
+     * the individual information and status of each linked battery.
+     */
     BATTERY_INFORMATION BatteryInformation;
     BATTERY_STATUS BatteryStatus;
     BATTERY_WAIT_STATUS WaitNotifyStatus;
+
+    /* The interrupt time of which the battery status was last read */
     ULONGLONG InterruptTime;
+
+    /*
+     * The physical device object that associates the Composite Battery and
+     * the attached device, typically the ACPI driver.
+     */
     PDEVICE_OBJECT AttachedDevice;
     PDEVICE_OBJECT DeviceObject;
+
+    /* The notification entry that identifies the registered I/O PnP notification */
     PVOID NotificationEntry;
 } COMPBATT_DEVICE_EXTENSION, *PCOMPBATT_DEVICE_EXTENSION;