1page.title=HAL version deprecation
2@jd:body
3
4<!--
5    Copyright 2014 The Android Open Source Project
6
7    Licensed under the Apache License, Version 2.0 (the "License");
8    you may not use this file except in compliance with the License.
9    You may obtain a copy of the License at
10
11        http://www.apache.org/licenses/LICENSE-2.0
12
13    Unless required by applicable law or agreed to in writing, software
14    distributed under the License is distributed on an "AS IS" BASIS,
15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    See the License for the specific language governing permissions and
17    limitations under the License.
18-->
19<div id="qv-wrapper">
20  <div id="qv">
21    <h2>In this document</h2>
22    <ol id="auto-toc">
23    </ol>
24  </div>
25</div>
26
27<p>In the L release of Android, we are halting support for some sensor HAL
28versions. The only supported versions are <code>SENSORS_DEVICE_API_VERSION_1_0
29</code>and <code>SENSORS_DEVICE_API_VERSION_1_3</code>.</p>
30
31<p>In the next releases, we are likely to drop support for 1_0 as well.</p>
32
33<p>1_0 has no concept of batching. If possible, all devices using 1_0 SHOULD
34upgrade to 1_3.</p>
35
36<p>1_1 and 1_2 suffer from poor definition of the batching concept, and are not
37supported anymore</p>
38
39<p>All devices currently using 1_1 or 1_2 MUST upgrade to 1_3.</p>
40
41<p>In 1_3, we simplified the notion of batching, and we introduced wake up
42sensors.</p>
43
44<p>To upgrade to 1_3, follow the changes listed below.</p>
45
46<h2>Implement the batch function</h2>
47
48<p>Even if you do not implement batching (your hardware has no FIFO), you must
49implement the <code>batch</code> function. <code>batch</code> is used to set
50the sampling period and the maximum reporting latency for a given sensor. It
51replaces <code>setDelay</code>. <code>setDelay</code> will not be called
52anymore.</p>
53
54<p>If you do not implement batching, you can implement <code>batch</code> by
55simply calling your existing <code>setDelay</code> function with the provided
56<code>sampling_period_ns</code> parameter.</p>
57
58<h2>Implement the flush function</h2>
59
60<p>Even if you do not implement batching, you must implement the
61<code>flush</code> function.</p>
62
63<p>If you do not implement batching, <code>flush</code> must generate one
64<code>META_DATA_FLUSH_COMPLETE</code> event and return 0 (success).</p>
65
66<h2>Change your sensors_poll_device_t.common.version</h2>
67
68<pre class=prettyprint>
69your_poll_device.common.version = SENSORS_DEVICE_API_VERSION_1_3
70</pre>
71
72<h2>Add the new fields to the definition of your sensors</h2>
73
74<p>When defining each sensor, in addition to the usual <a
75href="{@docRoot}devices/sensors/hal-interface.html#sensor_t">sensor_t</a>
76fields:</p>
77
78<pre class=prettyprint>
79.name =       "My magnetic field Sensor",
80.vendor =     "My company",
81.version
82=    1,
83.handle =     mag_handle,
84.type =       SENSOR_TYPE_MAGNETIC_FIELD,
85.maxRange =   200.0f,
86.resolution = CONVERT_M,
87.power =      5.0f,
88.minDelay =
89 16667,
90</pre>
91
92<p>you also must set the new fields, defined between 1_0 and 1_3:</p>
93
94<pre class=prettyprint>
95.fifoReservedEventCount = 0,
96.fifoMaxEventCount =   0,
97.stringType =         0,
98.requiredPermission = 0,
99.maxDelay =      200000
100.flags =
101SENSOR_FLAG_CONTINUOUS_MODE,
102</pre>
103
104<p><em>fifoReservedEventCount</em>: If not implementing batching, set this one to 0.</p>
105
106<p><em>fifoMaxEventCount</em>: If not implementing batching, set this one to 0</p>
107
108<p><em>stringType</em>: Set to 0 for all official android sensors (those that are defined in
109sensors.h), as this value will be overwritten by the framework. For
110non-official sensors, see <a
111href="{@docRoot}devices/sensors/hal-interface.html#sensor_t">sensor_t</a> for
112details on how to set it.</p>
113
114<p><em>requiredPermission</em>: This is the permission that applications will be required to have to get
115access to your sensor. You can usually set this to 0 for all of your sensors,
116but sensors with type <code>HEART_RATE</code> must set this to <code>SENSOR_PERMISSION_BODY_SENSORS.</code></p>
117
118<p><em>maxDelay</em>: This value is important and you will need to set it according to the
119capabilities of the sensor and of its driver.</p>
120
121<p>This value is defined only for continuous and on-change sensors. It is the
122delay between two sensor events corresponding to the lowest frequency that this
123sensor supports. When lower frequencies are requested through the
124<code>batch</code> function, the events will be generated at this frequency
125instead. It can be used by the framework or applications to estimate when the
126batch FIFO may be full. If this value is not set properly, CTS will fail.
127For one-shot and special reporting mode sensors, set <code>maxDelay</code> to 0.</p>
128
129<p>For continuous sensors, set it to the maximum sampling period allowed in
130microseconds.</p>
131
132<p>Note:</p>
133<ul>
134<li><code>period_ns</code> is in nanoseconds whereas
135<code>maxDelay</code>/<code>minDelay</code> are in microseconds.</li>
136<li><code>maxDelay </code>should always fit within a 32-bit signed integer. It
137is declared as 64 bit on 64 bit architectures only for binary compatibility reasons.</li>
138</ul>
139
140<p><em>flags</em>: This field defines the reporting mode of the sensor and whether the sensor is
141a wake up sensor.</p>
142
143<p>If you do not implement batching, and are just moving from 1.0 to 1.3, set this
144to:</p>
145
146<p><code>SENSOR_FLAG_WAKE_UP | SENSOR_FLAG_ONE_SHOT_MODE</code> for <a
147href="{@docRoot}devices/sensors/report-modes.html#one-shot">one-shot</a>
148sensors</p>
149
150<p><code>SENSOR_FLAG_CONTINUOUS_MODE</code> for <a
151href="{@docRoot}devices/sensors/report-modes.html#continuous">continuous</a>
152sensors <code>SENSOR_FLAG_ON_CHANGE_MODE</code> for <a
153href="{@docRoot}devices/sensors/report-modes.html#on-change">on-change</a>
154sensors except <a href="#proximity">proximity</a>
155<code>SENSOR_FLAG_SPECIAL_REPORTING_MODE</code> for sensors with <a
156href="{@docRoot}devices/sensors/report-modes.html#special">special</a>
157reporting mode except for the <a
158href="{@docRoot}devices/sensors/sensor-types.html#tilt_detector">tilt
159detector</a>.</p>
160
161<p><code>SENSOR_FLAG_WAKE_UP | SENSOR_FLAG_ON_CHANGE_MODE</code> for the <a
162href="{@docRoot}devices/sensors/sensor-types.html#proximity">proximity</a> sensor and the Android official <a
163href="{@docRoot}devices/sensors/sensor-types.html#tilt_detector">tilt detector</a> sensor.</p>
164
165<h2>Notes when upgrading from 1_1 or 1_2</h2>
166<ul>
167  <li> The <code>batch</code> function now nearly-always succeeds, even for sensors that do not support
168batching, independently of the value of the timeout argument. The only cases
169where the <code>batch </code>function might fail are internal errors, or a bad
170<code>sensor_handle,</code> or negative <code>sampling_period_ns </code>or
171negative <code>max_report_latency_ns</code>.
172  <li> Whether a sensor supports batching is defined by whether it has a
173<code>fifoMaxEventCount </code>greater than 0. (In previous versions, it was
174based on the return value of <code>batch()</code>.
175  <li> Sensors that support batching are always in what we called the “batch
176mode” in previous versions: even if the <code>max_report_latency_ns</code> parameter is 0, the sensor must still be batched, meaning the events must be
177stored in the FIFO when the SoC goes to suspend mode.
178  <li> The <code>flags </code>parameter of the <code>batch</code> function is
179not used anymore. <code>DRY_RUN</code> and <code>WAKE_UPON_FIFO_FULL</code> are
180both deprecated, and will never be passed to the <code>batch</code> function.
181  <li> The batch timeout argument is now referred to as the
182<code>max_report_latency</code> argument.
183</ul>
184