SDV VSIDL compatibility guidelines

The Vehicle Services IDL (VSIDL) catalog is compiled into service bundle libraries and the libraries depend on Comms Stack APIs to be ABI stable and platform software to perform compatible updates. This page provides guidelines intended to assist developers to ensure a stable VSIDL and, consequently, an updatable service bundle. Service bundles are expected to be compatible at runtime when the guidelines are adhered to and subsequently enforced by tooling.

Update VSIDL

Figure 1. Update VSIDL.

This content aims to help you determine if a change in VSIDL is binary compatible and to provide VSIDL compatibility best practices.

This content doesn't provide:

  • Design tools to prevent incompatible changes
  • SDV versioning policy

Design

This design is compatible when the service bundle that is recompiled according to the updated VSIDL and can speak with and understand the previously versioned service bundles or SOME/IP through DT or RPC.

  • Speak with: Two ends of DT and RPC transports are successfully connected and transmit data in accordance with agreed protocol.

  • Understand: Two ends of DT and RPC transports ​​can operate without potential runtime behavior breakage.

The guideline focuses primarily on the runtime compatibility on devices after the recompiled versions of different service bundles are updated. For each change, only the direct effect is evaluated, and potential risks resulting from potential subsequent changes are not considered for the initial change. The severity levels of

  • Error is used when service connection or protocol is sabotaged.

  • Warning is used when there is a potential for misinterpretation or misunderstanding.

Summary

Guidelines are based on Language Guide (proto 3).

File Change Compile-time
compatible		 Runtime
compatible
Android.bp Update catalog build target name No Yes
Android.bp Update catalog crate name No Yes
.proto Rename .proto file No Yes
.proto Move .proto file No Yes
.proto Rename package in .proto No Error
.proto Rename message in .proto No Error
.proto Move message, enum, or interface into a catalog No Yes
.proto Add message field in .proto Yes Warning
.proto Annotate message field as deprecated Yes Yes
.proto Delete message field No Warning
.proto Update message field name No Error
.proto Update message field type No Error
.proto Update message field number No Error
.proto Mark message field as optional Yes Yes
.proto Rename enum No Yes
.proto Update enum value name No Error
.proto Update enum value numeric value Yes Error
.proto Add enum value No Warning
.proto Delete enum value No Warning
.proto Update order of enum values
(used as unit type instance)		 Yes Yes
.proto Update order of enum values
(not used as unit type instance)		 Yes Warning
.proto Rename service (interface) No Error
.proto Add service RPC (method) Yes Yes
.proto Delete service RPC (method) No Error
.proto Rename service RPC (method) No Error
.proto Update service RPC (method) input/output types No Error
.proto Update field size limit to bigger Yes Yes
.proto Update field size limit to smaller Yes Error
.proto Update publication model annotation Yes Error
.proto Update publication instances enum annotation No Error
.proto Update publication message count to bigger Yes Yes
.proto Update publication message count to smaller Yes Warning
.vsidl Rename package No Error
.vsidl Rename service bundle No Error
.vsidl Add unit type Yes Yes
.vsidl Delete unit type No Error
.vsidl Replace type of unit type No Error
.vsidl Add publisher Yes Yes
.vsidl Delete publisher No Error
.vsidl Replace publisher type No Error
.vsidl Add publisher instance Yes Yes
.vsidl Remove publisher instance No Error
.vsidl Replace publisher instance No Error
.vsidl Add subscriber Yes Warning
.vsidl Delete subscriber No Yes
.vsidl Replace subscriber type No Warning
.vsidl Add subscriber instance Yes Warning
.vsidl Remove subscriber instance No Yes
.vsidl Replace subscriber instance No Warning
.vsidl Add server Yes Yes
.vsidl Delete server No Error
.vsidl Replace server interface No Error
.vsidl Add client Yes Warning
.vsidl Delete client No Yes
.vsidl Replace client interface No Warning

Breakdown

Update catalog build target name in Android.bp

  • Might break compilation.
  • No unexpected runtime behavior.

Update catalog crate name in Android.bp

  • Might break compilation.
  • No unexpected runtime behavior.

Rename .proto file

  • Might break compilation.
  • No unexpected runtime behavior.

Move .proto file

  • Might break compilation.
  • No unexpected runtime behavior.

Rename package in .proto

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior. Package name is part of unit type and service unit identifiers in service discovery.

  • (Best practice) Make sure all relevant service bundles are updated at the same time in all VMs on a car.

Rename message in .proto

  • Might break compilation.

  • If the message is directly used as a unit type:

    • (Error) Might cause unexpected runtime behavior. Protobuf message name is part of unit type and Service Unit identifiers in service discovery.

    • (Best practice) Make sure all the relevant service bundles are updated at the same time in all the VMs on a car.

  • If the message is not directly used as a unit type (for example, a child message).

  • No unexpected runtime behavior.

Move message, enum, interface around in .proto files

  • Might break compilation.
  • No unexpected runtime behavior.

Add message field in .proto

  • (Rule) Must not reuse existing or reserved field or enum value numbers.

  • Won't break compilation.

  • (Warning) Might cause misunderstanding between service units that offer or consume the data.

  • (Best practice) Make sure data provider service units are updated before or together with data consumer service units in all the VMs on a car.

  • (Alternative) Have all data consumer service units handle both data set/unset cases if the new field is not business critical, in which case update order doesn't matter.

Annotate message field as deprecated in .proto

  • Won't break compilation.
  • No unexpected runtime behavior.

Delete message field in .proto

  • Might break compilation.

  • No runtime error under conditions:

    • Mark the deleted field number as reserved

    • Field name needs to be reserved if JSON or TextFormat encodings of the message are used.

  • (Warning) Might cause misunderstanding between service units that offer or consume the data.

  • (Best practice) Make sure data consumer service units are updated before of together with data provider service units in all the VMs on a car.

Update message field name in .proto

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior when accessing the field with a field name through reflection.

  • (Best practice) Make sure all the relevant service bundles are updated at the same time in all the VMs on a car.

Update message field type in .proto

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior when the wire type of the old and new types differ (or are the same but with number casting). To learn more, see Encoding.

  • (Best practice) Don't do this.
    Instead, go to Add message field > Update Service > Bundles > Delete message field.

Update message field number in .proto

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior. Field number plays a key role in the serialization or deserialization of Protobuf messages.

  • (Best practice) Don't do this.

Mark message field as optional in .proto

  • Won't break compilation.
  • No unexpected runtime behavior.

Rename enum in .proto

  • Might break compilation.
  • No unexpected runtime behavior.

Update enum value name in .proto

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior. Unit type instance name is part of service unit identifier in service discovery.

  • (Best practice) Don't do this.
    You can lose control of updating multiple enum value names at the same time. Instead, go to Add enum value > Update Service Bundles > Delete enum value.

Update enum value numeric value in .proto

  • Won't break compilation.

  • (Error) Might cause unexpected runtime behavior. Numeric value of enum values plays a key role in the serialization/deserialization of Protobuf messages.

  • (Best practice) Don't do this.
    Instead, go to Add enum value > Update Service Bundles > Delete enum value.

Add enum value in .proto

  • Might break compilation.

  • If the enum is used to declare unit type instances:

    • No unexpected runtime behavior.

  • If the enum is not used to declare unit type instances (for example, a sub-type of message):

    • (Warning) Might cause misunderstanding between service units that offer or consume the data.

    • (Best practice) Make sure data provider service units are updated before or together with data consumer service units in all the VMs on a car.

Delete enum value in .proto

  • Might break compilation.

  • If the enum is used to declare unit type instances:

    • (Error) Might cause unexpected runtime behavior. Unit type instance name is part of service unit identifiers in service discovery.

    • (Best practice) Make sure data consumer service units are updated before or together with data provider service units in all the VMs on a car.

  • If the enum is not used to declare Unit Type instances (e.g. sub-type of message):

    • No unexpected runtime error under the conditions:

      • Mark the number as reserved

      • Mark the name as reserved if JSON or TextFormat encodings of the enum are used

      • The numeric value of the deleted enum value is not 0 in which case it is used as DEFAULT

    • (Warning) Might cause misunderstanding between service units that offer or consume the data.

    • (Best practice) Make sure data consumer service units are updated before or together with data provider service units in all the VMs on a car.

Update order of enum values in .proto

  • Won't break compilation.
  • If the enum is used to declare Unit Type instances
    • No unexpected runtime behavior if numeric value assignment is not changed.
  • If the enum is not used to declare Unit Type instances (e.g. sub-type of message)
    • (Warning) Default enum value will be changed if the first value is moved.
    • (Best practice) The first defined enum value should always be *_UNSPECIFIED.

Rename service (interface) in .proto

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior. Protobuf service name is part of Unit Type and service unit identifiers in service discovery.

  • (Best practice) Make sure all the relevant service bundles are updated at the same time in all the VMs on a car.

  • (Alternative)

    1. Create a new interface and deploy service units that serve the new service.
    2. Migrate RPC client service bundles to use the new interface.
    3. Deprecate old interface and RPC server service bundles.

Add service RPC (method) in .proto

  • Won't break compilation because Middleware generates default method implementation.

  • No unexpected runtime behavior.

Delete service RPC (method) in .proto

  • Might break compilation.

  • (Error) Might cause unexpected runtime errors (UNIMPLEMENTED).

  • (Best practice) Make sure RPC client service units are updated before or together with RPC server service units in all the VMs on a car.

Rename service RPC (method) in .proto

  • Might break compilation.

  • (Error) Might cause unexpected runtime errors (UNIMPLEMENTED).

  • (Best practice) Make sure all the relevant service bundles are updated at the same time in all the VMs on a car.

  • (Alternative)

    1. Create a new method.
    2. Update service units to serve both old and new methods.
    3. Migrate RPC client service bundles to use the new method.
    4. Deprecate the old method.

Update service RPC (method) input/output types in .proto

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior. RPC method input/output is part of the communication language between Unit Types.

  • (Best practice) Make sure all the relevant service bundles are updated at the same time in all the VMs on a car.

Update field size limit to bigger in .proto

(repeated_field_max_count or variable_type_max_size annotation)

  • Won't break compilation.
  • No unexpected runtime behavior.

Update field size limit to smaller in .proto

(repeated_field_max_count or variable_type_max_size annotation)

  • No change at compile time.

  • (Error) Might cause unexpected runtime errors when a publisher Service= Unit is publishing data that exceeds the new size limit.

  • (Best practice) Don't do this.
    Difficult to trace all the upstream data sources of the to-be-published data.

Update publication model annotation in .proto

(model annotation)

  • No change at compile time.

  • (Error) Might cause unexpected runtime data loss on subscriber service unit.

  • (Best practice) If SINGLE_PUB to MULTI_PUB, make sure subscribers are updated before or together with publisher service units in all the VMs on a car; If MULTI_PUB to SINGLE_PUB, make sure publisher service units are updated before or together with subscribers in all the VMs on a car.

Update publication instances enum annotation in .proto

(instances_enumannotation)

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior. Enum values are part of the service unit identifier in service discovery.

  • (Best practice) Make sure all the relevant service bundles are updated at the same time in all the VMs on a car.

Update publication message count to bigger in .proto

(message_count annotation)

  • Won't break compilation.
  • No unexpected runtime behavior.

Update publication message count to smaller in .proto

(message_count annotation)

  • Won't break compilation.

  • (Warning) Might cause unexpected data loss on subscriber service unit when the new message count (queue size) is too small for existing publication frequency.

  • (Best practice) Make sure publisher service units are updated before or together with subscribers in all the VMs on a car.

Rename package in .vsidl

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior. Package name is part of service bundle and Unit Type identifiers in service discovery. * (Best practice) Make sure all the relevant service bundles are updated at the same time in all the VMs on a car.

Rename service bundle in .vsidl

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior. The service bundle name is part of dervice bundle and Unit Type identifiers in service discovery.

  • (Best practice) Make sure all the relevant service bundles are updated at the same time in all the VMs on a car.

Add Unit Type in .vsidl

  • Won't break compilation.
  • No unexpected runtime behavior.

Delete Unit Type in .vsidl

  • Might break compilation.

  • (Error) Might cause unexpected runtime behavior. Deleting a Unit Type means deleting all the service units that offer or consume this type. Wrong update order might cause connection error on consumer service unit.

  • (Best practice) Make sure consumer service units are updated before or together with provider service units in all the VMs on a car.

Replace type of Unit Type (type) in .vsidl

  • Might break compilation.
  • (Error) Same as deleting the original type and adding a new type.

Add publisher in .vsidl

  • Won't break compilation.
  • No unexpected runtime behavior.

Delete publisher in .vsidl

  • Might break compilation.

  • (Error) Might cause unexpected runtime errors on subscriber Service Unit(s).

  • (Best practice) Make sure subscribers are updated before or together with publisher service units in all the VMs on a car.

Replace publisher type in .vsidl

  • Might break compilation.
  • (Error) Same as deleting the original type and adding a new type.

Add publisher instance in .vsidl

  • Won't break compilation.
  • No unexpected runtime behavior.

Remove publisher instance in .vsidl

  • Might break compilation.

  • (Error) Might cause unexpected runtime errors on subscriber Service Unit(s).

  • (Best practice) Make sure subscribers are updated before or together with publisher service units in all the VMs on a car.

Replace publisher instance in .vsidl

  • Might break compilation.

  • (Error) Same as deleting the original publisher instance and adding a new one.

Add subscriber in .vsidl

  • Won't break compilation.

  • (Warning) Might have unexpected runtime errors if the corresponding publisher service unit(s) is missing.

  • (Best practice) Make sure publisher service units are already updated.

Delete subscriber in .vsidl

  • Might break compilation.
  • No unexpected runtime behavior.

Replace subscriber type in .vsidl

  • Might break compilation.
  • (Warning) Same as deleting the original type and adding a new type.

Add subscriber instance in .vsidl

  • Won't break compilation.

  • (Warning) Might experience unexpected runtime errors if the corresponding publisher service units is missing.

  • (Best practice) Make sure publisher service units are already updated.

Remove subscriber instance in .vsidl

  • Might break compilation.
  • No unexpected runtime behavior.

Replace subscriber instance in .vsidl

  • Might break compilation.

  • (Warning) Same as deleting the original subscriber instance and adding a new one.

Add server in .vsidl

  • Won't break compilation (builder pattern).

  • No unexpected runtime behavior.

Delete server in .vsidl

  • Might break compilation.

  • (Error) Might cause unexpected connection failure on client service units.

  • (Best practice) Make sure RPC client service units are updated before or together with RPC server service units in all the VMs on a car.

Replace server interface in .vsidl

  • Might break compilation.

  • (Error) Same as deleting the original RPC server service unit and adding a new one.

Add client in .vsidl

  • Won't break compilation.

  • (Warning) Might experience unexpected runtime errors if the corresponding RPC server service units are not available or not serving all the needed methods of the interface on a car.

  • (Best practice) Make sure a service unit that serves all the needed methods of the interface is already updated on the car.

Delete client in .vsidl

  • Might break compilation.
  • No unexpected runtime behavior.

Replace client interface in .vsidl

  • Might break compilation.

  • (Warning) Same as deleting the original RPC client service unit and adding a new one.