A partire dal 2026, per allinearci al nostro modello di sviluppo trunk stabile e garantire la stabilità della piattaforma per l'ecosistema, pubblicheremo il codice sorgente su AOSP nel secondo e nel quarto trimestre. Per compilare e contribuire ad AOSP, utilizza android-latest-release. Il branch del manifest android-latest-release farà sempre riferimento alla release più recente pubblicata su AOSP. Per saperne di più, consulta la sezione Modifiche ad AOSP.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Debug di SDV

Questa guida fornisce una panoramica degli strumenti e delle tecniche essenziali per il debug di servizi e applicazioni eseguiti sulla piattaforma SDV.

Connettiti al dispositivo

Lo strumento principale per connettersi e interagire con il dispositivo è Android Debug Bridge (adb). Verifica che adb sia nel percorso del sistema.

Connettiti utilizzando la rete

Se il dispositivo si trova sulla stessa rete e conosci il suo indirizzo IP, puoi connetterti tramite Ethernet. Il nostro sistema utilizza esclusivamente connessioni di rete per adb:

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

Connettiti a più dispositivi

Per gestire più dispositivi da una singola workstation, puoi connetterti tramite indirizzi IP diversi. Se esegui più VM su un singolo host, devi assegnare porte diverse a ogni dispositivo. Ciò richiede la configurazione del daemon adb su ogni dispositivo SDV per l'ascolto su una porta univoca, ad esempio 5555 per il primo dispositivo e 5556 per il secondo. Puoi anche configurare l'host in modo che inoltri queste porte a guest diversi:

# 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

Quando esegui i comandi adb successivi, puoi scegliere come target un dispositivo specifico utilizzando il flag -s con il suo indirizzo 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

Visualizza i log

Quando un servizio non funziona o si comporta in modo imprevisto, controlla prima i log.

Utilizza logcat (log Android)

logcat visualizza i log dei servizi di sistema, degli agenti e dei bundle di servizi:

# 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

Utilizza dmesg (log del kernel)

dmesg mostra i log del kernel Linux. Questo è fondamentale per il debug di quanto segue:

Problemi relativi ad hardware e driver
Kernel panic
Rifiuti SELinux (avc: denied): visualizzati anche in logcat

# View all kernel messages
adb shell dmesg

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

Accedi ai log su Cuttlefish

Quando esegui un dispositivo virtuale Cuttlefish, puoi accedere direttamente ai file di log dal file system della macchina host. Questo è particolarmente utile se adb non è disponibile. Quando avvii Cuttlefish, vengono visualizzati tutti i percorsi di debug, che puoi anche cercare utilizzando cvd fleet per tutte le istanze in esecuzione.

Logcat (log Android): cuttlefish/instances/cvd-1/logs/logcat
Log del kernel: cuttlefish/instances/cvd-1/logs/kernel.log
Log di avvio di Cuttlefish: cuttlefish/instances/cvd-1/logs/launcher.log (utili per il debug dell'ambiente Cuttlefish)

Puoi utilizzare strumenti a riga di comando standard come cat, less o tail -f per visualizzare questi file in tempo reale.

Interagisci con la shell e il file system

Ottieni l'accesso alla shell per eseguire i comandi direttamente sul dispositivo, controllare lo stato del processo e navigare nel file system:

# 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>

Esegui operazioni sul file system

Utilizza adb push e adb pull per spostare i file tra la macchina host e il dispositivo. Utilizzalo per eseguire il deployment di script di test, aggiornare la configurazione o recuperare dump di arresto anomalo:

# 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 .

Esegui il debug delle applicazioni (C++/Rust)

Puoi eseguire il debug delle applicazioni sia online che offline.

Utilizza lldb per il debug in tempo reale

Segui questi passaggi per eseguire il debug di un servizio in tempo reale utilizzando lldb (per collegare il debugger da Android Studio for Platform, consulta Esegui il debug e il test e Esegui il debug del codice della piattaforma):

Riavvia adb con le autorizzazioni root (necessarie per il port forwarding):
```
adb root
```
Se un programma binario ha simboli di debug, esegui il push di una versione non sottoposta a stripping da out/target/product/[SDV_FLAVOR]/symbols/[PARTITION]/bin/[EXECUTABLE]. Ad esempio, per caricare rpcagent da system_ext e sdv_core_cf, esegui:
```
adb push out/target/product/sdv_core_cf/symbols/system_ext/bin/rpcagent /data/local/tmp
```

Connettiti al client LLDB utilizzando lo script di utilità 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

Questo script connette lldb da remoto. Per tutti i flag disponibili, esegui lldbclient.py --help.

Analizza i dump di arresto anomalo (tombstone)

Quando un servizio si arresta in modo anomalo, viene generato un file tombstone in /data/tombstones/. Il file contiene un'analisi dello stack, una mappa della memoria e altre informazioni cruciali.

Estrai il file tombstone, quindi utilizza uno strumento che riconosce i simboli (come lldb o uno script dedicato) per analizzarlo con la versione non sottoposta a stripping del file binario.

Analizza le prestazioni

SDV supporta più strumenti per le misurazioni delle prestazioni.

Controlla l'utilizzo di CPU e memoria

top: fornisce una visualizzazione in tempo reale dei processi in esecuzione ordinati in base all'utilizzo della CPU.
```
adb shell top -m 10  # Show top 10 processes
```
procrank: fornisce un'analisi dettagliata della memoria utilizzata per un processo specifico o per l'intero sistema.
```
adb shell procrank
```

Utilizza dumpsys per lo stato del servizio

dumpsys è uno strumento potente per eseguire query sullo stato interno di qualsiasi servizio di sistema Android.

# List all available services
adb shell dumpsys -l

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

Utilizza torq per l'analisi delle prestazioni

torq è uno strumento a riga di comando che semplifica le attività di profilazione e tracciamento su Android. Consente di eseguire Simpleperf, Perfetto e altre attività tipiche durante l'analisi delle prestazioni del sistema.

Utilizza Perfetto per il tracciamento

Perfetto è lo strumento standard per il tracciamento a livello di sistema su Android. Perfetto ti consente di registrare eventi di sistema, punti di traccia a livello di app e contatori delle prestazioni, nonché di visualizzarli su una sequenza temporale.

Passaggi principali:

Aggiungi punti di tracciamento nel codice C++ o Rust:
- C++: utilizza l'SDK Perfetto con le macro TRACE_EVENT.
- Ruggine: Utilizzare la crate tracing, che emette eventi ATrace compatibili con Perfetto.
Crea un file di configurazione textproto per specificare le origini dati (ad esempio ftrace, track_event), le categorie e i tag.
Utilizza lo script record_android_trace (external/perfetto/tools/record_android_trace) con il file di configurazione per acquisire la traccia dal dispositivo.
Apri il file di traccia generato nell'interfaccia utente web di Perfetto per analizzare il comportamento del sistema, identificare i colli di bottiglia e comprendere le interazioni dei servizi.

Per istruzioni dettagliate su strumentazione, configurazione e raccolta, consulta Utilizza il tracciamento per ottenere informazioni sulle prestazioni del sistema.

Utilizza Simpleperf per la profilazione

Simpleperf è uno strumento a riga di comando versatile per la profilazione delle prestazioni su Android, simile a Linux perf.

Casi d'uso comuni:

Profilazione della CPU: identifica le funzioni che consumano più tempo di CPU.
Analisi off-CPU: analizza il motivo per cui i thread sono in stato di sospensione o bloccati.
Contatori hardware: accedi ai contatori delle prestazioni hardware.

Comandi di esempio:

# 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

Simpleperf offre molti altri eventi e opzioni. Per la documentazione completa, consulta la guida di Simpleperf.

Rifiuti di SELinux

Sintomo: il servizio non si avvia, non accede a un file o non utilizza una funzionalità e viene visualizzato un messaggio avc: denied in dmesg o 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

Debug rapido (solo per lo sviluppo)

Puoi disattivare temporaneamente l'applicazione di SELinux per vedere se il problema viene risolto. Ciò conferma che il problema è dovuto a una regola della policy SELinux mancante.

# 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

Correzione: lo strumento audit2allow dell'albero di origine Android nel messaggio di rifiuto. In questo modo viene generata la regola della policy .te corretta da aggiungere alla configurazione SELinux del dispositivo.