You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/en/api-reference/system/heap_debug.rst
+139-2Lines changed: 139 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -200,10 +200,142 @@ Calls to :cpp:func:`heap_caps_check_integrity` or :cpp:func:`heap_caps_check_int
200
200
Heap Task Tracking
201
201
------------------
202
202
203
-
Heap Task Tracking can be used to get per-task info for heap memory allocation. The application has to specify the heap capabilities for which the heap allocation is to be tracked.
203
+
The Heap Task Tracking can be enabled via the menuconfig: ``Component config`` > ``Heap memory debugging`` > ``Enable heap task tracking`` (see :ref:`CONFIG_HEAP_TASK_TRACKING`).
204
204
205
-
Example applications are provided in :example:`system/heap_task_tracking/basic` and :example:`system/heap_task_tracking/advanced`.
205
+
The feature allows users to track the heap memory usage of each task created since startup and provides a series of statistics that can be accessed via getter functions or simply dumped into the stream of the user's choosing. This feature is useful for identifying memory usage patterns and potential memory leaks.
206
206
207
+
An additional configuration can be enabled by the user via the menuconfig: ``Component config`` > ``Heap memory debugging`` > ``Keep information about the memory usage of deleted tasks`` (see :ref:`CONFIG_HEAP_TRACK_DELETED_TASKS`) to keep the statistics collected for a given task even after it is deleted.
208
+
209
+
.. note::
210
+
Note that the Heap Task Tracking cannot detect the deletion of statically allocated tasks. Therefore, users will have to keep in mind while reading the following section that statically allocated tasks will always be considered alive in the scope of the Heap Task Tracking feature.
211
+
212
+
It is important to mention that its usage is strongly discouraged for other purposes than debugging for the following reasons:
213
+
214
+
.. list::
215
+
- Tracking the allocations and storing the resulting statistics for each task requires a non-negligible RAM usage overhead.
216
+
- The overall performance of the heap allocator is severely impacted due to the additional processing required for each allocation and free operation.
217
+
218
+
.. note::
219
+
Note that the memory allocated by the heap task tracking feature will not be visible when dumping or accessing the statistics.
220
+
221
+
Structure of the statistics and information
222
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
223
+
224
+
For a given task, the heap task tracking feature categorizes statistics on three different levels:
225
+
226
+
.. list::
227
+
- The task level statistics
228
+
- The heap level statistics
229
+
- The allocation level statistics
230
+
231
+
The task level statistics provides the following information:
232
+
233
+
.. list::
234
+
- Name of the given task
235
+
- Task handle of the given task
236
+
- Status of the given task (if the task is running or deleted)
237
+
- Peak memory usage of the given task (the maximum amount of memory used by the given task during the task lifetime)
238
+
- Current memory usage of the given task
239
+
- Number of heaps in which the task has allocated memory
240
+
241
+
The heap level statistics provides the following information for each heap used by the given task:
242
+
243
+
.. list::
244
+
- Name of the given heap
245
+
- Caps the capabilities of the given heap (without priority)
246
+
- Size the total size of the given heap
247
+
- Current usage of the given task on the given heap
248
+
- Peak usage of the given task on the given heap
249
+
- Number of allocations done by the given task for on the given heap
250
+
251
+
The allocation level statistics provides the following information for each allocation done by the given task on the given heap:
252
+
253
+
.. list::
254
+
- Address of the given allocation
255
+
- Size of the given allocation
256
+
257
+
Dumping the statistics and information
258
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
259
+
260
+
The :cpp:func:`heap_caps_print_single_task_stat_overview` API prints an overview of heap usage for a specific task to the provided output stream.
:cpp:func:`heap_caps_print_all_task_stat_overview` prints an overview of heap usage for all tasks (including the deleted tasks if :ref:`CONFIG_HEAP_TRACK_DELETED_TASKS` is enabled).
Note that the task named “Pre-scheduler” represents allocations that occurred before the scheduler was started. It is not an actual task, so the "status" field (which is shown as "ALIVE") is not meaningful and should be ignored.
287
+
288
+
Use :cpp:func:`heap_caps_print_single_task_stat` to dump the complete set of statistics for a specific task, or :cpp:func:`heap_caps_print_all_task_stat` to dump statistics for all tasks:
289
+
290
+
.. code-block:: text
291
+
292
+
[...]
293
+
├ ALIVE: main, CURRENT MEMORY USAGE 308, PEAK MEMORY USAGE 7412, TOTAL HEAP USED 2:
The dump shown above has been truncated (see "[...]") for readability reasons and only displays the statistics and information of the **main** task and the **Pre-scheduler**. The goal here is only to demonstrate the information displayed when calling the :cpp:func:`heap_caps_print_all_task_stat` (resp. :cpp:func:`heap_caps_print_single_task_stat`) API functions.
320
+
321
+
.. note::
322
+
Detailed use of the API functions described in this section can be found in :example:`system/heap_task_tracking/basic`.
323
+
324
+
Getting the statistics and information
325
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
326
+
327
+
:cpp:func:`heap_caps_get_single_task_stat` allows the user to access information of a specific task. The information retrieved by calling this API is identical to the one dumped using :cpp:func:`heap_caps_print_single_task_stat`.
328
+
329
+
:cpp:func:`heap_caps_get_all_task_stat` allows the user to access an overview of the information of all tasks (including the deleted tasks if :ref:`CONFIG_HEAP_TRACK_DELETED_TASKS` is enabled). The information retrieved by calling this API is identical to the one dumped using :cpp:func:`heap_caps_print_all_task_stat`.
330
+
331
+
Each getter function requires a pointer to the data structure that will be used by the heap task tracking to gather the statistics and information of a given task (or all tasks). This data structure contains pointers to arrays that the user can allocate statically or dynamically.
332
+
333
+
Due to the difficulty of estimating the size of the arrays used to store information — since it's hard to determine the number of allocations per task, the number of heaps used by each task, and the number of tasks created since startup — the heap task tracking also provides :cpp:func:`heap_caps_alloc_single_task_stat_arrays` (resp. :cpp:func:`heap_caps_alloc_all_task_stat_arrays`) to dynamically allocate the required amount of memory for those arrays.
334
+
335
+
Similarly, the heap task tracking also provides :cpp:func:`heap_caps_free_single_task_stat_arrays` (resp. :cpp:func:`heap_caps_free_all_task_stat_arrays`) to free the memory dynamically allocated when calling :cpp:func:`heap_caps_alloc_single_task_stat_arrays` (resp. :cpp:func:`heap_caps_alloc_all_task_stat_arrays`).
336
+
337
+
.. note::
338
+
Detailed use of the API functions described in this section can be found in :example:`system/heap_task_tracking/advanced`.
207
339
208
340
.. _heap-tracing:
209
341
@@ -632,6 +764,11 @@ Application Examples
632
764
- :example:`system/heap_task_tracking/basic` demonstrates the use of the overview feature of the heap task tracking, dumping per-task summary statistics on heap memory usage.
633
765
- :example:`system/heap_task_tracking/advanced` demonstrates the use of the statistics getter functions of the heap task tracking, accessing per-task complete statistic on the heap memory usage.
0 commit comments