Поставщик VSIDL для рефлексии

Провайдер VSIDL — это набор библиотек и инструментов, позволяющих пакетам служб предоставлять метаданные, объявленные в соответствии с VSIDL, агентам платформы SDV (диагностика, телеметрия и SOME/IP).

В частности, провайдер VSIDL позволяет агентам SDV обнаруживать следующие метаданные:

• Дескрипторы protobuf сообщений и служб, используемые в каталоге VSIDL
• Сопоставление SOME/IP
• диагностические декларации пакетов услуг

Руководство по использованию VSIDL-провайдера для разработчиков пакетов услуг

Библиотека поставщиков VSIDL выполняет следующие операции.

• Находит файлы в двух конкретных местах:
  • Внутри Apex-объектов по путям, определенным в sdv_service_bundle_metadata.
  • На изображении в статических путях.
• Инициирует RPC-вызовы для запроса 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 для указания места записи файла Android.bp со всеми сгенерированными целями genrule и prebuilt_etc .

Генератор создаст файл Android.bp с соответствующими целями genrule и prebuilt_etc . Над сгенерированными блоками целей в Android.bp будут размещены комментарии, указывающие на предполагаемое использование соответствующих целей.

Обновите файл Android.bp в APEX.

Как видно из комментариев к сгенерированному файлу Android.bp , они гласят:

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

Вам следует добавить следующие цели (ниже указанных комментариев Usage ) в файл Android.bp , определяющий Apex-код:

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

}

Обновите файл sdv_service_bundles_manifest.textproto в APEX.

В блоках sdv_service_bundle_metadata файлов sdv_service_bundles_manifest.textproto Apex необходимо определить (только для соответствующих путей):

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 выполнять запросы по путям, указанным в соответствующих записях sdv_service_bundle_metadata .

Добавить целевые объекты на изображение

Сгенерированные файлы Android.bp также создают цели, которые можно загрузить непосредственно в образ. В комментариях также указаны цели, которые предполагается использовать таким образом, а именно:

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

Сгенерированный целевой объект prebuilt_etc разместит файлы, созданные с помощью genrule s, в заранее указанном месте образа. Необходимо включить целевые объекты prebuilt_etc в соответствующие файлы *.mk (например, device/google/sdv/sdv_core_base/sdv_samples_automotive_services.mk ).

Руководство по использованию VSIDL-провайдеров для разработчиков платформы

Как правило, если вы разрабатываете агент SDV, которому необходимы возможности рефлексии, вы можете использовать библиотеку поставщиков VSIDL.

API библиотеки поставщиков VSIDL содержит следующие функции:

    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 . Это гарантирует, что разные FQIN, использующие один и тот же unit_type или message_name будут возвращать корректные данные. Параметр направляет библиотеку поставщика VSIDL к конкретному APEX, содержащему наиболее точную схему сообщения. Это необходимо, поскольку APEX обновляются независимо и могут использовать разные схемы для одного и того же сообщения или службы protobuf.

Использование функции get_message_descriptor

В результате возвращается исключительно 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>,
}

Эта структура содержит MessageDescriptor как для сообщения запроса, так и для сообщения ответа метода RPC.

Использование функции 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

Эта функция возвращает поток доступности для указанной виртуальной машины, служащий важным резервным механизмом. Используйте её, когда стандартные вызовы API поставщика VSIDL завершаются ошибкой SdvStatusCode::Unavailable , что позволяет системе эффективно ожидать восстановления работы интерфейса поставщика VSIDL.

Ключевые особенности этой функции включают в себя:

• Мгновенная передача: После подписки поток передает текущий статус доступности целевой виртуальной машины.
• Поведенческая совместимость: результирующий поток ведет себя идентично функции subscribe_service_unit_change_by_name используемой ServiceDiscoveryManager .

Агент поставщика VSIDL

На каждой виртуальной машине работает собственный агент поставщика VSIDL, который по сути является RPC-сервером, перенаправляющим запросы к API поставщика VSIDL (локального экземпляра библиотеки внутри агента). Агент используется для запроса к поставщику VSIDL на другой виртуальной машине, то есть служба на одной виртуальной машине может запрашивать метаданные 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 предлагает несколько публичных функций для создания экземпляров провайдера, адаптированных для различных агентов SDV. Каждая конфигурация задает уникальную цепочку источников данных для обработки данных, связанных с VSIDL. В таблице описано поведение каждой функции-конструктора:

Источники данных в таблице относятся к вызовам, показанным на рисунке 1 .