センサーAIDLHAL

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Sensors Hardware Abstraction Layer (HAL) は、Android センサー フレームワークとデバイスのセンサー (加速度計やジャイロスコープなど) の間のインターフェイスです。 Sensors HAL は、フレームワークがセンサーを制御できるようにするために実装する必要がある関数を定義します。

Sensors AIDL HAL は、新しいデバイスとアップグレードされたデバイスの Android 13 以降で利用できます。 Sensors HAL 2.1に基づく Sensors AIDL HAL は、 AIDL HAL インターフェースを使用し、ヘッド トラッカーと限定軸 IMU センサー タイプを公開します。

AIDL HAL インターフェイス

Sensors AIDL HAL のドキュメントの主なソースは、 hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidlの HAL 定義内にあります。

センサー AIDL HAL の実装

Sensors AIDL HAL を実装するには、オブジェクトでISensorsインターフェースを拡張し、 hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidlで定義されているすべての関数を実装する必要があります。

HAL の初期化

センサー HAL は、使用する前に Android センサー フレームワークによって初期化する必要があります。フレームワークは、 initialize()関数を呼び出して、センサー HAL に 3 つのパラメーター (2 つの FMQ 記述子とISensorsCallbackオブジェクトへの 1 つのポインター) を提供します。

HAL は最初の記述子を使用して、フレームワークにセンサー イベントを書き込むために使用されるイベント FMQ を作成します。 HAL は 2 番目の記述子を使用して、HAL がWAKE_UPセンサー イベントのウェイクロックを解放するときに同期するために使用されるウェイク ロック FMQ を作成します。 HAL は、必要なコールバック関数を呼び出すことができるように、 ISensorsCallbackオブジェクトへのポインターを保存する必要があります。

initialize()関数は、センサー HAL を初期化するときに最初に呼び出される関数でなければなりません。

利用可能なセンサーの公開

デバイスで使用可能なすべての静的センサーのリストを取得するには、 getSensorsList()関数を使用します。この関数は、ハンドルによって一意に識別されるセンサーのリストを返します。センサー HAL をホストしているプロセスが再起動したときに、特定のセンサーのハンドルを変更してはなりません。ハンドルは、デバイスの再起動やシステム サーバーの再起動によって変更される場合があります。

複数のセンサーが同じセンサー タイプとウェイクアップ プロパティを共有している場合、リストの最初のセンサーはデフォルトセンサーと呼ばれ、 getDefaultSensor(int sensorType, bool wakeUp)関数を利用するアプリに返されます。

センサーリストの安定性

センサー HAL の再起動後、 getSensorsList()によって返されたデータが、再起動前に取得したセンサー リストと比較して大幅な変化を示している場合、フレームワークは Android ランタイムの再起動をトリガーします。センサー リストの大幅な変更には、特定のハンドルを持つセンサーが見つからない、属性が変更された、または新しいセンサーが導入された場合が含まれます。 Android ランタイムの再起動はユーザーにとって混乱を招きますが、アプリの有効期間中に静的 (非動的) センサーが変更されないという Android API 契約を Android フレームワークが満たすことができなくなるため、再起動が必要になります。これにより、アプリによって行われたアクティブなセンサー要求をフレームワークが再確立できなくなる可能性もあります。したがって、HAL ベンダーは、回避可能なセンサー リストの変更を回避することをお勧めします。

安定したセンサー ハンドルを確保するために、HAL はデバイス内の特定の物理センサーをそのハンドルに決定論的にマッピングする必要があります。 Sensors HAL インターフェースによって特定の実装が義務付けられているわけではありませんが、開発者には、この要件を満たすために利用できる多くのオプションがあります。

たとえば、ベンダー、モデル、センサー タイプなど、各センサーの固定属性の組み合わせを使用して、センサー リストを並べ替えることができます。別のオプションは、デバイスの静的センサーのセットがハードウェアで固定されているという事実に依存しているため、HAL は、 getSensorsList()から戻る前に、予想されるすべてのセンサーの初期化がいつ完了したかを知る必要があります。この予想されるセンサーのリストは、HAL バイナリにコンパイルするか、ファイル システムの構成ファイルに格納することができます。また、出現順序を使用して、安定したハンドルを取得できます。最適なソリューションは HAL 固有の実装の詳細によって異なりますが、重要な要件は、HAL の再起動後もセンサー ハンドルが変更されないことです。

センサーの構成

センサーをアクティブ化する前に、 batch()関数を使用して、センサーにサンプリング期間と最大レポート遅延を設定する必要があります。

センサーは、センサー データを失うことなく、 batch()を使用していつでも再構成できる必要があります。

サンプリング期間

サンプリング期間は、構成されているセンサーの種類に基づいて異なる意味を持ちます。

  • 継続: センサー イベントは継続的な速度で生成されます。
  • 変化時: イベントはサンプリング周期より速く生成されず、測定値が変化しない場合はサンプリング周期より遅いレートで生成される場合があります。
  • ワンショット: サンプリング期間は無視されます。
  • 特別: 詳細については、「センサーの種類」を参照してください。

サンプリング期間とセンサーのレポート モードの間の相互作用については、「レポート モード」を参照してください。

最大レポート遅延

最大レポート レイテンシは、SoC が起動している間に HAL を介してイベント FMQ に書き込まれる前に、イベントを遅延させてハードウェア FIFO に格納できる最大時間をナノ秒単位で設定します。

ゼロの値は、FIFO を完全にスキップするか、センサーからの 1 つのイベントが FIFO に存在するとすぐに FIFO を空にするかのいずれかで、測定されたらすぐにイベントを報告する必要があることを意味します。

たとえば、50 Hz でアクティブ化され、最大レポート レイテンシがゼロの加速度計は、SoC が起動しているときに 1 秒あたり 50 回の割り込みをトリガーします。

最大レポート レイテンシが 0 より大きい場合、センサー イベントは、検出されたらすぐにレポートする必要はありません。イベントを一時的にハードウェア FIFO に保存し、イベントが最大レポート レイテンシを超えて遅延しない限り、バッチでレポートすることができます。前のバッチ以降のすべてのイベントが記録され、一度に返されます。これにより、SoC に送信される割り込みの数が減り、センサーがデータをキャプチャしてバッチ処理している間に SoC を低電力モードに切り替えることができます。

各イベントには、関連付けられたタイムスタンプがあります。イベントが報告される時間を遅らせても、イベントのタイムスタンプに影響を与えてはなりません。タイムスタンプは正確で、イベントが報告された時間ではなく、物理的に発生した時間に対応している必要があります。

最大レポート待ち時間がゼロ以外のセンサー イベントのレポートに関する追加情報と要件については、「バッチ処理」を参照してください。

センサーの有効化

フレームワークは、 activate()関数を使用してセンサーを有効および無効にします。センサーをアクティブ化する前に、フレームワークはまずbatch()を使用してセンサーを構成する必要があります。

センサーが非アクティブ化された後、そのセンサーからの追加のセンサー イベントをイベント FMQ に書き込むことはできません。

フラッシングセンサー

センサーがセンサー データをバッチ処理するように構成されている場合、フレームワークは、 flush()を呼び出して、バッチ処理されたセンサー イベントの即時フラッシュを強制できます。これにより、指定されたセンサー ハンドルのバッチ センサー イベントがすぐにイベント FMQ に書き込まれます。 Sensors HAL は、 flush()の呼び出しの結果として書き込まれるセンサー イベントの最後に、フラッシュ完了イベントを追加する必要があります。

フラッシュは非同期で発生します (つまり、この関数はすぐに戻る必要があります)。実装が複数のセンサーに対して 1 つの FIFO を使用する場合、その FIFO はフラッシュされ、指定されたセンサーに対してのみフラッシュ完了イベントが追加されます。

指定されたセンサーに FIFO がない (バッファリングができない) 場合、または呼び出し時に FIFO が空だった場合でも、 flush()は成功し、そのセンサーのフラッシュ完了イベントを送信する必要があります。これは、ワンショット センサー以外のすべてのセンサーに適用されます。

ワンショット センサーに対してflush()が呼び出された場合、flush( flush()BAD_VALUEを返さなければならず、フラッシュ完了イベントを生成してはなりません。

FMQ へのセンサー イベントの書き込み

イベント FMQ は、センサー HAL によってセンサー イベントを Android センサー フレームワークにプッシュするために使用されます。

イベント FMQ は同期された FMQ です。つまり、使用可能なスペースよりも多くのイベントを FMQ に書き込もうとすると、書き込みが失敗します。このような場合、HAL は、現在のイベント セットを 2 つの小さなイベント グループとして書き込むか、十分なスペースが利用可能になったときにすべてのイベントをまとめて書き込むかを決定する必要があります。

センサー HAL が必要な数のセンサー イベントをイベント FMQ に書き込んだ場合、センサー HAL は、 EventQueueFlagBits::READ_AND_PROCESSビットをイベント FMQ のEventFlag::wake関数に書き込むことによって、イベントの準備が整ったことをフレームワークに通知する必要があります。 EventFlag は、 EventFlag::createEventFlagおよびイベント FMQ のgetEventFlagWord()関数を使用して、イベント FMQ から作成できます。

Sensors writeBlocking HAL は、イベント FMQ でwriteと書き込みブロックの両方をサポートします。デフォルトの実装は、 writeを使用するための参照を提供します。 writeBlocking関数を使用する場合、 readNotificationフラグをEventQueueFlagBits::EVENTS_READに設定する必要があります。これは、イベント FMQ からイベントを読み取るときにフレームワークによって設定されます。書き込み通知フラグをEventQueueFlagBits::READ_AND_PROCESSに設定する必要があります。これにより、イベントがイベント FMQ に書き込まれたことがフレームワークに通知されます。

WAKE_UP イベント

WAKE_UPイベントは、アプリケーション プロセッサ (AP) を起動させ、イベントを即座に処理させるセンサー イベントです。 WAKE_UPイベントが Event FMQ に書き込まれるたびに、Sensor HAL はウェイク ロックを確保して、フレームワークがイベントを処理できるようになるまでシステムが起動していることを確認する必要があります。 WAKE_UPイベントを受信すると、フレームワークは独自のウェイクロックを確保し、センサー HAL がそのウェイクロックを解放できるようにします。 Sensors HAL がウェイク ロックを解放するタイミングを同期するには、Wake Lock FMQ を使用します。

Sensors HAL は、Wake Lock FMQ を読み取って、フレームワークが処理したWAKE_UPイベントの数を判断する必要があります。 HAL は、未処理のWAKE_UPイベントの総数がゼロの場合にのみ、 WAKE_UPイベントのウェイク ロックを解放する必要があります。センサー イベントを処理した後、フレームワークはWAKE_UPイベントとしてマークされたイベントの数をカウントし、この数を Wake Lock FMQ に書き戻します。

フレームワークは、WakeLock FMQ にデータを書き込むたびに、 WakeLockQueueFlagBits::DATA_WRITTEN書き込み通知を Wake Lock FMQ に設定します。

動的センサー

動的センサーは、物理的にはデバイスの一部ではありませんが、加速度計を備えたゲームパッドなど、デバイスへの入力として使用できるセンサーです。

動的センサーが接続されている場合、ISensorsCallback のonDynamicSensorConnected関数をセンサー HAL からISensorsCallback必要があります。これにより、新しい動的センサーのフレームワークが通知され、センサーがフレームワークを介して制御され、センサーのイベントがクライアントによって消費されるようになります。

同様に、動的センサーが切断された場合は、ISensorsCallback のonDynamicSensorDisconnected関数をISensorsCallbackて、使用できなくなったセンサーをフレームワークが削除できるようにする必要があります。

直接チャネル

ダイレクト チャネルは、センサー イベントが Android センサー フレームワークをバイパスする Event FMQ ではなく、特定のメモリに書き込まれる操作方法です。ダイレクト チャネルを登録するクライアントは、ダイレクト チャネルの作成に使用されたメモリからセンサー イベントを直接読み取る必要があり、フレームワークを介してセンサー イベントを受け取ることはありません。 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 テスト

Sensors AIDL HAL の VTS テストは、 hardware/interfaces/sensors/aidl/vts/にあります。これらのテストは、センサー HAL が適切に実装されていること、およびISensors.aidlISensorsCallback.aidl内のすべての要件が適切に満たされていることを確認します。

HAL の初期化

フレームワークと HAL の間で FMQ を確立するには、 initialize()関数をサポートする必要があります。

利用可能なセンサーの公開

Sensors AIDL HAL では、 getSensorsList()関数は、Sensors HAL の再起動後であっても、1 回のデバイスの起動中に同じ値を返す必要があります。 getSensorsList()関数の新しい要件は、センサー HAL の再起動後であっても、1 回のデバイスの起動中に同じ値を返す必要があることです。これにより、システム サーバーが再起動した場合に、フレームワークがセンサー接続の再確立を試みることができます。 getSensorsList()によって返される値は、デバイスの再起動後に変更される可能性があります。

FMQ へのセンサー イベントの書き込み

センサー AIDL HAL でpoll()が呼び出されるのを待つ代わりに、センサー HAL は、センサー イベントが利用可能になるたびに、イベント FMQ にセンサー イベントをプロアクティブに書き込む必要があります。 HAL は、正しいビットをEventFlagに書き込み、フレームワーク内で FMQ 読み取りを発生させる役割も果たします。

WAKE_UP イベント

poll() WAKE_UP 1.0 poll() 、フレームワークがすべてのWAKE_UPイベントを処理し、必要に応じてウェイクロック。 Sensors AIDL HAL では、フレームワークが FMQ に書き込まれたイベントを処理したときに HAL に通知されなくなるため、Wake Lock FMQ により、フレームワークはWAKE_UPイベントを処理したときに HAL と通信できます。

Sensors AIDL HAL では、 WAKE_UPイベント用に Sensors HAL によって保護されるウェイクロックはSensorsHAL_WAKEUPで始まる必要があります。

動的センサー

動的センサーは、センサー HAL 1.0 のpoll()関数を使用して返されました。センサー AIDL HAL では、動的センサー接続が変更されるたびに、 ISensorsCallbackonDynamicSensorsConnectedonDynamicSensorsDisconnectedを呼び出す必要があります。これらのコールバックは、 initialize()関数によって提供されるISensorsCallbackポインターの一部として使用できます。

動作モード

WAKE_UPセンサーのDATA_INJECTIONモードがサポートされている必要があります。

マルチ HAL サポート

Sensors AIDL HAL は、 Sensors Multi-HAL フレームワークを使用したマルチ HAL をサポートしています。実装の詳細については、「センサー HAL 2.1 からの移植」を参照してください。