واجهة AIDL 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 (لم يتم تقسيم واجهة الموقع الإلكتروني للمركبات ذاتية القيادة) V1

يُنصح بتنفيذ أحدث إصدار من 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)
لا يتم استخدامها ويمكن تنفيذها كعملية غير نشطة.
(ميزة جديدة في Android 16)
SupportedValuesListResults getSupportedValuesLists(in List propIdAreaIds)
تعرض هذه الطريقة قوائم القيم المتاحة لأزواج معرّفات المواقع الجغرافية ومعرّفات السمات المحدّدة.
تمت إضافة هذه السمة في الإصدار 4 من VHAL.
(ميزة جديدة في Android 16)
MinMaxSupportedValueResults getMinMaxSupportedValue(in List propIdAreaIds)
تعرض هذه الطريقة الحدّ الأدنى والأقصى للقيم المتوافقة مع أزواج أرقام تعريف المواقع الجغرافية وأرقام تعريف المناطق المحدّدة.
تمت إضافة هذه السمة في الإصدار 4 من VHAL.
void registerSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
تسجّل دالّة ردّ اتصال سيتم استدعاؤها عند تغيير القيم المتوافقة.
تمت إضافة هذه السمة في الإصدار 4 من VHAL.
void unregisterSupportedValueChangeCallback(in IVehicleCallback callback, in List propIdAreaIds)
لإلغاء تسجيل معاودة الاتصال لتغيير القيمة المسموح بها.
تمت إضافة هذه السمة في الإصدار 4 من 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 من خلال VTS الخاص بـ VHAL على 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: عملية غير متزامنة

عناصر parcelable كبيرة

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

الإرشادات الوصف
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 لتسلسل Parcel.

بصفتها برنامج Java للعميل في VHAL، تتولّى خدمة Car Service عملية التسلسل وإلغاء التسلسل لـ 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.
}