Haszowanie interfejsu

W tym dokumencie opisano hashowanie interfejsu HIDL, mechanizm zapobiegający przypadkowym zmianom interfejsu i zapewniający dokładne sprawdzenie zmian w interfejsie. Mechanizm ten jest wymagany, ponieważ interfejsy HIDL są wersjonowane, co oznacza, że ​​po wydaniu interfejsu nie można go zmieniać, chyba że w sposób zachowujący interfejs binarny aplikacji (ABI) (taki jak korekta komentarza).

Układ

Każdy katalog główny pakietu (tj. mapowanie android.hardware na hardware/interfaces lub mapowanie vendor.foo na vendor/foo/hardware/interfaces ) musi zawierać plik current.txt zawierający listę wszystkich wydanych plików interfejsu HIDL.

# current.txt files support comments starting with a ‘#' character
# this file, for instance, would be vendor/foo/hardware/interfaces/current.txt

# Each line has a SHA-256 hash followed by the name of an interface.
# They have been shortened in this doc for brevity but they are
# 64 characters in length in an actual current.txt file.
d4ed2f0e...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here

# types.hal files are also noted in current.txt files
c84da9f5...f8ea2648 vendor.awesome.foo@1.0::types

# Multiple hashes can be in the file for the same interface. This can be used
# to note how ABI sustaining changes were made to the interface.
# For instance, here is another hash for IFoo:

# Fixes type where "FooCallback" was misspelled in comment on "FooStruct"
822998d7...74d63b8c vendor.awesome.foo@1.0::IFoo

Uwaga: aby pomóc w śledzeniu, skąd pochodzą skróty, Google dzieli pliki HIDL current.txt na różne sekcje: Pierwsza sekcja została wydana w systemie Android O ; następna sekcja zostanie wydana w systemie Android O MR1 . Zdecydowanie zalecamy użycie podobnego układu w current.txt .

Haszowanie za pomocą hidl-gen

Możesz dodać skrót do pliku current.txt ręcznie lub używając hidl-gen . Poniższy fragment kodu zawiera przykłady poleceń, których można używać z hidl-gen do zarządzania plikiem current.txt (skróty zostały skrócone):

hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::types
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::INfc
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0 >> vendor/awesome/hardware/interfaces/current.txt

Ostrzeżenie: nie zastępuj skrótu dla wcześniej wydanego interfejsu. Zmieniając taki interfejs, należy dodać nowy hash na końcu current.txt . Aby uzyskać szczegółowe informacje, zobacz Stabilność ABI .

Każda biblioteka definicji interfejsu wygenerowana przez hidl-gen zawiera skróty, które można pobrać wywołując IBase::getHashChain . Kiedy hidl-gen kompiluje interfejs, sprawdza plik current.txt w katalogu głównym pakietu HAL, aby sprawdzić, czy HAL został zmieniony:

• Jeśli nie zostanie znaleziony skrót dla warstwy HAL, interfejs zostanie uznany za niepublikowany (w fazie rozwoju) i kompilacja będzie kontynuowana.
• Jeśli zostaną znalezione skróty, są one sprawdzane z bieżącym interfejsem:
  • Jeśli interfejs pasuje do skrótu, kompilacja jest kontynuowana.
  • Jeśli interfejs nie pasuje do skrótu, kompilacja zostaje zatrzymana, ponieważ oznacza to, że zmieniany jest wcześniej wydany interfejs.
    • Aby zachować zmianę ABI (zobacz Stabilność ABI ), current.txt plik .txt musi zostać zmodyfikowany, zanim będzie można kontynuować kompilację.
    • Wszystkie inne zmiany należy wprowadzić w ramach drobnej lub większej aktualizacji wersji interfejsu.

Stabilność ABI

Interfejs binarny aplikacji (ABI) zawiera binarne powiązania/konwencje wywoływania/etc. Jeśli ABI/API ulegnie zmianie, interfejs przestanie działać z ogólnym plikiem system.img , który został skompilowany z oficjalnymi interfejsami.

Upewnienie się, że interfejsy są wersjonowane, a ABI stabilne, jest kluczowe z kilku powodów:

• Gwarantuje, że Twoja implementacja przejdzie pomyślnie pakiet Vendor Test Suite (VTS), co umożliwi Ci wykonywanie OTA wyłącznie w ramach frameworku.
• Jako producent OEM możesz zapewnić pakiet wsparcia płyty (BSP), który jest prosty w użyciu i zgodny.
• Pomaga śledzić, jakie interfejsy można udostępnić. Rozważ current.txt jako mapę katalogu interfejsów, która pozwala zobaczyć historię i stan wszystkich interfejsów udostępnianych w katalogu głównym pakietu.

Dodając nowy skrót do interfejsu, który ma już wpis w current.txt , pamiętaj o dodaniu tylko skrótów reprezentujących interfejsy, które utrzymują stabilność ABI. Przejrzyj następujące typy zmian: