fuchsia.hardware.power.charger

Added: HEAD

PROTOCOLS

Charger

Defined in fuchsia.hardware.power.charger/charger.fidl

Diagnostic and telemetry interface for charging hardware.

This is a read-only protocol that supports multiple concurrent clients.

ConfigureWatch

Configures the fields of interest and wake triggers for this client connection.

The driver filters the requested masks against hardware capabilities and returns the effective configuration in effective_options.

  • Partially supported options: If some requested fields are supported and others are not (e.g., requesting passive fields like input_voltage_uv or input_current_ua that do not support active interrupt notifications), the driver enables the supported fields and returns the active subset in effective_options. The call succeeds (Ok).
  • Fully unsupported options: If non-empty masks were specified but NONE of the requested fields are supported, the driver returns NOT_SUPPORTED.

If ConfigureWatch is never called, Watch defaults to returning on ANY supported field change. The driver aggregates constraints across all clients to determine hardware reporting rates.

Calling ConfigureWatch while a Watch call is already pending takes effect immediately: if the current hardware state already differs from the last-delivered snapshot on a newly enabled field, the pending Watch resolves immediately; otherwise it remains pending under the updated mask.

If ConfigureWatch returns an error, the connection's prior watch configuration remains unchanged.

Parameters:

  • options: Requested watch options. Both interest and wake_on are optional.

Returns:

  • effective_options: The subset of requested options supported and enabled by the driver.

Errors:

  • NOT_SUPPORTED: Non-empty options were requested, but none of the requested interest/wake fields are supported by the driver.

Request

NameType
options WatchOptions

Response

NameType
payload Charger_ConfigureWatch_Result

GetSpec

Retrieves the static specification of the charger.

Returns:

  • spec: Static hardware characteristics and driver capabilities of the charger.

Errors:

  • NOT_SUPPORTED: Hardware does not supply a static specification.
  • IO: Communication failure with the charger hardware (e.g. SPMI transfer failure).
  • INTERNAL: Internal driver error.

Request

<EMPTY>

Response

NameType
payload Charger_GetSpec_Result

GetStatus

Retrieves an instantaneous snapshot of the charger status.

Returns:

  • status: Complete current telemetry snapshot of the charging regulator and its inputs.

Errors:

  • IO: Communication failure with the charger hardware (e.g. SPMI transfer failure).
  • INTERNAL: Internal driver error.

Request

<EMPTY>

Response

NameType
payload Charger_GetStatus_Result

Watch

Watches for changes in charger state using a hanging-get pattern.

The first call returns the full current hardware state immediately. Subsequent calls block until a state change matches the masks in ConfigureWatch. Each return contains a complete telemetry snapshot of all current charger fields, not a sparse delta.

At most one Watch call may be outstanding per connection; concurrent calls fail with ALREADY_WATCHING.

Parameters:

  • lease: An optional power lease token used to coordinate handoff between client and server, preventing the system from suspending before critical charger events are handled. If omitted, or if the driver does not support any wake_on fields, no lease coordination is performed and any provided token is dropped without returning a wake_lease.

Returns:

  • status: Complete current telemetry snapshot of the charger.
  • wake_lease: An optional lease token provided if the change triggered a wake_on condition. Omitted if the change did not trigger a wake condition or if suspend coordination is inactive.

Errors:

  • ALREADY_WATCHING: A Watch call is already pending on this connection.
  • IO: Communication failure with the charger hardware (e.g. SPMI transfer failure).
  • INTERNAL: Internal driver error.

Request

NameType
lease fuchsia.power.system/LeaseToken

Response

NameType
payload Charger_Watch_Result

Controller

Defined in fuchsia.hardware.power.charger/charger.fidl

Control interface for mutating charger hardware state.

Single-Client Exclusivity (Hardware Driver) vs. Policy Arbitrator

On a hardware charger driver, this protocol mutates shared hardware state and admits a single active client: while one client is connected, a second connection attempt is closed immediately with a ZX_ERR_ALREADY_BOUND epitaph before any request is served. When served by a userspace policy arbitrator (such as battery-manager), multiple policy clients may connect concurrently; each connection owns an independent vote that is aggregated using minimum selection on limit fields and Discharging > Passthrough > Charging precedence on operating_mode.

Connection-Scoped Lifetime (Revert on Close)

The Controller channel encodes the lifetime of the constraints applied through it. When the client closes the channel (or disconnects unexpectedly), all constraints set during that session are withdrawn (equivalent to calling ClearControl with an empty ControlOptions).

Debug Overrides

Fields overridden through Debug take precedence over this protocol. A request that sets an overridden field is validated and accepted as usual, but the new constraint (like ClearControl or revert on close) reaches the hardware only once the override is cleared. See Debug.

ClearControl

Withdraws constraints applied through this connection for the fields present in options.

options acts as a field mask: only field presence (set vs. unset) is inspected, and the field values themselves are ignored.

  • If options is empty (no fields set), all constraints applied through this connection are withdrawn.
  • If one or more fields are set in options, only the constraints corresponding to those fields are withdrawn, leaving any other fields untouched.

Each cleared field reverts to the next active constraint, if any, or otherwise to the autonomous hardware / board-configured default that Controller restores on close. Succeeds without effect for any targeted field that is not currently constrained.

Parameters:

  • options: Mask of ControlOptions fields whose constraints should be withdrawn, or an empty table to withdraw all constraints on this connection.

Errors:

  • IO: Communication failure with the charger hardware. Fields that could not be reverted retain their constraint, so the call can be retried.
  • INTERNAL: Internal driver error.

Request

NameType
options ControlOptions

Response

NameType
payload Controller_ClearControl_Result

SetControl

Applies operational and electrical constraints to the charger converter.

Validation is atomic: a request rejected with NOT_SUPPORTED or INVALID_ARGS leaves hardware and session state untouched. The response is returned only after all corresponding hardware register writes have completed and been acknowledged by the charger IC.

Parameters:

  • options: The constraints to apply. Present fields overwrite the constraints previously set on this connection for those fields; omitted fields leave this connection's prior constraints for those fields unchanged.

Errors:

  • NOT_SUPPORTED: One or more requested constraints are not adjustable on this hardware/arbiter, or the requested operating_mode is absent from Spec.supported_modes.
  • INVALID_ARGS: A requested value is outside the range the hardware can program, or the requested operating_mode conflicts with the active power path state (for example, requesting OperatingMode::OTG while external input power is online on the same port).
  • IO: Communication failure with the charger hardware (e.g. SPMI transfer failure).
  • INTERNAL: Internal driver error.

Request

NameType
options ControlOptions

Response

NameType
payload Controller_SetControl_Result

Debug

Defined in fuchsia.hardware.power.charger/charger.fidl

Debug control interface for hardware battery chargers.

Composes Controller without its single-client exclusivity or revert-on-close lifetime, so command-line diagnostic utilities (such as batteryutil) and integration tests can apply sticky charger overrides while the production policy client stays connected to Controller. Only reachable through DebugService.

Override Precedence

Each field set through SetControl becomes an override that takes precedence over Controller regardless of request order: a Controller request that sets an overridden field is validated and accepted, but takes effect only once the override is cleared, and a Controller revert on close leaves overridden fields untouched. Fields that are not overridden stay under Controller control.

Sticky Lifetime (No Revert on Close)

Overrides are not tied to the connection that applied them: closing the channel leaves them in effect, so a utility can apply an override and exit. They remain in effect until ClearControl is called on a Debug connection.

Multiple Connections

Any number of Debug connections may be open concurrently; connections are never rejected with ZX_ERR_ALREADY_BOUND. All Debug connections share one set of Debug overrides: for each field, the most recent SetControl wins, and ClearControl withdraws the targeted Debug overrides.

ClearControl

Withdraws constraints applied through this connection for the fields present in options.

options acts as a field mask: only field presence (set vs. unset) is inspected, and the field values themselves are ignored.

  • If options is empty (no fields set), all constraints applied through this connection are withdrawn.
  • If one or more fields are set in options, only the constraints corresponding to those fields are withdrawn, leaving any other fields untouched.

Each cleared field reverts to the next active constraint, if any, or otherwise to the autonomous hardware / board-configured default that Controller restores on close. Succeeds without effect for any targeted field that is not currently constrained.

Parameters:

  • options: Mask of ControlOptions fields whose constraints should be withdrawn, or an empty table to withdraw all constraints on this connection.

Errors:

  • IO: Communication failure with the charger hardware. Fields that could not be reverted retain their constraint, so the call can be retried.
  • INTERNAL: Internal driver error.

Request

NameType
options ControlOptions

Response

NameType
payload Controller_ClearControl_Result

SetControl

Applies operational and electrical constraints to the charger converter.

Validation is atomic: a request rejected with NOT_SUPPORTED or INVALID_ARGS leaves hardware and session state untouched. The response is returned only after all corresponding hardware register writes have completed and been acknowledged by the charger IC.

Parameters:

  • options: The constraints to apply. Present fields overwrite the constraints previously set on this connection for those fields; omitted fields leave this connection's prior constraints for those fields unchanged.

Errors:

  • NOT_SUPPORTED: One or more requested constraints are not adjustable on this hardware/arbiter, or the requested operating_mode is absent from Spec.supported_modes.
  • INVALID_ARGS: A requested value is outside the range the hardware can program, or the requested operating_mode conflicts with the active power path state (for example, requesting OperatingMode::OTG while external input power is online on the same port).
  • IO: Communication failure with the charger hardware (e.g. SPMI transfer failure).
  • INTERNAL: Internal driver error.

Request

NameType
options ControlOptions

Response

NameType
payload Controller_SetControl_Result

STRUCTS

Charger_ConfigureWatch_Response

Defined in fuchsia.hardware.power.charger/charger.fidl

FieldTypeDescriptionDefault
effective_options WatchOptions No default

Charger_GetSpec_Response

Defined in fuchsia.hardware.power.charger/charger.fidl

FieldTypeDescriptionDefault
spec Spec No default

Charger_GetStatus_Response

Defined in fuchsia.hardware.power.charger/charger.fidl

FieldTypeDescriptionDefault
status Status No default

Charger_Watch_Response resource

Defined in fuchsia.hardware.power.charger/charger.fidl

FieldTypeDescriptionDefault
status Status No default
wake_lease fuchsia.power.system/LeaseToken No default

Controller_ClearControl_Response

Defined in fuchsia.hardware.power.charger/charger.fidl

<EMPTY>

Controller_SetControl_Response

Defined in fuchsia.hardware.power.charger/charger.fidl

<EMPTY>

ENUMS

ChargePhase flexible

Type: uint32

Defined in fuchsia.hardware.power.charger/charger.fidl

Describes the active charging phase of the charger hardware.

Lithium-ion battery charging typically transitions across distinct stages: Pre-conditioning/Trickle -> Constant Current (Fast) -> Constant Voltage (Taper) -> Top-off -> Done.

NameValueDescription
1

The charger is idle, off, or not supplying charging power to the battery (including during passthrough, bypass, or charge-inhibit mode).
2

Pre-qualification / trickle charging phase. Used when the battery is deeply depleted below the pre-charge voltage threshold; current is limited to a small, safe level to restore cell voltage before fast charge.
3

Constant Current (CC) fast charging phase. The charger acts as a regulated current source supplying maximum programmed fast charge current.
4

Constant Voltage (CV) taper phase. The battery voltage has reached the regulation target limit; current naturally tapers down as the cell saturates.
5

Top-off charging phase. Low-current charging stage right after the CV termination threshold is reached, providing a timed saturation before stopping.
6

Charge termination complete. The charger has completed its charging cycle (e.g. top-off timer or termination-current threshold reached) and has cut off charge current to the battery while continuing to supply system load. The charger may automatically re-enter FAST if battery voltage decays below the recharge threshold.

Error flexible

Type: uint32

Defined in fuchsia.hardware.power.charger/charger.fidl

Errors returned by the charger protocols.

NameValueDescription
1

An unexpected error occurred within the driver.
2

The requested operation, field, or mode is not supported by this hardware.
3

One or more arguments provided to the method were invalid, or a requested value lies outside the range the hardware can program.
4

Communication with the charger hardware failed (e.g. a bus transfer error).
5

A Watch call is already pending on this connection.

Health flexible

Type: uint32

Defined in fuchsia.hardware.power.charger/charger.fidl

Hardware health and fault conditions of the charging converter.

NameValueDescription
1

Normal operation; no faults or converter thermal throttling detected.
2

Input voltage on the charger supply rail exceeds the over-voltage lockout (OVLO) limit.
3

Input voltage on the charger supply rail fell below the under-voltage lockout (UVLO) operational floor.
4

Internal charger die temperature reached the thermal regulation (TREG) threshold; the converter is still operating but actively folding back current to limit die heating.
5

Internal charger die or input connector temperature exceeded thermal shutdown (TSHDN) protection limits and the converter has suspended operation.
6

Hardware charge safety timer expired before reaching the target charge state.
7

Voltage sensed at the charger output rail exceeded the converter's over-voltage threshold.
8

Hardware watchdog timer expired (WDT), suspending converter operation.
9

Unspecified charger hardware fault.

OperatingMode flexible

Type: uint32

Defined in fuchsia.hardware.power.charger/charger.fidl

Describes the primary power converter operating state across the power path and battery interface.

Reported as state in Status and requested as a target in ControlOptions. A requested mode selects the converter configuration; the state subsequently reported also accounts for whether external power is actually present, so a charger left in CHARGING reports DISCHARGING once the input goes away.

NameValueDescription
1

Normal operation: External power supplies system rails and charges the battery. Requesting this mode resumes normal charging after PASSTHROUGH or DISCHARGING.
2

Inhibit charge / passthrough: External power supplies system rails, but battery charging is disabled (cell rests at current state of charge).
3

As a request: force discharge. External power draw is suspended; the system runs exclusively on battery while external communication (e.g. USB data) remains active.

As reported state: the battery is supplying the system, either because discharge was requested or because no external power is present. Use Status.online to tell these apart. A configured PASSTHROUGH is not separately observable while offline.
4

OTG / Reverse Boost: Power is sourced outward from the battery to the external port.

SourceType flexible

Type: uint32

Defined in fuchsia.hardware.power.charger/charger.fidl

Describes the external power source type feeding the charger.

NameValueDescription
1

Standard wall-plug adapter or dedicated charger (e.g. BC1.2 DCP).
2

Standard USB host or charging downstream port (e.g. BC1.2 SDP / CDP).
3

Inductive or magnetic resonance wireless charging pad (e.g. WCIN / Qi).

TABLES

ControlOptions

Defined in fuchsia.hardware.power.charger/charger.fidl

Operational and electrical constraints applicable to the charger converter.

This is a partial update: only the fields present are applied, and any omitted field leaves the corresponding hardware setting unchanged. While the Controller connection remains open, to relax or withdraw a previously applied limit, set the field again to the desired value, call Controller.ClearControl with a mask of fields to withdraw, or close the Controller channel to withdraw all constraints and restore driver defaults.

Values between discrete hardware register steps are rounded in the direction that honors the constraint. Ceilings (current and voltage limits) round down, so a value below the lowest programmable step is rejected with Error::INVALID_ARGS; the input_voltage_limit_uv floor rounds up, so a value below the lowest programmable step is clamped to it.

OrdinalFieldTypeDescription
operating_mode OperatingMode

Desired operational mode of the power converter.
input_current_limit_ua uint32

Active Input Current Limit (ICL) programmed into the input power path, in microamps. Values between discrete hardware register steps are rounded down to the nearest programmable step so the requested ceiling is never exceeded.
charge_current_limit_ua uint32

Active Fast Charge Current (FCC) regulation limit for the battery, in microamps. Values between discrete hardware register steps are rounded down to the nearest programmable step so the requested ceiling is never exceeded.
float_voltage_uv uint32

Active float (constant voltage / CV) regulation target across the battery, in microvolts (bounded by Spec.max_charge_voltage_uv). Values between discrete hardware register steps are rounded down to the nearest programmable step. Note that writing a float voltage target may cause the hardware charge state machine to exit ChargePhase::TOP_OFF and re-evaluate CV regulation.
charge_term_current_ua uint32

Active charge termination (top-off / taper cutoff) current threshold, in microamps. Values between discrete hardware register steps are rounded down to the nearest programmable step.
input_voltage_limit_uv uint32

Minimum input voltage regulation floor (VINDPM), in microvolts, below which the converter throttles input current draw to prevent source collapse. Values between discrete hardware register steps are rounded up to the nearest programmable step so the input voltage never drops below the requested floor.

Spec

Defined in fuchsia.hardware.power.charger/charger.fidl

Static hardware characteristics and driver capabilities.

OrdinalFieldTypeDescription
max_charge_current_ua uint32

Optional. Maximum current the charger hardware can supply to the battery, in microamps. Omitted if unsupported by hardware.
max_charge_voltage_uv uint32

Optional. Maximum voltage the charger hardware can regulate across the battery, in microvolts. Omitted if unsupported by hardware.
max_input_current_ua uint32

Optional. Maximum input current the charger input power path can draw, in microamps. Omitted if unsupported by hardware.
model string:128

Optional. Informational charger model string or manufacturer part number. Omitted if unknown or unprogrammed in hardware.
supported_modes vector<OperatingMode>:16

Optional. List of operating modes supported by this charger hardware implementation. Omitted if unsupported or unconfigurable by hardware.
supported_options WatchOptions

Required. The interest and wake options supported by this driver/hardware.

Drivers must populate this table so clients know which fields support active change notifications. If omitted by the driver, clients should assume no active interrupt watching is supported.

  • supported_options.interest: Telemetry fields that can actively trigger hanging-get watch notifications on change. Fields omitted are passive measurements that do not generate hardware interrupts; their freshest values are returned during active state changes or via Charger.GetStatus.
  • supported_options.wake_on: Telemetry fields capable of actively waking the system from suspend via hardware interrupt lines etc.
precharge_current_ua uint32

Optional. Trickle/precharge current supplied when battery voltage is below the fast-charge threshold, in microamps. Omitted if unsupported by hardware.
charge_term_current_ua uint32

Optional. Default or minimum charge termination (top-off / taper cutoff) current threshold, in microamps. Omitted if unsupported by hardware.
recharge_voltage_uv uint32

Optional. Battery voltage threshold (or drop below float voltage) at which the charger automatically initiates a recharge cycle after reaching ChargePhase::DONE, in microvolts. Omitted if unsupported by hardware.
min_input_voltage_uv uint32

Optional. Minimum programmable input voltage regulation floor (VINDPM), in microvolts. Omitted if unsupported by hardware.
max_input_voltage_uv uint32

Optional. Maximum programmable input voltage regulation floor (VINDPM), in microvolts. Omitted if unsupported by hardware.

Status

Defined in fuchsia.hardware.power.charger/charger.fidl

Primary telemetry snapshot of the charging regulator and its power inputs.

OrdinalFieldTypeDescription
online bool

Whether an external power supply or adapter (e.g. VBUS / USB-C / wireless) is physically attached and supplying valid power. If false, no external source is detected. Omitted if attachment status is indeterminate.
input_voltage_uv uint32

The measured input voltage from the external power source in microvolts. Omitted if unsupported by hardware or unavailable.
input_current_ua int32

The measured input current drawn from the external power source in microamps. Positive (+) indicates current drawn into the charger from the external power source; negative (-) indicates current sourced outward to the external port (e.g. during OperatingMode::OTG reverse boost, if the hardware senses reverse port current). Omitted if unsupported by hardware or unavailable.
operating_mode OperatingMode

Active operational mode of the power converter and battery interface. Omitted if indeterminate or unsupported by hardware.
charge_phase ChargePhase

Current charging phase. Omitted if indeterminate or unsupported by hardware.
input_current_limit_ua uint32

Active Input Current Limit (ICL) programmed into the input power path, in microamps. Represents the maximum current the charger is permitted to draw from the external input. Omitted if indeterminate or unsupported by hardware.
charge_current_limit_ua uint32

Active Fast Charge Current (FCC) regulation limit programmed for the battery, in microamps. Represents the target constant-current delivered to the battery terminals during fast charge. Omitted if indeterminate or unsupported by hardware.
float_voltage_uv uint32

Active float (constant voltage / CV) regulation target programmed for the battery, in microvolts. Represents the maximum terminal voltage across the battery pack (as distinct from the static hardware ceiling Spec.max_charge_voltage_uv). Omitted if indeterminate or unsupported by hardware.
source_type SourceType

The detected external power supply type feeding the charger. Omitted if indeterminate or disconnected.
health Health

Hardware health and fault condition of the charging converter. Omitted if indeterminate or unsupported by hardware.
charge_term_current_ua uint32

Active charge termination (top-off / taper cutoff) current threshold programmed into the charger, in microamps. Omitted if indeterminate or unsupported by hardware.
input_voltage_limit_uv uint32

Active minimum input voltage regulation floor (VINDPM) programmed into the input power path, in microvolts. Omitted if indeterminate or unsupported by hardware.

WatchOptions

Defined in fuchsia.hardware.power.charger/charger.fidl

Configuration options for charger state watching.

Both fields are optional masks. In both interest and wake_on, the actual field values within the Status table are ignored; only field presence (set vs. unset) determines the mask.

An absent mask means "use this field's default"; a present but empty mask means "no fields". The two defaults differ because the safe choice differs: interest defaults to everything the driver supports watching, so a client that never configures anything still makes progress, while wake_on defaults to nothing, since waking the system is a cost a client must opt into.

OrdinalFieldTypeDescription
interest Status

Fields the client wants to receive change notifications for. Defaults to every field the driver supports watching, as reported by Spec.supported_options. Pass an explicitly empty table to be notified only for the fields named in wake_on.
wake_on Status

Fields that should actively wake the system from suspend. Any field present in wake_on is implicitly included in interest. Defaults to no fields: changes occurring during suspend are deferred until the next system wakeup and do not wake the device.

UNIONS

Charger_ConfigureWatch_Result strict

Defined in fuchsia.hardware.power.charger/charger.fidl

OrdinalVariantTypeDescription
response Charger_ConfigureWatch_Response
err Error
framework_err internal

Charger_GetSpec_Result strict

Defined in fuchsia.hardware.power.charger/charger.fidl

OrdinalVariantTypeDescription
response Charger_GetSpec_Response
err Error
framework_err internal

Charger_GetStatus_Result strict

Defined in fuchsia.hardware.power.charger/charger.fidl

OrdinalVariantTypeDescription
response Charger_GetStatus_Response
err Error
framework_err internal

Charger_Watch_Result strict resource

Defined in fuchsia.hardware.power.charger/charger.fidl

OrdinalVariantTypeDescription
response Charger_Watch_Response
err Error
framework_err internal

Controller_ClearControl_Result strict

Defined in fuchsia.hardware.power.charger/charger.fidl

OrdinalVariantTypeDescription
response Controller_ClearControl_Response
err Error
framework_err internal

Controller_SetControl_Result strict

Defined in fuchsia.hardware.power.charger/charger.fidl

OrdinalVariantTypeDescription
response Controller_SetControl_Response
err Error
framework_err internal

SERVICES

DebugService

Defined in fuchsia.hardware.power.charger/charger.fidl

NameTypeTransport
debug fuchsia.hardware.power.charger/Debug Channel

Service

Defined in fuchsia.hardware.power.charger/charger.fidl

NameTypeTransport
charger fuchsia.hardware.power.charger/Charger Channel
controller fuchsia.hardware.power.charger/Controller Channel