| // Copyright 2019 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library fuchsia.update.installer; |
| |
| /// 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`]. |
| protocol Monitor { |
| /// 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`]. |
| OnState(State state) -> (); |
| }; |
| |
| /// 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 | |
| /// +----------------+ |
| /// ``` |
| union State { |
| /// 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. |
| 1: PrepareData prepare; |
| |
| /// Fetching packages and kernel images. |
| /// |
| /// Next States: |
| /// * `stage` required assets are ready to be staged for next boot. |
| /// * `fail_fetch` on error. |
| 2: FetchData fetch; |
| |
| /// 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. |
| 3: StageData stage; |
| |
| /// 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. |
| /// |
| 4: WaitToRebootData wait_to_reboot; |
| |
| /// The installer has initiated a system reboot into the updated OS. |
| /// |
| /// **This is a terminal state** |
| /// |
| 5: RebootData reboot; |
| |
| /// The initiator specifically requested to skip the reboot, but a reboot is |
| /// still required to complete the update. |
| /// |
| /// **This is a terminal state** |
| /// |
| 6: DeferRebootData defer_reboot; |
| |
| /// The update is complete and no reboot was required. |
| /// |
| /// **This is a terminal state** |
| /// |
| 7: CompleteData complete; |
| |
| /// An error occured while preparing the install. |
| /// |
| /// **This is a terminal state** |
| /// |
| 8: FailPrepareData fail_prepare; |
| |
| /// An error occured while fetching the required artifacts. |
| /// |
| /// **This is a terminal state** |
| /// |
| 9: FailFetchData fail_fetch; |
| |
| /// An error occured while staging the new OS. |
| /// |
| /// **This is a terminal state** |
| /// |
| 10: FailStageData fail_stage; |
| }; |
| |
| /// Data associated with [`State.prepare`]. |
| table PrepareData { |
| }; |
| |
| /// Data associated with [`State.fetch`]. |
| table FetchData { |
| 1: UpdateInfo info; |
| 2: InstallationProgress progress; |
| }; |
| |
| /// Data associated with [`State.stage`]. |
| table StageData { |
| 1: UpdateInfo info; |
| 2: InstallationProgress progress; |
| }; |
| |
| /// Data associated with [`State.wait_to_reboot`]. |
| table WaitToRebootData { |
| 1: UpdateInfo info; |
| 2: InstallationProgress progress; |
| }; |
| |
| /// Data associated with [`State.reboot`]. |
| table RebootData { |
| 1: UpdateInfo info; |
| 2: InstallationProgress progress; |
| }; |
| |
| /// Data associated with [`State.defer_reboot`]. |
| table DeferRebootData { |
| 1: UpdateInfo info; |
| 2: InstallationProgress progress; |
| }; |
| |
| /// Data associated with [`State.complete`]. |
| table CompleteData { |
| 1: UpdateInfo info; |
| 2: InstallationProgress progress; |
| }; |
| |
| /// Data associated with [`State.fail_prepare`]. |
| table FailPrepareData { |
| 1: PrepareFailureReason reason; |
| }; |
| |
| /// Data associated with [`State.fail_fetch`]. |
| table FailFetchData { |
| 1: UpdateInfo info; |
| 2: InstallationProgress progress; |
| 3: FetchFailureReason reason; |
| }; |
| |
| /// Data associated with [`State.fail_stage`]. |
| table FailStageData { |
| 1: UpdateInfo info; |
| 2: InstallationProgress progress; |
| }; |
| |
| /// Metadata for an update. Once a field is populated during an installation |
| /// attempt, the value will not change. |
| table UpdateInfo { |
| /// The total number of bytes that may be downloaded to apply this update. |
| /// Optional, the installer may not be able to provide this value. |
| 1: uint64 download_size; |
| }; |
| |
| /// Current progress for an installation attempt. |
| table InstallationProgress { |
| /// The fraction [0-1.0f] of the installation that has been completed. |
| 1: float32 fraction_completed; |
| |
| /// 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. |
| 2: uint64 bytes_downloaded; |
| }; |
| |
| /// The set of values provided when an installation attempt fails on [`State.prepare`]. |
| enum PrepareFailureReason { |
| /// The prepare failed because of some other reason. |
| INTERNAL = 0; |
| |
| /// The prepare failed because the system does not have enough space to fetch |
| /// the update package. |
| OUT_OF_SPACE = 1; |
| }; |
| |
| /// The set of values provided when an installation attempt fails on [`State.fetch`]. |
| enum FetchFailureReason { |
| /// The fetch failed because of some other reason. |
| INTERNAL = 0; |
| |
| /// The fetch failed because the system does not have enough space to fetch a package. |
| OUT_OF_SPACE = 1; |
| }; |