Clean up

Author: lupyuen

docs/index.js

@@ -1,4 +1,6 @@
-// Generated by purs version 0.15.15
+// Parse the NuttX Exception and NuttX Stack Dump. Explain the NuttX Exception.
+// Based on https://github.com/purescript-contrib/purescript-string-parsers/blob/main/test/Examples.purs
+// Main Module will be started by `spago run`
 import * as Control_Applicative from "https://compile.purescript.org/output/Control.Applicative/index.js";
 import * as Control_Apply from "https://compile.purescript.org/output/Control.Apply/index.js";
 import * as Control_Bind from "https://compile.purescript.org/output/Control.Bind/index.js";
@@ -17,6 +19,23 @@ import * as StringParser_CodePoints from "https://compile.purescript.org/output/
 import * as StringParser_Parser from "https://compile.purescript.org/output/StringParser.Parser/index.js";
 var discard = /* #__PURE__ */ Control_Bind.discard(Control_Bind.discardUnit);
 var discard1 = /* #__PURE__ */ discard(StringParser_Parser.bindParser);
+
+// To parse the line: `stack_dump: 0xc02027e0: c0202010 00000000 00000001 00000000 00000000 00000000 8000ad8a 00000000`
+// If the line begins with a Timestamp: `[    6.242000] `
+// Skip `[    `
+// `void` means ignore the Text Captured
+// `$ something something` is shortcut for `( something something )`
+// `<*` is the Delimiter between Patterns
+// void $
+//   string "["    -- Match the string `[`
+//   <* skipSpaces -- Skip the following spaces
+//   <* regex "[.0-9]+" -- Skip the number
+//   <* string "]" -- Match the string `]`
+//   <* skipSpaces -- Skip the following spaces
+// Skip `stack_dump: `
+// `void` means ignore the Text Captured
+// `$ something something` is shortcut for `( something something )`
+// `<*` is the Delimiter between Patterns
 var $$void = /* #__PURE__ */ Data_Functor["void"](StringParser_Parser.functorParser);
 var applyFirst = /* #__PURE__ */ Control_Apply.applyFirst(StringParser_Parser.applyParser);
 var bind = /* #__PURE__ */ Control_Bind.bind(StringParser_Parser.bindParser);
@@ -32,34 +51,44 @@ var logShow = /* #__PURE__ */ Effect_Console.logShow(/* #__PURE__ */ showRecord(
         return "pos";
     }
 })(Data_Show.showInt))(Data_Show.showString)));
+
+// Address can point to Code, Data, BSS or Heap
 var Code = /* #__PURE__ */ (function () {
     function Code() {
 
     };
     Code.value = new Code();
     return Code;
 })();
+
+// Address can point to Code, Data, BSS or Heap
 var Data = /* #__PURE__ */ (function () {
     function Data() {
 
     };
     Data.value = new Data();
     return Data;
 })();
+
+// Address can point to Code, Data, BSS or Heap
 var BSS = /* #__PURE__ */ (function () {
     function BSS() {
 
     };
     BSS.value = new BSS();
     return BSS;
 })();
+
+// Address can point to Code, Data, BSS or Heap
 var Heap = /* #__PURE__ */ (function () {
     function Heap() {
 
     };
     Heap.value = new Heap();
     return Heap;
 })();
+
+// How to display an Address Type
 var showAddressType = {
     show: function (v) {
         if (v instanceof Code) {
@@ -77,6 +106,9 @@ var showAddressType = {
         throw new Error("Failed pattern match at Main (line 73, column 1 - line 77, column 21): " + [ v.constructor.name ]);
     }
 };
+
+// NuttX Kernel: 0x5020_0000 to 0x5021_98ac
+// NuttX App (qjs): 0x8000_0000 to 0x8006_4a28
 var logShow1 = /* #__PURE__ */ Effect_Console.logShow(/* #__PURE__ */ Data_Maybe.showMaybe(/* #__PURE__ */ showRecord(/* #__PURE__ */ Data_Show.showRecordFieldsCons({
     reflectSymbol: function () {
         return "origin";
@@ -86,6 +118,11 @@ var logShow1 = /* #__PURE__ */ Effect_Console.logShow(/* #__PURE__ */ Data_Maybe
         return "type";
     }
 })(showAddressType))(Data_Show.showString))));
+
+// Parse a line of NuttX Stack Dump.
+// Given this line of NuttX Stack Dump: `stack_dump: 0xc02027e0: c0202010 00000000 00000001 00000000 00000000 00000000 8000ad8a 00000000`
+// Result: { addr: "c02027e0", timestamp: "6.242000", v1: "c0202010", v2: "00000000", v3: "00000001", v4: "00000000", v5: "00000000", v6: "00000000", v7: "8000ad8a", v8: "00000000" }
+// The next line declares the Function Type. We can actually erase it, VSCode PureScript Extension will helpfully suggest it for us.
 var parseStackDump = /* #__PURE__ */ discard1(/* #__PURE__ */ $$void(/* #__PURE__ */ applyFirst(/* #__PURE__ */ StringParser_CodePoints.string("stack_dump:"))(StringParser_CodePoints.skipSpaces)))(function () {
     return discard1($$void(StringParser_CodePoints.string("0x")))(function () {
         return bind(applyFirst(applyFirst(StringParser_CodePoints.regex("[0-9a-f]+"))(StringParser_CodePoints.string(":")))(StringParser_CodePoints.skipSpaces))(function (addr) {
@@ -119,6 +156,15 @@ var parseStackDump = /* #__PURE__ */ discard1(/* #__PURE__ */ $$void(/* #__PURE_
         });
     });
 });
+
+// Parse the line of NuttX Stack Dump with Timestamp
+// Result: { addr: "c02027e0", v1: "c0202010", v2: "00000000", v3: "00000001", v4: "00000000", v5: "00000000", v6: "00000000", v7: "8000ad8a", v8: "00000000" }
+// doRunParser "parseStackDump" parseStackDump
+//   "[    6.242000] stack_dump: 0xc02027e0: c0202010 00000000 00000001 00000000 00000000 00000000 8000ad8a 00000000"
+// Parse the NuttX Exception.
+// Given this NuttX Exception: `riscv_exception: EXCEPTION: Instruction page fault. MCAUSE: 000000000000000c, EPC: 000000008000ad8a, MTVAL: 000000008000ad8a`
+// Result: { epc: "8000ad8a", exception: "Instruction page fault", mcause: 12, mtval: "8000ad8a" }
+// The next line declares the Function Type. We can actually erase it, VSCode PureScript Extension will helpfully suggest it for us.
 var parseException = /* #__PURE__ */ discard1(/* #__PURE__ */ $$void(/* #__PURE__ */ applyFirst(/* #__PURE__ */ applyFirst(/* #__PURE__ */ applyFirst(/* #__PURE__ */ StringParser_CodePoints.string("riscv_exception:"))(StringParser_CodePoints.skipSpaces))(/* #__PURE__ */ StringParser_CodePoints.string("EXCEPTION:")))(StringParser_CodePoints.skipSpaces)))(function () {
     return bind(applyFirst(applyFirst(StringParser_CodePoints.regex("[^.]+"))(StringParser_CodePoints.string(".")))(StringParser_CodePoints.skipSpaces))(function (exception) {
         return discard1($$void(applyFirst(StringParser_CodePoints.string("MCAUSE:"))(StringParser_CodePoints.skipSpaces)))(function () {
@@ -141,12 +187,17 @@ var parseException = /* #__PURE__ */ discard1(/* #__PURE__ */ $$void(/* #__PURE_
         });
     });
 });
+
+// Return True if the Address matches the Regex Pattern.
+// Pattern is assumed to match the Entire Address.
 var matches = function (pattern) {
     return function (addr) {
         var patternWrap = "^" + (pattern + "$");
         return Data_Maybe.isJust(Data_String_Regex.match(Data_String_Regex_Unsafe.unsafeRegex(patternWrap)(Data_String_Regex_Flags.noFlags))(addr));
     };
 };
+
+// Given an Address, identify the Origin (NuttX Kernel or App) and Type (Code / Data / BSS / Heap)
 var identifyAddress = function (addr) {
     if (matches("502.....")(addr)) {
         return new Data_Maybe.Just({
@@ -165,6 +216,10 @@ var identifyAddress = function (addr) {
     };
     throw new Error("Failed pattern match at Main (line 57, column 1 - line 57, column 74): " + [ addr.constructor.name ]);
 };
+
+// Given this NuttX Exception: `riscv_exception: EXCEPTION: Load page fault. MCAUSE: 000000000000000d, EPC: 000000008000a0e4, MTVAL: 0000000880203b88`
+// Explain in friendly words: "We hit a Load Page Fault. Our code at Code Address 8000a0e4 tried to access the Data Address 0000000880203b88, which is Invalid."
+// The next line declares the Function Type. We can actually erase it, VSCode PureScript Extension will helpfully suggest it for us.
 var explainException = function (v) {
     return function (v1) {
         return function (v2) {
@@ -178,6 +233,10 @@ var explainException = function (v) {
         };
     };
 };
+
+// Shows the results of calling `runParser`. We typically don't want to use
+// this function when writing a parser because it doesn't help us debug
+// our code when we write it incorrectly.
 var doRunParser = function (dictShow) {
     var show1 = Data_Show.show(dictShow);
     return function (parserName) {
@@ -193,7 +252,7 @@ var doRunParser = function (dictShow) {
                         if (v instanceof Data_Either.Right) {
                             return Effect_Console.log("Result: " + show1(v.value0))();
                         };
-                        throw new Error("Failed pattern match at Main (line 261, column 3 - line 263, column 52): " + [ v.constructor.name ]);
+                        throw new Error("Failed pattern match at Main (line 262, column 3 - line 264, column 52): " + [ v.constructor.name ]);
                     })();
                     return Effect_Console.log("-----")();
                 };
@@ -255,6 +314,11 @@ var doRunParser2 = /* #__PURE__ */ doRunParser(/* #__PURE__ */ showRecord(/* #__
         return "v8";
     }
 })(Data_Show.showString))(Data_Show.showString))(Data_Show.showString))(Data_Show.showString))(Data_Show.showString))(Data_Show.showString))(Data_Show.showString))(Data_Show.showString))(Data_Show.showString)));
+
+// Test our code. Parse the NuttX Exception and NuttX Stack Dump. Explain the NuttX Exception.
+// `Effect` says that it will do Side Effects (printing to console)
+// `Unit` means that no value will be returned
+// The next line declares the Function Type. We can actually erase it, VSCode PureScript Extension will helpfully suggest it for us.
 var printResults = function __do() {
     Effect_Console.log(explainException(13)("8000a0e4")("0000000880203b88"))();
     Effect_Console.log(explainException(12)("epc")("mtval"))();
@@ -265,6 +329,11 @@ var printResults = function __do() {
     doRunParser1("parseException")(parseException)("riscv_exception: EXCEPTION: Instruction page fault. MCAUSE: 000000000000000c, EPC: 000000008000ad8a, MTVAL: 000000008000ad8a")();
     return doRunParser2("parseStackDump")(parseStackDump)("stack_dump: 0xc02027e0: c0202010 00000000 00000001 00000000 00000000 00000000 8000ad8a 00000000")();
 };
+
+// Main Function that will run our Test Code.
+// `Effect` says that it will do Side Effects (printing to console)
+// `Unit` means that no value will be returned
+// The next line declares the Function Type. We can actually erase it, VSCode PureScript Extension will helpfully suggest it for us.
 var main = printResults;
 export {
     main,

src/Main.purs

@@ -180,6 +180,7 @@ parseException = do
 
   -- Return the parsed content
   -- `pure` because we're in a `do` block that allows (Side) Effects
+  -- TODO: Return a ParseError instead of -1
   pure 
     {
       exception