APEX Vendor

Anda dapat menggunakan format file APEX untuk mengemas dan menginstal modul Android OS tingkat bawah. Format ini memungkinkan pembuatan dan penginstalan komponen secara independen seperti layanan dan library native, implementasi 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 bundling dan modularisasi alami implementasi fitur pada gambar vendor.

Saat gambar vendor dibuat sebagai kombinasi APEX vendor yang dibuat secara independen, produsen perangkat dapat dengan mudah memilih 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 perangkat mereka dengan APEX implementasi Wi-Fi AOSP, APEX implementasi Bluetooth SoC, dan APEX implementasi telepon OEM kustom.

Tanpa APEX vendor, implementasi dengan begitu banyak dependensi antar-komponen vendor memerlukan koordinasi dan pelacakan yang cermat. Dengan menggabungkan semua komponen (termasuk file konfigurasi dan library tambahan) dalam APEX dengan antarmuka yang ditentukan dengan jelas pada 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 implementasi fitur, seperti HAL Wi-Fi, di dalam APEX vendor. Developer kemudian dapat membuat dan mendorong APEX vendor secara individual untuk menguji perubahan, bukan membangun kembali seluruh gambar 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.

Bundling alami area fitur ke dalam APEX juga menyederhanakan proses pembuatan, mendorong, dan menguji perubahan untuk area fitur tersebut. Misalnya, menginstal ulang APEX akan otomatis mengupdate library atau file konfigurasi yang dibundel yang disertakan APEX.

Menggabungkan area fitur ke dalam APEX juga menyederhanakan proses debug atau mengembalikan saat perilaku perangkat yang buruk diamati. Misalnya, jika telepon berfungsi buruk dalam build baru, developer dapat mencoba menginstal APEX implementasi telepon 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 informasi APEX umum, termasuk persyaratan perangkat, detail format file, dan langkah-langkah penginstalan.

Di Android.bp, menetapkan 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 memiliki antarmuka yang stabil.

Antarmuka native yang stabil untuk dependensi APEX vendor mencakup cc_library dengan stubs dan library 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 program biner (my_service) dan dependensi non-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 non-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 implementasi 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 skrip init dan fragmen VINTF 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 passthrough.

Skrip init

APEX dapat menyertakan skrip init dengan dua cara: (A) file teks yang telah dibuat sebelumnya dalam payload APEX, atau (B) skrip init reguler di /vendor/etc. Anda dapat menetapkan 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 service definisi dan on <property or event> perintah.

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 perintah 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 sesegera 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 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 yang telah dibuat sebelumnya, 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 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 lainnya yang biasanya ditemukan di partisi vendor sebagai prebuilt di dalam APEX vendor, dan lebih banyak lagi yang ditambahkan.

Contoh:

APEX Vendor Bootstrap

Beberapa layanan HAL seperti keymint harus tersedia sebelum APEX diaktifkan. HAL tersebut biasanya menetapkan early_hal dalam definisi layanan di skrip init. Contoh lainnya adalah class animation yang biasanya dimulai lebih awal daripada peristiwa post-fs-data. Saat layanan HAL awal tersebut dikemas dalam APEX vendor, buat APEX "vendorBootstrap": true di Manifes APEX-nya sehingga dapat diaktifkan lebih awal. Perhatikan bahwa APEX bootstrap hanya dapat diaktifkan dari lokasi prebuilt 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 ditetapkan, file konfigurasi input (*.idc, *.kl, dan *.kcm) akan dicari dari direktori /etc/usr APEX.
  • ro.vulkan.apex=<apex name> - jika ditetapkan, driver Vulkan akan dimuat dari APEX. Karena driver Vulkan digunakan oleh HAL awal, jadikan APEX Bootstrap APEX dan konfigurasi namespace linker tersebut terlihat.

Tetapkan properti sistem dalam skrip init menggunakan setprop perintah.

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>. APEX dengan <apex name> akan diabaikan (tidak diaktifkan) jika properti sistem ini ditetapkan ke none. Anda dapat menggunakan fitur ini untuk menginstal beberapa salinan APEX dengan nama yang sama. Jika ada beberapa versi APEX yang sama, versi tersebut 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 booting ulang ke versi lain dan menjalankan kembali pengujian, lalu membandingkan hasil akhir.
  • Menginstal 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 booting, apexd akan 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 di 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-booting, ubah versi yang diaktifkan dengan menetapkan 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 pembaruan bootconfig setelah flashing (seperti melalui fastboot oem perintah), mengubah properti bootconfig untuk APEX yang diinstal beberapa kali juga akan mengubah versi yang diaktifkan saat booting.

Untuk perangkat referensi virtual berdasarkan Cuttlefish, Anda dapat menggunakan perintah --extra_bootconfig_args untuk menetapkan 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";