Depurar SDV

Este guia oferece uma visão geral das ferramentas e técnicas essenciais para depurar serviços e aplicativos que são executados na plataforma SDV.

Conectar ao dispositivo

A principal ferramenta para se conectar e interagir com o dispositivo é o Android Debug Bridge (adb). Verifique se adb está no caminho do seu sistema.

Conectar usando a rede

Se o dispositivo estiver na mesma rede e você souber o endereço IP dele, conecte-se por Ethernet. Nosso sistema usa exclusivamente conexões de rede para adb:

# Connect to the device using its IP address and default port
adb connect <device_ip_address>:5555

Conectar a vários dispositivos

Para gerenciar vários dispositivos em uma única estação de trabalho, conecte-se a eles usando endereços IP diferentes. Se você executar várias VMs em um único host, precisará atribuir portas diferentes a cada dispositivo. Isso exige configurar o daemon adb em cada dispositivo SDV para detectar uma porta exclusiva, por exemplo, 5555 para o primeiro dispositivo e 5556 para o segundo. Também é possível configurar o host para encaminhar essas portas para convidados diferentes:

# Connect to the first device
adb connect <device_1_ip_address>:5555

# Connect to a second device
adb connect <device_2_ip_address>:5555

# Connect to a second VM on first device on different port
adb connect <device_1_ip_address>:5556

# List all connected devices to verify
adb devices

Ao executar comandos adb subsequentes, você pode segmentar um dispositivo específico usando a flag -s com o endereço completo (ip:port):

# Run a shell command on the second VM on first device in the above example
adb -s <device_1_ip_address>:5556 shell

Ver registros

Quando um serviço falha ou se comporta de maneira inesperada, verifique os registros primeiro.

Usar o logcat (registros do Android)

O logcat mostra registros de serviços do sistema, agentes e pacotes de serviços:

# View all logs in real-time
adb logcat

# Filter logs by a specific tag (e.g., the name of your service)
adb logcat -s MyServiceTag

# Filter logs by priority (V: Verbose, D: Debug, I: Info, W: Warn, E: Error, F: Fatal)
# This shows only Error and Fatal messages for a specific tag
adb logcat MyServiceTag:E *:S

# Clear old logs before viewing new ones
adb logcat -c && adb logcat

# Show all logs and return
adb logcat -d

# Color logs by level
adb logcat -v color

# Show timestamps as time since boot
adb logcat -v monotonic

Usar dmesg (registros do kernel)

O dmesg mostra registros do kernel do Linux. Isso é crucial para depurar o seguinte:

  • Problemas de hardware e drivers
  • Kernel panics
  • Negações do SELinux (avc: denied): também mostradas no logcat
# View all kernel messages
adb shell dmesg

# Follow kernel messages in real-time
adb shell dmesg -w

Acessar registros no Cuttlefish

Ao executar em um dispositivo virtual Cuttlefish, é possível acessar diretamente os arquivos de registro do sistema de arquivos da máquina host. Isso é especialmente útil se adb não estiver disponível. Ao iniciar o Cuttlefish, ele gera todos os caminhos de depuração, e você também pode pesquisá-los usando cvd fleet para todas as instâncias em execução.

  • Logcat (registros do Android): cuttlefish/instances/cvd-1/logs/logcat
  • Registros do kernel:cuttlefish/instances/cvd-1/logs/kernel.log
  • Registros do iniciador do Cuttlefish:cuttlefish/instances/cvd-1/logs/launcher.log (útil para depurar o próprio ambiente do Cuttlefish)

Você pode usar ferramentas de linha de comando padrão, como cat, less ou tail -f, para visualizar esses arquivos em tempo real.

Interagir com o shell e o sistema de arquivos

Acesse o shell para executar comandos diretamente no dispositivo, verificar o status do processo e navegar pelo sistema de arquivos:

# Open an interactive shell on the device
adb shell

# From within the shell, you can check running processes
ps -A

# Or check the status of a specific service managed by init
getprop init.svc.<service_name>

Realizar operações do sistema de arquivos

Use adb push e adb pull para mover arquivos entre a máquina host e o dispositivo. Use isso para implantar scripts de teste, atualizar a configuração ou recuperar despejos de falhas:

# Push a file from your computer to the device
adb push my_local_file.txt /data/local/tmp/

# Pull a file from the device to your computer
adb pull /data/tombstones/tombstone_00 .

Depurar aplicativos (C++/Rust)

É possível depurar aplicativos on-line ou off-line.

Usar o lldb para depuração em tempo real

O lldb é o depurador padrão do Android Studio e geralmente é preferido para desenvolvimento moderno em C++ e Rust.

Siga estas etapas de configuração:

  1. Reinicie o adb para permitir permissões de root (necessárias para encaminhar). Use isso para configurar o encaminhamento de portas. No host, execute:

    adb root

  2. Se um binário tiver símbolos de depuração, envie uma versão sem remoção. A versão sem remoção de símbolos está em out/target/product/[SDV_FLAVOR]/symbols/[PARTITION]/bin/[EXECUTABLE]. Por exemplo, para fazer upload de rpcagent de system_ext e sdv_core_cf, execute:

    adb push out/target/product/sdv_core_cf/symbols/system_ext/bin/rpcagent /data/local/tmp

    Agora, a versão sem remoção está em /data/local/tmp.

  3. Conecte-se ao cliente LLDB usando o script de conveniência lldbclient.py:

    # Run and connect a binary on device, run on host:
lldbclient.py -r /data/local/tmp/rpcagent

# Connect to an existing process with PID 2759
lldbclient.py -p 2759

    Esse script conecta o lldb remotamente. Para todas as flags disponíveis, execute lldbclient.py. Consulte a documentação do seu ambiente de desenvolvimento integrado para conectá-lo ao lldb.

Analisar despejos de falhas (túmulos)

Quando um serviço falha, um arquivo tombstone é gerado em /data/tombstones/. O arquivo contém um stack trace, um mapa de memória e outras informações importantes.

Extraia o arquivo de lápide e use uma ferramenta compatível com símbolos (como lldb ou um script dedicado) para analisá-lo com a versão não removida do binário.

Analisar a performance

O SDV oferece suporte a várias ferramentas para medições de performance.

Verificar o uso de CPU e memória

  • top: oferece uma visualização em tempo real dos processos em execução classificados por uso da CPU.

    adb shell top -m 10  # Show top 10 processes

  • procrank: fornece um detalhamento do uso da memória para um processo específico ou para todo o sistema.

    adb shell procrank

Usar dumpsys para estado do serviço

dumpsys é uma ferramenta poderosa para consultar o estado interno de qualquer serviço do sistema Android.

# List all available services
adb shell dumpsys -l

# Dump the state of a specific service or agent
adb shell dumpsys <service_name>

Usar o torq para análise de desempenho

O torq é uma ferramenta de linha de comando que simplifica as tarefas de criação de perfis e rastreamento no Android. Ele permite executar o Simpleperf, o Perfetto e outras tarefas típicas durante a análise de desempenho do sistema.

Usar o Perfetto para rastreamento

O Perfetto é a ferramenta padrão para rastreamento em todo o sistema no Android. Com o Perfetto, é possível gravar eventos do sistema, pontos de rastreamento no nível do app e contadores de desempenho, além de visualizá-los em uma linha do tempo.

Etapas principais:

  1. Adicione pontos de rastreamento no seu código C++ ou Rust:
    • C++:use o SDK do Perfetto com macros TRACE_EVENT.
    • Rust:use a crate tracing, que emite eventos ATrace compatíveis com o Perfetto.
  2. Crie um arquivo de configuração textproto para especificar fontes de dados (por exemplo, ftrace, track_event), categorias e tags.
  3. Use o script record_android_trace (external/perfetto/tools/record_android_trace) com seu arquivo de configuração para capturar o rastreamento do dispositivo.
  4. Abra o arquivo de rastreamento gerado na interface da Web do Perfetto para analisar o comportamento do sistema, identificar gargalos e entender as interações de serviço.

Para instruções detalhadas sobre instrumentação, configuração e coleta, consulte Usar rastreamento para ter insights sobre a performance do sistema.

Usar o Simpleperf para criação de perfil

O Simpleperf é uma ferramenta versátil de linha de comando para criação de perfis de desempenho no Android, semelhante ao Linux perf.

Casos de uso comuns:

  • Criação de perfil da CPU: identifique as funções que consomem mais tempo de CPU.
  • Análise off-CPU: analise por que as linhas de execução estão em espera ou bloqueadas.
  • Contadores de hardware: acessam contadores de desempenho de hardware.

Exemplos de comandos:

# Go to simpleperf scripts
cd system/extras/simpleperf/scripts

# Profile system for 20 seconds and record call graph
./app_profiler.py --system_wide -r "--call-graph fp --duration 20"

# Record a profile for a specific process (PID 1)
./app_profiler.py --pid 1 -r "--call-graph fp --duration 5"

# Pull the profile data
adb pull /data/local/tmp/perf.data .

# Generate a report with symbol resolution
./report_html.py --add_source_code --source_dirs $ANDROID_BUILD_TOP --add_disassembly -o report.html

O Simpleperf oferece muito mais eventos e opções. Consulte o guia do Simpleperf para ver a documentação completa.

Recusas do SELinux

Sintoma: o serviço não inicia, não acessa um arquivo ou não usa um recurso, e você vê uma mensagem avc: denied em dmesg ou logcat.

[ 123.456] avc: denied { read } for pid=789 comm="my_service" name="some_file" dev="sda1" ino=123 scontext=u:r:my_service_t:s0 tcontext=u:object_r:some_file_t:s0 tclass=file permissive=0

Depuração rápida (somente para desenvolvimento)

Você pode desativar temporariamente a aplicação do SELinux para verificar se o problema foi resolvido. Isso confirma que o problema é devido a uma regra de política do SELinux ausente.

# Disabling SELinux requires root permission
adb root

# Set SELinux to permissive mode
adb shell setenforce 0

# Check the current mode (should return "Permissive")
adb shell getenforce

Correção: use a ferramenta audit2allow da árvore de origem do Android na mensagem de negação. Isso gera a regra de política .te correta para adicionar à configuração do SELinux do dispositivo.