Antarmuka dan paket

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

HIDL dibuat berdasarkan antarmuka, jenis abstrak yang digunakan dalam bahasa berorientasi objek untuk menentukan perilaku. Setiap antarmuka adalah bagian dari paket.

Paket

Nama paket dapat memiliki sublevel seperti package.subpackage. Direktori root untuk paket HIDL yang dipublikasikan adalah hardware/interfaces atau vendor/vendorName (misalnya, vendor/google untuk perangkat Pixel). Nama paket membentuk satu atau beberapa subdirektori dalam direktori root; semua file yang menentukan paket berada dalam direktori yang sama. Misalnya, package android.hardware.example.extension.light@2.0 dapat ditemukan di bagian hardware/interfaces/example/extension/light/2.0.

Tabel berikut mencantumkan awalan dan lokasi paket:

Direktori paket berisi file dengan ekstensi .hal. Setiap file harus berisi pernyataan package yang menamai paket dan versi yang menjadi bagian dari file. File types.hal, jika ada, tidak menentukan antarmuka, tetapi menentukan jenis data yang dapat diakses oleh setiap antarmuka dalam paket.

Definisi antarmuka

Selain types.hal, setiap file .hal lainnya menentukan antarmuka. Antarmuka biasanya ditentukan sebagai berikut:

interface IBar extends IFoo { // IFoo is another interface
    // embedded types
    struct MyStruct {/*...*/};

    // interface methods
    create(int32_t id) generates (MyStruct s);
    close();
};

Antarmuka tanpa deklarasi extends eksplisit secara implisit memperluas dari android.hidl.base@1.0::IBase (mirip dengan java.lang.Object di Java.) Antarmuka IBase, yang secara implisit diimpor, mendeklarasikan beberapa metode yang dicadangkan yang tidak boleh dan tidak dapat dideklarasikan ulang di antarmuka yang ditentukan pengguna atau digunakan sebaliknya. Metode ini mencakup:

• ping
• interfaceChain
• interfaceDescriptor
• notifySyspropsChanged
• linkToDeath
• unlinkToDeath
• setHALInstrumentation
• getDebugInfo
• debug
• getHashChain

Proses impor

Pernyataan import adalah mekanisme HIDL untuk mengakses antarmuka paket dan jenis dalam paket lain. Pernyataan import terkait dengan dua entitas:

• Entitying impor, yang dapat berupa paket atau antarmuka
• Entity yangdiimpor, yang dapat berupa paket atau antarmuka

Entitas pengimporan ditentukan oleh lokasi pernyataan import. Jika pernyataan berada di dalam types.hal paket, apa yang diimpor akan terlihat oleh seluruh paket; ini adalah impor tingkat paket. Jika pernyataan berada di dalam file antarmuka, entitas impor adalah antarmuka itu sendiri; ini adalah impor tingkat antarmuka.

Entity yang diimpor ditentukan oleh nilai setelah kata kunci import. Nilai tidak harus berupa nama yang sepenuhnya memenuhi syarat; jika komponen dihilangkan, komponen tersebut akan otomatis diisi dengan informasi dari paket saat ini. Untuk nilai yang sepenuhnya memenuhi syarat, kasus impor berikut didukung:

• Impor seluruh paket. Jika nilainya adalah nama paket dan versi (sintaksis dijelaskan di bawah), seluruh paket akan diimpor ke entitas pengimpor.
• Impor sebagian. Jika nilainya:
  • Antarmuka, types.hal paket, dan antarmuka tersebut diimpor ke entitas pengimpor.
  • UDT yang ditentukan di types.hal, lalu hanya UDT tersebut yang diimpor ke entitas pengimpor (jenis lain di types.hal tidak diimpor).
• Impor khusus jenis. Jika nilai menggunakan sintaksis impor parsial yang dijelaskan di atas, tetapi dengan kata kunci types, bukan nama Antarmuka, hanya UDT di types.hal dari paket yang ditetapkan yang diimpor.

Entitas pengimpor mendapatkan akses ke kombinasi dari:

• UDT umum paket yang diimpor yang ditentukan di types.hal;
• Antarmuka paket yang diimpor (untuk impor paket lengkap) atau antarmuka yang ditentukan (untuk impor sebagian) untuk tujuan memanggilnya, meneruskan handle ke antarmuka tersebut dan/atau mewarisinya.

Pernyataan impor menggunakan sintaksis nama jenis yang sepenuhnya memenuhi syarat untuk memberikan nama dan versi paket atau antarmuka yang diimpor:

import android.hardware.nfc@1.0;            // import a whole package
import android.hardware.example@1.0::IQuux; // import an interface and types.hal
import android.hardware.example@1.0::types; // import just types.hal

Pewarisan antarmuka

Antarmuka dapat berupa ekstensi dari antarmuka yang ditentukan sebelumnya. Ekstensi dapat berupa salah satu dari tiga jenis berikut:

• Antarmuka dapat menambahkan fungsi ke antarmuka lain, dengan menggabungkan API-nya tanpa perubahan.
• Paket dapat menambahkan fungsi ke paket lain, dengan menggabungkan API-nya tanpa perubahan.
• Antarmuka dapat mengimpor jenis dari paket atau dari antarmuka tertentu.

Antarmuka hanya dapat memperluas satu antarmuka lain (tidak ada pewarisan ganda). Setiap antarmuka dalam paket dengan nomor versi minor selain nol harus memperluas antarmuka dalam versi paket sebelumnya. Misalnya, jika antarmuka IBar dalam paket derivative versi 4.0 didasarkan pada (memperluas) antarmuka IFoo dalam paket original versi 1.2, dan paket original versi 1.3 dibuat, IBar versi 4.1 tidak dapat memperluas versi 1.3 IFoo. Sebagai gantinya, IBar versi 4.1 harus memperluas IBar versi 4.0, yang terikat dengan IFoo versi 1.2. IBar versi 5.0 dapat memperluas IFoo versi 1.3, jika diinginkan.

Ekstensi antarmuka tidak menyiratkan dependensi library atau penyertaan lintas HAL dalam kode yang dihasilkan—ekstensi ini hanya mengimpor struktur data dan definisi metode di tingkat HIDL. Setiap metode dalam HAL harus diterapkan di HAL tersebut.

Ekstensi vendor

Dalam beberapa kasus, ekstensi vendor diterapkan sebagai subclass dari objek dasar yang mewakili antarmuka inti yang diperluas. Objek yang sama didaftarkan dengan nama dan versi HAL dasar, serta dengan nama dan versi HAL (vendor) ekstensi.

Pembuatan versi

Paket memiliki versi, dan antarmuka memiliki versi paketnya. Versi dinyatakan dalam dua bilangan bulat, major.minor.

• Versi utama tidak kompatibel dengan versi sebelumnya. Menambahkan nomor versi utama akan mereset nomor versi minor ke 0.
• Versi minor kompatibel dengan versi sebelumnya. Penambahan angka minor menunjukkan bahwa versi yang lebih baru sepenuhnya kompatibel dengan versi sebelumnya. Struktur dan metode data baru dapat ditambahkan, tetapi tidak ada struktur data atau tanda tangan metode yang ada yang dapat diubah.

Beberapa versi utama atau minor HAL dapat ada di perangkat secara bersamaan. Namun, versi minor harus lebih diutamakan daripada versi utama karena kode klien yang berfungsi dengan antarmuka versi minor sebelumnya juga berfungsi dengan versi minor berikutnya dari antarmuka yang sama. Untuk detail selengkapnya tentang pembuatan versi dan ekstensi vendor, lihat Pembuatan Versi HIDL.

Ringkasan tata letak antarmuka

Bagian ini merangkum cara mengelola paket antarmuka HIDL (seperti hardware/interfaces) dan menggabungkan informasi yang ditampilkan di seluruh bagian HIDL. Sebelum membaca, pastikan Anda memahami pembuatan versi HIDL, konsep hashing dengan hidl-gen, detail cara menggunakan HIDL secara umum, dan definisi berikut:

Untuk definisi selengkapnya, lihat Istilah HIDL.

Setiap file dapat ditemukan dari pemetaan root paket dan namanya yang sepenuhnya memenuhi syarat

Root paket ditentukan ke hidl-gen sebagai argumen -r android.hardware:hardware/interfaces. Misalnya, jika paketnya adalah vendor.awesome.foo@1.0::IFoo dan hidl-gen dikirim -r vendor.awesome:some/device/independent/path/interfaces, file antarmuka harus berada di $ANDROID_BUILD_TOP/some/device/independent/path/interfaces/foo/1.0/IFoo.hal.

Dalam praktiknya, sebaiknya vendor atau OEM bernama awesome menempatkan antarmuka standarnya di vendor.awesome. Setelah dipilih, jalur paket tidak boleh diubah karena sudah di-bake ke dalam ABI antarmuka.

Pemetaan jalur paket harus unik

Misalnya, jika Anda memiliki -rsome.package:$PATH_A dan -rsome.package:$PATH_B, $PATH_A harus sama dengan $PATH_B untuk direktori antarmuka yang konsisten (hal ini juga membuat antarmuka pembuatan versi jauh lebih mudah).

Akar paket harus memiliki file pembuatan versi

Jika membuat jalur paket seperti -r vendor.awesome:vendor/awesome/interfaces, Anda juga harus membuat file $ANDROID_BUILD_TOP/vendor/awesome/interfaces/current.txt, yang harus berisi hash antarmuka yang dibuat menggunakan opsi -Lhash di hidl-gen (ini dibahas secara ekstensif dalam Hashing dengan hidl-gen).

Antarmuka berada di lokasi yang tidak bergantung pada perangkat

Dalam praktiknya, sebaiknya bagikan antarmuka antarcabang. Hal ini memungkinkan penggunaan ulang kode maksimum dan pengujian kode maksimum di berbagai perangkat dan kasus penggunaan.