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