Penanganan hotplug

Kemampuan tampilan (seperti mode tampilan dan jenis HDR yang didukung) dapat berubah secara dinamis di perangkat yang memiliki layar yang terhubung secara eksternal (dengan HDMI atau DisplayPort), seperti dekoder (STB) Android TV dan perangkat over-the-top (OTT). Perubahan ini dapat terjadi karena sinyal hotplug HDMI, seperti saat pengguna beralih dari satu layar ke layar lainnya atau melakukan booting perangkat tanpa layar terhubung. Android 12 dan yang lebih tinggi menyertakan perubahan dalam framework untuk menangani kemampuan hotplugging dan tampilan dinamis.

Halaman ini menjelaskan penanganan hotplug tampilan dan perubahan kemampuan tampilan dalam implementasi HAL Composer. Selain itu, dokumen ini membahas cara mengelola framebuffer terkait dan mencegah kondisi race dalam situasi ini.

Catatan: Istilah mode tampilan yang digunakan dalam Android API dan framework setara dengan istilah konfigurasi tampilan yang digunakan di HAL Composer.

Memperbarui kemampuan tampilan

Bagian ini menjelaskan cara framework Android menangani perubahan pada kemampuan tampilan yang dimulai oleh Composer HAL.

Sebelum Android dapat menangani perubahan kemampuan tampilan dengan benar, OEM harus mengimplementasikan Composer HAL sehingga menggunakan onHotplug(display, connection=CONNECTED) untuk memberi tahu framework tentang setiap perubahan pada kemampuan tampilan. Setelah itu diimplementasikan, Android akan menangani perubahan untuk menampilkan kemampuan sebagai berikut:

1. Saat mendeteksi perubahan pada kemampuan tampilan, framework akan menerima notifikasi onHotplug(display, connection=CONNECTED).
2. Saat menerima notifikasi, framework akan menghapus status tampilannya dan membuat ulang dengan kemampuan baru dari HAL menggunakan metode getActiveConfig, getDisplayConfigs, getDisplayAttribute, getColorModes, getHdrCapabilities, dan getDisplayCapabilities.
3. Setelah membuat ulang status tampilan baru, framework akan mengirim callback onDisplayChanged ke aplikasi yang memproses peristiwa tersebut.

Catatan: Pastikan getDisplayConfigs melaporkan semua kecepatan refresh dan resolusi layar yang didukung secara akurat.

Framework ini mengalokasikan ulang framebuffer pada peristiwa onHotplug(display, connection=CONNECTED) berikutnya. Lihat Pengelolaan framebuffer klien untuk informasi selengkapnya tentang cara mengelola memori framebuffer dengan benar untuk menghindari kegagalan selama alokasi framebuffer baru.

Menangani skenario koneksi umum

Bagian ini membahas cara menangani berbagai skenario koneksi dengan benar dalam implementasi Anda saat layar utama terhubung dan terputus.

Setelah dibangun untuk perangkat seluler, framework Android tidak memiliki dukungan bawaan untuk tampilan utama yang terputus. Sebagai gantinya, HAL harus mengganti tampilan utama dengan tampilan placeholder dalam interaksinya dengan framework jika tampilan utama terputus secara fisik.

Peringatan: Jangan kirim notifikasi onHotplug(display, connection=DISCONNECTED) untuk tampilan utama, karena akan menyebabkan framework mengalami error.

Skenario berikut dapat terjadi pada STB dan dongle TV yang memiliki layar yang terhubung secara eksternal yang dapat diputus. Untuk menerapkan dukungan untuk skenario ini, gunakan informasi dalam tabel di bawah:

Skenario	Penanganan
Tidak ada layar yang terhubung saat booting	Kirim sinyal onHotplug(display, connection=CONNECTED) dari Composer HAL ke framework. Ganti status tampilan fisik di dalam HAL Composer dengan status tampilan placeholder. Catatan: Sebaiknya layar placeholder memiliki satu mode yang didukung dengan resolusi 1080x1920 dan kecepatan refresh 60 Hz, karena mode tampilan ini didukung oleh sebagian besar aplikasi.
Layar utama terhubung secara fisik	Kirim peristiwa onHotplug(display, connection=CONNECTED) lain dari Composer HAL ke framework. Hal ini menyebabkan framework memuat ulang semua kemampuan tampilan.
Layar utama terputus secara fisik	Kirim peristiwa onHotplug(display, connection=CONNECTED) lain dari Composer HAL ke framework. Ganti status tampilan fisik di dalam HAL Composer dengan status tampilan placeholder. Tampilan placeholder harus memiliki satu mode tampilan, sehingga framework mengirimkan callback onDisplayChanged ke aplikasi (karena kumpulan mode yang didukung telah berubah). Mode tampilan tunggal ini harus cocok dengan mode aktif terakhir dari tampilan fisik sebelum koneksi diputus, agar aplikasi tidak menerima peristiwa perubahan konfigurasi.

Pertimbangan koneksi non-HDMI

Android TV hanya mendukung resolusi berikut:

• 720x1280
• 1080x1920
• 2160x3840
• 4320x7680

Jika STB atau dongle TV mencoba menampilkan resolusi yang tidak didukung, seperti 480i melalui koneksi CVBS, pesan error akan ditampilkan kepada pengguna.

Jika dongle STB atau TV memiliki koneksi HDMI dan non-HDMI, koneksi HDMI adalah layar utama dan koneksi non-HDMI tidak aktif. Akibatnya, jika koneksi HDMI terputus saat koneksi non-HDMI masih terhubung, peristiwa akan dikirim ke SurfaceFlinger dan kemampuan tampilan non-HDMI harus tercermin melalui getDisplayAttribute dan API iComposerClient lainnya (seperti getHdrCapabilities).

Menggunakan ID konfigurasi berurutan untuk mencegah kondisi race

Kondisi race dapat muncul jika Composer HAL mengupdate konfigurasi tampilan yang didukung secara serentak dengan framework yang memanggil setActiveConfig atau setActiveConfigWithConstraints. Solusinya adalah mengimplementasikan Composer HAL untuk menggunakan ID berurutan dan mencegah masalah ini.

Bagian ini menjelaskan bagaimana kondisi race mungkin terjadi, diikuti dengan detail tentang cara menerapkan HAL Composer agar menggunakan ID berurutan untuk mencegah kondisi tersebut.

Pertimbangkan urutan peristiwa berikut, jika ID berurutan yang baru TIDAK ditetapkan ke konfigurasi tampilan baru, sehingga menyebabkan kondisi race:

1. ID konfigurasi tampilan yang didukung adalah:

   • id=1, 1080x1920 60 Hz
   • id=2, 1080x1920 50 Hz

2. Framework ini memanggil setActiveConfig(display, config=1).

3. Secara bersamaan, Composer HAL memproses perubahan konfigurasi tampilan dan mengupdate status internalnya ke kumpulan konfigurasi tampilan baru, yang ditampilkan sebagai berikut:

   • id=1, 2160x3840 60 Hz
   • id=2, 2160x3840 50 Hz
   • id=3, 1080x1920 60 Hz
   • id=4, 1080x1920 50 Hz

4. Composer HAL mengirim peristiwa onHotplug ke framework untuk memberi tahu bahwa kumpulan mode yang didukung telah berubah.

5. Composer HAL menerima setActiveConfig(display, config=1) (dari langkah 2).

6. HAL menafsirkan bahwa framework telah meminta perubahan konfigurasi menjadi 2160x3840 60 Hz, meskipun pada kenyataannya yang diinginkan adalah 1080x1920 60 Hz.

Proses menggunakan penetapan ID tidak berurutan berakhir di sini dengan salah penafsiran perubahan konfigurasi yang diinginkan.

Mengonfigurasi Composer HAL untuk menggunakan ID berurutan

Untuk menghindari kondisi race tersebut, OEM harus menerapkan Composer HAL sebagai berikut:

• Saat Composer HAL memperbarui konfigurasi tampilan yang didukung, HAL ini menetapkan ID baru berurutan ke konfigurasi tampilan yang baru.
• Jika framework memanggil setActiveConfig atau setActiveConfigWithConstraints dengan ID konfigurasi yang tidak valid, HAL Composer akan mengabaikan panggilan tersebut.

Langkah-langkah ini berfungsi untuk mencegah kondisi race seperti yang ditunjukkan dalam diskusi berikut.

Pertimbangkan urutan peristiwa berikut, saat ID berurutan yang baru ditetapkan ke konfigurasi tampilan yang baru:

1. ID konfigurasi tampilan yang didukung adalah:

   • id=1, 1080x1920 60 Hz
   • id=2, 1080x1920 50 Hz

2. Framework ini memanggil setActiveConfig(display, config=1).

3. Saat perubahan konfigurasi tampilan diproses, rangkaian ID konfigurasi berikutnya ditetapkan mulai dari bilangan bulat yang tidak digunakan berikutnya, seperti yang ditampilkan sebagai berikut:

   • id=3, 2160x3840 60 Hz

   • id=4, 2160x3840 50 Hz

   • id=5, 1080x1920 60 Hz

   • id=6, 1080x1920 50 Hz

4. Composer HAL mengirim peristiwa onHotplug ke framework, untuk memberi tahu bahwa kumpulan mode yang didukung telah berubah.

5. Composer HAL menerima setActiveConfig(display, config=1) (dari langkah 2).

6. HAL Composer mengabaikan panggilan karena ID sudah tidak valid.

7. Framework ini menerima dan memproses peristiwa onHotplug dari langkah 4. Panggilan ini memanggil HAL Composer menggunakan fungsi getDisplayConfigs dan getDisplayAttribute. Dengan fungsi-fungsi ini, framework mengidentifikasi ID baru (5) untuk resolusi dan kecepatan refresh yang diinginkan, yaitu 1080x1920 dan 60 Hz.

   Catatan: Framework ini juga memanggil getActiveConfig untuk mendapatkan mode tampilan saat ini, dan jika berbeda dengan mode tampilan yang diinginkan, framework akan memanggil setActiveConfig() lagi.

8. Framework mengirim peristiwa setActiveConfig lain dengan ID 5 yang diupdate.

9. Composer HAL menerima setActiveConfig(display, config=5) dari langkah 5.

10. HAL dengan benar menafsirkan bahwa framework telah meminta perubahan konfigurasi ke 1080x1920 60 Hz.

Seperti ditunjukkan pada contoh di atas, proses yang menggunakan penetapan ID berurutan memastikan bahwa kondisi race dicegah dan perubahan konfigurasi tampilan yang benar diperbarui.