Antarmuka & Paket

HIDL dibangun di sekitar antarmuka, tipe abstrak yang digunakan dalam bahasa berorientasi objek untuk mendefinisikan perilaku. Setiap antarmuka adalah bagian dari sebuah paket.

Paket

Nama paket dapat memiliki sublevel seperti package.subpackage . Direktori root untuk paket HIDL yang diterbitkan adalah hardware/interfaces atau vendor/vendorName (mis vendor/google untuk perangkat Pixel). Nama paket membentuk satu atau lebih subdirektori di bawah direktori root; semua file yang mendefinisikan sebuah paket berada di direktori yang sama. Misalnya, package android.hardware.example.extension.light@2.0 dapat ditemukan di 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 file tersebut menjadi bagiannya. File types.hal , jika ada, tidak mendefinisikan antarmuka melainkan mendefinisikan tipe data yang dapat diakses oleh setiap antarmuka dalam paket.

Definisi antarmuka

Selain dari types.hal , setiap file .hal lainnya mendefinisikan sebuah antarmuka. Sebuah antarmuka biasanya didefinisikan 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 perluasan eksplisit secara implisit extends dari android.hidl.base@1.0::IBase (mirip dengan java.lang.Object di Java.) Antarmuka IBase, yang diimpor secara implisit, mendeklarasikan beberapa metode yang dicadangkan yang tidak boleh dan tidak dapat dideklarasikan ulang dalam antarmuka yang ditentukan pengguna atau digunakan sebaliknya. Metode ini meliputi:

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

Pengimporan

Pernyataan import adalah mekanisme HIDL untuk mengakses antarmuka paket dan mengetik di paket lain. Pernyataan import menyangkut dirinya dengan dua entitas:

• Entitas impor, yang dapat berupa paket atau antarmuka; dan
• Entitas import ed , yang juga dapat berupa paket atau antarmuka.

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

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

• Impor paket utuh . Jika nilainya adalah nama paket dan versi (sintaks yang dijelaskan di bawah), maka seluruh paket diimpor ke entitas pengimpor.
• Impor sebagian . Jika nilainya adalah:
  • Antarmuka, types.hal paket, dan antarmuka itu diimpor ke entitas pengimpor.
  • Sebuah UDT didefinisikan dalam types.hal , maka hanya UDT yang diimpor ke entitas pengimpor (jenis lain dalam types.hal tidak diimpor).
• Impor khusus jenis . Jika nilai menggunakan sintaks impor parsial yang dijelaskan di atas, tetapi dengan types kata kunci alih-alih nama Antarmuka, hanya UDT dalam types.hal dari paket yang ditunjuk yang diimpor.

Entitas pengimpor mendapatkan akses ke kombinasi:

• UDT umum paket yang diimpor didefinisikan dalam types.hal ;
• Antarmuka paket yang diimpor (untuk impor seluruh paket) atau antarmuka yang ditentukan (untuk impor sebagian) untuk tujuan memanggilnya, memberikan pegangan kepada mereka dan/atau mewarisi darinya.

Pernyataan impor menggunakan sintaks nama tipe 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

Warisan antarmuka

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

• Antarmuka dapat menambahkan fungsionalitas ke yang lain, menggabungkan API-nya tidak berubah.
• Paket dapat menambahkan fungsionalitas ke yang lain, menggabungkan API-nya tidak berubah.
• Antarmuka dapat mengimpor jenis dari paket atau dari antarmuka tertentu.

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

Ekstensi antarmuka tidak menyiratkan ketergantungan perpustakaan atau penyertaan lintas-HAL dalam kode yang dihasilkan—mereka hanya mengimpor struktur data dan definisi metode pada tingkat HIDL. Setiap metode dalam HAL harus diimplementasikan dalam HAL tersebut.

Ekstensi vendor

Dalam beberapa kasus, ekstensi vendor akan diimplementasikan sebagai subkelas dari objek dasar yang mewakili antarmuka inti yang mereka kembangkan. Objek yang sama akan didaftarkan di bawah nama dan versi HAL dasar, dan di bawah nama dan versi HAL ekstensi (vendor).

Versi

Paket berversi, dan antarmuka memiliki versi paketnya. Versi dinyatakan dalam dua bilangan bulat, mayor . kecil .

• Versi utama tidak kompatibel ke belakang. Menaikkan nomor versi utama akan mengatur ulang nomor versi minor ke 0.
• Versi minor kompatibel ke belakang. Penambahan angka minor menunjukkan 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 besar atau kecil dari HAL dapat hadir pada perangkat secara bersamaan. Namun, versi minor harus lebih disukai daripada versi mayor karena kode klien yang berfungsi dengan antarmuka versi minor sebelumnya juga akan berfungsi dengan versi minor yang lebih baru 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 disajikan di seluruh bagian HIDL. Sebelum membaca, pastikan Anda sudah familiar dengan HIDL Versioning , konsep hashing di Hashing dengan hidl-gen , rincian bekerja dengan HIDL secara umum , dan definisi berikut:

Untuk definisi lebih lanjut, lihat Terminologi HIDL.

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

Akar 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 , maka file antarmuka harus ditempatkan di $ANDROID_BUILD_TOP/some/device/independent/path/interfaces/foo/1.0/IFoo.hal .

Dalam praktiknya, direkomendasikan untuk vendor atau OEM bernama awesome untuk menempatkan antarmuka standar mereka di vendor.awesome . Setelah jalur paket dipilih, itu tidak boleh diubah karena ini dimasukkan 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 (ini juga membuat versi antarmuka menjadi lebih mudah).

Root paket harus memiliki file versi

Jika Anda 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 -Lhash opsi di hidl-gen (ini dibahas secara luas di Hashing dengan hidl-gen ).

Antarmuka masuk ke lokasi yang tidak bergantung pada perangkat

Dalam praktiknya, disarankan untuk berbagi antarmuka antar cabang. Ini memungkinkan penggunaan ulang kode maksimum dan pengujian kode maksimum di berbagai perangkat dan kasus penggunaan.