Dil belirtme

Bu sayfada, ISO/IEC 14977 Genişletilmiş Backus-Naur Formu (EBNF) ve protobuf kullanılarak Araç Hizmeti Arayüzü Tanım Dili (VSIDL) belirtilmektedir. Bu sayfada, dilin bağlamdan bağımsız dil bilgisi ve dil öğelerinin anlamı ele alınmaktadır.

Dil hiyerarşisi

Meta Object Facility (MOF)'ye göre VSIDL derleyicisi (VSIDLC), Şekil 1'de gösterilen dilleri kullanır:

Şekil 1. VSIDLC dilleri.

VSIDLC, temel olarak protokol arabelleği (protobuf) dilini temel alır. Protobuf, yayınla-abone ol ve uzak prosedür çağrıları (RPC'ler) kullanılarak değiş tokuş edilen veri türlerini belirtir. Teknik olarak VSIDL modelleri TextProto dosyalarıdır ve VSIDL söz dizimi bir protobuf dosyasında (syntax.proto) tanımlanır.

Veri türlerini belirtmek için kullanılan protobuf dosyaları ve VSIDL modelleri, Rust kodu oluşturmak için kullanılır. Oluşturulan kod, değiş tokuş edilen mesaj veri yapıları için struct'lar ve hizmet birimlerini otomatik olarak çağırmadan oluşturmak için Rust işlevleri içerir. Özel Rust kodu, hizmet birimlerini örneklendirmek ve uygulama mantığını uygulamak için oluşturulan kodu kullanır.

Soyut söz dizimi

Şekil 2'de VSIDL'deki temel mesaj türleri gösterilmektedir:

Şekil 2. VSIDL'deki temel mesaj türleri.

VSIDL girişi

Bu bölümde VsidlEntry mesaj türü açıklanmaktadır.

EBNF dil bilgisi

start VsidlEntry =
  "package" , ":" , String , ";" ,
  { "service_bundle" , ServiceBundle } ,
  { "extension" , ":" , Any } ,
  { "some_ip_mapping" , ":" , SomeIpMapping } ,
  { "vhal_mapping" , ":" , VhalMapping }
;

Proto tanımı

// The root message for VSIDL files
message VsidlEntry {
  // Required. Package name for entities mentioned in the file.
  string package = 1;
  // Enables custom extensions beyond the standard VSIDL model.
  repeated google.protobuf.Any extension = 3;

  // SOMEIP mapping rules
  repeated sdv.someip.v1.SomeIpMapping some_ip_mapping = 4;
  // VHAL mapping rules
  repeated VhalMapping vhal_mapping = 5;
  // List of SDV service bundles defined in the file.
  repeated ServiceBundle service_bundle = 6;
}

Kullanım örneği

package: "com.android.sdv.sample.vsidl"

service_bundle {
  name: "Manager"

  publisher {
    message: "TirePressure"
    topic: "front-left"
    topic: "front-right"
    capacity: 10
  }
}

Açıklama

VsidlEntry mesajı, .vsidl uzantılı bir VSIDL dosyası için kök kapsayıcı görevi görür. Bu mesaj, tüm tanımları ve yapılandırmaları tek bir VSIDL dosyasında birleştirir. VsidlEntry mesajı, diğer her şeyi bağlayan üst düzey öğedir.

VsidlEntry mesajı aşağıdaki amaçlara hizmet eder:

• VSIDL dosyasının genel yapısını tanımlar.
• Dosyadaki tüm varlıklar için paket ad alanını belirtir.
• Hizmet paketi tanımları koleksiyonu içerir.
• VSIDL modeline özel uzantılara izin verir.
• SOME/IP ve VHAL için eşleme kuralları içerir.

Sınırlamalar

• Paket adı (E211): Paket adı 127 karakteri aşmamalıdır.
• Bağlantısız dosyalar (E10B): Katalogdaki tüm dosyalara bir Android.bp dosya grubunda referans verilmelidir.

Hizmet paketi

Bu bölümde, hizmet paketi mesaj türü açıklanmaktadır.

EBNF dil bilgisi

ServiceBundle = "{" , { ServiceBundleElement } , "}" ;

ServiceBundleElement =
  "name" , ":" , String |
  "publisher" , Publisher |
  "subscriber" , Subscriber |
  "server" , Server |
  "client" , Client |
  "extension" , ":" , Any |
  "diagnostics_declaration" , DiagnosticsDeclaration |
  "build_cfg" , BuildConfiguration |
  "register_reflection_metadata" , Boolean
;

Proto tanımı

// Defines an SDV service
message ServiceBundle {
  // Required. Name of the service bundle (without the package name).
  string name = 1;
  // List of publications the service bundle provides.
  repeated Publisher publisher = 2;
  // List of publications a service bundle subscribes to.
  repeated Subscriber subscriber = 3;
  // RPC services offered by a service bundle.
  repeated Server server = 4;
  // RPC services consumed by a service bundle.
  repeated Client client = 5;
  // Enables custom extensions beyond the standard VSIDL model.
  repeated google.protobuf.Any extension = 7;

  // Diagnostics declarations
  sdv.diagnostics.v1.DiagnosticsDeclaration diagnostics_declaration = 8;

  // Build Configuration
  optional BuildConfiguration build_cfg = 9;

  // Register metadata for service units provided by this service bundle.
  // Setting this to true will increase the memory footprint
  // and network load significantly.
  bool register_reflection_metadata = 10;
}

Kullanım örneği

service_bundle {
    name: "SeatController"

    publisher {
      message: "SeatHeating"
      topic: "driver-seat"
      capacity: 10
    }
}

Açıklama

Hizmet paketi; ilgili hizmetlerin, yayıncıların, abonelerin, RPC sunucularının ve RPC istemcilerinin mantıksal bir gruplandırmasını tanımlar. Hizmet paketi, belirli bir işlev kümesi ve bunların etkileşimleri için bir kapsayıcı görevi görür.

Sınırlamalar

• Paket adı koşulları (E209, E20A, E20B, E20C):
  • Hizmet paketinin adı doldurulmalıdır.
  • Ad, geçerli bir Unicode tanımlayıcı başlangıç karakteriyle (genellikle bir harf) başlamalıdır.
  • Addaki sonraki karakterler geçerli Unicode tanımlayıcı devam karakterleri (genellikle harf veya sayı) olmalıdır.
  • Ad, Rust, Java veya C++'ta ayrılmış bir anahtar kelime olmamalıdır.
• Global paket benzersizliği (E309): Her hizmet paketinin benzersiz bir tam adı (paketine ve adına göre) olmalıdır.
• Dahili benzersizlik (E100, E300, E302, E303, E308):
  • Tek bir hizmet paketinde her RPC hizmeti en fazla bir sunucu tanımı tarafından sunulabilir.
  • Tek bir hizmet paketinde her MULTI_PUB yayın türü en fazla bir yayıncı tanımı tarafından yayınlanabilir.
  • Tek bir hizmet paketi içinde, kullanıcı tarafından tanımlanan tüm hizmet birimi adları (yayıncılar veya sunucular için) benzersiz olmalıdır.
  • Tek bir hizmet paketinde, tüm hizmet birimi adları (kullanıcı tarafından tanımlanan veya otomatik olarak oluşturulan) benzersiz olmalıdır.
• Derleme hedefi adlandırma kuralları (E205, E206, E207, E208): Özel bir derleme hedefi adı (build_cfg.target_name) sağlanırsa bu ad, snake case biçimine (küçük harfler, sayılar ve tek alt çizgiler, alt çizgiyle başlamayan veya bitmeyen) uygun olmalıdır.
• Derleme hedefi adının benzersizliği (E301): Kullanıcı tarafından tanımlanan bir derleme hedefi adı, diğer hizmet paketleri için otomatik olarak oluşturulan hedef adlarıyla çakışmamalıdır.

Yayıncı

Bu bölümde, yayıncı mesajı türü açıklanmaktadır.

EBNF dil bilgisi

Publisher = "{" , { PublisherElement } , "}" ;

PublisherElement =
  "message" , ":" , String |
  "topic" , ":" , String |
  "capacity" , ":" , Integer |
  "service_unit_name" , ":" , String
;

Proto tanımı

// Represents a publisher within a service bundle.
message Publisher {
  // Name of the service unit. Name may only use characters from [a-z0-9\-]+,
  // must start with [a-z], may not end with a hyphen,
  // and may not contain consecutive hyphens.
  string service_unit_name = 3;
  // Required. The type of data being published.
  string message = 4;
  // Required. The number of messages a publication queue can hold.
  // Must be an even number >= 2.
  int64 capacity = 6;
  // Required. Unique identifier for the publication topic.
  // Must be in lowercase dash-case.
  repeated string topic = 7;
}

Kullanım örneği

publisher {
  message: "SeatHeating"
  topic: "driver-heating"
  capacity: 10
}

Açıklama

Publisher mesaj türü, ServiceBundle tarafından sağlanan bir veri kaynağını tanımlar. Bu mesaj türü, yayınlanan verilerin türünü ve bu verilerin belirli konularını ve kapasitesini belirtir.

Konular

Her Publisher örneğinde, yayınlanan proto mesajına atıfta bulunan bir message alanı bulunur. Bir konu (topic ile temsil edilir) ve bir kapasite (capacity ile temsil edilir) belirtmelidir.

• Konu: Yayın konusunun benzersiz tanımlayıcısı. Küçük harf ve tire kullanılmalıdır (örneğin, my-topic).
• Kapasite: Sıranın boyutunu, yani okunmamış mesajlar silinmeden önce sıranın kaç mesaj tutabileceğini belirtir. 2'den büyük veya 2'ye eşit bir çift sayı olmalıdır.

Kullanıcı tanımlı adlar

Yayıncılar, otomatik olarak seçilen hizmet birimi adlarını geçersiz kılan, kullanıcı tanımlı hizmet birimi adlarına sahip olabilir. Bu sayede daha kısa adlar seçebilirsiniz. Yayıncı, kullanıcı tanımlı bir hizmet birimi adı kullanıyorsa hizmet birimi adının tek bir örneğe benzersiz şekilde atanması için yalnızca tek bir örnek kullanabilir.

# VALID: A publisher assigns a user-defined name to a single instance
publisher {
  message: "SeatHeating"
  topic: "seat-heating-status"
  service_unit_name: "heating-is-off"
}

# ERROR: user-defined names are only allowed if there's only a single instance
publisher {
  message: "SeatHeating"
  topic: "seat-heating-status"
  service_unit_name: "heating-status"
}

Sınırlamalar

• Yayıncı yerleşimi (E300): Aynı MULTI_PUB türü için yayıncılar ayrı hizmet paketlerinde tanımlanmalıdır.
• Yerel ad benzersizliği (E302): Tek bir hizmet paketindeki tüm yayıncıların kullanıcı tanımlı hizmet birimi adları benzersiz olmalıdır.
• Genel ad benzersizliği (E304): Aynı yayın türündeki yayıncıların, tüm hizmet paketlerinde kullanıcı tarafından tanımlanan genel olarak benzersiz hizmet birimi adları olmalıdır.
• Tek kanalları adlandırma (E306): Kullanıcı tarafından tanımlanan hizmet birimi adları yalnızca tam olarak bir örneği işleyen yayıncılara atanabilir.
• Tek yayıncı sınırı (E307): SINGLE_PUB olarak işaretlenen bir protobuf mesajı, tüm sistemde yalnızca bir yayıncı tarafından yayınlanabilir.
• Hizmet birimi adının benzersizliği (E308): Tüm hizmet birimi adları (oluşturulmuş veya kullanıcı tarafından tanımlanmış), hizmet paketleri içinde benzersiz olmalıdır. Oluşturulan adlarla ilgili çakışmaları çözmek için kullanıcı tarafından tanımlanan adlar kullanılmalıdır.
• Varyant spesifikasyonu şartı (E501): Yayıncı, birden fazla varyantı olan bir tür için kullanıcı tanımlı ad kullandığında yayınladığı varyantı açıkça belirtmelidir.
• Aboneler için yayıncı varlığı (E504): Tanımlanan her abone, belirtilen tür ve varyant için en az bir ilgili yayıncı gerektirir.
• Geçerli yayıncı türü (E601): Yayıncı, mevcut bir protobuf mesajına karşılık gelen bir türe referans vermelidir.
• Yayın ek açıklaması koşulu (E602): Bir yayıncı tarafından referans verilen protobuf mesaj türü, SdvPublication ek açıklamasını içermelidir.
• Geçerli varyant kullanımı (E606): Yayıncı bir varyant (örnek) belirtirse bu varyant, protobuf'ta yayın türü için tanımlanan instances_enum içinde bulunmalıdır.
• Varyant spesifikasyon koşulu (E607): Bir yayıncı, yalnızca yayın türü protobuf'ta bir instances_enum tanımlıyorsa açık bir varyant (örnek) belirtebilir.
• Konu adlandırma (E20D, E20F): Konular küçük harfle yazılmalı, tireyle ayrılmalı ve 127 karakteri aşmamalıdır.
• Konu benzersizliği (E314): Konular, tüm yayıncılar genelinde benzersiz olmalıdır.
• Kapasite koşulları (E406, E407): Kapasite zorunludur ve 2'den büyük veya 2'ye eşit bir çift sayı olmalıdır.

Abone

Bu bölümde, abone mesajı türü açıklanmaktadır.

EBNF dil bilgisi

Subscriber = "{" , { SubscriberElement } , "}" ;

SubscriberElement =
  "message" , ":" , String |
  "topic" , ":" , String
;

Proto tanımı

// Represents a subscriber within a service bundle.
message Subscriber {
  // Required. The type of data being subscribed to.
  string message = 4;
  // Required. Specific topic(s) of the message to subscribe to.
  // Must match the publisher's topic.
  repeated string topic = 6;
}

Kullanım örneği

subscriber {
  message: "SeatHeating"
  topic: "driver-seat"
}

Açıklama

Subscriber mesajı, ServiceBundle tarafından sağlanan bir yayın alıcısını tanımlar. Bu mesaj, abone olunan veri türünü ve söz konusu yayının belirli konularını belirtir. Bir konu için birden fazla yayıncı varsa abone, tüm yayıncılar tarafından yayınlanan mesajları alır.

Sınırlamalar

• Yayıncı varlığı (E504): Tanımlanan her abone için, belirtilen yayın türünü ve varyantını yayınlayan en az bir ilgili yayıncı bulunmalıdır.
• Geçerli abonelik türü (E608): Abone, SdvPublication ek açıklamasıyla tanımlanan mevcut bir protobuf mesajına karşılık gelen bir türe referans vermelidir.
• Geçerli varyant aboneliği (E609): Bir abone bir varyant (örnek) belirtirse bu varyant, ilgili protobuf yayın türünün instances_enum içinde tanımlanan geçerli bir değer olmalıdır.
• Konu zorunlu (E408): Aboneler için konu zorunludur.
• Konunun yeniden tanımlanması (E311): Abone konuları aynı hizmet paketinde yeniden tanımlanmamalıdır.

RPC sunucusu

Bu bölümde RPC sunucusu mesaj türü açıklanmaktadır.

EBNF dil bilgisi

Server = "{" , { ServerElement } , "}" ;

ServerElement =
  "service" , ":" , String |
  "channel" , ":" , String |
  "service_unit_name" , ":" , String
;

Proto tanımı

// Represents an RPC server within a service bundle.
message Server {
  // Deprecated. Name of the service unit.
  string service_unit_name = 3 [ deprecated = true ];
  // Required. Name of the RPC service.
  string service = 4;
  // Required. Name of the RPC channel.
  // Must be in lowercase dash-case.
  string channel = 5;
}

Kullanım örneği

server {
  service: "SetTemperature"
  channel: "temp-setter"
}

Açıklama

Server mesajı, ServiceBundle tarafından sağlanan bir RPC sunucusunu tanımlar. Bu mesaj, sunucunun uyguladığı hizmeti ve RPC kanalını belirtir.

RPC sunucusu, istemcilerin uzaktan çağırabileceği bir dizi yöntem sunar. service alanı, sunucunun uyguladığı RPC hizmetinin adını belirtir. Bu hizmet, bir proto dosyasında tanımlanır ve özel Rust kodunda uygulanır. RPC hizmetleri, protobuf hizmet tanımında belirtildiği gibi tekli, istemci akışlı ve sunucu akışlı yöntemleri içerebilir. channel alanı, iletişim uç noktasını tanımlar ve zorunludur (E409).

Sınırlamalar

• Hizmet tanımı (E603): Bir RPC sunucusu, mevcut bir protobuf RPC service değerine karşılık gelen bir service değeri belirtmelidir.
• Hizmet başına sunucu sınırı (E100): Tek bir hizmet paketinde belirli bir RPC service en fazla bir sunucu tanımı tarafından sunulabilir.
• Kanal adlandırma (E20E): RPC kanalları küçük harfle yazılmalı ve kelimeler arasında kısa çizgi kullanılmalıdır.
• Kanal zorunlu (E409): RPC kanalı zorunludur.
• Kanal benzersizliği (E40B): RPC kanalı yalnızca bir hizmet tarafından kullanılmalıdır.

RPC istemcisi

Bu bölümde RPC istemci mesajı türü açıklanmaktadır.

EBNF dil bilgisi

Client = "{" , { ClientElement } , "}" ;

ClientElement =
  "service" , ":" , String |
  "channel" , ":" , String
;

Proto tanımı

// Represents an RPC client within a service bundle.
message Client {
  // Required. Name of the RPC service.
  string service = 2;
  // Required. Name of the RPC channel.
  // Must match the server's channel and be in lowercase dash-case.
  string channel = 3;
}

Kullanım örneği

client {
  service: "SetTemperature"
  channel: "temp-setter"
}

Açıklama

client, ServiceBundle tarafından kullanılan bir RPC istemcisini tanımlar. client, istemcinin etkileşimde bulunduğu hizmeti ve bağlanılacak kanalı belirtir. İstemci, hizmet tanımına bağlı olarak tekli, istemci akışlı ve sunucu akışlı yöntemlerle etkileşim kurabilir.

Sınırlamalar

• Hizmet tanımı (E60A): RPC istemcisi, mevcut bir protobuf service tanımına karşılık gelen bir service belirtmelidir.
• Benzersiz hizmet kaynağı (E60B): Bir RPC istemcisinin service tarafından referans verilen protobuf service tanımı, tüm protobuf dosyalarında benzersiz şekilde tanımlanmalıdır (birden fazla kez tanımlanmamalıdır).
• Kanal zorunlu (E409): RPC kanalı zorunludur.

Derleme yapılandırması

Bu bölümde, derleme yapılandırması mesaj türü açıklanmaktadır.

EBNF dil bilgisi

BuildConfiguration = "{" , BuildConfigurationElement, "}" ;

BuildConfigurationElement =
  "target_name" , ":" , String |
  "skip_codegen" , ":" , Boolean
;

Proto tanımı

// Defines additional information used to configure build settings
message BuildConfiguration {
  /// Build target name
  optional string target_name = 1;
  // Do not generate code for this service bundle
  optional bool skip_codegen = 2;
}

Kullanım örneği

build_cfg {
  target_name: "my_custom_target_name"
  skip_codegen: false
}

Açıklama

BuildConfiguration, kod oluşturma için ServiceBundle standart dışı parametrelerini yapılandırır. Tüm derleme yapılandırmaları isteğe bağlıdır.

• target_name (isteğe bağlı string): Android.bp dosyalarındaki derleme hedefinin adını belirtir. Otomatik olarak seçilen adlardan daha kısa adlara sahip hedef adlar belirlemek için bu seçeneği kullanın.
• skip_codegen (isteğe bağlı bool): Bu hizmet paketi için kod oluşturma işleminin atlanıp atlanmayacağını belirtir. true olarak ayarlanırsa bu hizmet paketi için kod oluşturulmaz. Bu, manuel olarak uygulanan hizmet paketleri için yararlı olabilir. Varsayılan olarak bu ayar false şeklinde belirlenmiştir.

Sınırlamalar

• Hedef adı biçimi (E205, E206, E207, E208): Özel bir derleme hedefi adı (build_cfg.target_name) sağlanırsa bu ad, alt çizgili yazım biçimine kesinlikle uymalıdır:
  • Yalnızca küçük harf (a-z), rakam (0-9) ve alt çizgi (_) içermelidir.
  • Ardışık alt çizgiler (__) içermemelidir.
  • Alt çizgiyle başlamamalıdır.
  • Alt çizgiyle bitmemelidir.
• Hedef adının benzersizliği (E301): Kullanıcı tarafından tanımlanan build_cfg.target_name, derleme sisteminde benzersiz olmalı ve diğer hizmet paketi tanımlarından türetilen otomatik olarak oluşturulmuş hedef adlarıyla çakışmamalıdır.