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 diupdate secara independen melalui Registry Paket Layanan, seperti yang diilustrasikan di sini.
Gambar 1. Diagram konfigurasi orchestrator.
Konfigurasi yang tidak bergantung pada kendaraan tidak berubah bergantung pada OEM atau kendaraan. Konfigurasi tetap sama di semua kendaraan dari 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 akan 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:
Sistem akan memeriksa properti
persist.sdv.orchestrator_config_path. Jika memiliki nilai, jalur tersebut akan digunakan. Nilai ini dipertahankan saat mulai ulang atau ditetapkan pada waktu proses.Jika
persist.sdv.orchestrator_config_pathkosong, sistem akan memeriksa propertiro.boot.sdv.orchestrator_config_path. Jika propertiro.boot.sdvmemiliki nilai, jalur tersebut akan disalin ke properti persist dan digunakan untuk booting saat ini dan semua booting mendatang (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 di seluruh reboot perangkat. Anda dapat
mengubah nilai pada waktu proses, yang berguna untuk pengujian atau skenario tertentu
(misalnya, pengujian menyeluruh).
Anda dapat menetapkan nilai pada waktu proses menggunakan perintah setprop, dan pada waktu build
menggunakan makefile (dengan ekstensi .mk) atau file skrip resource, dengan
ekstensi .rc.
Menetapkan properti pada waktu proses
Menetapkan properti pada waktu proses berguna untuk pengujian atau membuat perubahan sementara, karena nilainya disimpan di seluruh reboot:
adb root
adb shell setprop persist.sdv.orchestrator_config_path {$path_to_file}.textproto
Menetapkan properti pada waktu build
Untuk menetapkan properti ini sebagai bagian dari konfigurasi build perangkat, tambahkan baris ke makefile produk atau board Anda. Hal ini ideal untuk menetapkan nilai default bagi image 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
melakukan booting, nilai ro.boot.sdv.orchestrator_config_path akan disalin ke dalamnya. Setelah
persist.sdv.orchestrator_config_path ditetapkan, properti ini tidak akan menimpanya
pada booting berikutnya.
Anda dapat menetapkan 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:
InstanceToGroupMappingmemungkinkan Anda menyertakan instance paket layanan dalam grup untuk membuat dependensi antara instance paket layanan yang sama.InstancesStatesmenentukan berbagai status untuk instance paket layanan.InstancesStateConfigurationmenentukan status (dariInstancesStates) yang harus ditetapkan untuk instance paket layanan jika kondisi bernilaitrue.ServiceBundleConfigberisi informasi tentang paket layanan tertentu dan instance-nya. File ini berisiInstanceToGroupMappingdanInstancesStateConfigurationmasing-masing untuk paket.CustomModesmenentukan daftar mode kustom yang diizinkan untuk dipublikasikan oleh paket.CustomModesdigunakan untuk mencegah paket yang tidak sah mengubah nilai mode kustom. Kolom ini bersifat opsional, karena paket layanan mungkin tidak dipublikasikan ke mode kustom apa 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 merupakan nama VM tempat file konfigurasi di-deploy dan sudah diketahui oleh agen orkestrasi.
Mengonfigurasi instance
Mendeklarasikan instance paket layanan tidak akan berpengaruh. Agar dapat dijalankan oleh Orchestrator, instance harus dikonfigurasi. Misalnya, Orchestrator harus diberi tahu tentang kondisi (atau status VM atau kendaraan) yang harus dijalankan oleh instance. Untuk mengonfigurasi instance, status konfigurasi harus ditentukan melalui:
conditionadalah ekspresi pada status VM atau kendaraan yang harus dievaluasi.instances_statesadalah kumpulan status per instance yang harus diterapkan jika kondisi bernilaitrue.
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. Pada 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 adalah 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. Layanan ini digunakan untuk memodelkan dependensi antara paket layanan di tingkat VM, sehingga memberikan fleksibilitas untuk mengubah status beberapa paket layanan secara bersamaan. Semua instance grup dibawa ke status yang ditentukan.
Orchestrator tidak menjamin urutan eksekusi perubahan status. Orchestrator mempromosikan setiap instance agar berada dalam status tertentu.
Grup dideklarasikan secara implisit menggunakan nama group di salah satu
bagian konfigurasi. Misalnya, pemetaan instance ke grup, pemetaan grup ke grup, dan status konfigurasi grup.
Pemetaan grup ke grup
Grup dapat berisi grup lain. Dengan mendeklarasikan 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 dijalankan oleh Orchestrator, grup harus dikonfigurasi. Misalnya, Orchestrator harus diberi tahu dalam kondisi atau status VM atau kendaraan apa grup harus dijalankan.
Anda dapat mengonfigurasi grup dengan cara yang mirip dengan instance layanan, yaitu dengan
menggunakan status konfigurasi. Satu-satunya perbedaan adalah penggunaan groups_states,
bukan 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, akan menerapkan status instance yang ditentukan. Kondisi memiliki karakteristik berikut:
Ekspresi boolean yang kompleks secara arbitrer (dibentuk dengan ekspresi
andataunot) berdasarkan sinyal yang didukung seperti daya, kendaraan, dan mode kustom.(Opsional) Status konfigurasi tanpa kondisi selalu aktif, yang berarti status tersebut dievaluasi ke
true
Status instance dan status grup
instances_states dan groups_states memiliki karakteristik ini.
Tentukan status yang diperlukan oleh agen orkestrasi untuk diterapkan ke instance atau grup tertentu, mengingat statusnya adalah
activeSaat menerapkan status ke grup, status tersebut akan berlaku untuk setiap instance paket layanan dalam grup. Tidak ada urutan yang diterapkan terkait kapan instance dibawa ke status tersebut.
Status yang didukung meliputi:
startedsetelahService::on_startdipanggil.createdsetelah
Service::newdipanggil, tetapi sebelumService::on_startdipanggil.ATAU
setelah
Service::on_stopdipanggil, tetapi sebelumService::dropdipanggil.
destroyedsetelahService::dropdipanggil.
Ruleset
Status konfigurasi dapat berupa aktif atau tidak aktif, bergantung pada kondisinya. Beberapa status dapat aktif kapan saja. Saat agen orkestrasi menerima update sinyal, semua status konfigurasi akan dievaluasi 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 akan berlaku:
destroyedmemiliki prioritas mutlak.startedlebih diprioritaskan daripadacreated.
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 dari error dan mulai ulang
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 cocok untuk menjalankan strategi mulai ulang dan coba lagi. Lifecycle Manager (LM) melaporkan error paket layanan ke Orchestrator melalui notifikasi kematian binder. Untuk menghindari panggilan binder yang tidak perlu ke LM, Orchestrator menyimpan status terakhir setiap paket ke dalam cache (baik berhasil maupun 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 percobaan ulang per instance dalam konfigurasi Orchestrator menggunakan retry_mapping. Jika max_retries tidak ditetapkan dalam
konfigurasi, nilai default akan diambil dari
properti sistem ro.boot.sdv.orchestrator.recovery.max_retries. Jika properti ini tidak ditetapkan, nilainya akan kembali ke 0.
max_retries: Menentukan frekuensi Orchestrator mencoba kembali transisi setelah kegagalan sementara atau notifikasi error paket. Penghitung percobaan ulang akan direset ke nilaimax_retriessetelah operasi berhasil atau saat mode baru diproses. Jika beberapa pemetaan menarget instance yang sama, pemetaan denganmax_retriestertinggi 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 percobaan ulang Orchestrator mengelola beberapa skenario kegagalan dengan baik:
- Error operasi normal: Jika paket layanan mengalami error saat berjalan, Orchestrator akan menerapkan strategi mulai ulang dan mencoba mengembalikan paket ke status terakhir yang diminta berdasarkan percobaan ulang yang tersisa.
- Error selama transisi mode: Jika paket mengalami error saat menerapkan mode baru, permintaan mulai ulang akan dimasukkan ke antrean dan diproses nanti. Setelah permintaan diproses, Orchestrator akan memeriksa status terakhir instance dan hanya menerapkan mulai ulang jika instance tidak berada dalam status terakhir yang diminta (dari transisi mode terakhir).
- Mode baru selama pemulihan: Jika Orchestrator menerima permintaan untuk beralih ke mode baru saat paket dimulai ulang (atau berada dalam antrean instance yang akan dimulai ulang), Orchestrator akan membatalkan pemulihan yang sedang berlangsung. Transisi mode baru akan mengambil alih, dan penghitung percobaan ulang direset untuk memungkinkan serangkaian upaya 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 status rusak dan mencoba menghentikan instance layanan sebelum mencoba kembali 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 mengalami error, semua proses paket layanan akan hilang. Karena status sebenarnya tidak diketahui, Orchestrator akan membatalkan validasi setiap instance dan menerapkan strategi mulai ulang dengan percobaan ulang yang tersisa untuk membawa setiap instance ke status terakhir yang diminta.
Untuk mencegah loop pemulihan tanpa batas untuk paket yang berulang kali 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
percobaan ulang karena kegagalan berturut-turut (misalnya, kegagalan transisi yang diikuti
dengan error), paket tersebut tidak akan dimulai ulang hingga penghitung percobaan ulang direset.
Pelaporan Status ke Health Monitor
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:
- Status siklus proses: Status instance yang diinginkan 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, sedang mencoba ulang setelah gagal, atau gagal dipulihkan setelah menghabiskan semua percobaan ulang.
Informasi ini dilaporkan untuk semua instance, termasuk yang belum terdaftar untuk dipantau heartbeat-nya. HM menggunakan informasi ini untuk mengimplementasikan API-nya guna melaporkan status VM. Anda dapat mempelajari lebih lanjut di Pemantauan kesehatan.
Contoh
Bagian ini menyajikan contoh untuk mengonfigurasi status dengan kondisi.
Contoh layanan dasar
- Tidak memiliki kondisi sehingga 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_LOWdanRANGE_EXT_ONaktif, aplikasi HVAC berjalan tanpa instance layananRefrigerantLoop: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 kehidupan di kapal
Kondisi: Aktif jika
power_state == ON && vehicle_state == LIFE_ON_BOARD.Status ini dapat dilihat sebagai Seseorang berada di dalam mobil dan mobil dihidupkan.
Menyatakan sensor suhu sebagai berjalan.
Saat seseorang berada di dalam mobil, item seperti suhu akan dipantau untuk alasan keselamatan.
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 satu 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. Parameter ini menentukan tingkat paralelisme maksimum untuk transaksi paket layanan dan secara langsung memengaruhi dua layanan inti:
Orchestration Engine: Layanan ini membaca properti untuk menentukan jumlah panggilan serentak (misalnya,
startService,stopService) yang dapat dilakukan Orchestrator ke Lifecycle Manager. Hal ini sangat penting untuk performa selama booting dan transisi mode saat banyak paket dapat mengubah status secara bersamaan.Lifecycle Manager: Layanan ini menggunakan nilai properti untuk menghitung ukuran kumpulan thread Binder, yang bertanggung jawab untuk menangani semua permintaan masuk. Hal ini memastikan bahwa LM memiliki thread yang cukup untuk menangani permintaan serentak dari Orchestrator.
Jika properti ini tidak ditetapkan, kedua layanan akan ditetapkan secara default ke nilai 12.
Metode konfigurasi
Anda dapat menetapkan properti di file BoardConfig.mk perangkat dengan menambahkannya ke
variabel BOARD_BOOTCONFIG. Hal ini memastikan nilai diterapkan setiap kali perangkat melakukan booting.
BOARD_BOOTCONFIG += \
androidboot.sdv.max_bundles_management_threads=8
Untuk mengubah nilai perangkat Anda, ubah baris ini di file
BoardConfig.mk yang sesuai dan build ulang.
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 Orchestration telah menyelesaikan inisialisasi 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, penemuan layanan, 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 pertentangan resource, sehingga memperlambat proses booting secara keseluruhan. Untuk mengurangi hal ini, urutan startup berurutan diterapkan menggunakan properti sistem:
- Registry paket layanan: Dimulai terlebih dahulu untuk memuat semua metadata paket layanan.
- Lifecycle Manager dan Orchestrator: Agen inti ini dimulai segera setelah registry siap. Permulaan awal ini sangat penting karena memungkinkan Orchestrator mulai mengevaluasi konfigurasinya dan bersiap untuk segera memulai paket layanan.
- Agen SDV lainnya: Hanya dimulai setelah Orchestrator siap.
Urutan terkontrol ini memastikan Orchestrator memiliki prioritas untuk menggunakan resource sistem guna memulai paket layanan secepat 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.readysdv.orchestrator.bootup.vehicle_mode.ready
Dengan menggunakan file konfigurasi sebagai referensi, agen orkestrasi secara dinamis menghitung kumpulan paket layanan yang harus dalam status berjalan berdasarkan nilai saat ini dari mode yang diterima. Orchestrator kemudian berkomunikasi dengan pengelola siklus proses, mengeluarkan berbagai perintah untuk menyelaraskan status sebenarnya dari paket layanan dengan status target yang dihitung.
Status kendaraan dan daya
Agen mode Kendaraan dan pengelolaan daya (VPM) memungkinkan komponen SDV diberi tahu tentang status kendaraan saat ini, seperti mode operasional (misalnya, Parkir atau Berkendara) dan status daya (misalnya, Aktif dan Ditangguhkan). Orchestrator mengevaluasi nilai ini untuk menentukan paket layanan yang harus dijalankan berdasarkan konfigurasi Orchestrator. Untuk mempelajari lebih lanjut, lihat Pengelolaan kendaraan dan daya.
Mode kustom
Mengingat banyaknya jumlahnya, kita tidak dapat memodelkan semua mode kendaraan. Setiap OEM memiliki kebutuhan yang berbeda dan menstandarkan mode kendaraan tidak dapat mengatasi semua kasus penggunaan OEM. Oleh karena itu, kami mendukung mode khusus OEM, yang dikenal sebagai mode kustom. Mode ini tidak memperluas mode kendaraan dan daya yang ada. Sebagai gantinya, model ini menyediakan cara untuk menentukan mode baru.
Fungsi:
Cakupan global: Mode kustom bersifat global, berlaku secara seragam di semua VM yang dikelola oleh Orchestrator.
Komposisi: Setiap perubahan mode kustom terdiri dari dua elemen:
Nama: ID unik yang dipilih oleh OEM untuk mewakili mode kustom.
Value: Status saat ini untuk mode kustom, yang dapat berupa
UNDEFINEDjika 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 berbagai sumber.
Tanggung jawab validasi: OEM bertanggung jawab untuk memastikan transisi status yang valid. Orchestrator menerima nilai baru apa pun.
Karakteristik estimasi:
Perkiraan jumlah: Mode daya dan kendaraan mengelola siklus proses sebagian besar paket layanan, dengan mode kustom yang memainkan peran tambahan. Kami memperkirakan bahwa urutan besarnya mode kustom akan berjumlah puluhan, bukan ratusan.
Estimasi waktu: Mode tidak dikirim secara berkala. Sebaliknya, mode didasarkan pada peristiwa, yang 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 Orchestrator tetap agnostik terhadap logika mesin status yang mendasarinya.
Mode yang didukung
Untuk memastikan bahwa paket layanan hanya dipublikasikan ke mode kustom yang dimilikinya, setiap paket harus secara eksplisit mendeklarasikan daftar mode kustom yang dimiliki dalam konfigurasi Orchestrator-nya, yang tersedia di VM lokal dengan registry paket layanan. Upaya untuk memublikasikan ke mode kustom yang tidak dideklarasikan akan dihapus.
Untuk mendeklarasikan mode kustom yang diizinkan untuk dipublikasikan (dan 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 yang akan
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 penetapan nilai mode kustom baru dimulai dengan paket layanan,
yang mengomunikasikan nilai yang diinginkan ke Orchestrator lokal yang berjalan di
VM yang sama. Kemudian, Orchestrator akan 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 menetapkan nilai baru melalui RPC terlihat seperti contoh ini:
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 akan menentukan perilaku Orchestrator. Dalam kedua kasus tersebut, mode daya SHUTDOWN_CANCELLED
ditambahkan ke akhir antrean. Kemudian, SHUTDOWN_CANCELLED dijalankan setelah
elemen dalam antrean digunakan.
Skenario 1: Mode yang sedang berlangsung adalah mode daya
Jika Orchestrator menjalankan update mode daya, 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 dalam contoh sebelumnya sedang
dalam proses memulai saat mode SHUTDOWN_CANCELLED diterima,
instance-1 akan menyelesaikan startup-nya. Namun, instance-2 dan instance-3 tidak
melanjutkan transisinya ke status dimulai.
Skenario 2: Mode daya ada dalam antrean pemrosesan
Jika Orchestrator memproses update mode non-daya, dan ada permintaan daya dalam antrean mode yang akan dijalankan, transisi daya akan dihapus dari antrean. Tindakan ini mencegah eksekusinya.
Contoh: Dengan menggunakan konfigurasi dalam contoh sebelumnya, jika Orchestrator
sedang mengerjakan update yang tidak terkait dengan daya (seperti update kendaraan) dan
SUSPEND_TO_RAM_ENTER berada dalam antrean, menerima SHUTDOWN_CANCELLED akan mengakibatkan
tidak ada instance (instance-1, instance-2, instance-3) yang
dimulai.
Contoh penerapan
Katalog untuk klien yang ingin menggunakan kode yang dihasilkan middleware untuk membuat klien ke server RPC dapat terlihat seperti contoh berikut:
# 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 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 diterapkan yang sedang berlangsung, atau mode diterapkan 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
Tindakan ini akan memberikan 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.