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

fuchsia.update

PROTOCOLS

Manager

Defined in fuchsia.update/update.fidl

The Manager protocol is used by a client that wishes to either check for an update, or follow the status of ongoing updates.

The Manager provides a mechanism for checking for updates via the Manager.CheckNow message.

CheckNow

Immediately check for an update, and optionally track the state and progress of that update check.

  • request options Options for how this request should be performed. E.g. What kind of entity initiated this request? E.g. Is monitoring an existing update check that is already in process an acceptable alternative?

  • request monitor An interface on which to receive the status events for this update check. The monitor is only valid for this single update check, after that it will not receive any more notifications and will be closed.

  • error If an update check cannot be started, an error will be returned. The Monitor, if provided, will not receive any notifications.

Request

NameType
options CheckOptions
monitor Monitor?

Response

NameType
result Manager_CheckNow_Result

PerformPendingReboot

Performs any pending reboot of the system into an updated OS, if an update has been staged for the next system startup.

Should be used when the platform is configured to let the product drive reboot scheduling. If this method is called when the platform is not configured to let the product drive reboot scheduling, no reboot will occur, and the system will reboot on its own after an update.

In product-driven reboot configurations, the platform still contains a backstop for post-update reboots. This means that if an update is installed but the system has not rebooted before the backstop duration occurs, the update system will automatically reboot the system as a security measure. To avoid hitting this backstop, products which desire control over reboot timing should call this method roughly daily.

  • response rebooting true if the system is rebooting, false if no update was pending reboot.

Request

NameType

Response

NameType
rebooting bool

Monitor

Defined in fuchsia.update/update.fidl

Monitors a single update check.

Clients interested in receiving progress information for an update check should implement this protocol and provide the client end to Manager.CheckNow.

OnState

Receives a status update for this update check.

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 Manager. It does not wait for any acknowledgements before it moves on to the next state in its state machine. The Manager will simply queue up the states for the Monitor implementation to receive.

During the installing_update state, the Manager 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 check.
  • response The implementation is ready to receive the next State from the Manager.

Request

NameType
state State

Response

NameType

STRUCTS

Manager_CheckNow_Response

Defined in fuchsia.update/update.fidl

NameTypeDescriptionDefault

ENUMS

CheckNotStartedReason

Type: uint32

Defined in fuchsia.update/update.fidl

This is the set of values that are returned by an request to immediately check for an update.

NameValueDescription
INTERNAL 1

There was an internal error in starting the update check. The client is not expected to be able to do something meaningful about this error, except to try again later (after an appropriate delay and back-off in the event of multiple errors.

INVALID_OPTIONS 2

If there are required arguments or options (or option values in conflict), provided via the CheckOptions table to CheckNow, this error will be returned.

ALREADY_IN_PROGRESS 3

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

THROTTLED 4

The update check was not started, because too many requests to check for updates have been made by clients in a short period of time.

NOTE: Clients MUST NOT attempt to cause background update checks to happen at a more frequent rate than the fuchsia.update.Manager will do them.

If a client attempts to abuse this, it will be throttled.

Initiator

Type: uint32

Defined in fuchsia.update/update.fidl

Who or what initiated the update check.

NameValueDescription
USER 1

The update check was initiated by an interactive user, or the user is otherwise blocked and waiting for the result of this update check. This SHOULD only be used when there is a UI element or flow that a user has interacted with which has initiated this update check.

SERVICE 2

The update check was initiated by a service, not a user-facing aspect of the system.

TABLES

CheckOptions

Defined in fuchsia.update/update.fidl

Configuration options for an update check.

OrdinalNameTypeDescription
1 initiator Initiator

Who or what initiated this update attempt. This is taken as input to Policy, and may influence how the update check is performed.

This is a required field.

2 allow_attaching_to_existing_update_check bool

If an update check is already in progress, it's acceptable to instead attach a Monitor to that in-progress update instead of failing this request to check for updates. This may convert situations that would have resulted in the ALREADY_IN_PROGRESS to be treated as non-error cases.

CheckingForUpdatesData

Defined in fuchsia.update/update.fidl

This is the set of data associated with checking_for_updates. (currently none)

OrdinalNameTypeDescription

ErrorCheckingForUpdateData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the error_checking_for_update state. (currently none)

OrdinalNameTypeDescription

InstallationDeferredData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the installation_deferred_by_policy state.

OrdinalNameTypeDescription
1 update UpdateInfo

InstallationErrorData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the installation_error state. (currently none)

OrdinalNameTypeDescription
1 update UpdateInfo
2 installation_progress InstallationProgress

InstallationProgress

Defined in fuchsia.update/update.fidl

This describes the progress installing the update that has been made so far.

OrdinalNameTypeDescription
1 fraction_completed float32

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

InstallingData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the states involved with installing an update:

  • installing_update
  • waiting_for_reboot
OrdinalNameTypeDescription
1 update UpdateInfo
2 installation_progress InstallationProgress

NoUpdateAvailableData

Defined in fuchsia.update/update.fidl

This is the set of data associated with the no_update_available state. (currently none)

OrdinalNameTypeDescription

UpdateInfo

Defined in fuchsia.update/update.fidl

This describes the update that is available to be installed.

OrdinalNameTypeDescription
1 version_available string[128]

A string that describes the version that is available. This may be either a semantic version (A.B.C.D) or an opaque hash. Clients MUST not attempt to inspect this value, it is for display purposes only.

2 download_size uint64

The total number of bytes that may be downloaded to apply this update.

UNIONS

Manager_CheckNow_Result

Defined in fuchsia.update/update.fidl

NameTypeDescription
response Manager_CheckNow_Response
err CheckNotStartedReason

State

Defined in fuchsia.update/update.fidl

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

An update check 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

    +----------------------+     +---------------------------------+
    | checking_for_updates |---->|    error_checking_for_update    |
    +----------------------+     +---------------------------------+
               |
               |                 +---------------------------------+
               +---------------->|       no_update_available       |
               |                 +---------------------------------+
               |
               |                 +---------------------------------+
               +---------------->| installation_deferred_by_policy |
               |                 +---------------------------------+
               v
    +----------------------+     +---------------------------------+
    |  installing_update   |---->|       installation_error        |
    +----------------------+     +---------------------------------+
               |
               |                 +---------------------------------+
               +---------------->|       waiting_for_reboot        |
                                 +---------------------------------+
NameTypeDescription
checking_for_updates CheckingForUpdatesData

The Manager is currently checking for an update.

Next states:

  • installing_update update is available and allowed by policy
  • error_checking_for_update on error
  • update_deferred_by_policy update is available but deferred by policy
error_checking_for_update ErrorCheckingForUpdateData

The Manager encountered an error while checking for the existence of a a new update.

This is a terminal state

no_update_available NoUpdateAvailableData

There is not update available at this time.

This is a terminal state

installation_deferred_by_policy InstallationDeferredData

The Manager has found an available update but is not acting on it at this time due to policy restrictions.

This is a terminal state

installing_update InstallingData

The Manager is installing the available update.

Next states:

  • waiting_for_reboot on success
  • installation_error on error
waiting_for_reboot InstallingData

The update has been installed, and the device is waiting to be rebooted.

Next states:

  • (none, the device reboots)

This is a terminal state

installation_error InstallationErrorData

The Manager encountered an update in the installation of the update.

This is a terminal state

CONSTANTS

NameValueTypeDescription
MAX_VERSION_STRING_SIZE 128 uint32

This is the maximum length of a version string that will be returned by the protocol