Mengonfigurasi Orchestrator

Orchestrator adalah agen SDV lokal yang berjalan di setiap virtual machine (VM) dan menyediakan mekanisme untuk mengontrol kapan paket layanan harus dibuat, dimulai, dihentikan, atau dihancurkan. Hal ini dilakukan melalui konfigurasi orkestrasi, tempat Anda menentukan serangkaian aturan yang menentukan kapan dan bagaimana tindakan dilakukan pada instance paket layanan. Aturan ini didasarkan pada mode kendaraan, daya, dan kustom.

Anda dapat mengonfigurasi Orchestrator di APEX konfigurasi atau melalui konfigurasi per VM. Sistem konfigurasi terdistribusi ini memungkinkan bagian dari setiap paket layanan diperbarui secara independen melalui Registry Paket Layanan, seperti yang diilustrasikan di sini.

Diagram konfigurasi terdistribusi Orchestrator

Gambar 1. Diagram konfigurasi pengorkestrasi.

Konfigurasi independen kendaraan tidak berubah, bergantung pada OEM atau kendaraan. Konfigurasi tetap sama di semua kendaraan setiap OEM. Konfigurasi khusus kendaraan dapat berbeda pada kendaraan yang berbeda oleh OEM yang berbeda, meskipun konfigurasi dapat sama untuk semua kendaraan yang dibuat oleh OEM tertentu.

APEX konfigurasi

Saat runtime, Orchestrator membuka registry paket layanan untuk mengambil orkestrasi SDV untuk setiap paket layanan, memuat dan mengurai setiap konfigurasi. Untuk mempelajari lebih lanjut, lihat Metadata orkestrasi.

Konfigurasi per VM

Saat dimulai, Orchestrator akan memuat dan mengurai konfigurasi VM (jika ada). Jalur absolut ke file konfigurasi ini ditentukan melalui properti sistem persist.sdv.orchestrator_config_path dan ro.boot.sdv.orchestrator_config_path.

Sistem menentukan jalur file konfigurasi VM saat booting berdasarkan hierarki berikut:

  1. Sistem memeriksa properti persist.sdv.orchestrator_config_path. Jika memiliki nilai, jalur tersebut akan digunakan. Nilai ini dipertahankan saat perangkat di-reboot atau ditetapkan saat runtime.

  2. Jika persist.sdv.orchestrator_config_path kosong, sistem akan memeriksa properti ro.boot.sdv.orchestrator_config_path. Jika properti ro.boot.sdv memiliki nilai, jalur tersebut akan disalin ke properti persist dan digunakan untuk booting saat ini dan semua booting berikutnya (kecuali jika diganti).

persist.sdv.orchestrator_config_path

persist.sdv.orchestrator_config_path adalah properti utama yang digunakan oleh agen SDV Orchestrator untuk mendapatkan jalur ke file konfigurasinya. Ini adalah properti persisten, yang berarti nilainya disimpan saat perangkat di-reboot. Anda dapat mengubah nilai saat runtime, yang berguna untuk pengujian atau skenario tertentu (misalnya, pengujian end-to-end).

Anda dapat menetapkan nilai saat runtime menggunakan perintah setprop, dan saat waktu build menggunakan makefile (dengan ekstensi .mk) atau file skrip resource, dengan ekstensi .rc.

Menetapkan properti saat runtime

Menetapkan properti saat runtime berguna untuk menguji atau membuat perubahan sementara, karena nilai disimpan di seluruh reboot:

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

Menetapkan properti pada waktu build

Untuk menyetel properti ini sebagai bagian dari konfigurasi build perangkat Anda, tambahkan baris ke makefile produk atau papan Anda. Hal ini ideal untuk menetapkan nilai default untuk gambar perangkat baru.

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

Anda juga dapat menetapkan properti ini dalam file skrip resource:

# 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 adalah properti hanya baca saat booting yang digunakan untuk memberikan nilai awal untuk properti persist.sdv.orchestrator_config_path. Jika persist.sdv.orchestrator_config_path kosong saat sistem di-boot, nilai ro.boot.sdv.orchestrator_config_path akan disalin ke persist.sdv.orchestrator_config_path. Setelah persist.sdv.orchestrator_config_path ditetapkan, properti ini tidak akan ditimpa oleh properti ini pada proses booting berikutnya.

Anda dapat menyetel ro.boot.sdv.orchestrator_config_path menggunakan bootconfig atau cmdline kernel.

Format file

Tentukan konfigurasi orkestrasi dalam format .textproto (misalnya, dalam teks terstruktur) sehingga konfigurasi baru dapat dimuat saat runtime.

Sintaksis konfigurasi

Bagian ini menjelaskan sintaksis konfigurasi.

Paket layanan

Setiap paket layanan harus ditentukan dengan konfigurasi Paket layanan, yang mengidentifikasi paket dalam Orchestrator dan digunakan untuk menangani siklus proses instance paket. Konfigurasi paket layanan menentukan:

  • InstanceToGroupMapping memungkinkan Anda menyertakan instance paket layanan dalam grup untuk membuat dependensi antara instance paket layanan yang sama.

  • InstancesStates menentukan berbagai status untuk instance paket layanan.

  • InstancesStateConfiguration menentukan status (dari InstancesStates) yang harus ditetapkan untuk instance paket layanan jika kondisi bernilai true.

  • ServiceBundleConfig berisi informasi tentang paket layanan tertentu dan instance-nya. Untuk paket, file ini berisi InstanceToGroupMapping dan InstancesStateConfiguration masing-masing.

  • CustomModes menentukan daftar mode kustom yang diizinkan untuk dipublikasikan oleh paket. CustomModes digunakan untuk mencegah paket yang tidak sah memodifikasi nilai mode kustom. Kolom ini bersifat opsional, karena paket layanan mungkin tidak dipublikasikan ke mode kustom mana pun. Untuk mempelajari lebih lanjut, lihat Mode kustom.

Konfigurasi paket yang diperlukan

Minimal, konfigurasi paket menyediakan atribut berikut:

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

    instance: "instance_1"
    instance: "instance_n"
}

Deklarasi ini menentukan instance paket layanan n dengan FQIN masing-masing:

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

Nama VM tidak dideklarasikan secara eksplisit dalam konfigurasi. Karena konfigurasi ditentukan per VM, nama VM selalu menjadi nama VM yang file konfigurasinya di-deploy dan sudah diketahui oleh agen orkestrasi.

Mengonfigurasi instance

Mendeklarasikan instance paket layanan tidak akan berpengaruh. Agar dapat dieksekusi oleh Orchestrator, instance harus dikonfigurasi. Misalnya, Orchestrator harus diberi tahu kondisi (atau status VM atau kendaraan) yang harus dijalankan oleh instance. Untuk mengonfigurasi instance, status konfigurasi harus ditentukan melalui:

  • condition adalah ekspresi pada status VM atau kendaraan yang harus dievaluasi.

  • instances_states adalah serangkaian status per instance yang harus diterapkan jika kondisi bernilai true.

Untuk mempelajari lebih lanjut, lihat Kondisi.

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

Pemetaan instance ke grup

Anda juga dapat mengonfigurasi instance layanan dengan menyertakannya dalam grup layanan. Di tingkat konfigurasi paket layanan, Anda dapat menambahkan instance ke grup. Kemudian, Anda dapat mengonfigurasi grup di tingkat konfigurasi VM. Untuk mempelajari lebih lanjut, lihat bagian berikutnya dan Paket layanan.

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

Skema proto

Berikut contoh skema 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;
}

Konfigurasi tingkat VM

Konfigurasi VM memungkinkan definisi pemetaan grup dan konfigurasi untuk grup. Fitur ini digunakan untuk memodelkan dependensi antar-paket layanan di tingkat VM, sehingga memberikan fleksibilitas untuk mengubah status beberapa paket layanan secara bersamaan. Semua instance dalam grup akan berada dalam status yang ditentukan.

Orchestrator tidak menjamin urutan perubahan status dieksekusi. Orchestrator mempromosikan setiap instance agar berada dalam status yang diberikan.

Grup dideklarasikan secara implisit dengan menggunakan nama group di bagian konfigurasi mana pun. Misalnya, pemetaan instance ke grup, pemetaan grup ke grup, dan status konfigurasi grup.

Pemetaan grup ke grup

Grup dapat berisi grup lain. Dengan menyatakan bahwa group_1 berisi subgroup_2, kita secara efektif menambahkan semua instance layanan dari subgroup_2 ke group_1.

Contoh:

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

Mengonfigurasi grup

Mendeklarasikan grup tidak akan berpengaruh. Agar dapat dieksekusi oleh Orchestrator, grup harus dikonfigurasi. Misalnya, Orchestrator harus diberi tahu kondisi atau status VM atau kendaraan yang akan menjalankan grup.

Anda dapat mengonfigurasi grup dengan cara yang serupa dengan instance layanan, yaitu dengan menggunakan status konfigurasi. Satu-satunya perbedaan adalah penggunaan groups_states alih-alih instances_states dalam sintaksis:

state {
    condition {
        power_state: "ON"
    }

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

Skema proto

Berikut adalah contoh skema 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;
}

Status konfigurasi

Status konfigurasi (status) menentukan kapan instance atau grup layanan dimulai, dihentikan, atau dihancurkan dan terdiri dari conditions dan instances_states (konfigurasi paket) serta groups_states (konfigurasi VM).

Kondisi

Kondisi memungkinkan model memiliki kondisi boolean yang, jika dievaluasi menjadi true, status instance yang ditentukan akan diterapkan. Kondisi memiliki karakteristik berikut:

  • Ekspresi boolean yang kompleks secara arbitrer (dibentuk dengan ekspresi and atau not ) berdasarkan sinyal yang didukung seperti daya, kendaraan, dan mode kustom.

  • (Opsional) Status config tanpa kondisi selalu aktif, yang berarti dievaluasi menjadi true

Status instance dan status grup

instances_states dan groups_states memiliki karakteristik berikut.

  • Mendikte status mana yang diperlukan oleh agen orkestrasi untuk diterapkan ke instance atau grup tertentu, mengingat statusnya adalah active

  • Saat menerapkan status ke grup, status tersebut akan diterapkan ke setiap instance paket layanan dalam grup. Tidak ada urutan yang diterapkan untuk kapan instance dibawa ke status tersebut.

Negara bagian yang didukung meliputi:

  • started setelah Service::on_start dipanggil.

  • created

    • setelah Service::new dipanggil, tetapi sebelum Service::on_start dipanggil.

      ATAU

    • setelah Service::on_stop dipanggil, tetapi sebelum Service::drop dipanggil.

  • destroyed setelah Service::drop dipanggil.

Set aturan

Status konfigurasi dapat berupa aktif atau tidak aktif, bergantung pada kondisinya. Beberapa status dapat aktif kapan saja. Saat menerima update sinyal, agen orkestrasi akan mengevaluasi semua status konfigurasi sebelum mengubah siklus proses paket layanan. Status instance layanan dievaluasi sesuai dengan aturan berikut:

  • Jika tidak ada status aktif yang berlaku untuk instance layanan, instance tersebut akan dihancurkan.

  • Jika satu atau beberapa status aktif berlaku, prioritas ini berlaku:

    1. destroyed memiliki prioritas mutlak.
    2. started lebih diprioritaskan daripada created.

Skema proto

Berikut adalah contoh skema 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;
}

Strategi pemulihan dan mulai ulang error

Orchestrator menyediakan mekanisme yang andal untuk menangani error paket layanan dan kegagalan transisi siklus proses. Karena Orchestrator memiliki tampilan holistik status layanan dan mengelola transisi mode, Orchestrator adalah komponen yang paling sesuai untuk menjalankan strategi mulai ulang dan coba lagi. Layanan pelaporan Lifecycle Manager (LM) melaporkan error paket layanan ke Orchestrator melalui notifikasi kematian binder. Untuk menghindari panggilan binder yang tidak perlu ke LM, Orchestrator meng-cache status terakhir setiap paket (berhasil atau tidak) dan tidak menerapkan kembali transisi jika status terakhir yang diketahui sama dengan status baru yang diminta.

Konfigurasi percobaan ulang

Anda dapat menentukan strategi mulai ulang dan coba lagi per instance dalam konfigurasi Orchestrator menggunakan retry_mapping. Jika max_retries tidak disetel dalam konfigurasi, nilai default akan diambil dari properti sistem ro.boot.sdv.orchestrator.recovery.max_retries. Jika properti ini tidak ditetapkan, nilai akan ditetapkan ke 0.

  • max_retries: Menentukan berapa kali Orchestrator mencoba kembali transisi setelah kegagalan sementara atau notifikasi error bundle. Penghitung coba lagi direset ke nilai max_retries setelah operasi berhasil atau saat mode baru diproses. Jika beberapa pemetaan menargetkan instance yang sama, pemetaan dengan max_retries tertinggi akan diprioritaskan.

Contoh konfigurasi

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

Perilaku pemulihan

Logika mulai ulang dan coba lagi Orchestrator mengelola beberapa skenario kegagalan dengan baik:

  • Error operasi normal: Jika paket layanan error saat berjalan, Orchestrator akan menerapkan strategi mulai ulang dan mencoba mengembalikan paket ke status yang terakhir diminta berdasarkan percobaan ulang yang tersisa.
  • Error saat transisi mode: Jika paket mengalami error saat menerapkan mode baru, permintaan mulai ulang akan dimasukkan dalam antrean dan diproses nanti. Setelah permintaan diproses, Orchestrator akan memeriksa status terakhir instance dan hanya menerapkan mulai ulang jika instance tidak berada pada status yang terakhir diminta (dari transisi mode terakhir).
  • Mode baru selama pemulihan: Jika Orchestrator menerima permintaan untuk beralih ke mode baru saat paket sedang dimulai ulang (atau berada dalam antrean instance untuk dimulai ulang), Orchestrator akan membatalkan pemulihan yang sedang berlangsung. Transisi mode baru akan mengambil alih, dan penghitung percobaan ulang akan direset untuk memungkinkan serangkaian percobaan baru untuk status target baru.

Orchestrator membedakan berbagai jenis error yang ditampilkan oleh Lifecycle Manager untuk menentukan strategi percobaan ulang:

  • Error sementara (SERVICE_NOT_FOUND, OPERATION_FAILED, INTERNAL_ERROR): Orchestrator mencoba lagi operasi tanpa melakukan tindakan pembersihan khusus.
  • Error persisten (VALUE_CORRUPTED, INVALID_ARGUMENT): Orchestrator mengasumsikan bahwa paket layanan mungkin dalam keadaan rusak dan mencoba menghentikan instance layanan sebelum mencoba lagi operasi untuk memastikan mulai ulang yang bersih.
  • Error permanen (PERMISSION_DENIED): Operasi tidak dicoba ulang, dan paket dianggap berada dalam status yang tidak dapat dipulihkan.

Jika Lifecycle Manager error, semua proses paket layanan akan hilang. Karena status sebenarnya tidak diketahui, Orchestrator membatalkan validasi setiap instance dan menerapkan strategi mulai ulang dengan percobaan ulang yang tersisa untuk membawa setiap instance ke status yang terakhir diminta.

Untuk mencegah loop pemulihan tak terbatas untuk paket yang berulang kali mengalami error atau gagal, penghitung percobaan ulang hanya direset ke max_retries setelah operasi siklus proses berhasil, atau saat transisi mode baru diminta. Jika paket kehabisan upaya coba lagi karena kegagalan berturut-turut (misalnya, kegagalan transisi yang diikuti dengan error), paket tidak akan dimulai ulang hingga penghitung upaya coba lagi direset.

Pelaporan Status ke Pemantau Kondisi

Orchestrator mengekspos antarmuka binder internal yang didaftarkan oleh Health Monitor (HM), sehingga memungkinkannya menerima update berkelanjutan tentang status semua paket layanan. Melalui antarmuka ini, Orchestrator secara aktif melaporkan keduanya:

  • Status siklus proses: Status instance yang dimaksud berdasarkan konfigurasi saat ini dan mode aktif (seperti dimulai, dibuat, atau dihancurkan).
  • Status pemulihan: Status pencapaian status siklus proses yang diinginkan, yang menunjukkan apakah instance beroperasi, saat ini mencoba lagi setelah gagal, atau gagal dipulihkan setelah semua percobaan ulang habis.

Informasi ini dilaporkan untuk semua instance, termasuk yang belum terdaftar untuk dipantau detak jantungnya. HM menggunakan informasi ini untuk menerapkan API-nya guna melaporkan status VM. Anda dapat mempelajari lebih lanjut di bagian Pemantauan kesehatan.

Contoh

Bagian ini menyajikan contoh untuk mengonfigurasi status dengan kondisi.

Contoh layanan dasar
  • Tidak memiliki kondisi dan oleh karena itu selalu aktif.
  • Memulai satu instance layanan.
state {
  # Note: This state has no condition, hence its actions are valid throughout the lifetime of the program
  instances_states { started: "ServiceBundleName" }
}
Contoh aplikasi HVAC

  • Kondisi: Aktif saat custom_state != occupancy.OCCUPANCY_EMPTY || custom_state == preheat.PREHEAT_ON.

  • Mendeklarasikan beberapa instance layanan terkait HVAC sebagai 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"
  }
}
Contoh penghematan daya

  • Kondisi: Aktif saat custom_state == system_power.SYSTEM_POWER_LOW && custom_state == range_ext.RANGE_EXT_ON.

    Status ini dapat dilihat sebagai status penghematan daya.

  • Mendeklarasikan satu instance layanan terkait HVAC sebagai destroyed.

  • Dalam contoh ini, saat mode SYSTEM_POWER_LOW dan RANGE_EXT_ON aktif, aplikasi HVAC berjalan tanpa instance layanan 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" }
}
Contoh Life onboard

  • Kondisi: Aktif jika power_state == ON && vehicle_state == LIFE_ON_BOARD.

    Status ini dapat dilihat sebagai Seseorang berada di dalam mobil dan mobil dinyalakan.

  • Mendeklarasikan sensor suhu sebagai sedang berjalan.

  • Saat seseorang berada di dalam mobil, item seperti suhu dipantau untuk alasan keamanan.

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

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

Contoh

Bagian ini menyajikan contoh lengkap yang berisi:

  • Konfigurasi proto tingkat paket layanan yang memperkenalkan paket layanan dengan dua instance, yang masing-masing merupakan bagian dari grup

  • Konfigurasi proto tingkat VM yang memperkenalkan logika untuk berinteraksi dengan grup berdasarkan mode

Konfigurasi tingkat paket layanan

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

Konfigurasi tingkat VM

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

Mengonfigurasi paralelisme pengelolaan paket

Properti sistem ro.boot.sdv.max_bundles_management_threads adalah parameter penyesuaian utama untuk mengontrol performa dan konsumsi resource selama operasi siklus proses paket layanan. Setelan ini menentukan tingkat paralelisme maksimum untuk transaksi paket layanan dan secara langsung memengaruhi dua layanan inti:

  1. Mesin Orkestrasi: Layanan ini membaca properti untuk menentukan jumlah panggilan serentak (misalnya, startService, stopService) yang dapat dilakukan Orchestrator ke Pengelola Siklus Proses. Hal ini sangat penting untuk performa selama proses booting dan transisi mode saat banyak paket dapat berubah status secara bersamaan.

  2. Lifecycle Manager: Layanan ini menggunakan nilai properti untuk menghitung ukuran kumpulan thread Binder-nya, yang bertanggung jawab untuk menangani semua permintaan masuk. Hal ini memastikan bahwa LM memiliki cukup thread untuk menangani permintaan serentak dari Orchestrator.

Jika properti ini tidak ditetapkan, kedua layanan akan ditetapkan secara default ke nilai 12.

Metode konfigurasi

Anda dapat menyetel properti di file BoardConfig.mk perangkat dengan menambahkannya ke variabel BOARD_BOOTCONFIG. Hal ini memastikan nilai diterapkan setiap kali perangkat di-boot.

BOARD_BOOTCONFIG += \
    androidboot.sdv.max_bundles_management_threads=8

Untuk mengubah nilai perangkat Anda, ubah baris ini di file BoardConfig.mk yang sesuai dan bangun kembali.

Pengoptimalan waktu booting

ro.sdv.orchestrator.state.ready adalah properti boolean write-once yang merupakan bagian dari strategi pengoptimalan performa waktu booting. Hal ini menunjukkan bahwa agen Orkesrasi telah menyelesaikan inisialisasinya dan siap untuk mulai mengelola siklus proses paket layanan. Tujuan utamanya adalah memprioritaskan startup Orchestrator dan paket layanan terkelolanya dengan mengontrol urutan startup agen SDV lainnya.

  • Ditetapkan oleh: Agen Orkestrasi.
  • Kapan: Sekali selama urutan booting.
  • Penggunaan: Properti ini digunakan oleh sistem init untuk mengontrol urutan startup sebagian besar agen SDV (Updates Manager, penyedia VSIDL, Health Monitor, Service Discovery, Data Tunnel, RPC, VPM, dan Telemetry). Dengan memulai Orchestrator lebih awal dan membuat agen lain menunggu properti ini, sistem memastikan bahwa Orchestrator dapat memulai tugas pentingnya untuk memulai paket layanan tanpa bersaing untuk mendapatkan resource sistem.

Performa

Selama booting sistem, memulai semua agen secara bersamaan dapat menyebabkan perebutan resource, sehingga memperlambat proses booting secara keseluruhan. Untuk mengurangi hal ini, urutan pengaktifan berurutan diterapkan menggunakan properti sistem:

  1. Registry paket layanan: Dimulai terlebih dahulu untuk memuat semua metadata paket layanan.
  2. Lifecycle Manager dan Orchestrator: Agen inti ini dimulai segera setelah registri siap. Awal yang lebih awal ini sangat penting karena memungkinkan Orchestrator mulai mengevaluasi konfigurasinya dan bersiap untuk memulai paket layanan dengan segera.
  3. Agen SDV lainnya: Dimulai hanya setelah Orchestrator siap.

Urutan yang dikontrol ini memastikan Orchestrator memiliki prioritas untuk menggunakan resource sistem guna memulai paket layanan sesegera mungkin, sehingga menghasilkan startup sistem yang lebih cepat, lebih deterministik, dan lebih efisien.

Mode yang digunakan oleh Orchestrator

Agen orkestrasi mempertahankan langganan aktif ke mode kendaraan dan daya yang dikirimkan oleh VPM. Setelah koneksi awal antara Orchestrator dan sistem Vehicle and Power Management (VPM) dibuat, Orchestrator menetapkan properti sistem boolean berikut ke true:

  • sdv.orchestrator.bootup.power_mode.ready

  • sdv.orchestrator.bootup.vehicle_mode.ready

Dengan menggunakan file konfigurasi sebagai referensi, agen orkestrasi akan menghitung secara dinamis kumpulan paket layanan yang harus dalam status berjalan berdasarkan nilai mode yang diterima saat ini. Kemudian, Orchestrator berkomunikasi dengan pengelola siklus proses, mengeluarkan berbagai perintah untuk menyelaraskan status sebenarnya paket layanan dengan status target yang dihitung.

Status kendaraan dan daya

Agen Vehicle mode and power management (VPM) memungkinkan komponen SDV diberi tahu tentang status kendaraan saat ini, seperti mode operasional (misalnya, dalam mode Parkir atau Mengemudi) dan status daya (misalnya, Aktif dan Ditangguhkan). Orchestrator mengevaluasi nilai ini untuk menentukan paket layanan mana yang harus dijalankan berdasarkan konfigurasi Orchestrator. Untuk mempelajari lebih lanjut, lihat Pengelolaan daya dan kendaraan.

Mode kustom

Karena jumlahnya banyak, kami tidak dapat memodelkan semua mode kendaraan. Setiap OEM memiliki kebutuhan yang berbeda dan menstandardisasi mode kendaraan tidak dapat menangani semua kasus penggunaan OEM. Oleh karena itu, kami mendukung mode khusus OEM, yang dikenal sebagai mode kustom. Mode ini tidak memperluas mode daya dan kendaraan yang ada. Sebagai gantinya, mereka menyediakan cara untuk menentukan mode baru.

Fungsi:

  • Cakupan global: Mode kustom bersifat global, diterapkan secara seragam di semua VM yang dikelola oleh Orchestrator.

  • Komposisi: Setiap perubahan mode kustom terdiri dari dua elemen:

    • Name: ID unik yang dipilih oleh OEM untuk merepresentasikan mode kustom.

    • Nilai: Status saat ini untuk mode kustom, yang dapat berupa UNDEFINED jika tidak ada nilai yang ditetapkan.

  • Peran Orchestrator: Orchestrator bertindak sebagai penerima pasif nilai mode kustom.

  • Peran paket layanan: Setiap paket layanan dapat memiliki beberapa mode kustom dan dapat memublikasikan nilai baru ke mode mana pun. Beberapa paket layanan dapat memiliki mode kustom yang sama, yang berarti mode kustom dapat menerima nilai baru dari sumber yang berbeda.

  • Tanggung jawab validasi: OEM bertanggung jawab untuk memastikan transisi status yang valid. Orchestrator menerima nilai baru apa pun.

Estimasi karakteristik:

  • Perkiraan jumlah: Mode daya dan kendaraan mengelola siklus proses sebagian besar paket layanan, dengan mode kustom memainkan peran tambahan. Kami memperkirakan bahwa urutan besarnya mode kustom adalah puluhan, bukan ratusan.

  • Estimasi waktu: Mode tidak dikirim secara berkala. Sebaliknya, mode didorong oleh peristiwa, dipicu oleh tindakan tertentu seperti membuka pintu, memulai urutan parkir, memulai siklus pengisian daya, dan peristiwa serupa lainnya yang ditentukan oleh OEM.

Desain mode kustom memberikan fleksibilitas untuk menentukan dan mengelola mode tertentu sekaligus memungkinkan Pengelola tetap tidak terpengaruh oleh logika mesin status yang mendasarinya.

Mode yang didukung

Untuk memastikan bahwa paket layanan hanya dipublikasikan ke mode kustom yang dimilikinya, setiap paket layanan harus secara eksplisit menyatakan daftar mode kustom yang dimiliki dalam konfigurasi Orchestrator-nya, yang tersedia di VM lokal dengan pendaftaran paket layanan. Upaya untuk memublikasikan ke mode kustom yang tidak dideklarasikan akan dibatalkan.

Untuk mendeklarasikan mode kustom yang diizinkan untuk dipublikasikan (sehingga dimiliki) oleh paket layanan, skema proto service_bundle_config diperluas dengan hal berikut:

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

Mengonfigurasi paket berdasarkan mode

Konfigurasi proto Orchestrator yang ada (komponen Condition) mendukung manipulasi paket layanan berdasarkan mode kustom:

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

Contoh proto

Contoh berikut menunjukkan cara mengonfigurasi instance paket layanan agar dimulai berdasarkan status TURN dan 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"
    }
}

}

Menetapkan mode kustom baru

Proses menyetel nilai mode kustom baru dimulai dengan paket layanan, yang mengomunikasikan nilai yang diinginkan ke Orchestrator lokal yang berjalan di VM yang sama. Kemudian, Orchestrator memverifikasi bahwa paket layanan memiliki izin yang diperlukan untuk memublikasikan ke mode kustom yang ditentukan, dengan merujuk pada konfigurasi yang ditentukan dalam .textproto, untuk menentukan apakah paket layanan harus menyebarkan nilai ke VM lain. Setelah disebarkan, setiap Orchestrator meninjau konfigurasinya untuk menemukan daftar paket layanan yang statusnya harus diubah.

RPC

Setiap Orchestrator yang berjalan di setiap VM membuat server RPC untuk memproses nilai mode kustom baru. Setiap paket layanan yang ingin memperbarui mode kustom harus membuat klien RPC ke server. ACL diterapkan untuk mencegah paket yang tidak sah terhubung ke server.

Definisi proto untuk menyetel nilai baru melalui RPC terlihat seperti contoh berikut:

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) {};
}

Pembatalan transisi daya

Orchestrator memungkinkan pembatalan transisi daya yang sedang berlangsung melalui mode daya SHUTDOWN_CANCELLED (dikirim oleh VPM ke Orchestrator).

Pertimbangkan konfigurasi Orchestrator berikut sebagai contoh:

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

Saat mode SHUTDOWN_CANCELLED diterima, dua skenario utama menentukan perilaku Orchestrator. Dalam kedua kasus tersebut, mode daya SHUTDOWN_CANCELLED ditambahkan di akhir antrean. Kemudian, SHUTDOWN_CANCELLED dieksekusi setelah elemen dalam antrean telah digunakan.

Skenario 1: Mode dalam proses saat ini adalah mode daya

Jika Orchestrator sedang menjalankan update mode daya, maka pembatalan mode yang sedang berlangsung akan diminta. Meskipun Lifecycle Manager tidak secara inheren mendukung pembatalan transisi yang sedang berlangsung, Orchestrator memverifikasi bahwa tidak ada permintaan paket layanan baru yang dimulai.

Contoh: Jika instance-1 dari konfigurasi pada contoh sebelumnya sedang dalam proses memulai saat mode SHUTDOWN_CANCELLED diterima, instance-1 menyelesaikan proses startup-nya. Namun, instance-2 dan instance-3 tidak melanjutkan transisinya ke status dimulai.

Skenario 2: Mode daya ada dalam antrean pemrosesan

Jika Orchestrator sedang memproses update mode non-daya, dan ada permintaan daya dalam antrean mode yang akan dieksekusi, transisi daya akan dihapus dari antrean. Hal ini mencegah eksekusinya.

Contoh: Dengan menggunakan konfigurasi pada contoh sebelumnya, jika Orchestrator sedang mengerjakan update yang tidak terkait daya (seperti update kendaraan) dan SUSPEND_TO_RAM_ENTER ada dalam antrean, menerima SHUTDOWN_CANCELLED tidak akan memulai instance (instance-1, instance-2, instance-3).

Contoh penerapan

Katalog untuk klien yang ingin menggunakan kode yang dihasilkan middleware untuk membuat klien ke server RPC dapat terlihat seperti contoh ini:

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

Saat membuat kode, Anda harus menambahkan dependensi ke katalog Orchestrator:

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

Kode klien untuk mengirim nilai baru terlihat seperti:

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

Alat proses debug

Agen Orchestrator memiliki dukungan untuk alat dumpsys. Anda dapat memanggilnya dengan menjalankan perintah berikut pada instance SDV yang sedang berjalan:

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

Gunakan alat ini untuk men-debug dan mendapatkan insight tentang status internal agen Orchestrator. Tindakan ini akan menampilkan:

  • Status Mode Saat Ini: Lihat mode kendaraan, daya, dan kustom yang aktif.
  • Penayang Mode Kustom: Mengidentifikasi layanan mana yang dapat memublikasikan mode kustom (dan ke mode mana).
  • Status yang diperlukan per layanan: Pelajari status setiap paket layanan berdasarkan kondisi yang telah ditentukan sebelumnya dan mode saat ini. Hal ini membantu mendiagnosis alasan layanan mungkin tidak dalam status yang diharapkan.
  • Status Penerapan Mode: Dapatkan gambaran yang jelas tentang mode penerapan yang sedang berlangsung, atau mode penerapan terakhir jika tidak ada yang sedang berlangsung.
  • Antrean Penerapan Mode: Lihat mode yang menunggu untuk diterapkan.

Contoh:

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: []
----------------

Untuk mempelajari lebih lanjut paket layanan individual yang dikelola oleh Orchestrator, gunakan dumpsys yang ada dari Lifecycle Manager sebagai berikut:

dumpsys google.sdv.lifecycle.ILifecycleManager/default

Dengan melakukannya, Anda akan mendapatkan informasi mendetail tentang status siklus proses setiap layanan. Dengan menggabungkan output dumpsys Orchestrator dengan output dari Lifecycle Manager, Anda akan mendapatkan gambaran lengkap tentang siklus proses paket layanan di VM.