ספק VSIDL להשתקפות

ספק ה-VSIDL הוא קבוצה של ספריות וכלים שמאפשרים לחבילות שירות לספק מטא-נתונים שהוגדרו ב-VSIDL לסוכני פלטפורמת ה-SDV (אבחון, טלמטריה ו-SOME/IP).

באופן ספציפי, ספק VSIDL מאפשר לסוכני SDV לגלות את המטא-נתונים הבאים:

• תיאורי protobuf של הודעות ושירותים שמשמשים בקטלוג VSIDL
• מיפויים של SOME/IP
• הצהרות אבחון של חבילות שירותים

מדריך לספקים של VSIDL למפתחים של חבילות שירות

ספריית הספק של VSIDL מבצעת את הפעולות הבאות.

• החיפוש מתבצע בשני מקומות ספציפיים:
  • בתוך חבילות Apex בנתיבים שמוגדרים ב-sdv_service_bundle_metadata.
  • בתמונה בנתיבים סטטיים.
• מתחיל קריאות RPC כדי לשלוח שאילתות ל-API לגבי סוכנים שמוצבים באותן מכונות VM או במכונות VM שונות.

אם אתם מפתחים חבילת שירותים, אתם לא צריכים לדעת את הפרטים של ספריית הספק VSIDL. אפשר פשוט לפעול לפי השלבים האלה, שיאפשרו לספק VSIDL למצוא את הקבצים שהוא צריך בזמן הריצה.

יצירת הגדרות זמן ריצה לקטלוג

כל שלושת סוגי הקבצים (סכימות 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 של קובצי ה-Apex‏ 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 לשלוח שאילתות מהנתיבים שצוינו ברשומות 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.

ספריית ה-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 מה-crate החיצוני שמשמש לרפלקציה. 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

הפונקציה הזו מחזירה זרם זמינות למכונה וירטואלית שצוינה, ומשמשת כמנגנון קריטי למעבר לגיבוי. משתמשים בו כשקריאות רגילות ל-VSIDL Provider API נכשלות עם שגיאה SdvStatusCode::Unavailable, וכך המערכת יכולה להמתין ביעילות עד שממשק VSIDL Provider יחזור למצב אונליין.

התנהגויות מרכזיות של הפונקציה הזו:

• פליטה מיידית: אחרי ההרשמה, הנתונים שמועברים בסטרימינג כוללים את סטטוס הזמינות הנוכחי של המכונה הווירטואלית של היעד.
• התנהגות זהה: מקור הנתונים שנוצר מתנהג בדיוק כמו הפונקציה subscribe_service_unit_change_by_name שבה נעשה שימוש ב-ServiceDiscoveryManager.

סוכן ספק VSIDL

כל מכונה וירטואלית מפעילה סוכן VSIDL Provider משלה, שהוא למעשה שרת RPC שמעביר בקשות ב-VSIDL Provider API (של מופע מקומי של הספרייה בתוך הסוכן). הסוכן משמש לשליחת שאילתות אל ספק 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. בטבלה הבאה מפורטת ההתנהגות של כל פונקציית constructor:

מקורות הנתונים של הטבלה מתייחסים לשיחות באיור 1.