تصحيح أخطاء SDV

يقدّم هذا الدليل نظرة عامة على الأدوات والأساليب الأساسية لتصحيح أخطاء الخدمات والتطبيقات التي تعمل على منصة SDV.

الاتصال بالجهاز

الأداة الأساسية للاتصال بالجهاز والتفاعل معه هي Android Debug Bridge (adb). تأكَّد من أنّ adb في مسار النظام.

الاتصال باستخدام الشبكة

إذا كان الجهاز متصلاً بالشبكة نفسها وكنت تعرف عنوان IP الخاص به، يمكنك الاتصال عبر شبكة إيثرنت. يستخدم نظامنا اتصالات الشبكة حصريًا لـ adb:

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

الربط بأجهزة متعددة

لإدارة أجهزة متعددة من محطة عمل واحدة، يمكنك الاتصال بها من خلال عناوين IP مختلفة. إذا كنت تشغّل عدة أجهزة افتراضية على مضيف واحد، عليك تخصيص منافذ مختلفة لكل جهاز. يتطلّب ذلك ضبط برنامج adb الخفي على كل جهاز SDV للاستماع إلى منفذ فريد، على سبيل المثال، 5555 للجهاز الأول و5556 للجهاز الثاني. يمكنك أيضًا ضبط المضيف لإعادة توجيه هذه المنافذ إلى أجهزة ضيف مختلفة:

# 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 للنظام الأساسي"، راجِع تصحيح الأخطاء والاختبار وتصحيح أخطاء رمز النظام الأساسي):

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. اتصِل بعميل LLDB باستخدام النص البرمجي المريح 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
   

   يربط هذا النص البرمجي lldb عن بُعد. للاطّلاع على جميع العلامات المتاحة، شغِّل lldbclient.py --help.

تحليل ملفات الذاكرة عند تعطّل البرنامج (Tombstones)

عند تعطُّل إحدى الخدمات، يتم إنشاء ملف 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++‎: استخدِم حزمة تطوير البرامج (SDK) من 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، وهي مشابهة لأداة perf في Linux.

حالات الاستخدام الشائعة:

• تحليل أداء وحدة المعالجة المركزية: تحديد الدوال التي تستهلك معظم وقت وحدة المعالجة المركزية
• تحليل Off-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 على جهازك.