Để phù hợp với mô hình phát triển ổn định của nhánh chính và đảm bảo tính ổn định của nền tảng cho hệ sinh thái, chúng tôi sẽ xuất bản mã nguồn lên AOSP vào quý 2 và quý 4 năm 2026. Để tạo và đóng góp cho AOSP, hãy sử dụng android-latest-release. Nhánh tệp kê khai android-latest-release sẽ luôn tham chiếu đến bản phát hành gần đây nhất được chuyển đến AOSP. Để biết thêm thông tin, hãy xem bài viết Các thay đổi đối với AOSP.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Gỡ lỗi SDV

Hướng dẫn này cung cấp thông tin tổng quan về các công cụ và kỹ thuật thiết yếu để gỡ lỗi các dịch vụ và ứng dụng chạy trên nền tảng SDV.

Kết nối với thiết bị

Công cụ chính để kết nối và tương tác với thiết bị là Cầu gỡ lỗi Android (adb). Xác minh rằng adb nằm trong đường dẫn của hệ thống.

Kết nối bằng mạng

Nếu thiết bị nằm trên cùng một mạng và bạn biết địa chỉ IP của thiết bị, thì bạn có thể kết nối qua Ethernet. Hệ thống của chúng tôi chỉ sử dụng kết nối mạng cho adb:

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

Kết nối với nhiều thiết bị

Để quản lý nhiều thiết bị từ một máy trạm, bạn có thể kết nối với các thiết bị đó thông qua nhiều địa chỉ IP. Nếu chạy nhiều máy ảo trên một máy chủ, bạn cần chỉ định các cổng khác nhau cho từng thiết bị. Để làm việc này, bạn cần định cấu hình trình nền adb trên mỗi thiết bị SDV để nghe trên một cổng riêng biệt, ví dụ: 5555 cho thiết bị đầu tiên và 5556 cho thiết bị thứ hai. Bạn cũng có thể định cấu hình máy chủ lưu trữ để chuyển tiếp các cổng đó đến nhiều máy khách:

# 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

Khi chạy các lệnh adb tiếp theo, bạn có thể nhắm đến một thiết bị cụ thể bằng cách sử dụng cờ -s với địa chỉ đầy đủ (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

Xem nhật ký

Khi một dịch vụ không hoạt động hoặc hoạt động không như mong đợi, hãy kiểm tra nhật ký trước tiên.

Sử dụng logcat (nhật ký Android)

logcat hiển thị nhật ký từ các dịch vụ hệ thống, tác nhân và gói dịch vụ:

# 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

Sử dụng dmesg (nhật ký nhân hệ điều hành)

dmesg hiển thị nhật ký từ nhân Linux. Điều này rất quan trọng để gỡ lỗi những vấn đề sau:

Vấn đề về phần cứng và trình điều khiển
Lỗi hoảng loạn hạt nhân
Lệnh từ chối SELinux (avc: denied) – cũng hiển thị trong logcat

# View all kernel messages
adb shell dmesg

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

Truy cập nhật ký trên Cuttlefish

Khi chạy trên thiết bị ảo Cuttlefish, bạn có thể truy cập trực tiếp vào các tệp nhật ký từ hệ thống tệp của máy chủ lưu trữ. Điều này đặc biệt hữu ích nếu không có adb. Khi bạn khởi động Cuttlefish, công cụ này sẽ xuất tất cả đường dẫn gỡ lỗi và bạn cũng có thể tra cứu các đường dẫn đó bằng cách sử dụng cvd fleet cho tất cả các thực thể đang chạy.

Logcat (nhật ký Android): cuttlefish/instances/cvd-1/logs/logcat
Nhật ký nhân hệ điều hành: cuttlefish/instances/cvd-1/logs/kernel.log
Nhật ký trình chạy Cuttlefish: cuttlefish/instances/cvd-1/logs/launcher.log (hữu ích cho việc gỡ lỗi chính môi trường Cuttlefish)

Bạn có thể sử dụng các công cụ dòng lệnh chuẩn như cat, less hoặc tail -f để xem các tệp này theo thời gian thực.

Tương tác với shell và hệ thống tệp

Có quyền truy cập vào shell để chạy lệnh trực tiếp trên thiết bị, kiểm tra trạng thái quy trình và điều hướng hệ thống tệp:

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

Thực hiện các thao tác trên hệ thống tệp

Sử dụng adb push và adb pull để di chuyển tệp giữa máy chủ và thiết bị. Sử dụng lệnh này để triển khai tập lệnh kiểm thử, cập nhật cấu hình hoặc truy xuất tệp kết xuất bộ nhớ:

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

Gỡ lỗi ứng dụng (C++/Rust)

Bạn có thể gỡ lỗi ứng dụng khi có mạng hoặc không có mạng.

Sử dụng lldb để gỡ lỗi trực tiếp

Hãy làm theo các bước sau để gỡ lỗi một dịch vụ theo thời gian thực bằng lldb (để đính kèm trình gỡ lỗi từ Android Studio cho Nền tảng, hãy xem phần Gỡ lỗi và kiểm thử và Gỡ lỗi mã nền tảng):

Khởi động lại adb bằng quyền của người dùng gốc (bắt buộc để chuyển tiếp cổng):
```
adb root
```
Nếu tệp nhị phân có biểu tượng gỡ lỗi, hãy đẩy phiên bản chưa loại bỏ từ out/target/product/[SDV_FLAVOR]/symbols/[PARTITION]/bin/[EXECUTABLE]. Ví dụ: để tải rpcagent lên từ system_ext và sdv_core_cf, hãy chạy:
```
adb push out/target/product/sdv_core_cf/symbols/system_ext/bin/rpcagent /data/local/tmp
```
Kết nối với ứng dụng LLDB bằng tập lệnh tiện lợi 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
```
Tập lệnh này kết nối lldb từ xa. Để xem tất cả cờ hiện có, hãy chạy lldbclient.py --help.

Phân tích tệp kết xuất bộ nhớ (tombstone)

Khi một dịch vụ gặp sự cố, tệp tombstone sẽ được tạo trong /data/tombstones/. Tệp này chứa dấu vết ngăn xếp, bản đồ bộ nhớ và các thông tin quan trọng khác.

Kéo tệp tombstone, sau đó sử dụng một công cụ nhận biết ký hiệu (như lldb hoặc một tập lệnh chuyên dụng) để phân tích tệp đó bằng phiên bản chưa loại bỏ của tệp nhị phân.

Phân tích hiệu suất

SDV hỗ trợ nhiều công cụ để đo lường hiệu suất.

Kiểm tra mức sử dụng CPU và bộ nhớ

top: Cung cấp chế độ xem theo thời gian thực về các quy trình đang chạy, được sắp xếp theo mức sử dụng CPU.
```
adb shell top -m 10  # Show top 10 processes
```
procrank: Cung cấp thông tin chi tiết về mức sử dụng bộ nhớ cho một quy trình cụ thể hoặc toàn bộ hệ thống.
```
adb shell procrank
```

Sử dụng dumpsys cho trạng thái dịch vụ

dumpsys là một công cụ mạnh mẽ để truy vấn trạng thái nội bộ của bất kỳ dịch vụ hệ thống Android nào.

# List all available services
adb shell dumpsys -l

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

Sử dụng torq để phân tích hiệu suất

torq là một công cụ dòng lệnh giúp đơn giản hoá các tác vụ phân tích và theo dõi trên Android. Tính năng này cho phép chạy Simpleperf, Perfetto và các tác vụ thông thường khác trong quá trình phân tích hiệu suất hệ thống.

Sử dụng Perfetto để theo dõi

Perfetto là công cụ tiêu chuẩn để theo dõi trên toàn hệ thống Android. Perfetto cho phép bạn ghi lại các sự kiện hệ thống, điểm theo dõi cấp ứng dụng và bộ đếm hiệu suất, đồng thời trực quan hoá các sự kiện đó trên dòng thời gian.

Các bước chính:

Thêm điểm theo dõi trong mã C++ hoặc Rust:
- C++: Sử dụng SDK Perfetto với macro TRACE_EVENT.
- Rust: Sử dụng crate tracing, crate này phát ra các sự kiện ATrace tương thích với Perfetto.
Tạo tệp cấu hình textproto để chỉ định nguồn dữ liệu (ví dụ: ftrace, track_event), danh mục và thẻ.
Sử dụng tập lệnh record_android_trace (external/perfetto/tools/record_android_trace) cùng với tệp cấu hình để ghi lại dấu vết từ thiết bị.
Mở tệp theo dõi đã tạo trong Giao diện người dùng web Perfetto để phân tích hành vi của hệ thống, xác định điểm tắc nghẽn và tìm hiểu các hoạt động tương tác của dịch vụ.

Để biết hướng dẫn chi tiết về khả năng đo lường, cấu hình và thu thập, hãy xem bài viết Sử dụng tính năng theo dõi để nắm bắt thông tin chi tiết về hiệu suất hệ thống.

Sử dụng Simpleperf để phân tích tài nguyên

Simpleperf là một công cụ dòng lệnh linh hoạt để phân tích hiệu suất trên Android, tương tự như Linux perf.

Các trường hợp sử dụng phổ biến:

Phân tích CPU: Xác định các hàm tiêu tốn nhiều thời gian của CPU nhất.
Phân tích ngoài CPU: Phân tích lý do các luồng ở trạng thái ngủ hoặc bị chặn.
Bộ đếm phần cứng: Truy cập vào bộ đếm hiệu suất phần cứng.

Ví dụ về lệnh:

# 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 cung cấp nhiều sự kiện và tuỳ chọn khác. Hãy tham khảo Hướng dẫn về Simpleperf để xem tài liệu đầy đủ.

Lệnh từ chối của SELinux

Dấu hiệu: Dịch vụ của bạn không khởi động được, không truy cập được vào tệp hoặc không sử dụng được một chức năng, đồng thời bạn thấy thông báo avc: denied trong dmesg hoặc 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

Gỡ lỗi nhanh (chỉ dành cho quá trình phát triển)

Bạn có thể tạm thời tắt chế độ thực thi SELinux để xem vấn đề có được giải quyết hay không. Điều này xác nhận rằng vấn đề là do thiếu quy tắc chính sách SELinux.

# 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

Cách khắc phục: Công cụ audit2allow từ cây nguồn Android trên thông báo từ chối. Thao tác này sẽ tạo quy tắc chính sách .te chính xác để thêm vào cấu hình SELinux của thiết bị.