Mbed OS Reference
Loading...
Searching...
No Matches
mbed_stats.h
1/* mbed Microcontroller Library
2 * Copyright (c) 2016-2019 ARM Limited
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17#ifndef MBED_STATS_H
18#define MBED_STATS_H
19#include <stdint.h>
20#include <stddef.h>
21#include "hal/ticker_api.h"
22
23#ifdef __cplusplus
24extern "C" {
25#endif
26
27/** \addtogroup platform-public-api */
28/** @{*/
29
30/**
31 * \defgroup platform_stats stats functions
32 * @{
33 */
34
35#ifdef MBED_ALL_STATS_ENABLED
36
37#ifndef MBED_SYS_STATS_ENABLED
38#define MBED_SYS_STATS_ENABLED 1
39#endif
40#ifndef MBED_STACK_STATS_ENABLED
41#define MBED_STACK_STATS_ENABLED 1
42#endif
43#ifndef MBED_CPU_STATS_ENABLED
44#define MBED_CPU_STATS_ENABLED 1
45#endif
46#ifndef MBED_HEAP_STATS_ENABLED
47#define MBED_HEAP_STATS_ENABLED 1
48#endif
49#ifndef MBED_THREAD_STATS_ENABLED
50#define MBED_THREAD_STATS_ENABLED 1
51#endif
52
53#endif // MBED_ALL_STATS_ENABLED
54
55/** Maximum memory regions reported by mbed-os memory statistics */
56#define MBED_MAX_MEM_REGIONS 4
57
58/**
59 * struct mbed_stats_heap_t definition
60 */
61typedef struct {
62 uint32_t current_size; /**< Bytes currently allocated on the heap */
63 uint32_t max_size; /**< Maximum bytes allocated on the heap at one time since reset */
64 uint32_t total_size; /**< Cumulative sum of bytes allocated on the heap that have not been freed */
65 uint32_t reserved_size; /**< Current number of bytes reserved for the heap */
66 uint32_t alloc_cnt; /**< Current number of allocations that have not been freed since reset */
67 uint32_t alloc_fail_cnt; /**< Number of failed allocations since reset */
68 uint32_t overhead_size; /**< Number of bytes used to store heap statistics. This overhead takes up space on the heap, reducing the available heap space */
70
71/**
72 * Fill the passed in heap stat structure with the heap statistics.
73 *
74 * @param stats A pointer to the mbed_stats_heap_t structure to fill
75 */
77
78/**
79 * struct mbed_stats_stack_t definition
80 */
81typedef struct {
82 uint32_t thread_id; /**< Identifier for the thread that owns the stack or 0 if representing accumulated statistics */
83 uint32_t max_size; /**< Maximum number of bytes used on the stack since the thread was started */
84 uint32_t reserved_size; /**< Current number of bytes reserved for the stack */
85 uint32_t stack_cnt; /**< The number of stacks represented in the accumulated statistics or 1 if representing a single stack */
87
88/**
89 * Fill the passed in structure with stack statistics accumulated for all threads. The thread_id will be 0
90 * and stack_cnt will represent number of threads.
91 *
92 * @param stats A pointer to the mbed_stats_stack_t structure to fill
93 */
95
96/**
97 * Fill the passed array of structures with the stack statistics for each available thread.
98 *
99 * @param stats A pointer to an array of mbed_stats_stack_t structures to fill
100 * @param count The number of mbed_stats_stack_t structures in the provided array
101 * @return The number of mbed_stats_stack_t structures that have been filled.
102 * If the number of stacks on the system is less than or equal to count, it will equal the number of stacks on the system.
103 * If the number of stacks on the system is greater than count, it will equal count.
104 */
106
107/**
108 * struct mbed_stats_cpu_t definition
109 */
110typedef struct {
111 us_timestamp_t uptime; /**< Time since the system has started */
112 us_timestamp_t idle_time; /**< Time spent in the idle thread since the system has started */
113 us_timestamp_t sleep_time; /**< Time spent in sleep since the system has started */
114 us_timestamp_t deep_sleep_time; /**< Time spent in deep sleep since the system has started */
116
117/**
118 * Fill the passed in CPU stat structure with CPU statistics.
119 *
120 * @param stats A pointer to the mbed_stats_cpu_t structure to fill
121 */
123
124/**
125 * struct mbed_stats_thread_t definition
126 */
127typedef struct {
128 uint32_t id; /**< ID of the thread */
129 uint32_t state; /**< State of the thread */
130 uint32_t priority; /**< Priority of the thread (higher number indicates higher priority) */
131 uint32_t stack_size; /**< Current number of bytes reserved for the stack */
132 uint32_t stack_space; /**< Current number of free bytes remaining on the stack */
133 const char *name; /**< Name of the thread */
135
136/**
137 * Fill the passed array of stat structures with the thread statistics for each available thread.
138 *
139 * @param stats A pointer to an array of mbed_stats_thread_t structures to fill
140 * @param count The number of mbed_stats_thread_t structures in the provided array
141 * @return The number of mbed_stats_thread_t structures that have been filled.
142 * If the number of threads on the system is less than or equal to count, it will equal the number of threads on the system.
143 * If the number of threads on the system is greater than count, it will equal count.
144 */
146
147/**
148 * enum mbed_compiler_id_t definition
149 */
150typedef enum {
151 ARM = 1, /**< ARM */
152 GCC_ARM, /**< GNU ARM */
153 IAR /**< IAR */
155
156/**
157 * struct mbed_stats_sys_t definition
158 */
159typedef struct {
160 uint32_t os_version; /**< Mbed OS version (populated only for tagged releases) */
161 uint32_t cpu_id; /**< CPUID register data (Cortex-M only supported) */
162 mbed_compiler_id_t compiler_id; /**< Compiler ID \ref mbed_compiler_id_t */
163 uint32_t compiler_version; /**< Compiler version */
164 uint32_t ram_start[MBED_MAX_MEM_REGIONS]; /**< Configured start addresses of all internal RAM memories */
165 uint32_t ram_size[MBED_MAX_MEM_REGIONS]; /**< Configured sizes of all internal RAM memories in target */
166 uint32_t rom_start[MBED_MAX_MEM_REGIONS]; /**< Configured start addresses of all internal ROM memories */
167 uint32_t rom_size[MBED_MAX_MEM_REGIONS]; /**< Configured sizes of all internal ROM memories in target */
169
170/**
171 * Fill the passed in system stat structure with system statistics.
172 *
173 * @param stats A pointer to the mbed_stats_sys_t structure to fill
174 */
176
177#ifdef __cplusplus
178}
179#endif
180
181#endif
182
183/** @}*/
184
185/** @}*/
uint64_t us_timestamp_t
A us timestamp stored in a 64 bit integer.
Definition: ticker_api.h:39
size_t mbed_stats_stack_get_each(mbed_stats_stack_t *stats, size_t count)
Fill the passed array of structures with the stack statistics for each available thread.
void mbed_stats_heap_get(mbed_stats_heap_t *stats)
Fill the passed in heap stat structure with the heap statistics.
void mbed_stats_sys_get(mbed_stats_sys_t *stats)
Fill the passed in system stat structure with system statistics.
void mbed_stats_cpu_get(mbed_stats_cpu_t *stats)
Fill the passed in CPU stat structure with CPU statistics.
void mbed_stats_stack_get(mbed_stats_stack_t *stats)
Fill the passed in structure with stack statistics accumulated for all threads.
mbed_compiler_id_t
enum mbed_compiler_id_t definition
Definition: mbed_stats.h:150
#define MBED_MAX_MEM_REGIONS
Maximum memory regions reported by mbed-os memory statistics.
Definition: mbed_stats.h:56
size_t mbed_stats_thread_get_each(mbed_stats_thread_t *stats, size_t count)
Fill the passed array of stat structures with the thread statistics for each available thread.
@ ARM
ARM.
Definition: mbed_stats.h:151
@ IAR
IAR.
Definition: mbed_stats.h:153
@ GCC_ARM
GNU ARM.
Definition: mbed_stats.h:152
struct mbed_stats_cpu_t definition
Definition: mbed_stats.h:110
us_timestamp_t sleep_time
Time spent in sleep since the system has started.
Definition: mbed_stats.h:113
us_timestamp_t uptime
Time since the system has started.
Definition: mbed_stats.h:111
us_timestamp_t deep_sleep_time
Time spent in deep sleep since the system has started.
Definition: mbed_stats.h:114
us_timestamp_t idle_time
Time spent in the idle thread since the system has started.
Definition: mbed_stats.h:112
struct mbed_stats_heap_t definition
Definition: mbed_stats.h:61
uint32_t alloc_fail_cnt
Number of failed allocations since reset.
Definition: mbed_stats.h:67
uint32_t max_size
Maximum bytes allocated on the heap at one time since reset.
Definition: mbed_stats.h:63
uint32_t alloc_cnt
Current number of allocations that have not been freed since reset.
Definition: mbed_stats.h:66
uint32_t current_size
Bytes currently allocated on the heap.
Definition: mbed_stats.h:62
uint32_t overhead_size
Number of bytes used to store heap statistics.
Definition: mbed_stats.h:68
uint32_t total_size
Cumulative sum of bytes allocated on the heap that have not been freed.
Definition: mbed_stats.h:64
uint32_t reserved_size
Current number of bytes reserved for the heap.
Definition: mbed_stats.h:65
struct mbed_stats_stack_t definition
Definition: mbed_stats.h:81
uint32_t max_size
Maximum number of bytes used on the stack since the thread was started.
Definition: mbed_stats.h:83
uint32_t thread_id
Identifier for the thread that owns the stack or 0 if representing accumulated statistics.
Definition: mbed_stats.h:82
uint32_t stack_cnt
The number of stacks represented in the accumulated statistics or 1 if representing a single stack.
Definition: mbed_stats.h:85
uint32_t reserved_size
Current number of bytes reserved for the stack.
Definition: mbed_stats.h:84
struct mbed_stats_sys_t definition
Definition: mbed_stats.h:159
mbed_compiler_id_t compiler_id
Compiler ID mbed_compiler_id_t.
Definition: mbed_stats.h:162
uint32_t compiler_version
Compiler version.
Definition: mbed_stats.h:163
uint32_t cpu_id
CPUID register data (Cortex-M only supported)
Definition: mbed_stats.h:161
uint32_t os_version
Mbed OS version (populated only for tagged releases)
Definition: mbed_stats.h:160
struct mbed_stats_thread_t definition
Definition: mbed_stats.h:127
uint32_t stack_space
Current number of free bytes remaining on the stack.
Definition: mbed_stats.h:132
uint32_t state
State of the thread.
Definition: mbed_stats.h:129
const char * name
Name of the thread.
Definition: mbed_stats.h:133
uint32_t priority
Priority of the thread (higher number indicates higher priority)
Definition: mbed_stats.h:130
uint32_t id
ID of the thread.
Definition: mbed_stats.h:128
uint32_t stack_size
Current number of bytes reserved for the stack.
Definition: mbed_stats.h:131