إعداد بيئة تطوير متكاملة (IDE) لتطوير SDV

‫استوديو Android for Platform (ASfP) هو بيئة التطوير المتكاملة (IDE) المقترَحة لتطوير منصة المركبات المعرَّفة بالبرامج (SDV) في نظام التشغيل Android Automotive‏ (AAOS). يتوافق ASfP مع جميع اللغات التي تستخدمها منصة SDV في نظام التشغيل Android Automotive، بما في ذلك لغة Rust لحِزم خدمات SDV.

تتناول هذه الصفحة الإعدادات الخاصة بمركبات SDV فقط. لمزيد من المعلومات حول الميزات وسير العمل العامة في ASfP، يُرجى الاطّلاع على "استوديو Android" للمنصة.

لا تعمل ASfP إلا على نظام التشغيل Linux‏ 64 بت مع وحدات المعالجة المركزية x86-64. يمكنك استخدامه على محطة عمل Linux محلية أو في السحابة الإلكترونية. لمزيد من المعلومات حول إعداد السحابة الإلكترونية، يُرجى الاطّلاع على التطوير في السحابة الإلكترونية.

تثبيت ASfP

يبلغ الحد الأقصى التلقائي لحجم الذاكرة المؤقتة في ASfP‏ 30 غيغابايت. تستهلك فهرسة عملية الدفع في النظام الأساسي قدرًا كبيرًا من الذاكرة، خاصةً عند تشغيل أجهزة Cuttlefish متعددة الأجهزة الافتراضية على الجهاز نفسه. احرص على أن يقتصر نطاق مشروعك على الأدلة التي تعمل عليها، وعدِّل الحد الأقصى لحجم الذاكرة المؤقتة في إعدادات ذاكرة ASfP إذا لزم الأمر.

تتيح ASfP التحديثات التلقائية داخل بيئة التطوير المتكاملة (IDE). لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تحديث "استوديو Android للمنصة". لمزيد من المعلومات حول تنزيل استوديو Android for Platform وتثبيته والتحقّق من متطلبات النظام، يُرجى الاطّلاع على تثبيت Android Studio for Platform.

إنشاء مشروع SDV

يجب إعداد عملية الدفع في AAOS SDV ومزامنتها وإنشاؤها قبل البدء. لمزيد من المعلومات حول إعداد عملية الدفع، يُرجى الاطّلاع على موقع الرمز والتنزيل والإنشاء والتشغيل.

لإنشاء مشروع SDV، اتّبِع الخطوات التالية:

  1. أنشئ مشروعًا جديدًا في ASfP واختَر جذر عملية سحب SDV في AAOS كعملية سحب المستودع. لمزيد من المعلومات حول خطوات المعالج، يُرجى الاطّلاع على إنشاء مشروع أو استيراده.
  2. بعد أن تنشئ ASfP المشروع، انقر على ASfP >‏ Project >‏ Open Config لفتح ملف .asfp-project.
  3. استبدِل محتوى الملف بالمثال التالي، ثم اضبط repo على مسار الدفع:

    repo: /path/to/sdv_source
    lunch: sdv_core_cf-aosp_current-userdebug
    directories:
      include:
        -   system/software_defined_vehicle/samples
    other_languages:
      -   rust
    
  4. عدِّل lunch وdirectories للمنطقة التي تعمل فيها. للحفاظ على سرعة الفهرسة والمزامنة، يجب تضمين الأدلة التي تعدّلها بشكل نشط فقط. يسرد الجدول التالي أهداف SDV والأدلة الشائعة:

    التركيز على تطوير SDV هدف واحد (lunch) موصى بها directories
    حِزم خدمات SDV sdv_core_cf-aosp_current-userdebug دليل حِزم وكتالوج الخدمات، مثل system/software_defined_vehicle/samples
    دمج منصة SDV Core sdv_core_cf-aosp_current-userdebug system/software_defined_vehicle/middleware وsystem/software_defined_vehicle/automotive_services وdevice/google/sdv
    ‫SDV Gateway على SDV IVI sdv_ivi_cf-aosp_current-userdebug system/software_defined_vehicle/sdv_gateway وsystem/software_defined_vehicle/samples/sdv_gateway وpackages/services/Car
    عرض ميزات السلامة على وسائط SDV sdv_media_har_cf-aosp_current-userdebug packages/services/display_safety، device/google/sdv_display_safety
    عرض ميزات السلامة على نظام المعلومات والترفيه داخل المركبة (IVI) في المركبات المعرَّفة بالبرامج (SDV) sdv_ivi_cf_ds-aosp_current-userdebug packages/apps/Car/DriverUI، packages/services/display_safety/service

    إذا كانت عملية الدفع تستخدم بيان trunk_staging، استبدِل -aosp_current-userdebug بـ -trunk_staging-userdebug. لتصفُّح رمز النظام الأساسي الأصلي أيضًا، أضِف cpp إلى other_languages. لمزيد من المعلومات حول جميع خيارات الضبط، يُرجى الاطّلاع على مَعلمات الضبط.

  5. لتطبيق التغييرات، اختَر ASfP > مزامنة > مزامنة المشروع. لمزيد من المعلومات حول أوضاع المزامنة (المزامنة الكاملة والمزامنة الجزئية والمزامنة بدون إنشاء) وتصدير أو استيراد نماذج .asfp-project القابلة للمشاركة لفريقك، يُرجى الاطّلاع على أوضاع المزامنة ونافذة أدوات Soong ونماذج المشاريع القابلة للمشاركة (التصدير والاستيراد).

نشر حِزم خدمات SDV

يتضمّن ASfP مكوّنًا إضافيًا لـ SDV ينشر ملف APEX يحتوي على حِزم الخدمات مباشرةً على جهاز SDV قيد التشغيل. يكون المكوّن الإضافي غير مفعَّل تلقائيًا. لاستخدامها، يجب تفعيل المكوّن الإضافي لـ SDV من خلال الإعدادات > المكوّنات الإضافية. لمزيد من المعلومات حول حِزم APEX، يُرجى الاطّلاع على إنشاء حِزم الخدمات ونشرها.

تعتمد طريقة النشر على ما إذا كان ملف APEX متوفّرًا على الجهاز:

  • إذا كان APEX مثبّتًا، يمكنك نشر التغييرات مباشرةً من ASfP.
  • إذا كان ملف APEX جديدًا، يجب إعادة إنشاء صورة النظام وإعادة تشغيلها أولاً، أو استخدام صورة نظام تتضمّن المفتاح المستخدَم لتوقيع ملف APEX. بعد ذلك، يمكنك نشر التطبيق من ASfP.

لنشر حزمة APEX لحزمة خدمات، اتّبِع الخطوات التالية:

  1. شغِّل جهاز SDV باستخدام المكوّن الإضافي Cuttlefish. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تشغيل أجهزة SDV على Cuttlefish.
  2. افتح ملف apex/Android.bp لحزمة الخدمة وانقر على رمز تشغيل في المسافة بين الأعمدة بجانب مجموعة apex {.
  3. في القائمة التي تظهر، انقر على تشغيل "نشر APEX_NAME". يمكنك أيضًا إنشاء ملف APEX بدون نشره أو تغيير إعدادات التشغيل من القائمة نفسها.

تشغيل أجهزة SDV على Cuttlefish

يتضمّن ASfP مكوّنًا إضافيًا لـ Cuttlefish ينشئ أجهزة Cuttlefish محلية ويشغّلها. يتطلّب المكوّن الإضافي أداة تنسيق مضيف Cuttlefish. إذا لم يكن برنامج تنسيق المضيف متاحًا، سيعرض ASfP تعليمات لإعداده.

لإنشاء جهاز SDV، اتّبِع الخطوات التالية:

  1. اختَر الأدوات > أداة إدارة الأجهزة، وانقر على +، ثم اختَر إنشاء جهاز Cuttlefish.
  2. لإنشاء إعدادات متعددة للأجهزة الافتراضية، اختَر من الإعدادات الأساسية وأنشئ إعدادات خاصة بك أو استورِدها، مثل SDV Core مع SDV IVI أو SDV Media مع SDV IVI لميزة "أمان الشاشة". لإنشاء جهاز افتراضي واحد، اختَر من عملية سحب شجرة مصدر Android المحلية بدلاً من ذلك.

لعرض جميع شاشات الأجهزة الافتراضية على شاشة واحدة والوصول إلى خيارات إضافية للأجهزة، استخدِم نافذة أدوات Cuttlefish. لفتحها، انقر على الرمز ... في اللوحة الجانبية واختَر Cuttlefish، أو ابحث عن Cuttlefish في مساعدة > البحث عن إجراء. يمكنك أيضًا عرض شاشات فردية في الأجهزة المتصلة. بما أنّ SDV Core يعمل بدون شاشة، استخدِم Logcat وTerminal لفحصه.

تصحيح الأخطاء والاختبار

تتضمّن ASfP مصحِّح أخطاء LLDB مدمجًا لرموز C++‎ وRust. لمزيد من المعلومات حول تصحيح الأخطاء والاختبار في ASfP، يُرجى الاطّلاع على تصحيح أخطاء رمز النظام الأساسي وتصحيح أخطاء رمز Rust واختبار رمز النظام الأساسي باستخدام أداة atest وتصحيح أخطاء أهداف cc_test وrust_test ضمن LLDB.

عند إرفاق برنامج تصحيح الأخطاء بحزمة خدمات، يجب إرفاقه بالعملية التي تستضيفه. تستخدم أسماء العمليات تنسيق <bundle_name>:<instance_name>، مثل OrchestratorSampleRustServiceBundle:sample-main-no-conditions. يسرد الأمر التالي العمليات المطابقة ومعرّفات العمليات الخاصة بها:

adb shell ps -A | grep <bundle_name>

لمزيد من المعلومات حول سير عمل تصحيح أخطاء SDV، مثل الاتصال بأجهزة متعددة وعرض السجلات، يُرجى الاطّلاع على تصحيح أخطاء SDV.

تعديل ملفات VSIDL

تتضمّن ASfP خادم لغة VSIDL (vsidl-lsp). لمزيد من المعلومات حول كيفية إعداد الكتالوج لخادم اللغة، يُرجى الاطّلاع على التحديثات التلقائية للكتالوج والتكامل مع LSP. عندما يتضمّن الكتالوج ملف CATALOG_UPDATE، يوفّر المحرِّر الميزات التالية لملفات .vsidl:

  • التحقّق المباشر: يميّز المحرّر الكلمات الرئيسية في VSIDL ويعرض أخطاء بناء الجملة والأنواع التي لم يتم حلّها وأخطاء التحقّق من VSIDLC في نافذة المشاكل. لمزيد من المعلومات حول قواعد التحقّق من الصحة ورموز الخطأ، يُرجى الاطّلاع على مواصفات لغة VSIDL.
  • الإكمال التلقائي والتوثيق: يمكنك الضغط على Ctrl+Space للحصول على اقتراحات بشأن الكلمات الرئيسية والرسائل والخدمات والمواضيع والقنوات، والضغط على Ctrl+Q لعرض تعليقات التوثيق.
  • التنقّل والتنسيق: يمكنك الضغط على Ctrl+B للانتقال إلى تعريفات .vsidl أو .proto، وAlt+Shift+F7 للعثور على المراجع، وCtrl+F12 لعرض بنية الملف، وCtrl+Alt+L لتنسيق الملف.

إضافة سياق SDV للمساعدين المستندين إلى الذكاء الاصطناعي

يتضمّن ASfP الذكاء الاصطناعي في "استوديو Android" ووكيل مدمج مع أداة الإنشاء Soong وأدوات atest. بما أنّ ملفات AGENTS.md تكون محفوظة بجانب الرمز المصدر في نظام التحكّم في الإصدارات، يمكنك مشاركة قواعد SDV نفسها بين وكيل ASfP المضمّن ووكلاء الترميز المستندين إلى سطر الأوامر أو الحاويات الذين يقرأون ملفات AGENTS.md. عند إرسال طلب مع فتح ملف في ASfP، يحمّل الوكيل ملفات AGENTS.md من دليل هذا الملف وأدلته الرئيسية (ما لم يكن لملف GEMINI.md في الدليل نفسه الأولوية)، ويمكنك التحقّق من الملفات النشطة في لوحة الدرج السياق ضمن ملفات AGENTS.md. لمزيد من المعلومات، يُرجى الاطّلاع على مقالتَي التعرّف على &quot;استوديو Android&quot; للمنصة وتخصيص الوكيل باستخدام ملفات AGENTS.md.

توفّر النماذج التالية نقاط بداية لسير العمل في إنشاء مشروع SDV.

حِزم خدمات SDV

ضَع ملف AGENTS.md هذا في دليل الحزمة المضمّن في .asfp-project الذي يحتوي على مجلدات catalog/ وservices/ وapex/. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء برمجيات وسيطة وإنشاء حِزم الخدمات ونشرها وكتابة ملف ربط SOME/IP ونظرة عامة على تفويض الاتصالات في SDV.

# AAOS SDV service bundle and VSIDL rules

## Build and test
- Initialize the build environment (`source build/envsetup.sh` and
  `lunch sdv_core_cf-aosp_current-userdebug`) when running outside ASfP, build
  modules with Soong (`m <module_name>`), and run tests with
  `atest <TestModuleName>` (`rust_test`, `rust_test_host`, `cc_test`, or
  `python_test_host`), without creating `Cargo.toml` files or running `cargo`
- In catalog `Android.bp` files, avoid `defaults` on `rust_protobuf` modules
  (`vsidlc` uses a regex parser), include each `.proto` file in at most one
  `rust_protobuf` target, and cover all catalog files in the first `filegroup`
  (`srcs: ["**/*"]`)

## Protobuf, VSIDL, and AUTOSAR SOME/IP mapping conventions
- Keep `.proto` files limited to `message`, `enum`, and RPC `service` schemas
  (using `sdv/vsidl/v1/annotations.proto` only for field size bounds), without
  topic names, channel names, or queue capacities
- Write `.vsidl` files in TextProto `VsidlEntry` syntax (`package: "..."`,
  `service_bundle { name: "..." }`, `publisher` or `subscriber` with `message`
  and `topic`, and `server` or `client` with `service` and `channel`, without
  `import` statements; RPCs support unary, client-streaming, and
  server-streaming methods, not bidirectional streaming), and isolate
  `some_ip_mapping` (`sdv_type_mapping` and `someip_service_mapping` for
  AUTOSAR electronic control unit (ECU) `ARXML` or `vsomeip` IDs) or
  `vhal_mapping` rules in dedicated `.vsidl` mapping files so core bundles stay
  transport-independent
- Use `PascalCase` for `service_bundle` names (avoiding Rust, C++, and Java
  keywords), `snake_case` for `build_cfg.target_name`, a globally unique
  lowercase `package` with at least four segments (`com.<org>.sdv.<domain>`;
  never reuse platform-reserved `com.android.sdv.*` or sample `com.sdv.*`
  names), and lowercase dash-case starting with a letter (no consecutive or
  trailing hyphens, underscores, or slashes) for `topic`, `channel`, and
  instance names
- Set `capacity` on every `publisher` to an even integer greater than or equal
  to 2, and pair every `subscriber` and RPC `client` with a matching
  `publisher` or `server` in the catalog or its `-d` dependency catalogs

## Code generation, authorization, and APEX packaging
- Export `ANDROID_BUILD_TOP`, check `CATALOG_UPDATE` for catalog-relative
  `output_path` (such as `".."`), `dependency_catalog_paths` (`-d`), and
  `vsidlc_gen_args`, and run `vsidlc -c <catalog_dir> -o <output_dir>`; omit
  `--services` from `vsidlc_gen_args` and avoid `-p` (`--purge`) or
  `regenerator` when `output_path` holds handwritten `services/` code
- Leave generated files in `generated_rs/`, `apex/`, and `configs/` unmodified,
  and implement Rust logic in `services/<ServiceBundleName>/src/main.rs` (even
  though the initial `vsidlc --services` skeleton header says not to edit; C++
  bundles do not use `vsidlc` C++ codegen and instead use
  `libsdv_lifecycle_client_cpp`, `libsdv_comms_cpp`, and
  `sdv_service_bundle_metadata` with `native_library_path: "lib64/lib<so>.so"`
  in `sdv_service_bundles_manifest.textproto`)
- Keep communications authorization `.textproto` policies in `configs/` aligned
  with every `publisher`, `subscriber`, `server`, and `client` unit (omitting
  `capacity` inside manual authorization `.textproto` `publisher` entries) so
  Service Discovery does not reject endpoints at runtime
- In Rust bundles, wait for publisher or RPC server availability before
  creating subscribers or clients, stop active tasks in `on_stop`, and run
  blocking work in `tokio::spawn_blocking`
- Generate Rust service bundle APEXes with `vsidlc --apex` (`updatable: true`,
  `min_sdk_version: "35"`, and `product_specific: true` in `apex/Android.bp`,
  never `vendor: true` or `soc_specific: true`, with matching unique `name` and
  `version` >= 1 in `apex_manifest.json`), and do not set
  `supportsRebootlessUpdate: true` or run `adb install --force-non-staged`
  because SDV APEX updates require a reboot

بوابة SDV على SDV IVI

ضَع ملف AGENTS.md هذا في دليل وحدة عميل "المعلومات والترفيه داخل المركبة" (IVI) أو system/software_defined_vehicle/sdv_gateway/. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة استخدام SDV Gateway على نظام المعلومات والترفيه داخل المركبة (IVI).

# AAOS SDV Gateway on SDV IVI rules

- Initialize the build environment (`source build/envsetup.sh` and
  `lunch sdv_ivi_cf-aosp_current-userdebug`) when running outside ASfP, build
  IVI modules with Soong (`m <module_name>`), and run verification with
  `atest <TestModuleName>`
- For native C or C++ IVI clients (including vehicle hardware abstraction layer
  (VHAL) integrations), link `libsdvgatewayclient`
  (`#include "libsdvgatewayclient.h"`) or `ISdvGateway`; for in-tree system Java
  or Kotlin clients, use `libsdvgatewayclient-java`,
  `libsdvgatewayclient-java-sdk.stubs`, `libsdvgatewayclient-java-sdk`, and
  `com.android.sdv.gateway.client`
- Start the Binder thread pool before calling `ASDVGateway_Client_new`, and
  call `ASDVGateway_Client_initComms` (or `SdvGatewayClient.initComms`) before
  any service discovery, data tunnel, or RPC calls
- Check `ASDVGateway_Client_isRpcAvailable` or
  `ASDVGateway_Client_isProcessBoundToSdvRpcNetworkInterface` before opening
  RPC sockets on early boot, treat `ASDVGateway_StatusCode_OK` with null
  `ASDVGateway_RpcCredentials_t` as insecure `UNLOCKED` boot mode, and free
  non-null credentials with `ASDVGateway_Client_deleteRpcCredentials`
- Grant `sdv_gateway_client_domain(<domain>)` in SELinux (do not add
  `binder_use` on `/vendor` daemons, which violates Treble `neverallow`; add
  `group inet` on native init services, and `INTERNET` plus
  `CONNECTIVITY_USE_RESTRICTED_NETWORKS` privapp permissions for system Java
  RPC clients)

أمان الشبكة الإعلانية

ضَع ملف AGENTS.md هذا في packages/services/display_safety/ أو دليل تطبيق لوحة القيادة. لمزيد من المعلومات، يُرجى الاطّلاع على بدء استخدام ميزة "أمان الشاشة" وطبقة تجريد النظام الأساسي لـ HAR وسلسلة أدوات تصميم الأمان وDriverUI.

# AAOS Display Safety partner integration rules

- Display Safety spans two guest VMs with separate `lunch` targets: keep
  safety-critical telltales, gauges, camera views, chimes, and early-boot or
  fallback placeholders in the Rust high availability renderer (HAR) and safety
  monitor on SDV Media (`sdv_media_har_cf`), and build non-safety cluster UI on
  SDV IVI (`sdv_ivi_cf_ds`) using `ClusterHomeManager` (`Cluster2` rather than
  legacy `Cluster1`)
- Implement target OS and hardware subsystems (display, graphics, exterior view
  system (EVS) cameras, audio, user input, and vehicle signals) in a dedicated
  `har-platform-<target>` platform abstraction layer (PAL) crate implementing
  `har-platform-api` traits rather than modifying core `harry` framework crates,
  and verify PAL crates against the HAR platform test suite with `atest`
- Generate safety monitor configurations and telltale inspection artifacts from
  the serialized Automotive Design for Compose document and safety JSON mapping
  (`{"documents": [{"rootnode": "#...", "display_id": 1, "document_id": "...",`
  `"states": {"<signal>": "#<node_id>"}}]}`) using the safety design compiler
  rather than hardcoding telltale pixel coordinates
- Because the HAR display plane composites above Android IVI, ensure HAR clears
  the cluster viewport region to `alpha = 0.0` while valid `HeartbeatRequest`
  gRPC messages arrive from IVI, and set opaque pixels in custom HAR OpenGL ES
  surfaces to `alpha = 1.0` (`0xFF`)
- Initialize the build environment (`source build/envsetup.sh` and `lunch`) when
  running outside ASfP, integrate prebuilt cluster APKs into `sdv_ivi_cf_ds`
  through `DriverUIPrebuilt` (`overrides: ["DriverUIStubApp"]`), launch dual-VM
  Cuttlefish setups from ASfP or with `ds_toolkit launch`, pass `--user 0` to
  `adb shell am` cluster commands, and note that
  `adb shell dumpsys SurfaceFlinger` on SDV IVI inspects only Android layers
  rather than the overlying HAR plane