ارائه دهنده VSIDL برای بازتاب

ارائه‌دهنده VSIDL مجموعه‌ای از کتابخانه‌ها و ابزارها است که به بسته‌های سرویس اجازه می‌دهد تا فراداده‌های اعلام‌شده توسط VSIDL را به عوامل پلتفرم SDV (Diagnostics، Telemetry و SOME/IP) ارائه دهند.

به طور خاص، ارائه دهنده VSIDL به نمایندگان SDV این امکان را می‌دهد که فراداده‌های زیر را کشف کنند:

• توصیف‌گرهای protobuf پیام‌ها و سرویس‌های مورد استفاده در کاتالوگ VSIDL
• نگاشت‌های SOME/IP
• اعلامیه‌های تشخیص بسته‌های خدماتی

راهنمای ارائه دهنده VSIDL برای توسعه دهندگان بسته خدمات

کتابخانه‌ی VSIDL Provider عملیات زیر را انجام می‌دهد.

• فایل‌ها را در دو مکان خاص پیدا می‌کند:
  • درون Apexeها در مسیرهای تعریف‌شده در 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 Provider را قادر می‌سازد تا از مسیرهای مشخص شده توسط در ورودی‌های 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 Agent هستید که به قابلیت‌های بازتاب نیاز دارد، می‌توانید از کتابخانه ارائه دهنده 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>,
}

این struct 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 در کدبیس

برخی از آی‌پی‌ها:

• 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 مشخص می‌کند. جدول زیر رفتار هر تابع سازنده را شرح می‌دهد:

منابع داده جدول به فراخوانی‌های شکل ۱ اشاره دارند.