1 // Copyright 2018 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 #pragma once 15 16 #ifdef CONFIG_HEAP_TASK_TRACKING 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 // This macro controls how much space is provided for partitioning the per-task 23 // heap allocation info according to one or more sets of heap capabilities. 24 #define NUM_HEAP_TASK_CAPS 4 25 26 /** @brief Structure to collect per-task heap allocation totals partitioned by selected caps */ 27 typedef struct { 28 TaskHandle_t task; ///< Task to which these totals belong 29 size_t size[NUM_HEAP_TASK_CAPS]; ///< Total allocations partitioned by selected caps 30 size_t count[NUM_HEAP_TASK_CAPS]; ///< Number of blocks partitioned by selected caps 31 } heap_task_totals_t; 32 33 /** @brief Structure providing details about a block allocated by a task */ 34 typedef struct { 35 TaskHandle_t task; ///< Task that allocated the block 36 void *address; ///< User address of allocated block 37 uint32_t size; ///< Size of the allocated block 38 } heap_task_block_t; 39 40 /** @brief Structure to provide parameters to heap_caps_get_per_task_info 41 * 42 * The 'caps' and 'mask' arrays allow partitioning the per-task heap allocation 43 * totals by selected sets of heap region capabilities so that totals for 44 * multiple regions can be accumulated in one scan. The capabilities flags for 45 * each region ANDed with mask[i] are compared to caps[i] in order; the 46 * allocations in that region are added to totals->size[i] and totals->count[i] 47 * for the first i that matches. To collect the totals without any 48 * partitioning, set mask[0] and caps[0] both to zero. The allocation totals 49 * are returned in the 'totals' array of heap_task_totals_t structs. To allow 50 * easily comparing the totals array between consecutive calls, that array can 51 * be left populated from one call to the next so the order of tasks is the 52 * same even if some tasks have freed their blocks or have been deleted. The 53 * number of blocks prepopulated is given by num_totals, which is updated upon 54 * return. If there are more tasks with allocations than the capacity of the 55 * totals array (given by max_totals), information for the excess tasks will be 56 * not be collected. The totals array pointer can be NULL if the totals are 57 * not desired. 58 * 59 * The 'tasks' array holds a list of handles for tasks whose block details are 60 * to be returned in the 'blocks' array of heap_task_block_t structs. If the 61 * tasks array pointer is NULL, block details for all tasks will be returned up 62 * to the capacity of the buffer array, given by max_blocks. The function 63 * return value tells the number of blocks filled into the array. The blocks 64 * array pointer can be NULL if block details are not desired, or max_blocks 65 * can be set to zero. 66 */ 67 typedef struct { 68 int32_t caps[NUM_HEAP_TASK_CAPS]; ///< Array of caps for partitioning task totals 69 int32_t mask[NUM_HEAP_TASK_CAPS]; ///< Array of masks under which caps must match 70 TaskHandle_t *tasks; ///< Array of tasks whose block info is returned 71 size_t num_tasks; ///< Length of tasks array 72 heap_task_totals_t *totals; ///< Array of structs to collect task totals 73 size_t *num_totals; ///< Number of task structs currently in array 74 size_t max_totals; ///< Capacity of array of task totals structs 75 heap_task_block_t *blocks; ///< Array of task block details structs 76 size_t max_blocks; ///< Capacity of array of task block info structs 77 } heap_task_info_params_t; 78 79 /** 80 * @brief Return per-task heap allocation totals and lists of blocks. 81 * 82 * For each task that has allocated memory from the heap, return totals for 83 * allocations within regions matching one or more sets of capabilities. 84 * 85 * Optionally also return an array of structs providing details about each 86 * block allocated by one or more requested tasks, or by all tasks. 87 * 88 * @param params Structure to hold all the parameters for the function 89 * (@see heap_task_info_params_t). 90 * @return Number of block detail structs returned (@see heap_task_block_t). 91 */ 92 extern size_t heap_caps_get_per_task_info(heap_task_info_params_t *params); 93 94 #ifdef __cplusplus 95 } 96 #endif 97 98 #endif // CONFIG_HEAP_TASK_TRACKING 99
