ضبط Orchestrator

Orchestrator هو وكيل SDV محلي يتم تشغيله على كل جهاز افتراضي (VM) ويوفر آلية للتحكّم في وقت إنشاء حِزم الخدمات أو بدء تشغيلها أو إيقافها أو إتلافها. ويتم ذلك من خلال إعدادات التنسيق، حيث تحدّد مجموعة من القواعد التي تحدّد متى وكيف يتم تنفيذ الإجراءات على مثيلات حِزم الخدمات. تستند هذه القواعد إلى أوضاع السيارة والطاقة والأوضاع المخصّصة.

يمكنك ضبط Orchestrator في configuration APEXes أو من خلال عمليات الضبط لكل جهاز ظاهري. يتيح نظام الإعدادات الموزّعة هذا إمكانية تعديل أجزاء من كل حزمة خدمات بشكل مستقل من خلال "سجلّ حِزم الخدمات"، كما هو موضّح هنا.

مخطّط الإعداد الموزّع لخدمة Orchestrator

الشكل 1: مخطّط إعدادات Orchestrator

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

حِزم APEX للإعداد

في وقت التشغيل، ينتقل Orchestrator إلى سجلّ حِزم الخدمات لجلب تنسيق SDV لكل حزمة خدمة، ويتم تحميل كل إعداد وتحليله. لمزيد من المعلومات، يُرجى الرجوع إلى بيانات وصفية للتنسيق.

الإعدادات لكل جهاز افتراضي

عند بدء تشغيل Orchestrator، يتم تحميل إعدادات الجهاز الافتراضي وتحليلها (في حال توفّرها). يتم تحديد المسار المطلق لملف الإعداد هذا من خلال خصائص النظام persist.sdv.orchestrator_config_path وro.boot.sdv.orchestrator_config_path.

يحدّد النظام مسار ملف إعداد الجهاز الافتراضي عند بدء التشغيل استنادًا إلى التسلسل الهرمي التالي:

  1. يتحقّق النظام من السمة persist.sdv.orchestrator_config_path. إذا كانت تتضمّن قيمة، يتم استخدام هذا المسار. يتم الاحتفاظ بهذه القيمة عند إعادة التشغيل أو يتم ضبطها في وقت التشغيل.

  2. إذا كان الحقل persist.sdv.orchestrator_config_path فارغًا، يتحقّق النظام من الحقل ro.boot.sdv.orchestrator_config_path. إذا كانت السمة ro.boot.sdv تتضمّن قيمة، يتم نسخ هذا المسار إلى السمة persist واستخدامه في عملية التشغيل الحالية وجميع عمليات التشغيل المستقبلية (ما لم يتم تجاوزه).

persist.sdv.orchestrator_config_path

‫persist.sdv.orchestrator_config_path هي السمة الأساسية التي يستخدمها وكيل SDV Orchestrator للحصول على مسار ملف الإعدادات. هذه السمة ثابتة، ما يعني أنّه يتم حفظ قيمتها عند إعادة تشغيل الجهاز. يمكنك تغيير القيمة في وقت التشغيل، وهو أمر مفيد للاختبار أو السيناريوهات المحدّدة (على سبيل المثال، الاختبارات الشاملة).

يمكنك ضبط القيمة في وقت التشغيل باستخدام الأمر setprop، وفي مدّة التصميم باستخدام ملف makefile (بالامتداد .mk) أو ملف نص برمجي للموارد، بالامتداد .rc.

ضبط السمة في وقت التشغيل

يُعدّ ضبط السمة في وقت التشغيل مفيدًا للاختبار أو إجراء تغييرات مؤقتة، لأنّه يتم حفظ القيمة عند إعادة التشغيل:

adb root
adb shell setprop persist.sdv.orchestrator_config_path {$path_to_file}.textproto

ضبط السمة في مدّة التصميم

لضبط هذه السمة كجزء من إعدادات التصميم لجهازك، أضِف سطرًا إلى ملف makefile الخاص بمنتجك أو لوحتك. هذا الإجراء مثالي لضبط قيمة تلقائية لصورة جهاز جديد.

# Add this line to a product's or device's .mk file
PRODUCT_PROPERTY_OVERRIDES += persist.sdv.orchestrator_config_path={$path_to_file}.textproto

يمكنك أيضًا ضبط هذه السمة ضمن ملف نصي للموارد:

# Add this line to an .rc file
on {$property}
    setprop persist.sdv.orchestrator_config_path {$path_to_file}.textproto

ro.boot.sdv.orchestrator_config_path

‫ro.boot.sdv.orchestrator_config_path هي سمة للقراءة فقط يتم استخدامها عند بدء التشغيل لتوفير قيمة أولية للسمة persist.sdv.orchestrator_config_path. إذا كانت persist.sdv.orchestrator_config_path فارغة عند تشغيل النظام، سيتم نسخ قيمة ro.boot.sdv.orchestrator_config_path إليها. بعد ضبط قيمة persist.sdv.orchestrator_config_path، لن يتم استبدالها بهذه السمة عند عمليات إعادة التشغيل اللاحقة.

يمكنك ضبط ro.boot.sdv.orchestrator_config_path باستخدام bootconfig أو سطر أوامر النواة.

تنسيق الملف

حدِّد إعدادات التنسيق بتنسيق .textproto (على سبيل المثال، في نص منظَّم) حتى يمكن تحميل الإعدادات الجديدة في وقت التشغيل.

بنية الإعدادات

يوضّح هذا القسم بنية الإعداد.

حِزم الخدمات

يجب تحديد كل حزمة خدمة باستخدام إعدادات حزمة الخدمة التي تحدّد الحزمة ضمن Orchestrator وتُستخدم للتعامل مع دورة حياة مثيل الحزمة. يحدّد إعداد حزمة الخدمات ما يلي:

  • تتيح لك السمة InstanceToGroupMapping تضمين مثيل لحزمة الخدمة في مجموعة لإنشاء تبعيات بين مثيلات حزمة الخدمة نفسها.

  • تحدّد InstancesStates الحالات المختلفة لحزمة الخدمة instance.

  • تحدّد InstancesStateConfiguration الحالة (من InstancesStates) التي يجب ضبط مثيل حزمة الخدمة عليها إذا تم تقييم الشرط على أنّه true.

  • تحتوي ServiceBundleConfig على معلومات حول حزمة الخدمات المحددة وحالاتها. ويحتوي على InstanceToGroupMapping وInstancesStateConfiguration المناسبَين للحزمة.

  • تحدّد السمة CustomModes قائمة بالأوضاع المخصّصة التي يُسمح للحزمة بنشرها. يُستخدَم CustomModes لمنع حِزمة غير مصرَّح بها من تعديل قيمة وضع مخصّص. هذا الحقل اختياري، لأنّه قد لا يتم نشر حزمة الخدمة في أي وضع مخصّص. لمزيد من المعلومات، اطّلِع على الأوضاع المخصّصة.

إعدادات الحزمة المطلوبة

توفّر إعدادات الحزمة السمات التالية كحدّ أدنى:

service_bundle_config {
    package_name: "package_name"
    service_bundle_name: "service_bundle_name"

    instance: "instance_1"
    instance: "instance_n"
}

يحدّد هذا البيان مثيلات حِزم خدمة n مع أسماء FQIN الخاصة بها:

vm_name.package_name.service_bundle_name.instance_1
…
vm_name.package_name.service_bundle_name.instance_n

لم يتم تحديد اسم الجهاز الافتراضي بشكل صريح في الإعدادات. بما أنّ الإعدادات يتم تحديدها لكل جهاز افتراضي، يكون اسم الجهاز الافتراضي دائمًا هو اسم الجهاز الافتراضي الذي يتم نشر ملف الإعدادات عليه، ويكون معروفًا مسبقًا لوكيل التنسيق.

ضبط المثيلات

ليس لتحديد مثيلات حِزم الخدمات أي تأثير. يجب إعداد النسخ ليتم تنفيذها بواسطة Orchestrator. على سبيل المثال، يجب إبلاغ Orchestrator بالشروط (أو حالة الجهاز الافتراضي أو المركبة) التي يجب أن يعمل بها أحد المثيلات. لضبط المثيلات، يجب تحديد حالات الضبط من خلال:

  • ‫condition هو تعبير عن حالة الجهاز الافتراضي أو المركبة يجب تقييمه.

  • ‫instances_states هي مجموعة من الحالات لكل نسخة افتراضية يجب تطبيقها إذا تم تقييم الشرط على أنّه true.

لمزيد من المعلومات، اطّلِع على الشروط.

service_bundle_config {
    package_name: "oem.package"
    service_bundle_name: "OemApplication"

    instance: "adaptive_light"
    instance: "reserve_light"

    state {
        condition {
            power_state: "ON"
        }

        instances_states {
            started: "adaptive_light"
            created: "reserve_light"
        }
    }
}

ربط المثيل بالمجموعة

يمكنك أيضًا ضبط مثيلات الخدمة من خلال تضمينها في مجموعات الخدمة. على مستوى إعداد حزمة الخدمات، يمكنك إضافة مثيلات إلى مجموعات. يمكنك بعد ذلك ضبط المجموعات على مستوى إعدادات الجهاز الظاهري. لمزيد من المعلومات، يُرجى الاطّلاع على القسم التالي وحِزم الخدمات.

service_bundle_config {
    package_name: "oem.package"
    service_bundle_name: "OemApplication"

    instance: "fog_front_light"
    instance: "fog_rear_light"
    instance: "turn_signal_light"
    instance: "light_flasher_display"

    # Declare that fog_light contains fog_front_light and fog_rear_light.
    group_mapping {
        group: "fog_light"
        instance: "fog_front_light"
        instance: "fog_rear_light"
    }

    # Declare that flasher_light contains turn_signal_light and light_flasher_display.
    group_mapping {
        group: "flasher_light"
        instance: "turn_signal_light"
        instance: "light_flasher_display"
    }
}

مخطط Proto

في ما يلي نموذج لمخطط أولي:

// Service bundle configuration.
//
// Defines service bundle data, its instances and configuration for instances
// states depending on the state of the system
message ServiceBundleConfig {
  // Required. Name of the service bundle.
  string service_bundle_name = 1;

  // Required. Package name of the service bundle.
  string package_name = 2;

  // Required. Service instances.
  repeated string instance = 3;

  // Configuration for instances states depending on the state of the system.
  repeated InstancesStateConfiguration state = 4;

  // Mapping of groups to their member service instances.
  repeated InstanceToGroupMapping group_mapping = 5;

  // Custom modes that this service bundle is allowed to set.
  repeated string custom_mode = 6;

  // Defines the retry policies for specific instances.
  // If multiple mappings target the same instance, the one with the highest `max_retries`
  // value takes precedence. This applies across all configuration files.
  repeated InstanceToRetryMapping retry_mapping = 7;
}

// Mapping of instances to their retry configuration.
message InstanceToRetryMapping {
  // Required.
  //
  // Name of the instances for which the given retry configuration is applied.
  repeated string instance = 1;

  // Required.
  //
  // The configuration that defines the restart and retry strategy for the instances.
  RetryConfiguration retry_config = 2;

  // Configuration for retry and restart.
  // This configuration is applied after a failure on a transition or after the bundle instance
  // has crashed. Upon a successful operation, the retry counter are reset to max_retries. This
  // configuration can be applied to any service bundle, not only the monitored ones. If the
  // configuration is not provided or none of the optional fields are filled, the default behavior
  // stated is applied (the value from `ro.boot.sdv.orchestrator.recovery.max_retries`
  // or zero if not set).
  message RetryConfiguration {
    // The number of times a retry/restart operation can be performed.
    // Defines the number of times the Orchestrator retries a transition
    // after a transient failure or after a bundle crash notification.
    // This applies to creating, starting and destroying operations.
    // The retry count resets to max_retries after a successful operation.
    // If not set, the default configured value in the
    // `ro.boot.sdv.orchestrator.recovery.max_retries` is used, or-if not set-
    // it fallbacks to zero.
    optional uint32 max_retries = 1;
  }
}

// Mapping of groups to their member service instances.
message InstanceToGroupMapping {
  // Required. Names of groups to which members are added.
  //
  // Group behavior is defined in VM configuration.
  repeated string group = 1;

  // Required. Names of instances to be included in the groups.
  //
  // Can reference only instance defined in the same config file.
  repeated string instance = 2;
}

// Describes the state the service instances should be in after the state is executed.
//
// If there is no valid configuration for the instance in the specific system state, such instance is transitioned to the "destroyed" state.
//
// For the GroupsStates definition to be useful, at least one item should be present in any of the fields.
message InstancesStates {
  // Names of the instances that must be in a "created" state.
  repeated string created = 1;

  // Names of the instances that must be in a "started" state, overrides "created" state.
  repeated string started = 2;

  // Names of the instances that must not run, overrides all other states.
  repeated string destroyed = 3;
}

// Configuration for instances states depending on the state of the system.
message InstancesStateConfiguration {
  // Condition for the system state under which the related instances states should be executed by Orchestrator.
  //
  // If omitted, the related instances states are always executed.
  Condition condition = 1;

  // Required. States of service bundle instances to be executed by Orchestrator if the condition is true.
  InstancesStates instances_states = 2;
}

الإعداد على مستوى الجهاز الافتراضي

تتيح إعدادات الجهاز الافتراضي تحديد عمليات ربط المجموعات وإعدادات المجموعات. ويُستخدَم لنمذجة التبعيات بين حِزم الخدمات على مستوى الجهاز الافتراضي، ما يتيح المرونة في تعديل حالة حِزم خدمات متعددة في الوقت نفسه. يتم نقل جميع مثيلات المجموعة إلى الحالة المحدّدة.

لا يضمن Orchestrator ترتيب تنفيذ تغيير الحالة. يعزّز Orchestrator كل مثيل ليكون في الحالة المحدّدة.

يتم تعريف المجموعات ضمنيًا باستخدام اسم group في أي من أجزاء الإعداد. على سبيل المثال، ربط مثيل بمجموعة، وربط مجموعة بمجموعة، وحالات ضبط المجموعة.

ربط المجموعات ببعضها

يمكن أن تحتوي المجموعات على مجموعات أخرى. من خلال الإعلان عن أنّ group_1 يتضمّن subgroup_2، نضيف بشكل فعّال جميع مثيلات الخدمة من subgroup_2 إلى group_1.

على سبيل المثال:

# Declare that body contains fog_light and flasher_light.
group_mapping {
    group: "body"
    subgroup: "fog_light"
    subgroup: "flasher_light"
}

إعداد مجموعة

ليس لتحديد مجموعة أي تأثير. يجب ضبط المجموعات ليتم تنفيذها بواسطة Orchestrator. على سبيل المثال، يجب إبلاغ Orchestrator بالشروط أو الحالة التي يجب أن تعمل بها المجموعات على الجهاز الافتراضي أو المركبة.

يمكنك ضبط المجموعات بطريقة مشابهة لطريقة ضبط مثيلات الخدمة، أي باستخدام حالات الضبط. الاختلاف الوحيد هو استخدام groups_states بدلاً من instances_states في البنية:

state {
    condition {
        power_state: "ON"
    }

    groups_states {
        started: "Body"
        started: "Adas"
    }
}

مخطط Proto

في ما يلي نموذج لمخطط أولي:

// VM configuration.
//
// Defines group-to-group mappings and configuration for groups
// states depending on the state of the system.
//
// Configurations of service bundles can also be defined in VM configuration (as well as in a separate configuration file).
message VmConfig {
  // Group to member groups mapping.
  repeated GroupToGroupMapping group_mapping = 1;

  // Configuration of group states.
  repeated GroupsStateConfiguration state = 2;

  // Required. We also allow to configure individual service bundles in the VM config, to simplify development and migration from the monolithic configuration.
  repeated ServiceBundleConfig service_bundle_config = 3;
}

// Mapping of groups to their member groups.
message GroupToGroupMapping {
  // Required. Names of groups to which members are added.
  repeated string group = 1;

  // Required. Names of member groups to be included in the groups.
  repeated string subgroup = 2;
}

// Describes the state the service instance groups should be in after the state is executed.
//
// If group configuration is valid in a specific system state, the configured state is applied to
// all group members. After that, the normal service instance configuration rules still apply:
// - "destroyed" > "started" > "created" precedence
// - not configured means the instance should be moved to the default state
//
// For the GroupsStates definition to be useful, at least one item should be present in any of the fields.
message GroupsStates {
  // Names of the groups that must be in a "created" state.
  repeated string created = 1;

  // Names of the groups that must be in a "started" state, overrides "created" state.
  repeated string started = 2;

  // Names of the groups that must not run, overrides all other states.
  repeated string destroyed = 3;
}

// Configuration for group states depending on the state of the system.
message GroupsStateConfiguration {
  // Condition for the system state under which the related group states should be executed by  Orchestrator.
  //
  // If omitted, the related groups states are always executed.
  Condition condition = 1;

  // Required. States of service bundle groups to be executed by Orchestrator if the condition  is true.
  GroupsStates groups_states = 2;
}

حالات الإعداد

تحدّد حالات الضبط (الحالات) وقت بدء أو إيقاف أو إتلاف مثيل خدمة أو مجموعة، وتتألف من conditions وinstances_states (إعداد الحزمة) وgroups_states (إعداد الجهاز الافتراضي).

الشروط

تسمح الشروط للنموذج بتحديد شرط منطقي يتم بموجبه تطبيق حالة المثيل المحدّدة عند تقييمها إلى true. تتضمّن الحالة الخصائص التالية:

  • تعبير منطقي معقّد بشكل عشوائي (يتم إنشاؤه باستخدام تعبيرات and أو not) استنادًا إلى الإشارات المتوافقة، مثل الطاقة والمركبة والوضع المخصّص

  • (اختياري) تكون حالة الإعداد بدون شرط نشطة دائمًا، ما يعني أنّها تُقيَّم على أنّها true

حالات الأجهزة الافتراضية وحالات المجموعات

تتضمّن السمتان instances_states وgroups_states الخصائص التالية.

  • تحديد الحالات التي يحتاجها عامل التنسيق لتطبيقها على المثيلات أو المجموعات المحدّدة، مع العلم أنّ الحالة هي active

  • عند تطبيق حالة على المجموعة، تنطبق الحالة على كل مثيل من حِزم الخدمات في المجموعة. لا يتم تطبيق أي ترتيب بشأن وقت نقل الحالات إلى الحالة.

تشمل الولايات المتوافقة ما يلي:

  • يتم استدعاء started بعد Service::on_start.

  • created

    • بعد استدعاء Service::new، ولكن قبل استدعاء Service::on_start

      أو

    • بعد استدعاء Service::on_stop، ولكن قبل استدعاء Service::drop

  • يتم استدعاء destroyed بعد Service::drop.

مجموعة القواعد

يمكن أن تكون حالة الإعداد نشطة أو غير نشطة، وذلك حسب الشرط. يمكن أن تكون حالات متعددة نشطة في أي وقت. عندما يتلقّى وكيل التنسيق تحديثًا للإشارة، يتم تقييم جميع حالات الإعداد قبل تعديل دورة حياة حِزم الخدمات. يتم تقييم حالات مثيل الخدمة وفقًا للقواعد التالية:

  • عندما لا تنطبق أي من الحالات النشطة على مثيل الخدمة، يتم إيقافه.

  • عندما تنطبق حالة نشطة واحدة أو أكثر، تسري الأولوية التالية:

    1. تتمتّع destroyed بأولوية مطلقة.
    2. started له الأولوية قبل created.

مخطط Proto

في ما يلي نموذج لمخطط أولي:

// A root boolean condition.
message Condition {
  // Required.
  oneof root {
    // VPM power state condition.
    string power_state = 1;
    // VPM vehicle state condition.
    string vehicle_state = 2;
    // Custom mode state condition.
    CustomState custom_state = 3;
    // Negation of a nested condition.
    Condition not = 4;
    // Logical 'and' between conditions grouped in expression.
    Expression and = 5;
    // Logical 'or' between conditions grouped in expression.
    Expression or = 6;
  }
}

// Representation of Custom state condition.
//
// Custom mode(s) are defined by the OEM and are not standardized by the platform, in contrast with
// VPM modes (i.e. power and vehicle mode).
message CustomState {
  // Custom mode being checked.
  string mode = 1;
  // State of the custom mode.
  string state = 2;
}

// A set of conditions united under an 'and' or 'or' expression.
//
// Evaluation type ('and' or 'or') depends on the field in [Condition]/[Expression], where the
// expression is being used.
//
// At least one value in at least one of the fields is required.
message Expression {
  // VPM power state condition.
  repeated string power_state = 1;
  // VPM vehicle state condition.
  repeated string vehicle_state = 2;
  // Custom mode state condition.
  repeated CustomState custom_state = 3;
  // Negation of a nested condition.
  repeated Condition not = 4;
  // Logical 'and' between conditions grouped in expression.
  repeated Expression and = 5;
  // Logical 'or' between conditions grouped in expression.
  repeated Expression or = 6;
}

استراتيجية استعادة البيانات عند حدوث أعطال وإعادة التشغيل

يوفر Orchestrator آلية قوية للتعامل مع الأعطال في حِزم الخدمات وحالات تعذُّر الانتقال بين مراحل النشاط. بما أنّ Orchestrator لديه نظرة شاملة على حالات الخدمة ويدير عمليات الانتقال بين الأوضاع، فهو المكوّن الأنسب لتنفيذ استراتيجية إعادة التشغيل وإعادة المحاولة. يُبلِغ مدير دورة الحياة (LM) خدمة التقارير عن أعطال الحِزم إلى Orchestrator من خلال إشعارات binder death. لتجنُّب طلبات ربط غير ضرورية إلى LM، يخزّن Orchestrator الحالة الأخيرة لكل حزمة (سواء كانت ناجحة أم لا) ولا يعيد تطبيق عمليات الانتقال إذا كانت الحالة الأخيرة المعروفة هي نفسها الحالة الجديدة المطلوبة.

إعادة محاولة الإعداد

يمكنك تحديد استراتيجية إعادة التشغيل وإعادة المحاولة لكل مثيل في إعدادات Orchestrator باستخدام retry_mapping. إذا لم يتم ضبط max_retries في الإعداد، سيتم أخذ القيمة التلقائية من سمة النظام ro.boot.sdv.orchestrator.recovery.max_retries. إذا لم يتم ضبط هذه السمة، سيتم تلقائيًا استخدام القيمة 0.

  • ‫max_retries: تحدّد عدد المرات التي يعيد فيها Orchestrator محاولة الانتقال بعد حدوث خطأ عابر أو تلقّي إشعار بتعطُّل الحزمة. تتم إعادة ضبط عدّاد إعادة المحاولة إلى قيمة max_retries بعد عملية ناجحة أو عند معالجة وضع جديد. إذا استهدفت عمليات ربط متعدّدة المثيل نفسه، تكون الأولوية لعملية الربط التي تتضمّن أعلى قيمة max_retries.

مثال على الإعداد

service_bundle_config {
  package_name: "oem.package"
  service_bundle_name: "OemApplication"
  instance: "fog_front_light"
  instance: "fog_rear_light"

  # Defines the restart configuration mapping for specific instances.
  retry_mapping {
    instance: "fog_front_light"
    instance: "fog_rear_light"
    retry_config {
      max_retries: 3
    }
  }
}

سلوك الاسترداد

تتعامل منطقتا إعادة التشغيل وإعادة المحاولة في Orchestrator بشكل سليم مع عدة سيناريوهات للتعطُّل:

  • تعطُّل التشغيل العادي: إذا تعطّلت حِزمة خدمة أثناء تشغيلها، يطبّق Orchestrator استراتيجية إعادة التشغيل ويحاول إعادة الحِزمة إلى آخر حالة مطلوبة استنادًا إلى عدد المحاولات المتبقية.
  • تعطُّل أثناء الانتقال إلى وضع آخر: إذا تعطّلت حزمة أثناء فرض وضع جديد، يتم وضع طلب إعادة التشغيل في قائمة الانتظار ومعالجته لاحقًا. بعد معالجة الطلب، يتحقّق Orchestrator من آخر حالة للمثيل، ولا يطبّق إعادة التشغيل إلا إذا لم يكن المثيل في آخر حالة مطلوبة (من آخر عملية انتقال إلى وضع آخر).
  • وضع جديد أثناء عملية الاسترداد: إذا تلقّى Orchestrator طلبًا بالانتقال إلى وضع جديد أثناء إعادة تشغيل حزمة (أو إذا كانت الحزمة في قائمة انتظار الحالات التي ستتم إعادة تشغيلها)، سيلغي عملية الاسترداد الجارية. يتم تنفيذ عملية الانتقال إلى الوضع الجديد، ويتم إعادة ضبط عدّاد إعادة المحاولة للسماح بمجموعة جديدة من المحاولات لحالة الاستهداف الجديدة.

يفرّق Orchestrator بين أنواع الأخطاء المختلفة التي يعرضها Lifecycle Manager لتحديد استراتيجية إعادة المحاولة:

  • الأخطاء المؤقتة (SERVICE_NOT_FOUND وOPERATION_FAILED وINTERNAL_ERROR): يعيد Orchestrator محاولة تنفيذ العملية بدون اتّخاذ أي إجراء خاص لتنظيف البيانات.
  • الأخطاء المستمرة (VALUE_CORRUPTED وINVALID_ARGUMENT): يفترض Orchestrator أنّ حِزمة الخدمة قد تكون في حالة تالفة، ويحاول إيقاف مثيل الخدمة قبل إعادة محاولة العملية لضمان إعادة تشغيلها بشكل سليم.
  • الأخطاء الدائمة (PERMISSION_DENIED): لا تتم إعادة محاولة تنفيذ العملية، ويُعتقد أنّ الحِزمة في حالة لا يمكن استردادها.

في حال تعطُّل Lifecycle Manager، سيتم فقدان جميع عمليات حِزم الخدمات. وبما أنّ الحالة الفعلية غير معروفة، يبطل Orchestrator كل مثيل ويطبّق استراتيجية إعادة التشغيل مع عدد المحاولات المتبقية لإعادة كل مثيل إلى الحالة المطلوبة الأخيرة.

لمنع حدوث حلقات استرداد لا نهائية للحِزم التي تتعطّل أو تفشل بشكل متكرّر، لا تتم إعادة ضبط عدّاد إعادة المحاولة على max_retries إلا بعد نجاح عملية دورة الحياة، أو عند طلب انتقال إلى وضع جديد. إذا استنفدت الحزمة عدد محاولاتها بسبب حالات تعذّر متتالية (على سبيل المثال، تعذّر الانتقال ثم حدوث عُطل)، لن تتم إعادة تشغيلها إلى أن تتم إعادة ضبط عدّاد المحاولات.

الإبلاغ عن الحالة إلى خدمة "مراقبة الصحة"

يعرض Orchestrator واجهة ربط داخلية يسجّلها Health Monitor (HM)، ما يتيح له تلقّي تحديثات مستمرة بشأن حالة جميع حِزم الخدمات. من خلال هذه الواجهة، يقدّم Orchestrator تقارير نشطة عن كلّ من:

  • حالة مراحل النشاط: هي الحالة المقصودة للمثيل استنادًا إلى الإعداد الحالي والأوضاع النشطة (مثل البدء أو الإنشاء أو الإيقاف).
  • حالة الاسترداد: حالة الوصول إلى حالة دورة الحياة المقصودة، تشير إلى ما إذا كانت الآلة الافتراضية تعمل أو تعيد المحاولة حاليًا بعد حدوث خطأ أو تعذّر استردادها بعد استنفاد جميع محاولات إعادة التشغيل.

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

أمثلة

يعرض هذا القسم أمثلة على ضبط الحالات باستخدام الشروط.

عيّنة الخدمة الأساسية
  • لا يتضمّن أي شرط، وبالتالي يكون نشطًا دائمًا.
  • يبدأ مثيلاً واحدًا من الخدمة.
state {
  # Note: This state has no condition, hence its actions are valid throughout the lifetime of the program
  instances_states { started: "ServiceBundleName" }
}
نموذج تطبيق التدفئة والتهوية وتكييف الهواء

  • الشرط: نشط عندما يكون custom_state != occupancy.OCCUPANCY_EMPTY || custom_state == preheat.PREHEAT_ON.

  • تُعرِّف هذه السمة نُسخًا متعددة من الخدمات ذات الصلة بنظام التدفئة والتهوية وتكييف الهواء على أنّها started.

state {
  condition {
    or {
      # I.e. when the vehicle is occupied (for example, by _DRIVER / _NON_DRIVER / _PET)
      not {
        custom_state {
          mode: "occupancy"
          state: "OCCUPANCY_EMPTY"
        }
      }
      custom_state {
        mode: "preheat"
        state: "PREHEAT_ON"
      }
    }
  }

  # HVAC-related services
  instances_states {
    started: "HvacTemperatureCommand"
    started: "TempSensorDriverZone"
    started: "TempSensorPassengerZone"
    started: "RefrigerantLoop"
  }
}
نموذج توفير الطاقة

  • الشرط: نشط عندما يكون custom_state == system_power.SYSTEM_POWER_LOW && custom_state == range_ext.RANGE_EXT_ON.

    يمكن اعتبار هذه الحالة حالة توفير للطاقة.

  • تُعرِّف هذه السمة مثيلاً واحدًا لخدمة متعلقة بنظام التدفئة والتهوية وتكييف الهواء على أنّه destroyed.

  • في هذا المثال، عندما يكون الوضعان SYSTEM_POWER_LOW وRANGE_EXT_ON نشطَين، يتم تشغيل تطبيق نظام التدفئة والتهوية وتكييف الهواء بدون مثيل الخدمة RefrigerantLoop:

    state {
  condition {
    and {
      custom_state {
        mode: "system_power"
        state: "SYSTEM_POWER_LOW"
      }
      custom_state {
        mode: "range_ext"
        state: "RANGE_EXT_ON"
      }
    }
  }

  # Disable services with high power consumption
  instances_states { destroyed: "RefrigerantLoop" }
}
Life onboard sample

  • الشرط: نشط إذا كان power_state == ON && vehicle_state == LIFE_ON_BOARD.

    يمكن اعتبار هذه الحالة أنّ هناك شخصًا في السيارة والسيارة مشغّلة.

  • تُستخدَم لتحديد أنّ مستشعرات الحرارة تعمل.

  • عندما يكون شخص ما في السيارة، تتم مراقبة عناصر مثل درجة الحرارة لأسباب تتعلق بالسلامة.

state {
  condition {
    and {
      power_state: "ON"
      vehicle_state: "LIFE_ON_BOARD"
    }
  }

  # Temperature monitoring services
  instances_states {
    started: "TempSensorDriverZone"
    started: "TempSensorPassengerZone"
  }
}

أمثلة

يعرض هذا القسم أمثلة كاملة تتضمّن ما يلي:

  • إعدادات أولية على مستوى حزمة الخدمات تعرض حزمة خدمات تتضمّن مثيلَين، كل منهما جزء من مجموعة

  • إعدادات أولية على مستوى الجهاز الافتراضي تتضمّن منطقًا للتفاعل مع المجموعات استنادًا إلى الأوضاع

الإعدادات على مستوى حزمة الخدمات

# proto-file: //system/software_defined_vehicle/orchestration/distributed_config/src/protos/service_bundle_config.proto
# proto-message: ServiceBundleConfig

package_name: "oem.package"
service_bundle_name: "OemApplication"
instance: "fog_front_light"
instance: "fog_rear_light"
instance: "turn_signal_light"
custom_mode: "FOG"
custom_mode: "TURN"

group_mapping {
    group: "fog_light"
    instance: "fog_front_light"
    instance: "fog_rear_light"
}

group_mapping {
    group: "flasher_light"
    instance: "turn_signal_light"
}

state {
    condition {
        power_state: "ON"
    }

    instances_states {
        created: "turn_signal_light"
        destroyed: "fog_front_light"
        destroyed: "fog_rear_light"
    }
}

الإعدادات على مستوى الجهاز الافتراضي

# proto-file: //system/software_defined_vehicle/orchestration/distributed_config/src/protos/vm_config.proto
# proto-message: VmConfig

group_mapping {
    group: "lights"
    subgroup: "fog_light"
    subgroup: "flasher_light"
}

state {
    condition {
        custom_state {
            mode: "FOG"
            state: "ON"
        }
    }
    groups_states {
        started: "fog_light"
    }
}

state {
    condition {
        custom_state {
            mode: "TURN"
            state: "RIGHT"
        }
    }
    groups_states {
        started: "flasher_light"
    }
}

state {
    condition {
        vehicle_state: "SUSPEND_TO_RAM_ENTER"
    }
    groups_states {
        created: "lights"
    }
}

ضبط التوازي في إدارة الحِزم

خاصية النظام ro.boot.sdv.max_bundles_management_threads هي إحدى معلَمات الضبط الرئيسية للتحكّم في الأداء واستهلاك الموارد أثناء عمليات دورة حياة حِزمة الخدمة. تحدّد هذه السمة الحد الأقصى لمستوى التوازي لمعاملات حِزم الخدمات، وتؤثّر بشكل مباشر في خدمتَين أساسيتَين:

  1. محرك التنسيق: تقرأ هذه الخدمة الموقع لتحديد عدد المكالمات المتزامنة (على سبيل المثال، startService وstopService) التي يمكن أن يجريها المنسّق إلى "مدير دورة الحياة". وهذا أمر بالغ الأهمية لتحقيق الأداء المطلوب أثناء بدء التشغيل وعمليات الانتقال بين الأوضاع التي قد تتغير فيها حالة العديد من الحِزم في الوقت نفسه.

  2. Lifecycle Manager: تستخدم هذه الخدمة قيمة السمة لاحتساب حجم مجموعة سلاسل Binder، وهي المسؤولة عن معالجة جميع الطلبات الواردة. يضمن ذلك توفّر عدد كافٍ من سلاسل المحادثات في LM للتعامل مع الطلبات المتزامنة من Orchestrator.

إذا لم يتم ضبط هذه السمة، سيتم تلقائيًا ضبط قيمة كلتا الخدمتين على 12.

طريقة الضبط

يمكنك ضبط السمة في ملف BoardConfig.mk على جهازك من خلال إضافتها إلى المتغيّر BOARD_BOOTCONFIG. ويضمن ذلك تطبيق القيمة في كل مرة يتم فيها تشغيل الجهاز.

BOARD_BOOTCONFIG += \
    androidboot.sdv.max_bundles_management_threads=8

لتغيير قيمة جهازك، عدِّل هذا السطر في ملف BoardConfig.mk المناسب وأعِد الإنشاء.

تحسين وقت التشغيل

‫ro.sdv.orchestrator.state.ready هي سمة منطقية write-once تشكّل جزءًا من استراتيجية تحسين الأداء أثناء وقت التشغيل. يشير ذلك إلى أنّ عامل التنسيق قد أكمل عملية التهيئة وأصبح جاهزًا لبدء إدارة دورة حياة حِزم الخدمات. الغرض الأساسي منه هو تحديد أولويات بدء تشغيل Orchestrator وحِزم الخدمات المُدارة من خلال التحكّم في تسلسل بدء تشغيل وكلاء SDV الآخرين.

  • تم الضبط بواسطة: وكيل التنسيق
  • الوقت: مرة واحدة أثناء تسلسل بدء التشغيل
  • الاستخدام: يستخدم نظام التهيئة هذه السمة للتحكّم في تسلسل بدء تشغيل معظم برامج SDV (مثل "مدير التحديثات" و"موفّر VSIDL" و"مراقبة السلامة" و"اكتشاف الخدمات" و"نفق البيانات" و"إجراءات طلبات الإجراءات عن بُعد" و"إدارة الطاقة في المركبة" و"القياس عن بُعد"). من خلال بدء تشغيل Orchestrator مبكرًا وجعل الوكلاء الآخرين ينتظرون هذه السمة، يضمن النظام أنّه يمكن لـ Orchestrator بدء مهمته المهمة المتمثلة في بدء حِزم الخدمات بدون التنافس على موارد النظام.

الأداء

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

  1. تسجيل حِزم الخدمات: يبدأ أولاً لتحميل جميع البيانات الوصفية الخاصة بحِزم الخدمات.
  2. أداة إدارة مراحل النشاط وأداة التنسيق: تبدأ هذه البرامج الأساسية عملها فور أن يصبح السجلّ جاهزًا. هذه البداية المبكرة مهمة لأنّها تسمح لـ Orchestrator ببدء تقييم إعداداته والاستعداد لبدء حِزم الخدمات على الفور.
  3. وكلاء SDV الآخرون: لا يبدأون العمل إلا بعد أن يصبح المنسّق جاهزًا.

يضمن هذا التسلسل المُتحكَّم فيه أن يكون لدى Orchestrator الأولوية في استخدام موارد النظام لبدء حِزم الخدمات في أقرب وقت ممكن، ما يؤدي إلى بدء تشغيل النظام بشكل أسرع وأكثر تحديدًا وأكثر كفاءة.

الأوضاع التي يستهلكها Orchestrator

يحتفظ وكيل التنسيق باشتراك نشط في أوضاع المركبة والطاقة التي يرسلها VPM. عند إنشاء عملية الربط الأوّلي بين Orchestrator ونظام إدارة المركبة والطاقة (VPM)، يضبط Orchestrator خصائص النظام المنطقية التالية على true:

  • sdv.orchestrator.bootup.power_mode.ready

  • sdv.orchestrator.bootup.vehicle_mode.ready

باستخدام ملف إعداد كمرجع، يحسب عامل التنسيق بشكل ديناميكي مجموعة حِزم الخدمات التي يجب أن تكون في حالة التشغيل استنادًا إلى القيم الحالية للأوضاع المستلَمة. بعد ذلك، يتواصل Orchestrator مع مدير مراحل النشاط، ويصدر أوامر مختلفة لمواءمة الحالة الفعلية لحِزم الخدمات مع الحالة المستهدَفة المحسوبة.

حالات المركبة والطاقة

يتيح وكيل "وضع المركبة" وإدارة الطاقة (VPM) لمكوّنات المركبة المحدّدة بالبرامج (SDV) معرفة الحالة الحالية للمركبة، مثل وضع التشغيل (على سبيل المثال، في وضع "الركن" أو "القيادة") وحالة الطاقة (على سبيل المثال، "تشغيل" و"تعليق"). يقيّم Orchestrator هذه القيم لتحديد حِزم الخدمات التي يجب تشغيلها استنادًا إلى إعدادات Orchestrator. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إدارة المركبة والطاقة.

أوضاع مخصّصة

وبالنظر إلى عددها الكبير، لا يمكننا تصميم جميع أوضاع المركبات. لكل مصنّع معدات أصلية احتياجات مختلفة، ولا يمكن أن يلبّي توحيد أوضاع المركبة جميع حالات الاستخدام لدى مصنّعي المعدات الأصلية. نتيجةً لذلك، نتيح استخدام أوضاع خاصة بمقدّمي خدمة OEM، تُعرف باسم الأوضاع المخصّصة. لا توسّع هذه الأوضاع نطاق أوضاع المركبة والطاقة الحالية. بدلاً من ذلك، توفّر هذه الفئات طريقة لتحديد أوضاع جديدة.

الوظائف:

  • النطاق العام: تكون الأوضاع المخصّصة عامة، ويتم تطبيقها بشكل موحّد على جميع الأجهزة الافتراضية التي يديرها Orchestrator.

  • التركيب: يتألف كل تغيير في الوضع المخصّص من عنصرَين:

    • الاسم: معرّف فريد تختاره الشركة المصنِّعة للأجهزة الأصلية لتمثيل الوضع المخصّص.

    • القيمة: هي الحالة الحالية للوضع المخصّص، ويمكن أن تكون UNDEFINED عندما لا يتم ضبط أي قيمة.

  • دور المنسّق: يعمل المنسّق كمستقبِل سلبي لقيم الوضع المخصّص.

  • دور حزمة الخدمات: يمكن أن تمتلك كل حزمة خدمات أوضاعًا مخصّصة متعددة ويمكنها نشر قيم جديدة إلى أي منها. يمكن أن تمتلك حِزم خدمات متعدّدة الوضع المخصّص نفسه، ما يعني أنّ الوضع المخصّص يمكن أن يتلقّى قيمًا جديدة من مصادر مختلفة.

  • مسؤولية التحقّق من الصحة: يتحمّل مصنّعو المعدات الأصلية مسؤولية ضمان صحة عمليات نقل البيانات بين الحالات. يقبل Orchestrator أي قيمة جديدة.

السمات المقدَّرة:

  • العدد المقدَّر: تدير أوضاع الطاقة والمركبة مراحل نشاط معظم حِزم الخدمات، وتلعب الأوضاع المخصّصة دورًا تكميليًا. نتوقّع أن يكون عدد الأوضاع المخصّصة عشرات وليس مئات.

  • التوقيت المقدَّر: لا يتم إرسال الأوضاع بشكل منتظم. بدلاً من ذلك، تستند الأوضاع إلى الأحداث، ويتم تشغيلها من خلال إجراءات معيّنة، مثل فتح باب أو بدء تسلسل ركن السيارة أو بدء دورة شحن أو أحداث أخرى مماثلة ذات أهمية يحدّدها المصنّع الأصلي للجهاز.

يتيح تصميم الوضع المخصّص المرونة في تحديد أوضاع معيّنة وإدارتها، مع السماح لـ Orchestrator بالبقاء غير مرتبط بمنطق آلة الحالة الأساسية.

الأوضاع المتوافقة

لضمان عدم نشر حِزم الخدمات إلا في الأوضاع المخصّصة التي تملكها، يجب أن تحدّد كل حزمة بوضوح قائمة الأوضاع المخصّصة التي تملكها ضمن إعدادات Orchestrator، والتي تتوفّر في الجهاز الافتراضي المحلي مع سجلّ حِزم الخدمات. ويتم تجاهل محاولات النشر في وضع مخصّص غير معرَّف.

لتحديد الأوضاع المخصّصة التي يُسمح لحزمة الخدمة بنشرها (وبالتالي امتلاكها)، يتم توسيع مخطط service_bundle_config الأوّلي ليشمل ما يلي:

// Service bundle configuration.
//
// Defines service bundle metadata, its instances, and configuration for instances
// lifecycle states depending on the state of the vehicle.
message ServiceBundleConfig {
      [...]

    // The list of custom modes that this service bundle publishes.
    repeated string custom_mode = 5;
}

ضبط الحِزم استنادًا إلى الأوضاع

يتيح إعداد بروتوكول Orchestrator الحالي (المكوّن Condition) تعديل حِزم الخدمات استنادًا إلى أوضاع مخصّصة:

message Condition {
  oneof root {
    string power_state = 1;
    string vehicle_state = 2;
    CustomState custom_state = 3;
    Condition not = 4;
    Expression and = 5;
    Expression or = 6;
  }
}

message CustomState {
  // Custom mode being checked.
  string mode = 1;
  // State of the custom mode.
  string state = 2;
}

عيّنة Proto

يوضّح المثال التالي كيفية ضبط مثيلات لحزمة خدمة ليتم بدء تشغيلها استنادًا إلى حالة TURN وFOG:

service_bundle_config {
package_name: "oem.package"
service_bundle_name: "OemApplication"
instance: "flasher_light"
// Service bundle is allowed to set values for the TURN mode
custom_mode: "TURN"
// Service bundle is allowed to set values for the FOG mode
custom_mode: "FOG"

state {
    condition {
        custom_state {
            mode: "TURN"
            state: "LEFT"
        }
    }
    instances_states {
        started: "flasher_light"
    }
}

state {
    condition {
        custom_state {
            mode: "FOG"
            state: "ON"
        }
    }
    // Group assumed to be defined containing all FOG lights instances.
    groups_states {
        started: "fog_lights"
    }
}

}

ضبط أوضاع مخصّصة جديدة

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

متوسط عائد النقرة

ينشئ كل Orchestrator يعمل على كل آلة افتراضية خادم RPC للاستماع إلى قيم الوضع المخصّص الجديدة. يجب أن تنشئ كل حزمة خدمات تريد تعديل وضع مخصّص عميل RPC للخادم. يتم فرض قوائم التحكم بالوصول لمنع الحِزم غير المصرَّح بها من الاتصال بالخادم.

يبدو تعريف البروتوكول لتحديد قيمة جديدة من خلال RPC على النحو التالي مثال:

syntax = "proto3";

import "google/protobuf/timestamp.proto";

package com.sdv.google.Orchestrator;

// Representation of the request used by service bundles to update a custom mode.
// Service bundles are permitted to update only the custom modes specifically designated
// for them within the Orchestrator configuration.
message SetCustomStateRequest {
  // Required.
  // The name of the custom mode.
  // The mode string can not be longer than 56 characters and can only contain
  // letters, numbers, dashes, dots and underscores: [a-zA-Z0-9_-.].
  // No other special character nor spaces should be present in the mode.
  string mode = 1;

  // Required.
  // The new value for the custom mode.
  // The value string can not be longer than 56 characters and can only contain
  // letters, numbers, dashes, dots and underscores: [a-zA-Z0-9_-.].
  // No other special character nor spaces should be present in the value.
  string value = 2;

  // Required.
  // The timestamp in which the new custom mode value was set. This is used to
  // prevent race conditions whenever different service bundles in different
  // VMs want to set a new value for the same custom mode.
  // We use this timestamp to order the requests and we promise eventual
  // consistency: while temporary inconsistencies may occur, the system will
  // eventually converges to the correct state.
  .google.protobuf.Timestamp timestamp = 3;
}

// Representation of the set custom state response.
message SetCustomStateResponse {}

// Orchestrator interface for service bundles that update the value of a
// custom mode.
// When a new value is received, it is propagated to Orchestrators running on
// other VMs.
service CustomStateService {
  // Updates the value for the custom mode.
  // Returns the error:
  // - PermissionDenied: the service is not authorized to update the custom mode.
  // - InvalidArgument: the provided mode and/or value are not valid.
  rpc SetCustomState(SetCustomStateRequest) returns (SetCustomStateResponse) {};
}

إلغاء عمليات التبديل بين مصادر الطاقة

يسمح Orchestrator بإلغاء عمليات نقل الطاقة الجارية من خلال وضع الطاقة SHUTDOWN_CANCELLED (الذي ترسله VPM إلى Orchestrator).

في ما يلي مثال على إعداد Orchestrator:

state {
    condition {
        power_state: "SUSPEND_TO_RAM_ENTER"
    }
    instances_states {
        started: "instance-1"
        started: "instance-2"
        started: "instance-3"
    }
}

عند تلقّي وضع SHUTDOWN_CANCELLED، يحدّد سيناريوهان أساسيان سلوك "المنسّق". في كلتا الحالتين، تتم إضافة وضع الطاقة SHUTDOWN_CANCELLED إلى نهاية قائمة الانتظار. بعد ذلك، يتم تنفيذ SHUTDOWN_CANCELLED بعد استخدام العناصر التي تم وضعها في قائمة الانتظار.

السيناريو 1: الوضع الحالي قيد التقدم هو وضع طاقة

إذا كان Orchestrator ينفّذ عملية تعديل لوضع الطاقة، سيتم طلب إلغاء الوضع قيد التنفيذ. على الرغم من أنّ أداة Lifecycle Manager لا تتيح بشكل أساسي إلغاء عملية نقل قيد التقدّم، تتحقّق أداة Orchestrator من عدم بدء أي طلبات جديدة لحِزم الخدمات.

مثال: إذا كان instance-1 من الإعداد في المثال السابق في طور البدء عند تلقّي وضع SHUTDOWN_CANCELLED، يكمل instance-1 عملية بدء التشغيل. ومع ذلك، لا تنتقل الحالتان instance-2 وinstance-3 إلى الحالة "بدأ".

السيناريو 2: توفُّر وضع طاقة في قائمة انتظار المعالجة

في حال كان Orchestrator يعالج عملية تعديل غير مرتبطة بوضع الطاقة، وكان هناك طلب طاقة في صفّ الأوضاع التي سيتم تنفيذها، تتم إزالة عملية انتقال الطاقة من صفّ الانتظار. ويمنع ذلك تنفيذه.

مثال: باستخدام الإعدادات في المثال السابق، إذا كان Orchestrator يعمل على تحديث غير مرتبط بالطاقة (مثل تحديث المركبة) وكانت SUSPEND_TO_RAM_ENTER في قائمة الانتظار، لن يتم بدء أي من النسخ (instance-1 وinstance-2 وinstance-3) عند تلقّي SHUTDOWN_CANCELLED.

مثال على التنفيذ

يمكن أن يبدو فهرس العميل الذي يريد استخدام الرمز الذي تم إنشاؤه بواسطة البرامج الوسيطة لإنشاء عميل لخادم RPC على النحو التالي:

# proto-file: //system/software_defined_vehicle/vsidl/language/src/protos/sdv/vsidl/v1/syntax.proto
# proto-message: VsidlEntry

package: "package_name"

service_bundle {
    name: "service_bundle_name"

    client {
        service: "com.android.sdv.orchestrator.CustomStateService"
    }
}

عند إنشاء الرمز، يجب إضافة التبعية إلى فهرس Orchestrator:

--dependency-catalog-path orchestration/engine/stable/vsidl/*

يبدو رمز العميل لإرسال قيمة جديدة على النحو التالي:

let fqin = ServiceFqin::builder()
        .sdv_vm_name("vm_name")
        .sdv_package_name("package_name")
        .service_bundle_name("service_bundle_name")
        .service_instance_name("instance_name")
        .build()
        .unwrap();
let context_ref = ContextRef::create(fqin);
let comms = Arc::new(SdvComms { context: context_ref });
// service_bundle_name is the bundle generated with middleware code that defines
// the RPC client to "com.android.sdv.orchestrator.CustomStateService".
let client = service_bundle_name::new(comms).await.unwrap();
let rpc_client = client
        .create_rpc_client::<Client>(
            UnitName::builder()
                .vm_name(comms.context.get_self_fqin().get_sdv_vm_name())
                .package_name("com.android.sdv.orchestrator")
                .bundle_name("OrchestratorServiceBundle")
                .service_unit_name(Client::DEFAULT_UNIT_NAME)
                .build()
                .unwrap(),
            ClientOptions::default(),
        )
        .await;
let client = Arc::new(rpc_client.unwrap());
let request = SetCustomStateRequest {
mode: custom_mode_name,
value: custom_mode_value,
timestamp: MessageField::some(Timestamp::now()),
..Default::default()
};
let result = client.SetCustomState(&request).await;
// Process result

أدوات تصحيح الأخطاء

يتوافق وكيل Orchestrator مع أداة dumpsys. يمكنك استدعاء هذه الأداة من خلال تنفيذ الأمر التالي على مثيل SDV قيد التشغيل:

adb shell dumpsys com.google.sdv.ISdvAgent/orch

استخدِم هذه الأداة لتصحيح الأخطاء والاطّلاع على حالة وكيل Orchestrator الداخلية. سيؤدي ذلك إلى عرض ما يلي:

  • حالة الأوضاع الحالية: يمكنك الاطّلاع على أوضاع السيارة والطاقة والأوضاع المخصّصة النشطة.
  • الناشرون في "الوضع المخصّص": حدِّد الخدمات التي يمكنها نشر أوضاع مخصّصة (والأوضاع التي يمكنها نشرها).
  • الحالة المطلوبة لكل خدمة: يمكنك التعرّف على حالة كل حزمة خدمات استنادًا إلى الشروط المحدّدة مسبقًا والأوضاع الحالية. يساعد ذلك في تشخيص سبب عدم توفّر خدمة معيّنة بالحالة المتوقّعة.
  • حالة تنفيذ الوضع: يمكنك الحصول على صورة واضحة للوضع الذي يتم تنفيذه حاليًا، أو آخر وضع تم تنفيذه إذا لم يكن هناك أي وضع قيد التنفيذ.
  • قائمة انتظار فرض الوضع: يمكنك الاطّلاع على الأوضاع التي تنتظر فرضها.

على سبيل المثال:

AGENT NAME: SDV Agent dump - Orchestrator
AGENT FQIN: instance1:com.android.sdv.orchestrator.OrchestratorServiceBundle/default
AGENT STATE: See orchestrator state below.
----------------
----------------
INTERNAL STATE REPORTERS:

*NAME: Configuration state
*REPORT:
Active modes:
MODE                          VALUE                         TIMESTAMP (scs, ns)
Power                         POWER_OFF_EXIT                -
Vehicle                       VEHICLE_ON                    -
Custom("CHARGING")            ON                            1750757590 (scs) 466507459 (ns)
Custom("TIRE_PRESSURE")       front-left                    1750757570 (scs) 554522995 (ns)

Modes allowed to publish by bundle (FQIN: modes):
com.android.sdv.sample.orchestration/CustomModeControlBundle: CHARGING, TIRE_PRESSURE

Requested state for instances:
STATE          FQIN
Started        com.android.sdv.sample.orchestration/CustomModeControlBundle/always-started-instance
Started        com.android.sdv.sample.orchestration/OrchestratedServiceBundle/my-instance
Started        com.sdv.oem.sample.diagnostics/DiagnosticsSampleWithDataItem/instance
Started        com.sdv.oem.sample.diagnostics/DiagnosticsSampleWithEvent/instance
Started        com.sdv.oem.user_preferences/UserPreferencesServiceBundle/default
----------------
*NAME: Engine state
*REPORT:
Last mode enforced was Custom("CHARGING") with value "ON"

Next modes to process: []
----------------

لمزيد من المعلومات حول حِزم الخدمات الفردية التي يديرها Orchestrator، استخدِم الأمر dumpsys الحالي من Lifecycle Manager على النحو التالي:

dumpsys google.sdv.lifecycle.ILifecycleManager/default

يؤدي ذلك إلى توفير معلومات تفصيلية حول حالة دورة حياة كل خدمة. من خلال الجمع بين ناتج dumpsys الخاص بـ Orchestrator والناتج من Lifecycle Manager، يمكن الحصول على صورة كاملة عن دورة حياة حِزم الخدمات في الجهاز الظاهري.