HAL de rádio de transmissão

As seções a seguir descrevem como trabalhar com a camada de abstração de hardware (HAL, na sigla em inglês) para implementar o rádio de transmissão.

Interface HAL de rádio de transmissão

A HAL de rádio de transmissão fornece estruturas de dados e interfaces no nível do hardware para implementar rádio de transmissão, como rádio AM/FM e DAB.

Interfaces HIDL 2.0 e AIDL

O HAL de rádio usa as interfaces descritas nas seções a seguir.

IAnnouncementListener

IAnnouncementListener é a interface de callback para o listener de anúncios, que pode ser registrado no HAL de rádio de transmissão para receber anúncios. A interface tem os seguintes métodos:

IAnnouncementListener
Descrição:chamado sempre que a lista de anúncios muda.
	HIDL 2.0	oneway onListUpdated(vec<Announcement> announcements)
	AIDL	oneway void onListUpdated(in Announcement[] announcements)

ICloseHandle

ICloseHandle é o manipulador de fechamento genérico para remover um callback que não precisa de uma interface ativa.

ICloseHandle
Descrição:feche o handle.
	HIDL 2.0	close()
	AIDL	void close()

ITunerCallback

ITunerCallback é a interface de callback chamada pelo HAL da rádio de transmissão para enviar atualizações ao serviço de cliente HAL.

ITunerCallback
Descrição:chamada pela HAL quando uma operação de ajuste (ajuste, busca (em AIDL) ou verificação (em HIDL) e etapa bem-sucedida) falha de forma assíncrona.
	HIDL 2.0	oneway onCurrentProgramInfoChanged(ProgramInfo info)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
Descrição:chamado quando o ajuste, a busca (em AIDL) ou a verificação (em HIDL) ou a etapa são concluídos.
	HIDL 2.0	oneway onTuneFailed(Result result, ProgramSelector selector)
	AIDL	void onTuneFailed(in Result result, in ProgramSelector selector)
Descrição:chamado quando o ajuste, a busca (em AIDL) ou a verificação (em HIDL) ou a etapa são concluídos.
	HIDL 2.0	oneway onCurrentProgramInfoChanged(ProgramInfo info)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
Descrição:chamada quando a lista de programas é atualizada. O tamanho de cada bloco deve ser limitado a 500 kiB.
	HIDL 2.0	oneway onProgramListUpdated(ProgramListChunk chunk)
	AIDL	void onProgramListUpdated(ProgramListChunk chunk)
Descrição:chamado quando a antena é conectada ou desconectada.
	HIDL 2.0	oneway onAntennaStateChange(bool connected)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
Descrição:chamada quando os valores de parâmetro específicos do fornecedor são atualizados internamente na HAL. Não invoque após chamar setParameters pelo cliente HAL.
	HIDL 2.0	oneway onParametersUpdated(vec<VendorKeyValue> parameters)
	AIDL	void onParametersUpdated(in VendorKeyValue[] parameters)
Descrição:novidade no AIDL. Chamado quando a flag de configuração é atualizada internamente na HAL (não deve ser invocada depois de chamar setConfigFlag pelo cliente HAL).
	HIDL 2.0	Não aplicável.
	AIDL	void onConfigFlagUpdated(in ConfigFlag flag, in boolean value)

IBroadcastRadio

IBroadcastRadio é a interface principal da HAL de rádio de transmissão. No HAL 2.0 do HIDL, use a interface ITunerSession para o sintonizador chamar operações. No entanto, no máximo um sintonizador fica ativo por vez, desde que cada instância do HAL de rádio de transmissão tenha apenas um chip de sintonizador. ITunerSession foi removido das interfaces AIDL, e as interfaces dele foram movidas para IBroadcastRadio.

IBroadcastRadio
Descrição:recebe a descrição de um módulo e os recursos dele.
	HIDL 2.0	getProperties() generates (Properties properties)
	AIDL	Properties getProperties()
Descrição:busca a configuração atual ou possível da região de AM/FM.
	HIDL 2.0	getAmFmRegionConfig(bool full) generates (Result result, AmFmRegionConfig config)
	AIDL	AmFmRegionConfig getAmFmRegionConfig(bool full)
Descrição:busca a configuração atual da região do DAB.
	HIDL 2.0	getDabRegionConfig() generates (Result result, vec<DabTableEntry> config)
	AIDL	DabTableEntry[] getDabRegionConfig()
Descrição:recebe uma imagem do cache do módulo de rádio. Em AIDL, o tamanho da imagem precisa ser menor que 1 MB devido a um limite rígido no buffer de transação do binder.
	HIDL 2.0	getImage(uint32_t id) generates (vec<uint8_t> image)
	AIDL	byte[] getImage(in int id)
Descrição:registra o listener de anúncio.
	HIDL 2.0	registerAnnouncementListener(vec<AnnouncementType> enabled,IAnnouncementListener listener) generates (Result result, ICloseHandle closeHandle)
	AIDL	ICloseHandle registerAnnouncementListener(in IAnnouncementListener listener, in AnnouncementType[] enabled)
Descrição: HAL do HIDL: quando uma nova sessão de sintonizador é aberta, a sessão antiga precisa ser encerrada. HAL AIDL: como nenhuma sessão de sintonizador está disponível, apenas o callback do sintonizador precisa ser definido. Se ele existir, o callback antigo vai ser desativado.
	HIDL 2.0	openSession(ITunerCallback callback) gera (Result result, ITunerSession session)
	AIDL	void setTunerCallback(in ITunerCallback callback)
Descrição: HAL do HIDL: o encerramento de uma sessão de sintonizador não pode falhar e só pode ser emitido uma vez. HAL AIDL: não há sintonizador, e apenas o callback do sintonizador precisa ser desativado.
	HIDL 2.0	close()
	AIDL	unsetTunerCallback()
Descrição:sintoniza um programa especificado.
	HIDL 2.0	tune(ProgramSelector program) generates (Result result)
	AIDL	void tune(in ProgramSelector program)
Descrição:procura o próximo programa válido no ar. Para evitar confusão no AIDL, scan foi renomeado como seek.
	HIDL 2.0	scan(bool directionUp, bool skipSubChannel) generates (Result result)
	AIDL	void seek(in boolean directionUp, in boolean skipSubChannel)
Descrição:etapas para o canal adjacente, que não pode ser ocupado por nenhum programa.
	HIDL 2.0	step(bool directionUp) generates (Result result)
	AIDL	void step(in boolean directionUp)
Descrição:cancela operações pendentes de ajuste, verificação (em HIDL) ou busca (em AIDL) ou de etapa.
	HIDL 2.0	cancel()
	AIDL	void cancel()
Descrição:aplica um filtro à lista de programas e começa a enviar atualizações da lista pelo callback onProgramListUpdated.
	HIDL 2.0	startProgramListUpdates(ProgramFilter filter) generates (Result result)
	AIDL	void startProgramListUpdates(in ProgramFilter filter)
Descrição:para de enviar atualizações da lista de programas.
	HIDL 2.0	stopProgramListUpdates()
	AIDL	void stopProgramListUpdates()
Descrição:busca a configuração atual de uma determinada flag de configuração.
	HIDL 2.0	isConfigFlagSet(ConfigFlag flag) generates (Result result, bool value)
	AIDL	boolean isConfigFlagSet(in ConfigFlag flag)
Descrição:define a flag de configuração especificada.
	HIDL 2.0	setConfigFlag(ConfigFlag flag, bool value) generates (Result result)
	AIDL	void setConfigFlag(in ConfigFlag flag, boolean value)
Descrição:define valores de parâmetros específicos do fornecedor.
	HIDL 2.0	setParameters(vec<VendorKeyValue> parameters) gera, (vec<VendorKeyValue> results)
	AIDL	VendorKeyValue[] setParameters(in VendorKeyValue[] parameters)
Descrição:recupera valores de parâmetros específicos do fornecedor.
	HIDL 2.0	getParameters(vec<string> keys) generates (vec<VendorKeyValue> parameters)
	AIDL	VendorKeyValue[] getParameters(in String[] keys)

Esclarecimentos sobre a interface

Comportamento assíncrono

Como cada operação de ajuste (por exemplo, ajuste, verificação (em HIDL) ou busca (em AIDL) e etapa) pode levar muito tempo e a linha de execução não pode ser bloqueada por muito tempo, a operação precisa agendar operações demoradas para ocorrerem mais tarde e retornar rapidamente um status ou resultado. Em detalhes, cada operação precisa:

• Cancela todas as operações de ajuste pendentes.
• Verifique se a operação pode ser processada com base nas entradas do método e no status do afinador.
• Programe a tarefa de ajuste e retorne o Result (em HIDL) ou status (em AIDL) imediatamente. Se o Result ou status for OK, o callback do ajuste tuneFailed ou currentProgramInfoChanged precisará ser chamado quando a tarefa de ajuste falhar (por exemplo, devido a um tempo limite) ou for concluída.

Da mesma forma, startProgramListUpdates também agenda a tarefa demorada de atualizar a lista de programas para mais tarde e retornar rapidamente um status ou resultado. O método primeiro cancela as solicitações de atualização pendentes e depois agenda a tarefa de atualização e retorna rapidamente o resultado.

Disputa

Devido ao comportamento assíncrono das operações de ajuste (por exemplo, ajuste, verificação (em HIDL) ou busca (em AIDL) e etapa), há uma condição de disputa entre o cancelamento da operação e as operações de ajuste. Se cancel for chamado depois que o HAL concluir uma operação de ajuste e antes da conclusão do callback, o cancelamento poderá ser ignorado, e o callback será concluído e recebido pelo cliente HAL.

Da mesma forma, se stopProgramListUpdates for chamado depois que a HAL concluir uma atualização da lista de programas e antes da conclusão do callback onCurrentProgramInfoChanged, stopProgramListUpdates poderá ser ignorado e o callback será concluído.

Limite de tamanho de dados

Como há um limite rígido no buffer de transação do binder, o limite de dados para alguns métodos de interface que transmitem dados de um tamanho potencialmente grande é esclarecido no HAL AIDL.

• O getImage exige que a imagem retornada tenha menos de 1 MB.
• O onProgramListUpdate exige que cada chunk tenha menos de 500 kiB. Listas de programas maiores precisam ser divididas pela implementação da HAL em vários blocos e enviadas por vários callbacks.

Mudanças nas estruturas de dados da HAL do AIDL

Além das mudanças nas interfaces, essas alterações foram aplicadas às estruturas de dados definidas na HAL AIDL de rádio de transmissão, que aproveita a AIDL.

• A enumeração Constant foi removida da AIDL e definida como int constante em IBroadcastRadio. Enquanto isso, ANTENNA_DISCONNECTED_TIMEOUT_MS é renomeado como ANTENNA_STATE_CHANGE_TIMEOUT_MS. Uma nova constante int TUNER_TIMEOUT_MS é adicionada. Todas as operações de ajuste, busca e etapa precisam ser concluídas nesse período.
• As enumerações RDS e Deemphasis foram removidas da AIDL e definidas como const int em AmFmRegionConfig. Da mesma forma, fmDeemphasis e fmRds em ProgramInfo são declarados como int, um resultado de computação de bits das flags respectivas. Enquanto isso, D50 e D75 são renomeados como DEEMPHASIS_D50 e DEEMPHASIS_D75, respectivamente.
• A enumeração ProgramInfoFlags é removida na AIDL e definida como int constante em ProgramInfo com um prefixo FLAG_ adicionado. Da mesma forma, infoFlags em ProgramInfo é declarado como int, um resultado de computação de bits de flags. TUNED também é renomeado como FLAG_TUNABLE para descrever melhor a definição de que a estação pode ser sintonizada.
• Em AmFmBandRange, scanSpacing é renomeado como seekSpacing, já que scan é renomeado como seek na AIDL.
• Como o conceito de união foi introduzido na AIDL, MetadataKey e Metadata definidos na HAL do HIDL não são mais usados. Uma união AIDL Metadata é definida na HAL AIDL. Cada valor de enumeração que estava em MetadataKey agora é um campo em Metadata com tipo de string ou int, dependendo das definições.

Compatibilidade com rádio DAB

Esta seção descreve o suporte a rádio DAB.

Identifiers

O tipo de identificador principal para rádio DAB e DMB na HAL de rádio de transmissão AIDL é DAB_SID_EXT. O DAB_SID_EXT usa identificadores de serviço (SIDs) de 32 bits para representar o SID do rádio DAB e DMB.

Além dos identificadores principais, também há suporte para identificadores secundários, como DAB_ENSEMBLE e DAB_FREQUENCY_KHZ. Isso é importante porque várias estações de DAB podem compartilhar um DAB_SID_EXT, mas ter valores diferentes de DAB_ENSEMBLE ou DAB_FREQUENCY_KHZ. Para garantir atualizações precisas da lista de programas, as emissoras com o mesmo DAB_SID_EXT são atualizadas juntas usando ITunerCallback#onProgramListUpdated. Essa atualização é transmitida ao serviço de rádio e ao gerenciador de rádio e, por fim, ao app de rádio por android.hardware.radio.ProgramList.

Metadados

A tabela a seguir mostra os metadados compatíveis específicos para DAB no AIDL Broadcast Radio HAL:

Campo de metadados	Descrição
dabEnsembleName (forma abreviada: dabEnsembleNameShort)	Nome do conjunto da estação DAB
dabServiceName (abreviação de dabServiceNameShort)	Nome do serviço da estação DAB
dabComponentName (abreviação de dabComponentNameShort)	Nome do componente da estação DAB

Suporte para rádio HD

Esta seção descreve o suporte ao rádio HD.

Identifiers

HD_STATION_ID_EXT serve como o identificador principal das estações de rádio HD. Para melhorar ainda mais a identificação da estação, também são fornecidos identificadores secundários, como HD_STATION_NAME e HD_STATION_LOCATION. HD_STATION_LOCATION, que fornece informações de localização, foi introduzido no Android 15.

Ativar ou desativar a rádio digital

A partir do Android 15, é possível ativar ou desativar o rádio digital (como o rádio HD) ajustando ConfigFlags. Para controlar essa configuração no rádio FM, use a flag FORCE_ANALOG_FM. Para o rádio AM, use a flag FORCE_ANALOG_AM. Definir a flag como false ativa o rádio HD, enquanto true força o rádio analógico AM/FM.

Canais em HD disponíveis

A partir do Android 15, os canais HD disponíveis para uma estação de rádio HD podem ser representados por uma máscara de bits de 8 bits, Metadata#hdSubChannelsAvailable, em ProgramInfo.metadata. Por exemplo, o valor do bit 1 da esquerda representa se o subcanal HD2 está disponível para essa estação HD.

Status da aquisição de indicadores

No Android 15 e em versões mais recentes, os apps de rádio podem mostrar aos usuários o status de aquisição de sinal das estações de rádio HD. Isso é útil porque a aquisição de um sinal HD forte às vezes pode levar alguns instantes.

Para fornecer essas informações, o sistema usa ProgramInfo.infoFlags para rastrear o status e atualiza o app de rádio por ITunerCallback#onCurrentProgramInfoChanged.

Veja como o status é representado no ProgramInfo.infoFlags:

• Bit 6: indica se o sinal de rádio HD foi adquirido.
• Bit 7: mostra se os dados do Serviço de informações da estação (SIS, na sigla em inglês) estão disponíveis. O SIS fornece mais informações sobre a estação e o que está sendo reproduzido.
• Bit 8: informa se o áudio digital HD está disponível.

Metadados

A tabela a seguir mostra os metadados de rádio HD compatíveis com o Android 15 e versões mais recentes.

Campo de metadados	Descrição
commentShortDescription	Breve descrição do contexto do comentário
commentActualText	Texto do comentário
commercial	Comercial de rádio
ufids	Identificadores exclusivos de arquivos (UFIDs) associados ao conteúdo
hdStationNameShort	O nome abreviado ou universal da estação de rádio HD
hdStationNameLong	O nome longo, o slogan ou uma mensagem da estação de rádio HD.

Alertas de emergência

No Android 15 e versões mais recentes, os alertas de emergência são compatíveis com estações de rádio HD para informar os usuários de apps de rádio sobre os alertas de emergência enviados pelas estações. O alerta de emergência (Alert) segue o padrão do Protocolo de Alerta Comum (CAP) 1.2 e é compatível com os alertas mostrados na tabela a seguir:

Informações do alerta	Descrição	Valores de tipo enumerado disponíveis
AlertStatus	Status da mensagem de alerta	ACTUAL, EXERCISE, TEST
AlertMessageType	Tipo de mensagem de alerta de emergência	ALERT, UPDATE, CANCEL
AlertCategory	Categoria do evento principal da mensagem de alerta de emergência	GEO, MET, SAFETY, SECURITY, RESCUE, FIRE, HEALTH, ENV, TRANSPORT, INFRA, CBRNE, OTHER
AlertUrgency	Urgência do evento principal da mensagem de alerta de emergência	IMMEDIATE, EXPECTED, FUTURE, PAST, UNKNOWN
AlertSeverity	Gravidade do evento principal da mensagem de alerta de emergência	EXTREME, SEVERE, MODERATE, MINOR, UNKNOWN
AlertCertainty	Certeza do evento principal da mensagem de alerta de emergência	OBSERVED, LIKELY, POSSIBLE, UNLIKELY, UNKNOWN

Você pode usar Alert (que contém as informações na tabela), mensagens de texto de alerta e AlertArea para mostrar informações sobre o alerta atual. Alert é um campo opcional em ProgramInfo para que possa ser enviado do HAL da rádio de transmissão para apps de rádio por callbacks do sintonizador para informações do programa atual e atualizações da lista de programas.