Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.

Architecture

Most of the changes needed to support VirtIO in AAOS involve changes at the HAL implementation level and below in the Android Common Kernel. The Android framework communicates with a generic hardware-agnostic HAL using the VirtIO drivers in the AAOS guest VM kernel, which communicates with VirtIO devices on the host side using VirtIO protocols. VirtIO devices on the host side can access the physical HW using SoC-specific device drivers.

Communication between the VirtIO driver and the VirtIO device takes place with virtqueue, which are DMA-like ring buffers of scatter gather lists. Several transports, such as MMIO or PCI can be used to exchange the VirtIO messages between VMs.

In some cases, vsock has been leveraged for inter-VM communication. Vehicle HAL, Audio Control, and Dumpstate communications are supported using a connection to a peer agent on a separate VM over a vsock interface. GRPC-vsock is used to access these non-standardized subsystems. GRPC in the Android source tree has been modified to work with vsock with the address format of vsock:CID:PORT_NUMBER.

**Figure 1.** Virtualization architecture

Audio

In virtualized AAOS, the Android guest VM can use virtio-snd to access audio. virtio-snd provides the virtualized PCM devices to the Android VM so that the audio HAL implementation can interact with the virtualized sound devices with the TinyALSA library.

The default audio HAL implementation is located in AOSP at /device/google/trout/hal/audio/6.0. OEMs can modify ro.vendor.trout.audiohal.{in,out}_period_{ms,count} for their platform. OEMs can also implement their own audio HAL by overriding the audio-related variables in /device/google/trout/aosp_trout_common.mk.

The audio control HAL manages the audio focus in AAOS. For example, when the system is playing emergency sounds, music playing in the background might need to be muted. The audio control HAL notifies those apps playing music to mute in this situation. In the virtualized system, the sounds can come from other VMs. In the reference implementation, the AAOS guest VM has an audio control server daemon running, which uses GRPC-vsock to receive audio focus requests from other VMs. The host VM can use device/google/trout/hal/audiocontrol/2.0/libandroid_audio_controller to send audio control requests to AAOS. While libandroid_audio_controller holds the audio focus, it continues to send heartbeats to AAOS until focus is released.

Bluetooth

The Bluetooth implementation is based on the design illustrated below.

Bluetooth Hands-Free Profile

To enable the Bluetooth Hands-Free Profile (HFP) on trout, the VirtIO sound device specification has been extended to support audio controls. Using this approach, a VirtIO sound device on the host/hypervisor side provides these three audio controls related to the HFP:

hfp_enable
hfp_set_sampling_rate
hfp_volume

When AAOS runs as a guest VM, AAOS uses TinyAlsa to set these audio controls. To enable the HFP use case, the host/hypervisor performs the vendor-specific routing and calibration accordingly.

The Bluetooth implementation is based on the design illustration below.

Dumpstate

When generating the bugreport for virtualized AAOS, it's valuable to include host VM information so that the developers have a more comprehensive view of the system. To accomplish this, the trout reference implementation implements IDumpstateDevice HAL, which collects the host VM information through GRPC-vsock. The `tar`-packaged host VM information is named dumpstate_board.bin in the bugreport while dumping logs are at dumpstate_board.txt.

To configure the commands to execute:

Copy the configuration details from the file below into an XML file, for example, config.xml.

<dumpstateHalConfiguration version="1.0">
    <services>
        <service name="coqos-virtio-blk"        command="/bin/journalctl --no-pager -t coqos-virtio-blk"/>
        <service name="coqos-virtio-net"        command="/bin/journalctl --no-pager -t coqos-virtio-net"/>
        <service name="coqos-virtio-video"      command="/bin/journalctl --no-pager -t coqos-virtio-video"/>
        <service name="coqos-virtio-console"    command="/bin/journalctl --no-pager -t coqos-virtio-console"/>
        <service name="coqos-virtio-rng"        command="/bin/journalctl --no-pager -t coqos-virtio-rng"/>
        <service name="coqos-virtio-vsock"      command="/bin/journalctl --no-pager -t coqos-virtio-vsock"/>
        <service name="coqos-virtio-gpu-virgl"  command="/bin/journalctl --no-pager -t coqos-virtio-gpu-virgl"/>
        <service name="coqos-virtio-scmi"       command="/bin/journalctl --no-pager -t coqos-virtio-scmi"/>
        <service name="coqos-virtio-input"      command="/bin/journalctl --no-pager -t coqos-virtio-input"/>
        <service name="coqos-virtio-snd"        command="/bin/journalctl --no-pager -t coqos-virtio-snd"/>
        <service name="dumpstate_grpc_server"   command="/bin/journalctl --no-pager -t dumpstate_grpc_server"/>
        <service name="systemd"                 command="/bin/journalctl --no-pager -t systemd"/>
        <service name="systemctl"               command="/bin/systemctl status"/>
        <service name="vehicle_hal_grpc_server" command="/bin/journalctl --no-pager -t vehicle_hal_grpc_server"/>
    </services>
    <systemLogs>
        <service name="dmesg" command="/bin/dmesg -kuPT"/>
    </systemLogs>
</dumpstateHalConfiguration>

Pass the path of the new XML file to the dumpstate server when launching. For example:
```
--config_file my_config.xml
```

Extended View System (EVS)

The Extended View System (EVS) is used to display video captured by the rear-view and surround-view cameras. In virtualized AAOS, the EVS stack can access the video stream from the virtualized V4L2 streaming device that uses the VirtIO-video driver.

Garage mode

For more information, see Garage Mode.

Entering and exiting Garage mode is triggered by AP_POWER_STATE_REQ properties sent by the Vehicle HAL. In virtualization mode, Garage mode is triggered from the host side. The host VM should remain powered on to provide virtual devices for Android VM, until Android is powered off. The VHAL server on the host VM sends the shutdown signal to the AAOS guest VM. Upon receiving the signal VHAL client, the AAOS VM enters Garage mode and starts to send heartbeat signals to keep the host VM active.

Global navigation satellite system (GNSS)

In trout 1.0, support for GNSS virtualization over virtio-console has been added. The implementation supports the exchange of raw measurements and location fixes from the host to the guest.

The data exchange format is the CSV used by the GnssLogger app. In the reference implementation, because the native GNSS driver isn't available, mock data is made available but a native driver can be implemented without any guest-side changes. A sample mock host agent is provided as part of the trout source code.

The current implementation expects GNSS initialization and Assisted GNSS (AGNSS) to be handled by the host OS environment.

Graphics

When AAOS is running as a guest VM alongside other automotive operating systems, Android might not have direct access to the GPU or the display controller. In this case, Mesa or goldfish-opengl and a virtio-gpu driver on the Android guest VM and virtio-gpu device can be used to access the GPU.

On the Android guest VM, Mesa or goldfish-opengl encodes OpenGLES commands either into a Gallium stream or an auto-generated GLES stream, respectively. The virtio-gpu kernel driver is used as a transport. On the host side, virglrenderer (for Mesa) and vulkan-cereal (for goldfish-opengl) replay the decoded command stream on top of the existing GPU driver. The AAOS reference platform trout supports OpenGL ES only with Vulkan support, anticipated in a future release.

Sensors

When AAOS is running as a guest VM alongside other automotive operating systems, Android might not have direct access to the sensors. In this case, the Virtio-SCMI driver on the Android guest VM and the VirtIO-SCMI device on the Host VM are used to access the sensors. The AAOS virtualization reference platform provides a generic and HW-agnostic Sensor HAL that can be used for ARM-based SoCs to access the sensors.

Sensor HAL communicates with the IIO SCMI driver in the Linux Kernel IIO subsystem, which uses the SCMI Sensor Management Protocol provided by the ARM System Control and Management Interface (SCMI) specification to discover and configure sensors, read sensor data, and be notified of sensor value changes.

The IIO SCMI driver uses the VirtIO SCMI Driver, which uses VirtIO transport protocol as specified in the virtio-scmi specification to exchange SCMI messages with the VirtIO SCMI device on the host VM. The VirtIO SCMI device has direct access to the sensors through SoC-specific sensor drivers.

Sensor HAL location

The reference implementation of the sensor HAL, which uses VirtIO SCMI, is located at device/google/trout/hal/sensors.

Sensor HAL configuration

Sensor HAL might need to modify the sensor data received from the Host VM to comply with the Android car sensor coordinate system. The schema for sensor configuration can be found in device/google/trout/hal/sensors/2.0/config/sensor_hal_configuration.xsd.

OEMs can provide sensor configuration, such as orientation and location, in sensor_hal_configuration.xml and copy the file at either /odm/etc/sensors/ or /vendor/etc/sensors/. A sample sensor configuration is provided below:

<sensorHalConfiguration version="1.0" xmlns:xi="http://www.w3.org/2001/XInclude">
    <modules>
        <module halName="android.hardware.sensors@2.0-Google-IIO-Subhal" halVersion="2.0">
            <sensors>
                <sensor name="scmi.iio.accel" type="1">
                    <configuration>
<!-- Attribute rotate denotes if HAL needs to modify the sensor data to comply with //
        the Android car sensor coordinate system -->
                        <orientation rotate="true">
               <!-- Attribute map denotes the indexes of data in sensor data received -->
               <!-- Attribute negate denotes if data needs to be negated -->
                            <x map="0" negate="false"/>
                            <y map="1" negate="true"/>
                            <z map="2" negate="true"/>
                        </orientation>
                        <location>
               <!-- Attribute x, y, z denotes location of the sensor placement -->
                            <x>10</x>
                            <y>15</y>
                            <z>20</z>
                        </location>
                    </configuration>
                </sensor>
         </sensors>
        </module>
    </modules>
</sensorHalConfiguration>

Vehicle HAL

The Vehicle HAL implementation consists of two components:

Client. Provides APIs used by Android in virtualized AAOS
Server. Communicates directly with the hardware, such as vehicle buses (or an emulator).

In virtualization, the VHAL server runs on the host VM. The VHAL client and server communicate through GRPC-vsock (for more information, see device/google/trout/hal/vehicle/2.0/proto/VehicleServer.proto). OEMs can use a different transport protocol other than GRPC by overriding the communication APIs. For examples, see device/google/trout/hal/vehicle/2.0/GrpcVehicle{Client,Server}.cpp.

Other subsystems

VirtIO already provides a well-defined interface for components such as Block Storage, Network, Console, Input, Socket, and Entropy. For these subsystems, AAOS uses the driver as-is, such as virtio-blk, virtio-input, virtio-console, and virtio-net.

In the virtualized AAOS reference platform, Wi-Fi is supported with mac80211_hwsim to enable a VirtWifi wireless network, which then uses virtio-net tunnel to send the network traffic to the host VM, which has direct access to the actual Wi-Fi network.

Architecture Stay organized with collections Save and categorize content based on your preferences.