A camada de abstração de hardware de sensores (HAL, na sigla em inglês) é a interface entre o framework de sensores do Android e os sensores de um dispositivo, como um acelerômetro ou giroscópio. O HAL de sensores define as funções que precisam ser implementadas para permitir que o framework controle os sensores.
A Sensors HAL 2.0 está disponível no Android 10 e versões mais recentes para dispositivos novos e atualizados. A Sensors HAL 2.0 é baseada na Sensors HAL 1.0, mas tem várias diferenças importantes, o que impede a compatibilidade com versões anteriores. A Sensors HAL 2.0 usa filas rápidas de mensagens (FMQs, na sigla em inglês) para enviar eventos do sensor da HAL para o Android Sensors Framework.
A HAL 2.1 de sensores está disponível no Android 11 e em versões mais recentes
para dispositivos novos e atualizados. A Sensors HAL 2.1 é uma iteração da Sensors HAL 2.0
que expõe o tipo de sensor
HINGE_ANGLE
e atualiza vários métodos para aceitar o tipo HINGE_ANGLE.
Interface HAL 2.1
A principal fonte de documentação da HAL de sensores 2.1 está na definição
da HAL em
hardware/interfaces/sensors/2.1/ISensors.hal.
Se houver um conflito de requisitos entre esta página e ISensors.hal,
use o requisito em ISensors.hal.
Interface HAL 2.0
A principal fonte de documentação da HAL 2.0 de sensores está na definição
da HAL em
hardware/interfaces/sensors/2.0/ISensors.hal.
Se houver um conflito de requisitos entre esta página e ISensors.hal,
use o requisito em ISensors.hal.
Implementar a HAL 2.0 e a HAL 2.1 de sensores
Para implementar o Sensors HAL 2.0 ou 2.1, um objeto precisa estender a interface ISensors
e implementar todas as funções definidas em
2.0/ISensors.hal
ou
2.1/ISensors.hal.
Inicializar o HAL
A HAL de sensores precisa ser inicializada pelo Android Sensors Framework antes de ser
usada. O framework chama a função initialize() para a HAL 2.0 e
a função initialize_2_1() para a HAL 2.1 para fornecer três parâmetros à
HAL de sensores: dois descritores de FMQ e um ponteiro para um objeto
ISensorsCallback.
A HAL usa o primeiro descritor para criar o evento FMQ usado para gravar eventos
do sensor no framework. A HAL usa o segundo descritor para criar a FMQ de trava de ativação
usada para sincronizar quando a HAL libera a trava de ativação para eventos do sensor
WAKE_UP. O HAL precisa salvar um ponteiro para o objeto ISensorsCallback para
que todas as funções de callback necessárias possam ser invocadas.
A função initialize() ou initialize_2_1() precisa ser a primeira função
chamada ao inicializar o HAL de sensores.
Expor os sensores disponíveis
Para conferir uma lista de todos os sensores estáticos disponíveis no dispositivo, use a
função getSensorsList() no HAL 2.0 e a função getSensorsList_2_1() no
HAL 2.1. Essa função retorna uma lista de sensores, cada um identificado exclusivamente pelo
identificador. O identificador de um determinado sensor não pode mudar quando o processo
que hospeda a HAL de sensores é reiniciado. Os identificadores podem mudar entre as reinicializações do dispositivo e
entre as reinicializações do servidor do sistema.
Se vários sensores compartilharem o mesmo tipo de sensor e a mesma propriedade de ativação, o
primeiro sensor da lista será chamado de sensor padrão e será retornado para
apps que usam a função
getDefaultSensor(int sensorType, bool wakeUp).
Lista de estabilidade da lista de sensores
Após uma reinicialização do HAL de sensores, se os dados retornados por getSensorsList() ou
getSensorsList_2_1() indicarem uma mudança significativa em comparação com a lista de sensores
recuperada antes da reinicialização, o framework vai acionar uma reinicialização do
ambiente de execução do Android. Mudanças significativas na lista de sensores incluem casos em que um
sensor com uma determinada alça está ausente ou mudou de atributo ou em que novos
sensores são introduzidos. Embora a reinicialização do ambiente de execução do Android seja prejudicial
ao usuário, ela é necessária porque o framework do Android não pode mais atender ao
contrato da API do Android que sensores estáticos (não dinâmicos) não mudam durante a
duração de um app. Isso também pode impedir que o framework restabeleça
solicitações de sensores ativos feitas por apps. Portanto, os fornecedores de HAL são aconselhados a
evitar mudanças evitáveis na lista de sensores.
Para garantir identificadores de sensores estáveis, o HAL precisa mapear de forma determinística um determinado sensor físico no dispositivo para o identificador. Embora nenhuma implementação específica seja obrigatória pela interface HAL de sensores, os desenvolvedores têm várias opções disponíveis para atender a esse requisito.
Por exemplo, a lista de sensores pode ser classificada usando uma combinação dos atributos fixos de cada sensor, como fornecedor, modelo e tipo de sensor. Outra opção depende
do fato de que o conjunto de sensores estáticos do dispositivo é fixo no hardware. Portanto, o
HAL precisa saber quando todos os sensores esperados concluíram a inicialização antes
de retornar de getSensorsList() ou getSensorsList_2_1(). Essa lista de
sensores esperados pode ser compilada no binário HAL ou armazenada em um
arquivo de configuração no sistema de arquivos, e a ordem de aparição pode ser usada
para extrair identificadores estáveis. Embora a melhor solução dependa dos detalhes específicos
de implementação da HAL, o principal requisito é que os identificadores de sensores
não mudem durante as reinicializações da HAL.
Configurar sensores
Antes de ativar um sensor, ele precisa ser configurado com um período de amostragem
e latência máxima de relatório usando a função batch().
Um sensor precisa ser reconfigurado a qualquer momento usando batch() sem a
perda de dados.
Período de amostragem
O período de amostragem tem um significado diferente com base no tipo de sensor que está sendo configurado:
- Contínuo: os eventos do sensor são gerados em uma taxa contínua.
- On-change: os eventos são gerados mais lentamente do que o período de amostragem e podem ser gerados a uma taxa mais lenta do que o período de amostragem se o valor medido não mudar.
- One-shot: o período de amostragem é ignorado.
- Especial: para mais detalhes, consulte Tipos de sensores.
Para saber mais sobre a interação entre um período de amostragem e os modos de relatório de um sensor, consulte Modos de relatório.
Latência máxima de relatórios
A latência máxima de relatórios define o tempo máximo em nanossegundos que os eventos podem ser atrasados e armazenados no FIFO de hardware antes de serem gravados no FMQ de eventos pelo HAL enquanto o SoC está ativo.
Um valor de zero significa que os eventos precisam ser informados assim que forem medidos, pulando o FIFO completamente ou esvaziando-o assim que um evento do sensor estiver presente no FIFO.
Por exemplo, um acelerômetro ativado a 50 Hz com uma latência máxima de relatório de zero aciona interrupções 50 vezes por segundo quando o SoC está ativo.
Quando a latência máxima de comunicação é maior que zero, os eventos do sensor não precisam ser informados assim que são detectados. Os eventos podem ser armazenados temporariamente no FIFO de hardware e informados em lotes, desde que nenhum evento seja atrasado por mais do que a latência máxima de relatórios. Todos os eventos desde o lote anterior são registrados e retornados de uma só vez. Isso reduz o número de interrupções enviadas ao SoC e permite que o SoC mude para um modo de energia mais baixo enquanto o sensor está capturando e agrupando dados.
Cada evento tem um carimbo de data/hora associado a ele. O atraso no horário em que um evento é informado não pode afetar o carimbo de data/hora do evento. O carimbo de data/hora precisa ser preciso e corresponder ao momento em que o evento ocorreu fisicamente, não ao momento em que foi relatado.
Para mais informações e requisitos sobre como informar eventos de sensor com latência máxima diferente de zero, consulte Processamento em lote.
Ativar sensores
O framework ativa e desativa sensores usando a função activate().
Antes de ativar um sensor, o framework precisa primeiro configurá-lo
usando batch().
Depois que um sensor é desativado, outros eventos desse sensor não podem ser gravados no FMQ de eventos.
Sensores de descarga
Se um sensor estiver configurado para agrupar dados, o framework poderá forçar
um flush imediato de eventos de sensores agrupados chamando flush(). Isso faz com que
os eventos de sensor agrupados para o identificador de sensor especificado sejam gravados imediatamente
na FMQ de eventos. O HAL de sensores precisa anexar um evento de limpeza completo
ao final dos eventos de sensores que são gravados como resultado de uma chamada para
flush().
A limpeza acontece de forma assíncrona (ou seja, essa função precisa retornar imediatamente). Se a implementação usar um único FIFO para vários sensores, esse FIFO será limpo e o evento de conclusão de limpeza será adicionado apenas para o sensor especificado.
Se o sensor especificado não tiver FIFO (nenhum buffer possível) ou se o FIFO estiver
vazio no momento da chamada, flush() ainda precisa ter sucesso e enviar um evento de
limpeza completo para esse sensor. Isso se aplica a todos os sensores, exceto
os one-shot.
Se flush() for chamado para um sensor único, flush() precisará retornar
BAD_VALUE e não gerar um evento de flush completo.
Gravar eventos do sensor no FMQ
O Event FMQ é usado pela HAL de sensores para enviar eventos do sensor ao framework do sensor do Android.
A FMQ de eventos é uma FMQ sincronizada, o que significa que qualquer tentativa de gravar mais eventos na FMQ do que o espaço disponível permite resulta em uma gravação falha. Nesse caso, o HAL precisa determinar se vai gravar o conjunto atual de eventos como dois grupos menores ou se vai gravar todos os eventos juntos quando houver espaço suficiente.
Quando a HAL de sensores grava o número desejado de eventos do sensor na
FMQ de eventos, ela precisa notificar o framework de que os eventos estão prontos
gravando o bit EventQueueFlagBits::READ_AND_PROCESS na função
EventFlag::wake da FMQ de eventos. A flag de evento pode ser criada na FMQ de eventos
usando EventFlag::createEventFlag e a função getEventFlagWord()
da FMQ de eventos.
A Sensors HAL 2.0/2.1 oferece suporte a write e writeBlocking na FMQ de eventos.
A implementação padrão fornece uma referência para usar write. Se a
função writeBlocking for usada, a flag readNotification precisa ser definida como
EventQueueFlagBits::EVENTS_READ, que é definida pelo framework quando ele lê
eventos do FMQ de eventos. A flag de notificação de gravação precisa ser definida como
EventQueueFlagBits::READ_AND_PROCESS, que notifica o framework de que os eventos
foram gravados no FMQ de eventos.
Eventos WAKE_UP
Os eventos WAKE_UP são eventos de sensor que fazem com que o processador do aplicativo (AP, na sigla em inglês)
acorde e processe o evento imediatamente. Sempre que um evento WAKE_UP é gravado
no evento FMQ, a HAL de sensores precisa proteger um wake lock para garantir que o
sistema permaneça ativado até que o framework possa processar o evento. Ao receber um
evento WAKE_UP, o framework protege o próprio wake lock, permitindo que o
HAL de sensores libere o wake lock. Para sincronizar quando a HAL de sensores
liberar o wake lock, use o Wake Lock FMQ.
A HAL de sensores precisa ler o FMQ do Wake Lock para determinar o número de eventos WAKE_UP
que o framework processou. O HAL só vai liberar o bloqueio de ativação
para eventos WAKE_UP se o número total de eventos WAKE_UP não processados for zero.
Depois de processar eventos do sensor, o framework conta o número de eventos que são
marcados como eventos WAKE_UP e grava esse número de volta no FMQ do Wake Lock.
O framework define a notificação de gravação
WakeLockQueueFlagBits::DATA_WRITTEN na FMQ de bloqueio de tela sempre que grava dados nela.
Sensores dinâmicos
Sensores dinâmicos são sensores que não fazem parte física do dispositivo, mas podem ser usados como entrada para o dispositivo, como um gamepad com um acelerômetro.
Quando um sensor dinâmico é conectado, a função onDynamicSensorConnected em
ISensorsCallback precisa ser chamada pelo HAL de sensores. Isso notifica o
framework do novo sensor dinâmico e permite que ele seja controlado
pelo framework e que os eventos do sensor sejam consumidos pelos clientes.
Da mesma forma, quando um sensor dinâmico é desconectado, a
função onDynamicSensorDisconnected em ISensorsCallback precisa ser chamada para
que o framework possa remover qualquer sensor que não esteja mais disponível.
Canal direto
O canal direto é um método de operação em que os eventos do sensor são gravados em
uma memória específica em vez de na FMQ de eventos, ignorando o Android Sensors
Framework. Um cliente que registra um canal direto precisa ler os eventos do sensor
diretamente na memória usada para criar o canal direto e não
receberá os eventos do sensor pelo framework. A função configDirectReport() é semelhante a batch() para operação normal e configura o canal de relatório direto.
As funções registerDirectChannel() e unregisterDirectChannel() criam
ou destroem um novo canal direto.
Modos de operação
A função setOperationMode() permite que o framework configure um sensor
para injetar dados nele. Isso é útil para
testes, especialmente para algoritmos que existem abaixo do framework.
A função injectSensorData() na HAL 2.0 e injectSensorsData_2_1()
na HAL 2.0 normalmente é usada para enviar parâmetros operacionais à
HAL de sensores. A função também pode ser usada para injetar eventos de sensores em um
sensor específico.
Validação
Para validar a implementação da HAL de sensores, execute os testes CTS e VTS de sensores.
Testes CTS
Os testes CTS de sensor existem tanto em testes de CTS automatizados quanto no app manual do CTS Verifier.
Os testes automatizados estão localizados em cts/tests/sensor/src/android/hardware/cts. Esses testes verificam a funcionalidade padrão dos sensores, como ativar sensores, agrupamento e taxas de eventos de sensores.
Os testes do CTS Verifier estão localizados em cts/apps/CtsVerifier/src/com/android/cts/verifier/sensors. Esses testes exigem entrada manual do operador de teste e garantem que os sensores informem valores precisos.
Passar nos testes de CTS é fundamental para garantir que o dispositivo em teste atenda a todos os requisitos do CDD.
Testes VTS
Os testes VTS para sensores HAL 2.0 estão localizados em
hardware/interfaces/sensores/2.0/vts.
Os testes VTS para sensores HAL 2.1 estão localizados em
hardware/interfaces/sensores/2.1/vts.
Esses testes garantem que o HAL de sensores seja implementado corretamente e que todos
os requisitos em ISensors.hal e ISensorsCallback.hal sejam atendidos corretamente.
Fazer upgrade da HAL 2.0 para a Sensors HAL 2.1
Ao fazer upgrade da versão 2.0 para a HAL de sensores, a implementação dela precisa incluir
os métodos initialize_2_1(), getSensorsList_2_1() e injectSensorsData_2_1(),
junto com os tipos de HAL 2.1. Esses métodos precisam atender aos mesmos
requisitos descritos para a HAL 2.0 acima.
Como as HALs de versão secundária precisam oferecer suporte a todas as funções de HALs anteriores, as HALs 2.1 precisam oferecer suporte à inicialização como HALs 2.0. Para evitar a complexidade de oferecer suporte a ambas as versões do HAL, é altamente recomendável usar o Multi-HAL 2.1.
Para conferir um exemplo de como implementar o HAL 2.1 de sensores, consulte Sensors.h.
Fazer upgrade da HAL 1.0 para a 2.0 de sensores
Ao fazer upgrade da HAL 1.0 para a 2.0, verifique se a implementação da HAL atende aos requisitos abaixo.
Inicializar o HAL
A função initialize() precisa ter suporte para estabelecer FMQs entre o
framework e a HAL.
Expor os sensores disponíveis
Na HAL de sensores 2.0, a função getSensorsList() precisa retornar o mesmo valor
durante a inicialização de um único dispositivo, mesmo entre reinicializações da HAL de sensores. Um novo requisito
da função getSensorsList() é que ela precisa retornar o mesmo valor durante
uma única inicialização do dispositivo, mesmo em reinicializações do HAL do Sensor. Isso permite que o
framework tente restabelecer as conexões do sensor se o servidor do sistema
for reiniciado. O valor retornado por getSensorsList() pode mudar depois que o dispositivo
é reinicializado.
Gravar eventos do sensor no FMQ
Em vez de esperar que poll() seja chamado, na HAL de sensores 2.0, a HAL de sensores
precisa gravar proativamente eventos do sensor no FMQ de eventos sempre que esses eventos
estiverem disponíveis. O HAL também é responsável por gravar os bits corretos em
EventFlag para causar uma leitura de FMQ no framework.
Eventos WAKE_UP
Na HAL 1.0 de sensores, a HAL podia liberar o bloqueio de ativação para qualquer evento WAKE_UP
em qualquer chamada subsequente para poll() depois que um WAKE_UP foi postado para
poll(), porque isso indicava que o framework havia processado todos os eventos
do sensor e recebido um bloqueio de ativação, se necessário. Como, na HAL 2.0 de sensores,
a HAL não sabe mais quando o framework processou eventos gravados na
FMQ, a FMQ de bloqueio de desbloqueio permite que o framework se comunique com a HAL quando
ela processa eventos WAKE_UP.
Na HAL 2.0 de sensores, a trava de ativação protegida pela HAL de sensores para eventos WAKE_UP
precisa começar com SensorsHAL_WAKEUP.
Sensores dinâmicos
Os sensores dinâmicos foram retornados usando a função poll() na HAL 1.0 de sensores.
O Sensors HAL 2.0 exige que onDynamicSensorsConnected e
onDynamicSensorsDisconnected em ISensorsCallback sejam chamados sempre que as conexões
dinâmicas de sensores mudarem. Esses callbacks estão disponíveis como parte do
ponteiro ISensorsCallback fornecido pela função initialize().
Modos de operação
O modo DATA_INJECTION para sensores WAKE_UP precisa ter suporte na HAL
2.0 de sensores.
Suporte a vários HALs
As HALs 2.0 e 2.1 de sensores oferecem suporte a várias HALs usando o framework de Sensores Multi-HAL. Para detalhes de implementação, consulte Portar da HAL 1.0 de sensores.