[reactos] 01/15: [COMPBATT] Prepare the base foundation for the header file

[George Bișoc]

https://git.reactos.org/?p=reactos.git;a=commitdiff;h=04cd478035a1d1cab2d1d…

commit 04cd478035a1d1cab2d1dde391f8ffc633bde6ec
Author:     George Bișoc <george.bisoc(a)reactos.org>
AuthorDate: Sat Dec 14 20:36:09 2024 +0100
Commit:     George Bișoc <george.bisoc(a)reactos.org>
CommitDate: Wed Jan 8 23:19:56 2025 +0100

    [COMPBATT] Prepare the base foundation for the header file
    
    - Introduce some new constructs
    - Annotate the function prototypes with SAL2
    - Re-structure & remove some useless fields in COMPBATT_DEVICE_EXTENSION and
COMPBATT_BATTERY_DATA
---
 drivers/bus/acpi/compbatt/compbatt.h | 175 +++++++++++++++++++++++++----------
 1 file changed, 127 insertions(+), 48 deletions(-)

diff --git a/drivers/bus/acpi/compbatt/compbatt.h b/drivers/bus/acpi/compbatt/compbatt.h
index 950e5a5f7dd..1b8c1fb49d1 100644
--- a/drivers/bus/acpi/compbatt/compbatt.h
+++ b/drivers/bus/acpi/compbatt/compbatt.h
@@ -1,20 +1,81 @@
 /*
- * PROJECT:         ReactOS Composite Battery Driver
- * LICENSE:         BSD - See COPYING.ARM in the top level directory
- * FILE:            boot/drivers/bus/acpi/compbatt/compbatt.h
- * PURPOSE:         Main Header File
- * PROGRAMMERS:     ReactOS Portable Systems Group
+ * PROJECT:     ReactOS Composite Battery Driver
+ * LICENSE:     BSD - See COPYING.ARM in the top level directory
+ * PURPOSE:     Composite battery main header file
+ * COPYRIGHT:   Copyright 2010 ReactOS Portable Systems Group
+ *              Copyright 2024 George Bișoc <george.bisoc(a)reactos.org>
  */
 
+/* INCLUDES *******************************************************************/
+
 #ifndef _COMPBATT_PCH_
 #define _COMPBATT_PCH_
 
 #include <wdm.h>
 #include <batclass.h>
 
+/* DEFINES ********************************************************************/
+
+//
+// I/O remove lock allocate tag
+//
+#define COMPBATT_TAG                            'aBoC'
+
+//
+// Composite battery flags
+//
 #define COMPBATT_BATTERY_INFORMATION_PRESENT    0x04
+#define COMPBATT_STATUS_NOTIFY_SET              0x10
 #define COMPBATT_TAG_ASSIGNED                   0x80
 
+//
+// IRP complete worker mode states
+//
+#define COMPBATT_QUERY_TAG                      1
+#define COMPBATT_READ_STATUS                    2
+
+//
+// Low/High capacity wait constants
+//
+#define COMPBATT_WAIT_MIN_LOW_CAPACITY          0
+#define COMPBATT_WAIT_MAX_HIGH_CAPACITY         0x7FFFFFFF
+
+//
+// One hour in seconds, used to calculate the total rate of each battery for time
estimation
+//
+#define COMPBATT_ATRATE_HOUR_IN_SECS            3600
+
+//
+// Time constant of which the battery status data is considered fresh (50000000 * 100ns
== 5s)
+//
+#define COMPBATT_FRESH_STATUS_TIME              50000000
+
+//
+// Macro that calculates the delta of a battery's capacity
+//
+#define COMPUTE_BATT_CAP_DELTA(LowDiff, Batt, TotalRate)            \
+    ((ULONG)(((LONGLONG)LowDiff * (Batt)->BatteryStatus.Rate) / TotalRate))
+
+//
+// Macro that calculates the "At Rate" time drain of the battery
+//
+#define COMPUTE_ATRATE_DRAIN(Batt, Time)                            \
+    ((LONG)((Batt)->BatteryStatus.Capacity) * COMPBATT_ATRATE_HOUR_IN_SECS / Time)
+
+//
+// Composite battery debug levels
+//
+#define COMPBATT_DEBUG_INFO                     0x1
+#define COMPBATT_DEBUG_TRACE                    0x2
+#define COMPBATT_DEBUG_WARN                     0x4
+#define COMPBATT_DEBUG_ERR                      0x10
+#define COMPBATT_DEBUG_ALL_LEVELS               (COMPBATT_DEBUG_INFO |
COMPBATT_DEBUG_TRACE | COMPBATT_DEBUG_WARN | COMPBATT_DEBUG_ERR)
+
+/* STRUCTURES *****************************************************************/
+
+//
+// Individual ACPI battery data
+//
 typedef struct _COMPBATT_BATTERY_DATA
 {
     LIST_ENTRY BatteryLink;
@@ -22,13 +83,14 @@ typedef struct _COMPBATT_BATTERY_DATA
     PDEVICE_OBJECT DeviceObject;
     PIRP Irp;
     WORK_QUEUE_ITEM WorkItem;
-    BOOLEAN WaitFlag;
+    UCHAR Mode;
     BATTERY_WAIT_STATUS WaitStatus;
     union
     {
         BATTERY_WAIT_STATUS WorkerWaitStatus;
         BATTERY_STATUS WorkerStatus;
-    };
+        ULONG WorkerTag;
+    } WorkerBuffer;
     ULONG Tag;
     ULONG Flags;
     BATTERY_INFORMATION BatteryInformation;
@@ -37,6 +99,9 @@ typedef struct _COMPBATT_BATTERY_DATA
     UNICODE_STRING BatteryName;
 } COMPBATT_BATTERY_DATA, *PCOMPBATT_BATTERY_DATA;
 
+//
+// Composite battery device extension data
+//
 typedef struct _COMPBATT_DEVICE_EXTENSION
 {
     PVOID ClassData;
@@ -47,110 +112,124 @@ typedef struct _COMPBATT_DEVICE_EXTENSION
     ULONG Flags;
     BATTERY_INFORMATION BatteryInformation;
     BATTERY_STATUS BatteryStatus;
+    BATTERY_WAIT_STATUS WaitNotifyStatus;
     ULONGLONG InterruptTime;
-    POWER_STATE PowerState;
-    ULONG LowCapacity;
-    ULONG HighCapacity;
     PDEVICE_OBJECT AttachedDevice;
     PDEVICE_OBJECT DeviceObject;
     PVOID NotificationEntry;
 } COMPBATT_DEVICE_EXTENSION, *PCOMPBATT_DEVICE_EXTENSION;
 
+/* PROTOTYPES *****************************************************************/
+
 NTSTATUS
 NTAPI
 CompBattAddDevice(
-    IN PDRIVER_OBJECT DriverObject,
-    IN PDEVICE_OBJECT PdoDeviceObject
+    _In_ PDRIVER_OBJECT DriverObject,
+    _In_ PDEVICE_OBJECT PdoDeviceObject
 );
 
 NTSTATUS
 NTAPI
 CompBattPowerDispatch(
-    IN PDEVICE_OBJECT DeviceObject,
-    IN PIRP Irp
+    _In_ PDEVICE_OBJECT DeviceObject,
+    _In_ PIRP Irp
 );
 
 NTSTATUS
 NTAPI
 CompBattPnpDispatch(
-    IN PDEVICE_OBJECT DeviceObject,
-    IN PIRP Irp
+    _In_ PDEVICE_OBJECT DeviceObject,
+    _In_ PIRP Irp
 );
 
 NTSTATUS
 NTAPI
 CompBattQueryInformation(
-    IN PCOMPBATT_DEVICE_EXTENSION FdoExtension,
-    IN ULONG Tag,
-    IN BATTERY_QUERY_INFORMATION_LEVEL InfoLevel,
-    IN OPTIONAL LONG AtRate,
-    IN PVOID Buffer,
-    IN ULONG BufferLength,
-    OUT PULONG ReturnedLength
+    _In_ PCOMPBATT_DEVICE_EXTENSION FdoExtension,
+    _In_ ULONG Tag,
+    _In_ BATTERY_QUERY_INFORMATION_LEVEL InfoLevel,
+    _In_opt_ LONG AtRate,
+    _In_ PVOID Buffer,
+    _In_ ULONG BufferLength,
+    _Out_ PULONG ReturnedLength
 );
 
 NTSTATUS
 NTAPI
 CompBattQueryStatus(
-    IN PCOMPBATT_DEVICE_EXTENSION DeviceExtension,
-    IN ULONG Tag,
-    IN PBATTERY_STATUS BatteryStatus
+    _In_ PCOMPBATT_DEVICE_EXTENSION DeviceExtension,
+    _In_ ULONG Tag,
+    _Out_ PBATTERY_STATUS BatteryStatus
+);
+
+NTSTATUS
+NTAPI
+CompBattGetEstimatedTime(
+    _Out_ PULONG Time,
+    _In_ PCOMPBATT_DEVICE_EXTENSION DeviceExtension
 );
 
 NTSTATUS
 NTAPI
 CompBattSetStatusNotify(
-    IN PCOMPBATT_DEVICE_EXTENSION DeviceExtension,
-    IN ULONG BatteryTag,
-    IN PBATTERY_NOTIFY BatteryNotify
+    _In_ PCOMPBATT_DEVICE_EXTENSION DeviceExtension,
+    _In_ ULONG BatteryTag,
+    _In_ PBATTERY_NOTIFY BatteryNotify
 );
 
 NTSTATUS
 NTAPI
 CompBattDisableStatusNotify(
-    IN PCOMPBATT_DEVICE_EXTENSION DeviceExtension
+    _In_ PCOMPBATT_DEVICE_EXTENSION DeviceExtension
 );
 
 NTSTATUS
 NTAPI
 CompBattQueryTag(
-    IN PCOMPBATT_DEVICE_EXTENSION DeviceExtension,
-    OUT PULONG Tag
+    _In_ PCOMPBATT_DEVICE_EXTENSION DeviceExtension,
+    _Out_ PULONG Tag
 );
 
 NTSTATUS
 NTAPI
 CompBattMonitorIrpComplete(
-    IN PDEVICE_OBJECT DeviceObject,
-    IN PIRP Irp,
-    IN PKEVENT Event
+    _In_ PDEVICE_OBJECT DeviceObject,
+    _In_ PIRP Irp,
+    _In_ PVOID Context
 );
 
-NTSTATUS
+VOID
 NTAPI
 CompBattMonitorIrpCompleteWorker(
-    IN PCOMPBATT_BATTERY_DATA BatteryData
+    _In_ PCOMPBATT_BATTERY_DATA BatteryData
 );
 
 NTSTATUS
 NTAPI
 CompBattGetDeviceObjectPointer(
-    IN PUNICODE_STRING DeviceName,
-    IN ACCESS_MASK DesiredAccess,
-    OUT PFILE_OBJECT *FileObject,
-    OUT PDEVICE_OBJECT *DeviceObject
+    _In_ PUNICODE_STRING DeviceName,
+    _In_ ACCESS_MASK DesiredAccess,
+    _Out_ PFILE_OBJECT *FileObject,
+    _Out_ PDEVICE_OBJECT *DeviceObject
 );
 
 NTSTATUS
 NTAPI
 BatteryIoctl(
-    IN ULONG IoControlCode,
-    IN PDEVICE_OBJECT DeviceObject,
-    IN PVOID InputBuffer,
-    IN ULONG InputBufferLength,
-    IN PVOID OutputBuffer,
-    IN ULONG OutputBufferLength,
-    IN BOOLEAN InternalDeviceIoControl
+    _In_ ULONG IoControlCode,
+    _In_ PDEVICE_OBJECT DeviceObject,
+    _In_ PVOID InputBuffer,
+    _In_ ULONG InputBufferLength,
+    _Out_ PVOID OutputBuffer,
+    _Inout_ ULONG OutputBufferLength,
+    _In_ BOOLEAN InternalDeviceIoControl
+);
+
+NTSTATUS
+NTAPI
+CompBattRemoveBattery(
+    _In_ PUNICODE_STRING BatteryName,
+    _In_ PCOMPBATT_DEVICE_EXTENSION DeviceExtension
 );
 
 extern ULONG CompBattDebug;