class PowerController

Performs a command-response exchange with the PCU firmware.

Returns ZX_ERR_IO_MISSED_DEADLINE if a timeout occurs while waiting for the

PCU firmware. This usually happens if the PCU does not complete `command`

in time, but can also indicate that the PCU firmware was already performing

on a different command, and did not become available in a reasonable amount

of time.

In case of success, returns the 64-bit value in the GT Mailbox Data

Low/High registers.

Before submitting `command` to the PCU firmware via the GT Mailbox

registers, this method waits (for quite a while) for any ongoing command to

finish executing. We adopted this strategy because successful execution of

PCU commands is usually critical to the driver's operation, so we trade off

some waiting time in return for maximizing the odds of successful

execution. The consequence of this approach is that Transact() may take

more than `command.timeout_us` to complete.

Informs the PCU of the display engine's voltage requirements.

Returns ZX_ERR_IO_MISSED_DEADLINE if a timeout occurs while communicating

with the the PCU firmware. This indicates a problem in the PCU firmware. We

should not make any clocking changes if this happens.

Returns ZX_ERR_IO_REFUSED if the PCU firmware did not set the voltage to

the requested level. This is an acceptable outcome when `voltage_level` is

not the maximum level. For example, another consumer (device that shares

the voltage rail with the display engine) may have requested a higher

voltage level.

`voltage_level` must be a valid display engine voltage level. All known

display engines use levels 0-3.

Trivially destructible.

Sets the display engine's block TCCOLD (Type C Cold power state) flag.

Returns ZX_ERR_IO_MISSED_DEADLINE if a timeout occurs while communicating

with the the PCU firmware. This indicates a problem in the PCU firmware. We

should stop using Type C ports if this happens.

Returns ZX_ERR_IO_REFUSED if the PCU firmware did not bring the Type C

subsystem into the state implied by the blocking request. This is an

acceptable outcome when `blocked` is false. For example, the Type C ports

may be used by another client.

The Type C system must be brought out of the cold power state before

accessing any registers in the FIA (Flexible IO Adapter) or in the Type C

PHYs. The cold power state must remain blocked as long as the display

engine uses any main link or AUX channel in a Type C connector.

This method implements the communication protocol for Tiger Lake's PCU

firmware. Other processors use different protocols.

Sets the display engine's SAGV (System Agent Geyserville) enabled flag.

Returns ZX_ERR_IO_MISSED_DEADLINE if a timeout occurs while communicating

with the the PCU firmware. This indicates a problem in the PCU firmware. We

should assume that the SAGV is stuck enabled and configure the display

engine's pipes and planes accordingly.

Returns ZX_ERR_IO_REFUSED if the PCU firmware did not bring the system

agent subsystem into the state implied by the enablement request. This is

an acceptable outcome when `enabled` is true.

This method implements the communication protocol for Kaby Lake and Skylake

PCUs. The protocol is supported by Tiger Lake PCUs, but has been superseded

by a more fine-grained version.

Reads the SAGV (System Agent Geyserville) blocking time.

Returns the SAGV Block Time, in microseconds.

Returns ZX_ERR_IO_MISSED_DEADLINE if a timeout occurs while communicating

with the the PCU firmware. Returns ZX_ERR_IO_REFUSED if the PCU firmware

reports an error. In either case, the display engine's planes cannot be

used safely.

This method implements the communication protocol for the Tiger Lake PCU.

The protocol is not supported on Kaby Lake and Skylake PCUs.

Reads the SAGV (System Agent Geyserville) blocking time.

Returns the SAGV Block Time, in microseconds.

This method has the same signature as GetSystemAgentBlockTimeUsTigerLake()

for programming convenience. On Kaby Lake and Skylake PCUs, the SAGV

blocking time is constant.

Reads the PCU's memory latency data.

Returns the raw memory latency data, as it is returned by the PCU firmware.

Each entry in the returned array represents a memory latency level, in

microseconds. The data may have to be adjusted based on the display engine

hardware and on extra information from the memory controller about the

installed DRAM.

Returns ZX_ERR_IO_MISSED_DEADLINE if a timeout occurs while communicating

with the the PCU firmware. Returns ZX_ERR_IO_REFUSED if the PCU firmware

reports an error. In either case, the display engine's planes cannot be

used safely.

Reads MemSS (Memory Subsystem) information from the PCU.

Returns ZX_ERR_IO_MISSED_DEADLINE if a timeout occurs while communicating

with the the PCU firmware. Returns ZX_ERR_IO_REFUSED if the PCU firmware

reports an error. In either case, SAGV (System Agent Geyserville) cannot be

enabled safely.

Tests that simulate retries must use the overrides below to avoid flakiness

stemming from scheduling variability. Tests that simulate timeouts should

use the overrides below to get the PowerController to issue a deterministic

MMIO access pattern.

static

static

static

static

static

static

static

static

Behavior when the PCU-reported state doesn't match the requested state.