APEX Vendor

Anda dapat menggunakan format file APEX untuk memaketkan dan menginstal modul OS Android tingkat bawah. Hal ini memungkinkan pembangunan dan penginstalan komponen secara independen seperti layanan dan library native, penerapan HAL, firmware, file konfigurasi, dll.

APEX vendor diinstal oleh sistem build secara otomatis di partisi /vendor dan diaktifkan saat runtime oleh apexd seperti APEX di partisi lainnya.

Kasus penggunaan

Modularisasi gambar vendor

APEX memfasilitasi penggabungan dan modularisasi alami penerapan fitur pada image vendor.

Jika image vendor dibuat sebagai kombinasi APEX vendor yang dibuat secara independen, produsen perangkat dapat dengan mudah memilih dan menentukan implementasi vendor tertentu yang diinginkan di perangkat mereka. Produsen bahkan dapat membuat APEX vendor baru jika tidak ada APEX yang disediakan sesuai dengan kebutuhan mereka, atau mereka memiliki hardware kustom yang baru.

Misalnya, OEM dapat memilih untuk menyusun perangkatnya dengan APEX implementasi Wi-Fi AOSP, APEX implementasi Bluetooth SoC, dan APEX implementasi teleponi OEM kustom.

Tanpa APEX vendor, penerapan dengan begitu banyak dependensi antara komponen vendor memerlukan koordinasi dan pelacakan yang cermat. Dengan membungkus semua komponen (termasuk file konfigurasi dan library tambahan) dalam APEX dengan antarmuka yang ditentukan dengan jelas di setiap titik komunikasi lintas fitur, berbagai komponen menjadi dapat dipertukarkan.

Iterasi developer

APEX vendor membantu developer melakukan iterasi lebih cepat saat mengembangkan modul vendor dengan menggabungkan seluruh penerapan fitur, seperti HAL Wi-Fi, di dalam APEX vendor. Kemudian, developer dapat membuat dan mengirimkan APEX vendor satu per satu untuk menguji perubahan, alih-alih membangun ulang seluruh image vendor.

Hal ini menyederhanakan dan mempercepat siklus iterasi developer bagi developer yang terutama bekerja di satu area fitur dan ingin melakukan iterasi hanya di area fitur tersebut.

Penggabungan alami area fitur ke dalam APEX juga menyederhanakan proses pembuatan, pengiriman, dan pengujian perubahan untuk area fitur tersebut. Misalnya, menginstal ulang APEX secara otomatis akan mengupdate file konfigurasi atau library yang di-bundle yang disertakan APEX.

Menggabungkan area fitur ke dalam APEX juga menyederhanakan proses men-debug atau mengembalikan saat perilaku perangkat yang buruk diamati. Misalnya, jika teleponi berfungsi buruk di build baru, developer dapat mencoba menginstal implementasi teleponi APEX yang lebih lama di perangkat (tanpa perlu mem-flash build lengkap) dan melihat apakah perilaku yang baik dipulihkan.

Contoh alur kerja:

# Build the entire device and flash. OR, obtain an already-flashed device.
source build/envsetup.sh && lunch oem_device-userdebug
m
fastboot flashall -w

# Test the device.
... testing ...

# Check previous behavior using a vendor APEX from one week ago, downloaded from
# your continuous integration build.
... download command ...
adb install <path to downloaded APEX>
adb reboot
... testing ...

# Edit and rebuild just the APEX to change and test behavior.
... edit APEX source contents ...
m <apex module name>
adb install out/<path to built APEX>
adb reboot
... testing ...

Contoh

Dasar-dasar

Lihat halaman Format File APEX utama untuk mengetahui informasi APEX umum, termasuk persyaratan perangkat, detail format file, dan langkah-langkah penginstalan.

Di Android.bp, menyetel properti vendor: true akan membuat modul APEX menjadi APEX vendor.

apex {
  ..
  vendor: true,
  ..
}

Biner dan library bersama

APEX menyertakan dependensi transitif di dalam payload APEX kecuali jika dependensi tersebut memiliki antarmuka yang stabil.

Antarmuka native yang stabil untuk dependensi APEX vendor mencakup cc_library dengan library stubs dan LLNDK. Dependensi ini dikecualikan dari pengemasan, dan dependensi dicatat dalam manifes APEX. Manifes diproses oleh linkerconfig sehingga dependensi native eksternal tersedia saat runtime.

Dalam cuplikan berikut, APEX berisi biner (my_service) dan dependensi tidak stabilnya (file *.so).

apex {
  ..
  vendor: true,
  binaries: ["my_service"],
  ..
}

Dalam cuplikan berikut, APEX berisi library bersama my_standalone_lib dan dependensi non-stabilnya (seperti yang dijelaskan di atas).

apex {
  ..
  vendor: true,
  native_shared_libs: ["my_standalone_lib"],
  ..
}

Membuat APEX lebih kecil

APEX mungkin menjadi lebih besar karena menggabungkan dependensi yang tidak stabil. Sebaiknya gunakan penautan statis. Library umum seperti libc++.so dan libbase.so dapat ditautkan secara statis ke biner HAL. Membuat dependensi untuk menyediakan antarmuka yang stabil dapat menjadi opsi lain. Dependensi tidak akan dibundel dalam APEX.

Implementasi HAL

Untuk menentukan penerapan HAL, berikan biner dan library yang sesuai di dalam APEX vendor yang mirip dengan contoh berikut:

Untuk sepenuhnya merangkum implementasi HAL, APEX juga harus menentukan fragmen VINTF dan skrip init yang relevan.

Fragmen VINTF

Fragmen VINTF dapat ditayangkan dari APEX vendor saat fragmen berada di etc/vintf APEX.

Gunakan properti prebuilts untuk menyematkan fragmen VINTF di APEX.

apex {
  ..
  vendor: true,
  prebuilts: ["fragment.xml"],
  ..
}

prebuilt_etc {
  name: "fragment.xml",
  src: "fragment.xml",
  sub_dir: "vintf",
}

API Kueri

Saat fragmen VINTF ditambahkan ke APEX, gunakan API libbinder_ndk untuk mendapatkan pemetaan antarmuka HAL dan nama APEX.

  • AServiceManager_isUpdatableViaApex("com.android.foo.IFoo/default") : true jika instance HAL ditentukan dalam APEX.
  • AServiceManager_getUpdatableApexName("com.android.foo.IFoo/default", ...) : mendapatkan nama APEX yang menentukan instance HAL.
  • AServiceManager_openDeclaredPassthroughHal("mapper", "instance", ...) : gunakan ini untuk membuka HAL teruskan.

Skrip init

APEX dapat menyertakan skrip init dengan dua cara: (A) file teks bawaan dalam payload APEX, atau (B) skrip init reguler di /vendor/etc. Anda dapat menyetel keduanya untuk APEX yang sama.

Skrip init di APEX:

prebuilt_etc {
  name: "myinit.rc",
  src: "myinit.rc"
}

apex {
  ..
  vendor: true,
  prebuilts: ["myinit.rc"],
  ..
}

Skrip init di APEX vendor dapat memiliki definisi service dan direktif on <property or event>.

Pastikan definisi service mengarah ke biner di APEX yang sama. Misalnya, APEX com.android.foo dapat menentukan layanan bernama foo-service.

on foo-service /apex/com.android.foo/bin/foo
  ...

Berhati-hatilah saat menggunakan direktif on. Karena skrip init di APEX diuraikan dan dieksekusi setelah APEX diaktifkan, beberapa peristiwa atau properti tidak dapat digunakan. Gunakan apex.all.ready=true untuk memicu tindakan sedini mungkin. APEX Bootstrap dapat menggunakan on init, tetapi tidak on early-init.

Firmware

Contoh:

Sematkan firmware di APEX vendor dengan jenis modul prebuilt_firmware, sebagai berikut.

prebuilt_firmware {
  name: "my.bin",
  src: "path_to_prebuilt_firmware",
  vendor: true,
}

apex {
  ..
  vendor: true,
  prebuilts: ["my.bin"],  // installed inside APEX as /etc/firmware/my.bin
  ..
}

Modul prebuilt_firmware diinstal di direktori <apex name>/etc/firmware APEX. ueventd memindai direktori /apex/*/etc/firmware untuk menemukan modul firmware.

file_contexts APEX harus memberi label pada entri payload firmware dengan benar untuk memastikan bahwa file ini dapat diakses oleh ueventd saat runtime; biasanya, label vendor_file sudah cukup. Contoh:

(/.*)? u:object_r:vendor_file:s0

Modul kernel

Sematkan modul kernel di APEX vendor sebagai modul bawaan, sebagai berikut.

prebuilt_etc {
  name: "my.ko",
  src: "my.ko",
  vendor: true,
  sub_dir: "modules"
}

apex {
  ..
  vendor: true,
  prebuilts: ["my.ko"],  // installed inside APEX as /etc/modules/my.ko
  ..
}

file_contexts APEX harus memberi label pada semua entri payload modul kernel dengan benar. Contoh:

/etc/modules(/.*)? u:object_r:vendor_kernel_modules:s0

Modul kernel harus diinstal secara eksplisit. Contoh skrip init berikut di partisi vendor menunjukkan penginstalan melalui insmod:

my_init.rc:

on early-boot
  insmod /apex/myapex/etc/modules/my.ko
  ..

Overlay resource runtime

Contoh:

Sematkan overlay resource runtime di APEX vendor menggunakan properti rros.

runtime_resource_overlay {
    name: "my_rro",
    soc_specific: true,
}


apex {
  ..
  vendor: true,
  rros: ["my_rro"],  // installed inside APEX as /overlay/my_rro.apk
  ..
}

File konfigurasi lainnya

APEX vendor mendukung berbagai file konfigurasi lain yang biasanya ditemukan di partisi vendor sebagai prebuilt di dalam APEX vendor, dan lebih banyak lagi yang ditambahkan.

Contoh:

Bootstrapping APEX Vendor

Beberapa layanan HAL seperti keymint harus tersedia sebelum APEX diaktifkan. HAL tersebut biasanya menetapkan early_hal dalam definisi layanannya di skrip init. Contoh lainnya adalah class animation yang biasanya dimulai lebih awal daripada peristiwa post-fs-data. Jika layanan HAL awal tersebut dikemas dalam APEX vendor, buat APEX "vendorBootstrap": true dalam Manifes APEX-nya sehingga dapat diaktifkan lebih awal. Perhatikan bahwa APEX bootstrap hanya dapat diaktifkan dari lokasi bawaan seperti /vendor/apex, bukan dari /data/apex.

Properti sistem

Berikut adalah properti sistem yang dibaca framework untuk mendukung APEX vendor:

  • input_device.config_file.apex=<apex name> - jika disetel, file konfigurasi input (*.idc, *.kl, dan *.kcm) akan dicari dari direktori /etc/usr APEX.
  • ro.vulkan.apex=<apex name> - jika disetel, driver Vulkan dimuat dari APEX. Karena driver Vulkan digunakan oleh HAL awal, buat APEX Bootstrap APEX dan konfigurasikan namespace linker tersebut agar terlihat.

Tetapkan properti sistem di skrip init menggunakan perintah setprop.

Fitur tambahan

Pemilihan APEX saat booting

Contoh:

APEX vendor dapat diaktifkan secara opsional selama booting. Jika Anda menentukan nama file menggunakan properti sistem ro.vendor.apex.<apex name>, hanya APEX yang cocok dengan nama file yang diaktifkan untuk <apex name> tertentu. APEX dengan <apex name> diabaikan (tidak diaktifkan) jika properti sistem ini disetel ke none. Anda dapat menggunakan fitur ini untuk menginstal beberapa salinan APEX dengan nama yang sama. Jika ada beberapa versi APEX yang sama, semuanya harus menggunakan kunci yang sama.

Contoh kasus penggunaan:

  • Menginstal 3 versi APEX vendor HAL Wi-Fi: Tim QA dapat menjalankan pengujian manual atau otomatis menggunakan satu versi, lalu melakukan reboot ke versi lain dan menjalankan kembali pengujian, lalu membandingkan hasil akhir.
  • Instal 2 versi APEX vendor HAL kamera, current dan experimental: Penguji internal dapat menggunakan versi eksperimental tanpa mendownload dan menginstal file tambahan, sehingga mereka dapat dengan mudah beralih kembali.

Selama proses booting, apexd mencari sysprop yang mengikuti format tertentu untuk mengaktifkan versi APEX yang tepat.

Format yang diharapkan untuk kunci properti adalah:

  • Bootconfig
    • Digunakan untuk menetapkan nilai default, di BoardConfig.mk.
    • androidboot.vendor.apex.<apex name>
  • Sysprop persisten
    • Digunakan untuk mengubah nilai default, ditetapkan pada perangkat yang sudah di-booting.
    • Mengganti nilai bootconfig jika ada.
    • persist.vendor.apex.<apex name>

Nilai properti harus berupa nama file APEX yang akan diaktifkan, atau none untuk menonaktifkan APEX.

// Default version.
apex {
  name: "com.oem.camera.hal.my_apex_default",
  vendor: true,
  ..
}

// Non-default version.
apex {
  name: "com.oem.camera.hal.my_apex_experimental",
  vendor: true,
  ..
}

Versi default juga harus dikonfigurasi menggunakan bootconfig di BoardConfig.mk:

# Example for APEX "com.oem.camera.hal" with the default above:
BOARD_BOOTCONFIG += \
    androidboot.vendor.apex.com.oem.camera.hal=com.oem.camera.hal.my_apex_default

Setelah perangkat di-boot, ubah versi yang diaktifkan dengan menyetel sysprop persisten:

$ adb root;
$ adb shell setprop \
    persist.vendor.apex.com.oem.camera.hal \
    com.oem.camera.hal.my_apex_experimental;
$ adb reboot;

Jika perangkat mendukung update bootconfig setelah flashing (seperti melalui perintah fastboot oem), maka mengubah properti bootconfig untuk APEX yang diinstal ganda juga akan mengubah versi yang diaktifkan saat booting.

Untuk perangkat referensi virtual berdasarkan Cuttlefish, Anda dapat menggunakan perintah --extra_bootconfig_args untuk menyetel properti bootconfig secara langsung saat meluncurkan. Contoh:

launch_cvd --noresume \
  --extra_bootconfig_args "androidboot.vendor.apex.com.oem.camera.hal:=com.oem.camera.hal.my_apex_experimental";