diff --git a/platform/mbed_stats.h b/platform/mbed_stats.h index 415be895c2..aa7b581976 100644 --- a/platform/mbed_stats.h +++ b/platform/mbed_stats.h @@ -42,17 +42,17 @@ extern "C" { * struct mbed_stats_heap_t definition */ typedef struct { - uint32_t current_size; /**< Bytes allocated currently. */ - uint32_t max_size; /**< Max bytes allocated at a given time. */ - uint32_t total_size; /**< Cumulative sum of bytes ever allocated. */ - uint32_t reserved_size; /**< Current number of bytes allocated for the heap. */ - uint32_t alloc_cnt; /**< Current number of allocations. */ - uint32_t alloc_fail_cnt; /**< Number of failed allocations. */ - uint32_t overhead_size; /**< Overhead added to heap for stats. */ + uint32_t current_size; /**< Bytes currently allocated on the heap */ + uint32_t max_size; /**< Maximum bytes allocated on the heap at one time since reset */ + uint32_t total_size; /**< Cumulative sum of bytes allocated on the heap that have not been freed */ + uint32_t reserved_size; /**< Current number of bytes reserved for the heap */ + uint32_t alloc_cnt; /**< Current number of allocations that have not been freed since reset */ + uint32_t alloc_fail_cnt; /**< Number of failed allocations since reset */ + 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 */ } mbed_stats_heap_t; /** - * Fill the passed in heap stat structure with heap stats. + * Fill the passed in heap stat structure with the heap statistics. * * @param stats A pointer to the mbed_stats_heap_t structure to fill */ @@ -62,14 +62,14 @@ void mbed_stats_heap_get(mbed_stats_heap_t *stats); * struct mbed_stats_stack_t definition */ typedef struct { - uint32_t thread_id; /**< Identifier for thread that owns the stack or 0 if multiple threads. */ - uint32_t max_size; /**< Maximum number of bytes used on the stack. */ - uint32_t reserved_size; /**< Current number of bytes allocated for the stack. */ - uint32_t stack_cnt; /**< Number of stacks stats accumulated in the structure. */ + uint32_t thread_id; /**< Identifier for the thread that owns the stack or 0 if representing accumulated statistics */ + uint32_t max_size; /**< Maximum number of bytes used on the stack since the thread was started */ + uint32_t reserved_size; /**< Current number of bytes reserved for the stack */ + uint32_t stack_cnt; /**< The number of stacks represented in the accumulated statistics or 1 if repesenting a single stack */ } mbed_stats_stack_t; /** - * Fill the passed in structure with stack stats accumulated for all threads. The thread_id will be 0 + * Fill the passed in structure with stack statistics accumulated for all threads. The thread_id will be 0 * and stack_cnt will represent number of threads. * * @param stats A pointer to the mbed_stats_stack_t structure to fill @@ -77,12 +77,13 @@ typedef struct { void mbed_stats_stack_get(mbed_stats_stack_t *stats); /** - * Fill the passed array of stat structures with the stack stats for each available thread. + * Fill the passed array of structures with the stack statistics for each available thread. * * @param stats A pointer to an array of mbed_stats_stack_t structures to fill * @param count The number of mbed_stats_stack_t structures in the provided array - * @return The number of mbed_stats_stack_t structures that have been filled, - * this is equal to the number of stacks on the system. + * @return The number of mbed_stats_stack_t structures that have been filled. + * 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. + * If the number of stacks on the system is greater than count, it will equal count. */ size_t mbed_stats_stack_get_each(mbed_stats_stack_t *stats, size_t count); @@ -90,10 +91,10 @@ size_t mbed_stats_stack_get_each(mbed_stats_stack_t *stats, size_t count); * struct mbed_stats_cpu_t definition */ typedef struct { - us_timestamp_t uptime; /**< Time since system is up and running */ - us_timestamp_t idle_time; /**< Time spent in idle thread since system is up and running */ - us_timestamp_t sleep_time; /**< Time spent in sleep since system is up and running */ - us_timestamp_t deep_sleep_time; /**< Time spent in deep sleep since system is up and running */ + us_timestamp_t uptime; /**< Time since the system has started */ + us_timestamp_t idle_time; /**< Time spent in the idle thread since the system has started */ + us_timestamp_t sleep_time; /**< Time spent in sleep since the system has started */ + us_timestamp_t deep_sleep_time; /**< Time spent in deep sleep since the system has started */ } mbed_stats_cpu_t; /** @@ -107,21 +108,22 @@ void mbed_stats_cpu_get(mbed_stats_cpu_t *stats); * struct mbed_stats_thread_t definition */ typedef struct { - uint32_t id; /**< Thread Object Identifier */ - uint32_t state; /**< Thread Object State */ - uint32_t priority; /**< Thread Priority */ - uint32_t stack_size; /**< Thread Stack Size */ - uint32_t stack_space; /**< Thread remaining stack size */ - const char *name; /**< Thread Object name */ + uint32_t id; /**< ID of the thread */ + uint32_t state; /**< State of the thread */ + uint32_t priority; /**< Priority of the thread (higher number indicates higher priority) */ + uint32_t stack_size; /**< Current number of bytes reserved for the stack */ + uint32_t stack_space; /**< Current number of free bytes remaining on the stack */ + const char *name; /**< Name of the thread */ } mbed_stats_thread_t; /** - * Fill the passed array of stat structures with the thread stats for each available thread. + * Fill the passed array of stat structures with the thread statistics for each available thread. * * @param stats A pointer to an array of mbed_stats_thread_t structures to fill * @param count The number of mbed_stats_thread_t structures in the provided array - * @return The number of mbed_stats_thread_t structures that have been filled, - * this is equal to the number of threads on the system. + * @return The number of mbed_stats_thread_t structures that have been filled. + * 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. + * If the number of threads on the system is greater than count, it will equal count. */ size_t mbed_stats_thread_get_each(mbed_stats_thread_t *stats, size_t count); @@ -138,14 +140,14 @@ typedef enum { * struct mbed_stats_sys_t definition */ typedef struct { - uint32_t os_version; /**< Mbed OS Version (Release only) */ - uint32_t cpu_id; /**< CPUID Register data (Cortex-M only supported) */ + uint32_t os_version; /**< Mbed OS version (populated only for tagged releases) */ + uint32_t cpu_id; /**< CPUID register data (Cortex-M only supported) */ mbed_compiler_id_t compiler_id; /**< Compiler ID \ref mbed_compiler_id_t */ uint32_t compiler_version; /**< Compiler version */ } mbed_stats_sys_t; /** - * Fill the passed in sys stat structure with system stats. + * Fill the passed in system stat structure with system statistics. * * @param stats A pointer to the mbed_stats_sys_t structure to fill */