// Copyright 2018 Espressif Systems (Shanghai) PTE LTD
|
//
|
// 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.
|
#pragma once
|
|
#ifdef CONFIG_HEAP_TASK_TRACKING
|
|
#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
|
