Google is committed to advancing racial equity for Black communities. See how.

fuchsia.update.installer

PROTOCOLS

Installer

Defined in fuchsia.update.installer/installer.fidl

Updates the system.

This protocol is intended to be consumed by a component capable of discovering when to update and what version of the system to install.

GetLastUpdateResult

Get the status of the last update attempt. If this device hasn't attempted an update since the last factory reset, every field in the result will be absent.

  • response info the status of the last update attempt, if available.

Request

NameType

Response

NameType
info UpdateResult

GetUpdateResult

Get the status of the given update attempt, if it exists. If this device hasn't attempted an update with the given attempt_id or forgotten about that attempt, every field in the result will be absent.

  • request attempt_id UUID identifying the requested update attempt.
  • response info the status of the last update attempt, if available.

Request

NameType
attempt_id AttemptId

Response

NameType
info UpdateResult

MonitorUpdate

Attempt to monitor a specific update attempt, if it exists. This request will not start an update if one is not already running.

  • request attempt_id UUID identifying the requested update attempt. If not given, monitor any active update attempt.
  • request monitor A protocol on which to receive progress updates.
  • response attached Whether or not the provided monitor was attached to an in-progress update attempt. If false, monitor will be closed by the server.

Request

NameType
attempt_id AttemptId
monitor Monitor

Response

NameType
attached bool

StartUpdate

Start an update if one is not running, or attach to a pending update attempt if one is running and Options.allow_attach_to_existing_attempt is true. If an update attempt is started or attached to, provide status updates through monitor.

  • request url The fuchsia-pkg URL of the update package to update to.
  • request options Configuration options for this update attempt. Ignored or merged with the existing options if an update attempt is already in progress.
  • request monitor A protocol on which to receive progress updates.
  • request reboot_controller An optional protocol to control the timing of the reboot into the update system. If not provided, the update attempt will initiate the reboot as soon as it is ready.
  • response attempt_id UUID identifying this update attempt. For updates that require a reboot, components may use this identifier to disambiguate the completion of this update attempt from new update attempts that start post-reboot.

Request

NameType
url fuchsia.pkg/PackageUrl
options Options
monitor Monitor
reboot_controller request<RebootController>?

Response

NameType
result Installer_StartUpdate_Result

Monitor

Defined in fuchsia.update.installer/progress.fidl

Monitors a single update installation attempt.

Clients interested in receiving progress information for an update attempt should implement this protocol and provide the client end to Installer.StartUpdate or Installer.MonitorUpdate.

OnState

Receives a status update for this installation attempt.

This request will be called for all state changes, skipping none. However, message delivery is throttled by the rate at which the implementation acknowledges the messages.

The throttled delivery doesn't impact the underlying state of the Installer. It does not wait for any acknowledgements before it moves on to the next state in its state machine. The Installer will simply queue up the states for the Monitor implementor to receive.

During states with data that changes as the updage progress, the Installer may, at its discretion, collapse redundant information like the fraction completed, in the event that the Monitor implementation is not responding to the OnState() requests in a timely manner.

  • request state The new state of the update installation attempt.
  • response The implementation is ready to receive the next State from the Installer.

Request

NameType
state State

Response

NameType

RebootController

Defined in fuchsia.update.installer/installer.fidl

Controls the timing of the reboot into the updated system.

If the client end of a RebootController is closed without calling RebootController.Detach(), the update attempt will fall back to the default behavior of rebooting as soon as it is ready.

Detach

Informs the update attempt that it should wait to reboot indefinitely, even if this RebootController connection is dropped.

Request

NameType

Unblock

Informs the update attempt that it may reboot when ready, unblocking a pending reboot if it is already ready to reboot.

If a controller is dropped without sending this request or RebootController.Detach, the update attempt reclaims control of the timing of the reboot, behaving as if the update attempt was not given a RebootController at all.

Request

NameType

STRUCTS

Installer_StartUpdate_Response

Defined in fuchsia.update.installer/installer.fidl

NameTypeDescriptionDefault
attempt_id AttemptId No default

ENUMS

Initiator

Type: uint32

Defined in fuchsia.update.installer/installer.fidl

Who or what initiated the update installation.

NameValueDescription
USER 0

The install was initiated by an interactive user, or the user is otherwise blocked and waiting for the result of this update.

SERVICE 1

The install was initiated by a service, in the background.

UpdateNotStartedReason

Type: uint32

Defined in fuchsia.update.installer/installer.fidl

The set of values that are returned by an request to start an update.

NameValueDescription
ALREADY_IN_PROGRESS 1

There was already another update attempt in progress when this request was made. A new update attempt will not be started.

TABLES

CompleteData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.complete.

OrdinalNameTypeDescription
1 info UpdateInfo
2 progress InstallationProgress

DeferRebootData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.defer_reboot.

OrdinalNameTypeDescription
1 info UpdateInfo
2 progress InstallationProgress

FailFetchData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.fail_fetch.

OrdinalNameTypeDescription
1 info UpdateInfo
2 progress InstallationProgress

FailPrepareData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.fail_prepare.

OrdinalNameTypeDescription

FailStageData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.fail_stage.

OrdinalNameTypeDescription
1 info UpdateInfo
2 progress InstallationProgress

FetchData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.fetch.

OrdinalNameTypeDescription
1 info UpdateInfo
2 progress InstallationProgress

InstallationProgress

Defined in fuchsia.update.installer/progress.fidl

Current progress for an installation attempt.

OrdinalNameTypeDescription
1 fraction_completed float32

The fraction [0-1.0f] of the installation that has been completed.

2 bytes_downloaded uint64

The number of bytes downloaded during this installation attempt. Less than or equal to UpdateInfo.download_size and only present if that field is also present.

Options

Defined in fuchsia.update.installer/installer.fidl

Configuration options for an update attempt.

OrdinalNameTypeDescription
1 initiator Initiator

What initiated this update attempt. Required.

2 allow_attach_to_existing_attempt bool

If an update is already in progress, it's acceptable to instead attach a Monitor to that in-progress update instead of failing this request to install the update. Setting this option to true may convert situations that would have resulted in the ALREADY_IN_PROGRESS to be treated as non-error cases. A controller, if provided, will be ignored if the running update attempt already has a controller.

3 should_write_recovery bool

Determines if the installer should update the recovery partition if an update is available. Defaults to true.

PrepareData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.prepare.

OrdinalNameTypeDescription

RebootData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.reboot.

OrdinalNameTypeDescription
1 info UpdateInfo
2 progress InstallationProgress

StageData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.stage.

OrdinalNameTypeDescription
1 info UpdateInfo
2 progress InstallationProgress

UpdateInfo

Defined in fuchsia.update.installer/progress.fidl

Metadata for an update. Once a field is populated during an installation attempt, the value will not change.

OrdinalNameTypeDescription
1 download_size uint64

The total number of bytes that may be downloaded to apply this update. Optional, the installer may not be able to provide this value.

UpdateResult

Defined in fuchsia.update.installer/installer.fidl

Metadata about a prior update attempt.

OrdinalNameTypeDescription
1 attempt_id AttemptId

Unique identifier for this specific update attempt. Always present.

2 url fuchsia.pkg/PackageUrl

fuchsia-pkg:// url for the update package associated with this update attempt. Always present.

3 options Options

Configuration options for this update attempt. Always present.

4 state State

Terminal state of this update attempt. Always present if the update failed. None if the update succeeded.

WaitToRebootData

Defined in fuchsia.update.installer/progress.fidl

Data associated with State.wait_to_reboot.

OrdinalNameTypeDescription
1 info UpdateInfo
2 progress InstallationProgress

UNIONS

Installer_StartUpdate_Result

Defined in fuchsia.update.installer/installer.fidl

NameTypeDescription
response Installer_StartUpdate_Response
err UpdateNotStartedReason

State

Defined in fuchsia.update.installer/progress.fidl

The set of states that a Monitor can receive during an update installation attempt.

An installation attempt ends when it enters a terminal state, denoted below as the states on the right-hand side of the diagram with no arrows leading out of them.

State Machine Diagram

    +----------------+     +----------------+
    |    prepare     |---->|  fail_prepare  |
    +----------------+     +----------------+
            |
            v
    +----------------+     +----------------+
    |     fetch      |---->|   fail_fetch   |
    +----------------+     +----------------+
            |
            v
    +----------------+     +----------------+
    |     stage      |---->|   fail_stage   |
    +----------------+     +----------------+
            |
            |              +----------------+
            +------------->|    complete    |
            |              +----------------+
            v
    +----------------+     +----------------+
    | wait_to_reboot |---->|  defer_reboot  |
    +----------------+     +----------------+
            |
            |              +----------------+
            +------------->|     reboot     |
                           +----------------+
NameTypeDescription
prepare PrepareData

Fetching required metadata to begin the update and verifying system state.

Next States:

  • fetch system is ready to install the update.
  • fail_prepare on error.
fetch FetchData

Fetching packages and kernel images.

Next States:

  • stage required assets are ready to be staged for next boot.
  • fail_fetch on error.
stage StageData

Writing kernel images and preparing to switch over to the new system.

Next States:

  • wait_to_reboot if a reboot is necessary to complete the update.
  • complete if no reboot is necessary to complete the update.
  • fail_stage on error.
wait_to_reboot WaitToRebootData

The system is configured to boot the updated OS on next boot, and the installer is waiting for the trigger to reboot the system.

Next States:

  • reboot when the installer decides it is time to initiate the reboot.
  • defer_reboot if the initiator specifically requests to not reboot.
reboot RebootData

The installer has initiated a system reboot into the updated OS.

This is a terminal state

defer_reboot DeferRebootData

The initiator specifically requested to skip the reboot, but a reboot is still required to complete the update.

This is a terminal state

complete CompleteData

The update is complete and no reboot was required.

This is a terminal state

fail_prepare FailPrepareData

An error occured while preparing the install.

This is a terminal state

fail_fetch FailFetchData

An error occured while fetching the required artifacts.

This is a terminal state

fail_stage FailStageData

An error occured while staging the new OS.

This is a terminal state

TYPE ALIASES

NameValueDescription
AttemptId string[36]