Gestionnaire de mises à jour

Le gestionnaire de mises à jour effectue les mises à jour pour sa VM. Le gestionnaire de mises à jour coordonne le client, qui est fourni par l'intégrateur système. Le client fournit la charge utile de mise à jour et coordonne la mise à jour globale du véhicule. La mise à jour comprend les étapes suivantes :

1. PRÊT : aucune mise à jour n'est en cours.
2. PRÉPARATION : le gestionnaire de mises à jour écrit la mise à jour sur le disque, mais ne l'active pas.
3. ACTIVER : le gestionnaire de mise à jour active la mise à jour préparée afin qu'elle prenne effet après un redémarrage.
4. APPLIQUER : le Gestionnaire de mises à jour rend la mise à jour permanente.

Figure 1. Fonctionnement général du Gestionnaire de mises à jour.

Le gestionnaire de mises à jour est compatible avec les mises à jour du système et des packs de services, qui sont décrites sur cette page.

Mises à jour du système

L'OS Android utilise deux ensembles de partitions appelés emplacements, avec un seul emplacement actif à la fois. Une mise à jour du système écrit un nouvel ensemble de partitions dans l'emplacement inactif, et le système bascule vers l'emplacement actif lors du prochain redémarrage. Pour en savoir plus sur la création de mises à jour du système, consultez Mises à jour du système A/B.

Mises à jour des packs de services

Dans AAOS SDV, les packs de services regroupent les services dans des APEX. L'étape de mise à jour du bundle de services prépare de nouveaux fichiers APEX dans des sessions temporaires. Le système active ces bundles mis à jour après un redémarrage. Pour en savoir plus sur la création d'APEX de bundle de services, consultez Mises à jour des bundles de services.

Machine à états

Les requêtes du client et les événements des services système pilotent la machine à états du gestionnaire de mises à jour. Le gestionnaire de mise à jour est conçu pour être résilient. Il récupère son état et reprend le processus de mise à jour, même après des redémarrages ou des plantages inattendus.

Figure 2. Machine à états du gestionnaire de mises à jour.

API

Le gestionnaire de mises à jour fournit une API qui pilote le processus de mise à jour via la machine à états. L'API utilise VSIDL, qui est compatible avec les clients résidant dans n'importe quelle VM prenant en charge les communications SDV et fournit une notification d'échec de la requête.

Sécurité et accès

Le système restreint l'accès à l'API à l'aide de règles d'autorisation. Seul le client autorisé peut appeler le gestionnaire de mises à jour.

Informations sur votre actualité

Étant donné que les opérations de mise à jour peuvent être de longue durée, le Gestionnaire de mises à jour fournit des mises à jour d'état asynchrones. Les clients doivent surveiller l'état en s'abonnant aux mises à jour de l'état.

Gestion des abonnements

• S'abonner : les clients s'abonnent aux mises à jour de l'état en appelant la méthode SubscribeToStatusUpdates() :

  rpc SubscribeToStatusUpdates(SubscribeToStatusUpdatesRequest)
      returns (SubscribeToStatusUpdatesResponse) {}
  
  message SubscribeToStatusUpdatesRequest {}
  
  message SubscribeToStatusUpdatesResponse {}
  

  Avant d'appeler SubscribeToStatusUpdates(), le client doit démarrer une interface RPC qui implémente UpdateManagerListenerService.

• Se désabonner : les clients peuvent cesser de recevoir des mises à jour de l'état en appelant UnsubscribeFromStatusUpdates() :

  rpc UnsubscribeFromStatusUpdates(UnsubscribeFromStatusUpdatesRequest)
      returns (UnsubscribeFromStatusUpdatesResponse) {}
  
  message UnsubscribeFromStatusUpdatesRequest {}
  
  message UnsubscribeFromStatusUpdatesResponse {}
  

UpdateManagerListenerService

Les clients qui appellent SubscribeToStatusUpdates() sur UpdateManagerService doivent implémenter le service suivant pour recevoir des mises à jour de l'état :

service UpdateManagerListenerService {
  /* Called when there is a status update from the Update Manager. */
  rpc OnStatusUpdate(OnStatusUpdateRequest) returns (OnStatusUpdateResponse) {}
}

message OnStatusUpdateRequest {
  oneof status_update {
    UpdateManagerStatus update_manager_status = 1;
    UpdateProgress update_progress = 2;
  }
}

message OnStatusUpdateResponse {}

OnStatusUpdateRequest fournit l'un des deux messages possibles à l'aide du champ status_update :

1. UpdateManagerStatus : envoyé lorsque l'état du gestionnaire de mise à jour change.
2. UpdateProgress : envoyé pour indiquer la progression de la mise à jour pendant les états PREPARE et ACTIVATE_PRE_REBOOT, car le processus peut prendre beaucoup de temps.

État et messages d'erreur

Les messages d'état incluent des informations sur l'état et les éventuels échecs :

• UpdateManagerStatus : indique la phase actuelle de la mise à jour et la raison de l'échec, le cas échéant :

  message UpdateManagerStatus {
    /* The current state of the update */
    UpdateState update_state = 1;
    /* The reason for the failure, if the update failed */
    FailureReason failure_reason = 2;
  }
  
  enum UpdateState {
    /* The Update Manager is ready to accept a new update. */
    READY = 0;
    /* An update is being prepared. */
    PREPARE = 1;
    /* The update failed during the prepare step. Roll back the update to start a
     *   new update. */
    PREPARE_FAILURE = 2;
    /* The update was prepared successfully. */
    PREPARE_COMPLETE = 3;
    /* A rollback has started from the prepare step. When complete, transitions
     *   to READY. */
    PREPARE_ROLLBACK = 4;
    /* The prepared update is being activated. */
    ACTIVATE_PRE_REBOOT = 5;
    /* The update failed during the activate step before the reboot. Roll back the
     *   update to start a new update. */
    ACTIVATE_PRE_REBOOT_FAILURE = 6;
    /* The update was activated successfully. Reboot to complete activation. */
    ACTIVATE_PRE_REBOOT_COMPLETE = 7;
    /* A rollback has started from the activate pre-reboot step. When complete,
     *   transitions to READY. */
    ACTIVATE_PRE_REBOOT_ROLLBACK = 8;
    /* An update was successfully activated after the reboot. The update needs to
     *   be committed or rolled back to be completed. */
    ACTIVATE_POST_REBOOT_COMPLETE = 9;
    /* A rollback has started from the activate post-reboot step. */
    ACTIVATE_POST_REBOOT_ROLLBACK = 10;
    /* The rollback was completed successfully. Reboot to complete the
     *   rollback. */
    ACTIVATE_POST_REBOOT_ROLLBACK_COMPLETE = 11;
    /* The update is being committed. When complete, transitions to READY */
    COMMIT = 12;
    /* The prepare request is being cancelled */
    PREPARE_CANCEL = 13;
    /* The system update has started suspending */
    PREPARE_SUSPEND = 14;
    /* The system update has finished suspending */
    PREPARE_SUSPEND_COMPLETE = 15;
  }
  
  message FailureReason {
    /* The original error that triggered the failure */
    ErrorCode error_code = 1;
    /* Binder error message for most ErrorCodes. */
    string error_message = 2;
  }
  
  enum ErrorCode {
    Unspecified = 0;
    /* Error from UpdateEngine service */
    UpdateEngineError = 1;
    // Error from the ApexService
    ApexServiceError = 2;
    // Error from the BootControlService
    BootControlServiceError = 3;
    // Error from the VoldService
    VoldServiceError = 4;
  }
  

• UpdateProgress : indique l'état actuel du moteur de mise à jour lors des mises à jour du système :

  message UpdateProgress {
    /* Matches the enum UpdateStatus from the UpdateEngine service. */
    int32 status_code = 1;
  
    /* A value ranging from 0.0 to 1.0, 1.0 representing the process is complete. */
    float percentage = 2;
  }
  
  

Obtenir l'état immédiat

Vous pouvez récupérer l'état et la charge utile actuels à tout moment en appelant GetStatus(). Les messages SystemUpdatePayload et ServiceBundleUpdatePayload sont décrits dans Préparer.

rpc GetStatus(GetStatusRequest) returns (GetStatusResponse) {}

message GetStatusRequest {}

message GetStatusResponse {
  /* The status of the Update Manager */
  UpdateManagerStatus update_manager_status = 1;
  /* The current update payload, if one has been set through the Prepare() request */
  oneof payload {
    SystemUpdatePayload system_update_payload = 2;
    ServiceBundleUpdatePayload service_bundle_update_payload = 3;
  }
}

Préparer

La requête Prepare lance le processus de mise à jour en préparant la charge utile, mais le système attend pour activer la mise à jour :

rpc Prepare(PrepareRequest) returns (PrepareResponse) {}

message PrepareRequest {
  oneof payload {
    SystemUpdatePayload system_update_payload = 1;
    ServiceBundleUpdatePayload service_bundle_update_payload = 2;
  }
}

message PrepareResponse {}

Si la requête est valide, l'état passe à PREPARE et Update Manager lance la mise à jour.

Le type de charge utile détermine le type de mise à jour.

Charge utile de mise à jour du système

Une mise à jour du système utilise les données SystemUpdatePayload, qui nécessitent un chemin d'accès à une image de mise à jour OTA (Over The Air). Les autres paramètres sont analysés à partir de l'image, mais vous pouvez les spécifier pour remplacer les valeurs analysées.

message SystemUpdatePayload {
  /* Absolute path to the update image (e.g., /updates/ota_update.zip) */
  string payload = 1;

  /* Offset (in bytes) into the payload where the payload binary starts. */
  optional int64 payload_offset = 2;

  /* The amount of data (in bytes) to read from "payload" as the update payload. */
  optional int64 payload_size = 3;

  /* The header key value pairs to apply with the payload. */
  map<string, string> header_key_value_pairs = 4;
}

Le gestionnaire de mise à jour traite l'image OTA (fournie par le client dans le répertoire /data/ota_package) pour exécuter les étapes post-installation, mais il ne change pas l'emplacement de démarrage actif. Il passe ensuite à l'état PREPARE_COMPLETE en cas de réussite ou à l'état PREPARE_FAILURE en cas d'échec.

Suspension de la mise à jour du système

Vous ne pouvez mettre en pause que les mises à jour du système. Cette demande n'est valide que lorsque l'état est PREPARE.

• Suspendre : met la mise à jour en pause et fait passer l'état à PREPARE_SUSPEND.

  rpc Suspend(SuspendRequest) returns (SuspendResponse) {}
  
  message SuspendRequest {}
  
  message SuspendResponse {}
  

  En cas de réussite, l'état passe à PREPARE_SUSPEND_COMPLETE. En cas d'échec, l'état passe à PREPARE_FAILURE.

• Reprendre : reprend la mise à jour suspendue. Cette méthode n'est valide que dans l'état PREPARE_SUSPEND_COMPLETE.

  rpc Resume(ResumeRequest) returns (ResumeResponse) {}
  
  message ResumeRequest {}
  
  message ResumeResponse {}
  

  L'état repasse à PREPARE.

Charge utile de mise à jour du pack de services

Une mise à jour du bundle de services utilise le ServiceBundleUpdatePayload, qui contient les chemins d'accès aux fichiers APEX et définit la limite de tentatives d'activation.

message ServiceBundleUpdatePayload {
  /* Absolute path to an .apex file. Multiple .apex files can be included. */
  repeated string apex_path = 1;

  /* Number of boots to attempt activation before aborting. Must be > 0. */
  int32 boot_attempts = 2;
}

Le gestionnaire de mise à jour vérifie que les fichiers APEX sont correctement signés et les prépare dans une session. En cas de réussite, l'état passe à PREPARE_COMPLETE. En cas d'échec, l'état passe à PREPARE_FAILURE.

Activer

La requête Activate active la mise à jour préparée au prochain redémarrage.

rpc Activate(ActivateRequest) returns (ActivateResponse) {}

message ActivateRequest {}

message ActivateResponse {}

Avant le redémarrage

Le gestionnaire de mise à jour passe à l'état ACTIVATE_PRE_REBOOT lors de l'activation de la mise à jour. Le gestionnaire de mise à jour crée également un point de contrôle des données utilisateur qui prend effet lorsque le système est redémarré.

Les actions d'activation diffèrent selon le type de mise à jour :

• Mise à jour du système : le système exécute les étapes post-installation et définit l'emplacement de démarrage pour qu'il soit activé au prochain redémarrage.
• Mise à jour du bundle de services : le système marque la session APEX intermédiaire comme prête à être activée.

Si le système active la mise à jour, l'état passe à ACTIVATE_PRE_REBOOT_COMPLETE, ce qui indique que la VM est prête à être redémarrée. Sinon, l'état passe à ACTIVATE_PRE_REBOOT_FAILURE.

Après le redémarrage

Après le redémarrage, le système démarre en mode point de contrôle. Dans ce mode, le système n'enregistre aucune modification apportée à la partition de données utilisateur dans le stockage permanent. Si le système ne valide pas correctement la mise à jour, il rétablit l'état initial de ces modifications.

Limite de démarrage

Le système rétablit les modifications apportées à la partition de données utilisateur dans l'une des conditions suivantes :

• Le client envoie une requête Rollback() explicite et redémarre le système.
• Le système redémarre trop souvent sans que le client appelle Commit() ou Rollback(). La limite de démarrage diffère pour chaque type de mise à jour :
  • Mise à jour du système : l'implémentation BootControl définit cette valeur. Par exemple, la limite par défaut dans l'implémentation utilisée par les appareils Cuttlefish est de sept démarrages.
  • Mise à jour du bundle de services : le champ boot_attempts de l'ServiceBundleUpdatePayload fourni par le client définit cette valeur lorsque la requête Prepare() est effectuée.

Validation

Le système valide ensuite la mise à jour :

• Mise à jour du système : dm-verity vérifie si l'emplacement mis à jour est corrompu.
• Mise à jour du bundle de services : apexd vérifie la signature de chaque APEX et monte l'image de l'APEX dans le système de fichiers.

Si la validation réussit, l'état passe à ACTIVATE_POST_REBOOT_COMPLETE. Le Gestionnaire de mises à jour attend Commit() ou Rollback().

Si la validation échoue, le système redémarre. Lorsque le système atteint la limite de démarrage, il revient à l'état d'origine :

• Mise à jour du système : le système revient à l'emplacement d'origine.
• Mise à jour du bundle de services : les APEX mis à jour sont supprimés et les APEX d'origine sont réactivés.

Si la validation échoue pour un type de mise à jour, l'état passe à ACTIVATE_PRE_REBOOT_FAILURE après la restauration de l'état d'origine.

Rollback

La requête Rollback commence à rétablir l'état du système avant la mise à jour.

rpc Rollback(RollbackRequest) returns (RollbackResponse) {}

message RollbackRequest {}

message RollbackResponse {}

Vous pouvez envoyer une demande Rollback() dans de nombreux états. En fonction de l'état initial, le système effectue différentes actions et différents états s'ensuivent :

Commit

Cette requête indique que la mise à jour s'est terminée correctement et applique toutes les modifications de manière permanente.

rpc Commit(CommitRequest) returns (CommitResponse) {}

message CommitRequest {}

message CommitResponse {}

L'état passe à COMMIT lors de l'exécution des actions de validation :

• Mise à jour du système : le gestionnaire de mises à jour marque le démarrage comme réussi, ce qui empêche tout retour à une version antérieure ultérieur et sélectionne cet emplacement lors des démarrages suivants.
• Mise à jour du bundle de services : le gestionnaire de mises à jour marque la session APEX intermédiaire comme réussie, ce qui clôture la session de mise à jour et active définitivement les bundles.

Une fois que le système a validé la mise à jour, le gestionnaire de mise à jour valide le point de contrôle des données utilisateur. Le système enregistre toutes les nouvelles données utilisateur écrites lors de ce démarrage dans un espace de stockage permanent. Le Gestionnaire de mises à jour repasse à READY, ce qui indique que la mise à jour est terminée.

Désinstaller des APEX

La requête UninstallApex supprime la version /data des offres de services. Vous pouvez appeler UninstallApex dans n'importe quel état, mais la VM doit redémarrer pour que la désinstallation prenne effet. Par conséquent, évitez d'appeler UninstallApex pendant une mise à jour. UninstallApex ne supprime pas les APEX préinstallés, n'efface pas les données APEX ni ne supprime les versions APEX inactives.

rpc UninstallApex(UninstallApexRequest) returns (UninstallApexResponse) {}

message UninstallApexRequest {
  message ApexInfo {
    string module_name = 1;
    int64 version_code = 2;
  }
  repeated ApexInfo apexes = 1;
}

message UninstallApexResponse {}