VSIDL Provider for reflection

موفّر VSIDL هو مجموعة من المكتبات والأدوات التي تسمح لحِزم الخدمات بتوفير بيانات وصفية معرَّفة في VSIDL لوكلاء منصة SDV (أدوات التشخيص وقياس الاستخدام وSOME/IP).

على وجه الخصوص، يتيح موفّر VSIDL لبرامج SDV Agents اكتشاف البيانات الوصفية التالية:

• واصفات protobuf للرسائل والخدمات المستخدَمة في كتالوج VSIDL
• عمليات الربط بين SOME/IP
• بيانات التشخيص لحِزم الخدمات

دليل مقدّم VSIDL لمطوّري حِزم الخدمات

تنفّذ مكتبة VSIDL Provider العمليات التالية.

• تحديد موقع الملفات في مكانَين محدّدين:
  • ضمن حِزم Apex في المسارات المحدّدة في sdv_service_bundle_metadata
  • في الصورة في المسارات الثابتة
• يبدأ طلبات RPC للاستعلام عن واجهة برمجة التطبيقات على البرامج التي تعمل على الأجهزة الافتراضية نفسها أو أجهزة افتراضية مختلفة.

إذا كنت بصدد تطوير حزمة خدمات، لن تحتاج إلى معرفة تفاصيل مكتبة VSIDL Provider. ما عليك سوى اتّباع الخطوات التالية التي تتيح لمزوّد VSIDL العثور على الملفات التي يحتاجها أثناء وقت التشغيل.

إنشاء إعدادات وقت التشغيل للكتالوج

يتم إنشاء جميع أنواع الملفات الثلاثة (مخططات VSDIL وبيانات التشخيص وعمليات ربط SOME/IP) من أداة 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 الهدف الذي تم إنشاؤه الملفات التي تم إنشاؤها باستخدام genrules في موقع محدّد مسبقًا على الصورة. يجب تضمين عناصر prebuilt_etc في ملفات *.mk المعنية (مثل device/google/sdv/sdv_core_base/sdv_samples_automotive_services.mk).

دليل موفِّر VSIDL لمطوّري المنصات

بشكل عام، إذا كنت بصدد تطوير SDV Agent يحتاج إلى إمكانات انعكاس، يمكنك استخدام مكتبة موفّر VSIDL.

تحتوي واجهة برمجة التطبيقات لمكتبة VSIDL Provider على الدوال التالية:

    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 هي جزء من البيانات الوصفية التي تتيح إمكانية التفكير الذاتي، ما يتيح الفحص الديناميكي ومعالجة رسائل البروتوكول المخزَّنة مؤقتًا في وقت التشغيل.

استخدام الدالة 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

تعرض هذه الدالة بثًا خاصًا بالتوفّر لجهاز افتراضي محدّد، ويُستخدَم كآلية احتياطية مهمة. استخدِمها عندما يتعذّر إتمام طلبات البيانات من واجهة برمجة التطبيقات VSIDL Provider API العادية مع ظهور الخطأ SdvStatusCode::Unavailable، ما يتيح للنظام الانتظار بكفاءة إلى أن تعود واجهة VSIDL Provider إلى الاتصال بالإنترنت.

تشمل السلوكيات الرئيسية لهذه الوظيفة ما يلي:

• الإصدار الفوري: عند الاشتراك، يبث الجهاز الحالة الحالية لتوفّر الجهاز الظاهري المستهدف.
• التكافؤ السلوكي: يتصرف البث الناتج بشكل مطابق للدالة subscribe_service_unit_change_by_name التي تستخدمها ServiceDiscoveryManager.

VSIDL Provider Agent

يعمل كل جهاز VM على تشغيل وكيل VSIDL Provider الخاص به، وهو في الأساس خادم RPC يعيد توجيه الطلبات على VSIDL Provider API (لنسخة محلية من المكتبة داخل الوكيل). يُستخدم الوكيل للاستعلام من "موفّر VSIDL" على جهاز افتراضي مختلف، أي يمكن لخدمة على جهاز افتراضي واحد الاستعلام عن البيانات الوصفية لـ VSIDL من جهاز افتراضي آخر باستخدام هذا الوكيل.

استخدام واجهة برمجة التطبيقات في قاعدة الرموز البرمجية

‫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.