Dil belirtme

Bu sayfada, ISO/IEC 14977 Extended Backus-Naur Form (EBNF) ve protobuf kullanılarak Araç Servisi Arayüzü Tanım Dili (VSIDL) belirtilmektedir. Bu sayfada, dilin bağlamdan bağımsız grameri ve dil öğelerinin anlamı üzerinde durulmaktadı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) diline dayanır. Yayın/abone olma ve uzak prosedür çağrıları (RPC) kullanılarak değiştirilen veri türlerini belirtmek için Protobuf kullanılır. Teknik açıdan VSIDL modelleri, VSIDL'nin söz diziminin bir protobuf dosyasında (syntax.proto) tanımlandığı TextProto dosyalarıdı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, temel olarak değiştirilen mesajların veri yapılarını uygulayan yapılar ve bu hizmet birimlerini otomatik olarak çağırmadan Rust'ta hizmet birimleri oluşturma işlevlerini uygulayan Rust işlevlerini içerir. Bu oluşturulan Rust kodu, hizmet birimlerini örneklemek ve uygulamanın iş mantığını uygulamak için oluşturulan kodu kullanan özel Rust koduyla birlikte gelir.

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 VSIDL giriş 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 dosyası (.vsidl uzantılı) 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 kapsar. VsidlEntry, diğer her şeyi bağlayan üst düzey öğedir.

Amaç:

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

Sınırlamalar

• Paket adı (E211): Paket adı 127 karakterden uzun olmamalıdır.
• Bağlantısız dosyalar (E10B): Bir 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, UPÇ sunucularının ve UPÇ istemcilerinin mantıksal bir gruplandırmasını tanımlar. Hizmet paketi, belirli bir işlev grubu ve bunların etkileşimleri için kapsayıcı görevi görür.

Sınırlamalar

• Paket adı koşulları (E209, E20A, E20B, E20C):
  • Hizmet paketinin adı doldurulmuş olmalıdır.
  • Ad, geçerli bir Unicode tanımlayıcı başlangıç karakteriyle (genellikle bir harf) başlamalıdır.
  • Adın sonraki karakterleri geçerli Unicode tanımlayıcı devam karakterleri (genellikle harfler veya sayılar) olmalıdır.
  • Ad, Rust, Java veya C++'da ayrılmış bir anahtar kelime olmamalıdır.
• Global paket benzersizliği (E309): Her hizmet paketinin benzersiz bir tam nitelikli adı olmalıdır (paketi ve adına göre).
• 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 paketinde, kullanıcı tanımlı tüm hizmet birimi adları (yayıncılar veya sunucular için) benzersiz olmalıdır.
  • Tek bir hizmet paketindeki tüm hizmet birimi adları (kullanıcı tanımlı veya otomatik olarak oluşturulmuş olsun) 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şlamaz veya bitmez) uygun olmalıdır.
• Hedef adı benzersizliği oluşturma (E301): Kullanıcı tanımlı bir derleme hedef adı, diğer hizmet paketleri için otomatik olarak oluşturulan hedef adlarla ç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 sağlayan 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 gösterilir) ve kapasite (capacity ile gösterilir) belirtmelidir.

• Konu: Yayın konusunun benzersiz tanımlayıcısı. Küçük harfli tireli biçimde olmalıdır (örneğin, my-topic).
• Kapasite: Kuyruğun boyutunu, yani okunmamış iletiler atılmadan önce kuyruğun kaç ileti 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 özellik, daha kısa adlar seçmenize olanak tanır. 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ündeki yayıncılar ayrı hizmet paketlerinde tanımlanmalıdır.
• Yerel adın benzersizliği (E302): Herhangi bir hizmet paketinde tüm yayıncılar, kullanıcı tanımlı benzersiz hizmet birimi adlarına sahip olmalıdır.
• Global adın benzersizliği (E304): Aynı yayın türündeki yayıncılar, tüm hizmet paketlerinde küresel olarak benzersiz kullanıcı tanımlı hizmet birimi adlarına sahip olmalıdır.
• Tek kanalları adlandırma (E306): Kullanıcı tanımlı hizmet birimi adları yalnızca tam olarak bir örnek işleyen yayıncılara atanabilir.
• Tek yayıncı sınırı (E307): SINGLE_PUB olarak işaretlenen bir protobuf mesajı, sistemin tamamında yalnızca tek bir yayıncı tarafından yayınlanabilir.
• Hizmet birimi adının benzersizliği (E308): Tüm hizmet birimi adları (oluşturulan veya kullanıcı tanımlı) hizmet paketinde benzersiz olmalıdır. Oluşturulan adlarla çakışmaları çözmek için kullanıcı tanımlı adlar kullanılmalıdır.
• Varyant belirtme zorunluluğu (E501): Bir yayıncı, birden fazla varyantı olan bir tür için kullanıcı tanımlı bir ad kullandığında yayınladığı varyantı açıkça belirtmelidir.
• Aboneler için yayıncı varlığı (E504): Tanımlanan her abone için belirtilen tür ve varyantta en az bir karşılık gelen yayıncı gerekir.
• 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 notu koşulu (E602): Bir yayıncı tarafından referans verilen protobuf mesaj türü, SdvPublication notunu 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 spesifikasyonu koşulu (E607): 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 harf ve tireli olmalı, 127 karakteri aşmamalıdır.
• Konu benzersizliği (E314): Konular, tüm yayıncılar genelinde global olarak benzersiz olmalıdır.
• Kapasite koşulları (E406, E407): Kapasite zorunludur ve 2'ye eşit veya 2'den büyük 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 sağlayan bir yayın alıcısını tanımlar. Bu mesajda, abone olunan veri türü ve yayının belirli konuları belirtilir. Bir konuyla ilgili birden fazla yayıncı varsa abone, tüm yayıncıların yayınladığı iletileri 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 yayıncı olmalıdır.
• Geçerli abonelik türü (E608): Abone, SdvPublication ek açıklamasıyla tanımlanmış mevcut bir protobuf mesajına karşılık gelen bir türü referans almalıdır.
• 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): Konu, aboneler için zorunludur.
• Konu yeniden bildirimi (E311): Abone konuları aynı hizmet paketinde yeniden bildirilmemelidir.

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.

Bir UPÇ 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ışı ve sunucu akışı yöntemlerini içerebilir. channel alanı, iletişim uç noktasını tanımlar ve zorunludur (E409).

Sınırlamalar

• Hizmet tanımı (E603): Bir TBG sunucusu, mevcut bir protobuf TBG 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 harf ve tireli olmalıdır.
• Kanal zorunlu (E409): RPC kanalı zorunludur.
• Kanalın benzersizliği (E40B): RPC kanalı yalnızca tek 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, tüketen bir RPC istemcisini tanımlar.ServiceBundle client, istemcinin etkileşimde bulunduğu hizmeti ve bağlanılacak kanalı belirtir. İstemci, hizmet tanımına bağlı olarak tekli, istemci akışı ve sunucu akışı yöntemleriyle etkileşime geçebilir.

Sınırlamalar

• Hizmet tanımı (E60A): Bir 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 bir şekilde tanımlanmalıdır (birden çok kez tanımlanmamalıdır).
• Kanal zorunlu (E409): RPC kanalı zorunludur.

Derleme yapılandırması

Bu bölümde, derleme yapılandırma 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'nin standart olmayan 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. Bunu, otomatik olarak seçilen adlardan daha kısa adlara sahip hedef adları ayarlamak için kullanın.
• skip_codegen (isteğe bağlı bool): Bu hizmet paketi için kod oluşturma işleminin atlanıp atlanmayacağını gösterir. true olarak ayarlanırsa bu hizmet paketi için kod oluşturulmaz. Bu özellik, manuel olarak uygulanan hizmet paketleri için yararlı olabilir. Bu ayar varsayılan olarak false şeklinde belirlenir.

Sınırlamalar

• Hedef adı biçimi (E205, E206, E207, E208): Özel bir derleme hedefi adı (build_cfg.target_name) sağlanırsa kesinlikle snake_case biçimlendirmesine 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ı tanımlı bir build_cfg.target_name, derleme sisteminde benzersiz olmalı ve diğer hizmet paketi tanımlarından türetilen otomatik olarak oluşturulmuş hedef adlarla çakışmamalıdır.