Skip to content

Support smart charging and battery authentication status - #167

Open
petm5 wants to merge 2 commits into
linux-surface:v6.18-surface-develfrom
petm5:v6.18-surface-devel-battery-features
Open

petm5 wants to merge 2 commits into
linux-surface:v6.18-surface-develfrom
petm5:v6.18-surface-devel-battery-features

Conversation

@petm5

@petm5 petm5 commented Jul 7, 2026

Copy link
Copy Markdown

Added support for battery features reverse-engineered from the Windows drivers.

Authentic batteries in Surface devices are verified and paired with the motherboard during manufacturing or repair for quality assurance. Windows reads the authentication status and shows a warning message if the battery isn't genuine. This status can now be read from Linux.

Newer Surface devices limit the battery charge to 80% based on usage patterns. The Surface app on Windows has a button that disables the limit temporarily and charges the battery to 100%, but Linux previously had no way to control it. The battery driver now reports the smart charging status as a charge limit and lets users disable it by setting it to 100%. The charge limit is controlled by the SAM and gets re-enabled automatically after a few days, and re-enabling the limit manually doesn't seem to be possible.

Fixes linux-surface/linux-surface#1781, linux-surface/linux-surface#2070.

petm5 added 2 commits July 7, 2026 16:11
Authentic batteries in Surface devices are verified and paired with the
motherboard during manufacturing or repair for quality assurance. Read
the authentication status from the SAM and report it.
Newer Surface devices limit the battery charge to 80% based on usage
patterns. Report the charge limit status and disengage it if requested.

The charge limit is always controlled by the SAM and will be re-enabled
after a few days depending on use.
@Cloveian

Copy link
Copy Markdown

so about "re-enabling the limit manually doesn't seem to be possible", you actually can set it, it's just a different pair of battery commands ("user charge mode"). i dug them out of the windows drivers and tested both on my Surface Pro for Business 11th Edition with Intel (SAM 10.3.139) through /dev/surface/aggregator.

commands

all TC 0x02 (BAT), TID 0x01, IID 0x01

CID name (windows) payload response
0x09 get user charge mode none u32 modes_supported, u8 current_mode, u8 previous_mode, u8 settings[]
0x0a set user charge mode u8 mode, u8 settings[4] (5 bytes) none

modes (enum UserChargeMode): 0 adaptive, 1 user set limit, 2 no limit with timeout

  • mode 1: settings[0] = limit in percent
  • mode 2: settings[0..3] = u32 timeout in seconds
  • mode 0: all zeros

so 80% is 0a with 01 50 00 00 00, and adaptive is 00 00 00 00 00.

where it's from

  • SurfaceBatteryClient.sys (Surface Pro 11 Intel driver pack, 26.083.38253.0): BatteryCommunication_SetUserChargeMode builds a BAT request with CID 0x0a, no response flag, and a 5 byte payload it just copies from whatever called it
  • the Surface app's battery service (Services/BatteryDm.dll in Microsoft.SurfaceHub 76.9122.158.0, it's .NET): CommandIdGetUserChargeMode = 9, CommandIdSetUserChargeMode = 10, the Battery_Set_UserChargeMode struct (byte Mode; byte[4] ModeSettings, Pack=1), and BatteryUserChargeModeUserSetLimitMinPct = 50 / MaxPct = 80 / DefaultPct = 80

what it actually does (on mine)

  • get returns 10 bytes here (03 00 00 00 01 00 50 00 00 00): supported = adaptive + user limit, current = user limit 80%, previous = adaptive. the app's struct has 24 settings bytes but this firmware only sends 4, and mode 2 isn't in the supported mask (probably needs newer firmware)
  • set to 50, 65, 66, and 69 all applied instantly, get reads the new value back
  • above the limit it drains to it even plugged in (Discharging ~6 W with ADP1 online), it doesn't just stop charging
  • a bit under the limit it holds (Not charging, 0 mW). at 64% it held with the limit at 65 and 66, and started charging (~30 W) at 69, so it starts charging again somewhere 3–5% under the limit
  • i didn't try anything outside 50–80 ¯\_(ツ)_/¯

@Cloveian

Copy link
Copy Markdown

fun fact, it rejects anything above 80% or below 50% ( ¬⩊¬)

@petm5

petm5 commented Oct 20, 2026

Copy link
Copy Markdown
Author

@Cloveian Thanks for your findings! I reversed the same commands from SurfaceBatteryClient.sys and the Surface app's BatteryDm.dll, but those commands don't seem to work on my Surface Pro 9.

The Surface app only shows a button to disable adaptive charging temporarily, with no manual control over charge limits. It checks some kind of condition to see what charge limit modes the EC supports, but I don't have the exact details in my notes. I think it had something to do with the return value of battery command 0x3a called Get_Protection_Policy, which returns 0x10 on my device.

The command sudo ./ctrl.py request 0x02 0x01 0x09 0x01 1 (from linux-surface/surface-aggregator-module) should report the user charge mode, but it just fails with a timeout for me. sudo ./ctrl.py request 0x02 0x01 0x0a 0x01 0 0x01 0x50 0x00 0x00 0x00 should limit the charge to 80% but it doesn't seem to have any effect.

@Cloveian

Copy link
Copy Markdown

ahhh, i am on a SP11 (intel) so its probably a little different

if (status)
return status;

bat->charge_limit_enforced = le32_to_cpu(bcl) == SAM_BATTERY_CHARGE_LIMIT_ENFORCED;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think le32_to_cpu(__le16) is probably wrong?

if (status)
return status;

bat->supports_smart_charging = (le32_to_cpu(bpp) & SAM_BATTERY_PROTECTION_POLICY_CHARGE_LIMIT) == SAM_BATTERY_PROTECTION_POLICY_CHARGE_LIMIT;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think le32_to_cpu(__u8) is unnecessary.

@qzed

qzed commented Nov 9, 2026

Copy link
Copy Markdown
Member

@Cloveian would you be willing to write this up as a separate patch?

And does either of you know if there's any way to identify what kind of operations SAM supports (wrt smart charging)? Like if it's controlled via Get_Protection_Policy maybe we should try to collect what it returns across different devices. I'd prefer if we can only expose the ops to userspace that are actually supported on the model.

I gave this a quick test on my SPX and unfortunately it seems to complicate things a bit more:

  • the get_protection_policy command works, but returns 2 bytes, not one.
  • all other commands (auth, limit, user charge mode) time out, so don't seem to be supported.

And just to be sure, those are really actually all SAM (0x01) category commands, not BAT (0x02)? I'm wondering if the instance ID from the device works well with that or if we should set it to 0 or so.

@Cloveian

Copy link
Copy Markdown

@Cloveian would you be willing to write this up as a separate patch?

I can try (⁠٥•▽•)

@Cloveian

Copy link
Copy Markdown

few questions:

  • should it be a separate PR against v6.18-surface-devel, or on top of this one? they both touch surface_battery.c so one of them is gonna conflict
  • i was thinking of just using the standard charge_types (Adaptive / Custom) + charge_control_end_threshold (50-80), that way upower and DEs pick it up without anything surface specific. is that ok or should it match whatever this PR ends up exposing?
  • for detecting support, 0x09 already returns a modes_supported mask so i'd gate on that. only problem is on SP9/SPX it times out instead of erroring, so probably one try at probe without ssam_retry

also im the only one in this PR discussion where user charge mode actually works so i can run the read-only ones (0x1b, 0x3a, 0x41, IID 1 and 0) on my SP11 if more data helps ദ്ദി(ˉ ꒳ ˉ マ.ᐟ

@petm5

petm5 commented Nov 10, 2026 •

Copy link
Copy Markdown
Author

And just to be sure, those are really actually all SAM (0x01) category commands, not BAT (0x02)? I'm wondering if the instance ID from the device works well with that or if we should set it to 0 or so.

From what I can tell, they are all SAM (0x01) category commands and the instance ID doesn't seem to have any effect.

And does either of you know if there's any way to identify what kind of operations SAM supports (wrt smart charging)?

The Windows battery control logic is split across several different modules, so tracing it isn't so easy. Charging modes appear to be detected as supported based on some field in Get_ExtInfoGeneralStandard (0x22) and bit 4 (bitmask 0x10) of Get_Protection_Policy (0x3a).

The operational logic is in the userspace BatteryDm.exe, but it sends commands with internal IDs to a kernel-space Surface Integration Driver (SID) in SurfaceIntegrationDriver.sys, which translates them to an actual SAM command ID that are then sent through SurfaceSerialHubDriver.sys.

In case anyone finds it helpful, here's my reverse-engineered mapping of the command translation in SurfaceIntegrationDriver.sys:

Internal command SAM command ID Name in BatteryDm.exe
0 0x64 Get_Bix
1 0x22 Get_ExtInfoGeneralStandard
2 0x23 Get_ExtInfoGeneralCustom
3 0x24 Get_ExtInfoBatteryProtection
4 0x25 Get_ExtInfoCutTheTop
5 0x3a Get_Protection_Policy
6 0x41 Get_Consolidated_Bcl_Status
7 0x42 Get_Bcl_Countdown
8 0x43 Force_Bcl_Disengage
9 0x1b AuthenticateBattery
10 0x46 BatteryShutdown
11 0x26 Get_ExtInfoPredictiveChargeControl
12 0x65 Set_PccEnable
14 0x11 Get_PsuGeneralInfo
15 0x0a Set_User_Charge_Mode
16 0x09 Get_User_Charge_Mode

Only commands 0x3a, 0x41, 0x42, 0x43, and 0x1b appear in a serial capture from Windows.

@Cloveian

Copy link
Copy Markdown

okie, i made the patch: v7.3-surface-devel...Cloveian:kernel:battery-charge-limit

i based it on v7.3-surface-devel (but it cleanly applies to v6.18-surface-devel too). tested on my SP11 on 7.2 and 7.3. it uses charge_types + charge_control_end_threshold, and it only registers if 0x23 reports a cmd_revision and 0x09 works, which is how windows decides. i can open it as a PR whenever, lmk if you want anything different ദ്ദി(ᵔᗜᵔ)

@Cloveian

Copy link
Copy Markdown

also, i found something that might help with the naming/category questions: the Surface app ships SurfaceCommonHeadersDotNet.dll, which is a generated copy of the SSH command headers (1017 commands across 36 categories, with names and request/response types). i probed the battery-related ones on my SP11:

TC CID name in the headers SP11 response
BAT 0x09 GetUserChargeMode 10 bytes 03000000 01 00 50000000, same with IID 0 and 1
BAT 0x0a SetUserChargeMode u8 status: 00 ok, 03 (SettingsInvalid) for 49/85
BAT 0x1b AuthenticateBattery 1 byte 00
BAT 0x22 GetExtendedInfoGeneralStandard 119 bytes
BAT 0x23 GetExtendedInfoGeneralCustom 91 bytes, cmd_revision = 1, charge_mode = 12 (user limit)
SAM 0x1b GetWakeAlarmStatus 4 bytes 00000000, same with IID 0 and 1
SAM 0x3a GetSystemProtectionPolicy 1 byte 0x10, same with IID 0 and 1
SAM 0x41 GetConsolidatedBatteryProtStatus 2 bytes, 0x0800 (= UserChargeModeLimit in the header's bitmask)
SAM 0x42 GetBclDisengageCounter 4 bytes, 0

so a few things:

  • SAM 0x1b looks like it's actually the ACPI wake alarm status, and battery auth is BAT 0x1b. the PR reads SAM 0x1b into an __le32, which matches the wake alarm size, not the 1 byte auth result
  • the IID doesn't seem to matter on mine either, same as petm5 found
  • user charge mode is BAT, not SAM. SAM 0x09 is SetBclState so probably don't send 0x09 to SAM

should i put the whole table somewhere (with what answers on the SP11)? not sure if it belongs here or in surface-aggregator-module or something. note for anyone else probeing stuff: TC 0x23 CID 0x04 (GetProductInfo according to the headers) instantly hard powered off my SP11, so the names aren't reliable outside SAM/BAT/FAN/TMP (◞‸◟)

@Cloveian

Copy link
Copy Markdown

would you like me to make a separate pr?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Surface Pro 9 charging stopped working after Ubuntu 24.04 updates (June 3, 2025)

3 participants