Antarmuka & Paket

HIDL dibangun berdasarkan 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 akar untuk paket HIDL yang diterbitkan adalah hardware/interfaces atau vendor/vendorName (misalnya vendor/google untuk perangkat Pixel). Nama paket membentuk satu atau lebih subdirektori di bawah direktori root; semua file yang mendefinisikan suatu paket berada di direktori yang sama. Misalnya, package android.hardware.example.extension.light@2.0 dapat ditemukan di bawah 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 memberi nama paket dan versi file tersebut. 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 antarmuka. 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 extends yang eksplisit secara implisit meluas dari android.hidl.base@1.0::IBase (mirip dengan java.lang.Object di Java.) Antarmuka IBase, yang diimpor secara implisit, mendeklarasikan beberapa metode khusus yang tidak boleh dan tidak dapat dideklarasikan ulang di antarmuka yang ditentukan pengguna atau digunakan sebaliknya. Metode-metode ini meliputi:

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

Pengimporan

Pernyataan import adalah mekanisme HIDL untuk mengakses antarmuka paket dan mengetikkan paket lain. Pernyataan import berkaitan dengan dua entitas:

• Entitas pengimpor , yang dapat berupa paket atau antarmuka; Dan
• Entitas yang diimpor, yang juga dapat berupa paket atau antarmuka.

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

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

• Impor seluruh paket . Jika nilainya adalah nama paket dan versi (sintaks dijelaskan di bawah), maka seluruh paket akan diimpor ke entitas pengimpor.
• Impor sebagian . Jika nilainya adalah:
  • Antarmuka, types.hal paket, dan antarmuka tersebut diimpor ke entitas pengimpor.
  • UDT yang didefinisikan dalam types.hal , maka hanya UDT tersebut yang diimpor ke entitas pengimpor (tipe lain dalam types.hal tidak diimpor).
• Impor hanya tipe . Jika nilai menggunakan sintaksis impor parsial yang dijelaskan di atas, namun dengan kata kunci types dan bukan nama Antarmuka, hanya UDT dalam types.hal dari paket yang ditunjuk yang diimpor.

Entitas pengimpor mendapat akses ke kombinasi:

• UDT umum paket yang diimpor ditentukan dalam types.hal ;
• Antarmuka paket yang diimpor (untuk impor seluruh paket) atau antarmuka tertentu (untuk impor sebagian) untuk tujuan memanggilnya, meneruskan pegangannya dan/atau mewarisinya.

Pernyataan import 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 antarmuka lain, menggabungkan API-nya tanpa perubahan.
• Paket dapat menambahkan fungsionalitas ke paket lainnya, dengan menggabungkan API-nya tanpa perubahan.
• Antarmuka dapat mengimpor tipe dari suatu paket atau dari antarmuka tertentu.

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

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

Ekstensi vendor

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

Pembuatan versi

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

• Versi utama tidak kompatibel ke belakang. Menambah nomor versi mayor akan mengatur ulang nomor versi minor menjadi 0.
• Versi minor kompatibel ke belakang. Menambah angka minor menunjukkan bahwa versi yang lebih baru sepenuhnya kompatibel dengan versi sebelumnya. Struktur dan metode data baru dapat ditambahkan, namun tidak ada struktur data atau tanda tangan metode yang ada yang dapat diubah.

Beberapa versi HAL besar atau kecil dapat muncul di perangkat secara bersamaan. Namun, versi minor sebaiknya lebih diutamakan 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 memahami HIDL Versioning , konsep hashing dalam Hashing dengan hidl-gen , detail penggunaan HIDL secara umum , dan definisi berikut:

Untuk definisi lebih lanjut, lihat Terminologi HIDL.

Setiap file dapat ditemukan dari pemetaan root paket dan nama lengkapnya

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, disarankan bagi vendor atau OEM bernama awesome untuk memasang antarmuka standar mereka di vendor.awesome . Setelah jalur paket dipilih, jalur tersebut tidak boleh diubah karena jalur 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 pembuatan 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 berada di lokasi yang tidak bergantung pada perangkat

Dalam praktiknya, disarankan untuk berbagi antarmuka antar cabang. Hal ini memungkinkan penggunaan kembali kode secara maksimal dan pengujian kode secara maksimal di berbagai perangkat dan kasus penggunaan.