تصحيح أخطاء 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، لعرض هذه الملفات في الوقت الفعلي.

التفاعل مع واجهة الأوامر ونظام الملفات

يمكنك الحصول على إذن الوصول إلى shell لتنفيذ الأوامر مباشرةً على الجهاز والتحقّق من حالة العملية والتنقّل في نظام الملفات:

# 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"، وغالبًا ما يُفضَّل استخدامه في تطوير تطبيقات C++ وRust الحديثة.

اتّبِع خطوات الإعداد التالية:

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
   

   أصبح الإصدار غير المضغوط متاحًا الآن في /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. راجِع مستندات بيئة التطوير المتكاملة (IDE) لربطها ببرنامج lldb.

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

عندما تتعطّل إحدى الخدمات، يتم إنشاء ملف tombstone في /data/tombstones/. يحتوي الملف على تتبُّع تسلسل استدعاء الدوال البرمجية وخريطة الذاكرة ومعلومات مهمة أخرى.

اسحب ملف Tombstone، ثم استخدِم أداة متوافقة مع الرموز (مثل lldb أو نص برمجي مخصّص) لتحليله باستخدام الإصدار غير المُزال من الرمز الثنائي.

تحليل الأداء

تتيح "بيئة تطوير البرامج" استخدام أدوات متعددة لقياس الأداء.

التحقّق من استخدام وحدة المعالجة المركزية والذاكرة

• ‫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، وهي تشبه أداة Linux perf.

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

• تحديد ملفات تعريف وحدة المعالجة المركزية: تحديد الدوال التي تستهلك أكبر قدر من وقت وحدة المعالجة المركزية
• تحليل وقت عدم استخدام وحدة المعالجة المركزية: يمكنك تحليل سبب توقّف سلاسل التعليمات أو حظرها.
• مقاييس الأجهزة: الوصول إلى مقاييس أداء الأجهزة

أمثلة على الطلبات:

# 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 على جهازك.