1 /* 2 * Copyright (C) 2019 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_MANAGER_H_ 18 #define CHRE_PLATFORM_PLATFORM_SENSOR_MANAGER_H_ 19 20 #include "chre/core/sensor.h" 21 #include "chre/target_platform/platform_sensor_manager_base.h" 22 #include "chre/util/dynamic_vector.h" 23 24 namespace chre { 25 26 /** 27 * Handles communicating with all CHRE-supported sensors in the system at the 28 * behest of the core framework while also managing the receipt of various 29 * sensor events that CHRE is able to process. 30 */ 31 class PlatformSensorManager : public PlatformSensorManagerBase { 32 public: 33 ~PlatformSensorManager(); 34 35 /** 36 * Initializes the manager implementation. This is called at a later stage of 37 * initialization than the constructor, so implementations are encouraged to 38 * put any blocking initialization here. 39 */ 40 void init(); 41 42 /** 43 * Constructs Sensor objects for every CHRE-supported sensor in the system, 44 * and returns them in a DynamicVector. This method is only invoked once 45 * during initialization of the CHRE framework. 46 * 47 * @return A DynamicVector to populate with the list of sensors the framework 48 * can send requests to. 49 * 50 * @note For the returned list of sensors, the following requirements MUST be 51 * respected: 52 * - A given sensor's target group mask MUST NOT overlap with another 53 * sensor's target group mask if both have the same index and type. 54 * - One-shot sensors MUST only appear once in this list. i.e. they 55 * cannot support multiple indices / target group ID masks. 56 * - There cannot be multiple sensors with the same index of the same 57 * type. 58 */ 59 DynamicVector<Sensor> getSensors(); 60 61 /** 62 * Sends the sensor request to the provided sensor. The request issued through 63 * this method must be a valid request based on the properties of the given 64 * sensor. 65 * 66 * If setting this new request fails due to a transient failure (example: 67 * inability to communicate with the sensor) false will be returned. 68 * 69 * If a request's latency is lower than its interval, the request is assumed 70 * to have a latency of 0 and samples should be delivered to CHRE as soon 71 * as they become available. 72 * TODO(b/142958445): Make the above modification to the request before it 73 * reaches the platform code. 74 * 75 * If the sensor was previously configured, but the new request fails to be 76 * processed, the previous configuration must remain in place. 77 * 78 * @param sensor One of the sensors provided by getSensors(). 79 * @param request The new request that contains the details about how the 80 * sensor should be configured. 81 * @return true if the sensor was successfully configured with the supplied 82 * request. 83 */ 84 bool configureSensor(Sensor &sensor, const SensorRequest &request); 85 86 /** 87 * Configures the reception of bias events for a specified sensor. 88 * 89 * It is recommended that the platform deliver the bias data at the same 90 * interval that sensor data is delivered, in order to optimize for power, 91 * with the bias data being delivered first so that nanoapps are easily able 92 * to translate sensor data if necessary. If bias events are not delivered at 93 * the same interval as the sensor data, they should be delivered as close to 94 * the corresponding sensor data as possible to reduce the amount of time 95 * nanoapps need to remember multiple bias updates. Additonally, an enable 96 * request must only be issued if a sensor has already been enabled through 97 * configureSensor(). 98 * 99 * @param sensor One of the sensors provided by getSensors(). 100 * @param enable whether to enable or disable bias event delivery 101 * @param latencyNs The maximum latency, in nanoseconds, allowed before the 102 * PAL begins delivery of events. This will control how many events can be 103 * queued before requiring a delivery event. This value will match 104 * the latency requested for sensor data through configureSensor() 105 * @return true if the sensor was successfully configured with the supplied 106 * parameters. 107 */ 108 bool configureBiasEvents(const Sensor &sensor, bool enable, 109 uint64_t latencyNs); 110 111 /** 112 * Synchronously retrieves the current bias for a sensor that supports 113 * data in the chreSensorThreeAxisData format. If the current bias hasn't been 114 * received for the given sensor, this method will store data with a bias of 0 115 * and the accuracy field in chreSensorDataHeader set to 116 * CHRE_SENSOR_ACCURACY_UNKNOWN per the CHRE API requirements. 117 * 118 * @param sensor One of the sensors provided by getSensors(). 119 * @param bias A non-null pointer to store the current bias data. 120 * @return false if sensor does not report bias data in the 121 * chreSensorThreeAxisData format. 122 */ 123 bool getThreeAxisBias(const Sensor &sensor, 124 struct chreSensorThreeAxisData *bias) const; 125 126 /** 127 * Makes a flush request for the given sensor. When a flush request made by 128 * this method is completed (i.e. all pending samples are posted to the CHRE 129 * event queue), PlatformSensorManager must invoke 130 * SensorRequestManager::handleFlushCompleteEvent(). 131 * 132 * @param sensor One of the sensors provided by getSensors(). 133 * @param flushRequestId A pointer where a UID will be stored identify this 134 * flush request. Must be set to UINT32_MAX if request IDs are not 135 * supported by this platform. This value must be passed into 136 * flushCompleteCallback() when the flush request is completed. 137 * @return true if the request was accepted. 138 */ 139 bool flush(const Sensor &sensor, uint32_t *flushRequestId); 140 141 /** 142 * @return the target group ID for a given nanoapp. This mapping is not 143 * allowed to change based on state that can change after a nanoapp is 144 * loaded and must remain constant for the lifetime of the nanoapp. 145 */ 146 uint16_t getTargetGroupId(const Nanoapp &nanoapp) const; 147 148 //! Methods that allow the platform to free the data given via the below 149 //! event handlers 150 void releaseSamplingStatusUpdate(struct chreSensorSamplingStatus *status); 151 void releaseSensorDataEvent(void *data); 152 void releaseBiasEvent(void *biasData); 153 }; 154 155 } // namespace chre 156 157 /* The platform can optionally provide an inlined implementation */ 158 #if __has_include("chre/target_platform/platform_sensor_manager_impl.h") 159 #include "chre/target_platform/platform_sensor_manager_impl.h" 160 #endif // __has_include("chre/target_platform/platform_sensor_manager_impl.h") 161 162 #endif // CHRE_PLATFORM_PLATFORM_SENSOR_MANAGER_H_ 163