撰寫 SOME/IP 對應檔案

本文將逐步說明如何編寫 SOME/IP 對應檔案。SOME/IP 對應檔案會定義 SDV 服務如何對應至 SOME/IP 服務，以及反向對應，方便 SDV 和非 SDV ECU 之間的通訊。

.vsidl 檔案中 VsidlEntry 訊息內的 some_ip_mapping 欄位包含 SOME/IP 對應資訊。some_ip_mapping 欄位可讓您定義 SOME/IP 對應，與 SDV 服務定義分開。

SomeIp Mapping proto 包含 SOME/IP 代理程式在 SDV 和 SOME/IP ECU 之間轉換時所需的所有資訊。這個 Proto 可以將 SOME/IP 服務對應至 SDV 生態系統，或將 SDV 服務單元對應至 AUTOSAR 生態系統。

核心概念

撰寫對應檔案前，請先瞭解下列重要 ID 和概念：

  • SDV 完整執行個體名稱 (FQIN)：這個專屬字串可識別 SDV 服務執行個體，由 VM 名稱、套件名稱、服務名稱和執行個體名稱組成。

  • SDV 類型：這個名稱是 SDV 訊息酬載資料格式的專屬 ID，對應至 proto 訊息。

  • SOME/IP ServiceIdentifier (SOME/IP SID)：透過服務 ID (uint16)、執行個體 ID (uint16)、主要版本 (uint8) 和次要版本 (uint32) 的組合，唯一識別 SOME/IP 服務。

  • SDV RPC：SDV 服務提供的方法，由 method name (字串)、包含的 Type 和 channel 名稱識別。

  • SDV Pub/Sub：由 SDV 服務發布或訂閱的主題，並以 Type 和 Topic 名稱識別

  • SOME/IP RPC：由服務 ID、執行個體 ID 和方法 ID 識別 (uint16)。

  • SOME/IP 事件：由 SOME/IP 服務發布至 Pub/Sub，並由服務 ID、例項 ID、事件 ID (uint16) 識別，且屬於事件群組 (uint16)。

  • SOME/IP 代理程式：SDV 中的橋接元件，會使用 SOME/IP 對應檔案，在 SDV 和 SOME/IP 服務之間建立通訊。

檔案結構和位置

SOME/IP 對應資訊會以重複欄位 some_ip_mapping 的形式，納入 .vsidl 檔案的 VsidlEntry 訊息中。這樣一來，您就能將 SOME/IP 對應與 SDV 服務定義分開定義，並在專用檔案中管理對應。

// The root message for VSIDL files.
message VsidlEntry {
  // Required. Package name for entities mentioned in the file.
  string package = 1;
  // List of SDV service bundles defined in the file.
  repeated ServiceBundle sdv_service_bundle = 2;
  // Enables custom extensions beyond the standard VSIDL model.
  repeated google.xml.Any extension = 3;

  // SOMEIP mapping rules.
  repeated sdv.someip.v1.SomeIpMapping some_ip_mapping = 4;
  // VHAL mapping rules.
  repeated VhalMapping vhal_mapping = 5;
}

建立對應檔案

SOME/IP 對應檔案通常包含定義，可在 SDV 生態系統和 SOME/IP 網路通訊協定之間進行轉換。您可以透過兩種主要方式定義對應：

  • sdv_type_mapping：將 SDV 類型 (例如 RPC 介面或發布主題) 對應至 SOME/IP 服務。
  • someip_service_mapping：將原始 SOME/IP 服務 (及其例項、事件或方法) 對應至 SDV Pub/Sub 主題或 RPC 管道。

單一對應檔案包含一或多個 SomeIpMapping 定義。

SDV 類型對應

sdv_type_mapping 是指您要向 SOME/IP 網路公開的現有 SDV 類型。

SDV 類型對應結構

請指定下列項目：

  • unit_type：要對應的 SDV 類型 (由 package_name 和 type_name 識別)。
  • someip_service_id：16 位元的 SOME/IP 服務 ID。
  • version_major 和 version_minor：SOME/IP 服務的版本。

  • service_oriented_mapping：定義特定對應行為 (適用於 RPC 介面或發布)。

出版品對應範例

如果 SDV 類型為主題 (發布)，請使用 publication_mapping。這會對應資料結構 (type_definition) 和 SOME/IP 事件 ID 或 EventGroup ID，然後將特定 SDV 主題對應至 SOME/IP 執行個體。

sdv_type_mapping {
  unit_type {
    package_name: "com.android.sdv.samples"
    type_name: "SpeedData"
  }
  someip_service_id: 0x1001
  version_major: 1
  version_minor: 0
  service_oriented_mapping {
    publication_mapping {
      offered_topic {
        simple_mapping {
          group_id: 1
          event_id: 0x8001
        }
        # type_definition defines the structural mapping to SOME/IP payloads
        type_definition {
          # ... (SomeIpStruct definition) ...
        }
      }
      # Maps the SDV topic name to a specific SOME/IP instance
      topic_mapping {
        topic: "vehicle_speed_topic"
        instance_id: 0x0001
      }
    }
  }
}

RPC 介面對應範例

如果 SDV 類型是 RPC 介面，請使用 rpc_interface_mapping。將 SDV 程序名稱對應至 SOME/IP method_id 執行個體，並將 SDV 通道連結至 SOME/IP 執行個體。

sdv_type_mapping {
  unit_type {
    package_name: "com.android.sdv.samples"
    type_name: "DoorControl"
  }
  someip_service_id: 0x2001
  version_major: 1
  version_minor: 0
  service_oriented_mapping {
    rpc_interface_mapping {
      offered_interface {
        method {
          procedure: "LockDoors"
          method_id: 0x0001
          # request_payload_mapping and response_payload_mapping can be defined here
        }
      }
      rpc_channel_mapping {
        channel: "front_doors"
        instance_id: 0x0001
      }
    }
  }
}

SOME/IP 服務對應

someip_service_mapping 會設定特定 SOME/IP 服務 (在網路上探索或提供) 如何對應至 SDV 主題和通道。這項設定可讓事件和 RPC 進行複雜的參數化對應。

SOME/IP 服務對應結構

  • someip_service_id、version_major、version_minor：找出 SOME/IP 服務。

  • sd_behavior (選用)：定義服務探索行為 (EXACT_OR_ANY_MINOR_VERSION 或 MINIMUM_MINOR_VERSION)

  • instance：針對特定 SOME/IP instance_id 執行個體，將 SDV 服務單元和主題參數化。

  • instance_impl：說明執行個體的實作方式，將事件或方法對應至參數化服務單元。

事件對應範例

這個範例會將 SOME/IP 事件對應至 SDV 主題。它會使用 instance 將 ID 1 對應至字串常值 speed_sensor_unit。

someip_service_mapping {
  someip_service_id: 0x1001
  version_major: 1
  version_minor: 0
  # Parameterize instances
  instance {
    instance_id: 0x0001
    sdv_service_unit_parameterization {
      key: 1
      value: "speed_sensor_unit"
    }
    sdv_topic_parameterization {
      key: 1
      value {
        topic: "speed_topic"
        capacity: 10
      }
    }
  }
  # Description of all instances
  instance_impl {
    offered_event {
      group_id: 1
      event_id: 0x8001
      simple_event {
        sdv_unit_type {
          package_name: "com.android.sdv.samples"
          type_name: "SpeedData"
        }
        # Refers to key 1 in sdv_service_unit_parameterization. If unspecified,
        # service unit name will be automatically generated by the broker
        service_unit: 1
        topic: 1        # Refers to key 1 in sdv_topic_parameterization
        message_translation_mode: REFLECTION
        type_definition {
          # ... (SomeIpStruct definition) ...
        }
      }
    }
  }
}

遠端程序呼叫 (RPC) 對應範例

這個範例會將 SOME/IP RPC 服務對應至 SDV RPC 介面。與事件對應類似，服務會使用執行個體來參數化服務單元名稱。這對應至 SDV 中的 RPC 頻道名稱。接著，instance_impl 模塊會定義 offered_interface 的執行個體，將 SOME/IP method_id 連結至 SDV 程序名稱：

someip_service_mapping {
  someip_service_id: 0x2001
  version_major: 1
  version_minor: 0
  # Parameterize instances
  instance {
    instance_id: 0x0001
    sdv_service_unit_parameterization {
      key: 1
      value: "door_control_unit"
    }
  }
  instance_impl {
    offered_interface {
      sdv_unit_type {
        package_name: "com.android.sdv.samples"
        type_name: "DoorControl"
      }
      # Refers to key 1 in sdv_service_unit_parameterization. This corresponds
      # to the RPC channel name in SDV.
      service_unit: 1
      method {
        procedure: "LockDoors"
        method_id: 0x0001
     # request_payload_mapping and response_payload_mapping can be defined here
      }
    }
  }
}

進階功能

本節說明 SOME/IP 對應支援的進階功能。

團體活動

group_event 可將單一 SOME/IP 事件分割並同時對應至多個 SDV 主題。方法是指定多個 event_part 項目，並使用 field_name_mapping 將傳入的 SOME/IP 酬載欄位名稱對應至 SDV 酬載欄位名稱：

offered_event {
  group_id: 1
  event_id: 0x8002
  group_event {
    type_definition {
      # Definition of the complete SOME/IP payload
    }
    event_part {
      sdv_unit_type {
        package_name: "com.android.sdv.samples"
        type_name: "PartAData"
      }
      service_unit: 1
      topic: 1
      field_name_mapping {
        key: "someip_field_a"
        value: "sdv_field_a"
      }
    }
    event_part {
      sdv_unit_type {
        package_name: "com.android.sdv.samples"
        type_name: "PartBData"
      }
      service_unit: 2
      topic: 2
      field_name_mapping {
        key: "someip_field_b"
        value: "sdv_field_b"
      }
    }
  }
}

啟動後便不須控制的對應

SOME/IP 啟動後不受控 (F&F) 方法在 SDV RPC 介面中沒有直接對應項目。而是透過 publication_mapping 將 SDV 主題 (發布) 對應至 F&F 方法來叫用。資料發布至對應的 SDV 主題時，代理程式會將資料轉換為 SOME/IP F&F 方法呼叫。

如要設定這項功能，請務必在 offered_topic 區塊中設定 someip_ff_methods: true，並在 topic_mapping 中提供目的地 fire_and_forget_method 路由詳細資料。

sdv_type_mapping {
  unit_type {
    package_name: "com.android.sdv.sample.someip"
    type_name: "CounterLoad"
  }
  someip_service_id: 0x13
  version_major: 1
  version_minor: 0
  service_oriented_mapping {
    publication_mapping {
      offered_topic {
        type_definition {
          # ... (SomeIpStruct definition) ...
        }
        someip_ff_methods: true
      }
      topic_mapping {
        topic: "counter-load-start-counter"
        instance_id: 0x1
        fire_and_forget_method {
          service_id: 0x3700
          instance_id: 0x1000
          version_major: 1
          version_minor: 0
          method_id: 0x1000
        }
      }
    }
  }
}