Penyedia VSIDL untuk refleksi

Penyedia VSIDL adalah sekumpulan library dan alat yang memungkinkan paket layanan menyediakan metadata yang dideklarasikan VSIDL ke agen platform SDV (Diagnostik, Telemetri, dan SOME/IP).

Secara khusus, penyedia VSIDL memungkinkan Agen SDV menemukan metadata berikut:

• deskriptor protobuf pesan dan layanan yang digunakan dalam katalog VSIDL
• pemetaan SOME/IP
• deklarasi diagnostik Paket Layanan

Panduan Penyedia VSIDL untuk developer paket layanan

Library Penyedia VSIDL melakukan operasi berikut.

• Menemukan file di dua tempat tertentu:
  • Dalam Apexes di jalur yang ditentukan dalam sdv_service_bundle_metadata.
  • Pada gambar di jalur statis.
• Memulai panggilan RPC untuk mengkueri API pada agen yang berada di VM yang sama atau berbeda.

Jika Anda mengembangkan paket layanan, Anda tidak perlu mengetahui spesifikasi library Penyedia VSIDL. Anda hanya perlu mengikuti langkah-langkah berikut, yang memungkinkan Penyedia VSIDL menemukan file yang diperlukan saat runtime.

Membuat Konfigurasi Runtime untuk Katalog

Ketiga jenis file (skema vsidl, deklarasi diagnostik, pemetaan someip) dibuat dari alat vsidl_rc_generator.

Gunakan alat biner host vsidl_rc_generator dengan parameter yang sama seperti yang digunakan untuk vsidlc dan parameter tambahan berikut:

• --variant runtime-config-prebuilts
• --filegroup untuk menentukan nama target filegroup yang berisi semua file katalog (termasuk Android.bp).

Sebagai referensi, parameter vsidlc yang relevan adalah sebagai berikut:

• --catalog-path untuk menentukan jalur root katalog.
• --dependency-catalog-path untuk menentukan katalog dependen.
• -- -path untuk menentukan tempat menulis Android.bp dengan semua target genrule dan prebuilt_etc yang dihasilkan.

Generator akan membuat file Android.bp dengan target genrule dan prebuilt_etc yang relevan. Selain blok target yang dihasilkan di Android.bp, akan ada komentar yang menunjukkan penggunaan target masing-masing.

Memperbarui Android.bp APEX

Seperti yang ditunjukkan oleh komentar file Android.bp yang dihasilkan, yang berbunyi:

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

Anda harus menambahkan target ini (di bawah komentar Usage yang ditunjukkan) ke Android.bp yang menentukan Apex:

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

}

Memperbarui sdv_service_bundles_manifest.textproto APEX

Dalam blok sdv_service_bundle_metadata dari file sdv_service_bundles_manifest.textproto Apex, Anda harus menentukan (hanya untuk jalur yang berlaku):

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

Jangan tentukan jalur Anda sendiri. Sebagai gantinya, salin jalur yang ditampilkan dalam komentar file Android.bp yang dihasilkan, yang ditemukan sebagai:

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

Tindakan ini memungkinkan instance Penyedia VSIDL melakukan kueri dari jalur yang ditentukan oleh dalam entri sdv_service_bundle_metadata masing-masing.

Menambahkan Target ke Gambar

File Android.bp yang dihasilkan juga membuat target yang dapat dimuat langsung pada gambar. Komentar juga menunjukkan target yang seharusnya digunakan dengan cara ini, dengan:

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

Target prebuilt_etc yang dihasilkan akan menempatkan file yang dibuat dengan genrule di lokasi yang telah ditentukan sebelumnya pada gambar. Anda harus menyertakan target prebuilt_etc dalam file *.mk masing-masing (misalnya, device/google/sdv/sdv_core_base/sdv_samples_automotive_services.mk).

Panduan Penyedia VSIDL untuk Developer Platform

Umumnya, jika Anda mengembangkan Agen SDV yang memerlukan kemampuan refleksi, Anda dapat menggunakan library penyedia VSIDL.

API library Penyedia VSIDL berisi fungsi berikut:

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

di mana

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

Semua fungsi dikueri menggunakan parameter source_fqin. Hal ini memastikan bahwa FQIN yang berbeda menggunakan unit_type atau message_name yang sama akan menampilkan data yang benar. Parameter ini mengarahkan library penyedia VSIDL ke APEX tertentu yang berisi skema pesan paling akurat. Hal ini diperlukan karena APEX diperbarui secara independen dan dapat menggunakan skema yang berbeda untuk pesan atau layanan protobuf yang sama.

Penggunaan fungsi get_message_descriptor

Fungsi ini hanya menampilkan pub struct MessageDescriptor dari crate eksternal yang digunakan untuk refleksi. MessageDescriptor adalah bagian metadata yang memungkinkan refleksi, sehingga memungkinkan pemeriksaan dan manipulasi pesan protobuf yang dinamis saat runtime.

Penggunaan fungsi get_publication_descriptor

Fungsi ini menampilkan PublicationDescriptor, yaitu:

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

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

Kolom size_metadata berisi informasi tentang ukuran dan batasan pesan publikasi. Metadata ini berasal dari konfigurasi 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>,
}

Penggunaan fungsi get_rpc_method_descriptor

Fungsi ini menampilkan RpcMethodDescriptor, yaitu:

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

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

Struct ini menyimpan MessageDescriptor untuk pesan permintaan dan respons metode RPC.

Penggunaan fungsi get_someip_mappings

Ini adalah fungsi untuk mengambil pemetaan layanan SOME/IP lokal, yang ditentukan dalam core_services/vsidl/protos/sdv/someip/v1/someip.proto.

Penggunaan fungsi get_diagnostics_declaration

Ini adalah fungsi untuk mengambil deklarasi diagnostik, yang ditentukan dalam core_services/vsidl/protos/sdv/diagnostics/v1/diagnostics_syntax.proto

Penggunaan fungsi subscribe_availability_change_by_vm

Fungsi ini menampilkan aliran ketersediaan untuk mesin virtual tertentu, yang berfungsi sebagai mekanisme penggantian penting. Gunakan fungsi ini saat panggilan VSIDL Provider API standar gagal dengan error SdvStatusCode::Unavailable, sehingga sistem dapat menunggu secara efisien hingga antarmuka penyedia VSIDL kembali online.

Perilaku utama fungsi ini mencakup:

• Emisi langsung: Setelah berlangganan, aliran akan memancarkan status ketersediaan mesin virtual target saat ini.
• Paritas perilaku: Aliran yang dihasilkan berperilaku sama dengan fungsi subscribe_service_unit_change_by_name yang digunakan oleh ServiceDiscoveryManager.

Agen Penyedia VSIDL

Setiap VM menjalankan agen Penyedia VSIDL-nya sendiri, yang pada dasarnya adalah server RPC yang meneruskan permintaan pada VSIDL Provider API (dari instance library lokal dalam agen). Agen ini digunakan untuk mengkueri Penyedia VSIDL di VM lain, yaitu layanan di satu VM dapat mengkueri metadata VSIDL dari VM lain menggunakan agen ini.

Penggunaan API dalam codebase

SOMEIP:

• get_publication_descriptor (semua kolom struct digunakan)
• get_rpc_method_descriptor (semua kolom struct digunakan)
• get_someip_mappings

Telemetri:

• get_publication_descriptor (hanya kolom message_descriptor yang digunakan)
• get_rpc_method_descriptor (semua kolom struct digunakan)

Diagnostik:

• get_message_descriptor
• get_diagnostics_declaration

Berbagai varian dengan berbagai sumber data dan prioritas sumber dapat ditemukan di core_services/vsidl/provider/src/vsidl_provider.rs.

Crate vsidl_provider menawarkan beberapa fungsi publik untuk membuat instance penyedia yang disesuaikan untuk agen SDV yang berbeda. Setiap konfigurasi menentukan rantai sumber data unik untuk menyelesaikan data terkait VSIDL. Tabel ini menguraikan perilaku setiap fungsi konstruktor:

Sumber data tabel merujuk ke panggilan di Gambar 1.