Cykl życia w FCM

Wersja platformy Androida zawiera wiele macierzy zgodności platform (FCM) – po jednej dla każdej docelowej wersji FCM z możliwością uaktualnienia. Określają one wymagania platformy i wymagania dotyczące wersji docelowej FCM. W ramach cyklu życia FCM Android wycofuje i usuwa HAL HIDL, a następnie modyfikuje pliki FCM, aby odzwierciedlały stan wersji HAL.

Aby włączyć w swoich ekosystemach OTA dostępne tylko na platformie, partnerzy, którzy rozszerzają interfejsy dostawców, powinni też w ten sam sposób wycofać i usuwać HAL HIDL.

Terminologia

Tablica zgodności FCM
Plik XML określający ramowe wymagania dotyczące zgodnych implementacji dostawców. Macierz zgodności ma różne wersje, a nowa wersja jest blokowana dla każdej wersji platformy. Każda wersja platformy zawiera wiele FCM.
Wersje FCM na platformie (SF)
Zestaw wszystkich wersji FCM w danej wersji platformy. Platforma może współpracować z implementacją dowolnego dostawcy zgodną z jednym z tych dostawców FCM.
Wersja FCM (F)
Najwyższa wersja spośród wszystkich FCM w danej wersji platformy.
Docelowa wersja FCM (V)
Docelowa wersja FCM (z SF) wyraźnie zadeklarowana w manifeście urządzenia, którą spełnia implementacja dostawcy. Implementację dostawcy należy wygenerować w odniesieniu do opublikowanego FCM, chociaż nowsze wersje HAL mogą być zadeklarowane w pliku manifestu urządzenia.
Wersja HAL
Wersja HAL ma format foo@x.y, gdzie foo to nazwa HAL, a x.y to konkretna wersja, np. nfc@1.0, keymaster@3.0 (prefiks główny, np. android.hardware, jest pomijany w tym dokumencie).
Plik manifestu urządzenia
Pliki XML określające, jakie wersje HAL udostępniają interfejs dostawcy po stronie urządzenia, w tym obrazy dostawcy i ODM. Zawartość pliku manifestu urządzenia jest ograniczona przez docelową wersję FCM urządzenia, ale może zawierać listę HAL, które są nowsze w stosunku do FC odpowiadającego wartości V.
Listy HAL urządzeń
HAL wymienione (dostarczane) w manifeście urządzenia i (wymagane lub opcjonalne) w tablicy zgodności platformy (FCM).
Matryca zgodności urządzeń (DCM)
Plik XML określający wymagania dostawcy dotyczące zgodnych implementacji ram. Każde urządzenie zawiera jeden DCM.
Plik manifestu platformy
Plik XML określający, jakie wersje HAL udostępniają interfejs dostawcy po stronie platformy, w tym system, system_ext i zdjęcia produktu. Listy HAL w pliku manifestu platformy są wyłączane dynamicznie zgodnie z docelową wersją FCM urządzenia.
HAL platformy
HAL wymienione w pliku manifestu platformy i jako wymagane lub opcjonalne w tabeli zgodności urządzeń (DCM).

Cykl życia FCM w bazie kodu

Ten dokument w skrócie opisuje cykl życia FCM. Listę obecnie obsługiwanych plików manifestu znajdziesz w sekcji hardware/interfaces/compatibility_matrix.<FCM>.xml, gdzie FCM znajduje się w folderze system/libvintf/include/vintf/Level.h.

Urządzenie wysyłające odpowiednią wersję Androida powinno mieć wartość FCM większą lub równą tej samej wartości. Na przykład urządzenie do wysyłki urządzenia z Androidem 11 zwykle ma FCM na poziomie 5, ale implementuje FCM na poziomie 6 lub wyższym, które ma różne dodatkowe wymagania określone w tabelach zgodności. Obsługiwane poziomy:

Menedżer Społeczności Wersja Androida
4 Android 10/Q
5 Android 11 lub R
6 Android 12/S
7 Android 13/T
8 Android 14/U
202404 Android 15 lub nowszy

Po wycofaniu poziomu FCM na Androidzie będzie on nadal obsługiwany na dotychczasowych urządzeniach.

Programowanie w nowej wersji FCM

Android zwiększa wersję FCM w przypadku każdej wersji platformy (np. Android 8, 8.1 itd.). W trakcie programowania tworzony jest nowy compatibility_matrix.F.xml, a istniejący compatibility_matrix.f.xml (gdzie f < F) nie jest już zmieniany.

Aby zacząć tworzyć aplikacje w nowej wersji FCM F:

  1. Skopiuj najnowszą wartość compatibility_matrix.<F-1>.xml do folderu compatibility_matrix.F.xml.
  2. Zaktualizuj atrybut level w pliku do F.
  3. Dodaj odpowiednie reguły kompilacji, aby zainstalować tę macierz zgodności na urządzeniu.

Przedstawiamy nową wersję HAL

Podczas tworzenia nowego interfejsu HAL (Wi-Fi, NFC itp.) na Androida w obecnej wersji FCM (F) dodaj tę wartość do elementu compatibility_matrix.F.xml z tymi ustawieniami optional:

  • optional="false", jeśli urządzenia wysyłane z marką V = F muszą zostać uruchomione z użyciem tej HAL,
  • optional="true", jeśli urządzenia wysyłane z marką V = F mogą zostać uruchomione bez tej HAL.

Na przykład w Androidzie 8.1 wprowadzono cas@1.0 jako opcjonalny interfejs HAL. Nie trzeba wdrażać tej wersji HAL na urządzeniach z Androidem 8.1, więc do elementu compatibility_matrix.F.xml (tymczasowo nosił on nazwę compatibility_matrix.current.xml podczas tworzenia tej wersji) dodaliśmy ten wpis:

<hal format="hidl" optional="true">
    <name>android.hardware.cas</name>
    <version>1.0</version>
    <interface>
        <name>IMediaCasService</name>
        <instance>default</instance>
    </interface>
</hal>

Uaktualnij HAL (wersja nieważna)

W trakcie programowania, gdy HAL zostanie uaktualniony z x.z do x.(z+1) w bieżącej wersji FCM F, jeśli ta wersja:

  • Wymagane na urządzeniach uruchamianych z pomocą V = F. compatibility_matrix.F.xml musi zawierać stan x.(z+1) i optional="false".
  • Nie jest wymagane na urządzeniach uruchamianych z pakietem V = F. compatibility_matrix.F.xml musi skopiować wartość x.y-z i opcję z compatibility_matrix.<F-1>.xml oraz zmienić wersję na x.w-(z+1) (gdzie w >= y).

Na przykład w Androidzie 8.1 wprowadzono broadcastradio@1.1 jako uaktualnioną wersję HAL 1.0. Starsza wersja (broadcastradio@1.0) jest opcjonalna na urządzeniach z Androidem 8.0, a nowsza wersja (broadcastradio@1.1) jest opcjonalna na urządzeniach z Androidem 8.1. W compatibility_matrix.1.xml:

<hal format="hidl" optional="true">
    <name>android.hardware.broadcastradio</name>
    <version>1.0</version>
    <interface>
        <name>IBroadcastRadioFactory</name>
        <instance>default</instance>
    </interface>
</hal>

Ten wpis został skopiowany do folderu compatibility_matrix.F.xml i zmodyfikowany w następujący sposób:

<hal format="hidl" optional="true">
    <name>android.hardware.broadcastradio</name>
    <version>1.0-1</version>
    <interface>
        <name>IBroadcastRadioFactory</name>
        <instance>default</instance>
    </interface>
</hal>

Uaktualnienie HAL (duże)

Gdy w trakcie programowania HAL zostanie uaktualniony do wersji głównej w bieżącej wersji FCM F, do compatibility_matrix.F.xml zostanie dodana nowa wersja główna x.0 z tymi ustawieniami w usłudze optional:

  • optional="false" tylko w wersji x.0, jeśli urządzenia wysyłane z produktem V = F muszą uruchamiać się z platformą x.0.
  • optional="false", ale wraz ze starszymi wersjami głównymi w tym samym tagu <hal>, jeśli urządzenia wysyłane z pakietem V = F muszą korzystać z tej platformy HAL, ale można uruchomić starszą wersję główną.
  • optional="true", jeśli urządzenia wysyłane z marką V = F nie muszą uruchamiać kodu HAL.

Na przykład w Androidzie 9 wprowadziliśmy health@2.0 jako główne uaktualnienie HAL 1.0 i wycofaliśmy tę wersję 1.0. Starsza wersja (health@1.0) jest opcjonalna na urządzeniach z Androidem 8.0 i 8.1. Urządzenia uruchamiane z Androidem 9 nie mogą udostępniać wycofanej wersji HAL 1.0 i muszą udostępniać zamiast tego nową wersję 2.0. Ja compatibility_matrix.legacy.xml, compatibility_matrix.1.xml i compatibility_matrix.2.xml:

<hal format="hidl" optional="true">
    <name>android.hardware.health</name>
    <version>1.0</version>;
    <interface>
        <name>IHealth</name>
        <instance>default</instance>
    </interface>
</hal>

Ten wpis jest kopiowany do folderu compatibility_matrix.F.xml i modyfikowany w ten sposób:

<hal format="hidl" optional="false">
    <name>android.hardware.health</name>
    <version>2.0</version>
    <interface>
        <name>IHealth</name>
        <instance>default</instance>
    </interface>
</hal>

Ograniczenia:

  • Ponieważ HAL w wersji 2.0 jest w compatibility_matrix.3.xmlprzypadkuoptional="false", urządzenia uruchamiane z Androidem 9 muszą być wyposażone w pakiet HAL 2.0.
  • Ponieważ kod HAL 1.0 nie znajduje się w języku compatibility_matrix.3.xml, urządzenia uruchamiane z Androidem 9 nie mogą korzystać z wersji HAL 1.0 (ponieważ ta wersja jest uznawana za wycofaną).
  • Ponieważ HAL 1.0 znajduje się w starszym/1/2.xml (starszych wersjach FCM, z którymi działa Android 9) jako opcjonalny interfejs HAL, platforma Androida 9 może z nim nadal działać (nie jest uznawana za usuniętą wersję HAL).

Nowe wersje FCM

Proces publikowania wersji FCM na partycji systemowej jest wykonywany wyłącznie przez Google w ramach wersji AOSP i obejmuje te czynności:

  1. Sprawdź, czy compatibility_matrix.F.xml ma atrybut level="F".
  2. Upewnij się, że wszystkie urządzenia są kompilowane i uruchamiane.
  3. Zaktualizuj testy VTS, aby upewnić się, że urządzenia uruchamiane z użyciem najnowszej platformy (na podstawie poziomu interfejsu Shipping API) mają docelową wersję FCM V >= F.
  4. Opublikuj plik w AOSP.

Na przykład w ramach testów VTS urządzenia uruchamiane z Androidem 9 mają docelową wersję FCM >= 3.

Dodatkowo w FCM w przypadku atrybutów product i system_ext mogą być też podane wymagania dla każdej wersji FCM na platformie. Opublikowanie wersji FCM w przypadku partycji produktu i partycji system_ext jest wykonywane odpowiednio przez właściciela tych zdjęć. Numery wersji FCM na partycjach usługi i system_ext muszą być zgodne z numerami na partycji systemowej. Podobnie jak w przypadku wersji FCM na partycji systemowej, macierz zgodności w FCM w wersji F w partycjach produktu i system_ext odzwierciedla wymagania urządzenia z docelową wersją FCM w FCM.

Wycofanie wersji HAL

Wycofanie wersji HAL jest decyzją dewelopera (w przypadku licencji AOSP HAL podejmuje to Google). Może się tak zdarzyć po opublikowaniu wyższej wersji HAL (wersji podrzędnej lub głównej).

Wycofanie HAL urządzenia

Jeśli interfejs HAL foo@x.y danego urządzenia został wycofany w FCM w wersji F, oznacza to, że na urządzeniach uruchamianych w FCM w wersji V = F lub nowszej nie można wdrażać elementu foo w wersji x.y ani starszej niż x.y. Wycofana wersja HAL jest nadal obsługiwana przez platformę do uaktualniania urządzeń.

Po opublikowaniu wersji F FCM wersja HAL foo@x.y jest uznawana za wycofaną, jeśli konkretna wersja HAL nie została wyraźnie określona w najnowszej wersji FCM dla docelowej wersji FCM V = F. W przypadku urządzeń uruchamianych za pomocą funkcji V = F spełniony jest jeden z tych warunków:

  • Platforma wymaga wyższej wersji (głównej lub podrzędnej).
  • Platforma nie wymaga już HAL.

Na przykład w Androidzie 9 pakiet health@2.0 został wprowadzony jako główne uaktualnienie HAL 1.0. Element health@1.0 został usunięty z compatibility_matrix.3.xml, ale znajduje się w plikach compatibility_matrix.legacy.xml, compatibility_matrix.1.xml i compatibility_matrix.2.xml. Z tego powodu usługa health@1.0 jest uznawana za wycofaną.

Wycofanie platformy HAL

Jeśli platforma HAL foo@x.y została wycofana w FCM w wersji F, oznacza to, że żadne urządzenia uruchamiane z docelową wersją FCM w wersji V = F lub nowszej nie mogą oczekiwać, że platforma będzie udostępniać foo w wersji x.y ani w żadnej wersji starszej niż x.y. Platforma do uaktualniania urządzeń nadal udostępnia wycofaną wersję HAL.

Po opublikowaniu wersji F FCM wersja HAL foo@x.y jest uznawana za wycofaną, jeśli w pliku manifestu platformy znajdziesz właściwość max-level="F - 1" dla foo@x.y. W przypadku urządzeń uruchamianych za pomocą interfejsu V = F platforma nie udostępnia interfejsu HAL foo@x.y. Tablica zgodności urządzeń z uruchomionym kodem V = F nie może zawierać list HAL z platformą max-level < V.

Na przykład w Androidzie 12 wycofano schedulerservice@1.0. Jego atrybut max-level ma wartość 5 – jest to wersja FCM wprowadzona w Androidzie 11. Zobacz plik manifestu platformy Android 12.

Wycofanie obsługi docelowych wersji FCM

Gdy liczba aktywnych urządzeń określonej docelowej wersji FCM (V) spadnie poniżej określonego progu, docelowa wersja FCM zostanie usunięta z zestawu F następnej wersji platformy. Aby to zrobić:

  1. Usunięcie pakietu compatibility_matrix.V.xml z reguł kompilacji (aby nie był on zainstalowany w obrazie systemu) oraz usunięcie kodu, który został wdrożony lub zależał od usuniętej funkcji.

  2. Usunięcie z pliku manifestu platformy HAL platformy max-level o wartości V lub mniejszej z pliku manifestu platformy i usunięcie całego kodu, który implementuje usunięte HAL platformy.

Urządzenia z docelową wersją FCM inną niż SF w danej wersji platformy nie mogą zostać uaktualnione do tej wersji.

Stan wersji HAL

W kolejnych sekcjach opisano możliwe stany wersji HAL (w kolejności chronologicznej).

Niewydane

W przypadku list HAL urządzeń, jeśli wersja HAL nie znajduje się w żadnej z publicznych i zablokowanych macierzy zgodności, jest uważana za nieopublikowaną i prawdopodobnie znajdującą się w fazie rozwoju. Dotyczy to też wersji HAL, które występują tylko w języku compatibility_matrix.F.xml. Przykłady:

  • W momencie tworzenia Androida 9 wartość HAL health@2.0 była uważana za nieopublikowaną i znajdowała się tylko w compatibility_matrix.3.xml.
  • HAL teleportation@1.0 nie występuje w żadnej z opublikowanych macierzy zgodności i jest też uważana za nieopublikowaną wersję HAL.

W przypadku platform HAL, jeśli wersja HAL znajduje się tylko w pliku manifestu platformy niepowiązanej gałęzi programistycznej, jest uznawana za nieopublikowaną.

Opublikowano i aktualne

Jeśli wersja HAL znajduje się w publicznej lub zablokowanej macierzy zgodności, jest publikowana. Na przykład po zawieszeniu i opublikowaniu wersji 3 FCM w AOSP wersja HAL health@2.0 jest uznawana za opublikowaną i bieżącą wersję HAL.

Jeśli wersja HAL znajduje się w publicznej i zablokowanej macierzy zgodności z najwyższą wersją FCM, wersja HAL jest aktualna (czyli nie została wycofana). Na przykład istniejące wersje HAL (np. nfc@1.0 wprowadzone w compatibility_matrix.legacy.xml, które nadal istnieją w compatibility_matrix.3.xml, są również uznawane za udostępnione i aktualne wersje HAL).

W przypadku platform HAL, jeśli wersja HAL znajduje się w pliku manifestu najnowszej opublikowanej gałęzi bez atrybutu max-level lub (nietypowo) ma ona wartość max-level równą wersji FCM dostępnej w tej gałęzi lub wyższej, jest ona uznawana za opublikowaną i bieżącą wersję HAL. Na przykład wersja HAL displayservice jest opublikowana i bieżąca w Androidzie 12, zgodnie z informacjami zawartymi w pliku manifestu platformy Androida 12.

Wersja opublikowana, ale wycofana

Wersje HAL urządzeń są wycofywane tylko wtedy, gdy są spełnione wszystkie te warunki:

  • Została opublikowana.
  • Nie znajduje się ona w publicznej, zablokowanej macierzy zgodności, która ma najwyższą wersję FCM.
  • Znajduje się w publicznej, zablokowanej macierzy zgodności, którą platforma nadal obsługuje.

Przykłady:

Dlatego tag power@1.0 jest aktualny, ale NIE jest wycofany w Androidzie 9.

W przypadku platform HAL, jeśli wersja HAL jest w pliku manifestu platformy najnowszej wydanej gałęzi, w której atrybut max-level jest niższy niż wersja FCM w tej gałęzi, jest uznawana za opublikowaną, ale wycofaną wersję HAL. Na przykład wersja HAL schedulerservice jest opublikowana, ale została wycofana w Androidzie 12, zgodnie z informacjami w pliku manifestu platformy Androida 12.

Usunięto

W przypadku list HAL urządzeń wersja HAL jest usuwana tylko wtedy, gdy są spełnione te warunki:

  • Została wcześniej wydana.
  • Nie znajduje się w żadnej publicznej, zablokowanej macierzy zgodności obsługiwanej przez tę platformę.

Macierze zgodności, które są publiczne, zablokowane, ale nie obsługiwane przez platformę, są przechowywane w bazie kodu do definiowania zestawu wersji HAL. Dzięki temu można zapisywać testy VTS tak, aby usunięte HAL nie były umieszczane na nowych urządzeniach.

W przypadku platformy HAL wersja HAL jest usuwana tylko wtedy, gdy są spełnione te warunki:

  • Została wcześniej wydana.
  • Nie ma go w żadnym pliku manifestu platformy w najnowszej opublikowanej gałęzi.

Starsze wersje FCM

Starsza wersja docelowej wersji FCM to specjalna wartość w przypadku wszystkich urządzeń innych niż wysokie. Starsza wersja FCM (compatibility_matrix.legacy.xml) zawiera listę wymagań dotyczących platformy w przypadku starszych urządzeń (tj. tych, które zostały wprowadzone na rynek przed Androidem 8.0).

Jeśli ten plik istnieje w FCM w wersji F, to na każdym urządzeniu bez wysokich tonów można przejść na F, o ile jego plik manifestu urządzenia jest zgodny z tym plikiem. Jego usunięcie przebiega tak samo jak w FCM w przypadku innych docelowych wersji FCM (usuniętych, gdy liczba aktywnych urządzeń w wersjach starszych niż 8.0 spadnie poniżej określonego progu).

Udostępnione wersje FCM

Listę opublikowanych wersji FCM znajdziesz tutaj: hardware/interfaces/compatibility_matrices.

Wersję FCM wydaną wraz z konkretną wersją Androida znajdziesz tutaj: Level.h.