حسگرهای چندگانه HAL

‫Sensors Multi-HAL چارچوبی است که به HALهای حسگر اجازه می‌دهد در کنار دیگر HALهای حسگر اجرا شوند. ‫Sensors Multi-HAL به‌طور پویا زیر HALهای حسگرها را که به‌عنوان کتابخانه‌های پویا در پارتیشن فروشنده ذخیره شده‌اند بار می‌کند و به آن‌ها یک شیء فراخوانی می‌دهد که می‌تواند ارسال رویدادها و دریافت و رها کردن قفل بیدارباش را مدیریت کند. HAL فرعی حسگرها یک HAL حسگرها است که در یک شیء مشترک در پارتیشن فروشنده ساخته شده است و توسط چارچوب چند HAL استفاده می‌شود. این HALهای فرعی به یکدیگر یا به کد چند HAL که حاوی تابع اصلی برای فرایند است وابسته نیستند.

‫Sensors Multi-HAL 2.1 که در دستگاه‌های دارای Android نسخه ۱۱ یا بالاتر دردسترس است، تکراری از Sensors Multi-HAL 2.0 است که از بار کردن زیر HALهایی که می‌توانند نوع حسگر زاویه لولا را نشان دهند پشتیبانی می‌کند. برای پشتیبانی از این نوع حسگر، HALهای فرعی باید از میاناهای برنامه‌سازی کاربردی HAL فرعی تعریف‌شده در سرصفحه SubHal نسخه ۲.۱ استفاده کنند.

برای دستگاه‌های دارای Android 13 یا بالاتر که از Sensors AIDL HAL استفاده می‌کنند، می‌توانید از لایه میانجی چندگانه HAL برای فعال کردن قابلیت چندگانه HAL استفاده کنید. برای جزئیات پیاده‌سازی، استفاده از Sensors Multi-HAL با Sensors AIDL HAL را ببینید.

تفاوت بین «حسگرهای چندگانه HAL 2» و «حسگرهای HAL 2»

«میانای سخت‌افزاری انتزاعی چندگانه حسگرها ۲» که در دستگاه‌های دارای Android 10 یا بالاتر دردسترس است، چندین انتزاع را در بالای میانای سخت‌افزاری انتزاعی حسگرها ۲ معرفی می‌کند تا تعامل با «میاناهای برنامه‌سازی کاربردی» میانای سخت‌افزاری انتزاعی را آسان‌تر کند. Sensors Multi-HAL 2 introduces the HalProxy class to handle implementing the Sensors HAL 2 interface and the V2_1/SubHal (or V2_0/SubHal) interface to allow HalProxy to interact with sub-HALs.

میانای ISensorsSubHal از 2.1/ISensors.hal (یا 2.0/ISensors.hal) میانای به روش‌های زیر متفاوت است:

  • روش مقداردهی اولیه به‌جای دو FMQ و ISensorsCallback، کلاس IHalProxyCallback را ارسال می‌کند.
  • «لایه انتزاع سخت‌افزار فرعی» باید تابع اشکال‌زدایی را برای ارائه اطلاعات اشکال‌زدایی در گزارش‌های اشکال پیاده‌سازی کند.
  • زیر HALها باید تابع نام را پیاده‌سازی کنند تا زیر HAL بارشده بتواند از دیگر زیر HALها متمایز شود.

تفاوت اصلی بین Sensors Multi-HAL 2 و Sensors HAL 2 در توابع اولیه است. به‌جای ارائه FMQ، میانای IHalProxyCallback دو روش ارائه می‌دهد: یک روش برای پست کردن رویدادهای حسگر به چارچوب حسگرها و یک روش برای ایجاد قفل‌های بیدارباش. در پشت صحنه، Sensors Multi-HAL همه تعاملات با FMQ را مدیریت می‌کند تا از ارائه به‌موقع رویدادهای حسگر برای همه زیر-HALها اطمینان حاصل کند. به‌شدت توصیه می‌شود که زیر-HALها از روش createScopedWakelock برای واگذار کردن بار زمان‌بندی قفل‌های بیداری به «چند-HAL حسگرها» استفاده کنند و استفاده از قفل بیداری را در یک قفل بیداری مشترک برای کل «چند-HAL حسگرها» متمرکز کنند، که این کار باعث به‌حداقل رساندن تماس‌های قفل کردن و باز کردن قفل می‌شود.

‫Sensors Multi-HAL 2 همچنین دارای برخی ویژگی‌های ایمنی داخلی است. این تابع موقعیت‌هایی را که در آن FMQ حسگر پر است یا چارچوب حسگر Android بازراه‌اندازی می‌شود و وضعیت حسگر باید بازنشانی شود مدیریت می‌کند. علاوه‌براین، وقتی رویدادها در کلاس HalProxy پست می‌شوند اما چارچوب حسگر نمی‌تواند رویدادها را فوراً بپذیرد، «چندگانه سخت‌افزار انتزاعی حسگرها» می‌تواند رویدادها را به یک رشته پس‌زمینه منتقل کند تا درحالی‌که منتظر پست شدن رویدادها است، کار در همه سخت‌افزارهای انتزاعی فرعی ادامه یابد.

کد منبع و پیاده‌سازی مرجع

همه کدهای Multi-HAL حسگرها در hardware/interfaces/sensors/common/default/2.X/multihal/ دردسترس است. در اینجا به چند منبع اشاره شده است.

  • HalProxy.h: شیء HalProxy توسط Sensors multi-HAL نمونه‌سازی می‌شود و انتقال داده‌ها از sub-HAL به چارچوب حسگر را مدیریت می‌کند.
  • HalProxy.cpp: پیاده‌سازی HalProxy حاوی همه منطق‌های لازم برای ارتباط چندگانه بین sub-HAL و چارچوب حسگر است.

  • SubHal.h: میانای ISensorsSubHal میانایی را تعریف می‌کند که HALهای فرعی باید از آن پیروی کنند تا با HalProxy سازگار باشند. ‫sub-HAL روش initialize را پیاده‌سازی می‌کند تا بتوان از شیء HalProxyCallback برای postEvents و createScopedWakelock استفاده کرد.

    برای پیاده‌سازی‌های Multi-HAL 2.0، از نسخه ۲.۰ SubHal.h استفاده کنید.

  • hardware/interfaces/sensors/common/default/2.X/multihal/tests/: این آزمون‌های واحد پیاده‌سازی HalProxy را درستی‌سنجی می‌کنند.

  • hardware/interfaces/sensors/common/default/2.X/multihal/tests/fake_subhal/: این پیاده‌سازی فرعی HAL از حسگرهای جعلی برای تولید داده‌های جعلی استفاده می‌کند. برای آزمایش نحوه تعامل چند HAL فرعی در دستگاه مفید است.

پیاده‌سازی

این بخش نحوه پیاده‌سازی Sensors Multi-HAL را در موقعیت‌های زیر شرح می‌دهد:

استفاده از Sensors Multi-HAL با Sensors AIDL HAL

برای فعال کردن قابلیت چندگانه HAL با Sensors AIDL HAL، واحد لایه میان‌افزار چندگانه HAL را که در hardware/interfaces/sensors/aidl/default/multihal/ قرار دارد وارد کنید. این ماژول تبدیل بین انواع تعریف HAL حسگرهای AIDL و HIDL را مدیریت می‌کند و یک پوشاننده در اطراف میانای چند HAL تعریف می‌کند که در پیاده‌سازی حسگرهای چند HAL نسخه ۲.۱ شرح داده شده است. لایه واسط چند HAL در AIDL با دستگاه‌هایی که Sensors Multi-HAL 2.1 را پیاده‌سازی می‌کنند سازگار است.

لایه میان‌افزار چندگانه AIDL به شما امکان می‌دهد ردیاب سر و انواع حسگر IMU با محور محدود را در Sensors AIDL HAL نمایان کنید. برای استفاده از این انواع حسگر تعریف‌شده توسط میانای AIDL HAL، فیلد type را در ساختار SensorInfo در پیاده‌سازی getSensorsList_2_1() تنظیم کنید. این کار ایمن است زیرا فیلدهای نوع حسگر با پشتیبانی عدد صحیح در HAL حسگرهای AIDL و HIDL هم‌پوشانی ندارند.

پیاده‌سازی Sensors Multi-HAL 2.1

برای پیاده‌سازی Sensors Multi-HAL 2.1 در دستگاه جدید، این مراحل را دنبال کنید:

  1. واسط ISensorsSubHal را همان‌گونه که در SubHal.h توضیح داده شده است پیاده‌سازی کنید.
  2. روش sensorsHalGetSubHal_2_1 را در SubHal.h پیاده‌سازی کنید.

  3. برای ساختن sub-HAL که به‌تازگی پیاده‌سازی شده است، cc_library_shared هدف اضافه کنید. هنگام افزودن هدف:

    1. مطمئن شوید که هدف به جایی در بخش فروشنده دستگاه ارسال شده باشد.
    2. در فایل پیکربندی واقع در /vendor/etc/sensors/hals.conf، مسیر کتابخانه را در خط جدیدی اضافه کنید. درصورت لزوم، فایل hals.conf را ایجاد کنید.

    برای نمونه Android.bp ورودی برای ساختن کتابخانه زیر HAL، به hardware/interfaces/sensors/common/default/2.X/multihal/tests/Android.bp مراجعه کنید.

  4. همه ورودی‌های android.hardware.sensors را از فایل manifest.xml که حاوی فهرست HALهای پشتیبانی‌شده در دستگاه است بردارید.

  5. همه فایل‌های android.hardware.sensors سرویس و service.rc را از فایل device.mk بردارید و android.hardware.sensors@2.1-service.multihal و android.hardware.sensors@2.1-service.multihal.rc را به PRODUCT_PACKAGES اضافه کنید.

هنگام راه‌اندازی، HalProxy شروع به کار می‌کند، به‌دنبال sub-HAL جدیداً پیاده‌سازی‌شده می‌گردد، و آن را با فراخوانی sensorsHalGetSubHal_2_1 مقداردهی اولیه می‌کند.

انتقال از Sensors Multi-HAL 2.0 به Multi-HAL 2.1

برای انتقال از Multi-HAL 2.0 به Multi-HAL 2.1، SubHal واسط را پیاده‌سازی کنید و sub-HAL را دوباره کامپایل کنید.

تفاوت‌های بین میاناهای 2.0 و 2.1 SubHal عبارتند از:

  • ‫IHalProxyCallback از انواع ایجادشده در نسخه ۲.۱ مشخصات ISensors.hal استفاده می‌کند.
  • تابع initialize() به‌جای تابع مربوط به میانای 2.0 SubHal، IHalProxyCallback جدیدی را ارسال می‌کند
  • «لایه انتزاع سخت‌افزار فرعی» باید getSensorsList_2_1 و injectSensorData_2_1 را به‌جای getSensorsList و injectSensorData پیاده‌سازی کند زیرا این روش‌ها از انواع جدید اضافه‌شده در نسخه ۲.۱ مشخصات ISensors.hal استفاده می‌کنند.
  • زیر HALها باید به‌جای sensorsHalGetSubHal، sensorsHalGetSubHal_2_1 را نمایش دهند تا Multi-HAL آن‌ها را به‌عنوان زیر HALهای نسخه ۲.۱ درنظر بگیرد.

انتقال از Sensors HAL 2.0

هنگام ارتقا دادن از Sensors HAL 2.0 به Sensors Multi-HAL 2.0، مطمئن شوید که پیاده‌سازی HAL الزامات زیر را برآورده می‌کند.

مقداردهی اولیه HAL

‫Sensors HAL 2.0 تابع اولیه دارد که به سرویس حسگر اجازه می‌دهد FMQ و برگشت‌پذیر حسگر پویا را منتقل کند. در Sensors Multi-HAL 2.0، تابع initialize() یک فراخوان برگشتی واحد را ارسال می‌کند که باید برای پست کردن رویدادهای حسگر، دریافت قفل‌های بیدارباش، و اطلاع‌رسانی درباره اتصال و قطع اتصال حسگر پویا استفاده شود.

رویدادهای حسگر را در پیاده‌سازی Multi-HAL پست کنید

به‌جای پست کردن رویدادهای حسگر ازطریق FMQ، زیر-HAL باید رویدادهای حسگر را در IHalProxyCallback وقتی رویدادهای حسگر دردسترس هستند بنویسد.

رویدادهای WAKE_UP

در Sensors HAL 2.0،‏ HAL می‌تواند قفل بیدارباش را برای پیاده‌سازی خود مدیریت کند. In Sensors Multi-HAL 2.0, the sub-HALs allow the Multi-HAL implementation to manage wake locks and can request a wake lock to be acquired by invoking createScopedWakelock. هنگام پست کردن رویدادهای بیدار شدن به پیاده‌سازی Multi-HAL، باید قفل بیداری با محدوده قفل‌شده دریافت شود و به postEvents ارسال شود.

حسگرهای پویا

‫Sensors Multi-HAL 2.0 مستلزم این است که onDynamicSensorsConnected و onDynamicSensorsDisconnected در IHalProxyCallback هرگاه اتصال‌های حسگر پویا تغییر می‌کند فراخوانی شوند. این فراخوانی‌های برگشتی به‌عنوان بخشی از اشاره‌گر IHalProxyCallback که ازطریق تابع initialize() ارائه می‌شود دردسترس هستند.

درگاه از Sensors HAL 1.0

هنگام ارتقا به Sensors Multi-HAL 2.0 از Sensors HAL 1.0، مطمئن شوید که پیاده‌سازی HAL الزامات زیر را برآورده می‌کند.

مقداردهی اولیه HAL

برای ایجاد تماس برگشتی بین پیاده‌سازی sub-HAL و Multi-HAL، باید از تابع initialize() پشتیبانی شود.

نمایش حسگرهای دردسترس

در Sensors Multi-HAL 2.0، تابع getSensorsList() باید مقدار یکسانی را درطول یک‌بار راه‌اندازی دستگاه برگرداند، حتی درصورت بازراه‌اندازی HAL حسگرها. این کار به چارچوب اجازه می‌دهد درصورت بازراه‌اندازی سرور سیستم، اتصال‌های حسگر را دوباره برقرار کند. مقدار برگشتی از getSensorsList() می‌تواند پس‌از بازراه‌اندازی دستگاه تغییر کند.

پست کردن رویدادهای حسگر به پیاده‌سازی Multi-HAL

در Sensors HAL 2.0، به‌جای اینکه منتظر بمانیم poll() فراخوانی شود، sub-HAL باید هرزمان رویدادهای حسگر دردسترس قرار گرفت، به‌صورت پیش‌کنشی رویدادهای حسگر را در IHalProxyCallback بنویسد.

رویدادهای WAKE_UP

در Sensors HAL 1.0،‏ HAL می‌تواند قفل بیدارباش را برای پیاده‌سازی خود مدیریت کند. در Sensors Multi-HAL 2.0، زیر HALها به پیاده‌سازی Multi-HAL اجازه می‌دهند تا قفل‌های بیداری را مدیریت کند و می‌تواند با فراخوانی createScopedWakelock درخواست کند که قفل بیداری دریافت شود. وقتی رویدادهای بیدار شدن در پیاده‌سازی Multi-HAL پست می‌شود، باید قفل بیداری محدودشده قفل‌شده‌ای دریافت و به postEvents ارسال شود.

حسگرهای پویا

در Sensors HAL 1.0، حسگرهای پویا ازطریق تابع poll() برگردانده می‌شوند. «لایه انتزاع سخت‌افزاری چندگانه حسگرها نسخه ۲.۰» ملزم می‌کند که onDynamicSensorsConnected و onDynamicSensorsDisconnected در IHalProxyCallback هر زمان که اتصالات حسگر پویا تغییر می‌کند فراخوانی شوند. این فراخوانی‌های برگشتی به‌عنوان بخشی از اشاره‌گر IHalProxyCallback که ازطریق تابع initialize() ارائه می‌شود دردسترس هستند.

انتقال از Sensors Multi-HAL 1.0

برای انتقال پیاده‌سازی موجود از Sensors Multi-HAL 1.0، این مراحل را دنبال کنید.

  1. مطمئن شوید که پیکربندی HAL حسگرها در /vendor/etc/sensors/hals.conf قرار دارد. این کار ممکن است شامل انتقال فایل موجود در /system/etc/sensors/hals.conf باشد.
  2. هرگونه ارجاع به hardware/hardware.h و hardware/sensors.h را بردارید زیرا این موارد برای HAL 2.0 پشتیبانی نمی‌شوند.
  3. زیر HALها را همان‌طور که در انتقال از Sensors Hal 1.0 شرح داده شده است منتقل کنید.
  4. با دنبال کردن مراحل ۳ و ۴ در بخش پیاده‌سازی «حسگرهای چندگانه HAL 2.0»، «حسگرهای چندگانه HAL 2.0» را به‌عنوان HAL تعیین‌شده تنظیم کنید.

اعتبارسنجی

اجرای VTS

وقتی یک یا چند زیر-HAL را با Sensors Multi-Hal 2.1 یکپارچه کردید، از مجموعه آزمایشی فروشنده (VTS) استفاده کنید تا مطمئن شوید پیاده‌سازی‌های زیر-HAL همه الزامات تعیین‌شده توسط میانای Sensors HAL را برآورده می‌کند.

برای اجرای فقط آزمون‌های VTS حسگرها وقتی VTS در ماشین میزبان راه‌اندازی شده است، فرمان‌های زیر را اجرا کنید:

vts-tradefed run commandAndExit vts \
    --skip-all-system-status-check \
    --primary-abi-only \
    --skip-preconditions \
    --module VtsHalSensorsV2_0Target && \
  vts-tradefed run commandAndExit vts \
    --skip-all-system-status-check \
    --primary-abi-only \
    --skip-preconditions \
    --module VtsHalSensorsV2_1Target

اگر لایه شبیه‌ساز AIDL Multi-HAL را اجرا می‌کنید، VtsAidlHalSensorsTargetTest را اجرا کنید.

vts-tradefed run commandAndExit vts \
    --skip-all-system-status-check \
    --primary-abi-only \
    --skip-preconditions \
    --module VtsAidlHalSensorsTargetTest

اجرای آزمون‌های واحد

آزمون‌های واحد در HalProxy_test.cpp، HalProxy را بااستفاده از زیر HALهای جعلی آزمایش می‌کنند که در آزمون واحد نمونه‌سازی شده‌اند و به‌صورت پویا بارگیری نمی‌شوند. هنگام ایجاد زیرHAL جدید، این آزمایش‌ها باید به‌عنوان راهنمایی برای نحوه افزودن آزمایش‌های واحدی که تأیید می‌کنند زیرHAL جدید به‌درستی پیاده‌سازی شده است عمل کنند.

برای اجرای آزمایش‌ها، فرمان‌های زیر را اجرا کنید:

cd $ANDROID_BUILD_TOP/hardware/interfaces/sensors/common/default/2.X/multihal/tests
atest

آزمایش با زیرواحد سخت‌افزاری انتزاعی جعلی

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

از HALهای فرعی جعلی می‌توان برای آزمایش نحوه عملکرد کد Multi-HAL کامل با سایر HALهای فرعی بارشده در سیستم و برای تحت فشار قرار دادن جنبه‌های مختلف کد Multi-HAL حسگرها استفاده کرد.

دو HAL فرعی جعلی در hardware/interfaces/sensors/common/default/2.X/multihal/tests/fake_subhal/ دردسترس است.

برای ساختن و ارسال زیر-HALهای جعلی به دستگاه، مراحل زیر را انجام دهید:

  1. فرمان‌های زیر را اجرا کنید تا سه زیر-HAL جعلی مختلف را بسازید و به دستگاه ارسال کنید:

    $ANDROID_BUILD_TOP/hardware/interfaces/sensors/common/default/2.X/multihal/tests/
mma
adb push \
  $ANDROID_BUILD_TOP/out/target/product/<device>/symbols/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config1.so \
  /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config1.so
adb push \
  $ANDROID_BUILD_TOP/out/target/product/<device>/symbols/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config2.so \
  /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config2.so
adb push \
  $ANDROID_BUILD_TOP/out/target/product/<device>/symbols/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config3.so \
  /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config3.so

  2. پیکربندی HAL حسگرها را در /vendor/etc/sensors/hals.conf با مسیرهای HAL فرعی جعلی به‌روز کنید.

    /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config1.so
/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config2.so
/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config3.so

  3. ‫HalProxy را بازراه‌اندازی کنید و زیر-HALهای جدید فهرست‌شده در پیکربندی را بار کنید.

    adb shell stop
adb shell start

اشکال‌زدایی

توسعه‌دهندگان می‌توانند چارچوب را بااستفاده از فرمان lshal اشکال‌زدایی کنند. برای درخواست برونداد اشکال‌زدایی «لایه انتزاع سخت‌افزار حسگرها»، فرمان زیر را اجرا کنید:

adb root
adb shell lshal debug android.hardware.sensors@2.1::ISensors/default

اطلاعات مربوط به وضعیت فعلی HalProxy و زیر-HALهای آن سپس در ترمینال نمایش داده می‌شود. در زیر نمونه‌ای از خروجی فرمان برای شیء HalProxy و HALهای فرعی جعلی نشان داده شده است.

Internal values:
  Threads are running: true
  Wakelock timeout start time: 200 ms ago
  Wakelock timeout reset time: 73208 ms ago
  Wakelock ref count: 0
  # of events on pending write queue: 0
  # of non-dynamic sensors across all subhals: 8
  # of dynamic sensors across all subhals: 0
SubHals (2):
  Name: FakeSubHal-OnChange
  Debug dump:
Available sensors:
Name: Ambient Temp Sensor
Min delay: 40000
Flags: 2
Name: Light Sensor
Min delay: 200000
Flags: 2
Name: Proximity Sensor
Min delay: 200000
Flags: 3
Name: Relative Humidity Sensor
Min delay: 40000
Flags: 2
  Name: FakeSubHal-OnChange
  Debug dump:
Available sensors:
Name: Ambient Temp Sensor
Min delay: 40000
Flags: 2
Name: Light Sensor
Min delay: 200000
Flags: 2
Name: Proximity Sensor
Min delay: 200000
Flags: 3
Name: Relative Humidity Sensor
Min delay: 40000
Flags: 2

اگر عدد مشخص‌شده برای # of events on pending write queue عدد بزرگی (۱۰۰۰ یا بیشتر) باشد، این نشان می‌دهد که رویدادهای زیادی درانتظار نوشته شدن در چارچوب حسگرها هستند. این نشان می‌دهد که سرویس حسگر در بن‌بست قرار گرفته یا ازکار افتاده است و رویدادهای حسگر را پردازش نمی‌کند، یا اینکه اخیراً دسته بزرگی از رویدادهای حسگر از HAL فرعی پست شده است.

اگر تعداد ارجاع قفل بیداری بیشتر از 0 باشد، یعنی HalProxy قفل بیداری را به‌دست آورده است. این مقدار فقط درصورتی باید بیشتر از 0 باشد که ScopedWakelock عمداً نگه داشته شده باشد یا رویدادهای بیدار شدن به HalProxy ارسال شده باشد و توسط چارچوب حسگر پردازش نشده باشد.

توصیف‌گر فایل ارسال‌شده به روش اشکال‌زدایی HalProxy به هریک از زیر HALها ارسال می‌شود، بنابراین توسعه‌دهندگان باید روش اشکال‌زدایی را به‌عنوان بخشی از میانای ISensorsSubHal پیاده‌سازی کنند.