Hashowanie interfejsu

Ten dokument opisuje haszowanie interfejsu HIDL, czyli mechanizm zapobiegający przypadkowym zmianom interfejsu i zapewniający, że zmiany interfejsu są dokładnie sprawdzane. Ten mechanizm jest wymagany, ponieważ interfejce HIDL są wersjonowane, co oznacza, że po wydaniu interfejsu nie można go zmieniać, z wyjątkiem sposobów zachowujących interfejs binarny aplikacji (ABI), takich jak poprawka komentarza.

Układ

Każdy katalog główny pakietu (czyli android.hardware mapowany na hardware/interfaces lub vendor.foo mapowany na vendor/foo/hardware/interfaces) musi zawierać plik current.txt z listą wszystkich opublikowanych 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ć śledzenie, skąd pochodzą hasze, Google dzieli pliki HIDL current.txt na różne sekcje: pierwsza sekcja to Wydana w Androidzie 8, a następna to Wydana w Androidzie 8 MR1. Zdecydowanie zalecamy użycie podobnego układu w pliku current.txt.

Haszowanie za pomocą hidl-gen

Możesz dodać hasz do pliku current.txt ręcznie lub za pomocą hidl-gen. Ten fragment kodu zawiera przykłady poleceń, których możesz używać z hidl-gen do zarządzania plikiem current.txt (zaszyfrowane wartości 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 hasha w przypadku wcześniej opublikowanego interfejsu. Podczas zmiany takiego interfejsu dodaj nowy ciąg haszowy na końcu pliku current.txt. Więcej informacji znajdziesz w artykule Stabilność ABI.

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

• Jeśli nie znajdzie się żadnego hasha dla HAL, interfejs zostanie uznany za nieopublikowany (w trakcie opracowywania) i kompilacja zostanie przeprowadzona.
• Jeśli znajdziemy szyfry, zostaną one sprawdzone w bieżącym interfejsie:
  • Jeśli interfejs pasuje do hasha, kompilacja jest kontynuowana.
  • Jeśli interfejs nie pasuje do hasha, kompilacja zostaje wstrzymana, ponieważ oznacza to, że zmienia się wcześniej opublikowany interfejs.
    • W przypadku zmiany, która zachowuje ABI (patrz stabilność ABI), przed rozpoczęciem kompilacji należy zmodyfikować plik current.txt.
    • Wszystkie inne zmiany należy wprowadzić w ramach uaktualnienia wersji podrzędnej lub głównej interfejsu.

stabilność ABI;

Interfejs ABI obejmuje linki binarne, konwencje wywoływania itp. Jeśli interfejs ABI lub API ulegnie zmianie, nie będzie już współpracować z usługą system.img, która została skompilowana z oficjalnymi interfejsami.

Upewnij się, że interfejsy mają wersje, a interfejs ABI jest stabilny. Jest to bardzo ważne z kilku powodów:

• Dzięki temu Twoja implementacja będzie mogła przejść testy dostawcy (VTS), co pozwoli Ci tworzyć OTA tylko dla frameworka.
• Umożliwia to producentom urządzeń OEM udostępnienie pakietu wsparcia płyty głównej (BSP), który jest prosty w użyciu i zgodny z wymaganiami.
• Pomaga śledzić, które interfejsy mogą zostać opublikowane. Rozważ użycie mapy current.txt katalogu interfejsów, która pozwala zobaczyć historię i stan wszystkich interfejsów udostępnianych w korzenia katalogu pakietu.

Podczas dodawania nowego hasha dla interfejsu, który ma już wpis w pliku current.txt, dodaj tylko te hashe, które reprezentują interfejsy zachowujące stabilność ABI. Zapoznaj się z tymi typami zmian: