Fournisseur VSIDL pour la réflexion

Le fournisseur VSIDL est un ensemble de bibliothèques et d'outils qui permettent aux packs de services de fournir des métadonnées déclarées VSIDL aux agents de la plate-forme SDV (Diagnostics, Télémétrie et SOME/IP).

En particulier, le fournisseur VSIDL permet aux agents SDV de découvrir les métadonnées suivantes :

• Descripteurs protobuf des messages et des services utilisés dans le catalogue VSIDL
• Mappages SOME/IP
• Déclarations de diagnostic des offres groupées de services

Guide du fournisseur VSIDL pour les développeurs de packs de services

La bibliothèque VSIDL Provider effectue les opérations suivantes.

• Localise les fichiers dans deux emplacements spécifiques :
  • Dans les Apexes des chemins définis dans sdv_service_bundle_metadata.
  • Sur l'image dans les chemins statiques.
• Lance des appels RPC pour interroger l'API sur les agents résidant sur la même VM ou sur des VM différentes.

Si vous développez un bundle de services, vous n'avez pas besoin de connaître les spécificités de la bibliothèque VSIDL Provider. Il vous suffit de suivre ces étapes pour permettre au fournisseur VSIDL de trouver les fichiers dont il a besoin au moment de l'exécution.

Générer des configurations d'exécution pour le catalogue

Les trois types de fichiers (schémas vsidl, déclarations de diagnostic, mappages someip) sont générés à partir de l'outil vsidl_rc_generator.

Utilisez l'outil binaire hôte vsidl_rc_generator avec les mêmes paramètres que ceux utilisés pour vsidlc et les paramètres supplémentaires suivants :

• --variant runtime-config-prebuilts
• --filegroup pour spécifier le nom du groupe de fichiers cible contenant tous les fichiers du catalogue (y compris Android.bp).

À titre indicatif, voici les paramètres vsidlc concernés :

• --catalog-path pour spécifier le chemin racine du catalogue.
• --dependency-catalog-path pour spécifier les catalogues dépendants.
• -- -path pour spécifier où écrire le Android.bp avec toutes les cibles genrule et prebuilt_etc générées.

Le générateur crée un fichier Android.bp avec les cibles genrule et prebuilt_etc pertinentes. En plus des blocs cibles générés dans Android.bp, des commentaires indiquent l'utilisation prévue de leurs cibles respectives.

Mettre à jour Android.bp d'APEX

Comme indiqué dans les commentaires du fichier Android.bp généré :

// Usage: add the following line to ... declaration

Vous devez ajouter ces cibles (sous les commentaires Usage indiqués) aux Android.bp qui définissent Apex :

apex {
    name: "some_apex_name",
    ...
    prebuilts: [
      // ADD THE prebuilt_etc TARGETS HERE
    ],
    ...

}

Mettre à jour sdv_service_bundles_manifest.textproto d'APEX

Dans les blocs sdv_service_bundle_metadata des fichiers sdv_service_bundles_manifest.textproto d'Apex, vous devez définir (uniquement pour les chemins d'accès applicables) :

sdv_service_bundle_metadata {
    ...
    vsidl_schemas_path: "etc/vsidl_provider/SomeFile-vsidl-config.binpb"
    diagnostics_config_path: "etc/vsidl_provider/SomeFile-diag-config.binpb"
    external_protocol_mapping_path: "etc/vsidl_provider/someip-config.binpb"
    ...
}

Ne définissez pas vos propres chemins. Copiez plutôt les chemins d'accès indiqués dans les commentaires du fichier Android.bp généré, qui se présentent comme suit :

// + vsidl_schemas_path:
// + diagnostics_config_path:
// + external_protocol_mapping_path:

Cela permet à l'instance du fournisseur VSIDL d'interroger les chemins spécifiés dans les entrées sdv_service_bundle_metadata respectives.

Ajouter des cibles à une image

Les fichiers Android.bp générés créent également des cibles qui peuvent être chargées directement sur l'image. Les commentaires indiquent également les cibles qui sont censées être utilisées de cette manière, en :

// Usage: add this target to the VM image.

La cible prebuilt_etc générée placera les fichiers créés avec les genrule à un emplacement prédéfini sur l'image. Vous devez inclure les cibles prebuilt_etc dans les fichiers *.mk respectifs (par exemple, device/google/sdv/sdv_core_base/sdv_samples_automotive_services.mk).

Guide du fournisseur VSIDL pour les développeurs de plates-formes

En règle générale, si vous développez un agent SDV qui a besoin de capacités de réflexion, vous pouvez utiliser la bibliothèque de fournisseur VSIDL.

L'API de la bibliothèque de fournisseurs VSIDL contient les fonctions suivantes :

    async fn get_publication_descriptor(
        &self,
        source_fqin: &ServiceFqin,
        unit_type: &UnitType,
    ) -> SdvResult<PublicationDescriptor>;

    async fn get_rpc_method_descriptor(
        &self,
        source_fqin: &ServiceFqin,
        unit_type: &UnitType,
        method_name: &str,
    ) -> SdvResult<RpcMethodDescriptor>;

    async fn get_message_descriptor(
        &self,
        source_fqin: &ServiceFqin,
        message_name: &str,
    ) -> SdvResult<MessageDescriptor>;

    async fn get_someip_mappings(&self, source_fqin: &ServiceFqin)
        -> SdvResult<Vec<SomeIpMapping>>;

    async fn get_diagnostics_declaration(
        &self,
        fqin: &ServiceFqin,
    ) -> SdvResult<DiagnosticsDeclaration>;

    async fn subscribe_availability_change_by_vm(
        &self,
        vm_name: &str,
    ) -> SdvResult<AvailabilityStream>;

où

pub type AvailabilityStream = Pin<Box<dyn Stream<Item = AvailabilityChangeEvent> + Send>>;

Toutes les fonctions sont interrogées à l'aide d'un paramètre source_fqin. Cela garantit que différents FQIN utilisant le même unit_type ou message_name renvoient les données correctes. Le paramètre dirige la bibliothèque de fournisseurs VSIDL vers l'APEX spécifique contenant le schéma de message le plus précis. Cela est nécessaire, car les APEX sont mis à jour indépendamment et peuvent utiliser différents schémas pour le même message ou service protobuf.

Utilisation de la fonction get_message_descriptor

Cela renvoie uniquement le pub struct MessageDescriptor du crate externe utilisé pour la réflexion. Un MessageDescriptor est un élément de métadonnées qui permet la réflexion, ce qui permet l'inspection et la manipulation dynamiques des messages protobuf au moment de l'exécution.

Utilisation de la fonction get_publication_descriptor

Cette fonction renvoie un PublicationDescriptor, qui est :

pub struct PublicationDescriptor {
    /// Message descriptor for publication.
    pub message_descriptor: MessageDescriptor,

    /// Information about the size of the publication message.
    pub size_metadata: SizeMetadata,
}

Le champ size_metadata contient des informations sur la taille et les contraintes du message d'une publication. Ces métadonnées sont dérivées de la configuration VSIDL.

pub struct SizeMetadata {
    /// Message size in bytes.
    pub message_size: u32,

    /// Message count.
    pub message_count: u32,

    /// VSIDL-declared size constraints for the message fields.
    pub field_size_constraints: HashMap<String, FieldSizeConstraint>,
}

pub struct FieldSizeConstraint {
    /// Max number of repeated fields allowed for the field.
    pub repeated_max_count: Option<u32>,

    /// Max size of variable sized types (string, bytes) in bytes.
    pub variable_type_max_size: Option<u32>,
}

Utilisation de la fonction get_rpc_method_descriptor

Cette fonction renvoie un RpcMethodDescriptor, qui est :

pub struct RpcMethodDescriptor {
    /// Message descriptor for RPC request.
    pub request_message: Option<MessageDescriptor>,

    /// Message descriptor for RPC response.
    pub response_message: Option<MessageDescriptor>,
}

Cette structure contient le MessageDescriptor pour les messages de requête et de réponse de la méthode RPC.

Utilisation de la fonction get_someip_mappings

Il s'agit d'une fonction permettant de récupérer les mappages de services SOME/IP locaux, qui sont définis dans core_services/vsidl/protos/sdv/someip/v1/someip.proto.

Utilisation de la fonction get_diagnostics_declaration

Il s'agit d'une fonction permettant de récupérer les déclarations de diagnostics, qui sont définies dans core_services/vsidl/protos/sdv/diagnostics/v1/diagnostics_syntax.proto.

Utilisation de la fonction subscribe_availability_change_by_vm

Cette fonction renvoie un flux de disponibilité pour une machine virtuelle spécifiée, qui sert de mécanisme de secours essentiel. Utilisez-le lorsque les appels d'API du fournisseur VSIDL standard échouent avec une erreur SdvStatusCode::Unavailable, ce qui permet au système d'attendre efficacement que l'interface du fournisseur VSIDL soit de nouveau en ligne.

Voici les principaux comportements de cette fonction :

• Émission immédiate : lors de l'abonnement, le flux émet l'état de disponibilité actuel de la machine virtuelle cible.
• Parité comportementale : le flux résultant se comporte de manière identique à la fonction subscribe_service_unit_change_by_name utilisée par ServiceDiscoveryManager.

Agent fournisseur VSIDL

Chaque VM exécute son propre agent fournisseur VSIDL, qui est essentiellement un serveur RPC qui transfère les requêtes sur l'API du fournisseur VSIDL (d'une instance locale de la bibliothèque dans l'agent). L'agent est utilisé pour interroger le fournisseur VSIDL sur une autre VM. Autrement dit, un service sur une VM peut interroger les métadonnées VSIDL d'une autre VM à l'aide de cet agent.

Utilisation de l'API dans la codebase

SOMEIP :

• get_publication_descriptor (tous les champs de structure sont utilisés)
• get_rpc_method_descriptor (tous les champs de structure sont utilisés)
• get_someip_mappings

Télémétrie :

• get_publication_descriptor (seul le champ message_descriptor est utilisé)
• get_rpc_method_descriptor (tous les champs de structure sont utilisés)

Diagnostic :

• get_message_descriptor
• get_diagnostics_declaration

Les différentes saveurs avec les différentes sources de données et priorités de sources sont disponibles dans core_services/vsidl/provider/src/vsidl_provider.rs.

La crate vsidl_provider propose plusieurs fonctions publiques permettant de créer des instances de fournisseur adaptées à différents agents SDV. Chaque configuration spécifie une chaîne unique de sources de données pour résoudre les données liées à VSIDL. Le tableau décrit le comportement de chaque fonction de constructeur :

Les sources de données du tableau font référence aux appels de la figure 1.