Antarmuka dan paket

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

Paket

Nama paket dapat memiliki sublevel seperti package.subpackage. Tujuan direktori utama untuk paket HIDL yang dipublikasikan adalah hardware/interfaces atau vendor/vendorName (misalnya, vendor/google untuk Pixel perangkat). Nama paket membentuk satu atau beberapa subdirektori di bawah root directory; semua file yang menentukan 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:

Awalan paket Lokasi Jenis antarmuka
android.hardware.* hardware/interfaces/* HAL
android.frameworks.* frameworks/hardware/interfaces/* framework/ terkait
android.system.* system/hardware/interfaces/* sistem/ terkait
android.hidl.* system/libhidl/transport/* core

Direktori paket berisi file dengan ekstensi .hal. Setiap harus berisi pernyataan package yang menamai paket dan versi tempat file tersebut berada. File types.hal, jika ada, melakukan tidak mendefinisikan antarmuka, melainkan mendefinisikan tipe data yang dapat diakses antarmuka pengguna dalam paket.

Definisi antarmuka

Selain types.hal, setiap file .hal lainnya menentukan 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 eksplisit secara implisit diperluas dari android.hidl.base@1.0::IBase (mirip dengan java.lang.Object dalam Java.) Antarmuka IBase, secara implisit mengimpor beberapa metode cadangan yang seharusnya tidak dan tidak boleh dideklarasikan ulang dalam antarmuka yang ditentukan pengguna atau digunakan sebaliknya. Metode ini termasuk:

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

Proses impor

Pernyataan import adalah mekanisme HIDL untuk mengakses paket antarmuka dan tipe dalam paket lain. Pernyataan import menyangkut dua entitas:

  • Entity yang mengimpor, yang dapat berupa paket atau antarmuka
  • Entity yang diimpor, yang dapat berupa paket atau antarmuka

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

Entitas yang diimpor ditentukan oleh nilai setelah import kata kunci. 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 didukung:

  • Impor paket secara keseluruhan. Jika nilainya adalah nama paket dan (sintaks yang dijelaskan di bawah), maka seluruh paket akan diimpor ke entitas impor.
  • Impor sebagian. Jika nilainya:
    • Antarmuka, types.hal paket, dan antarmuka tersebut diimpor ke dalam entity impor.
    • UDT yang ditentukan di types.hal, maka hanya UDT tersebut yang diimpor entitas impor (jenis lain di types.hal tidak diimpor).
  • Impor khusus jenis. Jika nilai menggunakan sintaks dari impor parsial yang dijelaskan di atas, tetapi dengan kata kunci types nama Antarmuka, hanya UDT di types.hal yang paket akan diimpor.

Entitas yang mengimpor mendapatkan akses ke kombinasi:

  • UDT umum paket yang diimpor yang ditentukan dalam types.hal;
  • Antarmuka paket yang diimpor (untuk impor paket utuh) atau yang ditentukan antarmuka (untuk impor parsial) untuk tujuan memanggilnya, meneruskan menangani mereka dan/atau mewarisi dari mereka.

Pernyataan impor menggunakan sintaks nama jenis yang sepenuhnya memenuhi syarat untuk memberikan nama dan versi paket atau antarmuka yang sedang 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 telah ditentukan sebelumnya. Ekstensi dapat berupa salah satu dari tiga jenis berikut:

  • Antarmuka dapat menambahkan fungsionalitas ke antarmuka lain dengan menggunakan API-nya tidak berubah.
  • Paket dapat menambahkan fungsionalitas ke paket lain dengan menyertakan API-nya tidak berubah.
  • Antarmuka dapat mengimpor jenis dari paket atau dari antarmuka tertentu.

Antarmuka hanya dapat memperluas satu antarmuka lainnya (tidak ada pewarisan banyak). Setiap antarmuka dalam paket dengan nomor versi minor bukan nol harus memperluas dalam versi paket sebelumnya. Misalnya, jika antarmuka IBar dalam versi 4.0 dari paket derivative didasarkan pada (memperluas) antarmuka IFoo dalam paket versi 1.2 original, dan versi 1.3 dari paket original adalah 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 yang diinginkan.

Ekstensi antarmuka tidak menyiratkan ketergantungan library atau penyertaan lintas-HAL dalam kode yang dihasilkan—cukup mengimpor struktur data dan metode pada level HIDL. Setiap metode dalam HAL harus diimplementasikan dalam HAL.

Ekstensi vendor

Dalam beberapa kasus, ekstensi vendor diterapkan sebagai subclass dari dasar yang merepresentasikan antarmuka inti yang diperluas. Objek yang sama terdaftar dengan nama dan versi HAL dasar, dan berdasarkan Nama dan versi HAL (vendor).

Pembuatan versi

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

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

Beberapa versi utama atau minor dari HAL dapat ada di perangkat secara bersamaan. Namun, versi minor harus lebih disukai daripada versi utama karena kode klien yang berfungsi dengan antarmuka versi minor sebelumnya juga berfungsi dengan versi minor baru dari antarmuka yang sama. Untuk selengkapnya detail 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 memahami Pembuatan versi HiDL, hashing dengan hidl-gen, detail bekerja dengan HIDL secara umum, dan definisi berikut:

Istilah Definisi
Antarmuka Biner aplikasi (ABI) Antarmuka pemrograman aplikasi ditambah tautan biner apa pun yang diperlukan.
nama yang sepenuhnya memenuhi syarat (fqName) Nama untuk membedakan jenis hidl. Contoh: android.hardware.foo@1.0::IFoo.
paket Paket yang berisi antarmuka dan jenis HIDL. Contoh: android.hardware.foo@1.0.
root paket Paket root yang berisi antarmuka HIDL. Contoh: antarmuka HIDL android.hardware ada di root paket android.hardware.foo@1.0.
jalur root paket Lokasi di hierarki sumber Android tempat root paket dipetakan.

Untuk definisi lainnya, lihat HIDL Terminologi.

Setiap file dapat ditemukan dari pemetaan {i>root<i} paket dan nama yang sepenuhnya memenuhi syarat

Akar paket ditetapkan untuk hidl-gen sebagai argumen -r android.hardware:hardware/interfaces. Misalnya, jika paket 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 paket dipilih, jalur tersebut tidak boleh diubah karena di-di-{i>kan<i} 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 antarmuka pembuatan versi lebih mudah).

Root paket harus memiliki file pembuatan 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 dengan menggunakan opsi -Lhash di hidl-gen (hal ini dibahas secara ekstensif dalam {i>Hashing<i} dengan hidl-gen).

Antarmuka tidak bergantung pada perangkat lokasi

Dalam praktiknya, sebaiknya gunakan antarmuka yang sama antar-cabang. Ini memungkinkan penggunaan ulang kode secara maksimum dan pengujian maksimum kode di berbagai perangkat dan kasus penggunaan.