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_PLATFORM_PLATFORM_SENSOR_H_ 18 #define CHRE_PLATFORM_PLATFORM_SENSOR_H_ 19 20 #include "chre/core/sensor_request.h" 21 #include "chre/target_platform/platform_sensor_base.h" 22 #include "chre/util/dynamic_vector.h" 23 #include "chre/util/non_copyable.h" 24 25 namespace chre { 26 27 class Sensor; 28 29 /** 30 * Defines the common interface to sensor functionality that is implemented in a 31 * platform-specific way, and must be supported on every platform. 32 * 33 * @see Sensor 34 */ 35 class PlatformSensor : public PlatformSensorBase, 36 public NonCopyable { 37 public: 38 /** 39 * Initializes the sensors subsystem. This must be called as part of the 40 * initialization of the runtime. 41 */ 42 static void init(); 43 44 /** 45 * Deinitializes the sensors subsystem, including releasing any outstanding 46 * sensor requests. This must be called as part of the deinitialization of the 47 * runtime. 48 */ 49 static void deinit(); 50 51 /** 52 * Constructs Sensor objects for every CHRE-supported sensor in the system, 53 * and puts them in the supplied DynamicVector, which should be empty when 54 * passed in. If this method returns false the vector may be partially filled. 55 * 56 * NOTE: Some platform implementations depend on this list only being 57 * constructed during initialization so it must remain fixed afterwards. 58 * 59 * @param sensors A non-null pointer to a DynamicVector to populate with the 60 * list of sensors. 61 * @return true if the query was successful. 62 */ 63 static bool getSensors(DynamicVector<Sensor> *sensors); 64 65 /** 66 * Obtains the SensorType of this platform sensor. The implementation of this 67 * method is supplied by the platform as the mechanism for determining the 68 * type may vary across platforms. 69 * 70 * @return The type of this sensor. 71 */ 72 SensorType getSensorType() const; 73 74 /** 75 * @return This sensor's minimum supported sampling interval, in nanoseconds. 76 */ 77 uint64_t getMinInterval() const; 78 79 /** 80 * Returns a descriptive name (e.g. type and model) for this sensor. 81 * 82 * @return A pointer to a string with storage duration at least as long as the 83 * lifetime of this object. 84 */ 85 const char *getSensorName() const; 86 87 /** 88 * @return Pointer to this sensor's last data event. It returns a nullptr if 89 * the the platform doesn't provide it. 90 */ 91 ChreSensorData *getLastEvent() const; 92 93 /** 94 * Gets the current status of this sensor in the CHRE API format. 95 * 96 * @param status A non-null pointer to chreSensorSamplingStatus to populate 97 * @return true if the sampling status has been successfully obtained. 98 */ 99 bool getSamplingStatus(struct chreSensorSamplingStatus *status) const; 100 101 /** 102 * Synchronously retrieves the current bias for a sensor that supports 103 * data in the chreSensorThreeAxisData format. 104 * 105 * @param bias A non-null pointer to store the current bias data. 106 * 107 * @return false if sensor does not report bias data in the 108 * chreSensorThreeAxisData format. 109 */ 110 bool getThreeAxisBias(struct chreSensorThreeAxisData *bias) const; 111 112 /** 113 * Makes a sensor flush request for a nanoapp asynchronously. When a flush 114 * request made by this method is completed (i.e. all pending samples are 115 * posted to the CHRE event queue), PlatformSensor should invoke 116 * SensorRequestManager::handleFlushCompleteEvent(). 117 * 118 * @return true if the request was accepted. 119 */ 120 bool flushAsync(); 121 122 protected: 123 /** 124 * Default constructor that puts this instance in an unspecified state. 125 * Additional platform-specific initialization will likely be necessary to put 126 * this object in a usable state. Do not construct PlatformSensor directly; 127 * instead construct via Sensor. 128 */ 129 PlatformSensor() = default; 130 131 PlatformSensor(PlatformSensor&& other); 132 PlatformSensor& operator=(PlatformSensor&& other); 133 134 /** 135 * Perform any necessary cleanup of resources acquired in PlatformSensorBase. 136 */ 137 ~PlatformSensor(); 138 139 /** 140 * Sends the sensor request to the platform sensor. The implementation 141 * of this method is supplied by the platform. If the request is 142 * invalid/unsupported by this sensor, for example because it requests an 143 * interval that is too short, then this function must return false. If 144 * setting this new request fails due to a transient failure (example: 145 * inability to communicate with the sensor) false must also be returned. 146 * 147 * If the request's latency is lower than its interval, the platform sensor 148 * must deliver the first sample to clients as soon as it becomes available. 149 * 150 * @param request The new request to set this sensor to. 151 * @return true if the platform sensor was successfully configured with the 152 * supplied request. 153 */ 154 bool applyRequest(const SensorRequest& request); 155 }; 156 157 } // namespace chre 158 159 #endif // CHRE_PLATFORM_PLATFORM_SENSOR_H_ 160