Sensores HAL 2

A camada de abstração de hardware dos sensores (HAL) é a interface entre a estrutura do sensor 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.

O Sensors HAL 2.0 está disponível no Android 10 e superior para dispositivos novos e atualizados. O Sensors HAL 2.0 é baseado no Sensors HAL 1.0 , mas possui 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 do sensor Android.

O Sensors HAL 2.1 está disponível no Android 11 e superior para dispositivos novos e atualizados. O Sensors HAL 2.1 é uma iteração do 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 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 Sensors 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 FMQ de evento usado para gravar eventos de 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 os Sensores HAL.

Expor 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 mudar 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 uma reinicialização do Sensors HAL, 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 com atributos alterados, ou onde novos sensores são introduzidos. Embora a reinicialização do tempo de execução do Android seja prejudicial para o usuário, ela é necessária 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 o tempo de vida de um aplicativo. Isso também pode impedir que a estrutura restabeleça as solicitações ativas do sensor feitas pelos 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 de forma determinística 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 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 aparência pode ser usada para derivar alças 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 entre as 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 a 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.
  • Na mudança: 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 mudar.
  • 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 que os eventos podem ser atrasados ​​e armazenados no hardware FIFO antes de serem gravados no FMQ de evento por meio do HAL enquanto o SoC está ativo.

Um valor zero significa que os eventos devem ser relatados assim que forem medidos, ignorando o FIFO completamente ou esvaziando o FIFO 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órios de zero gatilhos interrompe 50 vezes por segundo quando o SoC está ativo.

Quando a latência máxima de relatório é maior que zero, os eventos do sensor não precisam ser relatados assim que são detectados. Os eventos podem ser armazenados temporariamente no hardware FIFO 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 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. Atrasar o horário 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 adicionais e requisitos sobre como relatar eventos do sensor com latência de relatório máxima diferente de zero, consulte Lotes .

Ativando sensores

A estrutura ativa e desativa os sensores usando a função activate() . Antes de ativar um sensor, o framework deve primeiro configurar o sensor usando batch() .

Após a desativação de um sensor, eventos de sensor adicionais desse sensor não devem ser gravados no FMQ de evento.

Sensores de descarga

Se um sensor estiver configurado para dados do sensor em lote, a estrutura pode 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 FMQ de evento. 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 liberação ocorre 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 flush complete 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 deverá ter sucesso e enviar um evento flush complete para esse sensor. Isso se aplica a todos os sensores, exceto 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 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 Android.

O FMQ de evento é 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 falha na gravação. 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 de 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 write e writeBlocking no FMQ de evento. A implementação padrão fornece uma referência para usar write . Se a função writeBlocking for usada, o sinalizador readNotification deverá 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

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 ativo até que a estrutura possa lidar com o evento. Ao receber um evento WAKE_UP , a estrutura protege seu próprio wake lock, permitindo que o Sensor HAL libere seu wake lock. Para sincronizar quando o Sensor HAL libera 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 ele 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 a partir do Sensors HAL. Isso notifica a estrutura do novo sensor dinâmico e permite que o sensor seja controlado por meio da estrutura 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 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 no FMQ do evento, ignorando o Android Sensors Framework. Um cliente que cadastra um canal direto deve ler os eventos do sensor diretamente da memória que foi utilizada 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 a estrutura configure um sensor para que a estrutura 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 do Sensors HAL, execute os testes de sensor CTS e VTS.

testes CTS

Os testes CTS do sensor existem em testes CTS automatizados e 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 sensores de ativação, 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.

Passar nos testes 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/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 Sensors HAL 2.1 de 2.0, sua implementação HAL deve incluir os métodos initialize_2_1() , getSensorsList_2_1() e injectSensorsData_2_1() , junto 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 oferecer suporte a todas as funções dos HALs anteriores, os HALs 2.1 devem oferecer 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 seu próprio Sensors 2.1 HAL, consulte Sensors.h .

Atualizando para Sensores HAL 2.0 de 1.0

Ao atualizar para Sensors 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.

Expor 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 do Sensor 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 após a reinicialização do dispositivo.

Gravando eventos do sensor no FMQ

Em vez de esperar que poll() seja chamado, no Sensors HAL 2.0, o Sensors HAL deve gravar proativamente os eventos do sensor no Event FMQ sempre que os eventos do sensor estiverem disponíveis. O HAL também é responsável por gravar os bits corretos no EventFlag para causar uma leitura de FMQ dentro da estrutura.

eventos WAKE_UP

No Sensors HAL 1.0, o HAL foi capaz de liberar seu wake lock para qualquer evento WAKE_UP em qualquer chamada subseqüente para poll() depois que um WAKE_UP foi postado para poll() porque isso indicava que a estrutura processou todos os eventos do sensor e obteve um wake lock, se necessário. Como, no Sensors HAL 2.0, o HAL não sabe mais quando o framework processou eventos gravados no FMQ, o Wake Lock FMQ permite que o framework se comunique com o HAL quando tiver manipulado eventos WAKE_UP .

Em Sensores HAL 2.0, o wake lock protegido pelos Sensores 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() no Sensors HAL 1.0. O Sensors HAL 2.0 requer que onDynamicSensorsConnected e onDynamicSensorsDisconnected em ISensorsCallback sejam chamados sempre que as conexões do sensor dinâmico forem alteradas. 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 obter detalhes de implementação, consulte Porting from Sensors HAL 1.0 .