Merge pull request #14198 from ARMmbed/feature-bluetooth-traces

Feature bluetooth traces

Author: 0xc0170

.github/issue_template.md

@@ -47,4 +47,8 @@
 
 #### How is this defect reproduced ? 
 
+<!--
+    For connectivity issues it is recommended to enable mbed trace and attach the traces 
+    generated by the logger to the issue. 
+-->
 

connectivity/FEATURE_BLE/libraries/cordio_stack/wsf/include/wsf_trace.h

@@ -26,6 +26,10 @@
 
 #include <stdarg.h>
 
+#if MBED_CONF_CORDIO_TRACE_HCI_PACKETS
+#include "mbed_wsf_trace.h"
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -289,6 +293,7 @@ bool_t WsfTokenService(void);
 /*! \brief 3 argument HCI error trace. */
 #define HCI_TRACE_ERR3(msg, var1, var2, var3)       WSF_TRACE3("HCI", "ERR",  msg, var1, var2, var3)
 
+#if !MBED_CONF_CORDIO_TRACE_HCI_PACKETS
 /*! \brief HCI PDUMP on command. */
 #define HCI_PDUMP_CMD(len, pBuf)
 /*! \brief HCI PDUMP on event. */
@@ -301,6 +306,7 @@ bool_t WsfTokenService(void);
 #define HCI_PDUMP_TX_ISO(len, pBuf)
 /*! \brief HCI PDUMP on Received ISO message. */
 #define HCI_PDUMP_RX_ISO(len, pBuf)
+#endif // !MBED_CONF_CORDIO_TRACE_HCI_PACKETS
 
 /*! \brief 0 argument DM info trace. */
 #define DM_TRACE_INFO0(msg)                         WSF_TRACE0("DM", "INFO", msg)

connectivity/FEATURE_BLE/mbed_lib.json

@@ -108,10 +108,15 @@
             "value": 16,
             "macro_name": "BLE_GAP_HOST_PRIVACY_RESOLVED_CACHE_SIZE"
         },
+
         "ble-passkey-display-reversed-digits-deprecation": {
           "help": "This option is part of the deprecation process. Set this to false to remove the deprecation notice. When set to true, the digits in the SecurityManager passkeyDiplay event are reversed. When set to false the digits are in the correct order.",
           "value": true,
           "macro_name": "BLE_PASSKEY_DISPLAY_REVERSED_DIGITS_DEPRECATION"
+        },
+        "trace-human-readable-enums": {
+            "help": "More hexadecimal values in traces will be printed as human readable strings.",
+            "value": false
         }
     },
     "target_overrides": {

connectivity/FEATURE_BLE/source/CMakeLists.txt

@@ -7,13 +7,19 @@ add_subdirectory(gatt)
 add_subdirectory(generic)
 add_subdirectory(pal)
 
+target_include_directories(mbed-ble
+    INTERFACE
+        .
+)
+
 target_sources(mbed-ble
     INTERFACE
         BLE.cpp
         Gap.cpp
         GattClient.cpp
         GattServer.cpp
         SecurityManager.cpp
+        common/ble_trace_helpers.cpp
 )
 
 target_link_libraries(mbed-ble

connectivity/FEATURE_BLE/source/common/ble_trace_helpers.cpp

@@ -0,0 +1,120 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2021 ARM Limited
+ * SPDX-License-Identifier: Apache-2.0
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef BLE_CLIAPP_BLE_TRACE_HELPERS_H
+#define BLE_CLIAPP_BLE_TRACE_HELPERS_H
+
+#include "ble/BLE.h"
+#include "ble/SecurityManager.h"
+#include "mbed-trace/mbed_trace.h"
+#include "pal/GapTypes.h"
+#include "pal/GapEvents.h"
+#include "dm_api.h"
+#include "common/UUID.h"
+
+namespace ble {
+#if MBED_CONF_MBED_TRACE_ENABLE
+void trace_le_supported_features(uint64_t feat);
+
+const char* dm_callback_event_to_string(uint8_t event);
+const char* hci_opcode_to_string(uint16_t opcode);
+const char* attribute_error_code_to_string(uint8_t error);
+const char* attribute_opcode_to_string(uint8_t error);
+const char* ble_error_to_string(ble_error_t error);
+const char* att_client_callback_event_to_string(uint8_t code);
+const char* att_error_code_to_string(uint8_t code);
+#endif //MBED_CONF_MBED_TRACE_ENABLE
+
+template<size_t size>
+const char* to_string(const ble::byte_array_t<size> &array)
+{
+    return (mbed_trace_array)(array.data(), array.size());
+}
+
+const char* to_string(const UUID& uuid);
+
+const char *to_string(bool v);
+
+const char *to_string(ble::SecurityManager::SecurityIOCapabilities_t capabilities);
+
+const char *to_string(ble::io_capability_t capabilities);
+
+const char *to_string(ble::SecurityManager::SecurityMode_t security_mode);
+
+const char *passkey_str(const uint8_t* passkey);
+
+const char *to_string(const ble::address_t& address);
+
+const char *to_string(const ble::link_encryption_t encryption);
+
+const char *to_string(Keypress_t keypress);
+
+const char *to_string(ble::pairing_failure_t reason);
+
+const char *to_string(target_peer_address_type_t type);
+
+const char *to_string(privacy_mode_t mode);
+
+const char *to_string(ble::advertising_type_t advType);
+
+const char *to_string(ble::own_address_type_t addressType);
+
+const char *to_string(ble::advertising_filter_policy_t policy);
+
+const char *to_string(ble::phy_t phy);
+
+const char *to_string(ble::scanning_filter_policy_t policy);
+
+const char *to_string(ble::duplicates_filter_t filtering);
+
+const char *to_string(ble::peer_address_type_t addressType);
+
+const char *to_string(ble::initiator_filter_policy_t policy);
+
+const char *to_string(ble::coded_symbol_per_bit_t sym);
+
+const char *to_string(ble::local_disconnection_reason_t reason);
+
+const char *to_string(ble::advertising_channel_map_t map);
+
+const char *to_string(ble::connection_peer_address_type_t connection_peer_address_type);
+
+const char *to_string(ble::whitelist_address_type_t whitelist_address_type);
+
+const char *to_string(ble::hci_error_code_t error);
+
+const char *to_string(ble::advertising_fragment_description_t fragment_description);
+
+const char *to_string(ble::peripheral_privacy_configuration_t::resolution_strategy_t resolution_strategy);
+
+const char *to_string(ble::GapEventType event_type);
+
+const char *to_string(ble::received_advertising_type_t type);
+
+const char *to_string(ble::connection_role_t role);
+
+const char *to_string(ble::direct_address_type_t direct_address_type);
+
+const char *to_string(ble::advertising_data_status_t data_status);
+
+const char *to_string(ble::att_security_requirement_t security_requirement);
+
+const char *to_string(GattAuthCallbackReply_t authorization_reply);
+
+} // namespace ble
+
+#endif //BLE_CLIAPP_BLE_TRACE_HELPERS_H

connectivity/FEATURE_BLE/source/common/ble_trace_helpers.h

@@ -29,4 +29,5 @@ target_sources(mbed-ble-cordio
         stack_adaptation/wsf_cs.c
         stack_adaptation/wsf_mbed_os_adaptation.c
         stack_adaptation/wsf_os.c
+        stack_adaptation/mbed_wsf_trace.c
 )

connectivity/FEATURE_BLE/source/cordio/CMakeLists.txt

@@ -27,6 +27,11 @@
 #include "bstream.h"
 #include "hci_mbed_os_adaptation.h"
 
+#include "mbed-trace/mbed_trace.h"
+#include "common/ble_trace_helpers.h"
+
+#define TRACE_GROUP "BLHC"
+
 #define HCI_RESET_RAND_CNT        4
 
 namespace ble {
@@ -69,12 +74,14 @@ CordioHCIDriver::CordioHCIDriver(CordioHCITransportDriver& transport_driver) :
 
 void CordioHCIDriver::initialize()
 {
+    tr_info("CordioHCIDriver initializing");
     _transport_driver.initialize();
     do_initialize();
 }
 
 void CordioHCIDriver::terminate()
 {
+    tr_info("CordioHCIDriver terminating");
     do_terminate();
     _transport_driver.terminate();
 }
@@ -275,19 +282,34 @@ bool CordioHCIDriver::get_random_static_address(ble::address_t& address)
 
 void CordioHCIDriver::signal_reset_sequence_done()
 {
+    tr_debug("Signal cordio HCI reset sequence done");
     hci_mbed_os_signal_reset_sequence_done();
 }
 
 uint16_t CordioHCIDriver::write(uint8_t type, uint16_t len, uint8_t *pData)
 {
+#if MBED_CONF_CORDIO_TRACE_HCI_PACKETS
+    const char *type_prefix;
+    switch(type) {
+        case 0x01: type_prefix = "CMD"; break;
+        case 0x02: type_prefix = "ACL"; break;
+        /* illegal packet */
+        default: type_prefix = "ERR"; break;
+    }
+    tr_debug("HOST->LL %s %s", type_prefix, trace_array(pData, len));
+#endif
     return _transport_driver.write(type, len, pData);
 }
 
 void CordioHCIDriver::on_host_stack_inactivity()
 {
 }
+
 void CordioHCIDriver::handle_test_end(bool success, uint16_t packets)
 {
+    MBED_ASSERT(_test_end_handler);
+    tr_info("LE receiver mode ended (success: %s)", to_string(success));
+
     if (_test_end_handler) {
         _test_end_handler(success, packets);
         _test_end_handler = nullptr;
@@ -299,17 +321,21 @@ ble_error_t CordioHCIDriver::rf_test_start_le_receiver_test(
 )
 {
     if (_test_end_handler) {
+        tr_warning("Cannot start LE %s test mode - already started", "receiver");
         return BLE_ERROR_INVALID_STATE;
     }
 
     if (!test_end_handler) {
+        tr_warning("Cannot start LE %s  test mode - invalid handler", "receiver");
         return BLE_ERROR_INVALID_PARAM;
     }
 
     _test_end_handler = test_end_handler;
     uint8_t *buf = hciCmdAlloc(HCI_OPCODE_LE_RECEIVER_TEST, HCI_LEN_LE_RECEIVER_TEST);
 
     if (buf) {
+        tr_info("LE %s mode starter on channel %hhd", "receiver", channel);
+
         uint8_t* p = buf + HCI_CMD_HDR_LEN;
         UINT8_TO_BSTREAM(p, channel);
         hciCmdSend(buf);
@@ -325,17 +351,21 @@ ble_error_t CordioHCIDriver::rf_test_start_le_transmitter_test(
 )
 {
     if (_test_end_handler) {
+        tr_warning("Cannot start LE %s test mode - already started", "transmitter");
         return BLE_ERROR_INVALID_STATE;
     }
 
     if (!test_end_handler) {
+        tr_warning("Cannot start LE %s  test mode - invalid handler", "transmitter");
         return BLE_ERROR_INVALID_PARAM;
     }
 
     _test_end_handler = test_end_handler;
     uint8_t *buf = hciCmdAlloc(HCI_OPCODE_LE_TRANSMITTER_TEST, HCI_LEN_LE_TRANSMITTER_TEST);
 
     if (buf) {
+        tr_info("LE %s mode starter on channel %hhd", "transmitter", channel);
+
         uint8_t* p = buf + HCI_CMD_HDR_LEN;
         UINT8_TO_BSTREAM(p, channel);
         UINT8_TO_BSTREAM(p, length);
@@ -350,14 +380,18 @@ ble_error_t CordioHCIDriver::rf_test_start_le_transmitter_test(
 
 ble_error_t CordioHCIDriver::rf_test_end()
 {
+    MBED_ASSERT(_test_end_handler);
+
     if (!_test_end_handler) {
+        tr_info("Cannot end LE transmitter mode test - missing handler (test never started?)");
         return BLE_ERROR_INVALID_STATE;
     }
 
     uint8_t *buf = hciCmdAlloc(HCI_OPCODE_LE_TEST_END, HCI_LEN_LE_TEST_END);
 
     if (buf) {
         hciCmdSend(buf);
+        tr_info("LE transmitter mode ended");
 
         return BLE_ERROR_NONE;
     }

connectivity/FEATURE_BLE/source/cordio/driver/CordioHCIDriver.cpp

@@ -21,6 +21,11 @@
 #include "ble/driver/CordioHCITransportDriver.h"
 #include "ble/driver/CordioHCIDriver.h"
 
+#include "mbed-trace/mbed_trace.h"
+#include "common/ble_trace_helpers.h"
+
+#define TRACE_GROUP "BLHC"
+
 extern "C" void hciTrSerialRxIncoming(uint8_t *pBuf, uint8_t len);
 
 namespace ble {
@@ -40,6 +45,7 @@ void CordioHCITransportDriver::on_data_received(uint8_t* data, uint16_t len)
 
 void CordioHCITransportDriver::set_data_received_handler(data_received_handler_t handler)
 {
+    MBED_ASSERT(handler);
     data_received_handler = handler;
 }
 

connectivity/FEATURE_BLE/source/cordio/driver/CordioHCITransportDriver.cpp

@@ -81,6 +81,19 @@
             "help": "Check connection complete event if it needs the addresses swapped due to bug in controller",
             "value": null,
             "macro_name": "CORDIO_RPA_SWAP_WORKAROUND"
+        },
+        "trace-pal-echoes": {
+            "help": "Include 'echo' traces in PAL, i.e. function signature and argument prints",
+            "value": 0
+        },
+        "trace-hci-packets": {
+            "help": "If tracing is enabled at level DEBUG traces will include HCI packet traces.",
+            "value": false
+        },
+        "trace-cordio-wsf-traces": {
+            "help": "If tracing is enabled at level DEBUG traces will include WSF traces from Cordio packet traces.",
+            "value": false,
+            "macro_name": "WSF_TRACE_ENABLED"
         }
     },
     "target_overrides": {