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::typeshidl-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::INfchidl-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::INfcClientCallbackhidl-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.
- Aby zachować zmianę ABI (zobacz Stabilność ABI ),
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:
Zmiany dozwolone |
|
---|---|
Zmiany niedozwolone |
|