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 #pragma once 18 19 #include "ScopedWakelock.h" 20 21 #include <android/hardware/sensors/1.0/types.h> 22 #include <android/hardware/sensors/2.0/ISensors.h> 23 24 #include <vector> 25 26 // Indicates the current version of the multiHAL interface formatted as (HAL major version) << 24 | 27 // (HAL minor version) << 16 | (multiHAL version) 28 #define SUB_HAL_2_0_VERSION 0x02000000 29 30 namespace android { 31 namespace hardware { 32 namespace sensors { 33 namespace V2_0 { 34 namespace implementation { 35 36 using ::android::hardware::sensors::V1_0::Event; 37 using ::android::hardware::sensors::V1_0::Result; 38 using ::android::hardware::sensors::V1_0::SensorInfo; 39 40 /** 41 * Interface that contains several callbacks into the HalProxy class to communicate dynamic sensor 42 * changes and sensor events to the framework and acquire wake locks. The HalProxy will ensure 43 * callbacks occurring at the same time from multiple sub-HALs are synchronized in a safe, efficient 44 * manner. 45 */ 46 class IHalProxyCallback : public ISensorsCallback { 47 public: 48 /** 49 * Thread-safe callback used to post events to the HalProxy. Sub-HALs should invoke this 50 * whenever new sensor events need to be delivered to the sensors framework. Once invoked, the 51 * HalProxy will attempt to send events to the sensors framework using a blocking write with a 52 * 5 second timeout. This write may be done asynchronously if the queue used to communicate 53 * with the framework is full to avoid blocking sub-HALs for the length of the timeout. If the 54 * write fails, the events will be dropped and any wake locks held will be released. 55 * 56 * The provided ScopedWakelock must be locked if the events are from wakeup sensors. If it's 57 * not locked accordingly, the HalProxy will crash as this indicates the sub-HAL isn't compliant 58 * with the sensors HAL 2.0 specification. Additionally, since ScopedWakelock isn't copyable, 59 * the HalProxy will take ownership of the wake lock given when this method is invoked. Once the 60 * method returns, the HalProxy will handle holding the wake lock, if necessary, until the 61 * framework has successfully processed any wakeup events. 62 * 63 * No return type is used for this callback to avoid sub-HALs trying to resend events when 64 * writes fail. Writes should only fail when the framework is under inordinate stress which will 65 * likely result in a framework restart so retrying will likely only result in overloading the 66 * HalProxy. Sub-HALs should always assume that the write was a success and perform any 67 * necessary cleanup. Additionally, the HalProxy will ensure it logs any errors (through ADB and 68 * bug reports) it encounters during delivery to ensure it's obvious that a failure occurred. 69 * 70 * @param events the events that should be sent to the sensors framework 71 * @param wakelock ScopedWakelock that should be locked to send events from wake sensors and 72 * unlocked otherwise. 73 */ 74 virtual void postEvents(const std::vector<Event>& events, ScopedWakelock wakelock) = 0; 75 76 /** 77 * Initializes a ScopedWakelock on the stack that, when locked, will increment the reference 78 * count for the sub-HAL's wake lock managed inside the HalProxy. See the ScopedWakelock class 79 * definition for how it should be used. 80 * 81 * @param lock whether the ScopedWakelock should be locked before it's returned. 82 * @return the created ScopedWakelock 83 */ 84 virtual ScopedWakelock createScopedWakelock(bool lock) = 0; 85 }; 86 87 /** 88 * ISensorsSubHal is an interface that sub-HALs must implement in order to be compliant with 89 * multihal 2.0 and in order for the HalProxy to successfully load and communicate with the sub-HAL. 90 * 91 * Any vendor wishing to implement this interface and support multihal 2.0 will need to create a 92 * dynamic library that exposes sensorsHalGetSubHal (defined below). This library will be loaded by 93 * the HalProxy when the sensors HAL is initialized and then the HalProxy will retrieve the vendor's 94 * implementation of sensorsHalGetSubHal. 95 * 96 * With the exception of the initialize method, ISensorsSubHal will implement the ISensors.hal spec. 97 * Any sensor handles given to the HalProxy, either through getSensorsList() or the 98 * onDynamicSensors(Dis)Connected callbacks, will be translated to avoid clashing with other sub-HAL 99 * handles. To achieve this, the HalProxy will use the upper byte to store the sub-HAL index and 100 * sub-HALs can continue to use the lower 3 bytes of the handle. 101 */ 102 class ISensorsSubHal : public ISensors { 103 public: 104 // The ISensors version of initialize isn't used for multihal. Instead, sub-HALs must implement 105 // the version below to allow communciation logic to centralized in the HalProxy initialize(const::android::hardware::MQDescriptorSync<Event> &,const::android::hardware::MQDescriptorSync<uint32_t> &,const sp<ISensorsCallback> &)106 Return<Result> initialize( 107 const ::android::hardware::MQDescriptorSync<Event>& /* eventQueueDescriptor */, 108 const ::android::hardware::MQDescriptorSync<uint32_t>& /* wakeLockDescriptor */, 109 const sp<ISensorsCallback>& /* sensorsCallback */) final { 110 return Result::INVALID_OPERATION; 111 } 112 113 /** 114 * Method defined in ::android::hidl::base::V1_0::IBase. 115 * 116 * This method should write debug information to hidl_handle that is useful for debugging 117 * issues. Suggestions include: 118 * - Sensor info including handle values and any other state available in the SensorInfo class 119 * - List of active sensors and their current sampling period and reporting latency 120 * - Information about pending flush requests 121 * - Current operating mode 122 * - Currently registered direct channel info 123 * - A history of any of the above 124 */ 125 virtual Return<void> debug(const hidl_handle& fd, const hidl_vec<hidl_string>& args) = 0; 126 127 /** 128 * @return A human-readable name for use in wake locks and logging. 129 */ 130 virtual const std::string getName() = 0; 131 132 /** 133 * This is the first method invoked on the sub-HAL after it's allocated through 134 * sensorsHalGetSubHal() by the HalProxy. Sub-HALs should use this to initialize any state and 135 * retain the callback given in order to communicate with the HalProxy. Method will be called 136 * anytime the sensors framework restarts. Therefore, this method will be responsible for 137 * reseting the state of the subhal and cleaning up and reallocating any previously allocated 138 * data. Initialize should ensure that the subhal has reset its operation mode to NORMAL state 139 * as well. 140 * 141 * @param halProxyCallback callback used to inform the HalProxy when a dynamic sensor's state 142 * changes, new sensor events should be sent to the framework, and when a new ScopedWakelock 143 * should be created. 144 * @return result OK on success 145 */ 146 virtual Return<Result> initialize(const sp<IHalProxyCallback>& halProxyCallback) = 0; 147 }; 148 149 } // namespace implementation 150 } // namespace V2_0 151 } // namespace sensors 152 } // namespace hardware 153 } // namespace android 154 155 using ::android::hardware::sensors::V2_0::implementation::ISensorsSubHal; 156 157 /** 158 * Function that must be exported so the HalProxy class can invoke it on the sub-HAL dynamic 159 * library. This function will only be invoked once at initialization time. 160 * 161 * NOTE: The supported sensors HAL version must match SUB_HAL_2_0_VERSION exactly or the HalProxy 162 * will fail to initialize. 163 * 164 * @param uint32_t when this function returns, this parameter must contain the HAL version that 165 * this sub-HAL supports. To support this version of multi-HAL, this must be set to 166 * SUB_HAL_2_0_VERSION. 167 * @return A statically allocated, valid ISensorsSubHal implementation. 168 */ 169 __attribute__((visibility("default"))) extern "C" ISensorsSubHal* sensorsHalGetSubHal( 170 uint32_t* version); 171