1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef CHRE_CORE_SENSOR_REQUEST_H_ 18 #define CHRE_CORE_SENSOR_REQUEST_H_ 19 20 #include <cstdint> 21 22 #include "chre_api/chre/sensor.h" 23 #include "chre/core/nanoapp.h" 24 #include "chre/util/time.h" 25 26 namespace chre { 27 28 //! Maximum of non-default interval and latency values in nanoseconds to ensure 29 //! no overflow in CHRE operations. 30 constexpr uint64_t kMaxIntervalLatencyNs = (UINT64_MAX - 1) / 2; 31 32 // TODO: Move SensorType and related functions to a new file called 33 // sensor_type.h and include it here. This will allow using this logic in util 34 // code withput pulling in the entire SensorRequest class which is only intended 35 // to be used by the CHRE implementation. 36 37 //! The union of possible CHRE sensor data event type with one sample. 38 union ChreSensorData { 39 struct chreSensorThreeAxisData threeAxisData; 40 struct chreSensorOccurrenceData occurrenceData; 41 struct chreSensorFloatData floatData; 42 struct chreSensorByteData byteData; 43 }; 44 45 /** 46 * This SensorType is designed to wrap constants provided by the CHRE API 47 * to improve type-safety. In addition, an unknown sensor type is provided 48 * for dealing with sensors that are not defined as per the CHRE API 49 * specification. The details of these sensors are left to the CHRE API 50 * sensor definitions. 51 */ 52 enum class SensorType { 53 Unknown, 54 Accelerometer, 55 InstantMotion, 56 StationaryDetect, 57 Gyroscope, 58 GeomagneticField, 59 Pressure, 60 Light, 61 Proximity, 62 AccelerometerTemperature, 63 GyroscopeTemperature, 64 UncalibratedAccelerometer, 65 UncalibratedGyroscope, 66 UncalibratedGeomagneticField, 67 68 // Note to future developers: don't forget to update the implementation of 69 // 1) getSensorTypeName, 70 // 2) getSensorTypeFromUnsignedInt, 71 // 3) getUnsignedIntFromSensorType, 72 // 4) getSensorSampleTypeFromSensorType 73 // 5) sensorTypeIsOneShot 74 // 6) sensorTypeIsOnChange 75 // when adding or removing a new entry here :) 76 // Have a nice day. 77 78 //! The number of sensor types including unknown. This entry must be last. 79 SENSOR_TYPE_COUNT, 80 }; 81 82 /** 83 * This SensorSampleType is designed to help classify SensorType's data type in 84 * event handling. 85 */ 86 enum class SensorSampleType { 87 Byte, 88 Float, 89 Occurrence, 90 ThreeAxis, 91 Unknown, 92 }; 93 94 /** 95 * Returns a string representation of the given sensor type. 96 * 97 * @param sensorType The sensor type to obtain a string for. 98 * @return A string representation of the sensor type. 99 */ 100 const char *getSensorTypeName(SensorType sensorType); 101 102 /** 103 * Returns a sensor sample event type for a given sensor type. The sensor type 104 * must not be SensorType::Unknown. This is a fatal error. 105 * 106 * @param sensorType The type of the sensor. 107 * @return The event type for a sensor sample of the given sensor type. 108 */ 109 uint16_t getSampleEventTypeForSensorType(SensorType sensorType); 110 111 /** 112 * Returns a sensor type for a given sensor sample event type. 113 * 114 * @param eventType The event type for a sensor sample. 115 * @return The type of the sensor. 116 */ 117 SensorType getSensorTypeForSampleEventType(uint16_t eventType); 118 119 /** 120 * @return An index into an array for a given sensor type. This is useful to map 121 * sensor type to array index quickly. The range returned corresponds to any 122 * SensorType except for Unknown starting from zero to the maximum value sensor 123 * with no gaps. 124 */ 125 constexpr size_t getSensorTypeArrayIndex(SensorType sensorType); 126 127 /** 128 * @return The number of valid sensor types in the SensorType enum. 129 */ 130 constexpr size_t getSensorTypeCount(); 131 132 /** 133 * Translates an unsigned integer as provided by a CHRE-compliant nanoapp to a 134 * SensorType. If the integer sensor type does not match one of the internal 135 * sensor types, SensorType::Unknown is returned. 136 * 137 * @param sensorType The integer sensor type. 138 * @return The strongly-typed sensor if a match is found or SensorType::Unknown. 139 */ 140 SensorType getSensorTypeFromUnsignedInt(uint8_t sensorType); 141 142 /** 143 * Translates a SensorType to an unsigned integer as provided by CHRE API. If 144 * the sensor type is SensorType::Unknown, 0 is returned. 145 * 146 * @param sensorType The strongly-typed sensor. 147 * @return The integer sensor type if sensorType is not SensorType::Unknown. 148 */ 149 uint8_t getUnsignedIntFromSensorType(SensorType sensorType); 150 151 /** 152 * Provides a stable handle for a CHRE sensor type. This handle is exposed to 153 * CHRE nanoapps as a way to refer to sensors that they are subscribing to. This 154 * API is not expected to be called with SensorType::Unknown as nanoapps are not 155 * able to subscribe to the Unknown sensor type. 156 * 157 * @param sensorType The type of the sensor to obtain a handle for. 158 * @return The handle for a given sensor. 159 */ 160 constexpr uint32_t getSensorHandleFromSensorType(SensorType sensorType); 161 162 /** 163 * Maps a sensor handle to a SensorType or returns SensorType::Unknown if the 164 * provided handle is invalid. 165 * 166 * @param handle The sensor handle for a sensor. 167 * @return The sensor type for a given handle. 168 */ 169 constexpr SensorType getSensorTypeFromSensorHandle(uint32_t handle); 170 171 /** 172 * Maps a sensorType to its SensorSampleType. 173 * 174 * @param sensorType The type of the sensor to obtain its SensorSampleType for. 175 * @return The SensorSampleType of the sensorType. 176 */ 177 SensorSampleType getSensorSampleTypeFromSensorType(SensorType sensorType); 178 179 /** 180 * This SensorMode is designed to wrap constants provided by the CHRE API to 181 * imrpove type-safety. The details of these modes are left to the CHRE API mode 182 * definitions contained in the chreSensorConfigureMode enum. 183 */ 184 enum class SensorMode { 185 Off, 186 ActiveContinuous, 187 ActiveOneShot, 188 PassiveContinuous, 189 PassiveOneShot, 190 }; 191 192 /** 193 * @return true if the sensor mode is considered to be active and would cause a 194 * sensor to be powered on in order to get sensor data. 195 */ 196 constexpr bool sensorModeIsActive(SensorMode sensorMode); 197 198 /** 199 * @return true if the sensor mode is considered to be passive and would not 200 * cause a sensor to be powered on in order to get sensor data. 201 */ 202 constexpr bool sensorModeIsPassive(SensorMode sensorMode); 203 204 /** 205 * @return true if the sensor mode is considered to be contunuous. 206 */ 207 constexpr bool sensorModeIsContinuous(SensorMode sensorMode); 208 209 /** 210 * @return true if the sensor mode is considered to be one-shot. 211 */ 212 constexpr bool sensorModeIsOneShot(SensorMode sensorMode); 213 214 /** 215 * Translates a CHRE API enum sensor mode to a SensorMode. This function also 216 * performs input validation and will default to SensorMode::Off if the provided 217 * value is not a valid enum value. 218 * 219 * @param enumSensorMode A potentially unsafe CHRE API enum sensor mode. 220 * @return Returns a SensorMode given a CHRE API enum sensor mode. 221 */ 222 SensorMode getSensorModeFromEnum(enum chreSensorConfigureMode enumSensorMode); 223 224 /** 225 * Indicates whether the sensor type is a one-shot sensor. 226 * 227 * @param sensorType The sensor type of the sensor. 228 * @return true if the sensor is a one-shot sensor. 229 */ 230 bool sensorTypeIsOneShot(SensorType sensorType); 231 232 /** 233 * Indicates whether the sensor type is an on-change sensor. 234 * 235 * @param sensorType The sensor type of the sensor. 236 * @return true if the sensor is an on-change sensor. 237 */ 238 bool sensorTypeIsOnChange(SensorType sensorType); 239 240 /** 241 * Models a request for sensor data. This class implements the API set forth by 242 * the RequestMultiplexer container. 243 */ 244 class SensorRequest { 245 public: 246 /** 247 * Default constructs a sensor request to the minimal possible configuration. 248 * The sensor is disabled and the interval and latency are both set to zero. 249 */ 250 SensorRequest(); 251 252 /** 253 * Constructs a sensor request given a mode, interval and latency. Non-default 254 * interval or latency higher than kMaxIntervalLatencyNs will be capped. 255 * 256 * @param mode The mode of the sensor request. 257 * @param interval The interval between samples. 258 * @param latency The maximum amount of time to batch samples before 259 * delivering to a client. 260 */ 261 SensorRequest(SensorMode mode, Nanoseconds interval, Nanoseconds latency); 262 263 /** 264 * Constructs a sensor request given an owning nanoapp, mode, interval and 265 * latency. Non-default interval or latency higher than kMaxIntervalLatencyNs 266 * will be capped. 267 * 268 * @param nanoapp The nanoapp that made this request. 269 * @param mode The mode of the sensor request. 270 * @param interval The interval between samples. 271 * @param latency The maximum amount of time to batch samples before 272 * delivering to a client. 273 */ 274 SensorRequest(Nanoapp *nanoapp, SensorMode mode, Nanoseconds interval, 275 Nanoseconds latency); 276 277 /** 278 * Performs an equivalency comparison of two sensor requests. This determines 279 * if the effective request for sensor data is the same as another. 280 * 281 * @param request The request to compare against. 282 * @return Returns true if this request is equivalent to another. 283 */ 284 bool isEquivalentTo(const SensorRequest& request) const; 285 286 /** 287 * Assigns the current request to the maximal superset of the mode, rate 288 * and latency of the other request. 289 * 290 * @param request The other request to compare the attributes of. 291 * @return true if any of the attributes of this request changed. 292 */ 293 bool mergeWith(const SensorRequest& request); 294 295 /** 296 * @return Returns the interval of samples for this request. 297 */ getInterval()298 Nanoseconds getInterval() const { 299 return mInterval; 300 } 301 302 /** 303 * @return Returns the maximum amount of time samples can be batched prior to 304 * dispatching to the client. 305 */ getLatency()306 Nanoseconds getLatency() const { 307 return mLatency; 308 } 309 310 /** 311 * @return The mode of this request. 312 */ getMode()313 SensorMode getMode() const { 314 return mMode; 315 } 316 317 /** 318 * @return The nanoapp that owns this sensor request. 319 */ getNanoapp()320 Nanoapp *getNanoapp() const { 321 return mNanoapp; 322 } 323 324 private: 325 //! The nanoapp that made this request. This will be nullptr when returned by 326 //! the generateIntersectionOf method. 327 // TODO: need to (1) change this to instanceId to avoid potentially 328 // referencing a Nanoapp after it is unloaded, and (2) add a method to remove 329 // all open sensor requests associated with a nanoapp after it is unloaded 330 Nanoapp *mNanoapp = nullptr; 331 332 //! The interval between samples for this request. 333 Nanoseconds mInterval; 334 335 //! The maximum amount of time samples can be batched prior to dispatching to 336 //! the client 337 Nanoseconds mLatency; 338 339 //! The mode of this request. 340 SensorMode mMode; 341 }; 342 343 } // namespace chre 344 345 #include "chre/core/sensor_request_impl.h" 346 347 #endif // CHRE_CORE_SENSOR_REQUEST_H_ 348