Haszowanie interfejsu

Ten dokument opisuje szyfrowanie interfejsu HIDL, czyli mechanizm zapobiegający przypadkowe zmiany w interfejsie oraz upewnić się, że są one dokładnie sprawdzone. Ten mechanizm jest wymagany, ponieważ interfejsy HIDL mają wersje, co oznacza, że że po udostępnieniu interfejsu nie można go zmieniać za wyjątkiem sposób zachowania interfejsu binarnego aplikacji (ABI), np. komentarz korekta).

Układ

Każdy katalog główny pakietu (tj. mapowanie android.hardware na Mapowanie hardware/interfaces lub vendor.foo na vendor/foo/hardware/interfaces) musi zawierać parametr current.txt plik zawierający listę wszystkich udostępnionych 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 ułatwić sobie określenie, które hasze są stosowane Następnie Google dzieli pliki HIDL current.txt na różne Sekcje: pierwsza sekcja jest wydana w Androidzie 8. następna sekcja otrzyma Androida 8 MR1. Zdecydowanie zalecamy użycie podobny układ do pliku current.txt.

Hasz za pomocą algorytmu hidl-gen

Hasz możesz dodać do pliku current.txt ręcznie lub przez za pomocą: hidl-gen. Ten fragment kodu zawiera przykłady poleceń, których możesz używać wraz z hidl-gen do zarządzania current.txt plik (hasze 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 elementu z udostępnionego wcześniej interfejsu. Przy zmianie takiego interfejsu dodaj nowy hasz na końcu pliku current.txt. Więcej informacji: Stabilność interfejsu ABI.

Każda biblioteka definicji interfejsu wygenerowana przez hidl-gen zawiera hasze, które można pobrać, wywołując IBase::getHashChain Gdy hidl-gen kompiluje plik sprawdza plik current.txt w katalogu głównym Aby sprawdzić, czy kod HAL uległ zmianie:

• Jeśli nie zostanie znaleziony skrót HAL, interfejs jest uznawany za nieopublikowany (w prac programistycznych) i kompilacji.
• Po znalezieniu haszy zostaną one sprawdzone w porównaniu z obecnym interfejsem:
  • Jeśli interfejs odpowiada haszowi, kompilacja będzie kontynuowana.
  • Jeśli interfejs nie odpowiada haszowi, kompilacja jest zatrzymana, ponieważ oznacza to zmianę wcześniej opublikowanego interfejsu.
    • Aby uzyskać zmianę z zachowaniem interfejsu ABI (zobacz stabilność ABI), plik current.txt, musi zostać zmodyfikowany przed kontynuacją kompilacji.
    • Wszystkie inne zmiany należy wprowadzać w ramach uaktualnienia do wersji podrzędnej lub głównej za pomocą prostego interfejsu online.

Stabilność ABI

Interfejs ABI zawiera plik binarny powiązania, konwencje wywołań itp. Jeśli interfejs ABI lub API ulegnie zmianie, nie będzie działa dłużej z ogólnym system.img, który został skompilowany z z oficjalnych interfejsów.

Zapewnienie obsługi wersji interfejsów oraz stabilnego interfejsu ABI kluczowe z kilku powodów:

• Zapewnia, że implementacja przechodzi testy Vendor Test Suite (VTS), na dobrej drodze do tego, że będziesz mieć możliwość tworzenia OTA w ramach działania platformy.
• Jako producent OEM możesz zapewnić pakiet pomocy BSP, który jest są łatwe w użyciu i zgodne z zasadami.
• Pomaga śledzić, które interfejsy można udostępnić. Rozważ current.txt mapę katalogu interfejsów umożliwiające wyświetlanie historię i stan wszystkich interfejsów w katalogu głównym pakietu.

Podczas dodawania nowego skrótu dla interfejsu, który ma już wpis w current.txt, dodaj tylko hasze, które reprezentują dla interfejsów zapewniających stabilność interfejsu ABI. Zapoznaj się z tymi typami zmian:

Zmiany dozwolone	Zmiana komentarza (chyba że spowoduje to zmianę znaczenia metody). Zmiana nazwy parametru. Zmiana nazwy zwracanego parametru. Zmiana adnotacji.
Zmiany są niedozwolone	Zmiana kolejności argumentów, metod itp. Zmiana nazwy interfejsu lub przeniesienie go do nowego pakietu. Zmiana nazwy pakietu. Dodaję pole metody/struktury itp. w dowolnym miejscu interfejsu. Wszystko, co spowodowałoby uszkodzenie tabeli vtable C++. itd.