A camada de abstração de hardware de sensores (HAL) é a interface entre a estrutura de sensores do Android e os sensores de um dispositivo, como um acelerômetro ou giroscópio. O Sensors HAL define as funções que devem ser implementadas para permitir que o framework controle os sensores.
Sensores HAL 2.0 está disponível no Android 10 e superior para dispositivos novos e atualizados. Sensores HAL 2.0 é baseado em Sensores HAL 1.0 , mas tem várias diferenças importantes, que o impedem de ser compatível com versões anteriores. Sensores HAL 2.0 usa Fast Message Queues (FMQs) para enviar eventos de sensor do HAL para a estrutura de sensores do Android.
Sensores HAL 2.1 está disponível no Android 11 e superior para dispositivos novos e atualizados. Sensores HAL 2.1 é uma iteração dos Sensores HAL 2.0 que expõe o tipo de sensor HIGE_ANGLE e atualiza vários métodos para aceitar o tipo HINGE_ANGLE .
Interface HAL 2.1
A principal fonte de documentação para Sensores HAL 2.1 está dentro da definição 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 para Sensores HAL 2.0 está dentro da definição 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 .
Implementando Sensores HAL 2.0 e HAL 2.1
Para implementar os Sensores HAL 2.0 ou 2.1, um objeto deve estender a interface ISensors e implementar todas as funções definidas em 2.0/ISensors.hal ou 2.1/ISensors.hal .
Inicializando o HAL
O Sensors HAL deve ser inicializado pela estrutura do sensor Android antes de poder ser usado. A estrutura chama a função initialize() para HAL 2.0 e a função initialize_2_1() para HAL 2.1 para fornecer três parâmetros para o Sensors HAL: dois descritores FMQ e um ponteiro para um objeto ISensorsCallback .
O HAL usa o primeiro descritor para criar o Event FMQ usado para gravar eventos do sensor na estrutura. O HAL usa o segundo descritor para criar o Wake Lock FMQ usado para sincronizar quando o HAL libera seu wake lock para eventos do sensor WAKE_UP . O HAL deve salvar um ponteiro para o objeto ISensorsCallback para que quaisquer funções de retorno de chamada necessárias possam ser invocadas.
A função initialize() ou initialize_2_1() deve ser a primeira função chamada ao inicializar a HAL dos Sensores.
Expondo os sensores disponíveis
Para obter 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 por seu identificador. O identificador de um determinado sensor não deve ser alterado quando o processo que hospeda o Sensors HAL é reiniciado. Os identificadores podem mudar nas reinicializações do dispositivo e nas reinicializações do servidor do sistema.
Se vários sensores compartilharem o mesmo tipo de sensor e propriedade de ativação, o primeiro sensor na lista será chamado de sensor padrão e será retornado aos aplicativos que utilizam a função getDefaultSensor(int sensorType, bool wakeUp) .
Estabilidade da lista de sensores
Após a reinicialização de uma HAL de sensores, se os dados retornados por getSensorsList() ou getSensorsList_2_1() indicarem uma alteração significativa em comparação com a lista de sensores recuperada antes da reinicialização, a estrutura acionará uma reinicialização do tempo de execução do Android. Mudanças significativas na lista de sensores incluem casos em que um sensor com um determinado identificador está ausente ou mudou de atributos, ou onde novos sensores são introduzidos. Embora a reinicialização do tempo de execução do Android seja disruptiva para o usuário, isso é necessário porque a estrutura do Android não pode mais atender ao contrato da API do Android de que os sensores estáticos (não dinâmicos) não mudam durante a vida útil de um aplicativo. Isso também pode impedir que a estrutura restabeleça solicitações de sensores ativas feitas por aplicativos. Portanto, os fornecedores de HAL são aconselhados a evitar alterações evitáveis na lista de sensores.
Para garantir alças de sensor estáveis, o HAL deve mapear deterministicamente um determinado sensor físico no dispositivo para sua alça. Embora nenhuma implementação específica seja exigida pela interface Sensors HAL, 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 se baseia no 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 aparecimento pode ser usada para derivar identificadores estáveis. Embora a melhor solução dependa dos detalhes de implementação específicos do seu HAL, o principal requisito é que os identificadores do sensor não mudem nas reinicializações do HAL.
Configurando sensores
Antes de um sensor ser ativado, o sensor deve ser configurado com um período de amostragem e latência máxima de relatório usando a função batch() .
Um sensor deve poder ser reconfigurado a qualquer momento usando batch() sem perda de dados do sensor.
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 não são gerados mais rapidamente 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 for alterado.
- One-shot: O período de amostragem é ignorado.
- Especial: Para obter 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ório define o tempo máximo em nanossegundos em que os eventos podem ser atrasados e armazenados no FIFO de hardware antes de serem gravados no Event FMQ por meio do HAL enquanto o SoC está ativo.
Um valor de zero significa que os eventos devem ser relatados assim que forem medidos, pulando o FIFO completamente ou esvaziando o FIFO assim que um evento do sensor estiver presente no FIFO.
Por exemplo, um acelerômetro ativado em 50 Hz com latência máxima de relatório de zero aciona interrupções 50 vezes por segundo quando o SoC está ativado.
Quando a latência máxima de relatório for maior que zero, os eventos do sensor não precisam ser relatados assim que forem detectados. Os eventos podem ser armazenados temporariamente no FIFO de hardware e relatados em lotes, desde que nenhum evento seja atrasado por mais do que a latência máxima de relatório. Todos os eventos desde o lote anterior são registrados e devolvidos de uma só vez. Isso reduz o número de interrupções enviadas ao SoC e permite que o SoC alterne para um modo de energia mais baixo enquanto o sensor está capturando e agrupando dados.
Cada evento tem um timestamp associado a ele. Atrasar a hora em que um evento é relatado não deve afetar o carimbo de data/hora do evento. O carimbo de data/hora deve ser preciso e corresponder à hora em que o evento aconteceu fisicamente, não à hora em que foi relatado.
Para obter informações e requisitos adicionais sobre como relatar eventos do sensor com latência máxima de relatório diferente de zero, consulte Lotes .
Ativando sensores
A estrutura habilita e desabilita os sensores usando a função activate() . Antes de ativar um sensor, a estrutura deve primeiro configurar o sensor usando batch() .
Depois que um sensor é desativado, eventos de sensor adicionais desse sensor não devem ser gravados no Event FMQ.
Sensores de lavagem
Se um sensor estiver configurado para dados de sensor em lote, a estrutura poderá forçar uma liberação imediata de eventos de sensor em lote chamando flush() . Isso faz com que os eventos de sensor em lote para o identificador de sensor especificado sejam gravados imediatamente no Event FMQ. O Sensors HAL deve anexar um evento flush complete ao final dos eventos do sensor que são gravados como resultado de uma chamada para flush() .
A descarga acontece de forma assíncrona (ou seja, essa função deve retornar imediatamente). Se a implementação usar um único FIFO para vários sensores, esse FIFO será liberado e o evento de liberação completa será adicionado apenas para o sensor especificado.
Se o sensor especificado não tiver FIFO (sem buffering possível), ou se o FIFO estava vazio no momento da chamada, flush() ainda deve ser bem-sucedido e enviar um evento de flush complete para esse sensor. Isso se aplica a todos os sensores que não sejam sensores de disparo único.
Se flush() for chamado para um sensor one-shot, então flush() deve retornar BAD_VALUE e não gerar um evento de flush complete.
Gravando eventos do sensor no FMQ
O Event FMQ é usado pelo Sensors HAL para enviar eventos do sensor para a estrutura do sensor do Android.
O FMQ de eventos é um FMQ sincronizado, o que significa que qualquer tentativa de gravar mais eventos no FMQ do que o espaço disponível permite resultará em uma gravação com falha. Nesse caso, o HAL deve determinar se deve gravar o conjunto atual de eventos como dois grupos menores de eventos ou gravar todos os eventos juntos quando houver espaço suficiente disponível.
Quando o Sensors HAL tiver gravado o número desejado de eventos do sensor no Event FMQ, o Sensors HAL deve notificar a estrutura de que os eventos estão prontos gravando o bit EventQueueFlagBits::READ_AND_PROCESS na função EventFlag::wake do Event FMQ. O EventFlag pode ser criado a partir do Event FMQ usando EventFlag::createEventFlag e a função getEventFlagWord() do Event FMQ.
Sensores HAL 2.0/2.1 suporta tanto write quanto writeBlocking no Event FMQ. A implementação padrão fornece uma referência para usar write . Se a função writeBlocking for usada, o sinalizador readNotification deve ser definido como EventQueueFlagBits::EVENTS_READ , que é definido pela estrutura ao ler eventos do Event FMQ. O sinalizador de notificação de gravação deve ser definido como EventQueueFlagBits::READ_AND_PROCESS , que notifica a estrutura de que os eventos foram gravados no Event FMQ.
Eventos WAKE_UP
Os eventos WAKE_UP são eventos de sensor que fazem com que o processador de aplicativos (AP) acorde e trate o evento imediatamente. Sempre que um evento WAKE_UP é gravado no Event FMQ, o Sensors HAL deve proteger um wake lock para garantir que o sistema permaneça acordado até que a estrutura possa manipular o evento. Ao receber um evento WAKE_UP , o framework protege seu próprio wake lock, permitindo que o Sensors HAL libere seu wake lock. Para sincronizar quando o Sensors HAL liberar seu wake lock, use o Wake Lock FMQ.
O Sensors HAL deve ler o Wake Lock FMQ para determinar o número de eventos WAKE_UP que a estrutura tratou. O HAL só deve liberar seu wake lock para eventos WAKE_UP se o número total de eventos WAKE_UP não tratados for zero. Depois de manipular os eventos do sensor, a estrutura conta o número de eventos marcados como eventos WAKE_UP e grava esse número de volta no Wake Lock FMQ.
A estrutura define a notificação de gravação WakeLockQueueFlagBits::DATA_WRITTEN no Wake Lock FMQ sempre que grava dados no Wake Lock FMQ.
Sensores dinâmicos
Sensores dinâmicos são sensores que não fazem parte fisicamente 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 deve ser chamada do Sensors HAL. Isso notifica o framework do novo sensor dinâmico e permite que o sensor seja controlado através do 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 deve ser chamada para que a estrutura 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 no Event FMQ ignorando o Android Sensors Framework. Um cliente que registra um canal direto deve ler os eventos do sensor diretamente da memória que foi usada para criar o canal direto e não receberá os eventos do sensor por meio do framework. A função configDirectReport() é semelhante a batch() para operação normal e configura o canal de reporte 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 que o framework possa injetar dados do sensor no sensor. Isso é útil para testes, especialmente para algoritmos que existem abaixo da estrutura.
A função injectSensorData() no HAL 2.0 e a função injectSensorsData_2_1() no HAL 2.0 são normalmente usadas para enviar parâmetros operacionais para os Sensores HAL. A função também pode ser usada para injetar eventos de sensor em um sensor específico.
Validação
Para validar sua implementação dos Sensores HAL, execute os testes do sensor CTS e VTS.
Testes CTS
Os testes CTS do sensor existem tanto nos testes CTS automatizados quanto no aplicativo CTS Verifier manual.
Os testes automatizados estão localizados em cts/tests/sensor/src/android/hardware/cts . Esses testes verificam a funcionalidade padrão dos sensores, como ativação de sensores, lotes e taxas de eventos do sensor.
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 relatem valores precisos.
A aprovação nos testes CTS é fundamental para garantir que o dispositivo em teste atenda a todos os requisitos de CDD.
Testes VTS
Os testes VTS para Sensores HAL 2.0 estão localizados em hardware/interfaces/sensors/2.0/vts . Os testes VTS para Sensores HAL 2.1 estão localizados em hardware/interfaces/sensors/2.1/vts . Esses testes garantem que o Sensors HAL seja implementado corretamente e que todos os requisitos dentro de ISensors.hal e ISensorsCallback.hal sejam atendidos adequadamente.
Atualizando para Sensores HAL 2.1 de 2.0
Ao atualizar para Sensores HAL 2.1 de 2.0, sua implementação de HAL deve incluir os métodos initialize_2_1() , getSensorsList_2_1() e injectSensorsData_2_1() , juntamente com os tipos HAL 2.1. Esses métodos devem atender aos mesmos requisitos descritos para HAL 2.0 acima.
Como os HALs de versão secundária devem dar suporte a todas as funções de HALs anteriores, os HALs 2.1 devem dar suporte à inicialização como HALs 2.0. Para evitar a complexidade de suportar ambas as versões HAL, é altamente recomendável usar o Multi-HAL 2.1.
Para obter um exemplo de como implementar seus próprios Sensors 2.1 HAL, consulte Sensors.h .
Atualizando para Sensores HAL 2.0 de 1.0
Ao atualizar para Sensores HAL 2.0 de 1.0, certifique-se de que sua implementação HAL atenda aos seguintes requisitos.
Inicializando o HAL
A função initialize() deve ser suportada para estabelecer FMQs entre a estrutura e o HAL.
Expondo os sensores disponíveis
No Sensors HAL 2.0, a função getSensorsList() deve retornar o mesmo valor durante a inicialização de um único dispositivo, mesmo nas reinicializações do Sensors HAL. Um novo requisito da função getSensorsList() é que ela deve retornar o mesmo valor durante a inicialização de um único dispositivo, mesmo nas reinicializações de Sensores HAL. Isso permite que a estrutura 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 executa uma reinicialização.
Gravando eventos do sensor no FMQ
Em vez de esperar que poll() seja chamado, no Sensors HAL 2.0, o Sensors HAL deve gravar eventos de sensor proativamente no Event FMQ sempre que eventos de sensor estiverem disponíveis. O HAL também é responsável por gravar os bits corretos no EventFlag para causar uma leitura FMQ dentro da estrutura.
Eventos WAKE_UP
Nos Sensores HAL 1.0, o HAL foi capaz de liberar seu wake lock para qualquer evento WAKE_UP em qualquer chamada subsequente para poll() depois que um WAKE_UP foi postado em poll() porque isso indicava que a estrutura havia processado todos os eventos do sensor e obtido um wake lock, se necessário. Como, nos Sensores HAL 2.0, o HAL não sabe mais quando a estrutura processou eventos gravados no FMQ, o Wake Lock FMQ permite que a estrutura se comunique com o HAL quando tiver manipulado eventos WAKE_UP .
No Sensors HAL 2.0, o wake lock protegido pelo Sensors HAL para eventos WAKE_UP deve começar com SensorsHAL_WAKEUP .
Sensores dinâmicos
Os sensores dinâmicos foram retornados usando a função poll() em Sensores HAL 1.0. Sensores HAL 2.0 requer que onDynamicSensorsConnected e onDynamicSensorsDisconnected em ISensorsCallback sejam chamados sempre que as conexões do sensor dinâmico mudarem. Esses retornos de chamada estão disponíveis como parte do ponteiro ISensorsCallback fornecido por meio da função initialize() .
Modos de operação
O modo DATA_INJECTION para sensores WAKE_UP deve ser suportado em Sensores HAL 2.0.
Suporte multi-HAL
Os sensores HAL 2.0 e 2.1 suportam multi-HAL usando a estrutura Sensors Multi-HAL . Para detalhes de implementação, consulte Portabilidade de Sensores HAL 1.0 .