class SetPowerState

Transitions the PHY to `state`. See [`PowerState`] for the hardware preconditions of each

target state.

## Power States and Held Resources

Each lower power state holds a strict subset of the resources held by the state above it:

| State | Power Domains | Core Clocks

&

Rails | M-PHY Low-V Rail | Aux Clock |

|-------------------|---------------|---------------------|------------------|-----------|

| `ACTIVE` | ON | ON | ON | ON |

| `LINK_IDLE` | ON | ON | ON | OFF |

| `HIBERNATE_SLEEP` | ON | ON | OFF | OFF |

| `POWER_DOWN` | OFF | OFF | OFF | OFF |

## Allowed Transitions

- **Same state (`S -> S`)**: Always idempotent; returns `ZX_OK` without modifying hardware.

- **Higher power to lower power (`ACTIVE -> LINK_IDLE`, `ACTIVE/LINK_IDLE ->

HIBERNATE_SLEEP`, or `ACTIVE/LINK_IDLE/HIBERNATE_SLEEP -> POWER_DOWN`)**: Allowed.

Releases the additional resources not required in the target state.

- **Any lower power state to `ACTIVE` (`LINK_IDLE/HIBERNATE_SLEEP/POWER_DOWN -> ACTIVE`)**:

Allowed. Restores all resources required for `ACTIVE`.

- **Lower power to a higher non-`ACTIVE` state (`POWER_DOWN -> LINK_IDLE`, `POWER_DOWN ->

HIBERNATE_SLEEP`, or `HIBERNATE_SLEEP -> LINK_IDLE`)**: Rejected with `ZX_ERR_BAD_STATE`.

The caller must transition to `ACTIVE` first.

## Error Semantics

- **Transitions to `ACTIVE`, `LINK_IDLE`, or `HIBERNATE_SLEEP`**: On failure, the PHY rolls

back any partial changes (best-effort) and remains in its previous state.

- **Transitions to `POWER_DOWN`**: Every power-down step is attempted even if an earlier

step fails, the first error is returned, and the PHY transitions to `POWER_DOWN`.