診斷

SDV 平台提供一組 API，可用於 OEM 提供的 Diagnostics Manager 和 SDV 服務套件之間，以及公用程式和一般平台功能，以支援 OEM 的診斷用途。診斷是我們為 OEM 提供的 SDV 服務、汽車服務和技術的必要環節，因為診斷堆疊是任何汽車作業系統的重要元件。

原始設備製造商 (OEM) 會部署 Diagnostics Manager 執行個體 (通常每個 ECU 或每個 VM 各一個)，與系統上的 SDV 服務套件通訊，處理診斷用戶端的請求。為此，SDV 提供一組標準診斷 API、公用程式，以及 OEM 診斷用途的整體平台支援。我們的目標是：

  • 讓原始設備製造商 (OEM) 根據 UDS 標準導入 Diagnostics Manager。
  • 允許 Diagnostics Manager 將測試人員要求委派給 SDV 服務套件。
  • 允許 SDV 服務套件以與車輛無關的方式公開診斷資料。

為達成此目標，SDV 提供一組 API，可將 SDV 服務套件 (可能由第三方提供) 與 OEM 的診斷堆疊實作項目之間的互動標準化。

診斷堆疊

圖 1. 診斷堆疊。

SDV 服務套件可以公開診斷資料和實體、實作診斷功能，以及向診斷管理員回報故障情形。

我們提供標準的 SDV 範圍診斷 API，簡化 SDV 服務套件的實作程序，避免在不同 OEM 的不同車輛上執行診斷時，需要重新實作診斷程序。

診斷服務 API

SDV Diagnostics API 定義下列服務，這些服務對應於特定 UDS (ISO 14229-1) 服務：

  • service AuthenticationService：0x29 (驗證)。這項機制可讓用戶端證明自己的身分，以存取受限的資料或服務。
  • service DataItemService：0x22 (ReadDataByIdentifier) 和 0x2E (WriteDataByIdentifier)。可讀取及寫入 DID 所識別的資料元素。
  • service EcuResetService：0x11 (ECUReset)。測試人員可藉此要求重設 ECU。
  • service FileTransferService：0x34 (RequestDownload)、0x35 (RequestUpload)、0x36 (TransferData)、0x37 (RequestTransferExit) 和 0x38 (RequestFileTransfer)。負責啟動及處理檔案下載和上傳作業。
  • service IoControlService：0x2F (InputOutputControlByIdentifier)。外部測試人員可藉此控制系統的輸入和輸出內容，以進行測試。
  • service RoutineControlService：0x31 (RoutineControl)。測試人員可以藉此啟動及停止 SDV 服務實作的特定常式 (函式)，並要求取得結果。
  • service SecurityAccessService：0x27 (SecurityAccess)。這項服務會管理解鎖特定安全等級所需的種子和金鑰交換作業。

SDV 診斷 API 另外根據 AUTOSAR 的診斷事件管理員 (AUTOSAR_SWS_DiagnosticEventManager) 定義 service FaultListenerService 和 message Event，讓應用程式回報診斷事件和故障情形。

此外，service DiagnosticsManagerService 定義了 SDV 平台服務，可讓其他服務查詢目前的診斷連線參數 (來源位址、目標位址) 和工作階段類型。

服務套裝組合開發人員指南

服務套件開發人員可以在對應的 .vsidl 檔案中定義 diagnostics_declaration 和下列伺服器：

service_bundle {
    name: "<BUNDLE-NAME>"
    ...
    server {
        service: "com.sdv.google.diagnostics.data_item.DataItemService"
    }
    server {
        service: "com.sdv.google.diagnostics.routine_control.RoutineControlService"
    }
    server {
        service: "com.sdv.google.diagnostics.io_control.IoControlService"
    }
    server {
        service: "com.sdv.google.diagnostics.fault.FaultListenerService"
    }
    ...
    diagnostics_declaration {
        data_item {
            ...
        }

        routine {
            ...
        }

        event {
            ...
        }

        io_control {
            ...
        }
    }
    ...
}

DiagnosticsDeclaration 訊息定義如下：

package sdv.diagnostics.v1;

message DiagnosticsDeclaration {
  // Diagnostics data item declaration.
  //
  // See com.sdv.google.diagnostics.data_item.DataItemService service.
  message DataItem {
    // Required. Id of the data item.
    string id = 1;

    // Required. Fully qualified name of the message that defines a structure of
    // the data item.
    string message_name = 2;

    // Flag that indicates whether the data item is writable by the Diagnostics
    // Manager.
    //
    // Effectively, this indicates whether the call to DataItemService::Write,
    // is supported for this data item id.
    bool is_writable = 3;
  }

  // Declaration of diagnostics data for input/output control.
  //
  // See com.sdv.google.diagnostics.io_control.IoControl service.
  message InputOutputControlData {
    // Id of the input/output control data.
    string id = 1;

    // Fully qualified name of the message that defines a structure of the data.
    string message_name = 2;
  }

  // Declaration of diagnostics routine.
  //
  // See com.sdv.google.diagnostics.routine_control.RoutineControl.
  message Routine {
    // Information about routine control method.
    message Method {
      // Fully qualified name of the request message.
      string request = 1;

      // Fully qualified name of the response message.
      string response = 2;
    }

    // Id of the routine.
    string id = 1;

    // Information about routine start method.
    //
    // See com.sdv.google.diagnostics.routine_control.RoutineControl::Start.
    Method start = 2;

    // Information about routine stop method.
    //
    // See com.sdv.google.diagnostics.routine_control.RoutineControl::Stop.
    Method stop = 3;

    // Information about routine result method.
    //
    // See
    // com.sdv.google.diagnostics.routine_control.RoutineControl::RequestResult.
    Method result = 4;
  }

  // Declaration of diagnostics event and corresponding fault listener.
  //
  // See com.sdv.google.diagnostics.event.Event.
  // See com.sdv.google.diagnostics.fault.FaultListener.
  message Event {
    // Id of the event.
    string id = 1;

    // Fully qualified message name of the event's extended data message.
    string extended_data_message_name = 2;

    // Fault status changes which service wants to be notified of.
    //
    // See com.sdv.google.diagnostics.fault.FaultListener.StatusMask.
    uint32 fault_listener_mask = 3;

    // User-defined service unit name of a corresponding event publisher.
    string service_unit_name = 4;
  }

  // Diagnostic data items exposed by the service bundle.
  repeated DataItem data_item = 1;

  // Diagnostic data exposed for input/output control by the service bundle.
  repeated InputOutputControlData io_control = 2;

  // Diagnostic routines exposed by the service bundle.
  repeated Routine routine = 3;

  // Diagnostic events sent by the service bundle.
  repeated Event event = 4;
}

如果上述 (包含 diagnostics_declaration 的 service_bundle 區塊) 定義於目錄中，vsidl_rc_generator 會為每個宣告上述伺服器和 diagnostics_declaration 的服務套件產生 prebuilt_etc 目標：

prebuilt_etc {
    name: "<APEX-NAME>.<BUNDLE-NAME>-diag-config.binpb",
    filename: "DiagService-diag-config.binpb",
    sub_dir: "vsidl_provider",
    src: ":generate_vsidl_files_single_bundle_<APEX-NAME>.<BUNDLE-NAME>{diagnostics-config.binpb}",
    installable: false,
}

這些目標必須新增至對應 Apex 定義區塊的 prebuilts，如 prebuilt_etc {} 區塊上方對應的自動產生註解區塊所示：

apex {
    name: "<APEX-NAME>",
    ...
    prebuilts: [
        ...
        "<APEX-NAME>.<BUNDLE-NAME>-diag-config.binpb",
        ...
    ],
    ...
}

您也必須在相應 sdv_service_bundles_manifest.textproto 檔案的套件 sdv_service_bundle_metadata 項目中，將這些目標新增至 diagnostics_config_path 欄位。此外，您必須指定授權政策，才能在服務套件和診斷管理員服務之間啟用遠端程序呼叫 (RPC) 通訊：

sdv_service_bundle_metadata {
  name: "<BUNDLE-NAME>"
  ...
  diagnostics_config_path: "etc/vsidl_provider/<BUNDLE-NAME>-diag-config.binpb"
  authorization_policy_path: "etc/authz/permissions.textproto"
  ...
}

permissions.textproto 檔案中的權限應定義用戶端或伺服器角色。舉例來說，如果服務套裝組合實作診斷資料項目：

server {
    service: "com.sdv.google.diagnostics.data_item.DataItemService"
    allow_all_channels: true
}

平台開發人員指南

身為平台開發人員，原始設備製造商「必須」實作 Diagnostics Manager Agent rust_binary 目標：

rust_binary {
    name: "<DIAGNOSTICS-AGENT-BINARY-EXECUTABLE-NAME>",
    ...
    product_specific: true,
    ...
}

此外，在建構檔案中，必須設定/覆寫下列變數：SDV_DIAGNOSTICS_AGENT_MODULE := <DIAGNOSTICS-AGENT-BINARY-EXECUTABLE-NAME>

為方便起見，libsdv_uds_serde_v1 程式庫可用於 Proto ↔ UDS 轉譯，而 VSIDL Provider Library 則可用於反射。

診斷代理程式 .vsidl 檔案應包含下列內容：

package: "com.sdv.oem.diagnostics"

service_bundle {
    name: "DiagnosticsAgent"

    server {
        service: "com.sdv.google.diagnostics.DiagnosticsManagerService"
    }

    client {
        service: "com.sdv.google.diagnostics.data_item.DataItemService"
    }

    client {
        service: "com.sdv.google.diagnostics.routine_control.RoutineControlService"
    }

    client {
        service: "com.sdv.google.diagnostics.io_control.IoControlService"
    }

    client {
        service: "com.sdv.google.diagnostics.fault.FaultListenerService"
    }

    client {
        service: "com.sdv.google.diagnostics.ecu_reset.EcuResetService"
    }

    client {
        service: "com.sdv.google.diagnostics.security_access.SecurityAccessService"
    }

    client {
        service: "com.sdv.google.diagnostics.authentication.AuthenticationService"
    }

    client {
        service: "com.sdv.google.diagnostics.file_transfer.FileTransferService"
    }
}

由於 Diagnostics Manager Agent 是二進位可執行檔，因此套件的 sdv_service_bundle_metadata 定義為僅限設定的宣告：

sdv_service_bundle_metadata {
    # This name must match the agent's Bundle Name
    name: "DiagnosticsAgent"
    version_number: 1
    version_name: "1"

    # Reference the manifest itself to mark this as a config-only declaration.
    native_library_path: "etc/sdv_service_bundles_manifest.textproto"

    authorization_policy_path: "etc/authz/permissions.textproto"
}

診斷代理授權政策應定義與其互動的服務權限。舉例來說，如果呼叫檔案移轉服務：

client {
    service: "com.sdv.google.diagnostics.file_transfer.FileTransferService"
    allow_all_channels: true
}