Abandon de la version HAL

Dans la version L d'Android, nous interrompons la prise en charge de certaines versions de HAL de capteur. Les seules versions compatibles sont SENSORS_DEVICE_API_VERSION_1_0 et SENSORS_DEVICE_API_VERSION_1_3.

Dans les prochaines versions, nous allons probablement abandonner la compatibilité avec la version 1_0.

1_0 ne comporte pas de concept de traitement par lot. Si possible, tous les appareils utilisant la version 1_0 DOIVENT passer à la version 1_3.

Les versions 1_1 et 1_2 souffrent d'une mauvaise définition du concept de traitement par lot et ne sont plus compatibles.

Tous les appareils qui utilisent actuellement la version 1_1 ou 1_2 DOIVENT passer à la version 1_3.

Dans la version 1_3, nous avons simplifié la notion de traitement par lot et introduit des capteurs de réveil.

Pour passer à la version 1_3, suivez les modifications ci-dessous.

Implémenter la fonction de traitement par lot

Même si vous n'implémentez pas le traitement par lot (votre matériel ne dispose pas de FIFO), vous devez implémenter la fonction batch. batch permet de définir la période d'échantillonnage et la latence de création de rapports maximale pour un capteur donné. Il remplace setDelay. setDelay ne sera plus appelé.

Si vous n'implémentez pas le traitement par lot, vous pouvez implémenter batch en appelant simplement votre fonction setDelay existante avec le paramètre sampling_period_ns fourni.

Implémenter la fonction flush

Même si vous n'implémentez pas le traitement par lot, vous devez implémenter la fonction flush.

Si vous n'implémentez pas le traitement par lot, flush doit générer un événement META_DATA_FLUSH_COMPLETE et renvoyer 0 (succès).

Modifier votre sensors_poll_device_t.common.version

your_poll_device.common.version = SENSORS_DEVICE_API_VERSION_1_3

Ajoutez les nouveaux champs à la définition de vos capteurs.

Lorsque vous définissez chaque capteur, en plus des champs sensor_t habituels:

.name =       "My magnetic field Sensor",
.vendor =     "My company",
.version
=    1,
.handle =     mag_handle,
.type =       SENSOR_TYPE_MAGNETIC_FIELD,
.maxRange =   200.0f,
.resolution = CONVERT_M,
.power =      5.0f,
.minDelay =
 16667,

Vous devez également définir les nouveaux champs, définis entre 1_0 et 1_3:

.fifoReservedEventCount = 0,
.fifoMaxEventCount =   0,
.stringType =         0,
.requiredPermission = 0,
.maxDelay =      200000
.flags =
SENSOR_FLAG_CONTINUOUS_MODE,

fifoReservedEventCount: si vous n'implémentez pas le traitement par lot, définissez cette valeur sur 0.

fifoMaxEventCount: si vous n'implémentez pas le traitement par lot, définissez cette valeur sur 0.

stringType: défini sur 0 pour tous les capteurs Android officiels (ceux qui sont définis dans sensors.h), car cette valeur sera écrasée par le framework. Pour les capteurs non officiels, consultez sensor_t pour savoir comment les configurer.

requiredPermission: autorisation dont les applications auront besoin pour accéder à votre capteur. Vous pouvez généralement définir cette valeur sur 0 pour tous vos capteurs, mais les capteurs de type HEART_RATE doivent la définir sur SENSOR_PERMISSION_BODY_SENSORS..

maxDelay: cette valeur est importante et vous devrez la définir en fonction des fonctionnalités du capteur et de son pilote.

Cette valeur n'est définie que pour les capteurs en continu et à changement. Il s'agit du délai entre deux événements de capteur correspondant à la fréquence la plus basse prise en charge par ce capteur. Lorsque des fréquences inférieures sont demandées via la fonction batch, les événements sont générés à cette fréquence à la place. Il peut être utilisé par le framework ou les applications pour estimer quand la file d'attente FIFO par lot peut être saturée. Si cette valeur n'est pas définie correctement, CTS échouera. Pour les capteurs à déclenchement unique et en mode de création de rapports spécial, définissez maxDelay sur 0.

Pour les capteurs en continu, définissez-le sur la période d'échantillonnage maximale autorisée en microsecondes.

Les éléments suivants s'appliquent à period_ns, maxDelay et minDelay:

  • period_ns est en nanosecondes, tandis que maxDelay/minDelay sont en microsecondes.
  • maxDelay doit toujours tenir dans un entier signé de 32 bits. Il est déclaré comme 64 bits sur les architectures 64 bits uniquement pour des raisons de compatibilité binaire.

flags: ce champ définit le mode de création de rapports du capteur et si le capteur est un capteur de réveil.

Si vous n'implémentez pas le traitement par lot et que vous passez simplement de la version 1.0 à la version 1.3, définissez cette valeur sur:

SENSOR_FLAG_WAKE_UP | SENSOR_FLAG_ONE_SHOT_MODE pour les capteurs à déclenchement

SENSOR_FLAG_CONTINUOUS_MODE pour les capteurs continus SENSOR_FLAG_ON_CHANGE_MODE pour les capteurs à changement, à l'exception du capteur de proximité SENSOR_FLAG_SPECIAL_REPORTING_MODE pour les capteurs avec un mode de création de rapports spécifique, à l'exception du détecteur d'inclinaison.

SENSOR_FLAG_WAKE_UP | SENSOR_FLAG_ON_CHANGE_MODE pour le capteur de proximité et le capteur détecteur d'inclinaison officiel d'Android.

Remarques lors de la mise à niveau à partir de la version 1_1 ou 1_2

  • La fonction batch réussit désormais presque toujours, même pour les capteurs qui ne sont pas compatibles avec le traitement par lot, indépendamment de la valeur de l'argument de délai avant expiration. Les seuls cas où la fonction batch peut échouer sont les erreurs internes, ou une mauvaise sensor_handle,, ou une sampling_period_ns ou une max_report_latency_ns négative.
  • La compatibilité d'un capteur avec le traitement par lot est définie par la valeur fifoMaxEventCount supérieure à 0. (Dans les versions précédentes, il était basé sur la valeur renvoyée par batch().)
  • Les capteurs compatibles avec le traitement par lot sont toujours dans ce que nous appelions le "mode par lot" dans les versions précédentes: même si le paramètre max_report_latency_ns est défini sur 0, le capteur doit toujours être traité par lot, ce qui signifie que les événements doivent être stockés dans la file d'attente FIFO lorsque le SoC passe en mode suspension.
  • Le paramètre flags de la fonction batch n'est plus utilisé. DRY_RUN et WAKE_UPON_FIFO_FULL sont tous deux obsolètes et ne seront jamais transmis à la fonction batch.
  • L'argument de délai avant expiration de la série d'opérations est désormais appelé argument max_report_latency.