From 2769d4292d3f67ae687c975226d7f5eb8e28bd84 Mon Sep 17 00:00:00 2001 From: Fredrik Orderud Date: Thu, 20 Jun 2024 11:54:28 +0200 Subject: [PATCH] simbatt: Provide instructions for how to test the driver Add instructions for how to install the driver, simulate two batteries, modify battery parameters and clean up afterwards. The instructions assume that testsigning is already enabled with "bcdedit /set testsigning on" and that the driver signing certificate is trusted with "certutil.exe -addstore root simbatt.cer" and "certutil.exe -f -addstore trustedpublisher simbatt.cer". --- simbatt/README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/simbatt/README.md b/simbatt/README.md index 68a459b38..9f7c217c0 100644 --- a/simbatt/README.md +++ b/simbatt/README.md @@ -17,3 +17,43 @@ This source code is intended to demonstrate implementation of Windows battery dr This is a KMDF based sample. You may use this sample as a starting point to implement a battery miniport specific to your needs. + + +## How to test + +### Driver installation +``` +:: Install driver +pnputil /add-driver simbatt.inf /install + +:: Simulate two batteries +devgen /add /instanceid 1 /hardwareid "{6B34C467-CE1F-4c0d-A3E4-F98A5718A9D6}\SimBatt" +devgen /add /instanceid 2 /hardwareid "{6B34C467-CE1F-4c0d-A3E4-F98A5718A9D6}\SimBatt" +``` + +The simulated batteries will have device instance ID `SWD\DEVGEN\1` and `SWD\DEVGEN\2`. + +### Modify battery parameters +Parameters for each simulated battery can be changed through `IOCTL_SIMBATT_SET_STATUS` IOCTL calls with [`BATTERY_STATUS`](https://learn.microsoft.com/en-us/windows/win32/power/battery-status-str) input. This enables simulation of many power scenarios, such as low charge and switching between AC and DC power. This can be done without any physical batteries attached. One can in fact use the driver to simulate multi-battery setups in a Virtual Machine (VM). + +Example of how to simulate 50% battery charge that is currently being discharged: +``` +BATTERY_STATUS status = {}; +status.PowerState = BATTERY_DISCHARGING; +status.Capacity = 50; // 50% +status.Rate = BATTERY_UNKNOWN_RATE; +status.Voltage = BATTERY_UNKNOWN_VOLTAGE; +DeviceIoControl(battery, IOCTL_SIMBATT_SET_STATUS, &status, sizeof(status), nullptr, 0, nullptr, nullptr); +``` + +The `battery` handle can be accessed by first using `CM_Locate_DevNode` to get a device instance handle from the device instance ID. Then, use `CM_Get_DevNode_Property` with `DEVPKEY_Device_PDOName` to get the physical device object (PDO) string. Finally, use `CreateFile` to open the battery based on the PDO string with a `\\?\GLOBALROOT` prefix. + +### Driver uninstallation +``` +:: Delete simulated batteries +devgen /remove "SWD\DEVGEN\1" +devgen /remove "SWD\DEVGEN\2" + +:: Uninstall driver +pnputil /delete-driver simbatt.inf /uninstall /force +```