Interface VHAL

A VHAL da AIDL é definida no android.hardware.automotive.vehicle namespace. A interface VHAL é definida em IVehicle.aidl. A menos que especificado, todos os métodos precisam ser implementados.

Método
VehiclePropConfigs getAllPropConfigs() Retorna uma lista de todas as configurações de propriedade compatíveis com a HAL do veículo.
VehiclePropConfigs getPropConfigs(in int[] props) Retorna uma lista de configurações de propriedade para os IDs de propriedade fornecidos.
void getValues(IVehicleCallback callback, in GetValueRequests requests) Receba os valores das propriedades do veículo de forma assíncrona. Processa um lote de GetValueRequest de forma assíncrona. O resultado é entregue pelo método onGetValues de callback.
void setValues(IVehicleCallback callback, in SetValueRequests requests) Defina os valores de propriedade do veículo de forma assíncrona. Processa um lote de SetValueRequest de forma assíncrona. O resultado é enviado pelo método onSetValues de callback.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount) Inscreve-se em eventos da propriedade com opções específicas. As opções de inscrição incluem o ID da propriedade, o ID da área da propriedade e a taxa de amostragem em Hz (para uma propriedade contínua). maxSharedMemoryFileCount não é usado.
void unsubscribe(in IVehicleCallback callback, in int[] propIds) Cancela a assinatura de eventos de propriedade que foram assinados anteriormente para propriedades especificadas.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId) Não é usado e pode ser implementado como ambiente autônomo.

Os callbacks são definidos em IVehicleCallback.aidl e contêm esses métodos.

Método
oneway void onGetValues(in GetValueResults responses) Callback da função getValues para entregar resultados de recebimento de valor. Chamada quando alguns dos valores a serem buscados estão prontos.
oneway void onSetValues(in SetValueResults responses) Callback para a função setValues para entregar resultados de valores definidos. Chamada quando a VHAL termina de processar algumas das solicitações de conjunto de propriedades.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount) Callback para informar eventos de atualização da propriedade. Propriedade CONTINUOUS, um evento de propriedade ocorre com base na taxa de amostragem de inscrição em Hz ou na frequência da mensagem do barramento do veículo. Um evento de propriedade também pode acontecer se o status de uma propriedade mudar. Por exemplo, de indisponível para disponível. Para a propriedade ON_CHANGE, um evento de propriedade acontece quando o valor ou o status de uma propriedade muda. SharedMemoryFileCount é sempre 0.
oneway void onPropertySetError(in VehiclePropErrors errors) Callback para informar erros assíncronos do conjunto de propriedades que não têm uma solicitação correspondente. Se soubermos para qual solicitação de conjunto o erro se refere, será necessário usar onSetValues com um resultado de erro no lugar dele.

Para mais informações, consulte IVehicle.aidl e IVehicleCallback.aidl.

A implementação da VHAL é validada pelo VTS da VHAL em VtsHalAutomotiveVehicle_TargetTest.cpp. O teste verifica se os métodos básicos são implementados corretamente e se as configurações de propriedade com suporte estão corretas.

Valor de propriedade do veículo

Use a estrutura VehiclePropValue para descrever o valor de cada propriedade, que tem estes campos:

Campo	Descrição
timestamp	O carimbo de data/hora que representa a hora em que o evento ocorreu e foi sincronizado com o relógio SystemClock.elapsedRealtimeNano().
prop	O ID da propriedade para esse valor.
areaid	O ID da área para esse valor. A área precisa ser uma das áreas com suporte listadas na configuração do ID da área ou 0 para propriedades globais.
value	Uma estrutura de dados que contém o valor real da propriedade. Com base no tipo de propriedade, um ou mais campos dentro desse campo são usados para armazenar o valor real. Por exemplo, o primeiro elemento em value.int32Values é usado para propriedades do tipo Int32. Para mais detalhes, consulte Configurações de propriedade.

getValues e setValues assíncronos

As operações getValues e setValues são realizadas de forma assíncrona, o que significa que a função pode retornar antes que a operação real "get" ou "set" seja concluída. Os resultados da operação (por exemplo, o valor da propriedade para getValues e o status de sucesso ou de erro para setValues) são enviados pelos callbacks transmitidos como argumentos.

A implementação não pode bloquear o resultado na linha de execução de vinculação que processa a solicitação. Em vez disso, recomendamos armazenar a solicitação em uma fila de solicitações e usar uma linha de execução de gerenciador separada para processar as solicitações de forma assíncrona. Consulte a Implementação de referência para mais detalhes.

Figura 1. Processo assíncrono.

Parcelables grandes

Todas as estruturas com o nome XXXs, como VehiclePropConfigs, SetValueRequests e VehiclePropValues, são chamadas de LargeParcelable (ou StableLargeParcelable). Cada uma representa uma lista de valores usados para transmitir dados grandes que podem exceder as limitações do binder (4 KB na implementação da biblioteca LargeParcelable) em limites de binder. Cada um tem uma definição de estrutura semelhante que contém os seguintes campos.

Orientação	Descrição
payloads	Lista de valores quando o tamanho do valor se encaixa em uma limitação de memória do vinculador ou em uma lista vazia.
sharedMemoryFd	Descritor de arquivo anulável que aponta para um arquivo de memória compartilhada que armazena os payloads serializados se a lista de valores for muito grande.

Por exemplo, VehiclePropConfigs é definido como:

parcelable VehiclePropConfigs {
    // The list of vehicle property configs if they fit the binder memory
    // limitation.
    VehiclePropConfig[] payloads;
    // Shared memory file to store configs if they exceed binder memory
    // limitation. Created by VHAL, readable only at client. Client could keep
    // the fd opened or keep the FD mapped to access configs.
    @nullable ParcelFileDescriptor sharedMemoryFd;
}

VehiclePropConfigs contém payloads não vazios ou um sharedMemoryFd não nulo.

• Se payloads não estiver vazio, ele vai armazenar uma lista dos dados reais, que é a configuração da propriedade.
• Se sharedMemoryFd não for nulo, ele conterá um arquivo de memória compartilhada, que armazena a estrutura serializada de VehiclePropConfigs. A estrutura usa a função writeToParcel para serializar um pacote.

Como um cliente Java para VHAL, o Car Service processa a serialização e a desserialização de LargeParcelable. Para implementações de VHAL e clientes nativos, um LargeParcelable precisa ser serializado e desserializado com a biblioteca LargeParcelable ou uma classe wrapper útil para a biblioteca em ParcelableUtils.h.

Por exemplo, um cliente nativo que analisa solicitações para getValues recebidas de um binder é o seguinte:

// 'requests' are from the binder.
GetValueRequests requests;
expected, ScopedAStatus> deserializedResults = fromStableLargeParcelable(requests);
if (deserializedResults.ok()) {
    const std::vector& getValueRequests = deserializedResults.value().getObject()->payloads;
    // Use the getValueRequests.
  } else {
    // handle error.
}

Confira abaixo um exemplo de implementação do VHAL que envia resultados para getValues pelo vinculador:

std::vector results = getResults();
GetValueResults parcelableResults;
ScopedAStatus status = vectorToStableLargeParcelable(std::move(results), &parcelableResults);
if (status.isOk()) {
    // Send parcelableResults through callback.
} else {
    // Handle error.
}