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