From ddedc155d498c9201e0b7995dd3ccdb29c4ddcc1 Mon Sep 17 00:00:00 2001 From: Brian Daniels Date: Thu, 11 Oct 2018 17:39:49 -0500 Subject: [PATCH 1/2] Updating stats doc comments --- platform/mbed_stats.h | 68 ++++++++++++++++++++++--------------------- 1 file changed, 35 insertions(+), 33 deletions(-) diff --git a/platform/mbed_stats.h b/platform/mbed_stats.h index 415be895c2..d502bc4d37 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) */ - mbed_compiler_id_t compiler_id; /**< Compiler ID \ref mbed_compiler_id_t */ + 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 */ From 82c4ce607dfd759a821d4c4b86a923ac4bc0f45b Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Fri, 12 Oct 2018 11:08:01 -0500 Subject: [PATCH 2/2] Edit mbed_stats.h Capitalize ID for consistency. --- platform/mbed_stats.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform/mbed_stats.h b/platform/mbed_stats.h index d502bc4d37..aa7b581976 100644 --- a/platform/mbed_stats.h +++ b/platform/mbed_stats.h @@ -108,7 +108,7 @@ void mbed_stats_cpu_get(mbed_stats_cpu_t *stats); * struct mbed_stats_thread_t definition */ typedef struct { - uint32_t id; /**< Id of the thread */ + 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 */ @@ -142,7 +142,7 @@ typedef enum { typedef struct { 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 */ + mbed_compiler_id_t compiler_id; /**< Compiler ID \ref mbed_compiler_id_t */ uint32_t compiler_version; /**< Compiler version */ } mbed_stats_sys_t;