1 /* 2 * Copyright 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 BTIF_BQR_H_ 18 #define BTIF_BQR_H_ 19 20 #include "btm_api_types.h" 21 #include "common/leaky_bonded_queue.h" 22 23 namespace bluetooth { 24 namespace bqr { 25 26 // Bluetooth Quality Report (BQR) 27 // 28 // It is a feature to start the mechanism in the Bluetooth controller to report 29 // Bluetooth Quality event to the host and there are four options could be 30 // enabled: 31 // [Quality Monitoring Mode] 32 // The controller shall periodically send Bluetooth Quality Report sub-event 33 // to the host. 34 // 35 // [Approaching LSTO] 36 // Once no packets are received from the connected Bluetooth device for a 37 // duration longer than the half of LSTO (Link Supervision TimeOut) value, 38 // the controller shall report Approaching LSTO event to the host. 39 // 40 // [A2DP Audio Choppy] 41 // When the controller detects the factors which will cause audio choppy, 42 // the controller shall report A2DP Audio Choppy event to the host. 43 // 44 // [(e)SCO Voice Choppy] 45 // When the controller detects the factors which will cause voice choppy, 46 // the controller shall report (e)SCO Voice Choppy event to the host. 47 48 // Bit masks for the selected quality event reporting. 49 static constexpr uint32_t kQualityEventMaskAllOff = 0; 50 static constexpr uint32_t kQualityEventMaskMonitorMode = 0x00000001; 51 static constexpr uint32_t kQualityEventMaskApproachLsto = 0x00000002; 52 static constexpr uint32_t kQualityEventMaskA2dpAudioChoppy = 0x00000004; 53 static constexpr uint32_t kQualityEventMaskScoVoiceChoppy = 0x00000008; 54 static constexpr uint32_t kQualityEventMaskAll = 55 kQualityEventMaskMonitorMode | kQualityEventMaskApproachLsto | 56 kQualityEventMaskA2dpAudioChoppy | kQualityEventMaskScoVoiceChoppy; 57 // Define the minimum time interval (in ms) of quality event reporting for the 58 // selected quality event(s). Controller Firmware should not report the next 59 // event within the defined time interval. 60 static constexpr uint16_t kMinReportIntervalNoLimit = 0; 61 static constexpr uint16_t kMinReportIntervalMaxMs = 0xFFFF; 62 // Total length of all BQR parameters except Vendor Specific Parameters. 63 static constexpr uint8_t kBqrParamTotalLen = 48; 64 // Warning criteria of the RSSI value. 65 static constexpr int8_t kCriWarnRssi = -80; 66 // Warning criteria of the unused AFH channel count. 67 static constexpr uint8_t kCriWarnUnusedCh = 55; 68 // The queue size of recording the BQR events. 69 static constexpr uint8_t kBqrEventQueueSize = 25; 70 // The Property of BQR event mask configuration. 71 static constexpr const char* kpPropertyEventMask = 72 "persist.bluetooth.bqr.event_mask"; 73 // The Property of BQR minimum report interval configuration. 74 static constexpr const char* kpPropertyMinReportIntervalMs = 75 "persist.bluetooth.bqr.min_interval_ms"; 76 77 // Action definition 78 // 79 // Action to Add, Delete or Clear the reporting of quality event(s). 80 // Delete will clear specific quality event(s) reporting. Clear will clear all 81 // quality events reporting. 82 enum BqrReportAction : uint8_t { 83 REPORT_ACTION_ADD = 0x00, 84 REPORT_ACTION_DELETE = 0x01, 85 REPORT_ACTION_CLEAR = 0x02 86 }; 87 88 // Report ID definition 89 enum BqrQualityReportId : uint8_t { 90 QUALITY_REPORT_ID_MONITOR_MODE = 0x01, 91 QUALITY_REPORT_ID_APPROACH_LSTO = 0x02, 92 QUALITY_REPORT_ID_A2DP_AUDIO_CHOPPY = 0x03, 93 QUALITY_REPORT_ID_SCO_VOICE_CHOPPY = 0x04 94 }; 95 96 // Packet Type definition 97 enum BqrPacketType : uint8_t { 98 PACKET_TYPE_ID = 0x01, 99 PACKET_TYPE_NULL, 100 PACKET_TYPE_POLL, 101 PACKET_TYPE_FHS, 102 PACKET_TYPE_HV1, 103 PACKET_TYPE_HV2, 104 PACKET_TYPE_HV3, 105 PACKET_TYPE_DV, 106 PACKET_TYPE_EV3, 107 PACKET_TYPE_EV4, 108 PACKET_TYPE_EV5, 109 PACKET_TYPE_2EV3, 110 PACKET_TYPE_2EV5, 111 PACKET_TYPE_3EV3, 112 PACKET_TYPE_3EV5, 113 PACKET_TYPE_DM1, 114 PACKET_TYPE_DH1, 115 PACKET_TYPE_DM3, 116 PACKET_TYPE_DH3, 117 PACKET_TYPE_DM5, 118 PACKET_TYPE_DH5, 119 PACKET_TYPE_AUX1, 120 PACKET_TYPE_2DH1, 121 PACKET_TYPE_2DH3, 122 PACKET_TYPE_2DH5, 123 PACKET_TYPE_3DH1, 124 PACKET_TYPE_3DH3, 125 PACKET_TYPE_3DH5 126 }; 127 128 // Configuration Parameters 129 typedef struct { 130 BqrReportAction report_action; 131 uint32_t quality_event_mask; 132 uint16_t minimum_report_interval_ms; 133 } BqrConfiguration; 134 135 // BQR sub-event of Vendor Specific Event 136 class BqrVseSubEvt { 137 public: 138 // Parse the Bluetooth Quality Report VSE sub-event. 139 // 140 // @param length Total length of all parameters contained in the sub-event. 141 // @param p_param_buf A pointer to the parameters contained in the sub-event. 142 // @return false If the parameter total length is abnormal. 143 // true If all parameters are parsed successfully. 144 bool ParseBqrEvt(uint8_t length, uint8_t* p_param_buf); 145 146 // Get a string representation of the Bluetooth Quality event. 147 // 148 // @return a string representation of the Bluetooth Quality event. 149 std::string ToString() const; 150 151 friend std::ostream& operator<<(std::ostream& os, const BqrVseSubEvt& a) { 152 return os << a.ToString(); 153 } 154 155 virtual ~BqrVseSubEvt() = default; 156 157 // Quality report ID. 158 uint8_t quality_report_id_ = 0; 159 // Packet type of the connection. 160 uint8_t packet_types_ = 0; 161 // Connection handle of the connection. 162 uint16_t connection_handle_ = 0; 163 // Performing Role for the connection. 164 uint8_t connection_role_ = 0; 165 // Current Transmit Power Level for the connection. This value is the same as 166 // the controller's response to the HCI_Read_Transmit_Power_Level HCI command. 167 uint8_t tx_power_level_ = 0; 168 // Received Signal Strength Indication (RSSI) value for the connection. This 169 // value is an absolute receiver signal strength value. 170 int8_t rssi_ = 0; 171 // Signal-to-Noise Ratio (SNR) value for the connection. It is the average 172 // SNR of all the channels used by the link currently. 173 uint8_t snr_ = 0; 174 // Indicates the number of unused channels in AFH_channel_map. 175 uint8_t unused_afh_channel_count_ = 0; 176 // Indicates the number of the channels which are interfered and quality is 177 // bad but are still selected for AFH. 178 uint8_t afh_select_unideal_channel_count_ = 0; 179 // Current Link Supervision Timeout Setting. 180 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 181 uint16_t lsto_ = 0; 182 // Piconet Clock for the specified Connection_Handle. This value is the same 183 // as the controller's response to HCI_Read_Clock HCI command with the 184 // parameter "Which_Clock" of 0x01 (Piconet Clock). 185 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 186 uint32_t connection_piconet_clock_ = 0; 187 // The count of retransmission. 188 uint32_t retransmission_count_ = 0; 189 // The count of no RX. 190 uint32_t no_rx_count_ = 0; 191 // The count of NAK (Negative Acknowledge). 192 uint32_t nak_count_ = 0; 193 // Timestamp of last TX ACK. 194 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 195 uint32_t last_tx_ack_timestamp_ = 0; 196 // The count of Flow-off (STOP). 197 uint32_t flow_off_count_ = 0; 198 // Timestamp of last Flow-on (GO). 199 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 200 uint32_t last_flow_on_timestamp_ = 0; 201 // Buffer overflow count (how many bytes of TX data are dropped) since the 202 // last event. 203 uint32_t buffer_overflow_bytes_ = 0; 204 // Buffer underflow count (in byte). 205 uint32_t buffer_underflow_bytes_ = 0; 206 // Local wall clock timestamp of receiving BQR VSE sub-event 207 std::tm tm_timestamp_ = {}; 208 }; 209 210 // Get a string representation of the Quality Report ID. 211 // 212 // @param quality_report_id The quality report ID to convert. 213 // @return a string representation of the Quality Report ID. 214 std::string QualityReportIdToString(uint8_t quality_report_id); 215 216 // Get a string representation of the Packet Type. 217 // 218 // @param packet_type The packet type to convert. 219 // @return a string representation of the Packet Type. 220 std::string PacketTypeToString(uint8_t packet_type); 221 222 // Enable/Disable Bluetooth Quality Report mechanism. 223 // 224 // Which Quality event will be enabled is according to the setting of the 225 // property "persist.bluetooth.bqr.event_mask". 226 // And the minimum time interval of quality event reporting depends on the 227 // setting of property "persist.bluetooth.bqr.min_interval_ms". 228 // 229 // @param is_enable True/False to enable/disable Bluetooth Quality Report 230 // mechanism in the Bluetooth controller. 231 void EnableBtQualityReport(bool is_enable); 232 233 // Dump Bluetooth Quality Report information. 234 // 235 // @param fd The file descriptor to use for dumping information. 236 void DebugDump(int fd); 237 238 // Configure Bluetooth Quality Report setting to the Bluetooth controller. 239 // 240 // @param bqr_config The struct of configuration parameters. 241 void ConfigureBqr(const BqrConfiguration& bqr_config); 242 243 // Invoked on completion of Bluetooth Quality Report configuration. Then it will 244 // Register/Unregister for receiving VSE - Bluetooth Quality Report sub event. 245 // 246 // @param current_evt_mask Indicates current quality event bit mask setting in 247 // the Bluetooth controller. 248 void ConfigureBqrCmpl(uint32_t current_evt_mask); 249 250 // Callback invoked on completion of vendor specific Bluetooth Quality Report 251 // command. 252 // 253 // @param p_vsc_cmpl_params A pointer to the parameters contained in the vendor 254 // specific command complete event. 255 void BqrVscCompleteCallback(tBTM_VSC_CMPL* p_vsc_cmpl_params); 256 257 // Record a new incoming Bluetooth Quality Report in quality event queue. 258 // 259 // @param len Lengths of the quality report sent from the Bluetooth 260 // controller. 261 // @param p_quality_report A pointer to the quality report which is sent from 262 // the Bluetooth controller via Vendor Specific Event. 263 void AddBqrEventToQueue(uint8_t length, uint8_t* p_stream); 264 265 } // namespace bqr 266 } // namespace bluetooth 267 268 #endif // BTIF_BQR_H_ 269