1 /* 2 * Copyright (C) 2021 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 android_hardware_automotive_vehicle_aidl_impl_hardware_include_IVehicleHardware_H_ 18 #define android_hardware_automotive_vehicle_aidl_impl_hardware_include_IVehicleHardware_H_ 19 20 #include <VehicleHalTypes.h> 21 22 #include <memory> 23 #include <vector> 24 25 namespace android { 26 namespace hardware { 27 namespace automotive { 28 namespace vehicle { 29 30 // A structure used to return dumped information. 31 struct DumpResult { 32 // If callerShouldDumpState is true, caller would print the information in buffer and 33 // continue to dump its state, otherwise would just dump the buffer and skip its own 34 // dumping logic. 35 bool callerShouldDumpState; 36 // The dumped information for the caller to print. 37 std::string buffer; 38 // To pass if DefaultVehicleHal should refresh the property configs 39 bool refreshPropertyConfigs = false; 40 }; 41 42 // A structure to represent a set value error event reported from vehicle. 43 struct SetValueErrorEvent { 44 aidl::android::hardware::automotive::vehicle::StatusCode errorCode; 45 int32_t propId; 46 int32_t areaId; 47 }; 48 49 // An abstract interface to access vehicle hardware. 50 // For virtualized VHAL, GrpcVehicleHardware would communicate with a VehicleHardware 51 // implementation in another VM through GRPC. For non-virtualzied VHAL, VHAL directly communicates 52 // with a VehicleHardware through this interface. 53 class IVehicleHardware { 54 public: 55 using SetValuesCallback = std::function<void( 56 std::vector<aidl::android::hardware::automotive::vehicle::SetValueResult>)>; 57 using GetValuesCallback = std::function<void( 58 std::vector<aidl::android::hardware::automotive::vehicle::GetValueResult>)>; 59 using PropertyChangeCallback = std::function<void( 60 std::vector<aidl::android::hardware::automotive::vehicle::VehiclePropValue>)>; 61 using PropertySetErrorCallback = std::function<void(std::vector<SetValueErrorEvent>)>; 62 63 virtual ~IVehicleHardware() = default; 64 65 // Get all the property configs. 66 virtual std::vector<aidl::android::hardware::automotive::vehicle::VehiclePropConfig> 67 getAllPropertyConfigs() const = 0; 68 69 // Set property values asynchronously. Server could return before the property set requests 70 // are sent to vehicle bus or before property set confirmation is received. The callback is 71 // safe to be called after the function returns and is safe to be called in a different thread. 72 virtual aidl::android::hardware::automotive::vehicle::StatusCode setValues( 73 std::shared_ptr<const SetValuesCallback> callback, 74 const std::vector<aidl::android::hardware::automotive::vehicle::SetValueRequest>& 75 requests) = 0; 76 77 // Get property values asynchronously. Server could return before the property values are ready. 78 // The callback is safe to be called after the function returns and is safe to be called in a 79 // different thread. 80 virtual aidl::android::hardware::automotive::vehicle::StatusCode getValues( 81 std::shared_ptr<const GetValuesCallback> callback, 82 const std::vector<aidl::android::hardware::automotive::vehicle::GetValueRequest>& 83 requests) const = 0; 84 85 // Dump debug information in the server. 86 virtual DumpResult dump(const std::vector<std::string>& options) = 0; 87 88 // Check whether the system is healthy, return {@code StatusCode::OK} for healthy. 89 virtual aidl::android::hardware::automotive::vehicle::StatusCode checkHealth() = 0; 90 91 // Register a callback that would be called when there is a property change event from vehicle. 92 // This function must only be called once during initialization. 93 virtual void registerOnPropertyChangeEvent( 94 std::unique_ptr<const PropertyChangeCallback> callback) = 0; 95 96 // Register a callback that would be called when there is a property set error event from 97 // vehicle. Must only be called once during initialization. 98 virtual void registerOnPropertySetErrorEvent( 99 std::unique_ptr<const PropertySetErrorCallback> callback) = 0; 100 101 // Gets the batching window used by DefaultVehicleHal for property change events. 102 // 103 // In DefaultVehicleHal, all the property change events generated within the batching window 104 // will be delivered through one callback to the VHAL client. This affects the maximum supported 105 // subscription rate. For example, if this returns 10ms, then only one callback for property 106 // change events will be called per 10ms, meaining that the max subscription rate for all 107 // continuous properties would be 100hz. 108 // 109 // A higher batching window means less callbacks to the VHAL client, causing a better 110 // performance. However, it also means a longer average latency for every property change 111 // events. 112 // 113 // 0 means no batching should be enabled in DefaultVehicleHal. In this case, batching can 114 // be optionally implemented in IVehicleHardware layer. getPropertyOnChangeEventBatchingWindow()115 virtual std::chrono::nanoseconds getPropertyOnChangeEventBatchingWindow() { 116 // By default batching is disabled. 117 return std::chrono::nanoseconds(0); 118 } 119 120 // A [propId, areaId] is newly subscribed or the subscribe options are changed. 121 // 122 // The subscribe options contain sample rate in Hz or enable/disable variable update rate. 123 // 124 // For continuous properties: 125 // 126 // The sample rate is never 0 and indicates the desired polling rate for this property. The 127 // sample rate is guaranteed to be within supported {@code minSampleRate} and 128 // {@code maxSampleRate} as specified in {@code VehiclePropConfig}. 129 // 130 // If the specified sample rate is not supported, e.g. vehicle bus only supports 5hz and 10hz 131 // polling rate but the sample rate is 8hz, impl must choose the higher polling rate (10hz). 132 // 133 // Whether variable update rate is enabled is specified by {@code enableVariableUpdateRate} in 134 // {@code SubscribeOptions}. If variable update rate is not supported for the 135 // [propId, areaId], impl must ignore this option and always treat it as disabled. 136 // 137 // If variable update rate is disabled/not supported, impl must report all the property events 138 // for this [propId, areaId] through {@code propertyChangeCallback} according to the sample 139 // rate. E.g. a sample rate of 10hz must generate at least 10 property change events per second. 140 // 141 // If variable update rate is enabled AND supported, impl must only report property events 142 // when the [propId, areaId]'s value or status changes (a.k.a same as on-change property). 143 // The sample rate still guides the polling rate, but duplicate property events must be dropped 144 // and not reported via {@code propertyChangeCallback}. 145 // 146 // Async property set error events are not affected by variable update rate and must always 147 // be reported. 148 // 149 // If the impl is always polling at {@code maxSampleRate} for all continuous [propId, areaId]s, 150 // and do not support variable update rate for any [propId, areaId], then this function can be a 151 // no-op. 152 // 153 // For on-change properties: 154 // 155 // The sample rate is always 0 and must be ignored. If the impl is always subscribing to all 156 // on-change properties, then this function can be no-op. 157 // 158 // For all properties: 159 // 160 // It is recommended to only deliver the subscribed property events to DefaultVehicleHal to 161 // improve performance. However, even if unsubscribed property events are delivered, they 162 // will be filtered out by DefaultVehicleHal. 163 // 164 // A subscription from VHAL client might not necessarily trigger this function. 165 // DefaultVehicleHal will aggregate all the subscriptions from all the clients and notify 166 // IVehicleHardware if new subscriptions are required or subscribe options are updated. 167 // 168 // For example: 169 // 1. VHAL initially have no subscriber for speed. 170 // 2. A new subscriber is subscribing speed for 10 times/s, 'subscribe' is called 171 // with sampleRate as 10. The impl is now polling vehicle speed from bus 10 times/s. 172 // 3. A new subscriber is subscribing speed for 5 times/s, because it is less than 10 173 // times/sec, 'subscribe' is not called. 174 // 4. The initial subscriber is removed, 'subscribe' is called with sampleRate as 175 // 5, because now it only needs to report event 5times/sec. The impl can now poll vehicle 176 // speed 5 times/s. If the impl is still polling at 10 times/s, that is okay as long as 177 // the polling rate is larger than 5times/s. DefaultVehicleHal would ignore the additional 178 // events. 179 // 5. The second subscriber is removed, 'unsubscribe' is called. 180 // The impl can optionally disable the polling for vehicle speed. 181 // subscribe(aidl::android::hardware::automotive::vehicle::SubscribeOptions options)182 virtual aidl::android::hardware::automotive::vehicle::StatusCode subscribe( 183 [[maybe_unused]] aidl::android::hardware::automotive::vehicle::SubscribeOptions 184 options) { 185 return aidl::android::hardware::automotive::vehicle::StatusCode::OK; 186 } 187 188 // A [propId, areaId] is unsubscribed. This applies for both continuous or on-change property. unsubscribe(int32_t propId,int32_t areaId)189 virtual aidl::android::hardware::automotive::vehicle::StatusCode unsubscribe( 190 [[maybe_unused]] int32_t propId, [[maybe_unused]] int32_t areaId) { 191 return aidl::android::hardware::automotive::vehicle::StatusCode::OK; 192 } 193 194 // This function is deprecated, subscribe/unsubscribe should be used instead. 195 // 196 // Update the sampling rate for the specified property and the specified areaId (0 for global 197 // property) if server supports it. The property must be a continuous property. 198 // {@code sampleRate} means that for this specific property, the server must generate at least 199 // this many OnPropertyChange events per seconds. 200 // A sampleRate of 0 means the property is no longer subscribed and server does not need to 201 // generate any onPropertyEvent for this property. 202 // This would be called if sample rate is updated for a subscriber, a new subscriber is added 203 // or an existing subscriber is removed. For example: 204 // 1. We have no subscriber for speed. 205 // 2. A new subscriber is subscribing speed for 10 times/s, updateSampleRate would be called 206 // with sampleRate as 10. The impl is now polling vehicle speed from bus 10 times/s. 207 // 3. A new subscriber is subscribing speed for 5 times/s, because it is less than 10 208 // times/sec, updateSampleRate would not be called. 209 // 4. The initial subscriber is removed, updateSampleRate would be called with sampleRate as 210 // 5, because now it only needs to report event 5times/sec. The impl can now poll vehicle 211 // speed 5 times/s. If the impl is still polling at 10 times/s, that is okay as long as 212 // the polling rate is larger than 5times/s. DefaultVehicleHal would ignore the additional 213 // events. 214 // 5. The second subscriber is removed, updateSampleRate would be called with sampleRate as 0. 215 // The impl can optionally disable the polling for vehicle speed. 216 // 217 // If the impl is always polling at {@code maxSampleRate} as specified in config, then this 218 // function can be a no-op. updateSampleRate(int32_t propId,int32_t areaId,float sampleRate)219 virtual aidl::android::hardware::automotive::vehicle::StatusCode updateSampleRate( 220 [[maybe_unused]] int32_t propId, [[maybe_unused]] int32_t areaId, 221 [[maybe_unused]] float sampleRate) { 222 return aidl::android::hardware::automotive::vehicle::StatusCode::OK; 223 } 224 }; 225 226 } // namespace vehicle 227 } // namespace automotive 228 } // namespace hardware 229 } // namespace android 230 231 #endif // android_hardware_automotive_vehicle_aidl_impl_hardware_include_IVehicleHardware_H_ 232