Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

simbatt: Provide instructions for how to test the driver #1187

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

simbatt: Provide instructions for how to test the driver #1187

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions simbatt/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```