Cuttlefish: Create a custom device

This page describes how to create a customized Cuttlefish device. Cuttlefish includes predefined device types in different form factors as listed in AndroidProducts.mk. In addition to the general device customization options described in Adding a new device, you can make Cuttlefish-specific customizations such as virtual device board configuration presets (vsoc_x88_64, vsoc_arm64, vsoc_riscv64), kernel prebuilts, bootloader prebuilts, vendor properties, system configurations, nested virtualization support, and display options. For a full list of the build time parameters that can be customized, see device/google/cuttlefish/vsoc_x86_64/phone/aosp_cf.mk.

The following steps describe how to create a fictional x86-64 big_phone device ten times the size of an ordinary Cuttlefish device.

Inherit from an existing target

To inherit from an existing target:

Create a device/google/cuttlefish/vsoc_x86_64/big_phone directory.
Create an aosp_cf.mk file in that directory.

$(call inherit-product, device/google/cuttlefish/vsoc_x86_64_phone.mk)

PRODUCT_NAME: big_phone
PRODUCT_DEVICE: vsoc_x86_64
PRODUCT_MANUFACTURER := My Company
PRODUCT_MODEL: My Company very large phone

PRODUCT_VENDOR_PROPERTIES += \
    ro.soc.manufacturer=$(PRODUCT_MANUFACTURER) \
    ro.soc.model=$(PRODUCT_DEVICE)

Add a lunch target

Insert the lunch target into the device/google/cuttlefish/AndroidProducts.mk file:

PRODUCT_MAKEFILES := \
  ...
  big_phone:$(LOCAL_DIR)/vsoc_x86_64/big_phone/aosp_cf.mk
  ...

lunch big_phone

Define JSON configuration

To launch the Cuttlefish device, create a JSON configuration file named big_phone.json with a hierarchical structure representing the device properties. For example, in the JSON configuration file, you can specify options such as the RAM allocated for the VM and the display configuration. This file doesn't have to be in the AOSP tree. For details on the JSON format for configurations, see Canonical configurations.

{
  "instances":
      [
        {
          "vm": {
            "memory_mb": 40960,
          },
          "graphics": {
            "displays": [
              {
                "width": 7200,
                "height": 12800,
                "dpi": 320
              }
            ]
          }
        }
      ]
}

To launch the configuration, run:

cvd create --config_file=big_phone.json

Run launch_cvd (legacy)

Certain configuration properties aren't available in the hierarchical JSON configuration format. For such configurations, you can set launch_cvd flag default values from a single-level JSON dictionary. For a full list of all configuration options, see cf_flags_validator.cpp.

The following describes an example of how to override the default values of the launch_cvd flag options using a JSON configuration file and enable the Cuttlefish launcher to launch the custom configuration.

Create a JSON configuration file, device/google/cuttlefish/shared/config/config_big_phone.json, with custom values.

{
  "x_res": 7200,
  "y_res": 12800,
  "dpi": 320,
  "memory_mb": 40960,
  "ddr_mem_mb": 49150,
}

For the Cuttlefish launcher to launch the big_phone config, ensure it has access to the device/google/cuttlefish/shared/config/config_big_phone.json file by doing the following:
1. Declare the JSON artifact as a build artifact by adding the prebuilt_etc_host stanza in the device/google/cuttlefish/shared/config/Android.bp file.
```
prebuilt_etc_host {
    name: "cvd_config_big_phone.json",
    src: "config_big_phone.json",
    sub_dir: "cvd_config",
}
```
2. Add the resulting build artifact declaration into the Cuttlefish launcher by running the following in device/google/cuttlefish/shared/device.mk.
```
$(call soong_config_append,cvd,launch_configs,cvd_config_big_phone)
```
3. Create an android_info.txt file and tie the big_phone config to the file by adding the following line to device/google/cuttlefish/vsoc_x86_64/big_phone/aosp_cf.mk:
```
TARGET_BOARD_INFO_FILE := device/google/cuttlefish/vsoc_x86_64/<var>big_phone</var>/android-info.txt
```
4. Label the device type with the big_phone config by populating device/google/cuttlefish/vsoc_x86_64/big_phone/android-info.txt with the following:
```
config=big_phone
```