fuchsia.update

Added: 7

PROTOCOLS

AttemptsMonitor

Defined in fuchsia.update/update.fidl

Monitors update attempts as they start.

Clients interested in receiving progress information for an update check should implement this protocol and provide the client end to Manager.MonitorAllUpdateChecks. The Manager will close the client end of the AttemptsMonitor if there are more than 2 outstanding requests.

OnStart

Called when a new update attempt has started.

Arguments:

  • |options| Options for how this request should be performed.
  • |monitor| A protocol on which to receive progress updates.

Request

NameType
options AttemptOptions
monitor server_end:Monitor

Response

<EMPTY>

CommitStatusProvider

Defined in fuchsia.update/commit.fidl

A reporter for whether the currently booted system is committed. When an update is committed, this means:

  • The currently booted slot is marked as healthy (e.g. successfully booted).
  • The alternate slot (if present) is marked as unbootable.
  • The system will not roll back to the previous version of the OS on reboot.
  • The previous version of the OS may be garbage collected.

Until the update is committed, the system retains the prior version of the OS. That way, if we discover the newly written version is bad (e.g. it cannot itself update), then the system can fall back to the previous committed version.

IsCurrentSystemCommitted

Determines whether the currently booted system is committed, and immediately returns an EventPair.

  • If the currently booted system is committed, the ZX_USER_SIGNAL_0 signal is asserted on the EventPair, e.g. the signal is asserted before the EventPair is returned.
  • If the commit is pending, no signals are asserted on the EventPair. When the system is committed, ZX_USER_SIGNAL_0 is asserted on the EventPair.
  • If the system fails to commit the currently booted version, the system will reboot and terminate the component serving CommitStatusProvider, which will assert ZX_EVENTPAIR_PEER_CLOSED. At this point, any remaining EventPairs will observe the ZX_EVENTPAIR_PEER_CLOSED signal.
  • response event an EventPair with rights ZX_RIGHTS_BASIC.

Request

<EMPTY>

Response

NameType
event handle<eventpair>

Listener

Defined in fuchsia.update/update.fidl

Used by components to wait for the first software update check to complete.

Added: HEAD

WaitForFirstUpdateCheckToComplete

This is a hanging get. It may be called at any time. It will only return if the software update checker has completed its post-boot check (with or without error) and is not trying to reboot.

Request

<EMPTY>

Response

<EMPTY>

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 client_end:Monitor?

Response

NameType
payload Manager_CheckNow_Result

MonitorAllUpdateChecks

Monitor all update attempts as they start, as well as an in-progress attempt, if there is one.

Arguments:

  • |attempts_monitor| A protocol on which to receive |Monitor| instances as update attempts start.

Request

NameType
attempts_monitor client_end:AttemptsMonitor

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

<EMPTY>

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

<EMPTY>

STRUCTS

Manager_CheckNow_Response

Defined in fuchsia.update/update.fidl

<EMPTY>

ENUMS

CheckNotStartedReason strict

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
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.
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.
3

There was already another update check in progress when this request was made. A new update check will not be started.
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 strict

Type: uint32

Defined in fuchsia.update/update.fidl

Who or what initiated the update check.

NameValueDescription
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.
2

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

InstallationDeferralReason flexible

Type: uint32

Defined in fuchsia.update/update.fidl

This is the set of values that are provided when an update installation is deferred.

NameValueDescription
1

The update was not installed because the currently booted system is not committed. Consumers are encouraged to use the CommitStatusProvider to determine when to retry the update check such that the update will be installed.

TABLES

AttemptOptions

Defined in fuchsia.update/update.fidl

Details for an update attempt monitor.

OrdinalFieldTypeDescription
initiator Initiator

Who or what initiated this update attempt. This may influence how the update check is performed.

CheckOptions

Defined in fuchsia.update/update.fidl

Configuration options for an update check.

OrdinalFieldTypeDescription
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.
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)

OrdinalFieldTypeDescription

ErrorCheckingForUpdateData

Defined in fuchsia.update/update.fidl

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

OrdinalFieldTypeDescription

InstallationDeferredData

Defined in fuchsia.update/update.fidl

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

OrdinalFieldTypeDescription
update UpdateInfo
deferral_reason InstallationDeferralReason

InstallationErrorData

Defined in fuchsia.update/update.fidl

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

OrdinalFieldTypeDescription
update UpdateInfo
installation_progress InstallationProgress

InstallationProgress

Defined in fuchsia.update/update.fidl

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

OrdinalFieldTypeDescription
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

OrdinalFieldTypeDescription
update UpdateInfo
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)

OrdinalFieldTypeDescription

UpdateInfo

Defined in fuchsia.update/update.fidl

This describes the update that is available to be installed.

OrdinalFieldTypeDescription
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.
download_size uint64

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

Whether the update was marked as urgent. Default is false.

UNIONS

Manager_CheckNow_Result strict

Defined in fuchsia.update/update.fidl

OrdinalVariantTypeDescription
response Manager_CheckNow_Response
err CheckNotStartedReason

State strict

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        |
                                 +---------------------------------+
OrdinalVariantTypeDescription
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