VSIDL Provider for reflection

VSIDL 供應商是一組程式庫和工具，可讓服務套件將 VSIDL 宣告的中繼資料提供給 SDV 平台代理程式 (診斷、遙測和 SOME/IP)。

具體來說，VSIDL 供應商可讓 SDV 代理程式探索下列中繼資料：

• VSIDL 目錄中使用的訊息和服務的 protobuf 描述元
• SOME/IP 對應
• 服務組合的診斷聲明

服務套件開發人員適用的 VSIDL 供應商指南

VSIDL 提供者程式庫會執行下列作業。

• 在兩個特定位置尋找檔案：
  • 位於 sdv_service_bundle_metadata 中定義路徑的 Apexes 內。
  • 靜態路徑中的圖片。
• 發出 RPC 呼叫，查詢位於相同或不同 VM 的代理程式上的 API。

如果您要開發服務套件，不需要瞭解 VSIDL Provider 程式庫的詳細資訊。您只需按照下列步驟操作，即可讓 VSIDL Provider 在執行階段找到所需檔案。

為目錄產生執行階段設定

這三種檔案 (vsidl 結構定義、診斷聲明、someip 對應) 都是透過 vsidl_rc_generator 工具產生。

使用 vsidl_rc_generator 主機二進位工具，並採用與 vsidlc 相同的參數，以及下列額外參數：

• --variant runtime-config-prebuilts
• --filegroup，指定包含目錄中所有檔案 (包括 Android.bp) 的檔案群組目標名稱。

供您參考，相關的 vsidlc 參數如下：

• --catalog-path 指定目錄的根路徑。
• --dependency-catalog-path，指定依附目錄。
• -- -path，指定要將所有產生的 genrule 和 prebuilt_etc 目標寫入 Android.bp 的位置。

產生器會建立含有相關 genrule 和 prebuilt_etc 目標的 Android.bp 檔案。在 Android.bp 中產生的目標區塊上方，會有註解指出各個目標的預期用途。

更新 APEX 的 Android.bp

如生成的 Android.bp 檔案註解所示：

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

您應將這些目標 (在標示的 Usage 註解下方) 新增至定義 Apex 的 Android.bp：

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

}

更新 APEX 的 sdv_service_bundles_manifest.textproto

在 Apex 的 sdv_service_bundle_metadata 檔案的 sdv_service_bundles_manifest.textproto 區塊中，您需要定義 (僅適用於相關路徑)：

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

請勿自行定義路徑。請改為複製產生的 Android.bp 檔案註解中顯示的路徑，如下所示：

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

這樣做可讓 VSIDL Provider 執行個體從各個 sdv_service_bundle_metadata 項目指定的路徑查詢。

在圖片中新增目標

產生的 Android.bp 檔案也會產生可直接載入圖片的目標。註解也會指出應以這種方式使用的目標，方法如下：

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

產生的 prebuilt_etc 目標會將使用 genrule 生成的檔案，放置在圖片上預先指定的位置。您需要在各自的 *.mk 檔案中加入 prebuilt_etc 目標 (例如 device/google/sdv/sdv_core_base/sdv_samples_automotive_services.mk)。

平台開發人員適用的 VSIDL 供應商指南

一般來說，如果您開發需要反射功能的 SDV 代理程式，可以使用 VSIDL 供應商程式庫。

VSIDL 提供者程式庫 API 包含下列函式：

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

地點

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

所有函式都會使用 source_fqin 參數查詢。這可確保使用相同 unit_type 或 message_name 的不同 FQIN 傳回正確資料。這個參數會將 VSIDL 供應商程式庫導向包含最準確訊息結構定義的特定 APEX。這是必要步驟，因為 APEX 會獨立更新，且可能針對相同的 protobuf 訊息或服務使用不同的結構定義。

get_message_descriptor 函式的用法

這會從用於反射的外部 Crate 中，純粹傳回 pub struct MessageDescriptor。MessageDescriptor 是一段中繼資料，可進行反映，在執行階段動態檢查及操控 protobuf 訊息。

get_publication_descriptor 函式的使用方式

這個函式會傳回 PublicationDescriptor，也就是：

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

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

size_metadata 欄位包含發布訊息的大小和限制相關資訊。這項中繼資料衍生自 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>,
}

get_rpc_method_descriptor 函式的用法

這個函式會傳回 RpcMethodDescriptor，也就是：

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

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

這個結構體會保留 RPC 方法要求和回應訊息的 MessageDescriptor。

使用 get_someip_mappings 函式

這項函式用於擷取本機 SOME/IP 服務對應，這些對應定義於 core_services/vsidl/protos/sdv/someip/v1/someip.proto 中。

使用 get_diagnostics_declaration 函式

這是用於擷取診斷宣告的函式，這些宣告定義於 core_services/vsidl/protos/sdv/diagnostics/v1/diagnostics_syntax.proto

使用 subscribe_availability_change_by_vm 函式

這個函式會傳回指定虛擬機器的可用性串流，做為重要的備用機制。如果標準 VSIDL Provider API 呼叫失敗並顯示 SdvStatusCode::Unavailable 錯誤，請使用這項功能，讓系統有效率地等待 VSIDL 提供者介面恢復連線。

這項功能的主要行為包括：

• 立即發出：訂閱後，串流會發出目標虛擬機器的目前可用性狀態。
• 行為一致：產生的串流行為與 ServiceDiscoveryManager 使用的 subscribe_service_unit_change_by_name 函式完全相同。

VSIDL 提供者代理程式

每個 VM 都會執行自己的 VSIDL Provider 代理程式，這基本上是 RPC 伺服器，負責轉送 VSIDL Provider API (代理程式內程式庫的本機執行個體) 的要求。代理程式可用於查詢不同 VM 上的 VSIDL 提供者，也就是說，一個 VM 上的服務可以使用這個代理程式，查詢另一個 VM 的 VSIDL 中繼資料。

程式碼集中的 API 用法

SOMEIP：

• get_publication_descriptor (使用所有結構體欄位)
• get_rpc_method_descriptor (使用所有結構體欄位)
• get_someip_mappings

遙測：

• get_publication_descriptor (僅使用 message_descriptor 欄位)
• get_rpc_method_descriptor (使用所有結構體欄位)

診斷：

• get_message_descriptor
• get_diagnostics_declaration

如要瞭解各種版本、資料來源和來源優先順序，請參閱 core_services/vsidl/provider/src/vsidl_provider.rs。

vsidl_provider Crate 提供多個公開函式，可建立專為不同 SDV 代理程式設計的供應商例項。每項設定都會指定一組獨特的資料來源鏈結，用於解析 VSIDL 相關資料。下表列出各建構函式的行為：

資料表中的資料來源是指圖 1 中的呼叫。