Penanganan hot-plug

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

Halaman ini menjelaskan penanganan hotplug layar dan perubahan kemampuan layar 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 dalam Composer HAL.

Memperbarui kemampuan tampilan

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

Sebelum Android dapat menangani perubahan kemampuan tampilan dengan benar, OEM harus menerapkan Composer HAL sehingga menggunakan onHotplug(display, connection=CONNECTED) untuk memberi tahu framework tentang perubahan apa pun pada kemampuan tampilan. Setelah diterapkan, Android menangani perubahan pada kemampuan layar sebagai berikut:

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

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

Framework mengalokasikan ulang framebuffer pada peristiwa onHotplug(display, connection=CONNECTED) berikutnya. Lihat Pengelolaan framebuffer klien untuk mengetahui 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 penerapan Anda saat layar utama terhubung dan terputus.

Setelah dibuat untuk perangkat seluler, framework Android tidak memiliki dukungan bawaan untuk layar 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 mengirim notifikasi onHotplug(display, connection=DISCONNECTED) untuk tampilan utama, karena hal ini akan menyebabkan framework error.

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

Skenario	Penanganan
Tidak ada layar yang terhubung saat waktu booting	Kirim sinyal onHotplug(display, connection=CONNECTED) dari Composer HAL ke framework. Ganti status tampilan fisik di dalam Composer HAL dengan status tampilan placeholder. Catatan: Sebaiknya layar penampung memiliki satu mode yang didukung dengan resolusi 1080x1920 dan kecepatan refresh 60 Hz, karena mode layar 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 Composer HAL dengan status tampilan placeholder. Tampilan placeholder harus memiliki satu mode tampilan, sehingga framework mengirimkan callback onDisplayChanged ke aplikasi (karena set mode yang didukung telah berubah). Mode tampilan tunggal ini harus cocok dengan mode aktif terakhir tampilan fisik sebelum koneksi terputus, sehingga aplikasi tidak menerima peristiwa perubahan konfigurasi.

Pertimbangan koneksi non-HDMI

Android TV hanya mendukung resolusi berikut:

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

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

Jika STB atau dongle 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 layar non-HDMI harus tercermin melalui getDisplayAttribute dan API iComposerClient lainnya (seperti getHdrCapabilities).

Menggunakan ID konfigurasi berurutan untuk mencegah kondisi race

Kondisi persaingan dapat muncul jika HAL Composer memperbarui konfigurasi layar yang didukung secara bersamaan dengan framework yang memanggil setActiveConfig atau setActiveConfigWithConstraints. Solusinya adalah menerapkan Composer HAL untuk menggunakan ID berurutan dan mencegah masalah ini.

Bagian ini menjelaskan bagaimana kondisi persaingan dapat terjadi, diikuti dengan detail tentang cara menerapkan Composer HAL sehingga menggunakan ID berurutan untuk mencegah kondisi tersebut.

Pertimbangkan urutan peristiwa berikut, saat ID berurutan baru TIDAK ditetapkan ke konfigurasi tampilan baru, sehingga menyebabkan kondisi persaingan:

1. ID konfigurasi tampilan yang didukung adalah:

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

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

3. Secara bersamaan, Composer HAL memproses perubahan konfigurasi layar dan mengupdate status internalnya ke set konfigurasi layar baru, seperti yang ditunjukkan di bawah ini:

   • 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 set mode yang didukung telah berubah.

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

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

Proses yang menggunakan penetapan ID non-berurutan berakhir di sini dengan salah menafsirkan perubahan konfigurasi yang diinginkan.

Mengonfigurasi HAL Composer untuk menggunakan ID berurutan

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

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

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

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

1. ID konfigurasi tampilan yang didukung adalah:

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

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

3. Saat perubahan konfigurasi tampilan diproses, kumpulan ID konfigurasi berikutnya ditetapkan mulai dari bilangan bulat yang tidak digunakan berikutnya, seperti yang ditunjukkan di bawah ini:

   • id=3, 2160x3840 60 Hz

   • id=4, 2160x3840 50 Hz

   • id=5, 1080x1920 60 Hz

   • id=6, 1080x1920 50 Hz

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

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

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

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

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

8. Framework mengirimkan peristiwa setActiveConfig lain dengan ID yang diperbarui menjadi 5.

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

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

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