DM power control (<tt>power.h</tt>)

Header: components/drivers/include/drivers/core/power.h. Implementation: components/drivers/core/power.c.

This layer handles system-wide shutdown and reset, ordered power-off callbacks, and reboot mode strings—not battery/charger UI (**documentation/6.components/device-driver/power/supply.md**) and not per-IP power domains (**documentation/6.components/device-driver/power_domain/power_domain.md**).

Driver / BSP quick notes

Topic	Guidance
Callback context	`rt_dm_power_off_handler` callbacks run from `rt_hw_cpu_shutdown` / `rt_hw_cpu_reset` paths—may be IRQ or dedicated power thread; do not sleep unless your platform guarantees thread context.
Priority bands	Handlers run low index first within each `rt_dm_power_off_priority` level, then next priority—register reboot-mode notifiers at `RT_DM_POWER_OFF_PRIO_HIGH` if they must run before generic GPIO poweroff.
`-RT_EEMPTY` on domain attach	`rt_dm_power_domain_attach` returning `-RT_EEMPTY` means no `power-domains` in DTS—often OK; RPMsg/platform code treats it as non-fatal.

Power-off handlers

rt_err_t rt_dm_power_off_handler(struct rt_device *dev, int mode, int priority,

rt_err_t (*callback)(struct rt_device *));

rt_device

Definition: rtdef.h:1369

`mode`	Use
`RT_DM_POWER_OFF_MODE_SHUTDOWN`	Full power down (PMIC off, etc.).
`RT_DM_POWER_OFF_MODE_RESET`	Warm reset path before `rt_hw_cpu_reset`.

`priority` (increasing order)	Typical registrant
`RT_DM_POWER_OFF_PRIO_PLATFORM`	SoC-specific flush
`RT_DM_POWER_OFF_PRIO_LOW` / `DEFAULT` / `HIGH`	Drivers, storage sync
`RT_DM_POWER_OFF_PRIO_FIRMWARE`	Last-chance firmware handoff

Registration appends to a per-mode, per-priority singly linked list. On shutdown/reset the core walks all priority levels and invokes each callback; a non-**RT_EOK** return is logged but does not stop later handlers.

Examples: components/drivers/power/reset/gpio-poweroff.c and **gpio-restart.c** register GPIO drivers via **rt_dm_power_off_handler**.

Machine hooks

extern void (*rt_dm_machine_shutdown)(void);

extern void (*rt_dm_machine_reset)(void);

BSP or SoC code sets these to enter PMIC/PSCI/firmware sequences after DM handlers run.

Reboot mode

rt_err_t rt_dm_reboot_mode_register(struct rt_device *dev,
        rt_err_t (*callback)(struct rt_device *, char *cmd));
rt_err_t rt_dm_reboot_mode_unregister(struct rt_device *dev);
void rt_hw_cpu_reset_mode(char *cmd);

**rt_hw_cpu_reset_mode** updates the global command string (e.g. **"recovery"**) and calls **rt_hw_cpu_reset()**.
On reset, handlers registered at **RT_DM_POWER_OFF_MODE_RESET** run—core init registers **dm_reboot_notifiy** at **RT_DM_POWER_OFF_PRIO_HIGH** to apply reboot-mode callbacks before the CPU resets.

Use **syscon-reboot-mode** / NVMEM-backed mode drivers to persist **cmd** across boots.

Relation to power domains

**rt_dm_power_domain_attach(dev, on)** (in **power_domain.h**) is called from **platform probe** and some buses (e.g. RPMsg) to power on the device’s IP block before driver init. That is independent of system shutdown:

API	Scope
`rt_dm_power_domain_*`	Per-device SoC power island while system is running.
`rt_dm_power_off_handler`	Whole-system off/reset.
`rt_power_supply_*`	Charger/battery reporting.

Recommended order for a consumer **probe**: regulator enable → power domain on → clock/reset → rt_dm_dev_iomap.

Pitfalls

Missing rt_dm_machine_shutdown: handlers run but hardware never powers off—set machine hooks in BSP.
Reboot mode without storage: **cmd** is RAM-only unless a **reboot-mode** driver writes persistent storage.
GPIO poweroff polarity: wrong active level looks like “hang on shutdown”—verify DTS and **gpio-poweroff** properties.