FCM-Lebenszyklus

Eine Android-Frameworkversion hat mehrere Framework Compatibility Matrices (FCMs), eine für jede aufrüstbare Ziel-FCM-Version. Darin wird definiert, was das Framework verwenden darf und welche Anforderungen an die Ziel-FCM-Version gelten. Im Rahmen des FCM-Lebenszyklus werden HIDL HALs von Android eingestellt und entfernt. Anschließend werden FCM-Dateien so geändert, dass der Status der HAL-Version widergespiegelt wird.

Um OTAs nur für das Framework in ihren eigenen Systemen zu ermöglichen, sollten Partner, die Anbieterschnittstellen erweitern, auch HIDL HALs mit denselben Methoden verwerfen und entfernen.

Terminologie

Framework Compatibility Matrix (FCM)

Eine XML-Datei, die die Frameworkanforderungen an konforme Anbieterimplementierungen angibt. Die Kompatibilitätsmatrix ist versioniert und für jeden Framework-Release wird eine neue Version eingefroren. Jede Framework-Version enthält mehrere FCMs.

Plattform-FCM-Versionen (S_F)

Die Gesamtheit aller FCM-Versionen in einem Framework-Release. Das Framework kann mit jeder Anbieterimplementierung verwendet werden, die eine dieser FCMs erfüllt.

FCM-Version (F)

Die höchste Version aller FCMs in einem Framework-Release.

Ziel-FCM-Version (V)

Die angestrebte FCM-Version (von S_F), die im Gerätemanifest explizit deklariert ist und die eine Anbieterimplementierung erfüllt. Eine Anbieterimplementierung muss anhand eines veröffentlichten FCM generiert werden, kann aber neuere HAL-Versionen in ihrem Gerätemanifest deklarieren.

HAL-Version

Eine HAL-Version hat das Format foo@x.y, wobei foo der HAL-Name und x.y die jeweilige Version ist, z. B. nfc@1.0, keymaster@3.0. Das Stammpräfix, z. B. android.hardware, wird in diesem Dokument nicht verwendet.

Gerätemanifest

XML-Dateien, die angeben, welche HAL-Versionen die geräteseitige Anbieteroberfläche, einschließlich der Anbieter- und ODM-Images, bereitstellt. Der Inhalt eines Gerätemanifests ist durch die Ziel-FCM-Version des Geräts eingeschränkt, kann aber HALs enthalten, die im Vergleich zum FC, der V entspricht, deutlich neuer sind.

Geräte-HALs

HALs, die im Gerätemanifest aufgeführt (zur Verfügung gestellt) und in der Framework-Kompatibilitätsmatrix (FCM) aufgeführt sind (entweder erforderlich oder optional).

Gerätekompatibilitätsmatrix (Device Compatibility Matrix, DCM)

Eine XML-Datei, die die Anforderungen der Anbieter an konforme Framework-Implementierungen angibt. Jedes Gerät enthält einen DCM.

Framework-Manifest

Eine XML-Datei, in der angegeben ist, welche HAL-Versionen die Framework-Seite der Anbieterschnittstelle bereitstellt, einschließlich System-, System_ext- und Produktbildern. HALs im Framework-Manifest werden entsprechend der FCM-Zielversion des Geräts dynamisch deaktiviert.

Framework HALs

HALs, die im Framework-Manifest als bereitgestellt aufgeführt und in der Gerätekompatibilitätsmatrix (Device Compatibility Matrix, DCM) als erforderlich oder optional aufgeführt sind.

FCM-Lebenszyklus in der Codebasis

In diesem Dokument wird der FCM-Lebenszyklus in der Zusammenfassung beschrieben. Eine Liste der unterstützten Manifeste findest du unter hardware/interfaces/compatibility_matrix.<FCM>.xml. Dort findest du FCM in system/libvintf/include/vintf/Level.h.

Auf einem Gerät mit der entsprechenden Android-Releaseversion muss der FCM-Wert mindestens dem entsprechenden Level entsprechen. Ein Gerät mit Android 11 hat beispielsweise in der Regel FCM-Ebene 5, implementiert aber FCM-Ebene 6 oder höher. Dies hat verschiedene zusätzliche Anforderungen zur Folge, die in den Kompatibilitätsmatrizen angegeben sind. Folgende Stufen werden unterstützt:

Die FCM-Ebene ist gleich oder neuer als die API-Ebene des Anbieters.

Wenn eine FCM-Ebene von Android eingestellt wird, wird sie für bestehende Geräte weiterhin unterstützt. Geräte, die auf niedrigere FCM-Ebenen ausgerichtet sind, dürfen HALs, die auf neueren FCM-Ebenen aufgeführt sind, implizit verwenden, sofern sie im Zweig verfügbar sind.

In einer neuen FCM-Version entwickeln

Android erhöht die FCM-Version für jede Framework-Version (z. B. Android 8 und 8.1). Während der Entwicklung wird die neue compatibility_matrix.F.xml erstellt und die vorhandene compatibility_matrix.f.xml (wobei f < F) wird nicht mehr geändert.

So beginnen Sie mit der Entwicklung in einer neuen FCM-Version F:

1. Kopieren Sie die neueste compatibility_matrix.<F-1>.xml in compatibility_matrix.F.xml.
2. Aktualisieren Sie das Attribut level in der Datei auf F.
3. Fügen Sie entsprechende Build-Regeln hinzu, um diese Kompatibilitätsmatrix auf dem Gerät zu installieren.

Einführung einer neuen HAL

Wenn Sie während der Entwicklung eine neue HAL (z. B. für WLAN oder NFC) in Android mit der aktuellen FCM-Version F einführen, fügen Sie die HAL compatibility_matrix.F.xml mit den folgenden optional-Einstellungen hinzu:

• optional="false", wenn Geräte, die mit V = F ausgeliefert werden, mit dieser HAL gestartet werden müssen,
• optional="true", ob Geräte, die mit V = F ausgeliefert werden, ohne diese HAL gestartet werden können.

In Android 8.1 wurde beispielsweise cas@1.0 als optionale HAL eingeführt. Für Geräte, die mit Android 8.1 auf den Markt kommen, ist diese HAL nicht erforderlich. Daher wurde der folgende Eintrag zu compatibility_matrix.F.xml hinzugefügt (diese Datei hieß während der Entwicklung dieser Version vorübergehend compatibility_matrix.current.xml):

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

HAL (Nebenversion) aktualisieren

Wenn während der Entwicklung ein HAL ein Upgrade auf die Nebenversion x.(z+1) von der aktuellen FCM-Version F durchführt, gilt Folgendes für diese Version:x.z

• Erforderlich auf Geräten, die mit V = F gestartet werden. compatibility_matrix.F.xml muss x.(z+1) und optional="false" angeben.
• Auf Geräten, die mit V = F auf den Markt gebracht werden, muss compatibility_matrix.F.xml die x.y-z und die optionalen Einstellungen von compatibility_matrix.<F-1>.xml kopieren und die Version in x.w-(z+1) ändern (wobei w >= y).

In Android 8.1 wurde beispielsweise broadcastradio@1.1 als Nebenversionsupgrade der 1.0 HAL eingeführt. Die ältere Version broadcastradio@1.0 ist für Geräte mit Android 8.0 optional und die neuere Version broadcastradio@1.1 für Geräte mit Android 8.1 optional. In 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>

Dieser Eintrag wurde in compatibility_matrix.F.xml kopiert und so geändert:

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

HAL (major) aktualisieren

Wenn während der Entwicklung ein HAL ein Upgrade auf die aktuelle FCM-Version F durchführt, wird compatibility_matrix.F.xml die neue Hauptversion x.0 mit den folgenden optional-Einstellungen hinzugefügt:

• optional="false" nur mit Version x.0, wenn Geräte, die mit V = F ausgeliefert werden, mit x.0 auf den Markt gebracht werden müssen.
• optional="false", aber auch mit älteren Hauptversionen im selben <hal>-Tag, wenn Geräte, die mit V = F ausgeliefert werden, mit dieser HAL gestartet werden müssen, aber auch mit einer älteren Hauptversion gestartet werden können.
• optional="true", wenn Geräte, die mit V = F ausgeliefert werden, die HAL nicht starten müssen.

In Android 9 wird beispielsweise health@2.0 als Major-Version-Upgrade der HAL 1.0 eingeführt und die HAL 1.0 wird eingestellt. Die ältere Version health@1.0 ist für Geräte mit Android 8.0 und Android 8.1 optional. Auf Geräten, die mit Android 9 auf den Markt kommen, muss die neue Version 2.0 verfügbar sein. Angenommen, compatibility_matrix.legacy.xml, compatibility_matrix.1.xml und compatibility_matrix.2.xml enthalten diesen Eintrag:

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

Kopieren Sie diesen Eintrag in compatibility_matrix.F.xml und ändern Sie ihn so:

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

Einschränkungen:

• Da sich die 2.0 HAL in compatibility_matrix.3.xml mit optional="false" befindet, müssen Geräte, die mit Android 9 ausgeliefert werden, die 2.0 HAL enthalten.`
• Da die HAL 1.0 nicht in compatibility_matrix.3.xml enthalten ist, dürfen Geräte, die mit Android 9 ausgeliefert werden, die HAL 1.0 nicht bereitstellen, da diese HAL als eingestellt gilt.
• Da die HAL 1.0 in legacy/1/2.xml (ältere FCM-Versionen, mit denen Android 9 verwendet werden kann) als optionale HAL vorhanden ist, kann das Android 9-Framework weiterhin mit der HAL 1.0 verwendet werden (diese wird nicht als entfernte HAL-Version betrachtet).

Neue FCM-Versionen

Die Freigabe einer FCM-Version auf der Systempartition erfolgt ausschließlich von Google im Rahmen eines AOSP-Release und umfasst die folgenden Schritte:

1. Achten Sie darauf, dass das compatibility_matrix.F.xml das Attribut level="F" hat.
2. Prüfen Sie, ob alle Geräte erstellt und gestartet werden.
3. Aktualisiere die VTS-Tests, damit Geräte, die mit dem neuesten Framework (basierend auf dem Shipping API-Level) gestartet werden, die FCM-Zielversion V >= F haben.
4. Datei im AOSP veröffentlichen.

Mit VTS-Tests wird beispielsweise sichergestellt, dass auf Geräten, die mit Android 9 ausgeliefert werden, die Ziel-FCM-Version >= 3 ist.

Darüber hinaus können die FCMs für Produkt und system_ext auch Anforderungen für die einzelnen FCM-Versionen der Plattform auflisten. Die Veröffentlichung von FCM-Versionen auf den Partitionen „product“ und „system_ext“ erfolgt durch den Inhaber dieser Images. Die FCM-Versionsnummern auf den Partitionen „product“ und „system_ext“ müssen mit denen auf der Systempartition übereinstimmen. Ähnlich wie bei FCM-Versionen in der Systempartition spiegelt die Kompatibilitätsmatrix bei FCM-Version F in den Partitionen „product“ und „system_ext“ die Anforderungen an ein Gerät mit der Ziel-FCM-Version F wider.

Einstellung der HAL-Version

Die Einstellung einer HAL-Version ist eine Entscheidung des Entwicklers (d.h. für AOSP HALs trifft Google die Entscheidung). Das kann passieren, wenn eine höhere HAL-Version (egal ob Neben- oder Hauptversion) veröffentlicht wird.

HAL eines Geräts einstellen

Wenn die HAL foo@x.y eines bestimmten Geräts mit der FCM-Version F verworfen wird, bedeutet dies, dass auf Geräten, die mit der FCM-Zielversion V = F oder höher gestartet werden, foo nicht in Version x.y oder einer älteren Version als x.y implementiert werden darf. Eine eingestellte HAL-Version wird vom Framework weiterhin für das Upgrade von Geräten unterstützt.

Wenn die FCM-Version F veröffentlicht wird, gilt eine HAL-Version foo@x.y als eingestellt, wenn die jeweilige HAL-Version nicht ausdrücklich in der neuesten FCM-Version für die Ziel-FCM-Version V = F angegeben ist. Bei Geräten, die mit V = F gestartet werden, gilt eine der folgenden Bedingungen:

• Für das Framework ist eine höhere Version (Haupt- oder Nebenversion) erforderlich.
• Das Framework benötigt den HAL nicht mehr.

In Android 9 wird beispielsweise health@2.0 als Hauptversionsupgrade der 1.0 HAL eingeführt. health@1.0 wird aus compatibility_matrix.3.xml entfernt, ist aber in compatibility_matrix.legacy.xml, compatibility_matrix.1.xml und compatibility_matrix.2.xml vorhanden. Daher wird health@1.0 als eingestellt betrachtet.

HAL eines Frameworks einstellen

Wenn eine bestimmte HAL foo@x.y des Frameworks in der FCM-Version F eingestellt wird, bedeutet das, dass auf Geräten, die mit der Ziel-FCM-Version V = F oder höher gestartet werden, nicht davon ausgegangen werden darf, dass das Framework foo in Version x.y oder einer älteren Version bereitstellt.x.y Eine verworfene HAL-Version wird vom Framework für Geräteupgrades weiterhin bereitgestellt.

Wenn die FCM-Version F veröffentlicht wird, gilt die HAL-Version foo@x.y als verworfen, wenn im Framework-Manifest für foo@x.y max-level="F - 1" angegeben ist. Bei Geräten, die mit V = F gestartet werden, bietet das Framework den HAL foo@x.y nicht. In der Gerätekompatibilitätsmatrix für Geräte, die mit V = F eingeführt werden, dürfen keine Framework-HALs mit max-level < V aufgeführt sein.

In Android 12 wird schedulerservice@1.0 beispielsweise eingestellt. Das Attribut max-level ist auf 5 gesetzt, die mit Android 11 eingeführte FCM-Version. Siehe Android 12-Framework-Manifest.

Einstellung der Unterstützung für Ziel-FCM-Versionen

Wenn die aktiven Geräte einer bestimmten FCM-Zielversion V unter einen bestimmten Grenzwert fallen, wird die FCM-Zielversion aus der festgelegten _F des nächsten Framework-Release entfernt. Dies geschieht durch die beiden folgenden Schritte:

1. Entfernen Sie compatibility_matrix.V.xml aus den Build-Regeln, damit es nicht auf dem System-Image installiert wird, und löschen Sie den Code, der die entfernten Funktionen implementiert oder davon abhängig ist.

2. Entfernen Sie Framework-HALs mit einer max-level, die kleiner oder gleich V ist, aus dem Framework-Manifest und löschen Sie den Code, der die entfernten Framework-HALs implementiert.

Geräte mit einer Ziel-FCM-Version, die nicht zu S_F für eine bestimmte Framework-Version gehört, können nicht auf diese Version umgestellt werden.

HAL-Versionsstatus

In den folgenden Abschnitten werden die möglichen Status einer HAL-Version in chronologischer Reihenfolge beschrieben.

Unveröffentlicht

Wenn eine HAL-Version für Geräte nicht in einer der öffentlichen und eingefrorenen Kompatibilitätsmatrizen enthalten ist, gilt sie als nicht veröffentlicht und möglicherweise als in der Entwicklung befindlich. Dies gilt auch für HAL-Versionen, die nur in compatibility_matrix.F.xml verfügbar sind. Beispiele:

• Während der Entwicklung von Android 9 galt die health@2.0 HAL als unveröffentlichte HAL und war nur in compatibility_matrix.3.xml vorhanden.
• Die teleportation@1.0 HAL ist in keiner veröffentlichten Kompatibilitätsmatrix enthalten und gilt auch als nicht veröffentlichte HAL.

Bei Framework-HALs gilt eine HAL-Version, die sich nur im Framework-Manifest eines nicht zugehörigen Entwicklungszweigs befindet, als nicht veröffentlicht.

Veröffentlicht und aktuell

Bei Geräte-HALs wird eine HAL-Version veröffentlicht, wenn sie in einer öffentlichen und eingefrorenen Kompatibilitätsmatrix enthalten ist. Nachdem beispielsweise FCM-Version 3 eingefroren und in AOSP veröffentlicht wurde, gilt die health@2.0 HAL als veröffentlichte und aktuelle HAL-Version.

Wenn sich eine HAL-Version in einer öffentlichen und eingefrorenen Kompatibilitätsmatrix mit der höchsten FCM-Version befindet, ist die HAL-Version aktuell (d.h. nicht verworfen). Beispielsweise werden vorhandene HAL-Versionen (wie nfc@1.0 in compatibility_matrix.legacy.xml eingeführt, die in compatibility_matrix.3.xml weiterhin vorhanden sind) auch als veröffentlichte und aktuelle HAL-Versionen betrachtet.

Bei Framework-HALs gilt eine HAL-Version im Framework-Manifest des zuletzt veröffentlichten Branches ohne das Attribut max-level oder (ungewöhnlich) mit einer max-level, die der in diesem Branch veröffentlichten FCM-Version entspricht oder höher ist, als veröffentlichte und aktuelle HAL-Version. Beispielsweise ist die displayservice HAL in Android 12 veröffentlicht und aktuell, wie im Android 12-Frameworkmanifest angegeben.

Veröffentlicht, aber eingestellt

Bei Geräte-HALs wird eine HAL-Version nur dann verworfen, wenn alle der folgenden Bedingungen erfüllt sind:

• Es wird veröffentlicht.
• Sie befindet sich nicht in der öffentlichen und eingefrorenen Kompatibilitätsmatrix mit der höchsten FCM-Version.
• Es ist in einer öffentlichen und unveränderlichen Kompatibilitätsmatrix aufgeführt, in der das Framework weiterhin unterstützt wird.

Beispiele:

• Der health@1.0 HAL ist in compatibility_matrix.legacy.xml, compatibility_matrix.1.xml und compatibility_matrix.2.xml, aber nicht in compatibility_matrix.3.xml. Daher wird sie in Android 9 als veraltet betrachtet.
• Die HAL für die Energieverwaltung hat in Android 9 ein Minor-Version-Upgrade erhalten, power@1.0 ist jedoch noch bei compatibility_matrix.3.xml.
• power@1.0 compatibility_matrix.legacy.xml, compatibility_matrix.1.xml und compatibility_matrix.2.xml.
• compatibility_matrix.3.xml hat power@1.0-1.

Daher ist power@1.0 in Android 9 aktuell, aber NICHT eingestellt.

Wenn sich bei Framework-HALs eine HAL-Version im Framework-Manifest des zuletzt veröffentlichten Zweigs mit einem Attribut max-level befindet, das niedriger als der FCM-Versionsrelease in diesem Zweig ist, wird sie als freigegebene, aber nicht mehr unterstützte HAL-Version betrachtet. Die schedulerservice HAL ist beispielsweise veröffentlicht, aber in Android 12 verworfen, wie im Android 12-Framework-Manifest angegeben.

Entfernt

Bei Geräte-HALs wird eine HAL-Version nur dann entfernt, wenn Folgendes zutrifft:

• Sie wurde bereits veröffentlicht.
• Es ist in keiner öffentlichen und fixierten Kompatibilitätsmatrix aufgeführt, die vom Framework unterstützt wird.

Kompatibilitätsmatrizen, die öffentlich, eingefroren, aber vom Framework nicht unterstützt werden, werden in der Codebasis aufbewahrt, um den Satz der entfernten HAL-Versionen zu definieren. So können VTS-Tests geschrieben werden, um sicherzustellen, dass entfernte HALs nicht auf neuen Geräten vorhanden sind.

Bei Framework-HALs wird eine HAL-Version nur dann entfernt, wenn folgende Voraussetzungen erfüllt sind:

• Sie wurde bereits veröffentlicht.
• Es ist in keinem Framework-Manifest des zuletzt veröffentlichten Branches enthalten.

Legacy-FCMs

„Target FCM Version legacy“ ist ein spezieller Wert für alle Nicht-Treble-Geräte. In der Legacy-FCM-Version compatibility_matrix.legacy.xml sind die Anforderungen des Frameworks auf Legacy-Geräten (d.h. Geräten, die vor Android 8.0 auf den Markt gebracht wurden) aufgeführt.

Wenn diese Datei für einen FCM mit der Version F vorhanden ist, kann jedes Gerät, das nicht mit Treble kompatibel ist, auf F aktualisiert werden, sofern das Gerätemanifest mit dieser Datei kompatibel ist. Das Entfernen erfolgt nach demselben Verfahren wie bei FCMs für andere Ziel-FCM-Versionen (entfernt, wenn die Anzahl der aktiven Geräte mit einer älteren Version als 8.0 unter einen bestimmten Grenzwert sinkt).

Veröffentlichte FCM-Versionen

Eine Liste der veröffentlichten FCM-Versionen finden Sie unter hardware/interfaces/compatibility_matrices.

Informationen zur FCM-Version, die mit einer bestimmten Android-Version veröffentlicht wurde, finden Sie unter Level.h.