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 "include/hardware/bt_bqr.h" 23 #include "osi/include/osi.h" 24 #include "raw_address.h" 25 26 namespace bluetooth { 27 namespace bqr { 28 29 // Bluetooth Quality Report (BQR) 30 // 31 // It is a feature to start the mechanism in the Bluetooth controller to report 32 // Bluetooth Quality event to the host and the following options can be enabled: 33 // [Quality Monitoring Mode] 34 // The controller shall periodically send Bluetooth Quality Report sub-event 35 // to the host. 36 // 37 // [Approaching LSTO] 38 // Once no packets are received from the connected Bluetooth device for a 39 // duration longer than the half of LSTO (Link Supervision TimeOut) value, 40 // the controller shall report Approaching LSTO event to the host. 41 // 42 // [A2DP Audio Choppy] 43 // When the controller detects the factors which will cause audio choppy, 44 // the controller shall report A2DP Audio Choppy event to the host. 45 // 46 // [(e)SCO Voice Choppy] 47 // When the controller detects the factors which will cause voice choppy, 48 // the controller shall report (e)SCO Voice Choppy event to the host. 49 // 50 // [Root Inflammation] 51 // When the controller encounters an error it shall report Root Inflammation 52 // event indicating the error code to the host. 53 // 54 // [Vendor Specific Quality] 55 // Used for the controller vendor to define the vendor proprietary quality 56 // event(s). 57 // 58 // [LMP/LL message trace] 59 // The controller sends the LMP/LL message handshaking with the remote 60 // device to the host. 61 // 62 // [Bluetooth Multi-profile/Coex scheduling trace] 63 // The controller sends its scheduling information on handling the Bluetooth 64 // multiple profiles and wireless coexistence in the 2.4 Ghz band to the 65 // host. 66 // 67 // [Enable the Controller Debug Information mechanism] 68 // After enabling the Controller Debug Information mechanism, the controller 69 // just can autonomously report debug logging information via the Controller 70 // Debug Info sub-event to the host. 71 // 72 // [Connect Fail] 73 // When the controller fails to create connection with remote side, 74 // and remote responds for at least one time, the controller shall report 75 // connection fail event to the host. However, if remote doesn't respond 76 // at all(most likely remote is powered off or out of range), controller 77 // will not report this event. 78 79 // Bit masks for the selected quality event reporting. 80 static constexpr uint32_t kQualityEventMaskAllOff = 0; 81 static constexpr uint32_t kQualityEventMaskMonitorMode = 0x1 << 0; 82 static constexpr uint32_t kQualityEventMaskApproachLsto = 0x1 << 1; 83 static constexpr uint32_t kQualityEventMaskA2dpAudioChoppy = 0x1 << 2; 84 static constexpr uint32_t kQualityEventMaskScoVoiceChoppy = 0x1 << 3; 85 static constexpr uint32_t kQualityEventMaskRootInflammation = 0x1 << 4; 86 static constexpr uint32_t kQualityEventMaskEnergyMonitoring = 0x1 << 5; 87 static constexpr uint32_t kQualityEventMaskLeAudioChoppy = 0x1 << 6; 88 static constexpr uint32_t kQualityEventMaskConnectFail = 0x1 << 7; 89 static constexpr uint32_t kQualityEventMaskVendorSpecificQuality = 0x1 << 15; 90 static constexpr uint32_t kQualityEventMaskLmpMessageTrace = 0x1 << 16; 91 static constexpr uint32_t kQualityEventMaskBtSchedulingTrace = 0x1 << 17; 92 static constexpr uint32_t kQualityEventMaskControllerDbgInfo = 0x1 << 18; 93 static constexpr uint32_t kQualityEventMaskVendorSpecificTrace = 0x1 << 31; 94 static constexpr uint32_t kQualityEventMaskAll = 95 kQualityEventMaskMonitorMode | kQualityEventMaskApproachLsto | 96 kQualityEventMaskA2dpAudioChoppy | kQualityEventMaskScoVoiceChoppy | 97 kQualityEventMaskRootInflammation | kQualityEventMaskEnergyMonitoring | 98 kQualityEventMaskLeAudioChoppy | kQualityEventMaskConnectFail | 99 kQualityEventMaskVendorSpecificQuality | kQualityEventMaskLmpMessageTrace | 100 kQualityEventMaskBtSchedulingTrace | kQualityEventMaskControllerDbgInfo | 101 kQualityEventMaskVendorSpecificTrace; 102 // Define the minimum time interval (in ms) of quality event reporting for the 103 // selected quality event(s). Controller Firmware should not report the next 104 // event within the defined time interval. 105 static constexpr uint16_t kMinReportIntervalNoLimit = 0; 106 static constexpr uint16_t kMinReportIntervalMaxMs = 0xFFFF; 107 // The maximum count of Log Dump related event can be written in the log file. 108 static constexpr uint16_t kLogDumpEventPerFile = 0x00FF; 109 // Total length of all parameters of the link Quality related event except 110 // Vendor Specific Parameters. 111 static constexpr uint8_t kLinkQualityParamTotalLen = 55; 112 // 7.8.116 LE Read ISO Link Quality command 113 static constexpr uint8_t kISOLinkQualityParamTotalLen = 24; 114 // Total length of all parameters of the ROOT_INFLAMMATION event except Vendor 115 // Specific Parameters. 116 static constexpr uint8_t kRootInflammationParamTotalLen = 3; 117 // Total length of all parameters of the Log Dump related event except Vendor 118 // Specific Parameters. 119 static constexpr uint8_t kLogDumpParamTotalLen = 3; 120 // Warning criteria of the RSSI value. 121 static constexpr int8_t kCriWarnRssi = -80; 122 // Warning criteria of the unused AFH channel count. 123 static constexpr uint8_t kCriWarnUnusedCh = 55; 124 // The queue size of recording the BQR events. 125 static constexpr uint8_t kBqrEventQueueSize = 25; 126 // The Property of BQR event mask configuration. 127 static constexpr const char* kpPropertyEventMask = 128 "persist.bluetooth.bqr.event_mask"; 129 // The Property of BQR Vendor Quality configuration. 130 static constexpr const char* kpPropertyVndQualityMask = 131 "persist.bluetooth.bqr.vnd_quality_mask"; 132 // The Property of BQR Vendor Trace configuration. 133 static constexpr const char* kpPropertyVndTraceMask = 134 "persist.bluetooth.bqr.vnd_trace_mask"; 135 // The Property of BQR minimum report interval configuration. 136 static constexpr const char* kpPropertyMinReportIntervalMs = 137 "persist.bluetooth.bqr.min_interval_ms"; 138 // Path of the LMP/LL message trace log file. 139 static constexpr const char* kpLmpLlMessageTraceLogPath = 140 "/data/misc/bluetooth/logs/lmp_ll_message_trace.log"; 141 // Path of the last LMP/LL message trace log file. 142 static constexpr const char* kpLmpLlMessageTraceLastLogPath = 143 "/data/misc/bluetooth/logs/lmp_ll_message_trace.log.last"; 144 // Path of the Bluetooth Multi-profile/Coex scheduling trace log file. 145 static constexpr const char* kpBtSchedulingTraceLogPath = 146 "/data/misc/bluetooth/logs/bt_scheduling_trace.log"; 147 // Path of the last Bluetooth Multi-profile/Coex scheduling trace log file. 148 static constexpr const char* kpBtSchedulingTraceLastLogPath = 149 "/data/misc/bluetooth/logs/bt_scheduling_trace.log.last"; 150 // The Property of BQR a2dp choppy report and sco choppy report thresholds. 151 // A2dp choppy will be reported only when a2dp choppy times is >= 152 // a2dp_choppy_threshold. The default value in firmware side is 1. It is same 153 // for sco choppy. Value format is a2dp_choppy_threshold,sco_choppy_threshold 154 static constexpr const char* kpPropertyChoppyThreshold = 155 "persist.bluetooth.bqr.choppy_threshold"; 156 157 // File Descriptor of LMP/LL message trace log 158 static int LmpLlMessageTraceLogFd = INVALID_FD; 159 // File Descriptor of Bluetooth Multi-profile/Coex scheduling trace log 160 static int BtSchedulingTraceLogFd = INVALID_FD; 161 // Counter of LMP/LL message trace 162 static uint16_t LmpLlMessageTraceCounter = 0; 163 // Counter of Bluetooth Multi-profile/Coex scheduling trace 164 static uint16_t BtSchedulingTraceCounter = 0; 165 // The version supports ISO packets start from v1.01(257) 166 static constexpr uint16_t kBqrIsoVersion = 0x101; 167 // The version supports vendor quality and trace log starting v1.02(258) 168 static constexpr uint16_t kBqrVndLogVersion = 0x102; 169 170 // Action definition 171 // 172 // Action to Add, Delete or Clear the reporting of quality event(s). 173 // Delete will clear specific quality event(s) reporting. Clear will clear all 174 // quality events reporting. 175 enum BqrReportAction : uint8_t { 176 REPORT_ACTION_ADD = 0x00, 177 REPORT_ACTION_DELETE = 0x01, 178 REPORT_ACTION_CLEAR = 0x02 179 }; 180 181 // Report ID definition 182 enum BqrQualityReportId : uint8_t { 183 QUALITY_REPORT_ID_MONITOR_MODE = 0x01, 184 QUALITY_REPORT_ID_APPROACH_LSTO = 0x02, 185 QUALITY_REPORT_ID_A2DP_AUDIO_CHOPPY = 0x03, 186 QUALITY_REPORT_ID_SCO_VOICE_CHOPPY = 0x04, 187 QUALITY_REPORT_ID_ROOT_INFLAMMATION = 0x05, 188 QUALITY_REPORT_ID_LE_AUDIO_CHOPPY = 0x07, 189 QUALITY_REPORT_ID_CONNECT_FAIL = 0x08, 190 QUALITY_REPORT_ID_VENDOR_SPECIFIC_QUALITY = 0x10, 191 QUALITY_REPORT_ID_LMP_LL_MESSAGE_TRACE = 0x11, 192 QUALITY_REPORT_ID_BT_SCHEDULING_TRACE = 0x12, 193 QUALITY_REPORT_ID_CONTROLLER_DBG_INFO = 0x13, 194 QUALITY_REPORT_ID_VENDOR_SPECIFIC_TRACE = 0x20, 195 }; 196 197 // Packet Type definition 198 enum BqrPacketType : uint8_t { 199 PACKET_TYPE_ID = 0x01, 200 PACKET_TYPE_NULL, 201 PACKET_TYPE_POLL, 202 PACKET_TYPE_FHS, 203 PACKET_TYPE_HV1, 204 PACKET_TYPE_HV2, 205 PACKET_TYPE_HV3, 206 PACKET_TYPE_DV, 207 PACKET_TYPE_EV3, 208 PACKET_TYPE_EV4, 209 PACKET_TYPE_EV5, 210 PACKET_TYPE_2EV3, 211 PACKET_TYPE_2EV5, 212 PACKET_TYPE_3EV3, 213 PACKET_TYPE_3EV5, 214 PACKET_TYPE_DM1, 215 PACKET_TYPE_DH1, 216 PACKET_TYPE_DM3, 217 PACKET_TYPE_DH3, 218 PACKET_TYPE_DM5, 219 PACKET_TYPE_DH5, 220 PACKET_TYPE_AUX1, 221 PACKET_TYPE_2DH1, 222 PACKET_TYPE_2DH3, 223 PACKET_TYPE_2DH5, 224 PACKET_TYPE_3DH1, 225 PACKET_TYPE_3DH3, 226 PACKET_TYPE_3DH5, 227 PACKET_TYPE_ISO = 0x51 228 }; 229 230 // Configuration Parameters 231 typedef struct { 232 BqrReportAction report_action; 233 uint32_t quality_event_mask; 234 uint16_t minimum_report_interval_ms; 235 uint32_t vnd_quality_mask; 236 uint32_t vnd_trace_mask; 237 } BqrConfiguration; 238 239 // Link quality related BQR event 240 typedef struct { 241 // Quality report ID. 242 uint8_t quality_report_id; 243 // Packet type of the connection. 244 uint8_t packet_types; 245 // Connection handle of the connection. 246 uint16_t connection_handle; 247 // Performing Role for the connection. 248 uint8_t connection_role; 249 // Current Transmit Power Level for the connection. This value is the same as 250 // the controller's response to the HCI_Read_Transmit_Power_Level HCI command. 251 int8_t tx_power_level; 252 // Received Signal Strength Indication (RSSI) value for the connection. This 253 // value is an absolute receiver signal strength value. 254 int8_t rssi; 255 // Signal-to-Noise Ratio (SNR) value for the connection. It is the average 256 // SNR of all the channels used by the link currently. 257 uint8_t snr; 258 // Indicates the number of unused channels in AFH_channel_map. 259 uint8_t unused_afh_channel_count; 260 // Indicates the number of the channels which are interfered and quality is 261 // bad but are still selected for AFH. 262 uint8_t afh_select_unideal_channel_count; 263 // Current Link Supervision Timeout Setting. 264 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 265 uint16_t lsto; 266 // Piconet Clock for the specified Connection_Handle. This value is the same 267 // as the controller's response to HCI_Read_Clock HCI command with the 268 // parameter "Which_Clock" of 0x01 (Piconet Clock). 269 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 270 uint32_t connection_piconet_clock; 271 // The count of retransmission. 272 uint32_t retransmission_count; 273 // The count of no RX. 274 uint32_t no_rx_count; 275 // The count of NAK (Negative Acknowledge). 276 uint32_t nak_count; 277 // Timestamp of last TX ACK. 278 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 279 uint32_t last_tx_ack_timestamp; 280 // The count of Flow-off (STOP). 281 uint32_t flow_off_count; 282 // Timestamp of last Flow-on (GO). 283 // Unit: N * 0.3125 ms (1 Bluetooth Clock) 284 uint32_t last_flow_on_timestamp; 285 // Buffer overflow count (how many bytes of TX data are dropped) since the 286 // last event. 287 uint32_t buffer_overflow_bytes; 288 // Buffer underflow count (in byte). 289 uint32_t buffer_underflow_bytes; 290 // Remote device address 291 RawAddress bdaddr; 292 // The count of calibration failed items 293 uint8_t cal_failed_item_count; 294 // The number of packets that are sent out. 295 uint32_t tx_total_packets; 296 // The number of packets that don't receive an acknowledgment. 297 uint32_t tx_unacked_packets; 298 // The number of packets that are not sent out by its flush point. 299 uint32_t tx_flushed_packets; 300 // The number of packets that Link Layer transmits a CIS Data PDU in the last 301 // subevent of a CIS event. 302 uint32_t tx_last_subevent_packets; 303 // The number of received packages with CRC error since the last event. 304 uint32_t crc_error_packets; 305 // The number of duplicate(retransmission) packages that are received since 306 // the last event. 307 uint32_t rx_duplicate_packets; 308 // For the controller vendor to obtain more vendor specific parameters. 309 const uint8_t* vendor_specific_parameter; 310 } BqrLinkQualityEvent; 311 312 // Log dump related BQR event 313 typedef struct { 314 // Quality report ID. 315 uint8_t quality_report_id; 316 // Connection handle of the connection. 317 uint16_t connection_handle; 318 // For the controller vendor to obtain more vendor specific parameters. 319 const uint8_t* vendor_specific_parameter; 320 } BqrLogDumpEvent; 321 322 // BQR sub-event of Vendor Specific Event 323 class BqrVseSubEvt { 324 public: 325 // Parse the Link Quality related BQR event. 326 // 327 // @param length Total length of all parameters contained in the sub-event. 328 // @param p_param_buf A pointer to the parameters contained in the sub-event. 329 void ParseBqrLinkQualityEvt(uint8_t length, const uint8_t* p_param_buf); 330 // Write the LMP/LL message trace to the log file. 331 // 332 // @param fd The File Descriptor of the log file. 333 // @param length Total length of all parameters contained in the sub-event. 334 // @param p_param_buf A pointer to the parameters contained in the sub-event. 335 void WriteLmpLlTraceLogFile(int fd, uint8_t length, 336 const uint8_t* p_param_buf); 337 // Write the Bluetooth Multi-profile/Coex scheduling trace to the log file. 338 // 339 // @param fd The File Descriptor of the log file. 340 // @param length Total length of all parameters contained in the sub-event. 341 // @param p_param_buf A pointer to the parameters contained in the sub-event. 342 void WriteBtSchedulingTraceLogFile(int fd, uint8_t length, 343 const uint8_t* p_param_buf); 344 // Get a string representation of the Bluetooth Quality event. 345 // 346 // @return a string representation of the Bluetooth Quality event. 347 std::string ToString() const; 348 349 friend std::ostream& operator<<(std::ostream& os, const BqrVseSubEvt& a) { 350 return os << a.ToString(); 351 } 352 353 virtual ~BqrVseSubEvt() = default; 354 // Link Quality related BQR event 355 BqrLinkQualityEvent bqr_link_quality_event_ = {}; 356 // Log Dump related BQR event 357 BqrLogDumpEvent bqr_log_dump_event_ = {}; 358 // Local wall clock timestamp of receiving BQR VSE sub-event 359 std::tm tm_timestamp_ = {}; 360 }; 361 362 BluetoothQualityReportInterface* getBluetoothQualityReportInterface(); 363 364 // Get a string representation of the Quality Report ID. 365 // 366 // @param quality_report_id The quality report ID to convert. 367 // @return a string representation of the Quality Report ID. 368 std::string QualityReportIdToString(uint8_t quality_report_id); 369 370 // Get a string representation of the Packet Type. 371 // 372 // @param packet_type The packet type to convert. 373 // @return a string representation of the Packet Type. 374 std::string PacketTypeToString(uint8_t packet_type); 375 376 // Enable/Disable Bluetooth Quality Report mechanism. 377 // 378 // Which Quality event will be enabled is according to the setting of the 379 // property "persist.bluetooth.bqr.event_mask". 380 // And the minimum time interval of quality event reporting depends on the 381 // setting of property "persist.bluetooth.bqr.min_interval_ms". 382 // 383 // @param is_enable True/False to enable/disable Bluetooth Quality Report 384 // mechanism in the Bluetooth controller. 385 void EnableBtQualityReport(bool is_enable); 386 387 // Configure Bluetooth Quality Report setting to the Bluetooth controller. 388 // 389 // @param bqr_config The struct of configuration parameters. 390 void ConfigureBqr(const BqrConfiguration& bqr_config); 391 392 // Callback invoked on completion of vendor specific Bluetooth Quality Report 393 // command. 394 // 395 // @param p_vsc_cmpl_params A pointer to the parameters contained in the vendor 396 // specific command complete event. 397 void BqrVscCompleteCallback(tBTM_VSC_CMPL* p_vsc_cmpl_params); 398 399 // Invoked on completion of Bluetooth Quality Report configuration. Then it will 400 // Register/Unregister for receiving VSE - Bluetooth Quality Report sub-event. 401 // 402 // @param current_evt_mask Indicates current quality event bit mask setting in 403 // the Bluetooth controller. 404 void ConfigureBqrCmpl(uint32_t current_evt_mask); 405 406 // Categorize the incoming Bluetooth Quality Report. 407 // 408 // @param length Lengths of the quality report sent from the Bluetooth 409 // controller. 410 // @param p_bqr_event A pointer to the BQR VSE sub-event which is sent from the 411 // Bluetooth controller. 412 void CategorizeBqrEvent(uint8_t length, const uint8_t* p_bqr_event); 413 414 // Record a new incoming Link Quality related BQR event in quality event queue. 415 // 416 // @param length Lengths of the Link Quality related BQR event. 417 // @param p_link_quality_event A pointer to the Link Quality related BQR event. 418 void AddLinkQualityEventToQueue(uint8_t length, 419 const uint8_t* p_link_quality_event); 420 421 // Dump the LMP/LL message handshaking with the remote device to a log file. 422 // 423 // @param length Lengths of the LMP/LL message trace event. 424 // @param p_lmp_ll_message_event A pointer to the LMP/LL message trace event. 425 void DumpLmpLlMessage(uint8_t length, const uint8_t* p_lmp_ll_message_event); 426 427 // Open the LMP/LL message trace log file. 428 // 429 // @return a file descriptor of the LMP/LL message trace log file. 430 int OpenLmpLlTraceLogFile(); 431 432 // Dump the Bluetooth Multi-profile/Coex scheduling information to a log file. 433 // 434 // @param length Lengths of the Bluetooth Multi-profile/Coex scheduling trace 435 // event. 436 // @param p_bt_scheduling_event A pointer to the Bluetooth Multi-profile/Coex 437 // scheduling trace event. 438 void DumpBtScheduling(uint8_t length, const uint8_t* p_bt_scheduling_event); 439 440 // Open the Bluetooth Multi-profile/Coex scheduling trace log file. 441 // 442 // @return a file descriptor of the Bluetooth Multi-profile/Coex scheduling 443 // trace log file. 444 int OpenBtSchedulingTraceLogFile(); 445 446 // Dump Bluetooth Quality Report information. 447 // 448 // @param fd The file descriptor to use for dumping information. 449 void DebugDump(int fd); 450 451 } // namespace bqr 452 } // namespace bluetooth 453 454 #endif // BTIF_BQR_H_ 455