20. Heap Memory Usage

SDK6 uses four heap areas for dynamic memory allocation:

  • KE_MEM_ENV: Used for environment variables.

  • KE_MEM_ATT_DB: Used for service attribute databases.

  • KE_MEM_KE_MSG: Used for kernel messages.

  • KE_MEM_NON_RETENTION: Used for general purpose heap memory.

The SDK contains default values for the maximum size of each of these heap areas and normally no adjustment is necessary.

20.1. Heap Memory Errors

Occasionally, the default heap sizes are not sufficient for your application. In this case, when running your application under control of the debugger, you might find it stopping in the platform_reset_func and that the error value passed to this function is RESET_MEM_ALLOC_FAIL.

If you get this heap related error while running your application, then the first step is to determine which heap(s) have run out of memory. To do this, follow the instructions in the Heap Memory Logging section below.

20.2. Heap Memory Logging

The actual amount of heap memory in use can be monitored, by running your application under control of the Keil Debugger, as follows:

  1. Set the CFG_LOG_HEAP_USAGE macro definition, in the da1458x_config_advanced.h file, to defined:

#define CFG_LOG_HEAP_USAGE
  1. Replace da14531.lib with da14531_with_heap_logging.lib in the Keil project:

_images/heap_log_lib.png

Figure 57 Using the Heap Logging Library

Note

The heap logging libraries can be found in the \sdk\platform\system_library\output\Keil_5 folder of the SDK.

  1. Rebuild the application and then execute using the Keil debugger. In the command window type disp_heaplog() and you should see something like the following:

_images/disp_heaplog.png

Figure 58 Display Heap Log Results

The current values represent the amount of heap memory used at the time the disp_heaplog command was executed. The maximum values represent the maximum amount of heap memory that has been used so far - note, it does not represent the maximum heap memory available.

If the memory set aside for a particular heap becomes exhausted, then memory from another heap area is used. If this happens the Used size in other HEAPs entries in the log will be none-zero.

Note

Your application code will continue to run after this command has been executed. It is recommended to try using this command at different points while your code is executing, to get a feel for the maximum heap usage. For example, if your device acts as a BLE peripheral, check the heap usage after it has connected to a central etc.

If you find that one or more of the heap areas is out of memory, you can inrease the maximum size by following the instructions in the next section.

20.3. Heap Memory Resizing

The default values for the maximum heap sizes can be overridden using the following macros, defined in the file da1458x_config_advanced.h:

/****************************************************************************************************************/
/* Custom heap sizes                                                                                            */
/****************************************************************************************************************/
// #define DB_HEAP_SZ              1024
// #define ENV_HEAP_SZ             4928
// #define MSG_HEAP_SZ             6880
// #define NON_RET_HEAP_SZ         2048

Simply uncomment the macro(s) corresponding to the heap size you want to change, and then set the value accordingly. For example, if you want to increase the maximum size of the non retained heap to 3000 bytes, you would change the definition to the following:

/****************************************************************************************************************/
/* Custom heap sizes                                                                                            */
/****************************************************************************************************************/
// #define DB_HEAP_SZ              1024
// #define ENV_HEAP_SZ             4928
// #define MSG_HEAP_SZ             6880
#define NON_RET_HEAP_SZ            3000

When an error occurs, logging the heap usage only tells you that you have run out of memory. It does not tell you how much bigger the heap area needs to be. Determining this is an itterative process; increase the relevant custom heap size macro, rebuild the application and then log the heap memory usage once again. After a couple of iterations you should have discovered a suitable maximum heap size.

Note

It might be tempting to simply increase the maximum heap size to a large value. We recommend against doing this. Using large memory areas for the heap reduces the amount of memory available for code and data storage.

20.4. Optimizing Heap Memory Usage

Some common causes of heap exhaustion are as follows:

  • Defining a large number of services/characteristics can result in database heap exhaustion. It is recommended to keep the number of services and characteritics to a minimum.