VSIDL Provider for reflection

Il fornitore VSIDL è un insieme di librerie e strumenti che consentono ai bundle di servizi di fornire metadati dichiarati in VSIDL agli agenti della piattaforma SDV (diagnostica, telemetria e SOME/IP).

In particolare, il provider VSIDL consente agli agenti SDV di rilevare i seguenti metadati:

• descrittori protobuf di messaggi e servizi utilizzati nel catalogo VSIDL
• Mappature SOME/IP
• dichiarazioni di diagnostica dei pacchetti di servizi

Guida del fornitore VSIDL per gli sviluppatori di pacchetti di servizi

La libreria del provider VSIDL esegue le seguenti operazioni.

• Individua i file in due posizioni specifiche:
  • All'interno degli Apex nei percorsi definiti in sdv_service_bundle_metadata.
  • Sull'immagine nei percorsi statici.
• Avvia chiamate RPC per eseguire query sull'API sugli agenti che risiedono sulle stesse VM o su VM diverse.

Se stai sviluppando un bundle di servizi, non devi conoscere i dettagli della libreria del fornitore VSIDL. Ti basterà seguire questi passaggi, che consentono al provider VSIDL di trovare i file di cui ha bisogno in fase di runtime.

Genera configurazioni di runtime per il catalogo

Tutti e tre i tipi di file (schemi vsidl, dichiarazioni diagnostiche, mapping someip) vengono generati dallo strumento vsidl_rc_generator.

Utilizza lo strumento binario host vsidl_rc_generator con gli stessi parametri utilizzati per vsidlc e i seguenti parametri aggiuntivi:

• --variant runtime-config-prebuilts
• --filegroup per specificare il nome di destinazione del gruppo di file che contiene tutti i file del catalogo (incluso Android.bp).

Per riferimento, i parametri vsidlc pertinenti sono i seguenti:

• --catalog-path per specificare il percorso principale del catalogo.
• --dependency-catalog-path per specificare i cataloghi dipendenti.
• -- -path per specificare dove scrivere il file Android.bp con tutti i target genrule e prebuilt_etc generati.

Il generatore creerà un file Android.bp con genrule e prebuilt_etc pertinenti. Oltre ai blocchi di target generati in Android.bp, ci saranno commenti che indicano l'utilizzo previsto dei rispettivi target.

Aggiorna Android.bp di APEX

Come indicato dai commenti del file Android.bp generato, che recitano:

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

Devi aggiungere questi target (sotto i commenti Usage indicati) al Android.bp che definisce Apex:

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

}

Aggiorna il file sdv_service_bundles_manifest.textproto di APEX

All'interno dei blocchi sdv_service_bundle_metadata dei file sdv_service_bundles_manifest.textproto di Apex, devi definire (solo per i percorsi applicabili):

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"
    ...
}

Non definire i tuoi percorsi. Copia invece i percorsi mostrati nei commenti del file Android.bp generato, che si trovano come:

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

In questo modo, l'istanza del provider VSIDL può eseguire query dai percorsi specificati nelle rispettive voci sdv_service_bundle_metadata.

Aggiungere target all'immagine

I file Android.bp generati creano anche target che possono essere caricati direttamente sull'immagine. I commenti indicano anche i target che devono essere utilizzati in questo modo:

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

La destinazione prebuilt_etc generata posizionerà i file generati con genrule in una posizione predefinita dell'immagine. Devi includere i target prebuilt_etc nei rispettivi file *.mk (ad esempio, device/google/sdv/sdv_core_base/sdv_samples_automotive_services.mk).

Guida per i fornitori di VSIDL per gli sviluppatori di piattaforme

In genere, se stai sviluppando SDV Agent che richiede funzionalità di reflection, puoi utilizzare la libreria del provider VSIDL.

L'API della libreria del provider VSIDL contiene le seguenti funzioni:

    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>;

dove

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

Tutte le funzioni vengono interrogate utilizzando un parametro source_fqin. In questo modo, FQIN diversi che utilizzano lo stesso unit_type o message_name restituiscono i dati corretti. Il parametro indirizza la libreria del provider VSIDL all'APEX specifico contenente lo schema del messaggio più accurato. Ciò è necessario perché gli APEX vengono aggiornati in modo indipendente e potrebbero utilizzare schemi diversi per lo stesso messaggio o servizio protobuf.

Utilizzo della funzione get_message_descriptor

Restituisce solo pub struct MessageDescriptor dalla crate esterna utilizzata per la reflection. Un MessageDescriptor è un metadato che consente la riflessione, abilitando l'ispezione e la manipolazione dinamica dei messaggi protobuf in fase di runtime.

Utilizzo della funzione get_publication_descriptor

Questa funzione restituisce un PublicationDescriptor, ovvero:

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

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

Il campo size_metadata contiene informazioni sulle dimensioni e sui vincoli di un messaggio di una pubblicazione. Questi metadati derivano dalla configurazione 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>,
}

Utilizzo della funzione get_rpc_method_descriptor

Questa funzione restituisce un RpcMethodDescriptor, ovvero:

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

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

Questa struttura contiene MessageDescriptor per i messaggi di richiesta e risposta del metodo RPC.

Utilizzo della funzione get_someip_mappings

Questa è una funzione per recuperare i mapping dei servizi SOME/IP locali, che sono definiti in core_services/vsidl/protos/sdv/someip/v1/someip.proto.

Utilizzo della funzione get_diagnostics_declaration

Si tratta di una funzione per recuperare le dichiarazioni di diagnostica, definite in core_services/vsidl/protos/sdv/diagnostics/v1/diagnostics_syntax.proto

Utilizzo della funzione subscribe_availability_change_by_vm

Questa funzione restituisce un flusso di disponibilità per una macchina virtuale specificata, fungendo da meccanismo di fallback critico. Utilizzalo quando le chiamate API del provider VSIDL standard non riescono e restituiscono un errore SdvStatusCode::Unavailable, consentendo al sistema di attendere in modo efficiente che l'interfaccia del provider VSIDL torni online.

I comportamenti chiave di questa funzione includono:

• Emissione immediata:al momento della sottoscrizione, lo stream emette lo stato di disponibilità attuale della macchina virtuale di destinazione.
• Parità comportamentale:lo stream risultante si comporta in modo identico alla funzione subscribe_service_unit_change_by_name utilizzata da ServiceDiscoveryManager.

VSIDL Provider Agent

Ogni VM esegue il proprio agente VSIDL Provider, che è essenzialmente un server RPC che inoltra le richieste all'API VSIDL Provider (di un'istanza locale della libreria all'interno dell'agente). L'agente viene utilizzato per eseguire query sul provider VSIDL su una VM diversa, ovvero un servizio su una VM può eseguire query sui metadati VSIDL da un'altra VM utilizzando questo agente.

Utilizzo dell'API nel codebase

SOMEIP:

• get_publication_descriptor (vengono utilizzati tutti i campi strutturati)
• get_rpc_method_descriptor (vengono utilizzati tutti i campi strutturati)
• get_someip_mappings

Telemetria:

• get_publication_descriptor (viene utilizzato solo il campo message_descriptor)
• get_rpc_method_descriptor (vengono utilizzati tutti i campi strutturati)

Diagnostica:

• get_message_descriptor
• get_diagnostics_declaration

Le varie versioni con le varie origini dati e priorità delle origini sono disponibili in core_services/vsidl/provider/src/vsidl_provider.rs.

Il crate vsidl_provider offre diverse funzioni pubbliche per creare istanze di provider personalizzate per diversi agenti SDV. Ogni configurazione specifica una catena unica di origini dati per risolvere i dati correlati a VSIDL. La tabella descrive il comportamento di ogni funzione costruttore:

Le origini dati della tabella fanno riferimento alle chiamate nella Figura 1.