esp-idf/components/heap/include/esp_heap_task_info.h

97 lines
4.4 KiB
C
Raw Normal View History

/*
* SPDX-FileCopyrightText: 2018-2022 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
heap: Add task tracking option for heap usage monitoring Add back a feature that was available in the old heap implementation in release/v2.1 and earlier: keep track of which task allocates each block from the heap. The task handle is conditionally added as another word in the heap poisoning header under this configuration option CONFIG_HEAP_TASK_TRACKING. To allow custom monitoring and debugging code to be added, add helper functions in multi_heap.c and multi_heap_poisoning.c to provide access to information in the block headers. Add esp_heap_debug_dump_totals() to monitor heap usage esp_heap_debug_dump_totals() dumps into a user-provided data structure a summary of the amound of heap memory in region type that is used by each task. Optionally it will also dump into another data structure the metadata about each allocated block for a given list of tasks or for all tasks (limited by available space). Address change requests on PR #1498 This set of changes fixes the files in e3b702c to just add the CONFIG_HEAP_TASK_TRACKING option without adding the new function heap_caps_get_per_task_info() in case that is the only portion of the PR that will be accepted. Part of the change is to remove the new .c and .h files containing that function and to remove the line to compile it from components/heap/component.mk since it should not have been included in e3b702c. One or more additional commits to add the new function will follow. The other changes here: - uint32_t get_all_caps() moves to heap_private.h - replace "void* foo" with "void *foo" - add braces around single-line "if" blocks - replace tab characters with spaces Address change requests on PR #1498, part 2 This set of changes fixes the files in cdf32aa to add the new function heap_caps_get_per_task_info() with its new name and to add the line to compile it in components/heap/component.mk. This does not address all the suggested changes because there are some needing further discussion. This commit does not include the suggested change to move the declaration of the new function into esp_heap_caps.h because the new function references TaskHandle_t so esp_heap_caps.h would have to include freertos/FreeRTOS.h and freertos/task.h, but FreeRTOS.h includes esp_heap_caps.h through two other header files which results in compilation errors because not all of FreeRTOS.h has been read yet. Change heap_caps_get_per_task_info() to take struct of params In addition to moving the large number of function parameters into a struct as the single parameter, the following changes were made: - Clear out the totals for any prepopulated tasks so the app code doesn't have to do it. - Rather than partitioning the per-task totals into a predetermined set of heap capabilities, take a list of <caps,mask> pairs to compare the caps to the heap capabilities as masked. This lets the caller configure the desired partitioning, or none. - Allow the totals array pointer or the blocks array pointer to be NULL to indicate not to collect that part of the information. - In addition to returning the total space allocated by each task, return the number of blocks allocated by each task. - Don't need to return the heap capabilities as part of the details for each block since the heap region (and therefore its capabilities) can be determined from the block address. - Renamed heap_task_info.h to esp_heap_task_info.h to fit the naming convention, and renamed the structs for totals and block details to better fit the revised function name. - Provide full Doxygen commenting for the function and parameter structs. Add copyright header to new files Merges https://github.com/espressif/esp-idf/pull/1498
2018-01-10 04:14:47 -05:00
#pragma once
#include "sdkconfig.h"
heap: Add task tracking option for heap usage monitoring Add back a feature that was available in the old heap implementation in release/v2.1 and earlier: keep track of which task allocates each block from the heap. The task handle is conditionally added as another word in the heap poisoning header under this configuration option CONFIG_HEAP_TASK_TRACKING. To allow custom monitoring and debugging code to be added, add helper functions in multi_heap.c and multi_heap_poisoning.c to provide access to information in the block headers. Add esp_heap_debug_dump_totals() to monitor heap usage esp_heap_debug_dump_totals() dumps into a user-provided data structure a summary of the amound of heap memory in region type that is used by each task. Optionally it will also dump into another data structure the metadata about each allocated block for a given list of tasks or for all tasks (limited by available space). Address change requests on PR #1498 This set of changes fixes the files in e3b702c to just add the CONFIG_HEAP_TASK_TRACKING option without adding the new function heap_caps_get_per_task_info() in case that is the only portion of the PR that will be accepted. Part of the change is to remove the new .c and .h files containing that function and to remove the line to compile it from components/heap/component.mk since it should not have been included in e3b702c. One or more additional commits to add the new function will follow. The other changes here: - uint32_t get_all_caps() moves to heap_private.h - replace "void* foo" with "void *foo" - add braces around single-line "if" blocks - replace tab characters with spaces Address change requests on PR #1498, part 2 This set of changes fixes the files in cdf32aa to add the new function heap_caps_get_per_task_info() with its new name and to add the line to compile it in components/heap/component.mk. This does not address all the suggested changes because there are some needing further discussion. This commit does not include the suggested change to move the declaration of the new function into esp_heap_caps.h because the new function references TaskHandle_t so esp_heap_caps.h would have to include freertos/FreeRTOS.h and freertos/task.h, but FreeRTOS.h includes esp_heap_caps.h through two other header files which results in compilation errors because not all of FreeRTOS.h has been read yet. Change heap_caps_get_per_task_info() to take struct of params In addition to moving the large number of function parameters into a struct as the single parameter, the following changes were made: - Clear out the totals for any prepopulated tasks so the app code doesn't have to do it. - Rather than partitioning the per-task totals into a predetermined set of heap capabilities, take a list of <caps,mask> pairs to compare the caps to the heap capabilities as masked. This lets the caller configure the desired partitioning, or none. - Allow the totals array pointer or the blocks array pointer to be NULL to indicate not to collect that part of the information. - In addition to returning the total space allocated by each task, return the number of blocks allocated by each task. - Don't need to return the heap capabilities as part of the details for each block since the heap region (and therefore its capabilities) can be determined from the block address. - Renamed heap_task_info.h to esp_heap_task_info.h to fit the naming convention, and renamed the structs for totals and block details to better fit the revised function name. - Provide full Doxygen commenting for the function and parameter structs. Add copyright header to new files Merges https://github.com/espressif/esp-idf/pull/1498
2018-01-10 04:14:47 -05:00
#ifdef CONFIG_HEAP_TASK_TRACKING
#include <stdint.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
heap: Add task tracking option for heap usage monitoring Add back a feature that was available in the old heap implementation in release/v2.1 and earlier: keep track of which task allocates each block from the heap. The task handle is conditionally added as another word in the heap poisoning header under this configuration option CONFIG_HEAP_TASK_TRACKING. To allow custom monitoring and debugging code to be added, add helper functions in multi_heap.c and multi_heap_poisoning.c to provide access to information in the block headers. Add esp_heap_debug_dump_totals() to monitor heap usage esp_heap_debug_dump_totals() dumps into a user-provided data structure a summary of the amound of heap memory in region type that is used by each task. Optionally it will also dump into another data structure the metadata about each allocated block for a given list of tasks or for all tasks (limited by available space). Address change requests on PR #1498 This set of changes fixes the files in e3b702c to just add the CONFIG_HEAP_TASK_TRACKING option without adding the new function heap_caps_get_per_task_info() in case that is the only portion of the PR that will be accepted. Part of the change is to remove the new .c and .h files containing that function and to remove the line to compile it from components/heap/component.mk since it should not have been included in e3b702c. One or more additional commits to add the new function will follow. The other changes here: - uint32_t get_all_caps() moves to heap_private.h - replace "void* foo" with "void *foo" - add braces around single-line "if" blocks - replace tab characters with spaces Address change requests on PR #1498, part 2 This set of changes fixes the files in cdf32aa to add the new function heap_caps_get_per_task_info() with its new name and to add the line to compile it in components/heap/component.mk. This does not address all the suggested changes because there are some needing further discussion. This commit does not include the suggested change to move the declaration of the new function into esp_heap_caps.h because the new function references TaskHandle_t so esp_heap_caps.h would have to include freertos/FreeRTOS.h and freertos/task.h, but FreeRTOS.h includes esp_heap_caps.h through two other header files which results in compilation errors because not all of FreeRTOS.h has been read yet. Change heap_caps_get_per_task_info() to take struct of params In addition to moving the large number of function parameters into a struct as the single parameter, the following changes were made: - Clear out the totals for any prepopulated tasks so the app code doesn't have to do it. - Rather than partitioning the per-task totals into a predetermined set of heap capabilities, take a list of <caps,mask> pairs to compare the caps to the heap capabilities as masked. This lets the caller configure the desired partitioning, or none. - Allow the totals array pointer or the blocks array pointer to be NULL to indicate not to collect that part of the information. - In addition to returning the total space allocated by each task, return the number of blocks allocated by each task. - Don't need to return the heap capabilities as part of the details for each block since the heap region (and therefore its capabilities) can be determined from the block address. - Renamed heap_task_info.h to esp_heap_task_info.h to fit the naming convention, and renamed the structs for totals and block details to better fit the revised function name. - Provide full Doxygen commenting for the function and parameter structs. Add copyright header to new files Merges https://github.com/espressif/esp-idf/pull/1498
2018-01-10 04:14:47 -05:00
#ifdef __cplusplus
extern "C" {
#endif
// This macro controls how much space is provided for partitioning the per-task
// heap allocation info according to one or more sets of heap capabilities.
#define NUM_HEAP_TASK_CAPS 4
/** @brief Structure to collect per-task heap allocation totals partitioned by selected caps */
typedef struct {
TaskHandle_t task; ///< Task to which these totals belong
size_t size[NUM_HEAP_TASK_CAPS]; ///< Total allocations partitioned by selected caps
size_t count[NUM_HEAP_TASK_CAPS]; ///< Number of blocks partitioned by selected caps
} heap_task_totals_t;
/** @brief Structure providing details about a block allocated by a task */
typedef struct {
TaskHandle_t task; ///< Task that allocated the block
void *address; ///< User address of allocated block
uint32_t size; ///< Size of the allocated block
} heap_task_block_t;
/** @brief Structure to provide parameters to heap_caps_get_per_task_info
*
* The 'caps' and 'mask' arrays allow partitioning the per-task heap allocation
* totals by selected sets of heap region capabilities so that totals for
* multiple regions can be accumulated in one scan. The capabilities flags for
* each region ANDed with mask[i] are compared to caps[i] in order; the
* allocations in that region are added to totals->size[i] and totals->count[i]
* for the first i that matches. To collect the totals without any
* partitioning, set mask[0] and caps[0] both to zero. The allocation totals
* are returned in the 'totals' array of heap_task_totals_t structs. To allow
* easily comparing the totals array between consecutive calls, that array can
* be left populated from one call to the next so the order of tasks is the
* same even if some tasks have freed their blocks or have been deleted. The
* number of blocks prepopulated is given by num_totals, which is updated upon
* return. If there are more tasks with allocations than the capacity of the
* totals array (given by max_totals), information for the excess tasks will be
* not be collected. The totals array pointer can be NULL if the totals are
* not desired.
*
* The 'tasks' array holds a list of handles for tasks whose block details are
* to be returned in the 'blocks' array of heap_task_block_t structs. If the
* tasks array pointer is NULL, block details for all tasks will be returned up
* to the capacity of the buffer array, given by max_blocks. The function
* return value tells the number of blocks filled into the array. The blocks
* array pointer can be NULL if block details are not desired, or max_blocks
* can be set to zero.
*/
typedef struct {
int32_t caps[NUM_HEAP_TASK_CAPS]; ///< Array of caps for partitioning task totals
int32_t mask[NUM_HEAP_TASK_CAPS]; ///< Array of masks under which caps must match
TaskHandle_t *tasks; ///< Array of tasks whose block info is returned
size_t num_tasks; ///< Length of tasks array
heap_task_totals_t *totals; ///< Array of structs to collect task totals
size_t *num_totals; ///< Number of task structs currently in array
size_t max_totals; ///< Capacity of array of task totals structs
heap_task_block_t *blocks; ///< Array of task block details structs
size_t max_blocks; ///< Capacity of array of task block info structs
} heap_task_info_params_t;
/**
* @brief Return per-task heap allocation totals and lists of blocks.
*
* For each task that has allocated memory from the heap, return totals for
* allocations within regions matching one or more sets of capabilities.
*
* Optionally also return an array of structs providing details about each
* block allocated by one or more requested tasks, or by all tasks.
*
* @param params Structure to hold all the parameters for the function
* (@see heap_task_info_params_t).
* @return Number of block detail structs returned (@see heap_task_block_t).
*/
extern size_t heap_caps_get_per_task_info(heap_task_info_params_t *params);
#ifdef __cplusplus
}
#endif
#endif // CONFIG_HEAP_TASK_TRACKING