Le multi-HAL des capteurs est un framework qui permet aux HAL des capteurs de s'exécuter avec d'autres HAL de capteurs. Le multi-HAL des capteurs charge dynamiquement les sous-HAL des capteurs stockés en tant que bibliothèques dynamiques sur la partition du fournisseur et leur fournit un objet de rappel capable de gérer l'envoi d'événements, l'acquisition et la libération du verrouillage de réveil. Un sous-HAL de capteurs est un HAL de capteurs intégré à un objet partagé sur la partition du fournisseur et utilisé par le framework multi-HAL. Ces sous-HAL ne dépendent pas les uns des autres ni du code multi-HAL qui contient la fonction principale du processus.
Sensors Multi-HAL 2.1, disponible sur les appareils équipés d'Android 11 ou version ultérieure, est une itération de Sensors Multi-HAL 2.0 qui permet de charger des sous-HAL pouvant exposer le type de capteur angle de charnière. Pour prendre en charge ce type de capteur, les sous-HAL doivent utiliser les API de sous-HAL définies dans l'en-tête SubHal 2.1.
Pour les appareils équipés d'Android 13 ou version ultérieure qui utilisent le HAL AIDL Sensors, vous pouvez utiliser la couche shim multi-HAL pour autoriser la fonctionnalité multi-HAL. Pour en savoir plus sur l'implémentation, consultez la section Utiliser le multi-HAL Sensors avec le HAL Sensors AIDL.
Différence entre Sensors Multi-HAL 2 et Sensors HAL 2
Sensors Multi-HAL 2, disponible sur les appareils équipés d'Android 10 ou version ultérieure, introduit plusieurs abstractions au-dessus de Sensors HAL 2 pour faciliter l'interaction avec les API HAL. Sensors Multi-HAL 2 introduit la classe HalProxy pour gérer l'implémentation de l'interface Sensors HAL 2 et de l'interface V2_1/SubHal
(ou V2_0/SubHal
) afin de permettre à HalProxy
d'interagir avec les sous-HAL.
L'interface ISensorsSubHal
diffère de l'interface 2.1/ISensors.hal
(ou 2.0/ISensors.hal
) comme suit:
- La méthode initialize transmet une classe
IHalProxyCallback
au lieu de deux FMQ etISensorsCallback
. - Les sous-HAL doivent implémenter une fonction de débogage pour fournir des informations de débogage dans les rapports de bugs.
- Les sous-HAL doivent implémenter une fonction de nom afin que le sous-HAL chargé puisse être distingué des autres sous-HAL.
La principale différence entre Sensors Multi-HAL 2 et Sensors HAL 2 réside dans les fonctions d'initialisation. Au lieu de fournir des FMQ, l'interface IHalProxyCallback
fournit deux méthodes : une pour publier des événements de capteur dans le framework de capteurs et une pour créer des wake locks. Sous le capot, le multi-HAL des capteurs gère toutes les interactions avec les FMQ pour garantir la diffusion rapide des événements de capteur pour tous les sous-HAL. Il est fortement recommandé que les sous-HAL utilisent la méthode createScopedWakelock
pour déléguer la charge de la temporisation des wake locks au multi-HAL Sensors et pour centraliser l'utilisation des wake locks sur un seul wake lock commun pour l'ensemble du multi-HAL Sensors, ce qui réduit au minimum les appels de verrouillage et de déverrouillage.
Sensors Multi-HAL 2 intègre également des fonctionnalités de sécurité. Il gère les situations où le FMQ du capteur est plein ou où le framework de capteur Android redémarre et que l'état du capteur doit être réinitialisé. De plus, lorsque des événements sont publiés dans la classe HalProxy
, mais que le framework de capteurs ne peut pas les accepter immédiatement, le multi-HAL des capteurs peut déplacer les événements vers un thread en arrière-plan pour permettre la poursuite des travaux sur tous les sous-HAL en attendant que les événements soient publiés.
Code source et implémentation de référence
Le code multi-HAL de tous les capteurs est disponible dans hardware/interfaces/sensors/common/default/2.X/multihal/
.
Voici quelques ressources.
HalProxy.h
: l'objetHalProxy
est instancié par le multi-HAL Sensors et gère le transfert de données des sous-HAL vers le framework de capteurs.HalProxy.cpp
: l'implémentation deHalProxy
contient toute la logique nécessaire pour multiplexer la communication entre les sous-HAL et le framework de capteurs.SubHal.h
: l'interfaceISensorsSubHal
définit l'interface que les sous-HAL doivent suivre pour être compatibles avecHalProxy
. Le sous-HAL implémente la méthode d'initialisation afin que l'objetHalProxyCallback
puisse être utilisé pourpostEvents
etcreateScopedWakelock
.Pour les implémentations Multi-HAL 2.0, utilisez la version 2.0 de
SubHal.h
.hardware/interfaces/sensors/common/default/2.X/multihal/tests/
: ces tests unitaires vérifient l'implémentation deHalProxy
.hardware/interfaces/sensors/common/default/2.X/multihal/tests/fake_subhal/
: cet exemple d'implémentation de sous-HAL utilise de faux capteurs pour générer de fausses données. Utile pour tester l'interaction de plusieurs sous-HAL sur un appareil.
Implémentation
Cette section explique comment implémenter le multi-HAL des capteurs dans les situations suivantes:
- Utiliser le multi-HAL des capteurs avec le HAL AIDL des capteurs
- Implémenter Sensors Multi-HAL 2.1
- Portage de Sensors Multi-HAL 2.0 vers Multi-HAL 2.1
- Portage à partir de Sensors HAL 2.0
- Portage à partir de Sensors HAL 1.0
- Portage à partir de Sensors Multi-HAL 1.0
Utiliser le multi-HAL Sensors avec le HAL Sensors AIDL
Pour autoriser la fonctionnalité multi-HAL avec le HAL AIDL des capteurs, importez le module de couche de shim multi-HAL AIDL, qui se trouve dans hardware/interfaces/sensors/aidl/default/multihal/. Le module gère la conversion entre les types de définition HAL des capteurs AIDL et HIDL, et définit un wrapper autour de l'interface multi-HAL décrite dans la section Implémenter Sensors Multi-HAL 2.1. La couche de shim multi-HAL AIDL est compatible avec les appareils qui implémentent Sensors Multi-HAL 2.1.
La couche de shim multi-HAL AIDL vous permet d'exposer le suivi de la tête et les types de capteurs IMU à axes limités dans le HAL AIDL Sensors. Pour utiliser ces types de capteurs définis par l'interface HAL AIDL, définissez le champ type
dans la structure SensorInfo
dans l'implémentation getSensorsList_2_1()
. Cela est sécurisé, car les champs de type de capteur basés sur des entiers des HAL de capteurs AIDL et HIDL ne se chevauchent pas.
Implémenter Sensors Multi-HAL 2.1
Pour implémenter Sensors Multi-HAL 2.1 sur un nouvel appareil, procédez comme suit:
- Implémentez l'interface
ISensorsSubHal
comme décrit dansSubHal.h
. - Implémentez la méthode
sensorsHalGetSubHal_2_1
dansSubHal.h
. Ajoutez une cible
cc_library_shared
pour compiler le sous-HAL nouvellement implémenté. Lorsque vous ajoutez la cible:- Assurez-vous que la cible est transmise à un emplacement de la partition du fournisseur de l'appareil.
- Dans le fichier de configuration situé à
/vendor/etc/sensors/hals.conf
, ajoutez le chemin d'accès à la bibliothèque sur une nouvelle ligne. Si nécessaire, créez le fichierhals.conf
.
Pour obtenir un exemple d'entrée
Android.bp
permettant de créer une bibliothèque de sous-HAL, consultezhardware/interfaces/sensors/common/default/2.X/multihal/tests/Android.bp
.Supprimez toutes les entrées
android.hardware.sensors
du fichiermanifest.xml
, qui contient la liste des HAL compatibles sur l'appareil.Supprimez tous les fichiers de service
android.hardware.sensors
etservice.rc
du fichierdevice.mk
, puis ajoutezandroid.hardware.sensors@2.1-service.multihal
etandroid.hardware.sensors@2.1-service.multihal.rc
àPRODUCT_PACKAGES
.
Au démarrage, HalProxy
démarre, recherche le sous-HAL nouvellement implémenté et l'initialise en appelant sensorsHalGetSubHal_2_1
.
Migration de Sensors Multi-HAL 2.0 vers Multi-HAL 2.1
Pour passer de Multi-HAL 2.0 à Multi-HAL 2.1, implémentez l'interface SubHal
et recompilez votre sous-HAL.
Voici les différences entre les interfaces SubHal
2.0 et 2.1:
IHalProxyCallback
utilise les types créés dans la version 2.1 de la spécificationISensors.hal
.- La fonction
initialize()
transmet un nouvel élémentIHalProxyCallback
au lieu de celui de l'interfaceSubHal
2.0. - Les sous-HAL doivent implémenter
getSensorsList_2_1
etinjectSensorData_2_1
au lieu degetSensorsList
etinjectSensorData
, car ces méthodes utilisent les nouveaux types ajoutés dans la version 2.1 de la spécificationISensors.hal
. - Les sous-HAL doivent exposer
sensorsHalGetSubHal_2_1
plutôt quesensorsHalGetSubHal
pour que le multi-HAL les traite comme des sous-HAL de la version 2.1.
Port de Sensors HAL 2.0
Lorsque vous passez à Sensors Multi-HAL 2.0 à partir de Sensors HAL 2.0, assurez-vous que l'implémentation du HAL répond aux exigences suivantes.
Initialiser le HAL
Sensors HAL 2.0 dispose d'une fonction d'initialisation qui permet au service de capteur de transmettre des FMQ et un rappel de capteur dynamique. Dans Sensors Multi-HAL 2.0, la fonction initialize()
transmet un seul rappel qui doit être utilisé pour publier des événements de capteur, obtenir des verrouillages de réveil et notifier les connexions et les déconnexions dynamiques des capteurs.
Publier des événements de capteur dans l'implémentation multi-HAL
Au lieu d'afficher des événements de capteur via le FMQ, le sous-HAL doit écrire des événements de capteur dans IHalProxyCallback
lorsque des événements de capteur sont disponibles.
Événements WAKE_UP
Dans Sensors HAL 2.0, le HAL peut gérer le verrouillage de réveil pour son implémentation. Dans Sensors Multi-HAL 2.0, les sous-HAL permettent à l'implémentation Multi-HAL de gérer les wakelocks et peuvent demander l'acquisition d'un wakelock en appelant createScopedWakelock
.
Un verrouillage de réveil de portée verrouillée doit être acquis et transmis à postEvents
lors de la publication d'événements de réveil dans l'implémentation multi-HAL.
Capteurs dynamiques
Sensors Multi-HAL 2.0 exige que onDynamicSensorsConnected
et onDynamicSensorsDisconnected
dans IHalProxyCallback
soient appelés chaque fois que les connexions de capteurs dynamiques changent. Ces rappels sont disponibles dans le pointeur IHalProxyCallback
fourni via la fonction initialize()
.
Port de Sensors HAL 1.0
Lorsque vous passez à Sensors Multi-HAL 2.0 à partir de Sensors HAL 1.0, assurez-vous que l'implémentation du HAL répond aux exigences suivantes.
Initialiser le HAL
La fonction initialize()
doit être compatible pour établir le rappel entre le sous-HAL et l'implémentation multi-HAL.
Exposer les capteurs disponibles
Dans Sensors Multi-HAL 2.0, la fonction getSensorsList()
doit renvoyer la même valeur lors d'un seul démarrage de l'appareil, même lors des redémarrages du HAL des capteurs. Cela permet au framework de tenter de rétablir les connexions des capteurs si le serveur système redémarre. La valeur renvoyée par getSensorsList()
peut changer après le redémarrage de l'appareil.
Publier des événements de capteur dans l'implémentation multi-HAL
Dans Sensors HAL 2.0, au lieu d'attendre l'appel de poll()
, le sous-HAL doit écrire de manière proactive des événements de capteur dans IHalProxyCallback
chaque fois que des événements de capteur sont disponibles.
Événements WAKE_UP
Dans Sensors HAL 1.0, le HAL peut gérer le verrouillage de réveil pour son implémentation. Dans Sensors Multi-HAL 2.0, les sous-HAL permettent à l'implémentation Multi-HAL de gérer les verrouillages de réveil et peuvent demander l'acquisition d'un verrouillage de réveil en appelant createScopedWakelock
.
Un verrouillage de réveil de portée verrouillée doit être acquis et transmis à postEvents
lors de la publication d'événements de réveil dans l'implémentation multi-HAL.
Capteurs dynamiques
Dans Sensors HAL 1.0, les capteurs dynamiques sont renvoyés via la fonction poll()
.
Sensors Multi-HAL 2.0 exige que onDynamicSensorsConnected
et onDynamicSensorsDisconnected
dans IHalProxyCallback
soient appelés chaque fois que les connexions de capteurs dynamiques changent. Ces rappels sont disponibles dans le pointeur IHalProxyCallback
fourni via la fonction initialize()
.
Port de Sensors Multi-HAL 1.0
Pour porter une implémentation existante à partir de Sensors Multi-HAL 1.0, procédez comme suit.
- Assurez-vous que la configuration HAL des capteurs se trouve dans
/vendor/etc/sensors/hals.conf
. Cela peut impliquer de déplacer le fichier situé à/system/etc/sensors/hals.conf
. - Supprimez toutes les références à
hardware/hardware.h
et àhardware/sensors.h
, car elles ne sont pas compatibles avec HAL 2.0. - Portez les sous-HAL comme décrit dans la section Portage à partir de Sensors HAL 1.0.
- Définissez Sensors Multi-HAL 2.0 comme HAL désigné en suivant les étapes 3 et 4 de la section Implémenter Sensors Multi-HAL 2.0.
Validation
Exécuter VTS
Une fois que vous avez intégré un ou plusieurs sous-HAL avec Sensors Multi-HAL 2.1, utilisez la suite de tests du fournisseur (VTS) pour vous assurer que vos implémentations de sous-HAL répondent à toutes les exigences définies par l'interface HAL des capteurs.
Pour exécuter uniquement les tests VTS des capteurs lorsque VTS est configuré sur une machine hôte, exécutez les commandes suivantes:
vts-tradefed run commandAndExit vts \
--skip-all-system-status-check \
--primary-abi-only \
--skip-preconditions \
--module VtsHalSensorsV2_0Target && \
vts-tradefed run commandAndExit vts \
--skip-all-system-status-check \
--primary-abi-only \
--skip-preconditions \
--module VtsHalSensorsV2_1Target
Si vous exécutez la couche de shim multi-HAL AIDL, exécutez VtsAidlHalSensorsTargetTest
.
vts-tradefed run commandAndExit vts \
--skip-all-system-status-check \
--primary-abi-only \
--skip-preconditions \
--module VtsAidlHalSensorsTargetTest
Exécuter des tests unitaires
Les tests unitaires de HalProxy_test.cpp
testent HalProxy
à l'aide de faux sous-HAL instanciés dans le test unitaire et qui ne sont pas chargés dynamiquement. Lorsque vous créez un sous-HAL, ces tests doivent vous servir de guide pour ajouter des tests unitaires qui vérifient que le nouveau sous-HAL est implémenté correctement.
Pour exécuter les tests, exécutez les commandes suivantes:
cd $ANDROID_BUILD_TOP/hardware/interfaces/sensors/common/default/2.X/multihal/tests
atest
Tester avec les faux sous-HAL
Les faux sous-HAL sont des implémentations factices de l'interface ISensorsSubHal
.
Les sous-HAL exposent différentes listes de capteurs. Lorsque les capteurs sont activés, ils publient périodiquement des événements de capteur générés automatiquement dans HalProxy
en fonction des intervalles spécifiés dans une requête de capteur donnée.
Les faux sous-HAL peuvent être utilisés pour tester le fonctionnement du code Multi-HAL complet avec d'autres sous-HAL chargés dans le système et pour tester différents aspects du code Multi-HAL des capteurs.
Deux faux sous-HAL sont disponibles dans hardware/interfaces/sensors/common/default/2.X/multihal/tests/fake_subhal/
.
Pour créer et transférer les faux sous-HAL vers un appareil, procédez comme suit:
Exécutez les commandes suivantes pour créer et transférer les trois faux sous-HAL sur l'appareil:
$ANDROID_BUILD_TOP/hardware/interfaces/sensors/common/default/2.X/multihal/tests/
mma
adb push \ $ANDROID_BUILD_TOP/out/target/product/<device>/symbols/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config1.so \ /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config1.so
adb push \ $ANDROID_BUILD_TOP/out/target/product/<device>/symbols/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config2.so \ /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config2.so
adb push \ $ANDROID_BUILD_TOP/out/target/product/<device>/symbols/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config3.so \ /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config3.so
Mettez à jour la configuration HAL des capteurs à
/vendor/etc/sensors/hals.conf
avec les chemins d'accès aux faux sous-HAL./vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config1.so /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config2.so /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config3.so
Redémarrez
HalProxy
et chargez les nouveaux sous-HAL listés dans la configuration.adb shell stop
adb shell start
Débogage
Les développeurs peuvent déboguer le framework à l'aide de la commande lshal
. Pour demander la sortie de débogage du HAL des capteurs, exécutez la commande suivante:
adb root
adb shell lshal debug android.hardware.sensors@2.1::ISensors/default
Les informations sur l'état actuel de HalProxy
et de ses sous-HAL sont ensuite affichées dans le terminal. Vous trouverez ci-dessous un exemple de sortie de commande pour l'objet HalProxy
et les faux sous-HAL.
Internal values:
Threads are running: true
Wakelock timeout start time: 200 ms ago
Wakelock timeout reset time: 73208 ms ago
Wakelock ref count: 0
# of events on pending write queue: 0
# of non-dynamic sensors across all subhals: 8
# of dynamic sensors across all subhals: 0
SubHals (2):
Name: FakeSubHal-OnChange
Debug dump:
Available sensors:
Name: Ambient Temp Sensor
Min delay: 40000
Flags: 2
Name: Light Sensor
Min delay: 200000
Flags: 2
Name: Proximity Sensor
Min delay: 200000
Flags: 3
Name: Relative Humidity Sensor
Min delay: 40000
Flags: 2
Name: FakeSubHal-OnChange
Debug dump:
Available sensors:
Name: Ambient Temp Sensor
Min delay: 40000
Flags: 2
Name: Light Sensor
Min delay: 200000
Flags: 2
Name: Proximity Sensor
Min delay: 200000
Flags: 3
Name: Relative Humidity Sensor
Min delay: 40000
Flags: 2
Si le nombre spécifié pour # of events on pending write queue
est élevé (1 000 ou plus), cela indique que de nombreux événements sont en attente d'être écrits dans le framework de capteurs. Cela indique que le service de capteur est bloqué ou a planté et qu'il ne traite pas les événements de capteur, ou qu'un grand lot d'événements de capteur a été publié récemment à partir d'un sous-HAL.
Si le nombre de références de verrouillage de réveil est supérieur à 0
, cela signifie que HalProxy
a acquis un verrouillage de réveil. Cette valeur ne doit être supérieure à 0
que si un ScopedWakelock
est maintenu intentionnellement ou si des événements de réveil ont été envoyés à HalProxy
et n'ont pas été traités par le framework de capteurs.
Le descripteur de fichier transmis à la méthode de débogage de HalProxy
est transmis à chaque sous-HAL. Les développeurs doivent donc implémenter la méthode de débogage dans l'interface ISensorsSubHal
.