واجهة VHAL

يتم تعريف AIDL VHAL في android.hardware.automotive.vehicle namespace. يتم تعريف واجهة VHAL في IVehicle.aidl. ما لم يتم تحديد خلاف ذلك، يجب تنفيذ جميع الطرق لإصدار معيّن من VHAL.

الإصدارات

إصدار Android أحدث إصدار من VHAL أحدث إصدار من سمة VHAL الحد الأدنى للإصدار المتوافق من VHAL
Android 16 V4 V4 V1
Android 15 V3 V3 V1
Android 14 V2 V2 V1
Android 13 V1 (لم يتم تقسيم واجهة سمة VHAL) V1

ننصح بتنفيذ أحدث إصدار من VHAL لإصدار معيّن من Android.

الدوال وعمليات معاودة الاتصال

يتم تعريف دوال VHAL في IVehicle.aidl.

الطريقة
VehiclePropConfigs getAllPropConfigs()
Returns a list of all Property Configurations supported by this vehicle HAL.
VehiclePropConfigs getPropConfigs(in int[] props)
Returns a list of Property Configurations for given property IDs.
void getValues(IVehicleCallback callback, in GetValueRequests requests)
Get vehicle property values asynchronously. Handles a batch of GetValueRequest asynchronously. The result is delivered through the onGetValues method of callback.
void setValues(IVehicleCallback callback, in SetValueRequests requests)
Set vehicle property values asynchronously. Handles a batch of SetValueRequest asynchronously. The result is delivered through the onSetValues method of callback.
void subscribe(in IVehicleCallback callback, in SubscribeOptions[] options, int maxSharedMemoryFileCount)
Subscribes to property events with specified options. The subscribe options include property ID, property area ID, and sample rate in Hz (for a continuous property). maxSharedMemoryFileCount isn't used.
void unsubscribe(in IVehicleCallback callback, in int[] propIds)
Unsubscribes previously subscribed property events for specified properties.
returnSharedMemory(in IVehicleCallback callback, long sharedMemoryId)
Not used and can be implemented as no-op.
(New in Android 16)
SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds)
Gets the supported values lists for the specified property ID and area ID pairs.
Introduced in VHAL V4.
(New in Android 16)
MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds)
Gets the minimum and maximum supported values for the specified property ID and area ID pairs.
Introduced in VHAL V4.
void registerSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
Registers a callback to be called when the supported values change.
Introduced in VHAL V4.
void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
Unregisters the supported value change callback.
Introduced in VHAL V4.

يتم تعريف عمليات معاودة الاتصال في IVehicleCallback.aidl وتحتوي على هذه الطرق.

الطريقة
oneway void onGetValues(in GetValueResults responses)
Callback for the getValues function to deliver get value results. Called when some of the values to fetch are ready.
oneway void onSetValues(in SetValueResults responses)
Callback for setValues function to deliver set value results. Called when VHAL has finished handling some of the property set requests.
oneway void onPropertyEvent(in VehiclePropValues propValues, int sharedMemoryFileCount)
Callback for reporting property update events.
CONTINUOUS property, a property event happens based on subscribe sample rate in Hz or vehicle bus message frequency. A property event might also happen if a property's status changes. For example, from unavailable to available.
For the ON_CHANGE property, a property event happens when a property's value or a property's status changes.
This should also be used to deliver property status change events, for example, when the property becomes unavailable or error for reading, a VehiclePropValue with an unavailable or error status and an empty value should be delivered.
SharedMemoryFileCount is always 0.
oneway void onPropertySetError(in VehiclePropErrors errors)
Callback for reporting asynchronous property set errors that have no corresponding set request. If we know which set request the error is for, onSetValues with an error result must be used instead of this.
oneway void onSupportedValueChange(in List propIdAreaIds)
Callback for reporting minimum and maximum supported value or supported value list changes. The caller is supposed to call getMinMaxSupportedValue or getSupportedValuesLists to get the updated values.

يتم التحقق من صحة تنفيذ 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) من خلال عمليات معاودة الاتصال التي يتم تمريرها كمعلَمات.

يجب ألا يتم حظر التنفيذ على النتيجة في سلسلة ربط المعالج التي تعالج الطلب. بدلاً من ذلك، ننصحك بتخزين الطلب في قائمة انتظار الطلبات واستخدام سلسلة معالج منفصلة لمعالجة الطلبات بشكلٍ غير متزامن. لمزيد من التفاصيل، اطّلِع على التنفيذ المرجعي.

الشكل 1: العملية غير المتزامنة

الطرود الكبيرة

تُعرف جميع البِنى التي تحمل الاسم XXXs، مثل VehiclePropConfigs، SetValueRequests، وVehiclePropValues باسم LargeParcelable (أو StableLargeParcelable). يمثّل كل منها قائمة بال قيم المستخدَمة لتمرير البيانات الكبيرة التي قد تتجاوز حدود أداة الربط (4 كيلوبايت في تنفيذ مكتبة LargeParcelable) عبر حدود أداة الربط. لكل منها تعريف بنية مشابه يحتوي على الحقول التالية.

الإرشادات الوصف
payloads قائمة بالقيم عندما يتناسب حجم القيمة مع حدّ الذاكرة لأداة الربط، أو قائمة فارغة
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 لتسلسل طرد.

بصفتها عميلاً في Java لـ VHAL، تعالج "خدمة السيارة" عملية النشر على نحو متسلسِل وإلغاء التسلسل لـ LargeParcelable. بالنسبة إلى عمليات تنفيذ VHAL والعملاء الأصليين، يجب نشر LargeParcelable على نحو متسلسِل وإلغاء تسلسله باستخدام LargeParcelable مكتبة أو فئة برنامج تضمين مفيدة للمكتبة في ParcelableUtils.h.

على سبيل المثال، يكون العميل الأصلي الذي يحلّل طلبات getValues الواردة من أداة الربط على النحو التالي:

// '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.
}