telemetry2_thread_info.c: Review updates

Author: Jyri Sarha

src/debug/telemetry/telemetry2_thread_info.c

@@ -1,6 +1,6 @@
-/* SPDX-License-Identifier: Apache-2.0
- * Copyright (c) 2024 Intel Corporation
- */
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// Copyright(c) 2024 Intel Corporation.
 
 #include <zephyr/logging/log.h>
 #include <zephyr/kernel.h>
@@ -12,13 +12,12 @@
 
 LOG_MODULE_REGISTER(thread_info);
 
-/* to adsp backend header, data to be shared with user space client*/
 #define THREAD_INFO_MAX_THREADS 16
 
 struct thread_info {
 	char name[14];
-	uint8_t stack_usage;	/* precentage */
-	uint8_t cpu_usage;	/* precentage */
+	uint8_t stack_usage;	/* Relative stack usage U(0,8) fixed point value */
+	uint8_t cpu_usage;	/* Relative cpu usage U(0,8) fixed point value */
 } __packed;
 
 #define THREAD_INFO_VERSION_0_0		0
@@ -27,14 +26,19 @@ struct thread_info {
 #define THREAD_INFO_STATE_BEING_UPDATED	1
 #define THREAD_INFO_STATE_UPTODATE	2
 
+/* Core specific data, updated each round, including the thread table. */
 struct thread_info_core {
-	uint8_t state;
-	uint8_t counter;		/* incremented every round */
-	uint8_t load;			/* precentage */
+	uint8_t state;		/* indicates if core data is in consistent state */
+	uint8_t counter;	/* incremented every round */
+	uint8_t load;		/* Core's load U(0,8) fixed point value */
 	uint8_t thread_count;
 	struct thread_info thread[THREAD_INFO_MAX_THREADS];
 } __packed __aligned(CONFIG_DCACHE_LINE_SIZE);
 
+/* Thread info telemetry2 chunk header. Only initialized at first
+ * thread info thread start. Should be used to find the core specific
+ * sections where the thread info is when decoding.
+ */
 struct thread_info_chunk {
 	struct telemetry2_chunk_hdr hdr;
 	uint16_t core_count;
@@ -43,6 +47,10 @@ struct thread_info_chunk {
 } __packed;
 
 #ifdef CONFIG_THREAD_RUNTIME_STATS
+/* Data structure to store the cycle counter values from the previous
+ * round. The numbers are used to calculate what the load was on this
+ * round.
+ */
 static struct previous_counters { // Cached data from previous round
 	uint64_t active;	  // All execution cycles
 	uint64_t all;		  // All cycles including idle
@@ -53,6 +61,9 @@ static struct previous_counters { // Cached data from previous round
 } previous[CONFIG_MP_MAX_NUM_CPUS];
 #endif
 
+/* Data structure to be passed down to thread_info_cb() by
+ * k_thread_foreach_my_core().
+ */
 struct user_data {
 	struct thread_info_core *core_data;
 	int thread_count;
@@ -252,7 +263,7 @@ static void thread_info_get(struct thread_info_core *core_data)
 						  ud.previous->all);
 
 		ud.stats_valid = true;
-		load = (active_cycles * 100U) / all_cycles;
+		load = (uint8_t) ((255LLU * active_cycles) / all_cycles);
 		LOG_DBG("Core %u load %u / %u total %llu / %llu", arch_proc_id(),
 			active_cycles, all_cycles,
 			core_stats.total_cycles, core_stats.execution_cycles);