A partir de 27 de março de 2025, recomendamos usar android-latest-release em vez de aosp-main para criar e contribuir com o AOSP. Para mais informações, consulte Mudanças no AOSP.

Esta página foi traduzida pela API Cloud Translation.

HIDL

A linguagem de definição de interface HAL ou HIDL (pronuncia-se "hide-l") é uma linguagem de descrição de interface (IDL) para especificar a interface entre um HAL e seus usuários. Permite especificar tipos e chamadas de métodos, coletados em interfaces e pacotes. Mais amplamente, HIDL é um sistema para comunicação entre bases de código que podem ser compiladas independentemente. A partir do Android 10, o HIDL está obsoleto e o Android está migrando para usar o AIDL em todos os lugares.

O HIDL destina-se a ser usado para comunicação entre processos (IPC). A comunicação entre processos é chamada de Binderizada . Para bibliotecas que devem ser vinculadas a um processo, um modo de passagem também está disponível (não suportado em Java).

HIDL especifica estruturas de dados e assinaturas de métodos, organizadas em interfaces (semelhantes a uma classe) que são coletadas em pacotes. A sintaxe do HIDL parecerá familiar para programadores C++ e Java, embora com um conjunto diferente de palavras-chave. O HIDL também usa anotações no estilo Java.

Projeto HIDL

O objetivo do HIDL é que a estrutura possa ser substituída sem ter que reconstruir HALs. Os HALs serão construídos por fornecedores ou fabricantes de SOC e colocados em uma partição /vendor no dispositivo, permitindo que o framework, em sua própria partição, seja substituído por um OTA sem recompilar os HALs.

O projeto HIDL equilibra as seguintes preocupações:

Interoperabilidade . Crie interfaces interoperáveis de forma confiável entre processos que podem ser compilados com várias arquiteturas, cadeias de ferramentas e configurações de compilação. As interfaces HIDL são versionadas e não podem ser alteradas após serem publicadas.
Eficiência . HIDL tenta minimizar o número de operações de cópia. Os dados definidos por HIDL são entregues ao código C++ em estruturas de dados de layout padrão C++ que podem ser usadas sem descompactar. O HIDL também fornece interfaces de memória compartilhada e, como os RPCs são inerentemente lentos, o HIDL suporta duas maneiras de transferir dados sem usar uma chamada RPC: memória compartilhada e uma fila de mensagens rápidas (FMQ).
Intuitivo . HIDL evita questões espinhosas de propriedade de memória usando apenas in parâmetros para RPC (veja Android Interface Definition Language (AIDL) ); valores que não podem ser retornados com eficiência de métodos são retornados por meio de funções de retorno de chamada. Nem passar dados para HIDL para transferência nem receber dados de HIDL altera a propriedade dos dados — a propriedade sempre permanece com a função de chamada. Os dados precisam persistir apenas pela duração da função chamada e podem ser destruídos imediatamente após o retorno da função chamada.

Usando o modo de passagem

Para atualizar dispositivos que executam versões anteriores do Android para o Android O, você pode agrupar HALs convencionais (e legadas) em uma nova interface HIDL que atende a HAL nos modos binderized e mesmo processo (passthrough). Esse encapsulamento é transparente tanto para o HAL quanto para a estrutura do Android.

O modo de passagem está disponível apenas para clientes e implementações C++. Os dispositivos que executam versões anteriores do Android não têm HALs escritas em Java, portanto, as HALs Java são inerentemente vinculadas.

Quando um arquivo .hal é compilado, hidl-gen produz um arquivo de cabeçalho de passagem extra BsFoo.h , além dos cabeçalhos usados para comunicação de fichário; este cabeçalho define as funções a serem dlopen ed. Como as HALs de passagem são executadas no mesmo processo em que são chamadas, na maioria dos casos, os métodos de passagem são invocados por chamada direta de função (mesma thread). Métodos oneway são executados em seu próprio encadeamento, pois não se destinam a aguardar o HAL processá-los (isso significa que qualquer HAL que usa métodos oneway no modo de passagem deve ser thread-safe).

Dado um IFoo.hal , BsFoo.h encapsula os métodos gerados por HIDL para fornecer recursos adicionais (como fazer transações oneway executadas em outro thread). Este arquivo é semelhante ao BpFoo.h , porém em vez de passar as chamadas IPC usando o binder, as funções desejadas são invocadas diretamente. Futuras implementações de HALs podem fornecer várias implementações, como FooFast HAL e FooAccurate HAL. Nesses casos, seria criado um arquivo para cada implementação adicional (por exemplo, PTFooFast.cpp e PTFooAccurate.cpp ).

Como vincular HALs de passagem

Você pode vincular implementações de HAL que dão suporte ao modo de passagem. Dada uma interface HAL abcd@MN::IFoo , dois pacotes são criados:

abcd@MN::IFoo-impl . Contém a implementação do HAL e expõe a função IFoo* HIDL_FETCH_IFoo(const char* name) . Em dispositivos legados, este pacote é HIDL_FETCH_IFoo dlopen Você pode gerar o código base usando hidl-gen e -Lc++-impl e -Landroidbp-impl .
abcd@MN::IFoo-service . Abre o HAL de passagem e se registra como um serviço vinculado, permitindo que a mesma implementação de HAL seja usada como passagem e vinculada.

Dado o tipo IFoo , você pode chamar sp<IFoo> IFoo::getService(string name, bool getStub) para obter acesso a uma instância de IFoo . Se getStub for true, getService tentará abrir o HAL somente no modo de passagem. Se getStub for false, getService tentará localizar um serviço vinculado; se isso falhar, ele tenta localizar o serviço de passagem. O parâmetro getStub nunca deve ser usado, exceto em defaultPassthroughServiceImplementation . (Os dispositivos iniciados com o Android O são dispositivos totalmente vinculados, portanto, a abertura de um serviço no modo de passagem não é permitida.)

Gramática HIDL

Por design, a linguagem HIDL é semelhante a C (mas não usa o pré-processador C). Toda pontuação não descrita abaixo (além do uso óbvio de = e | ) faz parte da gramática.

Observação: para obter detalhes sobre o estilo de código HIDL, consulte o Guia de estilo de código .

/** */ indica um comentário de documentação. Eles podem ser aplicados apenas a declarações de tipo, método, campo e valor de enumeração.
/* */ indica um comentário de várias linhas.
// indica um comentário no final da linha. Além de // , as novas linhas são iguais a qualquer outro espaço em branco.
Na gramática de exemplo abaixo, o texto de // até o final da linha não faz parte da gramática, mas sim um comentário sobre a gramática.
[empty] significa que o termo pode estar vazio.
? seguir um literal ou termo significa que é opcional.
... indica sequência contendo zero ou mais itens com pontuação de separação conforme indicado. Não há argumentos variáveis em HIDL.
Vírgulas separam os elementos de sequência.
O ponto e vírgula termina cada elemento, incluindo o último elemento.
MAIÚSCULAS é um não-terminal.
italics é uma família de tokens, como integer ou identifier (regras de análise C padrão).
constexpr é uma expressão constante de estilo C (como 1 + 1 e 1L << 3 ).
import_name é um nome de pacote ou interface, qualificado conforme descrito em HIDL Versioning .
words minúsculas são tokens literais.

Exemplo:

ROOT =
    PACKAGE IMPORTS PREAMBLE { ITEM ITEM ... }  // not for types.hal
  | PACKAGE IMPORTS ITEM ITEM...  // only for types.hal; no method definitions

ITEM =
    ANNOTATIONS? oneway? identifier(FIELD, FIELD ...) GENERATES?;
  |  safe_union identifier { UFIELD; UFIELD; ...};
  |  struct identifier { SFIELD; SFIELD; ...};  // Note - no forward declarations
  |  union identifier { UFIELD; UFIELD; ...};
  |  enum identifier: TYPE { ENUM_ENTRY, ENUM_ENTRY ... }; // TYPE = enum or scalar
  |  typedef TYPE identifier;

VERSION = integer.integer;

PACKAGE = package android.hardware.identifier[.identifier[...]]@VERSION;

PREAMBLE = interface identifier EXTENDS

EXTENDS = <empty> | extends import_name  // must be interface, not package

GENERATES = generates (FIELD, FIELD ...)

// allows the Binder interface to be used as a type
// (similar to typedef'ing the final identifier)
IMPORTS =
   [empty]
  |  IMPORTS import import_name;

TYPE =
  uint8_t | int8_t | uint16_t | int16_t | uint32_t | int32_t | uint64_t | int64_t |
 float | double | bool | string
|  identifier  // must be defined as a typedef, struct, union, enum or import
               // including those defined later in the file
|  memory
|  pointer
|  vec<TYPE>
|  bitfield<TYPE>  // TYPE is user-defined enum
|  fmq_sync<TYPE>
|  fmq_unsync<TYPE>
|  TYPE[SIZE]

FIELD =
   TYPE identifier

UFIELD =
   TYPE identifier
  |  safe_union identifier { FIELD; FIELD; ...} identifier;
  |  struct identifier { FIELD; FIELD; ...} identifier;
  |  union identifier { FIELD; FIELD; ...} identifier;

SFIELD =
   TYPE identifier
  |  safe_union identifier { FIELD; FIELD; ...};
  |  struct identifier { FIELD; FIELD; ...};
  |  union identifier { FIELD; FIELD; ...};
  |  safe_union identifier { FIELD; FIELD; ...} identifier;
  |  struct identifier { FIELD; FIELD; ...} identifier;
  |  union identifier { FIELD; FIELD; ...} identifier;

SIZE =  // Must be greater than zero
     constexpr

ANNOTATIONS =
     [empty]
  |  ANNOTATIONS ANNOTATION

ANNOTATION =
  |  @identifier
  |  @identifier(VALUE)
  |  @identifier(ANNO_ENTRY, ANNO_ENTRY  ...)

ANNO_ENTRY =
     identifier=VALUE

VALUE =
     "any text including \" and other escapes"
  |  constexpr
  |  {VALUE, VALUE ...}  // only in annotations

ENUM_ENTRY =
     identifier
  |  identifier = constexpr

Terminologia

Esta seção usa os seguintes termos relacionados ao HIDL:

encadernado	Indica que o HIDL está sendo usado para chamadas de procedimento remoto entre processos, implementado em um mecanismo do tipo Binder. Consulte também passagem .
retorno de chamada, assíncrono	Interface servida por um usuário HAL, passada para o HAL (através de um método HIDL) e chamada pelo HAL para retornar dados a qualquer momento.
retorno de chamada, síncrono	Retorna dados da implementação do método HIDL de um servidor para o cliente. Não usado para métodos que retornam void ou um único valor primitivo.
cliente	Processo que chama métodos de uma determinada interface. Um processo HAL ou framework pode ser um cliente de uma interface e um servidor de outra. Consulte também passagem .
estende	Indica uma interface que adiciona métodos e/ou tipos a outra interface. Uma interface pode estender apenas uma outra interface. Pode ser usado para um incremento de versão menor no mesmo nome de pacote ou para um novo pacote (por exemplo, uma extensão de fornecedor) para construir em um pacote mais antigo.
gera	Indica um método de interface que retorna valores ao cliente. Para retornar um valor não primitivo ou mais de um valor, uma função de retorno de chamada síncrona é gerada.
interface	Coleção de métodos e tipos. Traduzido em uma classe em C++ ou Java. Todos os métodos em uma interface são chamados na mesma direção: um processo cliente invoca métodos implementados por um processo servidor.
mão única	Quando aplicado a um método HIDL, indica que o método não retorna valores e não bloqueia.
pacote	Coleção de interfaces e tipos de dados que compartilham uma versão.
atravessar	Modo de `dlopen` em que o servidor é uma biblioteca compartilhada, aberta pelo cliente. No modo de passagem, cliente e servidor são o mesmo processo, mas bases de código separadas. Usado apenas para trazer bases de código legadas para o modelo HIDL. Consulte também Encadernado .
servidor	Processo que implementa métodos de uma interface. Consulte também passagem .
transporte	Infraestrutura HIDL que move dados entre o servidor e o cliente.
versão	Versão de um pacote. Consiste em dois inteiros, maior e menor. Incrementos de versão menores podem adicionar (mas não alterar) tipos e métodos.

HIDL Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.