اشکال‌زدایی SDV

این راهنما نمای کلی‌ای از ابزارها و تکنیک‌های ضروری برای اشکال‌زدایی سرویس‌ها و برنامه‌هایی که در پلاتفرم «خودرو نرم‌افزارمحور» اجرا می‌شوند ارائه می‌دهد.

متصل شدن به دستگاه

ابزار اصلی برای اتصال به دستگاه و تعامل با آن پل اشکال‌زدایی Android (adb) است. مطمئن شوید adb در مسیر سیستم شما قرار دارد.

اتصال بااستفاده از شبکه

اگر دستگاه در همان شبکه باشد و نشانی IP آن را بدانید، می‌توانید ازطریق اترنت متصل شوید. سیستم ما منحصراً از اتصالات شبکه برای adb استفاده می‌کند:

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

اتصال به چند دستگاه

برای مدیریت چندین دستگاه از یک ایستگاه کاری، می‌توانید ازطریق نشانی‌های IP مختلف به آن‌ها متصل شوید. اگر چند ماشین مجازی را روی یک میزبان اجرا می‌کنید، باید درگاه‌های مختلفی را به هر دستگاه اختصاص دهید. این کار مستلزم پیکربندی کردن دیمون adb در هر دستگاه SDV است تا به درگاه یکتایی گوش دهد، برای مثال، ۵۵۵۵ برای دستگاه اول و ۵۵۵۶ برای دستگاه دوم. همچنین می‌توانید میزبان را برای بازارسال آن درگاه‌ها به مهمانان مختلف پیکربندی کنید:

# 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

وقتی فرمان‌های adb بعدی را اجرا می‌کنید، می‌توانید دستگاه خاصی را بااستفاده از پرچم -s با نشانی کامل آن (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

مشاهده گزارش‌ها

وقتی سرویسی ازکار می‌افتد یا رفتار غیرمنتظره‌ای دارد، ابتدا گزارش‌ها را بررسی کنید.

استفاده از logcat (گزارش‌های Android)

logcat گزارش‌های مربوط به سرویس‌های سیستم، عامل‌ها، و بسته‌های سرویس را نمایش می‌دهد:

# 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

استفاده از dmesg (گزارش‌های هسته)

dmesg گزارش‌های هسته Linux را نمایش می‌دهد. این برای اشکال‌زدایی موارد زیر بسیار مهم است:

• مشکلات سخت‌افزار و درایور
• کرنل پنیک
• رد کردن‌های SELinux‏ (avc: denied) - در logcat نیز نمایش داده می‌شود

# View all kernel messages
adb shell dmesg

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

گزارش‌های دسترسی در Cuttlefish

وقتی روی دستگاه مجازی Cuttlefish اجرا می‌کنید، می‌توانید مستقیماً به فایل‌های گزارش از سیستم فایل دستگاه میزبان دسترسی داشته باشید. این ویژگی به‌ویژه زمانی مفید است که adb دردسترس نباشد. وقتی Cuttlefish را راه‌اندازی می‌کنید، همه مسیرهای اشکال‌زدایی را برونداد می‌کند و همچنین می‌توانید آن‌ها را بااستفاده از cvd fleet برای همه نمونه‌های درحال اجرا جستجو کنید.

• Logcat (گزارش‌های Android): cuttlefish/instances/cvd-1/logs/logcat
• گزارش‌های هسته: cuttlefish/instances/cvd-1/logs/kernel.log
• گزارش‌های راه‌انداز Cuttlefish: cuttlefish/instances/cvd-1/logs/launcher.log (مفید برای اشکال‌زدایی خود محیط Cuttlefish)

می‌توانید از ابزارهای خط فرمان استاندارد مانند cat، less، یا tail -f برای مشاهده این فایل‌ها در زمان واقعی استفاده کنید.

تعامل با پوسته و سیستم فایل

دسترسی به پوسته برای اجرای مستقیم فرمان‌ها در دستگاه، بررسی وضعیت پردازش، و پیمایش سیستم فایل:

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

اجرای عملیات سیستم فایل

از adb push و adb pull برای انتقال فایل‌ها بین دستگاه میزبان و دستگاه استفاده کنید. از این مورد برای استقرار دستورگان آزمایشی، به‌روزرسانی پیکربندی، یا بازیابی رونوشت خرابی استفاده کنید:

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

اشکال‌زدایی برنامه‌ها (C++/Rust)

می‌توانید برنامه‌ها را به‌صورت آنلاین یا آفلاین اشکال‌زدایی کنید.

استفاده از lldb برای اشکال‌زدایی زنده

این مراحل را برای اشکال‌زدایی هم‌زمان سرویس بااستفاده از lldb دنبال کنید (برای پیوست کردن اشکال‌زدا از Android Studio برای پلاتفرم، به اشکال‌زدایی و آزمایش و اشکال‌زدایی کد پلاتفرم مراجعه کنید):

1. بازراه‌اندازی adb با اجازه‌های ریشه (برای بازارسال درگاه لازم است):

   adb root
   

2. اگر باینری نمادهای اشکال‌زدایی دارد، نسخه حذف‌نشده را از out/target/product/[SDV_FLAVOR]/symbols/[PARTITION]/bin/[EXECUTABLE] ارسال کنید. برای مثال، برای بارگذاری rpcagent از system_ext و sdv_core_cf، این دستور را اجرا کنید:

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

3. بااستفاده از اسکریپت راحتی lldbclient.py به کارخواه LLDB متصل شوید:

   # 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
   

   این دستورگان lldb را از راه دور متصل می‌کند. برای همه پرچم‌های دردسترس، lldbclient.py --help را اجرا کنید.

تجزیه‌وتحلیل رونوشت‌های خرابی (سنگ‌قبرها)

وقتی سرویسی ازکار می‌افتد، فایل tombstone در /data/tombstones/ ایجاد می‌شود. این فایل حاوی ردیابی پشته‌ای، نقشه حافظه، و اطلاعات مهم دیگر است.

فایل tombstone را بکشید، سپس از ابزار آگاه از نماد (مانند lldb یا اسکریپت اختصاصی) برای تجزیه‌وتحلیل آن با نسخه حذف‌نشده باینری استفاده کنید.

تحلیل عملکرد

‫SDV از چندین ابزار برای اندازه‌گیری عملکرد پشتیبانی می‌کند.

بررسی استفاده از CPU و حافظه

• ‫top: نمای هم‌زمان از فرایندهای درحال اجرا را که براساس میزان استفاده از واحد پردازش مرکزی مرتب شده‌اند ارائه می‌دهد.

  adb shell top -m 10  # Show top 10 processes
  

• ‫procrank: تفکیک دقیقی از استفاده از حافظه برای یک فرایند خاص یا کل سیستم ارائه می‌دهد.

  adb shell procrank
  

استفاده از dumpsys برای وضعیت سرویس

‫dumpsys ابزاری قدرتمند برای پُرسمان وضعیت داخلی هر سرویس سیستم Android است.

# List all available services
adb shell dumpsys -l

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

استفاده از torq برای تحلیل عملکرد

torq ابزاری با رابط خط فرمان است که کارهای نمایه‌سازی و ردیابی را در Android ساده می‌کند. این گزینه امکان اجرای Simpleperf،‏ Perfetto، و دیگر تکالیف معمول را درطول تجزیه‌وتحلیل عملکرد سیستم فراهم می‌کند.

استفاده از Perfetto برای ردیابی

Perfetto ابزار استاندارد برای ردیابی سراسری سیستم در Android است. Perfetto به شما امکان می‌دهد رویدادهای سیستم، نقاط ردیابی سطح برنامه، و شمارنده‌های عملکرد را ضبط کنید و آن‌ها را در خط زمان تجسم کنید.

مراحل کلیدی:

1. نقاط ردیابی را در کد C++‎ یا Rust خود اضافه کنید:
   • C++: از کیت توسعه نرم‌افزار Perfetto با ماکروهای TRACE_EVENT استفاده کنید.
   • Rust: از جعبه tracing استفاده کنید که رویدادهای ATrace سازگار با Perfetto را منتشر می‌کند.
2. یک فایل پیکربندی textproto برای مشخص کردن منابع داده (برای مثال، ftrace، track_event)، دسته‌ها، و برچسب‌ها ایجاد کنید.
3. از دستورات record_android_trace (external/perfetto/tools/record_android_trace) با فایل پیکربندی‌تان استفاده کنید تا ردیابی را از دستگاه ضبط کنید.
4. فایل ردیابی تولیدشده را در رابط کاربری وب Perfetto باز کنید تا رفتار سیستم را تحلیل کنید، گلوگاه‌ها را شناسایی کنید، و تعاملات سرویس را درک کنید.

برای دستورالعمل‌های دقیق درباره ابزار دقیق، پیکربندی، و جمع‌آوری، به استفاده از ردیابی برای کسب اطلاعات آماری درباره عملکرد سیستم مراجعه کنید.

استفاده از Simpleperf برای نمایه‌سازی

Simpleperf یک ابزار خط فرمان همه‌کاره برای نمایه‌سازی عملکرد در Android است، مشابه Linux perf.

موارد استفاده رایج:

• نمایه‌سازی واحد پردازش مرکزی: توابعی را که بیشترین زمان واحد پردازش مرکزی را مصرف می‌کنند شناسایی کنید.
• تجزیه‌وتحلیل غیرCPU: تجزیه‌وتحلیل کنید که چرا رشته‌ها در حالت خواب یا مسدود هستند.
• شمارنده‌های سخت‌افزاری: به شمارنده‌های عملکرد سخت‌افزار دسترسی پیدا کنید.

نمونه فرمان‌ها:

# 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 رویدادها و گزینه‌های بسیار بیشتری ارائه می‌دهد. برای اسناد جامع، به راهنمای Simpleperf مراجعه کنید.

رد کردن‌های SELinux

نشانه: سرویس شما شروع نمی‌شود، به فایلی دسترسی ندارد، یا از قابلیتی استفاده نمی‌کند، و پیام avc: denied را در dmesg یا 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

اشکال‌زدایی سریع (فقط برای توسعه)

می‌توانید اجرای SELinux را موقتاً غیرفعال کنید تا ببینید مشکل برطرف می‌شود یا نه. این موضوع تأیید می‌کند که مشکل به‌دلیل نبود قانون خط‌مشی 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

رفع مشکل: ابزار audit2allow از درخت منبع Android در پیام رد. با این کار، قانون خط‌مشی .te صحیح برای افزودن به پیکربندی SELinux دستگاهتان تولید می‌شود.