This document guides you through writing a SOME/IP mapping file. A SOME/IP mapping file defines how SDV services map to SOME/IP services and the other way around, facilitating communication between SDV and non-SDV ECUs.
The some_ip_mapping field within the VsidlEntry message in your .vsidl
file contains the SOME/IP mapping information. The some_ip_mapping field lets
you define SOME/IP mappings separately from SDV service definitions.
The SomeIp Mapping proto contains all information the SOME/IP broker needs
for transformations between SDV and SOME/IP ECUs. This proto can map either a
SOME/IP service into the SDV ecosystem or SDV service units into the AUTOSAR
ecosystem.
Core concepts
Before writing your mapping file, understand these key identifiers and concepts:
SDV Fully Qualified Instance Name (FQIN): This unique string identifies SDV service instances. It's composed of the VM name, package name, service name, and instance name.
SDV type: This name is a unique identifier for the data format of an SDV message payload and corresponds to a proto message.
SOME/IP
ServiceIdentifier(SOME/IP SID): Uniquely identifies SOME/IP services with a combination of service ID (uint16), instance ID (uint16), major version (uint8), and minor version (uint32).SDV RPC: Methods offered by SDV services, identified by
method name(string), the containingType, and achannelname.SDV Pub/Sub: Topics published or subscribed to by SDV services and identified by a
TypeandTopicnameSOME/IP RPC: Identified by service ID, instance ID, and method ID (
uint16).SOME/IP events: Published by SOME/IP services for Pub/Sub and identified by service ID, instance ID, event ID (
uint16), and belonging to an event-group (uint16).SOME/IP broker: A bridging component in SDV that consumes the SOME/IP mapping file to enable communication between SDV and SOME/IP services.
File structure and location
The SOME/IP mapping information is included as a repeated field,
some_ip_mapping, within the VsidlEntry message in your .vsidl file. This
lets the SOME/IP mappings to be defined separately from the SDV service
definitions, enabling you to manage the mappings in a dedicated file.
// 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;
}
Create a mapping file
A SOME/IP mapping file typically contains definitions that translate between the SDV ecosystem and the SOME/IP network protocol. You can define mappings in two primary ways:
sdv_type_mapping: Maps an SDV type (such as an RPC interface or a publication topic) to a SOME/IP service.someip_service_mapping: Maps a raw SOME/IP service (and its instances, events, or methods) to SDV Pub/Sub topics or RPC channels.
A single mapping file consists of one or more SomeIpMapping definitions.
SDV type mapping
sdv_type_mapping is for existing SDV types that you want to expose to the
SOME/IP network.
SDV type mapping structure
You need to specify:
unit_type: The SDV type being mapped (identified bypackage_nameandtype_name).someip_service_id: The 16-bit SOME/IP service ID.version_majorandversion_minor: The versioning of the SOME/IP service.service_oriented_mapping: Defines the specific mapping behavior (either for an RPC interface or a publication).
Publication mapping example
If your SDV type is a topic (publication), use publication_mapping. This maps
the structure of the data (type_definition) and the SOME/IP Event ID or
EventGroup ID, followed by mapping specific SDV topics to SOME/IP instances.
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 interface mapping example
If your SDV type is an RPC interface, use rpc_interface_mapping.
Map the SDV procedure names to the SOME/IP method_id instances, and link SDV
channels to SOME/IP instances.
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 service mapping
someip_service_mapping configures how a specific SOME/IP service
(discovered or offered on the network) maps onto SDV topics and channels. It
allows for complex parameterized mappings of events and RPCs.
SOME/IP service mapping structure
someip_service_id,version_major,version_minor: Identify the SOME/IP service.sd_behavior(optional): Defines service discovery behavior (EXACT_OR_ANY_MINOR_VERSIONorMINIMUM_MINOR_VERSION)instance: Parameterizes SDV service units and topics for specific SOME/IPinstance_idinstances.instance_impl: Describes the implementation of the instance, mapping events or methods to the parameterized service units.
Event mapping example
This example maps a SOME/IP event into an SDV topic. It uses instance to map
the ID 1 to the literal string 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 mapping example
This example maps a SOME/IP RPC service to an SDV RPC interface. Similar to
event mappings, the service uses instance to parameterize the service unit name. This
corresponds to the RPC channel name in SDV. The instance_impl block then
defines an instance of offered_interface to link the SOME/IP method_id to
the SDV procedure name:
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
}
}
}
}
Advanced features
This section describes advanced features supported by the SOME/IP mapping.
Group events
group_event allows a single SOME/IP event to be split and mapped to multiple
SDV topics simultaneously. This is done by specifying multiple event_part
entries and using field_name_mapping to map the incoming SOME/IP payload
field names to the SDV payload field names:
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"
}
}
}
}
Fire and forget mappings
SOME/IP fire and forget (F&F) methods have no direct equivalent in SDV RPC
interfaces. Instead, they are invoked by mapping an SDV topic (publication) to
the F&F method using publication_mapping. When data is published to the
corresponding SDV topic, the broker translates it into a SOME/IP F&F
method call.
To configure this, you must set someip_ff_methods: true within the
offered_topic block, and provide the destination fire_and_forget_method
routing details inside your topic_mapping.
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
}
}
}
}
}