Thiết lập một IDE để phát triển SDV

Android Studio for Platform (ASfP) là môi trường phát triển tích hợp (IDE) được đề xuất để phát triển nền tảng Xe dựa trên phần mềm (SDV) của Android Automotive OS (AAOS). ASfP hỗ trợ tất cả ngôn ngữ mà nền tảng SDV của AAOS sử dụng, bao gồm cả Rust cho các gói dịch vụ SDV.

Trang này chỉ đề cập đến quy trình thiết lập dành riêng cho SDV. Để biết thêm thông tin về các tính năng và quy trình công việc chung của ASfP, hãy xem bài viết Android Studio for Platform.

ASfP chỉ chạy trên Linux 64 bit có CPU x86-64. Bạn có thể sử dụng công cụ này trên máy trạm Linux cục bộ hoặc trên đám mây. Để biết thêm thông tin về cách thiết lập đám mây, hãy xem phần Phát triển đám mây.

Cài đặt ASfP

ASfP mặc định có kích thước vùng nhớ khối xếp tối đa là 30 GB. Việc lập chỉ mục một quy trình thanh toán trên nền tảng sẽ tốn rất nhiều bộ nhớ, đặc biệt là khi bạn cũng chạy các thiết bị Cuttlefish nhiều máy ảo trên cùng một máy. Giữ cho dự án của bạn nằm trong phạm vi các thư mục mà bạn làm việc, và điều chỉnh kích thước vùng nhớ khối xếp tối đa trong phần cài đặt bộ nhớ ASfP nếu cần.

ASfP hỗ trợ cập nhật tự động trong IDE. Để biết thêm thông tin, hãy xem bài viết Cập nhật Android Studio cho nền tảng. Để biết thêm thông tin về cách tải xuống và cài đặt ASfP cũng như kiểm tra các yêu cầu về hệ thống, hãy xem bài viết Cài đặt Android Studio cho Nền tảng.

Tạo dự án SDV

Khởi động, đồng bộ hoá và tạo bản dựng AAOS SDV trước khi bắt đầu. Để biết thêm thông tin về cách thiết lập quy trình thanh toán, hãy xem phần Vị trí mã và Tải xuống, tạo và chạy.

Để tạo một dự án SDV, hãy làm theo các bước sau:

  1. Tạo một dự án mới trong ASfP rồi chọn thư mục gốc của quy trình kiểm tra AAOS SDV làm quy trình kiểm tra kho lưu trữ. Để biết thêm thông tin về các bước của trình hướng dẫn, hãy xem phần Tạo hoặc nhập dự án.
  2. Sau khi ASfP tạo dự án, hãy chọn ASfP > Project > Open Config (ASfP > Dự án > Mở cấu hình) để mở tệp .asfp-project.
  3. Thay thế nội dung của tệp bằng ví dụ sau, rồi đặt repo thành đường dẫn của trang thanh toán:

    repo: /path/to/sdv_source
    lunch: sdv_core_cf-aosp_current-userdebug
    directories:
      include:
        -   system/software_defined_vehicle/samples
    other_languages:
      -   rust
    
  4. Cập nhật lunch và directories cho khu vực bạn làm việc. Để duy trì tốc độ lập chỉ mục và đồng bộ hoá nhanh, chỉ thêm các thư mục mà bạn chủ động sửa đổi. Bảng sau đây liệt kê các mục tiêu và thư mục SDV phổ biến:

    Trọng tâm phát triển SDV lunch mục tiêu directories được đề xuất
    Gói dịch vụ SDV sdv_core_cf-aosp_current-userdebug Danh mục dịch vụ và thư mục gói của bạn, chẳng hạn như system/software_defined_vehicle/samples
    Tích hợp nền tảng SDV Core sdv_core_cf-aosp_current-userdebug system/software_defined_vehicle/middleware, system/software_defined_vehicle/automotive_services, device/google/sdv
    Cổng SDV trên SDV IVI sdv_ivi_cf-aosp_current-userdebug system/software_defined_vehicle/sdv_gateway, system/software_defined_vehicle/samples/sdv_gateway, packages/services/Car
    Hiển thị thông tin an toàn trên SDV Media sdv_media_har_cf-aosp_current-userdebug packages/services/display_safety, device/google/sdv_display_safety
    An toàn khi hiển thị trên IVI của SDV sdv_ivi_cf_ds-aosp_current-userdebug packages/apps/Car/DriverUI, packages/services/display_safety/service

    Nếu quy trình thanh toán của bạn sử dụng tệp kê khai trunk_staging, hãy thay thế -aosp_current-userdebug bằng -trunk_staging-userdebug. Để duyệt xem cả mã nền tảng gốc, hãy thêm cpp vào other_languages. Để biết thêm thông tin về tất cả các lựa chọn cấu hình, hãy xem phần Thông số cấu hình.

  5. Để áp dụng các thay đổi, hãy chọn ASfP > Sync > Sync Project (ASfP > Đồng bộ hoá > Đồng bộ hoá dự án). Để biết thêm thông tin về các chế độ đồng bộ hoá (Đồng bộ hoá toàn bộ, Đồng bộ hoá một phần và Đồng bộ hoá không cần bản dựng) cũng như cách xuất hoặc nhập các mẫu .asfp-project có thể chia sẻ cho nhóm của bạn, hãy xem phần Chế độ đồng bộ hoá và cửa sổ công cụ Soong và Mẫu dự án có thể chia sẻ (xuất và nhập).

Triển khai gói dịch vụ SDV

ASfP có một trình bổ trợ SDV để triển khai một APEX chứa các gói dịch vụ của bạn trực tiếp vào một thiết bị SDV đang chạy. Trình bổ trợ này bị tắt theo mặc định. Để sử dụng, hãy bật trình bổ trợ SDV trong phần Settings > Plugins (Cài đặt > Trình bổ trợ). Để biết thêm thông tin về việc đóng gói APEX, hãy xem phần Tạo và triển khai gói dịch vụ.

Cách bạn triển khai phụ thuộc vào việc APEX đã có trên thiết bị hay chưa:

  • Nếu đã cài đặt APEX, bạn có thể triển khai các thay đổi trực tiếp từ ASfP.
  • Nếu APEX là mới, trước tiên, bạn phải tạo lại và chạy lại hình ảnh hệ thống hoặc sử dụng hình ảnh hệ thống có chứa khoá dùng để ký APEX. Sau đó, bạn có thể triển khai từ ASfP.

Để triển khai APEX gói dịch vụ, hãy làm theo các bước sau:

  1. Khởi động thiết bị SDV bằng trình bổ trợ Cuttlefish. Để biết thêm thông tin, hãy xem bài viết Chạy thiết bị SDV trên Cuttlefish.
  2. Mở tệp apex/Android.bp của gói dịch vụ rồi nhấp vào biểu tượng Run (Chạy) trong lề bên cạnh khối apex {.
  3. Trong trình đơn mở ra, hãy chọn Run "Deploy APEX_NAME" (Chạy "Triển khai"). Bạn cũng có thể tạo APEX mà không cần triển khai hoặc thay đổi cấu hình chạy trong cùng một trình đơn.

Chạy thiết bị SDV trên Cuttlefish

ASfP có một trình bổ trợ Cuttlefish giúp tạo và chạy các thiết bị Cuttlefish cục bộ. Trình bổ trợ này cần có trình điều phối máy chủ Cuttlefish. Nếu không có trình điều phối máy chủ, ASfP sẽ hiển thị hướng dẫn thiết lập.

Để tạo một thiết bị SDV, hãy làm theo các bước sau:

  1. Chọn Tools > Device Manager (Công cụ > Trình quản lý thiết bị), nhấp vào + rồi chọn Create Cuttlefish Device (Tạo thiết bị Cuttlefish).
  2. Để tạo một chế độ thiết lập nhiều máy ảo, hãy chọn From canonical configuration (Từ cấu hình chính tắc) rồi tạo hoặc nhập một cấu hình cho chế độ thiết lập của bạn, chẳng hạn như SDV Core với SDV IVI hoặc SDV Media với SDV IVI cho Display Safety. Để tạo một máy ảo, hãy chọn From local Android source tree checkout (Từ quy trình kiểm tra cây nguồn Android cục bộ).

Để xem tất cả màn hình máy ảo trên một màn hình và truy cập vào các tuỳ chọn thiết bị khác, hãy sử dụng cửa sổ công cụ Cuttlefish. Để mở, hãy chọn biểu tượng ... trong bảng điều khiển bên rồi chọn Cuttlefish hoặc tìm Cuttlefish trong phần Help > Find Action (Trợ giúp > Tìm thao tác). Bạn cũng có thể xem từng màn hình trong Running Devices (Thiết bị đang chạy). Vì SDV Core chạy mà không có màn hình, hãy sử dụng Logcat và Terminal để kiểm tra.

Gỡ lỗi và kiểm thử

ASfP có một trình gỡ lỗi LLDB tích hợp sẵn cho mã C++ và Rust. Để biết thêm thông tin về cách gỡ lỗi và kiểm thử trong ASfP, hãy xem bài viết Gỡ lỗi mã nền tảng, Gỡ lỗi mã Rust, Kiểm thử mã nền tảng bằng atest và Gỡ lỗi mục tiêu cc_test và rust_test trong LLDB.

Khi bạn đính kèm trình gỡ lỗi vào một gói dịch vụ, hãy đính kèm vào quy trình lưu trữ gói dịch vụ đó. Tên quy trình sử dụng định dạng <bundle_name>:<instance_name>, chẳng hạn như OrchestratorSampleRustServiceBundle:sample-main-no-conditions. Lệnh sau đây liệt kê các tiến trình phù hợp và mã định danh tiến trình của các tiến trình đó:

adb shell ps -A | grep <bundle_name>

Để biết thêm thông tin về quy trình gỡ lỗi SDV, chẳng hạn như kết nối với nhiều thiết bị và xem nhật ký, hãy xem phần Gỡ lỗi SDV.

Chỉnh sửa tệp VSIDL

ASfP bao gồm Máy chủ ngôn ngữ VSIDL (vsidl-lsp). Để biết thêm thông tin về cách thiết lập danh mục cho máy chủ ngôn ngữ, hãy xem phần Tự động cập nhật danh mục và tích hợp LSP. Khi danh mục của bạn có tệp CATALOG_UPDATE, trình chỉnh sửa sẽ cung cấp các tính năng sau cho tệp .vsidl:

  • Xác thực trực tiếp: Trình chỉnh sửa làm nổi bật các từ khoá VSIDL và cho thấy lỗi cú pháp, các loại chưa được giải quyết và lỗi xác thực VSIDLC trong cửa sổ Vấn đề. Để biết thêm thông tin về các quy tắc xác thực và mã lỗi, hãy xem quy cách ngôn ngữ VSIDL.
  • Tự động hoàn thành và tài liệu: Bạn có thể nhấn tổ hợp phím Ctrl+Space để xem các đề xuất về từ khoá, thông báo, dịch vụ, chủ đề và kênh, đồng thời nhấn tổ hợp phím Ctrl+Q để xem nhận xét về tài liệu.
  • Thao tác và định dạng: Bạn có thể nhấn tổ hợp phím Ctrl+B để chuyển đến định nghĩa .vsidl hoặc .proto, nhấn tổ hợp phím Alt+Shift+F7 để tìm tệp đối chiếu, nhấn tổ hợp phím Ctrl+F12 để xem cấu trúc tệp và nhấn tổ hợp phím Ctrl+Alt+L để định dạng tệp.

Thêm bối cảnh SDV cho trợ lý AI

ASfP tích hợp AI trong Android Studio và một tác nhân tích hợp sẵn có các công cụ và bản dựng Soong atest. Vì các tệp AGENTS.md nằm cùng với mã nguồn trong hệ thống quản lý phiên bản, nên bạn có thể chia sẻ cùng một quy tắc SDV cho tác nhân tích hợp sẵn của ASfP và các tác nhân lập trình dựa trên vùng chứa hoặc dòng lệnh đọc AGENTS.md. Khi bạn gửi câu lệnh có tệp đang mở trong ASfP, tác nhân sẽ tải các tệp AGENTS.md từ thư mục của tệp đó và các thư mục mẹ của tệp đó (trừ phi một tệp GEMINI.md trong cùng thư mục được ưu tiên) và bạn có thể xác minh các tệp đang hoạt động trong ngăn Bối cảnh của bảng trò chuyện trong phần Tệp AGENTS.md. Để biết thêm thông tin, hãy xem bài viết Làm quen với Android Studio cho Nền tảng và Tuỳ chỉnh tác nhân bằng tệp AGENTS.md.

Các mẫu sau đây cung cấp điểm khởi đầu cho quy trình công việc trong phần Tạo dự án SDV.

Gói dịch vụ SDV

Đặt tệp AGENTS.md này vào thư mục gói có trong .asfp-project, bao gồm các thư mục catalog/, services/ và apex/. Để biết thêm thông tin, hãy xem các bài viết Tạo phần mềm trung gian, Tạo và triển khai gói dịch vụ, Viết tệp ánh xạ SOME/IP và Tổng quan về việc uỷ quyền giao tiếp 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

Cổng SDV trên SDV IVI

Đặt tệp AGENTS.md này vào thư mục mô-đun ứng dụng IVI hoặc system/software_defined_vehicle/sdv_gateway/. Để biết thêm thông tin, hãy xem bài viết Sử dụng Cổng SDV trên 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)

An toàn khi hiển thị

Đặt tệp AGENTS.md này vào packages/services/display_safety/ hoặc thư mục ứng dụng cụm đồng hồ. Để biết thêm thông tin, hãy xem bài viết Bắt đầu sử dụng tính năng An toàn khi hiển thị, Lớp trừu tượng nền tảng HAR, Chuỗi công cụ thiết kế an toàn và 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