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