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 #include "osi/include/osi.h" 23 24 namespace bluetooth { 25 namespace bqr { 26 27 // Bluetooth Quality Report (BQR) 28 // 29 // It is a feature to start the mechanism in the Bluetooth controller to report 30 // Bluetooth Quality event to the host and the following options can be 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 // [Root Inflammation] 49 // When the controller encounters an error it shall report Root Inflammation 50 // event indicating the error code to the host. 51 // 52 // [LMP/LL message trace] 53 // The controller sends the LMP/LL message handshaking with the remote 54 // device to the host. 55 // 56 // [Bluetooth Multi-profile/Coex scheduling trace] 57 // The controller sends its scheduling information on handling the Bluetooth 58 // multiple profiles and wireless coexistence in the 2.4 Ghz band to the 59 // host. 60 // 61 // [Enable the Controller Debug Information mechanism] 62 // After enabling the Controller Debug Information mechanism, the controller 63 // just can autonomously report debug logging information via the Controller 64 // Debug Info sub-event to the host. 65 // 66 67 // Bit masks for the selected quality event reporting. 68 static constexpr uint32_t kQualityEventMaskAllOff = 0; 69 static constexpr uint32_t kQualityEventMaskMonitorMode = 0x00000001; 70 static constexpr uint32_t kQualityEventMaskApproachLsto = 0x00000002; 71 static constexpr uint32_t kQualityEventMaskA2dpAudioChoppy = 0x00000004; 72 static constexpr uint32_t kQualityEventMaskScoVoiceChoppy = 0x00000008; 73 static constexpr uint32_t kQualityEventMaskRootInflammation = 0x00000010; 74 static constexpr uint32_t kQualityEventMaskLmpMessageTrace = 0x00010000; 75 static constexpr uint32_t kQualityEventMaskBtSchedulingTrace = 0x00020000; 76 static constexpr uint32_t kQualityEventMaskControllerDbgInfo = 0x00040000; 77 static constexpr uint32_t kQualityEventMaskAll = 78 kQualityEventMaskMonitorMode | kQualityEventMaskApproachLsto | 79 kQualityEventMaskA2dpAudioChoppy | kQualityEventMaskScoVoiceChoppy | 80 kQualityEventMaskRootInflammation | kQualityEventMaskLmpMessageTrace | 81 kQualityEventMaskBtSchedulingTrace | kQualityEventMaskControllerDbgInfo; 82 // Define the minimum time interval (in ms) of quality event reporting for the 83 // selected quality event(s). Controller Firmware should not report the next 84 // event within the defined time interval. 85 static constexpr uint16_t kMinReportIntervalNoLimit = 0; 86 static constexpr uint16_t kMinReportIntervalMaxMs = 0xFFFF; 87 // The maximum count of Log Dump related event can be written in the log file. 88 static constexpr uint16_t kLogDumpEventPerFile = 0x00FF; 89 // Total length of all parameters of the link Quality related event except 90 // Vendor Specific Parameters. 91 static constexpr uint8_t kLinkQualityParamTotalLen = 48; 92 // Total length of all parameters of the ROOT_INFLAMMATION event except Vendor 93 // Specific Parameters. 94 static constexpr uint8_t kRootInflammationParamTotalLen = 3; 95 // Total length of all parameters of the Log Dump related event except Vendor 96 // Specific Parameters. 97 static constexpr uint8_t kLogDumpParamTotalLen = 3; 98 // Warning criteria of the RSSI value. 99 static constexpr int8_t kCriWarnRssi = -80; 100 // Warning criteria of the unused AFH channel count. 101 static constexpr uint8_t kCriWarnUnusedCh = 55; 102 // The queue size of recording the BQR events. 103 static constexpr uint8_t kBqrEventQueueSize = 25; 104 // The Property of BQR event mask configuration. 105 static constexpr const char* kpPropertyEventMask = 106 "persist.bluetooth.bqr.event_mask"; 107 // The Property of BQR minimum report interval configuration. 108 static constexpr const char* kpPropertyMinReportIntervalMs = 109 "persist.bluetooth.bqr.min_interval_ms"; 110 // Path of the LMP/LL message trace log file. 111 static constexpr const char* kpLmpLlMessageTraceLogPath = 112 "/data/misc/bluetooth/logs/lmp_ll_message_trace.log"; 113 // Path of the last LMP/LL message trace log file. 114 static constexpr const char* kpLmpLlMessageTraceLastLogPath = 115 "/data/misc/bluetooth/logs/lmp_ll_message_trace.log.last"; 116 // Path of the Bluetooth Multi-profile/Coex scheduling trace log file. 117 static constexpr const char* kpBtSchedulingTraceLogPath = 118 "/data/misc/bluetooth/logs/bt_scheduling_trace.log"; 119 // Path of the last Bluetooth Multi-profile/Coex scheduling trace log file. 120 static constexpr const char* kpBtSchedulingTraceLastLogPath = 121 "/data/misc/bluetooth/logs/bt_scheduling_trace.log.last"; 122 123 // File Descriptor of LMP/LL message trace log 124 static int LmpLlMessageTraceLogFd = INVALID_FD; 125 // File Descriptor of Bluetooth Multi-profile/Coex scheduling trace log 126 static int BtSchedulingTraceLogFd = INVALID_FD; 127 // Counter of LMP/LL message trace 128 static uint16_t LmpLlMessageTraceCounter = 0; 129 // Counter of Bluetooth Multi-profile/Coex scheduling trace 130 static uint16_t BtSchedulingTraceCounter = 0; 131 132 // Action definition 133 // 134 // Action to Add, Delete or Clear the reporting of quality event(s). 135 // Delete will clear specific quality event(s) reporting. Clear will clear all 136 // quality events reporting. 137 enum BqrReportAction : uint8_t { 138 REPORT_ACTION_ADD = 0x00, 139 REPORT_ACTION_DELETE = 0x01, 140 REPORT_ACTION_CLEAR = 0x02 141 }; 142 143 // Report ID definition 144 enum BqrQualityReportId : uint8_t { 145 QUALITY_REPORT_ID_MONITOR_MODE = 0x01, 146 QUALITY_REPORT_ID_APPROACH_LSTO = 0x02, 147 QUALITY_REPORT_ID_A2DP_AUDIO_CHOPPY = 0x03, 148 QUALITY_REPORT_ID_SCO_VOICE_CHOPPY = 0x04, 149 QUALITY_REPORT_ID_ROOT_INFLAMMATION = 0x05, 150 QUALITY_REPORT_ID_LMP_LL_MESSAGE_TRACE = 0x11, 151 QUALITY_REPORT_ID_BT_SCHEDULING_TRACE = 0x12, 152 QUALITY_REPORT_ID_CONTROLLER_DBG_INFO = 0x13 153 }; 154 155 // Packet Type definition 156 enum BqrPacketType : uint8_t { 157 PACKET_TYPE_ID = 0x01, 158 PACKET_TYPE_NULL, 159 PACKET_TYPE_POLL, 160 PACKET_TYPE_FHS, 161 PACKET_TYPE_HV1, 162 PACKET_TYPE_HV2, 163 PACKET_TYPE_HV3, 164 PACKET_TYPE_DV, 165 PACKET_TYPE_EV3, 166 PACKET_TYPE_EV4, 167 PACKET_TYPE_EV5, 168 PACKET_TYPE_2EV3, 169 PACKET_TYPE_2EV5, 170 PACKET_TYPE_3EV3, 171 PACKET_TYPE_3EV5, 172 PACKET_TYPE_DM1, 173 PACKET_TYPE_DH1, 174 PACKET_TYPE_DM3, 175 PACKET_TYPE_DH3, 176 PACKET_TYPE_DM5, 177 PACKET_TYPE_DH5, 178 PACKET_TYPE_AUX1, 179 PACKET_TYPE_2DH1, 180 PACKET_TYPE_2DH3, 181 PACKET_TYPE_2DH5, 182 PACKET_TYPE_3DH1, 183 PACKET_TYPE_3DH3, 184 PACKET_TYPE_3DH5 185 }; 186 187 // Configuration Parameters 188 typedef struct { 189 BqrReportAction report_action; 190 uint32_t quality_event_mask; 191 uint16_t minimum_report_interval_ms; 192 } BqrConfiguration; 193 194 // Link quality related BQR event 195 typedef struct { 196 // Quality report ID. 197 uint8_t quality_report_id; 198 // Packet type of the connection. 199 uint8_t packet_types; 200 // Connection handle of the connection. 201 uint16_t connection_handle; 202 // Performing Role for the connection. 203 uint8_t connection_role; 204 // Current Transmit Power Level for the connection. This value is the same as 205 // the controller's response to the HCI_Read_Transmit_Power_Level HCI command. 206 int8_t tx_power_level; 207 // Received Signal Strength Indication (RSSI) value for the connection. This 208 // value is an absolute receiver signal strength value. 209 int8_t rssi; 210 // Signal-to-Noise Ratio (SNR) value for the connection. It is the average 211 // SNR of all the channels used by the link currently. 212 uint8_t snr; 213 // Indicates the number of unused channels in AFH_channel_map. 214 uint8_t unused_afh_channel_count; 215 // Indicates the number of the channels which are interfered and quality is 216 // bad but are still selected for AFH. 217 uint8_t afh_select_unideal_channel_count; 218 // Current Link Supervision Timeout Setting. 219 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 220 uint16_t lsto; 221 // Piconet Clock for the specified Connection_Handle. This value is the same 222 // as the controller's response to HCI_Read_Clock HCI command with the 223 // parameter "Which_Clock" of 0x01 (Piconet Clock). 224 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 225 uint32_t connection_piconet_clock; 226 // The count of retransmission. 227 uint32_t retransmission_count; 228 // The count of no RX. 229 uint32_t no_rx_count; 230 // The count of NAK (Negative Acknowledge). 231 uint32_t nak_count; 232 // Timestamp of last TX ACK. 233 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 234 uint32_t last_tx_ack_timestamp; 235 // The count of Flow-off (STOP). 236 uint32_t flow_off_count; 237 // Timestamp of last Flow-on (GO). 238 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 239 uint32_t last_flow_on_timestamp; 240 // Buffer overflow count (how many bytes of TX data are dropped) since the 241 // last event. 242 uint32_t buffer_overflow_bytes; 243 // Buffer underflow count (in byte). 244 uint32_t buffer_underflow_bytes; 245 // For the controller vendor to obtain more vendor specific parameters. 246 uint8_t* vendor_specific_parameter; 247 } BqrLinkQualityEvent; 248 249 // Log dump related BQR event 250 typedef struct { 251 // Quality report ID. 252 uint8_t quality_report_id; 253 // Connection handle of the connection. 254 uint16_t connection_handle; 255 // For the controller vendor to obtain more vendor specific parameters. 256 uint8_t* vendor_specific_parameter; 257 } BqrLogDumpEvent; 258 259 // BQR sub-event of Vendor Specific Event 260 class BqrVseSubEvt { 261 public: 262 // Parse the Link Quality related BQR event. 263 // 264 // @param length Total length of all parameters contained in the sub-event. 265 // @param p_param_buf A pointer to the parameters contained in the sub-event. 266 void ParseBqrLinkQualityEvt(uint8_t length, uint8_t* p_param_buf); 267 // Write the LMP/LL message trace to the log file. 268 // 269 // @param fd The File Descriptor of the log file. 270 // @param length Total length of all parameters contained in the sub-event. 271 // @param p_param_buf A pointer to the parameters contained in the sub-event. 272 void WriteLmpLlTraceLogFile(int fd, uint8_t length, uint8_t* p_param_buf); 273 // Write the Bluetooth Multi-profile/Coex scheduling trace to the log file. 274 // 275 // @param fd The File Descriptor of the log file. 276 // @param length Total length of all parameters contained in the sub-event. 277 // @param p_param_buf A pointer to the parameters contained in the sub-event. 278 void WriteBtSchedulingTraceLogFile(int fd, uint8_t length, 279 uint8_t* p_param_buf); 280 // Get a string representation of the Bluetooth Quality event. 281 // 282 // @return a string representation of the Bluetooth Quality event. 283 std::string ToString() const; 284 285 friend std::ostream& operator<<(std::ostream& os, const BqrVseSubEvt& a) { 286 return os << a.ToString(); 287 } 288 289 virtual ~BqrVseSubEvt() = default; 290 // Link Quality related BQR event 291 BqrLinkQualityEvent bqr_link_quality_event_ = {}; 292 // Log Dump related BQR event 293 BqrLogDumpEvent bqr_log_dump_event_ = {}; 294 // Local wall clock timestamp of receiving BQR VSE sub-event 295 std::tm tm_timestamp_ = {}; 296 }; 297 298 // Get a string representation of the Quality Report ID. 299 // 300 // @param quality_report_id The quality report ID to convert. 301 // @return a string representation of the Quality Report ID. 302 std::string QualityReportIdToString(uint8_t quality_report_id); 303 304 // Get a string representation of the Packet Type. 305 // 306 // @param packet_type The packet type to convert. 307 // @return a string representation of the Packet Type. 308 std::string PacketTypeToString(uint8_t packet_type); 309 310 // Enable/Disable Bluetooth Quality Report mechanism. 311 // 312 // Which Quality event will be enabled is according to the setting of the 313 // property "persist.bluetooth.bqr.event_mask". 314 // And the minimum time interval of quality event reporting depends on the 315 // setting of property "persist.bluetooth.bqr.min_interval_ms". 316 // 317 // @param is_enable True/False to enable/disable Bluetooth Quality Report 318 // mechanism in the Bluetooth controller. 319 void EnableBtQualityReport(bool is_enable); 320 321 // Configure Bluetooth Quality Report setting to the Bluetooth controller. 322 // 323 // @param bqr_config The struct of configuration parameters. 324 void ConfigureBqr(const BqrConfiguration& bqr_config); 325 326 // Callback invoked on completion of vendor specific Bluetooth Quality Report 327 // command. 328 // 329 // @param p_vsc_cmpl_params A pointer to the parameters contained in the vendor 330 // specific command complete event. 331 void BqrVscCompleteCallback(tBTM_VSC_CMPL* p_vsc_cmpl_params); 332 333 // Invoked on completion of Bluetooth Quality Report configuration. Then it will 334 // Register/Unregister for receiving VSE - Bluetooth Quality Report sub-event. 335 // 336 // @param current_evt_mask Indicates current quality event bit mask setting in 337 // the Bluetooth controller. 338 void ConfigureBqrCmpl(uint32_t current_evt_mask); 339 340 // Categorize the incoming Bluetooth Quality Report. 341 // 342 // @param length Lengths of the quality report sent from the Bluetooth 343 // controller. 344 // @param p_bqr_event A pointer to the BQR VSE sub-event which is sent from the 345 // Bluetooth controller. 346 void CategorizeBqrEvent(uint8_t length, uint8_t* p_bqr_event); 347 348 // Record a new incoming Link Quality related BQR event in quality event queue. 349 // 350 // @param length Lengths of the Link Quality related BQR event. 351 // @param p_link_quality_event A pointer to the Link Quality related BQR event. 352 void AddLinkQualityEventToQueue(uint8_t length, uint8_t* p_link_quality_event); 353 354 // Dump the LMP/LL message handshaking with the remote device to a log file. 355 // 356 // @param length Lengths of the LMP/LL message trace event. 357 // @param p_lmp_ll_message_event A pointer to the LMP/LL message trace event. 358 void DumpLmpLlMessage(uint8_t length, uint8_t* p_lmp_ll_message_event); 359 360 // Open the LMP/LL message trace log file. 361 // 362 // @return a file descriptor of the LMP/LL message trace log file. 363 int OpenLmpLlTraceLogFile(); 364 365 // Dump the Bluetooth Multi-profile/Coex scheduling information to a log file. 366 // 367 // @param length Lengths of the Bluetooth Multi-profile/Coex scheduling trace 368 // event. 369 // @param p_bt_scheduling_event A pointer to the Bluetooth Multi-profile/Coex 370 // scheduling trace event. 371 void DumpBtScheduling(uint8_t length, uint8_t* p_bt_scheduling_event); 372 373 // Open the Bluetooth Multi-profile/Coex scheduling trace log file. 374 // 375 // @return a file descriptor of the Bluetooth Multi-profile/Coex scheduling 376 // trace log file. 377 int OpenBtSchedulingTraceLogFile(); 378 379 // Dump Bluetooth Quality Report information. 380 // 381 // @param fd The file descriptor to use for dumping information. 382 void DebugDump(int fd); 383 384 } // namespace bqr 385 } // namespace bluetooth 386 387 #endif // BTIF_BQR_H_ 388