مشخصات زبان

این صفحه «زبان تعریف میانای سرویس خودرو» (VSIDL) را بااستفاده از «فرم گسترش‌یافته بکوس-نائور» (EBNF) ISO/IEC 14977 و protobuf مشخص می‌کند. این صفحه بر دستور زبان مستقل از بافت زبان و معنی عناصر زبان تمرکز دارد.

سلسله‌مراتب زبان

طبق Meta Object Facility (MOF)، کامپایلر VSIDL (VSIDLC) از زبان‌های نشان‌داده‌شده در شکل ۱ استفاده می‌کند:

زبان‌های VSIDLC

شکل ۱. زبان‌های VSIDLC.

VSIDLC عمدتاً براساس زبان میان‌گیر پروتکل (protobuf) است. Protobuf انواع داده‌های مبادله‌شده بااستفاده از انتشار-اشتراک و فراخوانی‌های رویه از راه دور (RPC) را مشخص می‌کند. ازنظر فنی، مدل‌های VSIDL فایل‌های TextProto هستند و نحو VSIDL در فایل protobuf (syntax.proto) تعریف شده است.

هم فایل‌های protobuf برای مشخص کردن انواع داده و هم مدل‌های VSIDL برای تولید کد Rust استفاده می‌شوند. کد تولیدشده حاوی ساختارهایی برای ساختارهای داده پیام مبادله‌شده و توابع Rust برای ایجاد واحدهای سرویس است، بدون اینکه آن واحدهای سرویس به‌طور خودکار فراخوانی شوند. سپس کد Rust سفارشی از کد تولیدشده برای نمونه‌سازی واحدهای سرویس و پیاده‌سازی منطق برنامه استفاده می‌کند.

نحو انتزاعی

شکل ۲ انواع پیام‌های اصلی را در VSIDL نشان می‌دهد:

انواع پیام‌های اصلی در VSIDL

شکل ۲. انواع پیام اصلی در VSIDL.

ورودی VSIDL

این بخش نوع پیام VsidlEntry را توضیح می‌دهد.

دستور زبان EBNF

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

تعریف Proto

// 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;
}

نمونه کاربرد

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

service_bundle {
  name: "Manager"

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

توضیح

پیام VsidlEntry به‌عنوان محفظه ریشه برای فایل VSIDL با پسوند .vsidl عمل می‌کند. این پیام همه تعاریف و پیکربندی‌ها را در یک فایل VSIDL واحد کپسوله می‌کند. پیام VsidlEntry عنصر سطح بالایی است که همه چیزهای دیگر را به هم متصل می‌کند.

پیام VsidlEntry اهداف زیر را دنبال می‌کند:

  • ساختار کلی فایل VSIDL را تعریف می‌کند.
  • جایِ نام بسته را برای همه نهادهای موجود در فایل مشخص می‌کند.
  • حاوی مجموعه‌ای از تعاریف بسته خدمات است.
  • افزونه‌های سفارشی را برای مدل VSIDL مجاز می‌کند.
  • شامل قوانین نگاشت برای SOME/IP و VHAL.

محدودیت‌ها

  • نام بسته (E211): نام بسته نباید بیشتر از ۱۲۷ نویسه باشد.
  • فایل‌های معلق (E10B): همه فایل‌های موجود در کاتالوگ باید در یک Android.bp گروه فایل ارجاع داده شوند.

بسته خدماتی

این بخش نوع پیام دسته سرویس را توضیح می‌دهد.

دستور زبان EBNF

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

// 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;
}

نمونه کاربرد

service_bundle {
    name: "SeatController"

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

توضیح

دسته سرویس گروه‌بندی منطقی سرویس‌ها، ناشران، مشترکان، سرورهای RPC، و کارخواهان RPC مرتبط را تعریف می‌کند. دسته خدمات به‌عنوان محفظه‌ای برای مجموعه خاصی از عملکردها و تعاملات آن‌ها عمل می‌کند.

محدودیت‌ها

  • الزامات نام بسته (E209،‏ E20A،‏ E20B،‏ E20C):
    • دسته خدمات باید نامی داشته باشد که پر شده باشد.
    • نام باید با نویسه شروع شناسه Unicode معتبر (معمولاً یک حرف) شروع شود.
    • نویسه‌های بعدی در نام باید نویسه‌های ادامه شناسه Unicode معتبر (معمولاً حروف یا اعداد) باشند.
    • نام نباید کلیدواژه رزروشده در Rust،‏ Java، یا C++‎ باشد.
  • یکتایی دسته جهانی (E309): هر دسته سرویس باید نام کاملاً واجدشرایط یکتایی داشته باشد (براساس بسته و نام آن).
  • یکتایی داخلی (E100،‏ E300،‏ E302،‏ E303،‏ E308):
    • Within a single service bundle, each RPC service can be served by at most one server definition.
    • در یک بسته خدمات، هر نوع انتشارات MULTI_PUB می‌تواند حداکثر توسط یک تعریف ناشر منتشر شود.
    • در یک بسته سرویس واحد، همه نام‌های واحد سرویس تعریف‌شده توسط کاربر (برای ناشران یا سرورها) باید منحصربه‌فرد باشند.
    • در یک بسته خدمات، همه نام‌های واحد خدمات (چه تعریف‌شده توسط کاربر یا به‌طور خودکار تولیدشده) باید منحصربه‌فرد باشند.
  • قراردادهای نام‌گذاری هدف ساخت (E205،‏ E206،‏ E207،‏ E208): اگر نام هدف ساخت سفارشی (build_cfg.target_name) ارائه شده باشد، باید از قالب نگارش ماری (حروف کوچک، اعداد، و زیرخط تکی، بدون شروع یا پایان با زیرخط) پیروی کند.
  • یکتا بودن نام هدف ساخت (E301): نام هدف ساخت تعریف‌شده توسط کاربر نباید با نام‌های هدف تولیدشده خودکار برای سایر بسته‌های سرویس تداخل داشته باشد.

ناشر

این بخش نوع پیام «ناشر» را توضیح می‌دهد.

دستور زبان EBNF

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

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

تعریف Proto

// 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;
}

نمونه کاربرد

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

توضیح

نوع پیام Publisher منبع داده‌ای را تعریف می‌کند که ServiceBundle ارائه می‌دهد. این نوع پیام نوع داده‌ای را که منتشر می‌شود و موضوعات خاص و ظرفیت آن داده را مشخص می‌کند.

موضوع

هر نمونه Publisher دارای فیلد message است که به پیام proto درحال انتشار ارجاع می‌دهد. باید موضوع (که با topic نشان داده می‌شود) و ظرفیت (که با capacity نشان داده می‌شود) را مشخص کند.

  • موضوع: شناسه یکتا برای موضوع انتشارات. باید از قالب dash-case با حروف کوچک (برای مثال، my-topic) پیروی کند.
  • ظرفیت: اندازه صف را مشخص می‌کند، یعنی صف چند پیام را می‌تواند نگه دارد تا پیام‌های خوانده‌نشده دور ریخته شوند. باید عدد زوجی بزرگ‌تر یا مساوی ۲ باشد.

نام‌های تعریف‌شده توسط کاربر

ناشران می‌توانند نام‌های واحد خدمات تعریف‌شده توسط کاربر داشته باشند که نام‌های واحد خدمات انتخاب‌شده به‌طور خودکار را لغو می‌کند. این امکان انتخاب نام‌های کوتاه‌تر را فراهم می‌کند. اگر ناشری از نام واحد خدمات تعریف‌شده توسط کاربر استفاده کند، ممکن است فقط از یک نمونه استفاده کند، به‌طوری‌که نام واحد خدمات به‌طور منحصربه‌فرد به یک نمونه اختصاص داده شود.

# 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"
}

محدودیت‌ها

  • جای آگهی ناشر (E300): ناشران برای همان نوع MULTI_PUB باید در بسته‌های خدمات جداگانه تعریف شوند.
  • منحصربه‌فرد بودن نام محلی (E302): در هر بسته سرویس واحد، همه ناشران باید نام‌های واحد سرویس تعریف‌شده توسط کاربر منحصربه‌فرد داشته باشند.
  • یکتایی نام جهانی (E304): ناشران یک نوع انتشارات باید نام‌های واحد خدمات تعریف‌شده توسط کاربر را به‌صورت جهانی در تمام بسته‌های خدمات یکتا داشته باشند.
  • نام‌گذاری کانال‌های تکی (E306): نام‌های واحد خدمات تعریف‌شده توسط کاربر را فقط می‌توان به ناشرانی اختصاص داد که دقیقاً یک نمونه را مدیریت می‌کنند.
  • محدودیت ناشر تکی (E307): پیام protobuf علامت‌گذاری‌شده به‌عنوان SINGLE_PUB فقط توسط یک ناشر در کل سیستم قابل انتشار است.
  • یکتا بودن نام واحد خدمات (E308): همه نام‌های واحد خدمات (چه تولیدشده یا تعریف‌شده توسط کاربر) باید در بسته خدمات خود یکتا باشند؛ نام‌های تعریف‌شده توسط کاربر باید برای حل تعارضات با نام‌های تولیدشده استفاده شوند.
  • الزام مشخصات گونه (E501): وقتی ناشر از نام تعریف‌شده توسط کاربر برای نوعی با چندین گونه استفاده می‌کند، باید گونه‌ای را که منتشر می‌کند به‌طور صریح مشخص کند.
  • وجود ناشر برای مشترکین (E504): هر مشترک تعریف‌شده به حداقل یک ناشر متناظر برای نوع و گونه مشخص‌شده نیاز دارد.
  • نوع ناشر معتبر (E601): ناشر باید به نوعی ارجاع دهد که با پیام protobuf موجود مطابقت داشته باشد.
  • الزام حاشیه‌نویسی انتشار (E602): نوع پیام protobuf که ناشر به آن ارجاع داده است باید شامل حاشیه‌نویسی SdvPublication باشد.
  • استفاده از گونه معتبر (E606): اگر ناشر گونه‌ای (نمونه‌ای) را مشخص کند، آن گونه باید در instances_enum تعریف‌شده برای نوع انتشارات در protobuf وجود داشته باشد.
  • شرط مشخصات گونه (E607): ناشر فقط درصورتی می‌تواند گونه (نمونه) صریحی را مشخص کند که نوع انتشار instances_enum را در protobuf تعریف کند.
  • نام‌گذاری موضوع (E20D،‏ E20F): موضوعات باید با حروف کوچک و با خط تیره از هم جدا شوند و بیشتر از ۱۲۷ نویسه نباشند.
  • منحصربه‌فرد بودن موضوع (E314): موضوع‌ها باید در سطح جهانی در میان همه ناشران منحصربه‌فرد باشند.
  • الزامات ظرفیت (E406،‏ E407): ظرفیت اجباری است و باید عدد زوج >= 2 باشد.

مشترک

این بخش نوع پیام «مشترک» را توضیح می‌دهد.

دستور زبان EBNF

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

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

تعریف Proto

// 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;
}

نمونه کاربرد

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

توضیح

پیام Subscriber گیرنده انتشاراتی را تعریف می‌کند که ServiceBundle ارائه می‌دهد. این پیام نوع داده‌ای را که در آن مشترک شده‌اید و موضوعات خاص آن انتشارات را مشخص می‌کند. اگر چند ناشر برای یک موضوع وجود داشته باشد، مشترک پیام‌های منتشرشده توسط همه آن‌ها را دریافت می‌کند.

محدودیت‌ها

  • وجود ناشر (E504): برای هر مشترک تعریف‌شده، حداقل یک ناشر متناظر باید وجود داشته باشد که نوع و گونه انتشارات مشخص‌شده را منتشر کند.
  • نوع اشتراک معتبر (E608): مشترک باید به نوعی ارجاع دهد که با پیام protobuf موجود تعریف‌شده با حاشیه‌نویسی SdvPublication مطابقت داشته باشد.
  • اشتراک گونه معتبر (E609): اگر مشترک گونه‌ای (نمونه‌ای) را مشخص کند، آن گونه باید مقدار معتبری باشد که در instances_enum نوع انتشار protobuf مربوطه تعریف شده است.
  • موضوع الزامی است (E408): موضوع برای مشترکین الزامی است.
  • اعلام مجدد موضوع (E311): موضوعات مشترک نباید در یک بسته خدمات یکسان مجدداً اعلام شوند.

سرور RPC

این بخش نوع پیام سرور RPC را توضیح می‌دهد.

دستور زبان EBNF

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

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

تعریف Proto

// 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;
}

نمونه کاربرد

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

توضیح

پیام Server سرور RPC را که ServiceBundle ارائه می‌دهد تعریف می‌کند. این پیام سرویسی را که سرور پیاده‌سازی می‌کند و کانال RPC را مشخص می‌کند.

سرور RPC مجموعه‌ای از روش‌ها را ارائه می‌دهد که کارخواهان می‌توانند ازراه‌دور فراخوانی کنند. فیلد ‫service نام سرویس RPC را که سرور پیاده‌سازی می‌کند مشخص می‌کند. این سرویس در یک فایل proto تعریف شده و در کد Rust سفارشی پیاده‌سازی شده است. سرویس‌های RPC می‌توانند شامل روش‌های تک‌مقداری، جاری‌سازی مشتری، و جاری‌سازی سرور باشند، همان‌طور که در تعریف سرویس protobuf تعریف شده است. فیلد channel نقطه پایانی ارتباط را تعریف می‌کند و اجباری است (E409).

محدودیت‌ها

  • تعریف سرویس (E603): سرور RPC باید مقدار service را مشخص کند که با مقدار RPC بافر پروتکل موجود service مطابقت داشته باشد.
  • محدودیت سرور برای هر سرویس (E100): در یک بسته سرویس واحد، یک RPC خاص service می‌تواند حداکثر توسط یک تعریف سرور ارائه شود.
  • نام‌گذاری کانال (E20E): کانال‌های RPC باید با حروف کوچک و خط تیره باشند.
  • کانال الزامی است (E409): کانال RPC الزامی است.
  • یکتایی کانال (E40B): کانال RPC باید فقط توسط یک سرویس استفاده شود.

کارخواه RPC

این بخش نوع پیام کارخواه RPC را توضیح می‌دهد.

دستور زبان EBNF

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

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

تعریف Proto

// 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;
}

نمونه کاربرد

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

توضیح

client یک مشتری RPC را تعریف می‌کند که ServiceBundle مصرف می‌کند. client سرویسی را که مشتری با آن تعامل دارد و کانالی را که به آن متصل می‌شود مشخص می‌کند. کارخواه می‌تواند با روش‌های تک‌مقداری، جاری‌سازی کارخواه، و جاری‌سازی سرور تعامل داشته باشد، که این امر به تعریف سرویس بستگی دارد.

محدودیت‌ها

  • تعریف سرویس (E60A): مشتری RPC باید service را مشخص کند که با تعریف protobuf service موجود مطابقت داشته باشد.
  • منبع سرویس یکتا (E60B): تعریف protobuf service که توسط service مشتری RPC ارجاع داده شده است باید به‌طور یکتا در همه فایل‌های protobuf تعریف شود (نباید چندین بار تعریف شود).
  • کانال الزامی است (E409): کانال RPC الزامی است.

پیکربندی ساخت

این بخش نوع پیام پیکربندی Build را توضیح می‌دهد.

دستور زبان EBNF

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

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

تعریف Proto

// 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;
}

نمونه کاربرد

build_cfg {
  target_name: "my_custom_target_name"
  skip_codegen: false
}

توضیح

BuildConfiguration پارامترهای غیراستاندارد ServiceBundle را برای تولید کد پیکربندی می‌کند. همه پیکربندی‌های ساخت اختیاری هستند.

  • ‫target_name (اختیاری string): نام هدف ساخت را در فایل‌های Android.bp مشخص می‌کند. از این گزینه برای تنظیم نام‌های هدف با نام‌های کوتاه‌تر از نام‌های انتخاب‌شده به‌طور خودکار استفاده کنید.
  • ‫skip_codegen (bool اختیاری): نشان می‌دهد که آیا باید از تولید کد برای این بسته خدمات صرف‌نظر شود یا نه. اگر روی true تنظیم شود، هیچ کدی برای این بسته خدماتی خاص تولید نمی‌شود. این کار می‌تواند برای بسته‌های خدماتی که به‌صورت دستی پیاده‌سازی می‌شوند مفید باشد. به‌طور پیش‌فرض، این گزینه روی false تنظیم شده است.

محدودیت‌ها

  • قالب نام هدف (E205،‏ E206،‏ E207،‏ E208): اگر نام هدف ساخت سفارشی (build_cfg.target_name) ارائه شده باشد، باید دقیقاً از قالب‌بندی نگارش ماری پیروی کند:
    • باید فقط حاوی حروف کوچک (a تا z)، اعداد (0 تا 9)، و زیرخط (_) باشد.
    • نباید حاوی زیرخط‌های متوالی (__) باشد.
    • نباید با زیرخط شروع شود.
    • نباید با زیرخط تمام شود.
  • یکتا بودن نام هدف (E301): build_cfg.target_name تعریف‌شده توسط کاربر باید در سراسر سیستم ساخت یکتا باشد و نباید با هیچ‌یک از نام‌های هدف تولیدشده به‌طور خودکار که از سایر تعاریف بسته سرویس مشتق شده‌اند تداخل داشته باشد.