.. Add general general-debugging section first, then add the BLE stuff .. include:: /debugging/inc_general-debugging.rst Debugging a Program Exit ------------------------ The program must never exit the main() function. The usual cause for this is that some software module has called ``abort()``. Both IAR and CCS will halt execution when this happens, and the disassembly and call stack will show some type of `__exit` symbol. The BLE Stack will call `ICall_abort()` when one of the below happens: * Calling an ICall function from a stack callback * Misconfiguring of additional ICall tasks or entities * Incorrect ICall task registering Should the call stack not give enough information to deduce the cause of the abort, a breakpoint can be set in the ICall\_abort function to trace from where this error is coming. HAL Assert Handling ------------------- Asserts can be useful when debugging, to trap undesirable states in the code. The BLE Stack projects are by default set up to have the global preprocessor symbol ``EXT_HAL_ASSERT`` enabled, which will try to call an assert handler that the user application can define. Catching Stack Asserts in the Application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The application has an assert callback to catch asserts in the stack project. The assert callback is registered in main() function of each project:: /* Register Application callback to trap asserts raised in the Stack */ RegisterAssertCback(AssertHandler); The ``main.c`` file also contains an example ``AssertHandler`` function. Some generic assert causes that can be returned in the callback include HAL\_ASSERT\_CAUSE\_TRUE, HAL\_ASSERT\_CAUSE\_OUT\_OF\_MEMORY, and HAL\_ASSERT\_CAUSE\_ICALL\_ABORT. The user can decide how to handle these asserts in the callback. By default, it goes into spinlock for most of the asserts. The assert can also define a subcause that gives a more specific reason for the assert. An example of a subcause is HAL\_ASSERT\_OUT\_OF\_HEAP, which describes the type of memory causing the assert for HAL\_ASSERT\_CAUSE\_OUT\_OF\_MEMORY. If no application callback is registered, the default assert callback is called and returns without further action unless HAL\_ASSERT\_SPIN is defined in the application project, which traps the application in an infinite while loop. In addition, one of the following can also be defined in the stack project if it is not caught in the application callback: * HAL\_ASSERT\_RESET: Resets the device * HAL\_ASSERT\_LIGHTS: Turn on the hazard lights (to be configured by user) * HAL\_ASSERT\_SPIN: Spinlock in a while loop indefinitely Enable these by ensuring that one of the above corresponding symbols are defined in the preprocessor symbols. See hal\_assert.h and hal\_assert.c in the stack project for implementation details. Preprocessor Options -------------------- Preprocessor symbols configure system behavior, features, and resource usage at compile time. Some symbols are required as part of the Bluetooth low energy system, while others are configurable. See :ref:`sec-developing-with-ccs-accessing-preprocessor-symbols` or :ref:`sec-developing-with-iar-accessing-preprocessor-symbols` for details on accessing preprocessor symbols. Symbols defined in a particular project are defined in all files within the project. Modifying ^^^^^^^^^ To disable a symbol, put an *x* in front of the name. To disable power management, change POWER\_SAVING to xPOWER\_SAVING. Options ^^^^^^^ :numref:`tbl_preproc_symbols_ble_app` lists the preprocessor symbols used by the application in the simple\_peripheral project. Symbols that must remain unmodified are marked with an *N* in the Modify column while modifiable; configurable symbols are marked with a *Y*. .. _tbl_preproc_symbols_ble_app: .. table:: BLE Application Preprocessor Symbols +------------------------------------------+---------------------------------------------------------------------------+------------------+ | **Preprocessor Symbol** | **Description** | **Modify** | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | USE\_ICALL | Required to use ICall Bluetooth low energy and primitive services. | N | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | POWER\_SAVING | Power management is enabled when defined, and disabled when | Y | | | not defined. Requires same option in stack project. | | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | HEAPMGR\_SIZE=0 | Defines the size in bytes of the ICall heap. Memory is allocated in | Y | | | .bss section. When zero, the heap is auto sized. See | | | | :ref:`dynamic_memory_allocation`. | | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | ICALL\_MAX\_NUM\_TASKS=3 | Defines the number of ICall aware tasks. Modify only if adding a | Y | | | new TI-RTOS task that uses ICall services. | | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | ICALL\_MAX\_NUM\_ENTITIES=6 | Defines maximum number of entities that use ICall, including | Y | | | service entities and application entities. Modify only if adding a | | | | new TI-RTOS task that uses ICall services. | | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | Display\_DISABLE\_ALL | All Display statements are removed and no display operations will | Y | | | take place. See Display.h for more details found in the Drivers | | | | virtual folder in the project. | | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | BOARD\_DISPLAY\_EXCLUDE\_UART | Define this symbol to exclude the UART used in the display | Y | | | driver. | | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | BOARD\_DISPLAY\_EXCLUDE\_LCD | Define this symbol to exclude the LCD used in the display driver. | Y | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | MAX\_NUM\_BLE\_CONNS=1 | This is the maximum number of simultaneous Bluetooth low | Y | | | energy collections allowed. Adding more connections uses more | | | | RAM and may require increasing HEAPMGR\_SIZE. Profile heap | | | | usage accordingly. | | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | CC26XX | This selects the chipset. | N | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | | In |SDK|, only CC2640R2_LAUNCHXL is supported. | N | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | xdc\_runtime\_Assert\_DISABLE\_ALL | Disables XDC run-time assert | N | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | xdc\_runtime\_Log\_DISABLE\_ALL | Disables XDC run-time logging | N | +------------------------------------------+---------------------------------------------------------------------------+------------------+ | HEAPMGR\_METRICS | Enables collection of ICall heap metrics. See | Y | | | :ref:`dynamic_memory_allocation` for details on how to profile heap | | | | usage. | | +------------------------------------------+---------------------------------------------------------------------------+------------------+ :numref:`tbl_preproc_symbols_ble_stack` lists the only stack preprocessor options that may be modified: .. _tbl_preproc_symbols_ble_stack: .. table:: BLE Stack Preprocessor Symbols +--------------------------------------+--------------------------------------------------+------------------+ | **Preprocessor Symbol** | **Description** | **Modify** | +--------------------------------------+--------------------------------------------------+------------------+ | POWER\_SAVING | Power management is enabled when | Y | | | defined, and disabled when not defined. | | | | Requires the same option in application | | | | project. | | +--------------------------------------+--------------------------------------------------+------------------+ | GATT\_NO\_CLIENT | When defined, the GATT client is not | Y | | | included to save flash. GATT client is | | | | excluded from most peripheral projects, | | | | included in central and certain peripheral | | | | projects (for example, TimeApp). | | +--------------------------------------+--------------------------------------------------+------------------+ | BLE\_NO\_SECURITY | Unlink security functions from the | Y | | | dispatcher, used in conjunction with | | | | disabling GAP bond manager and SNV to | | | | further reduce flash space. | | +--------------------------------------+--------------------------------------------------+------------------+ | OSAL\_SNV=1 | Select the number of NV pages to use for | Y | | | SNV. Each page is 4kB of flash. A | | | | minimum of one page is required when | | | | GAP\_BOND\_MANAGER is defined. See | | | | :ref:`using-simple-nv` | | +--------------------------------------+--------------------------------------------------+------------------+ | OSAL\_MAX\_NUM\_PROXY\_TASKS=2 | Number of ICall-aware tasks the protocol | Y | | | task can communicate with. Default is 2. | | | | Increase this value if more TI-RTOS tasks | | | | are added that make ICall protocol stack | | | | API calls. | | +--------------------------------------+--------------------------------------------------+------------------+ | EXT\_HAL\_ASSERT | Extended assert enables support for | Y | | | application callback for asserts. | | +--------------------------------------+--------------------------------------------------+------------------+