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