Proveedor de VSIDL para la reflexión

El proveedor de VSIDL es un conjunto de bibliotecas y herramientas que permiten que los paquetes de servicios proporcionen metadatos declarados por VSIDL a los agentes de la plataforma de SDV (diagnóstico, telemetría y SOME/IP).

En particular, el proveedor de VSIDL permite que los agentes de SDV descubran los siguientes metadatos:

• Descriptores de protobuf de los mensajes y servicios que se usan en el catálogo de VSIDL
• Asignaciones de SOME/IP
• declaraciones de diagnóstico de los Service Bundles

Guía del proveedor de VSIDL para desarrolladores de paquetes de servicios

La biblioteca del proveedor de VSIDL realiza las siguientes operaciones.

• Ubica archivos en dos lugares específicos:
  • Dentro de los Apexes en las rutas definidas en sdv_service_bundle_metadata.
  • En la imagen de rutas estáticas
• Inicia llamadas a RPC para consultar la API sobre los agentes que residen en la misma VM o en diferentes.

Si desarrollas un paquete de servicios, no necesitas conocer los detalles de la biblioteca de VSIDL Provider. Solo debes seguir estos pasos, que permiten que el proveedor de VSIDL encuentre los archivos que necesita en el tiempo de ejecución.

Genera configuraciones de entorno de ejecución para el catálogo

Los tres tipos de archivos (esquemas de vsidl, declaraciones de diagnóstico y asignaciones de someip) se generan a partir de la herramienta vsidl_rc_generator.

Usa la herramienta binaria del host vsidl_rc_generator con los mismos parámetros que se usaron para vsidlc y los siguientes parámetros adicionales:

• --variant runtime-config-prebuilts
• --filegroup para especificar el nombre del destino del grupo de archivos que contiene todos los archivos del catálogo (incluido el Android.bp).

Como referencia, los parámetros de vsidlc relevantes son los siguientes:

• --catalog-path para especificar la ruta de acceso raíz del catálogo
• --dependency-catalog-path para especificar catálogos dependientes
• -- -path para especificar dónde escribir el Android.bp con todos los destinos genrule y prebuilt_etc generados.

El generador creará un archivo Android.bp con destinos genrule y prebuilt_etc relevantes. Además de los bloques de destino generados en Android.bp, habrá comentarios que indicarán el uso previsto de sus respectivos destinos.

Actualiza el archivo Android.bp de APEX

Como se indica en los comentarios del archivo Android.bp generado, que dicen lo siguiente:

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

Debes agregar estos destinos (debajo de los comentarios Usage indicados) al Android.bp que define el Apex:

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

}

Actualiza el archivo sdv_service_bundles_manifest.textproto de APEX

Dentro de los bloques sdv_service_bundle_metadata de los archivos sdv_service_bundles_manifest.textproto de Apex, debes definir (solo para las rutas aplicables):

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

No definas tus propias rutas. En su lugar, copia las rutas que se muestran en los comentarios del archivo Android.bp generado, que se encuentran de la siguiente manera:

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

Esto permite que la instancia del proveedor de VSIDL realice consultas desde las rutas de acceso especificadas en las entradas sdv_service_bundle_metadata respectivas.

Agregar destinos a la imagen

Los archivos Android.bp generados también generan destinos que se pueden cargar directamente en la imagen. Los comentarios también indican los destinos que se deben usar de esta manera, de la siguiente forma:

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

El destino prebuilt_etc generado colocará los archivos que se generen con los genrule en una ubicación preespecificada de la imagen. Debes incluir los destinos prebuilt_etc en los archivos *.mk respectivos (por ejemplo, device/google/sdv/sdv_core_base/sdv_samples_automotive_services.mk).

Guía para proveedores de VSIDL para desarrolladores de plataformas

En general, si desarrollas un agente de SDV que necesita capacidades de reflexión, puedes usar la biblioteca del proveedor de VSIDL.

La API de la biblioteca del proveedor de VSIDL contiene las siguientes funciones:

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

dónde

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

Todas las funciones se consultan con un parámetro source_fqin. Esto garantiza que los diferentes FQIN que usan el mismo unit_type o message_name devuelvan los datos correctos. El parámetro dirige la biblioteca del proveedor de VSIDL al APEX específico que contiene el esquema de mensajes más preciso. Esto es necesario porque los APEX se actualizan de forma independiente y pueden usar diferentes esquemas para el mismo mensaje o servicio de protobuf.

Uso de la función get_message_descriptor

Esto devuelve solo el pub struct MessageDescriptor del crate externo que se usa para la reflexión. Un MessageDescriptor es un fragmento de metadatos que permite la reflexión, lo que habilita la inspección y manipulación dinámicas de los mensajes de protobuf en el tiempo de ejecución.

Uso de la función get_publication_descriptor

Esta función devuelve un PublicationDescriptor, que es lo siguiente:

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

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

El campo size_metadata contiene información sobre el tamaño y las restricciones del mensaje de una publicación. Estos metadatos se derivan de la configuración de 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>,
}

Uso de la función get_rpc_method_descriptor

Esta función devuelve un RpcMethodDescriptor, que es lo siguiente:

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

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

Esta estructura contiene el MessageDescriptor para los mensajes de solicitud y respuesta del método RPC.

Uso de la función get_someip_mappings

Esta es una función para recuperar asignaciones de servicios SOME/IP locales, que se definen en core_services/vsidl/protos/sdv/someip/v1/someip.proto.

Uso de la función get_diagnostics_declaration

Esta es una función para recuperar declaraciones de diagnóstico, que se definen en core_services/vsidl/protos/sdv/diagnostics/v1/diagnostics_syntax.proto.

Uso de la función subscribe_availability_change_by_vm

Esta función devuelve un flujo de disponibilidad para una máquina virtual especificada, que sirve como un mecanismo de respaldo crítico. Úsala cuando las llamadas estándar a la API del proveedor de VSIDL fallen con un error SdvStatusCode::Unavailable, lo que permite que el sistema espere de manera eficiente a que la interfaz del proveedor de VSIDL vuelva a estar en línea.

Entre los comportamientos clave de esta función, se incluyen los siguientes:

• Emisión inmediata: Al suscribirse, la transmisión emite el estado de disponibilidad actual de la máquina virtual de destino.
• Paridad de comportamiento: El flujo resultante se comporta de manera idéntica a la función subscribe_service_unit_change_by_name que usa el ServiceDiscoveryManager.

Agente de proveedor de VSIDL

Cada VM ejecuta su propio agente de VSIDL Provider, que es básicamente un servidor RPC que reenvía solicitudes en la API de VSIDL Provider (de una instancia local de la biblioteca dentro del agente). El agente se usa para consultar el proveedor de VSIDL en una VM diferente, es decir, un servicio en una VM puede consultar los metadatos de VSIDL desde otra VM con este agente.

Uso de la API en la base de código

SOMEIP:

• get_publication_descriptor (se usan todos los campos de la estructura)
• get_rpc_method_descriptor (se usan todos los campos de la estructura)
• get_someip_mappings

Telemetría:

• get_publication_descriptor (solo se usa el campo message_descriptor)
• get_rpc_method_descriptor (se usan todos los campos de la estructura)

Diagnóstico:

• get_message_descriptor
• get_diagnostics_declaration

Las diferentes variantes con las diversas fuentes de datos y prioridades de fuentes se pueden encontrar en core_services/vsidl/provider/src/vsidl_provider.rs.

El crate vsidl_provider ofrece varias funciones públicas para crear instancias de proveedores adaptadas a diferentes agentes de SDV. Cada configuración especifica una cadena única de fuentes de datos para resolver los datos relacionados con VSIDL. En la siguiente tabla, se describe el comportamiento de cada función de constructor:

Las fuentes de datos de la tabla hacen referencia a las llamadas de la Figura 1.