1 page.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 28 versions. 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 34 upgrade to 1_3.</p> 35 36 <p>1_1 and 1_2 suffer from poor definition of the batching concept, and are not 37 supported 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 42 sensors.</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 49 implement the <code>batch</code> function. <code>batch</code> is used to set 50 the sampling period and the maximum reporting latency for a given sensor. It 51 replaces <code>setDelay</code>. <code>setDelay</code> will not be called 52 anymore.</p> 53 54 <p>If you do not implement batching, you can implement <code>batch</code> by 55 simply 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> 69 your_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 75 href="{@docRoot}devices/sensors/hal-interface.html#sensor_t">sensor_t</a> 76 fields:</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 = 101 SENSOR_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 109 sensors.h), as this value will be overwritten by the framework. For 110 non-official sensors, see <a 111 href="{@docRoot}devices/sensors/hal-interface.html#sensor_t">sensor_t</a> for 112 details 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 115 access to your sensor. You can usually set this to 0 for all of your sensors, 116 but 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 119 capabilities 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 122 delay between two sensor events corresponding to the lowest frequency that this 123 sensor supports. When lower frequencies are requested through the 124 <code>batch</code> function, the events will be generated at this frequency 125 instead. It can be used by the framework or applications to estimate when the 126 batch FIFO may be full. If this value is not set properly, CTS will fail. 127 For 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 130 microseconds.</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 137 is 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 141 a 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 144 to:</p> 145 146 <p><code>SENSOR_FLAG_WAKE_UP | SENSOR_FLAG_ONE_SHOT_MODE</code> for <a 147 href="{@docRoot}devices/sensors/report-modes.html#one-shot">one-shot</a> 148 sensors</p> 149 150 <p><code>SENSOR_FLAG_CONTINUOUS_MODE</code> for <a 151 href="{@docRoot}devices/sensors/report-modes.html#continuous">continuous</a> 152 sensors <code>SENSOR_FLAG_ON_CHANGE_MODE</code> for <a 153 href="{@docRoot}devices/sensors/report-modes.html#on-change">on-change</a> 154 sensors except <a href="#proximity">proximity</a> 155 <code>SENSOR_FLAG_SPECIAL_REPORTING_MODE</code> for sensors with <a 156 href="{@docRoot}devices/sensors/report-modes.html#special">special</a> 157 reporting mode except for the <a 158 href="{@docRoot}devices/sensors/sensor-types.html#tilt_detector">tilt 159 detector</a>.</p> 160 161 <p><code>SENSOR_FLAG_WAKE_UP | SENSOR_FLAG_ON_CHANGE_MODE</code> for the <a 162 href="{@docRoot}devices/sensors/sensor-types.html#proximity">proximity</a> sensor and the Android official <a 163 href="{@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 168 batching, independently of the value of the timeout argument. The only cases 169 where 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 171 negative <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 174 based on the return value of <code>batch()</code>. 175 <li> Sensors that support batching are always in what we called the batch 176 mode 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 177 stored in the FIFO when the SoC goes to suspend mode. 178 <li> The <code>flags </code>parameter of the <code>batch</code> function is 179 not used anymore. <code>DRY_RUN</code> and <code>WAKE_UPON_FIFO_FULL</code> are 180 both 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
