Cuttlefish: reiniciar e redefinir

Esta página descreve como reiniciar e redefinir dispositivos virtuais Cuttlefish. A redefinição para o estado inicial do disco é chamada de Powerwash na ferramenta de linha de comando.

Ao executar fluxos de trabalho automatizados ou manuais com vários procedimentos, como pacotes de testes, a redefinição do dispositivo Cuttlefish entre procedimentos garante que o comportamento de cada um deles seja independente. Se o estado do disco não for redefinido, um procedimento poderá afetar o comportamento do próximo.

Os procedimentos de reinicialização e redefinição descritos nesta página pressupõem que você criou um dispositivo Cuttlefish e definiu algum estado no disco.

# Launch a device
launch_cvd
# Make some modifications to the device
adb shell touch /storage/self/primary/Documents/hello
# Check the device state
adb shell ls /storage/self/primary/Documents

Após esse ponto de partida, é possível usar os seguintes fluxos de reinicialização e redefinição:

  • Se o dispositivo estiver respondendo, execute uma reinicialização limpa usando o adb reboot.
  • Se o dispositivo não estiver respondendo, execute uma reinicialização forçada usando o restart_cvd.
  • Redefina o estado do dispositivo usando o powerwash_cvd.
  • Interrompa o dispositivo e mude os argumentos launch_cvd enquanto mantém ou apaga à força o estado dele.

Implementação da redefinição rápida do Cuttlefish

O Cuttlefish usa uma implementação de redefinição rápida que depende da proteção dos discos por trás das sobreposições de discos qcow2 (link em inglês). Por padrão, o Cuttlefish trata discos originais como somente leitura e usa sobreposições para capturar gravações de disco.

No entanto, as sobreposições do tipo copy-on-write têm desvantagens. As mudanças externas nos discos interrompem a compatibilidade com as sobreposições já existentes e causam um estado de disco inconsistente. O Cuttlefish força a recriação das sobreposições quando detecta mudanças incompatíveis.

Essa recriação não é recomendável ao desenvolver um recurso que exige que parte do disco seja mantida em um estado inicializado específico enquanto outra é substituída. Um exemplo disso seria instalar um app com uma configuração de usuário específica e depois trocar o kernel repetidamente para testar a interação entre o app e os diferentes builds do kernel. Nesse caso, é recomendável desativar as sobreposições.

Redefinir dispositivos

As seções a seguir descrevem maneiras de redefinir um dispositivo Cuttlefish para o estado inicial do disco.

Redefinir um dispositivo

Para redefinir um dispositivo Cuttlefish para o estado inicial do disco, execute o seguinte:

powerwash_cvd

O powerwash_cvd desliga a máquina virtual, redefine as mudanças feitas no disco, reinicia essa máquina e espera até o fim da reinicialização. A instância preserva as flags originais fornecidas para launch_cvd.

Em uma configuração com vários locatários, o powerwash_cvd reinicia uma única instância do grupo:

powerwash_cvd --instance_num=N

Redefinir todos os dispositivos

Para interromper e redefinir um ou mais dispositivos para os estados iniciais do disco, execute o seguinte:

stop_cvd
launch_cvd --resume=false

O stop_cvd força o desligamento e interrompe o dispositivo.

A adição de --resume=false ao launch_cvd faz com que o Cuttlefish destrua todos os arquivos relacionados à instância que estava em execução anteriormente antes de iniciar a próxima execução. É seguro adicionar outras flags launch_cvd.

Em uma configuração de vários locatários, o stop_cvd encerra todo o grupo de instâncias.

Reiniciar dispositivos

As seções a seguir descrevem maneiras de reiniciar um dispositivo sem fazer a redefinição para o estado inicial do disco.

Reinicialização limpa

Para fazer uma reinicialização limpa do dispositivo quando ele responder, execute o seguinte:

adb reboot

O adb reboot conduz o dispositivo por todo o procedimento de desligamento, sincronizando mudanças no disco e garantindo que os processos sejam encerrados. Os processos do host do Cuttlefish não estão envolvidos. Esse procedimento poderá ficar indisponível se o dispositivo entrar em um estado inadequado e parar de responder.

Para fazer uma reinicialização limpa de um único dispositivo Cuttlefish em uma configuração de vários locatários, especifique o número de série do dispositivo de destino ao executar o adb-reboot. Se a especificação não for feita, o adb não reiniciará nenhum dispositivo.

adb -s SERIAL reboot

Reinicialização forçada

Para realizar uma reinicialização forçada quando o dispositivo não estiver respondendo, execute o seguinte:

restart_cvd

O restart_cvd desliga o dispositivo Cuttlefish de forma instantânea e forçada. Executar o restart_cvd equivale a remover e reinserir a bateria de um dispositivo físico. As gravações de disco podem não ser mantidas caso estejam em andamento. O trabalho do restart_cvd só termina quando o dispositivo for totalmente inicializado novamente.

Em uma configuração com vários locatários, o restart_cvd reinicia uma única instância fora do grupo. Para especificar qual instância do Cuttlefish vai ser reiniciada, use a flag instance_num.

restart_cvd --instance_num=N

Se a --instance_num não for usada, o número da instância será definido como 1 por padrão.

Reiniciar usando diferentes flags launch_cvd

Se quiser parar um ou mais dispositivos e reiniciar com diferentes flags launch_cvd, execute o seguinte:

stop_cvd
launch_cvd NEW_FLAG

O stop_cvd executa um desligamento forçado semelhante ao restart_cvd. O dispositivo fica em um estado inativo que pode ser iniciado mais uma vez com um comando launch_cvd diferente. Assim como em restart_cvd, as gravações de disco podem não persistir se não forem totalmente sincronizadas. Para salvar dados no disco com segurança, execute o adb reboot primeiro.

adb reboot
stop_cvd
launch_cvd NEW_FLAG

Se as mudanças nas flags launch_cvd forçarem uma mudança no layout do disco que seja incompatível com a implementação de copy-on-write, o launch_cvd vai ignorar as modificações de disco antigas e redefinir o disco para o estado original. Para uma lista completa, consulte Flags.

Executar sem sobreposição

Para desativar o suporte à redefinição rápida, execute o seguinte:

launch_cvd --use_overlay=false

--use_overlay=false trata os arquivos de disco do Cuttlefish como leitura/gravação e as mudanças são propagadas para esses arquivos.

A mudança entre --use_overlay=false e o padrão pode causar erros de compatibilidade. Para forçar a limpeza do estado anterior do dispositivo, execute o seguinte:

stop_cvd
rm $HOME/cuttlefish $HOME/cuttlefish_runtime $HOME/cuttlefish_assembly

O Cuttlefish não consegue fazer a transição entre os fluxos com e sem sobreposições de forma segura. Portanto, essa mudança exclui todo o estado de gerenciamento do Cuttlefish. Se os arquivos do disco externo forem modificados e reutilizados depois com sobreposições, as modificações anteriores vão ser consideradas parte do estado de referência.

Flags

É possível adicionar argumentos usando flags ao iniciar um dispositivo Cuttlefish com o launch_cvd. No entanto, a perda de dados poderá ocorrer com algumas flags se elas forem modificadas entre os comandos launch_cvd. Confira as flags que precisam permanecer iguais. Para garantir que não haja perda de dados ao executar uma sequência de comandos que incluem launch_cvd, stop_cvd e launch_cvd novamente, use as mesmas flags para cada comando launch_cvd. Por exemplo, se a primeira flag launch_cvd incluir o argumento --kernel_path=KERNEL_PATH, a segunda invocação de launch_cvd também precisará incluir o mesmo argumento --kernel_path=KERNEL_PATH, ou as mudanças do sistema de arquivos feitas antes de stop_cvd serão perdidas na segunda invocação de launch_cvd. O arquivo referenciado por KERNEL_PATH também precisa ter os mesmos conteúdos.

Algumas flags são seguras para mudanças entre as invocações de launch_cvd. As seções a seguir listam as flags que precisam permanecer iguais para evitar a perda de dados e as que podem ser modificadas com segurança sem essas perdas. Para detalhes sobre flags específicas, consulte a origem (flags.cc, disk_flags.cc) ou execute launch_cvd --help.

Flags que precisam permanecer iguais

Para evitar a perda de dados, estas flags não podem mudar de uma invocação de launch_cvd para a próxima:

  • --data_policy
  • --blank_data_image_mb
  • --kernel_path
  • --initramfs_path
  • --vm_manager
  • --enable_minimal_mode
  • --bootloader
  • --protected_vm
  • --userdata_format
  • --use_overlay
  • --system_image_dir
  • --boot_image
  • --init_boot_image
  • --data_image
  • --super_image
  • --misc_image
  • --misc_info_txt
  • --metadata_image
  • --vendor_boot_image
  • --vbmeta_image
  • --vbmeta_system_image
  • --linux_kernel_path
  • --linux_initramfs_path
  • --linux_root_image
  • --fuchsia_zedboot_path
  • --fuchsia_multiboot_bin_path
  • --fuchsia_root_image
  • --custom_partition_path
  • --blank_metadata_image_mb

Flags que podem mudar

Estas flags podem ser modificadas com segurança entre as invocações de launch_cvd sem causar perda de dados:

  • --displays_textproto
  • --displays_binproto
  • --cpus
  • --gdb_port
  • --display0
  • --display1
  • --display2
  • --display3
  • --x_res
  • --y_res
  • --dpi
  • --refresh_rate_hz
  • --extra_kernel_cmdline
  • --extra_bootconfig_args
  • --guest_enforce_security
  • --memory_mb
  • --serial_number
  • --use_random_serial
  • --gpu_mode
  • --hwcomposer
  • --gpu_capture_binary
  • --enable_gpu_udmabuf
  • --enable_gpu_angle
  • --use_allocd
  • --pause_in_bootloader
  • --enable_host_bluetooth
  • --rootcanal_instance_num
  • --rootcanal_args
  • --netsim
  • --netsim_bt
  • --bluetooth_controller_properties_file
  • --bluetooth_commands_file
  • --enable_sandbox
  • --seccomp_policy_dir
  • --start_webrtc
  • --webrtc_assets_dir
  • --webrtc_certs_dir
  • --start_webrtc_sig_server
  • --webrtc_sig_server_addr
  • --webrtc_sig_server_port
  • --tcp_port_range
  • --udp_port_range
  • --webrtc_sig_server_path
  • --webrtc_sig_server_secure
  • --verify_sig_server_certificate
  • --webrtc_device_id
  • --uuid
  • --daemon
  • --setupwizard_mode
  • --enable_bootanimation
  • --qemu_binary_dir
  • --crosvm_binary
  • --gem5_binary_dir
  • --gem5_checkpoint_dir
  • --gem5_debug_file
  • --gem5_debug_flags
  • --restart_subprocesses
  • --enable_vehicle_hal_grpc_server
  • --boot_slot
  • --num_instances
  • --report_anonymous_usage_stats
  • --ril_dns
  • --kgdb
  • --start_gnss_proxy
  • --gnss_file_path
  • --fixed_location_file_path
  • --enable_modem_simulator
  • --modem_simulator_sim_type
  • --console
  • --enable_kernel_log
  • --vhost_net
  • --vhost_user_mac80211_hwim
  • --wmediumd_config
  • --ap_rootfs_image
  • --ap_kernel_image
  • --record_screen
  • --smt
  • --vsock_guest_cid
  • --secure_hals
  • --use_sdcard
  • --enable_audio
  • --camera_server_port
  • --modem_simulator_count
  • --blank_sdcard_image_mb
  • --adb_mode