Vendor APEX

Anda dapat menggunakan format file APEX untuk mengemas dan menginstal modul Android OS tingkat yang lebih rendah. Hal ini memungkinkan proses pengembangan dan pembuatan instalasi komponen seperti layanan asli dan pustaka, HAL implementasi, {i>firmware<i}, file konfigurasi, dll.

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

Kasus penggunaan

Modularisasi image vendor

APEX memfasilitasi pemaketan dan modularisasi fitur alami pada image vendor.

Saat image vendor dibangun sebagai kombinasi dari vendor yang dibangun secara independen APEX, produsen perangkat dapat dengan mudah memilih dan menentukan yang diinginkan oleh vendor di perangkat mereka. Produsen bahkan dapat membuat APEX vendor baru jika tidak ada APEX yang disediakan yang sesuai dengan kebutuhan mereka, atau mereka memiliki perangkat keras khusus baru.

Misalnya, OEM dapat memilih untuk menyusun perangkat mereka dengan wifi AOSP APEX, implementasi bluetooth SoC APEX, dan OEM kustom APEX implementasi telepon.

Tanpa APEX vendor, implementasi dengan begitu banyak dependensi antara komponen vendor membutuhkan koordinasi dan pelacakan yang cermat. Dengan menggabungkan semua (termasuk file konfigurasi dan pustaka tambahan) di APEX dengan antarmuka yang jelas pada setiap titik komunikasi lintas fitur, maka komponen yang berbeda menjadi dapat dipertukarkan.

Iterasi developer

APEX vendor membantu developer melakukan iterasi lebih cepat saat mengembangkan modul vendor dengan memaketkan seluruh implementasi fitur, seperti HAL wifi, di dalam vendor APEX. Developer kemudian dapat membangun dan secara individual mendorong APEX vendor untuk menguji perubahan, alih-alih membangun ulang gambar seluruh vendor.

Hal ini menyederhanakan dan mempercepat siklus iterasi developer untuk developer yang terutama bekerja di satu area fitur dan ingin melakukan iterasi pada fitur itu area tersebut.

Pemaketan alami area fitur ke dalam APEX juga menyederhanakan proses membangun, mendorong, dan menguji perubahan di area fitur itu. Misalnya, menginstal ulang APEX secara otomatis memperbarui koleksi atau file konfigurasi apa pun yang tercakup dalam APEX.

Memaketkan area fitur ke dalam APEX juga menyederhanakan proses debug atau pengembalian saat perilaku perangkat yang buruk diamati. Misalnya, jika telepon berfungsi dengan buruk pada versi baru, pengembang bisa mencoba menginstal versi telepon lama implementasi APEX di perangkat (tanpa perlu mem-flash build penuh) 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 utama Format File APEX untuk APEX umum informasi tambahan, 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 mencakup dependensi transitif di dalam {i>payload<i} APEX kecuali jika dependensi memiliki antarmuka yang stabil.

Antarmuka native yang stabil untuk dependensi APEX vendor menyertakan cc_library dengan stubs, ndk_library, atau llndk_library. Ketergantungan ini dikecualikan dari paket, dan dependensi dicatat dalam manifes APEX. Manifesnya adalah diproses oleh linkerconfig sehingga dependensi native eksternal yang tersedia saat runtime.

Tidak seperti APEX di partisi /system, APEX vendor biasanya terikat dengan versi VNDK spesifik. Library VNDK menjamin stabilitas ABI dalam sehingga kita bisa memperlakukan library VNDK sebagai stabil dan mengurangi ukuran vendor APEX dengan mengecualikannya dari APEX menggunakan use_vndk_as_stable saat ini.

Dalam cuplikan di bawah, APEX akan berisi biner (my_service) dan dependensinya yang tidak stabil (file *.so). Versi ini tidak akan berisi library VNDK, meskipun my_service di-build dengan library VNDK seperti libbase. Sebagai gantinya, pada runtime my_service akan menggunakan libbase dari library VNDK yang disediakan oleh sistem file.

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

Dalam cuplikan di bawah, APEX akan berisi library bersama my_standalone_libdan semua dependensinya yang tidak stabil (seperti yang dijelaskan di atas).

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

Implementasi HAL

Untuk mendefinisikan implementasi HAL, sediakan biner dan pustaka yang sesuai di dalam APEX vendor yang mirip dengan contoh berikut:

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

Fragmen VINTF

Fragmen VINTF dapat disajikan dari APEX vendor ketika fragmen berada di etc/vintf dari 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",
}

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 dalam APEX hanya dapat memiliki service definisi. Skrip init di APEX Vendor juga dapat memiliki perintah on <property>.

Hati-hati saat menggunakan perintah on. Karena skrip {i>init<i} dalam APEX merupakan diuraikan dan dieksekusi setelah APEX diaktifkan, beberapa peristiwa atau properti tidak dapat digunakan. Gunakan apex.all.ready=true untuk mengaktifkan tindakan sedini mungkin.

Firmware

Contoh:

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

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 <apex name>/etc/firmware APEX. ueventd memindai /apex/*/etc/firmware direktori untuk menemukan modul {i>firmware<i}.

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

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

Modul kernel

Sematkan modul kernel dalam 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 setiap entri payload modul kernel mereka dapat terus berjalan dengan baik. Contoh:

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

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

my_init.rc:

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

Overlay resource runtime

Contoh:

Menyematkan 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 vendor partisi sebagai bawaan di dalam APEX vendor, dan banyak lagi yang ditambahkan.

Contoh:

Fitur pengembangan tambahan

Pemilihan APEX saat booting

Contoh:

Pengembang juga dapat menginstal beberapa versi APEX vendor yang berbagi nama dan kunci APEX yang sama, lalu pilih versi mana yang diaktifkan dalam setiap booting menggunakan sysprops persisten. Untuk kasus penggunaan pengembang tertentu, hal ini mungkin lebih mudah daripada menginstal salinan APEX baru menggunakan adb install.

Contoh kasus penggunaan:

  • Instal 3 versi APEX vendor HAL wifi: Tim QA dapat menjalankan secara manual otomatis atau pengujian otomatis menggunakan satu versi, lalu {i>reboot<i} ke versi lain dan menjalankan kembali pengujian, lalu membandingkan hasil akhirnya.
  • Instal 2 versi APEX vendor HAL kamera APEX, saat ini dan eksperimental: Pengguna versi dogfood dapat menggunakan versi eksperimental tanpa mengunduh dan menginstal file tambahan, sehingga mereka dapat dengan mudah menukar kembali.

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

Format yang diharapkan untuk kunci properti adalah:

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

Nilai properti harus berupa nama file APEX yang harus diaktifkan.

// 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 {i>bootconfig<i} 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 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 melakukan flash (seperti melalui perintah fastboot oem), Anda dapat mengubah properti bootconfig untuk APEX juga mengubah versi yang diaktifkan saat {i>booting<i}.

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

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