From 7f1e5202704c0cb14bb9b6f55f59e68ef64d72ba Mon Sep 17 00:00:00 2001
From: Rodrigo Arias Mallo <rodrigo.arias@bsc.es>
Date: Wed, 4 Sep 2024 16:17:21 +0200
Subject: [PATCH] Improve plictool output and write manual

---
 tools/plictool.c | 74 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 65 insertions(+), 9 deletions(-)

diff --git a/tools/plictool.c b/tools/plictool.c
index c517e81..d2705c6 100644
--- a/tools/plictool.c
+++ b/tools/plictool.c
@@ -6,9 +6,12 @@
 
 /* Changelog:
  *   v0.0.1 (2024-09-03): Initial version.
- *   v0.0.2 (2024-09-04): Print contexts in another line and on/off information.
+ *   v0.0.2 (2024-09-04): Print contexts in another line and masked information.
+ *   v0.0.3 (2024-09-04): Make output format more clear and add manual.
  */
 
+#define VERSION "v0.0.3"
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <stdint.h>
@@ -26,10 +29,49 @@ long nsources = 1024L;
 static void
 usage(void)
 {
-	printf("plictool v0.0.2 - Rodrigo Arias Mallo <rodrigo.arias@bsc.es>\n");
-
 	printf(
-"Usage: plictool [-a addr] [-s nsources] [-c ncontexts]\n");
+"NAME\n"
+"    plictool - dump PLIC information\n"
+"\n"
+"SYNOPSIS\n"
+"    plictool [-a addr] [-s nsources] [-c ncontexts]\n"
+"\n"
+"DESCRIPTION\n"
+"    Dumps information about the RISC-V PLIC interrupt controller.\n"
+"    Optional arguments:\n"
+"\n"
+"      -a addr        The starting address of the PLIC.\n"
+"                     The default is 0x40800000.\n"
+"\n"
+"      -s nsources    Limit the number of sources to print.\n"
+"                     The default is 1024.\n"
+"\n"
+"      -c ncontexts   Limit the number of contexts to print.\n"
+"                     The default is 15872.\n"
+"\n"
+"OUTPUT FORMAT\n"
+"    Information is printed for each source that has some bit set\n"
+"    in the pending or priority registers, or it has some context\n"
+"    enabled. The the following attributes are printed:\n"
+"\n"
+"      src     source number\n"
+"      pend    pending bit\n"
+"      prio    priority of the source\n"
+"\n"
+"    Additionally, for each enabled context of the source the\n"
+"    following attributes are printed for that context:\n"
+"\n"
+"      ctx     context number\n"
+"      thre    threshold value\n"
+"      masked  the source is masked (prio <= thre)\n"
+"\n"
+"AUTHOR\n"
+"    Rodrigo Arias Mallo <rodrigo.arias@bsc.es>\n"
+"\n"
+"SEE ALSO\n"
+"    See https://github.com/riscv/riscv-plic-spec/\n"
+"\n"
+);
 	exit(1);
 }
 
@@ -45,7 +87,7 @@ void dump_sources(void *base)
 		uint32_t priority = *priority_reg;
 
 		const char *fmt =
-			"src=%ld pend=%u prio=%u\n";
+			"src=%ld pend=%u prio=%u";
 
 		if (pending || priority) {
 			printf(fmt, s, pending, priority);
@@ -53,6 +95,8 @@ void dump_sources(void *base)
 		}
 
 		int first_context = 1;
+		int enabled_contexts = 0;
+		int unmasked = 0;
 		for (long c = 0; c < ncontexts; c++) {
 			uint32_t *enable_reg = base + 0x2000L + 0x80L * c + (s / 32L) * 4L;
 			uint32_t enabled = ((*enable_reg) >> shift) & 1;
@@ -67,10 +111,21 @@ void dump_sources(void *base)
 				printed_source = 1;
 			}
 
-			int active = priority > threshold ? 1 : 0;
 
-			printf("  ctx=%ld thre=%u active=%d\n", c, threshold, active);
+			int is_masked = priority <= threshold;
+
+			if (!is_masked)
+				unmasked++;
+
+			const char *masked = is_masked ? "masked" : "unmasked";
+
+			printf("\n    ctx=%ld thre=%u %s",
+					c, threshold, masked);
+			enabled_contexts++;
 		}
+
+		if (printed_source)
+			printf("\n");
 	}
 }
 
@@ -95,11 +150,12 @@ int main(int argc, char *argv[])
 		}
 	}
 
-	off_t plic_address = (off_t) strtoll(plic_address_str, NULL, 16);
+	unsigned long long plic_address = strtoull(plic_address_str, NULL, 16);
 
-	printf("plic=0x%08x nsources=%ld ncontexts=%ld\n",
+	printf("plictool "VERSION" addr=0x%08llx nsrc=%ld nctx=%ld\n",
 			plic_address, nsources, ncontexts);
 
+	//int fd = open("test.bin", O_RDWR | O_SYNC);
 	int fd = open("/dev/mem", O_RDWR | O_SYNC);
 
 	if (fd == -1) {