PROTOCOLS

Admin

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Provides methods to request that the system be transitioned into a supported power state.

Note (see https://fxbug.dev/42136295): These methods do not return until after the state transition has been completed. In most cases (e.g. Reboot), a successful transition means that the caller does not actually observe the completion because the system will be rebooted before the call is completed. The implication is that using a synchronous FIDL client with these methods will result in a blocked thread for the duration of the call, or even for the remainder of the component's life (in the case of Reboot). Therefore, if a synchronous FIDL client is to be used with this protocol then care should be taken to avoid handling any shutdown-induced callbacks on the same thread that was used to initiate the transition. Example callbacks include fuchsia.process.lifecycle/Lifecycle.Stop and fuchsia.hardware.power.statecontrol/RebootMethodsWatcher.OnReboot. Alternatively, the caller could choose to use an asynchronous FIDL client with this protocol to avoid blocking their calling thread.

Mexec

Performs a kernel mexec.

It is expected that the ZBI items specified by zx_system_mexec_payload_get() have not yet been appended to the provided data ZBI.

Request

Name	Type
kernel_zbi	handle<vmo>
data_zbi	handle<vmo>

Response

Name	Type
payload	Admin_Mexec_Result

PerformReboot

Asks the device to reboot.

Arguments:

• options: The options with which to perform this requests. ZX_ERR_INVALID_ARGS is returned if the options are malformed (i.e. reasons is absent or empty).

Deprecation

Use Shutdown, which allows callers to specify the intended action and reasons for the action.

Request

Name	Type
options	RebootOptions

Response

Name	Type
payload	Admin_PerformReboot_Result

PowerFullyOn

Asks the device to enter a fully on state.

Request

<EMPTY>

Response

Name	Type
payload	Admin_PowerFullyOn_Result

Poweroff

Asks all devices to enter a powered off state.

Deprecation

Use Shutdown, which allows callers to specify reasons why they are requesting a poweroff.

Request

<EMPTY>

Response

Name	Type
payload	Admin_Poweroff_Result

Reboot

Asks the device to reboot.

Replaced by PerformReboot.

Request

Name	Type
reason	RebootReason

Response

Name	Type
payload	Admin_Reboot_Result

RebootToBootloader

Asks the device to reboot into the bootloader.

Deprecation

Use Shutdown, which allows callers to specify reasons why they are requesting a reboot to bootloader.

Request

<EMPTY>

Response

Name	Type
payload	Admin_RebootToBootloader_Result

RebootToRecovery

Asks the device to reboot into the recovery partition.

Deprecation

Use Shutdown, which allows callers to specify reasons why they are requesting a reboot to recovery.

Request

<EMPTY>

Response

Name	Type
payload	Admin_RebootToRecovery_Result

Shutdown

Asks the device to enter the state specified by options.action.

Arguments:

• options: The options with which to perform this request. ZX_ERR_INVALID_ARGS is returned if action is absent. reasons may be omitted, but adding a new enum value instead is strongly encouraged.

Request

Name	Type
options	ShutdownOptions

Response

Name	Type
payload	Admin_Shutdown_Result

SuspendToRam

Asks the device to enter the suspend to RAM (S3) power state. Currently only supported on x64. If a system state transition is already in progress then ZX_ERR_ALREADY_EXISTS is returned. If the device fails to reach the suspend power state then ZX_ERR_INTERNAL is returned. If the device successfully suspends, ZX_OK is returned when the device resumes.

Request

<EMPTY>

Response

Name	Type
payload	Admin_SuspendToRam_Result

RebootMethodsWatcher

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Allows components to be notified when Reboot related methods are called. Watchers will be given 'MAX_REBOOT_WATCHER_RESPONSE_TIME_SECONDS' to return before the system power state is changed. The channel will be used once to send a notification to the watcher. Once the watcher responds or the timeout expires, the channel will be closed by the client of RebootMethodsWatcher.

Replaced by RebootWatcher

OnReboot

Request

Name	Type
reason	RebootReason

Response

<EMPTY>

RebootMethodsWatcherRegister

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Allows components to register a callback that will be executed when a Reboot method is called. The main purpose of this protocol is to be able to track reboot reasons. Consider relying on Component Framework's orderly shutdown if you're looking at using this protocol.

Register

Register a watcher to be notified when a Reboot method is called. The Register channel will be used at most once to notify the watcher of an impending reboot and allow it the chance to respond.

Watchers can unregister by closing the underlying channel.

Replaced by RegisterWatcher.

Request

Name	Type
watcher	client_end:RebootMethodsWatcher

RegisterWatcher

Registers a watcher to be notified when a Reboot method is called.

Once the watcher has been successfully registered with the server, then the request will be completed and the RebootMethodsWatcherRegister channel will be left open (though a client is free to close it at this time).

If there is an error in registering the watcher, then the RebootMethodsWatcherRegister channel will be closed without completing the request.

The provided watcher channel will be used at most once to notify the watcher of an impending reboot and allow it the chance to respond.

Watchers can unregister by closing their RebootWatcher channel.

Request

Name	Type
watcher	client_end:RebootWatcher

Response

<EMPTY>

RegisterWithAck

Registers a watcher to be notified when a Reboot method is called.

Once the watcher has been successfully registered with the server, then the request will be completed and the RebootMethodsWatcherRegister channel will be left open (though a client is free to close it at this time).

If there is an error in registering the watcher, then the RebootMethodsWatcherRegister channel will be closed without completing the request.

The provided watcher channel will be used at most once to notify the watcher of an impending reboot and allow it the chance to respond.

Watchers can unregister by closing their RebootMethodsWatcher channel.

Replaced by RegisterWatcher.

Request

Name	Type
watcher	client_end:RebootMethodsWatcher

Response

<EMPTY>

RebootWatcher

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Allows components to be notified when Reboot related methods are called. Watchers will be given 'MAX_REBOOT_WATCHER_RESPONSE_TIME_SECONDS' to return before the system power state is changed. The channel will be used once to send a notification to the watcher. Once the watcher responds or the timeout expires, the channel will be closed by the client of RebootWatcher.

OnReboot

Request

Name	Type
options	RebootOptions

Response

<EMPTY>

ShutdownWatcher

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Allows components to be notified when the Shutdown method is called. Watchers will be given 'MAX_SHUTDOWN_WATCHER_RESPONSE_TIME_SECONDS' to return before the system power state is changed. The channel will be used once to send a notification to the watcher. Once the watcher responds or the timeout expires, the channel will be closed by the client of ShutdownWatcher.

OnShutdown

Request

Name	Type
options	ShutdownOptions

Response

Name	Type
payload	ShutdownWatcher_OnShutdown_Result

ShutdownWatcherRegister

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Allows components to register a callback that will be executed when the Shutdown method is called. The main purpose of this protocol is to be able to track shutdown reasons. Consider relying on Component Framework's orderly shutdown if you're looking at using this protocol.

RegisterWatcher

Registers a watcher to be notified when the Shutdown method is called.

Once the watcher has been successfully registered with the server, then the request will be completed and the ShutdownWatcherRegister channel will be left open (though a client is free to close it at this time).

If there is an error in registering the watcher, then the ShutdownWatcherRegister channel will be closed without completing the request.

The provided watcher channel will be used at most once to notify the watcher of an impending shutdown and allow it the chance to respond.

Watchers can unregister by closing their ShutdownWatcher channel.

Request

Name	Type
watcher	client_end:ShutdownWatcher

Response

Name	Type
payload	ShutdownWatcherRegister_RegisterWatcher_Result

STRUCTS

Admin_Mexec_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

Admin_PerformReboot_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

Admin_PowerFullyOn_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

Admin_Poweroff_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

Admin_RebootToBootloader_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

Admin_RebootToRecovery_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

Admin_Reboot_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

Admin_Shutdown_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

Admin_SuspendToRam_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

ShutdownWatcherRegister_RegisterWatcher_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

ShutdownWatcher_OnShutdown_Response

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

<EMPTY>

ENUMS

RebootReason strict

Type: uint32

Defined in fuchsia.hardware.power.statecontrol/reboot_reason.fidl

Why the system reboots.

Replaced by RebootReason2.

Name	Value	Description
USER_REQUEST	1
SYSTEM_UPDATE	2	A new system update has been downloaded.
RETRY_SYSTEM_UPDATE	8	Applying the system update has failed.
HIGH_TEMPERATURE	3
FACTORY_DATA_RESET	6
SESSION_FAILURE	4	Sessionmgr has failed.
SYSMGR_FAILURE	5	sysmgr crashed.
CRITICAL_COMPONENT_FAILURE	7	A critical system component has failed.
ZBI_SWAP	9	A boot partition change was effected.
OUT_OF_MEMORY	10	The system hit a critical low threshold of available memory.

RebootReason2 flexible

Type: uint32

Defined in fuchsia.hardware.power.statecontrol/reboot_reason.fidl

Why the system reboots.

Name	Value	Description
USER_REQUEST	1	The device rebooted because the end user of the device initiated the reboot. DO NOT USE for any code path not directly related to an end user explicit reboot action. Use DEVELOPER_REQUEST below instead.
DEVELOPER_REQUEST	13	The device rebooted because a developer initiated the reboot, typically via a shell command or similar interface, including within an automated test. Added: 28
SYSTEM_UPDATE	2	A new system update has been downloaded.
RETRY_SYSTEM_UPDATE	8	Applying the system update has failed.
HIGH_TEMPERATURE	3
FACTORY_DATA_RESET	6
SESSION_FAILURE	4	Sessionmgr has failed.
SYSMGR_FAILURE	5	sysmgr crashed.
CRITICAL_COMPONENT_FAILURE	7	A critical system component has failed.
ZBI_SWAP	9	A boot partition change was effected.
OUT_OF_MEMORY	10	The system hit a critical low threshold of available memory.
NETSTACK_MIGRATION	11	The Netstack component is changing versions.
ANDROID_UNEXPECTED_REASON	12	An Android-initiated reboot reason that Starnix doesn't recognize Added: 28
ANDROID_RESCUE_PARTY	14	Android called for the "RescueParty". Added: NEXT
ANDROID_CRITICAL_PROCESS_FAILURE	15	A critical Android process failed. Added: NEXT

ShutdownAction flexible

Type: uint32

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Name	Value	Description
POWEROFF	1
REBOOT	2
REBOOT_TO_RECOVERY	3
REBOOT_TO_BOOTLOADER	4

ShutdownReason flexible

Type: uint32

Defined in fuchsia.hardware.power.statecontrol/shutdown_reason.fidl

Why the system is shutting down.

Name	Value	Description
USER_REQUEST	1	The end user of the device initiated the shutdown. DO NOT USE for any code path not directly related to an end user explicit shutdown action. Use DEVELOPER_REQUEST below instead.
DEVELOPER_REQUEST	2	The developer initiated the shutdown, typically via a shell command or similar interface, including within an automated test.
SYSTEM_UPDATE	3	A new system update has been downloaded.
RETRY_SYSTEM_UPDATE	4	Applying the system update has failed.
HIGH_TEMPERATURE	5	The device has crossed the high temperature threshold.
FACTORY_DATA_RESET	6	The device is about to perform an FDR.
SESSION_FAILURE	7	Sessionmgr has failed.
CRITICAL_COMPONENT_FAILURE	8	A critical system component has failed.
ZBI_SWAP	9	A boot partition change was effected.
OUT_OF_MEMORY	10	The system hit a critical low threshold of available memory.
NETSTACK_MIGRATION	11	The Netstack component is changing versions.
ANDROID_UNEXPECTED_REASON	12	An Android-initiated shutdown reason that Starnix doesn't recognize.
ANDROID_RESCUE_PARTY	13	Android called for the "RescueParty".
ANDROID_CRITICAL_PROCESS_FAILURE	14	A critical Android process failed.

TABLES

RebootOptions

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

The options specified when a reboot is requested.

Ordinal	Field	Type	Description
1	reasons	vector<RebootReason2>:100	The set of reboot reasons that are responsible for this reboot request.

ShutdownOptions

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

The options specified when a shutdown is requested.

Ordinal	Field	Type	Description
1	action	ShutdownAction
2	reasons	vector<ShutdownReason>:100	The set of shutdown reasons that are responsible for this shutdown request.

UNIONS

Admin_Mexec_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	Admin_Mexec_Response
2	err	zx/Status

Admin_PerformReboot_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	Admin_PerformReboot_Response
2	err	zx/Status

Admin_PowerFullyOn_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	Admin_PowerFullyOn_Response
2	err	zx/Status

Admin_Poweroff_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	Admin_Poweroff_Response
2	err	zx/Status

Admin_RebootToBootloader_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	Admin_RebootToBootloader_Response
2	err	zx/Status

Admin_RebootToRecovery_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	Admin_RebootToRecovery_Response
2	err	zx/Status

Admin_Reboot_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	Admin_Reboot_Response
2	err	zx/Status

Admin_Shutdown_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	Admin_Shutdown_Response
2	err	zx/Status

Admin_SuspendToRam_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	Admin_SuspendToRam_Response
2	err	zx/Status

ShutdownWatcherRegister_RegisterWatcher_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	ShutdownWatcherRegister_RegisterWatcher_Response
3	framework_err	internal

ShutdownWatcher_OnShutdown_Result strict

Defined in fuchsia.hardware.power.statecontrol/admin.fidl

Ordinal	Variant	Type	Description
1	response	ShutdownWatcher_OnShutdown_Response
3	framework_err	internal

CONSTANTS

Name	Value	Type	Description
MAX_REBOOT_REASONS	100	uint8	The maximum number of reboot reasons that can be attributed to a single reboot request. Deprecated: NEXT Added: 26
MAX_REBOOT_WATCHER_RESPONSE_TIME_SECONDS	5	uint32	The maxium number of seconds the server will wait for responses from all RebootMethodsWatchers before changing the system power state. Deprecated: NEXT
MAX_SHUTDOWN_REASONS	100	uint8	The maximum number of shutdown reasons that can be attributed to a single shutdown request. Added: NEXT
MAX_SHUTDOWN_WATCHER_RESPONSE_TIME_SECONDS	5	uint32	The maximum number of seconds the server will wait for responses from all ShutdownWatchers before changing the system power state. Added: NEXT