Sensors AIDL HAL

طبقة تجريد أجهزة الاستشعار (HAL) هي الواجهة بين إطار عمل أجهزة الاستشعار في Android وأجهزة الاستشعار في الجهاز، مثل مقياس التسارع أو الجيروسكوب. تحدّد طبقة تجريد الأجهزة (HAL) الخاصة بأجهزة الاستشعار الوظائف التي يجب تنفيذها للسماح للإطار بالتحكّم في أجهزة الاستشعار.

تتوفّر طبقة تجريد الأجهزة (HAL) لواجهة تعريف لغة وصف البيانات المجردة (AIDL) الخاصة بأجهزة الاستشعار في نظام التشغيل Android 13 والإصدارات الأحدث للأجهزة الجديدة والمحدَّثة. تستخدم طبقة تجريد الأجهزة (HAL) المستندة إلى AIDL لأدوات الاستشعار، والتي تستند إلى طبقة تجريد الأجهزة (HAL) 2.1 لأدوات الاستشعار، واجهة AIDL HAL، وتتيح استخدام أنواع أدوات الاستشعار الخاصة بأجهزة تتبُّع الرأس وأجهزة وحدة القياس بالقصور الذاتي (IMU) ذات المحاور المحدودة.

واجهة AIDL HAL

يقع المصدر الرئيسي لمستندات Sensors AIDL HAL ضمن تعريف HAL في hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl.

تنفيذ طبقة تجريد الأجهزة (HAL) لواجهة تعريف لغة AIDL الخاصة بأدوات الاستشعار

لتنفيذ طبقة تجريد الأجهزة (HAL) لواجهة تعريف لغة AIDL الخاصة بأجهزة الاستشعار، يجب أن يوسّع أحد العناصر واجهة ISensors وأن ينفّذ جميع الدوال المحدّدة في hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl.

إعداد طبقة HAL

يجب أن يتم تهيئة طبقة تجريد الأجهزة (HAL) الخاصة بأجهزة الاستشعار من خلال إطار عمل أجهزة الاستشعار في Android قبل أن يصبح بالإمكان استخدامها. يستدعي إطار العمل الدالة initialize() لتوفير ثلاث مَعلمات إلى Sensors HAL: وصفتان لـ FMQ ومؤشر واحد إلى عنصر ISensorsCallback.

تستخدم طبقة HAL الواصف الأول لإنشاء Event FMQ المستخدَم لكتابة أحداث المستشعر إلى إطار العمل. يستخدم HAL واصفًا ثانيًا لإنشاء Wake Lock FMQ المستخدَم للمزامنة عندما يحرر HAL قفل التنشيط لأحداث WAKE_UP المستشعر. يجب أن يحفظ HAL مؤشرًا إلى العنصر ISensorsCallback حتى يمكن استدعاء أي وظائف رد اتصال ضرورية.

يجب أن تكون الدالة initialize() هي الدالة الأولى التي يتم استدعاؤها عند تهيئة طبقة تجريد الأجهزة (HAL) الخاصة بأجهزة الاستشعار.

عرض أجهزة الاستشعار المتاحة

للحصول على قائمة بجميع المستشعرات الثابتة المتاحة في الجهاز، استخدِم الدالة getSensorsList(). تعرض هذه الدالة قائمة بأدوات الاستشعار، ويتم تحديد كل منها بشكل فريد من خلال معرّفها. يجب ألا يتغيّر معرّف أي جهاز استشعار عند إعادة تشغيل العملية التي تستضيف طبقة تجريد أجهزة الاستشعار. قد تتغير المعرّفات عند إعادة تشغيل الأجهزة أو إعادة تشغيل خادم النظام.

إذا كانت عدّة مستشعرات تتشارك في نوع المستشعر نفسه وخاصية التنشيط، يُطلق على المستشعر الأول في القائمة اسم مستشعر تلقائي ويتم عرضه للتطبيقات التي تستخدم الدالة getDefaultSensor(int sensorType, bool wakeUp).

ثبات قائمة أدوات الاستشعار

بعد إعادة تشغيل Sensors HAL، إذا كانت البيانات التي تعرضها getSensorsList() تشير إلى تغيير كبير مقارنةً بقائمة المستشعرات التي تم استردادها قبل إعادة التشغيل، سيؤدي إطار العمل إلى إعادة تشغيل وقت تشغيل Android. تشمل التغييرات الكبيرة في قائمة أجهزة الاستشعار الحالات التي يكون فيها جهاز استشعار ذو معرّف معيّن غير متوفّر أو تم تغيير سماته، أو الحالات التي يتم فيها تقديم أجهزة استشعار جديدة. على الرغم من أنّ إعادة تشغيل وقت تشغيل Android تؤدي إلى تعطيل تجربة المستخدم، إلا أنّها ضرورية لأنّ إطار عمل Android لم يعُد يستوفي عقد واجهة برمجة التطبيقات Android الذي ينص على أنّ أجهزة الاستشعار الثابتة (غير الديناميكية) لا تتغيّر خلال مدة استخدام التطبيق. وقد يمنع ذلك أيضًا إطار العمل من إعادة إنشاء طلبات أجهزة الاستشعار النشطة التي تقدّمها التطبيقات. لذلك، ننصح مورّدي طبقة تجريد الأجهزة (HAL) بتجنُّب إجراء تغييرات غير ضرورية على قائمة المستشعرات.

لضمان ثبات معرّفات المستشعر، يجب أن تربط طبقة HAL بشكل حتمي مستشعرًا ماديًا معيّنًا في الجهاز بمعرّفه. على الرغم من أنّ واجهة Sensors HAL لا تفرض أي تنفيذ محدّد، يتوفّر للمطوّرين عدد من الخيارات لتلبية هذا الشرط.

على سبيل المثال، يمكن ترتيب قائمة أجهزة الاستشعار باستخدام مجموعة من السمات الثابتة لكل جهاز استشعار، مثل المورّد والطراز ونوع جهاز الاستشعار. يعتمد خيار آخر على حقيقة أنّ مجموعة أجهزة الاستشعار الثابتة في الجهاز تكون ثابتة في الأجهزة، لذا يجب أن تعرف طبقة HAL متى اكتملت عملية تهيئة جميع أجهزة الاستشعار المتوقّعة قبل العودة من getSensorsList(). يمكن تجميع قائمة أجهزة الاستشعار المتوقّعة هذه في ثنائي HAL أو تخزينها في ملف إعداد في نظام الملفات، ويمكن استخدام ترتيب الظهور لاشتقاق معرّفات ثابتة. على الرغم من أنّ أفضل حل يعتمد على تفاصيل التنفيذ المحدّدة لطبقة HAL، فإنّ الشرط الأساسي هو عدم تغيير معرّفات أجهزة الاستشعار عند إعادة تشغيل طبقة HAL.

ضبط أجهزة الاستشعار

قبل تفعيل أي جهاز استشعار، يجب ضبطه باستخدام فترة أخذ العيّنات والحد الأقصى لوقت استجابة إعداد التقارير باستخدام الدالة batch().

يجب أن يكون من الممكن إعادة ضبط جهاز الاستشعار في أي وقت باستخدام batch() بدون فقدان بيانات جهاز الاستشعار.

فترة أخذ العيّنات

يختلف معنى فترة أخذ العيّنات استنادًا إلى نوع المستشعر الذي يتم إعداده:

  • مستمر: يتم إنشاء أحداث المستشعر بمعدّل مستمر.
  • عند التغيير: لا يتم إنشاء الأحداث بشكل أسرع من فترة أخذ العيّنات، وقد يتم إنشاؤها بمعدّل أبطأ من فترة أخذ العيّنات إذا لم تتغيّر القيمة المقاسة.
  • التقييم لمرة واحدة: يتم تجاهل فترة أخذ العيّنات.
  • خاص: لمزيد من التفاصيل، راجِع أنواع المستشعرات.

للتعرّف على التفاعل بين فترة أخذ العيّنات وأوضاع إرسال البيانات في المستشعر، راجِع أوضاع إرسال البيانات.

الحد الأقصى لمدة انتظار إعداد التقارير

يحدّد الحد الأقصى لوقت الاستجابة للتقارير الحد الأقصى للوقت بالنانو ثانية الذي يمكن فيه تأخير الأحداث وتخزينها في قائمة الانتظار FIFO للأجهزة قبل كتابتها إلى Event FMQ من خلال طبقة HAL أثناء تشغيل SoC.

تشير القيمة صفر إلى أنّه يجب تسجيل الأحداث فور قياسها، إما بتخطّي قائمة FIFO بالكامل أو بإفراغها فور توفّر حدث واحد من المستشعر في قائمة FIFO.

على سبيل المثال، يؤدي مقياس التسارع الذي يتم تنشيطه بمعدل 50 هرتز مع الحد الأقصى لوقت الاستجابة للإبلاغ البالغ صفرًا إلى تشغيل المقاطعات 50 مرة في الثانية عندما يكون نظام التشغيل على الشريحة نشطًا.

عندما يكون الحد الأقصى لوقت استجابة إعداد التقارير أكبر من صفر، لا يلزم إعداد تقارير عن أحداث المستشعر فور رصدها. يمكن تخزين الأحداث مؤقتًا في قائمة الانتظار FIFO للأجهزة والإبلاغ عنها على شكل دفعات، طالما لم يتأخّر أي حدث عن الحد الأقصى لوقت استجابة الإبلاغ. يتم تسجيل جميع الأحداث منذ الدفعة السابقة وعرضها مرة واحدة. يقلّل ذلك من عدد المقاطعات التي يتم إرسالها إلى نظام التشغيل على الشريحة (SoC)، ويتيح لنظام التشغيل على الشريحة التبديل إلى وضع استهلاك أقل للطاقة أثناء جمع البيانات وتجميعها.

يتضمّن كل حدث طابعًا زمنيًا مرتبطًا به. يجب ألا يؤثر تأخير الوقت الذي يتم فيه تسجيل حدث في الطابع الزمني للحدث. يجب أن يكون الطابع الزمني دقيقًا وأن يتطابق مع وقت وقوع الحدث فعليًا، وليس مع وقت إرسال التقرير عنه.

للحصول على معلومات ومتطلبات إضافية حول تسجيل أحداث المستشعر مع الحد الأقصى لوقت الاستجابة غير الصفري، يُرجى الاطّلاع على التجميع.

تفعيل أجهزة الاستشعار

يتيح إطار العمل تفعيل المستشعرات وإيقافها باستخدام الدالة activate(). قبل تفعيل أداة الاستشعار، يجب أن يضبط الإطار أداة الاستشعار أولاً باستخدام batch().

بعد إيقاف جهاز الاستشعار، يجب عدم كتابة أحداث إضافية من جهاز الاستشعار هذا إلى قائمة FMQ للأحداث.

أجهزة الاستشعار المخفية

إذا تم ضبط جهاز استشعار على تجميع بياناته في دفعات، يمكن للإطار فرض إفراغ فوري لأحداث أجهزة الاستشعار المجمّعة في دفعات من خلال استدعاء flush(). يؤدي ذلك إلى كتابة أحداث أداة الاستشعار المجمّعة لمقبض أداة الاستشعار المحدّد على الفور في Event FMQ. يجب أن يضيف Sensors HAL حدث اكتمال عملية المسح إلى نهاية أحداث المستشعر التي يتم تسجيلها نتيجة طلب flush().

تتم عملية المسح بشكل غير متزامن (أي يجب أن تعرض هذه الدالة النتيجة على الفور). إذا كان التنفيذ يستخدم قائمة انتظار FIFO واحدة لعدة أجهزة استشعار، يتم إفراغ قائمة الانتظار FIFO وإضافة حدث اكتمال الإفراغ لجهاز الاستشعار المحدّد فقط.

إذا لم يكن المستشعر المحدّد يتضمّن ذاكرة FIFO (لا يمكن التخزين المؤقت)، أو إذا كانت ذاكرة FIFO فارغة وقت إجراء المكالمة، يجب أن تنجح الدالة flush() وأن ترسل حدثًا يشير إلى اكتمال عملية المسح لهذا المستشعر. وينطبق ذلك على جميع أجهزة الاستشعار باستثناء أجهزة الاستشعار التي تعمل لمرة واحدة.

إذا تم استدعاء flush() لمستشعر لمرة واحدة، يجب أن تعرض flush() القيمة BAD_VALUE وألا تنشئ حدث اكتمال التخزين المؤقت.

كتابة بيانات أحداث أجهزة الاستشعار في قائمة FMQ

يتم استخدام Event FMQ من قِبل Sensors HAL لإرسال أحداث أجهزة الاستشعار إلى إطار عمل أجهزة الاستشعار في Android.

قائمة انتظار FMQ للأحداث هي قائمة انتظار FMQ متزامنة، ما يعني أنّ أي محاولة لكتابة أحداث في قائمة انتظار FMQ أكثر من المساحة المتاحة تؤدي إلى تعذُّر الكتابة. في هذه الحالة، يجب أن تحدّد طبقة HAL ما إذا كان سيتم كتابة المجموعة الحالية من الأحداث كمجموعتين أصغر من الأحداث أو كتابة جميع الأحداث معًا عند توفّر مساحة كافية.

عندما يكتب Sensors HAL العدد المطلوب من أحداث أجهزة الاستشعار إلى Event FMQ، يجب أن يرسل Sensors HAL إشعارًا إلى إطار العمل بأنّ الأحداث جاهزة من خلال كتابة البت EventQueueFlagBits::READ_AND_PROCESS إلى الدالة EventFlag::wake في Event FMQ. يمكن إنشاء EventFlag من Event FMQ باستخدام EventFlag::createEventFlag ودالة getEventFlagWord() في Event FMQ.

تتيح طبقة تجريد الأجهزة (HAL) المستندة إلى AIDL الخاصة بأجهزة الاستشعار استخدام كل من write وwriteBlocking في قائمة انتظار الرسائل السريعة (FMQ) الخاصة بالأحداث. يوفّر التنفيذ التلقائي مرجعًا لاستخدام write. في حال استخدام الدالة writeBlocking، يجب ضبط العلامة readNotification على EventQueueFlagBits::EVENTS_READ، ويتم ضبطها من خلال إطار العمل عند قراءة الأحداث من Event FMQ. يجب ضبط علامة إشعار الكتابة على EventQueueFlagBits::READ_AND_PROCESS، ما يرسل إشعارًا إلى إطار العمل بأنّه تمّت كتابة أحداث في قائمة انتظار الرسائل السريعة (FMQ) الخاصة بالأحداث.

أحداث WAKE_UP

أحداث WAKE_UP هي أحداث مستشعر تؤدي إلى تنبيه معالج التطبيق (AP) والتعامل مع الحدث على الفور. عندما يتم تسجيل حدث WAKE_UP في قائمة انتظار الرسائل السريعة (FMQ) الخاصة بالأحداث، يجب أن يحصل Sensors HAL على قفل تنبيه لضمان بقاء النظام نشطًا إلى أن يتمكّن إطار العمل من معالجة الحدث. عند تلقّي حدث WAKE_UP، يؤمّن إطار العمل قفل التنشيط الخاص به، ما يسمح لطبقة تجريد الأجهزة (HAL) الخاصة بأجهزة الاستشعار بإيقاف قفل التنشيط. لمزامنة وقت إيقاف قفل التنشيط في طبقة تجريد الأجهزة (HAL) الخاصة بأدوات الاستشعار، استخدِم Wake Lock FMQ.

يجب أن يقرأ Sensors HAL Wake Lock FMQ لتحديد عدد WAKE_UP الأحداث التي تعامل معها إطار العمل. يجب ألا يحرّر HAL قفل التنشيط إلا لأحداث WAKE_UP إذا كان إجمالي عدد أحداث WAKE_UP التي لم تتم معالجتها صفرًا. بعد معالجة أحداث المستشعر، يحسب إطار العمل عدد الأحداث التي تم وضع علامة عليها كأحداث WAKE_UP، ثم يعيد كتابة هذا العدد إلى Wake Lock FMQ.

يضبط إطار العمل إشعار WakeLockQueueFlagBits::DATA_WRITTEN write على Wake Lock FMQ كلما كتب بيانات إلى Wake Lock FMQ.

أجهزة الاستشعار الديناميكية

أجهزة الاستشعار الديناميكية هي أجهزة استشعار ليست جزءًا من الجهاز، ولكن يمكن استخدامها كمدخلات للجهاز، مثل عصا الألعاب التي تتضمّن مقياس تسارع.

عند توصيل جهاز استشعار ديناميكي، يجب استدعاء الدالة onDynamicSensorConnected في ISensorsCallback من Sensors HAL. يؤدي ذلك إلى إعلام إطار العمل بجهاز الاستشعار الديناميكي الجديد، ويتيح التحكّم في جهاز الاستشعار من خلال إطار العمل واستهلاك الأحداث التي يرصدها جهاز الاستشعار من قِبل العملاء.

وبالمثل، عند فصل جهاز استشعار ديناميكي، يجب استدعاء الدالة onDynamicSensorDisconnected في ISensorsCallback حتى يتمكّن إطار العمل من إزالة أي جهاز استشعار لم يعُد متاحًا.

قناة مباشرة

القناة المباشرة هي طريقة تشغيل يتم فيها كتابة أحداث المستشعر في ذاكرة معيّنة بدلاً من كتابتها في Event FMQ، ما يؤدي إلى تجاوز إطار عمل Android Sensors. يجب أن يقرأ التطبيق الذي يسجّل قناة مباشرة أحداث أجهزة الاستشعار مباشرةً من الذاكرة التي تم استخدامها لإنشاء القناة المباشرة، ولن يتلقّى أحداث أجهزة الاستشعار من خلال إطار العمل. تشبه الدالة configDirectReport() الدالة batch() في التشغيل العادي، كما أنّها تضبط قناة التقارير المباشرة.

تنشئ الدالتان registerDirectChannel() وunregisterDirectChannel() قناة مباشرة جديدة أو تحذفانها.

أوضاع التشغيل

تسمح الدالة setOperationMode() للإطار بضبط إعدادات أداة استشعار ليتمكّن الإطار من إدخال بيانات أداة الاستشعار إلى الأداة. ويفيد ذلك في الاختبار، لا سيما بالنسبة إلى الخوارزميات التي تقع أسفل إطار العمل.

يتم عادةً استخدام الدالة injectSensorData() لإرسال المَعلمات التشغيلية إلى طبقة تجريد الأجهزة (HAL) الخاصة بأجهزة الاستشعار. يمكن أيضًا استخدام الدالة لإدخال أحداث مستشعر في مستشعر معيّن.

التحقُّق

للتحقّق من صحة تنفيذ طبقة تجريد الأجهزة (HAL) الخاصة بأجهزة الاستشعار، شغِّل اختبارات CTS وVTS الخاصة بأجهزة الاستشعار.

اختبارات مجموعة أدوات اختبار التوافق (CTS)

تتوفّر اختبارات CTS الخاصة بأجهزة الاستشعار في كل من اختبارات CTS المبرمَجة وتطبيق CTS Verifier اليدوي.

تتوفّر الاختبارات المبرمَجة في cts/tests/sensor/src/android/hardware/cts. تتحقّق هذه الاختبارات من الوظائف العادية لأجهزة الاستشعار، مثل تفعيل أجهزة الاستشعار وتجميع البيانات ومعدّلات أحداث أجهزة الاستشعار.

تتوفّر اختبارات CTS Verifier في cts/apps/CtsVerifier/src/com/android/cts/verifier/sensors. تتطلّب هذه الاختبارات إدخال بيانات يدويًا من مشغّل الاختبار، وتضمن أن تقدّم المستشعرات قيمًا دقيقة.

ويُعد اجتياز اختبارات CTS أمرًا بالغ الأهمية لضمان استيفاء الجهاز الخاضع للاختبار جميع متطلبات CDD.

اختبارات VTS

تتوفّر اختبارات VTS الخاصة بـ Sensors AIDL HAL في hardware/interfaces/sensors/aidl/vts/‎. تضمن هذه الاختبارات تنفيذ Sensors HAL بشكل سليم واستيفاء جميع المتطلبات الواردة في ISensors.aidl وISensorsCallback.aidl بشكل سليم.

إعداد طبقة HAL

يجب أن تكون الدالة initialize() متوافقة لإنشاء قوائم FMQ بين إطار العمل وطبقة HAL.

عرض أجهزة الاستشعار المتاحة

في Sensors AIDL HAL، يجب أن تعرض الدالة getSensorsList() القيمة نفسها أثناء عملية إعادة تشغيل واحدة للجهاز، حتى عند إعادة تشغيل Sensors HAL. من المتطلبات الجديدة للدالة getSensorsList() أن تعرض القيمة نفسها أثناء عملية إعادة تشغيل واحدة للجهاز، حتى في حال إعادة تشغيل طبقة تجريد الأجهزة (HAL) الخاصة بأجهزة الاستشعار. ويتيح ذلك للإطار محاولة إعادة إنشاء اتصالات المستشعر في حال إعادة تشغيل خادم النظام. يمكن أن تتغيّر القيمة التي تعرضها getSensorsList() بعد إعادة تشغيل الجهاز.

كتابة بيانات أحداث أجهزة الاستشعار في قائمة FMQ

بدلاً من انتظار استدعاء poll()، يجب أن يكتب Sensors HAL أحداث أجهزة الاستشعار بشكل استباقي إلى Event FMQ كلما توفّرت أحداث أجهزة الاستشعار، وذلك في Sensors AIDL HAL. تتولّى طبقة HAL أيضًا مسؤولية كتابة وحدات البت الصحيحة إلى EventFlag لتفعيل عملية قراءة FMQ ضمن إطار العمل.

أحداث WAKE_UP

في الإصدار 1.0 من Sensors HAL، كان بإمكان طبقة HAL إيقاف قفل التنشيط لأي حدث WAKE_UP في أي عملية استدعاء لاحقة إلى poll() بعد نشر WAKE_UP إلى poll()، لأنّ ذلك يشير إلى أنّ إطار العمل قد عالج جميع أحداث المستشعر وحصل على قفل تنشيط، إذا لزم الأمر. في واجهة AIDL الخاصة بطبقة HAL الخاصة بأجهزة الاستشعار، لم يعُد يتم إشعار طبقة HAL عندما يعالج إطار العمل الأحداث المكتوبة في قائمة FMQ. تتيح قائمة FMQ الخاصة بقفل التنشيط لإطار العمل إمكانية التواصل مع طبقة HAL عندما يعالج أحداث WAKE_UP.

في Sensors AIDL HAL، يجب أن يبدأ قفل التنشيط الذي يوفّره Sensors HAL WAKE_UP للأحداث بـ SensorsHAL_WAKEUP.

أجهزة الاستشعار الديناميكية

تم عرض أجهزة الاستشعار الديناميكية باستخدام الدالة poll() في Sensors HAL 1.0. يتطلّب Sensors AIDL HAL استدعاء onDynamicSensorsConnected وonDynamicSensorsDisconnected في ISensorsCallback كلما تغيّرت اتصالات المستشعر الديناميكي. تتوفّر عمليات رد الاتصال هذه كجزء من المؤشر ISensorsCallback الذي يتم توفيره من خلال الدالة initialize().

أوضاع التشغيل

يجب أن يكون وضع DATA_INJECTION متوافقًا مع أجهزة الاستشعار WAKE_UP.

دعم طبقات HAL المتعددة

تتيح طبقة تجريد الأجهزة (HAL) لواجهة تعريف لغة وصف البيانات المجردة (AIDL) الخاصة بأجهزة الاستشعار استخدام عدة طبقات تجريد أجهزة (HAL) من خلال إطار عمل Sensors Multi-HAL. للحصول على تفاصيل التنفيذ، يُرجى الاطّلاع على نقل البيانات من Sensors HAL 2.1.