میانای AIDL VHAL

‫AIDL VHAL در android.hardware.automotive.vehicle namespace تعریف شده است. میانای VHAL در IVehicle.aidl تعریف شده است. مگر اینکه مشخص شده باشد، همه روش‌ها باید برای نسخه VHAL خاصی پیاده‌سازی شوند.

نسخه‌ها

نسخه Android جدیدترین نسخه VHAL جدیدترین نسخه ویژگی VHAL حداقل نسخه سازگار VHAL
‫Android 16 V4 V4 نسخه ۱
Android 15 V3 V3 نسخه ۱
Android 14 V2 V2 نسخه ۱
Android 13 نسخه ۱ (میانای ویژگی VHAL تقسیم نشده است) نسخه ۱

توصیه می‌شود جدیدترین نسخه VHAL را برای نسخه Android خاصی پیاده‌سازی کنید.

توابع و بازخوانی‌ها

توابع VHAL در IVehicle.aidl تعریف شده‌اند.

روش
VehiclePropConfigs getAllPropConfigs()
فهرستی از همه پیکربندی‌های ویژگی پشتیبانی‌شده توسط این لایه انتزاع سخت‌افزار خودرو را برمی‌گرداند.
VehiclePropConfigs getPropConfigs(in int[] props)
فهرستی از پیکربندی‌های دارایی را برای شناسه‌های دارایی داده‌شده برمی‌گرداند.
void getValues(IVehicleCallback callback, in GetValueRequests requests)
دریافت مقادیر خصوصیت خودرو به‌صورت ناهمگام. دسته‌ای از GetValueRequest را به‌صورت ناهمگام مدیریت می‌کند. نتیجه ازطریق روش onGetValues فراخوانی برگشتی ارائه می‌شود.
void setValues(IVehicleCallback callback, in SetValueRequests requests)
مقادیر خصوصیت خودرو را به‌صورت ناهمگام تنظیم کنید. دسته‌ای از SetValueRequest را به‌صورت ناهمگام مدیریت می‌کند. نتیجه ازطریق روش onSetValues فراخوانی برگشتی ارائه می‌شود.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount)
با گزینه‌های مشخص‌شده در رویدادهای دارایی مشترک می‌شود. گزینه‌های اشتراک شامل شناسه ویژگی، شناسه ناحیه ویژگی، و نرخ نمونه‌برداری برحسب هرتز (برای ویژگی پیوسته) است. ‫maxSharedMemoryFileCount استفاده نمی‌شود.
void unsubscribe(in IVehicleCallback callback, in int[] propIds)
اشتراک رویدادهای دارایی را که قبلاً برای دارایی‌های مشخص‌شده مشترک شده‌اند لغو می‌کند.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)
استفاده نمی‌شود و می‌تواند به‌عنوان no-op پیاده‌سازی شود.
(جدید در Android 16)
SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds)
فهرست‌های مقادیر پشتیبانی‌شده را برای جفت‌های شناسه ویژگی و شناسه منطقه مشخص‌شده دریافت می‌کند.
در VHAL نسخه ۴ معرفی شده است.
(جدید در Android 16)
MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds)
حداقل و حداکثر مقادیر پشتیبانی‌شده را برای جفت‌های شناسه ویژگی و شناسه منطقه مشخص‌شده دریافت می‌کند.
در VHAL نسخه ۴ معرفی شده است.
void registerSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
یک فراخوان برگشتی را ثبت می‌کند تا هنگام تغییر مقادیر پشتیبانی‌شده فراخوانی شود.
در VHAL نسخه ۴ معرفی شده است.
void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
ثبت فراخوانی برگشتی تغییر مقدار پشتیبانی‌شده را لغو می‌کند.
در VHAL نسخه ۴ معرفی شده است.

فراخوانی‌های برگشتی در IVehicleCallback.aidl تعریف شده‌اند و شامل این روش‌ها هستند.

روش
oneway void onGetValues(in GetValueResults responses)
بازخوانی برای تابع getValues برای ارائه نتایج دریافت مقدار. وقتی برخی‌از مقادیر برای واکشی آماده باشند، فراخوانی می‌شود.
oneway void onSetValues(in SetValueResults responses)
فراخوانی برگشتی برای تابع setValues برای ارائه نتایج مقدار تنظیم‌شده. وقتی فراخوانی می‌شود که VHAL رسیدگی به برخی‌از درخواست‌های مجموعه ویژگی را به‌پایان رسانده باشد.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)
فراخوانی برای گزارش رویدادهای به‌روزرسانی ویژگی.
CONTINUOUS، رویداد دارایی براساس نرخ نمونه‌برداری اشتراک به هرتز یا بسامد پیام گذرگاه خودرو اتفاق می‌افتد. اگر وضعیت دارایی تغییر کند، ممکن است رویداد دارایی نیز اتفاق بیفتد. برای مثال، از دردسترس نبودن به دردسترس بودن.
برای ویژگی ON_CHANGE، رویداد ویژگی زمانی اتفاق می‌افتد که مقدار ویژگی یا وضعیت ویژگی تغییر کند.
این مورد باید برای ارائه رویدادهای تغییر وضعیت دارایی نیز استفاده شود، برای مثال، وقتی دارایی غیرقابل‌دسترس می‌شود یا خطای خواندن رخ می‌دهد، باید یک VehiclePropValue با وضعیت غیرقابل‌دسترس یا خطا و مقدار خالی ارائه شود.
SharedMemoryFileCount همیشه 0 است.
oneway void onPropertySetError(in VehiclePropErrors errors)
فراخوانی برای گزارش خطاهای مجموعه ویژگی ناهمگام که درخواست مجموعه متناظر ندارند. اگر بدانیم خطا مربوط به کدام درخواست تنظیم است، باید به‌جای این از onSetValues با نتیجه خطا استفاده شود.
oneway void onSupportedValueChange(in List propIdAreaIds)
فراخوانی برای گزارش کردن حداقل و حداکثر مقدار پشتیبانی‌شده یا تغییرات فهرست مقادیر پشتیبانی‌شده. فراخواننده باید getMinMaxSupportedValue یا getSupportedValuesLists را فراخوانی کند تا مقادیر به‌روزشده را دریافت کند.

پیاده‌سازی VHAL توسط VHAL VTS در VtsHalAutomotiveVehicle_TargetTest.cpp اعتبارسنجی می‌شود.

این آزمایش درستی‌سنجی می‌کند که روش‌های پایه به‌درستی پیاده‌سازی شده باشند و پیکربندی‌های ویژگی پشتیبانی‌شده درست باشند. این آزمایش برای همه نمونه‌های VHAL در دستگاه اجرا می‌شود، اما AAOS فقط از نمونه پیش‌فرض (android.hardware.automotive.vehicle.IVehicle/default) استفاده می‌کند

مقدار خصوصیت خودرو

از ساختار VehiclePropValue برای توصیف مقدار هر ویژگی استفاده کنید که این فیلدها را دارد:

فیلد شرح
timestamp مُهر زمانی نشان‌دهنده زمان وقوع رویداد است و با ساعت SystemClock.elapsedRealtimeNano() همگام‌سازی شده است.
prop شناسه دارایی برای این مقدار.
areaid شناسه منطقه برای این مقدار. منطقه باید یکی از مناطق پشتیبانی‌شده فهرست‌شده در پیکربندی شناسه منطقه، یا 0 برای ویژگی‌های جهانی باشد.
value ساختار داده‌ای که حاوی مقدار واقعی دارایی است. براساس نوع ویژگی، یک یا چند فیلد در این فیلد برای ذخیره مقدار واقعی استفاده می‌شود. برای مثال، اولین عنصر در value.int32Values برای ویژگی‌های نوع Int32 استفاده می‌شود. برای جزئیات، پیکربندی‌های دارایی را ببینید.
status وضعیت دارایی برای خواندن. برای ویژگی خواندن/نوشتن، این ممکن است برای نوشتن نیز اعمال شود اما تضمین نمی‌شود، برای مثال، ویژگی ممکن است برای خواندن دردسترس باشد اما برای نوشتن دردسترس نباشد. در این حالت، وضعیت AVAILABLE است و فیلد مقدار حاوی اطلاعات معتبر است. برای وضعیت‌های ممکن، VehiclePropertyStatus را ببینید.

getValues و setValues ناهمگام

عملیات getValues و setValues به‌صورت ناهمگام انجام می‌شوند، یعنی ممکن است تابع قبل‌از تکمیل عملیات واقعی دریافت یا تنظیم برگردانده شود. نتایج عملیات (برای مثال، مقدار ویژگی برای getValues و وضعیت موفقیت یا خطا برای setValues) ازطریق فراخوانی‌های برگشتی که به‌عنوان آرگومان ارسال شده‌اند ارائه می‌شود.

پیاده‌سازی نباید در رشته اتصال‌دهنده‌ای که درخواست را مدیریت می‌کند، نتیجه را مسدود کند. درعوض، توصیه می‌کنیم درخواست را در صف درخواست ذخیره کنید و از رشته گرداننده جداگانه‌ای برای رسیدگی ناهمگام به درخواست‌ها استفاده کنید. برای جزئیات، پیاده‌سازی مرجع را ببینید.

شکل ۱. فرایند ناهمگام.

بسته‌های بزرگ

همه ساختارهای نام‌گذاری‌شده XXXs، مانند VehiclePropConfigs، SetValueRequests، و VehiclePropValues LargeParcelable (یا، StableLargeParcelable) نامیده می‌شوند. هرکدام نشان‌دهنده فهرستی از مقادیر استفاده‌شده برای انتقال داده‌های بزرگ است که ممکن است از محدودیت‌های binder (۴ کیلوبایت در پیاده‌سازی کتابخانه LargeParcelable) در مرزهای binder فراتر رود. هرکدام تعریف ساختار مشابهی دارند که شامل فیلدهای زیر است.

راهنما شرح
payloads فهرست مقادیر وقتی اندازه مقدار در محدوده حافظه binder باشد، یا فهرست خالی.
sharedMemoryFd توصیف‌گر فایل تهی‌پذیر که به فایل حافظه مشترکی اشاره می‌کند که اگر فهرست مقادیر بیش‌ازحد بزرگ باشد، داده‌های مفید سریالی‌شده را ذخیره می‌کند.

برای مثال، VehiclePropConfigs به‌صورت زیر تعریف می‌شود:

parcelable VehiclePropConfigs {
    // The list of vehicle property configs if they fit the binder memory
    // limitation.
    VehiclePropConfig[] payloads;
    // Shared memory file to store configs if they exceed binder memory
    // limitation. Created by VHAL, readable only at client. Client could keep
    // the fd opened or keep the FD mapped to access configs.
    @nullable ParcelFileDescriptor sharedMemoryFd;
}

VehiclePropConfigs حاوی محموله‌های غیرخالی یا sharedMemoryFd غیرتهی است.

  • اگر payloads خالی نباشد، فهرستی از داده‌های واقعی را ذخیره می‌کند که همان پیکربندی دارایی است.
  • اگر sharedMemoryFd تهی نباشد، حاوی فایل حافظه مشترک است که ساختار سریالی‌شده VehiclePropConfigs را ذخیره می‌کند. این ساختار از تابع writeToParcel برای سریال‌سازی Parcel استفاده می‌کند.

به‌عنوان کارخواه Java برای VHAL، «سرویس خودرو» سریال‌سازی و سریال‌زدایی را برای LargeParcelable انجام می‌دهد. برای پیاده‌سازی‌های VHAL و کلاینت‌های بومی، یک LargeParcelable باید با کتابخانه LargeParcelable یا یک کلاس پوشاننده مفید برای کتابخانه در ParcelableUtils.h سریال‌سازی و غیرسریال‌سازی شود.

برای مثال، یک کلاینت بومی که درخواست‌های getValues دریافتی از یک binder را تجزیه می‌کند، به این صورت است:

// 'requests' are from the binder.
GetValueRequests requests;
expected<LargeParcelableBase::BorrowedOwnedObject, ScopedAStatus> deserializedResults = fromStableLargeParcelable(requests);
if (deserializedResults.ok()) {
    const std::vector& getValueRequests = deserializedResults.value().getObject()->payloads;
    // Use the getValueRequests.
  } else {
    // handle error.
}

نمونه پیاده‌سازی VHAL که نتایج getValues را ازطریق بایندر ارسال می‌کند در زیر نشان داده شده است:

std::vector results = getResults();
GetValueResults parcelableResults;
ScopedAStatus status = vectorToStableLargeParcelable(std::move(results), &parcelableResults);
if (status.isOk()) {
    // Send parcelableResults through callback.
} else {
    // Handle error.
}