trap comments

pipelined/src/lsu/endianswap.sv

@@ -6,6 +6,8 @@
 //
 // Purpose: Swap byte order for Big-Endian accesses
 // 
+// Documentation: RISC-V System on Chip Design Chapter 5 (Figure 5.9)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University

pipelined/src/privileged/csr.sv

@@ -8,6 +8,8 @@
 // Purpose: Counter Control and Status Registers
 //          See RISC-V Privileged Mode Specification 20190608 
 // 
+// Documentation: RISC-V System on Chip Design Chapter 5
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University

pipelined/src/privileged/csrc.sv

@@ -9,6 +9,8 @@
 // Purpose: Counter CSRs
 //          See RISC-V Privileged Mode Specification 20190608 3.1.10-11
 // 
+// Documentation: RISC-V System on Chip Design Chapter 5
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University

pipelined/src/privileged/csri.sv

@@ -7,6 +7,8 @@
 // Purpose: Interrupt Control & Status Registers (IP, EI)
 //          See RISC-V Privileged Mode Specification 20190608 & 20210108 draft
 // 
+// Documentation: RISC-V System on Chip Design Chapter 5
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University

pipelined/src/privileged/csrm.sv

@@ -11,6 +11,8 @@
 //   - Disabling portions of the instruction set with bits of the MISA register
 //   - Changing from RV64 to RV32 by writing the SXL/UXL bits of the STATUS register
 //
+// Documentation: RISC-V System on Chip Design Chapter 5
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University

pipelined/src/privileged/csrs.sv

@@ -8,6 +8,8 @@
 // Purpose: Supervisor-Mode Control and Status Registers
 //          See RISC-V Privileged Mode Specification 20190608 
 //
+// Documentation: RISC-V System on Chip Design Chapter 5
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University

pipelined/src/privileged/csrsr.sv

@@ -7,6 +7,8 @@
 // Purpose: Status register
 //          See RISC-V Privileged Mode Specification 20190608 
 // 
+// Documentation: RISC-V System on Chip Design Chapter 5
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University

pipelined/src/privileged/csru.sv

@@ -5,8 +5,8 @@
 // Modified: 
 //
 // Purpose: User-Mode Control and Status Registers for Floating Point
-
+// 
-//          See RISC-V Privileged Mode Specification 20190608 Table 2.2
+// Documentation: RISC-V System on Chip Design Chapter 5
 //
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 

pipelined/src/privileged/privdec.sv

@@ -7,6 +7,8 @@
 // Purpose: Decode Privileged & related instructions 
 //          See RISC-V Privileged Mode Specification 20190608 3.1.10-11
 // 
+// Documentation: RISC-V System on Chip Design Chapter 5
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University

pipelined/src/privileged/privileged.sv

@@ -7,6 +7,8 @@
 // Purpose: Implements the CSRs, Exceptions, and Privileged operations
 //          See RISC-V Privileged Mode Specification 20190608 
 // 
+// Documentation: RISC-V System on Chip Design Chapter 5 (Figure 5.8)
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021 Harvey Mudd College & Oklahoma State University
@@ -86,25 +88,24 @@ module privileged (
   output logic             WFIStallM                                  // Stall in Memory stage for WFI until interrupt or timeout
 );
 
-  logic [`LOG_XLEN-1:0] CauseM;
+  logic [`LOG_XLEN-1:0]    CauseM;                                    // trap cause
-  logic [`XLEN-1:0] MEDELEG_REGW;
+  logic [`XLEN-1:0]        MEDELEG_REGW;                              // exception delegation CSR
-  logic [11:0]      MIDELEG_REGW;
+  logic [11:0]             MIDELEG_REGW;                              // interrupt delegation CSR
+  logic                    sretM, mretM;                              // supervisor / machine return instruction
+  logic                    IllegalCSRAccessM;                         // Illegal access to CSR
+  logic                    IllegalIEUInstrFaultM;                     // Illegal IEU instruction, delayed to Mem stage
+  logic                    InstrPageFaultM;                           // Instruction page fault, delayed to Mem stage
+  logic                    InstrAccessFaultM;                         // Instruction access fault, delayed to Mem stages
+  logic                    IllegalInstrFaultM;                        // Illegal instruction fault
+  logic                    STATUS_SPP, STATUS_TSR, STATUS_TW, STATUS_TVM; // Status bits needed within privileged unit
+  logic                    STATUS_MIE, STATUS_SIE;                    // status bits: interrupt enables
+  logic [11:0]             MIP_REGW, MIE_REGW;                        // interrupt pending and enable bits
+  logic [1:0]              NextPrivilegeModeM;                        // next privilege mode based on trap or return
+  logic                    DelegateM;                                 // trap should be delegated
+  logic                    wfiM;                                      // wait for interrupt instruction
+  logic                    IntPendingM;                               // interrupt is pending, even if not enabled.  ends wfi
+  (* mark_debug = "true" *) logic InterruptM;                         // interrupt occuring
 
-  logic sretM, mretM;
-  logic IllegalCSRAccessM;
-  logic IllegalIEUInstrFaultM;
-  logic InstrPageFaultM;
-  logic InstrAccessFaultM;
-  logic IllegalInstrFaultM;
-
-  (* mark_debug = "true" *)  logic InterruptM; 
-
-  logic       STATUS_SPP, STATUS_TSR, STATUS_TW, STATUS_TVM;
-  logic       STATUS_MIE, STATUS_SIE;
-  logic [11:0] MIP_REGW, MIE_REGW;
-  logic [1:0] NextPrivilegeModeM;
-  logic       DelegateM;
-  logic       wfiM, IntPendingM;
 
   // track the current privilege level
   privmode privmode(.clk, .reset, .StallW, .TrapM, .mretM, .sretM, .DelegateM,

pipelined/src/privileged/privmode.sv

@@ -5,7 +5,8 @@
 // Modified: 
 //
 // Purpose: Track privilege mode
-//          See RISC-V Privileged Mode Specification 20190608 3.1.10-11
+// 
+// Documentation: RISC-V System on Chip Design Chapter 5
 //
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 

pipelined/src/privileged/privpiperegs.sv

@@ -6,6 +6,8 @@
 //
 // Purpose: Pipeline registers for early exceptions
 // 
+// Documentation: RISC-V System on Chip Design Chapter 5
+//
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
 // Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University

pipelined/src/privileged/trap.sv

@@ -5,7 +5,8 @@
 // Modified: dottolia@hmc.edu 14 April 2021: Add support for vectored interrupts
 //
 // Purpose: Handle Traps: Exceptions and Interrupts
-//          See RISC-V Privileged Mode Specification 20190608 3.1.10-11
+// 
+// Documentation: RISC-V System on Chip Design Chapter 5 (Figure 5.9)
 //
 // A component of the CORE-V-WALLY configurable RISC-V project.
 // 
@@ -28,28 +29,33 @@
 `include "wally-config.vh"
 
 module trap (
-   input logic 		   reset, 
+  input  logic 		                             reset, 
-  (* mark_debug = "true" *) input logic 		   InstrMisalignedFaultM, InstrAccessFaultM, HPTWInstrAccessFaultM, IllegalInstrFaultM,
+  (* mark_debug = "true" *) input  logic 		   InstrMisalignedFaultM, InstrAccessFaultM, HPTWInstrAccessFaultM, IllegalInstrFaultM,
-  (* mark_debug = "true" *) input logic 		   BreakpointFaultM, LoadMisalignedFaultM, StoreAmoMisalignedFaultM,
+  (* mark_debug = "true" *) input  logic 		   BreakpointFaultM, LoadMisalignedFaultM, StoreAmoMisalignedFaultM,
-  (* mark_debug = "true" *) input logic 		   LoadAccessFaultM, StoreAmoAccessFaultM, EcallFaultM, InstrPageFaultM,
+  (* mark_debug = "true" *) input  logic 		   LoadAccessFaultM, StoreAmoAccessFaultM, EcallFaultM, InstrPageFaultM,
-  (* mark_debug = "true" *) input logic 		   LoadPageFaultM, StoreAmoPageFaultM,
+  (* mark_debug = "true" *) input  logic 		   LoadPageFaultM, StoreAmoPageFaultM,              // various trap sources
-  (* mark_debug = "true" *) input logic 		   mretM, sretM, 
+  (* mark_debug = "true" *) input  logic 		   mretM, sretM,                                    // return instructions
-  input logic [1:0] 	   PrivilegeModeW, 
+  input  logic                                 wfiM,                                            // wait for interrupt instruction
-  (* mark_debug = "true" *) input logic [11:0] 	   MIP_REGW, MIE_REGW, MIDELEG_REGW, 
+  input  logic [1:0] 	                         PrivilegeModeW,                                  // current privilege mode
-  input logic [`XLEN-1:0] MEDELEG_REGW,
+  (* mark_debug = "true" *) input logic [11:0] MIP_REGW, MIE_REGW, MIDELEG_REGW,                // interrupt pending, enabled, and delegate CSRs
-  input logic 		   STATUS_MIE, STATUS_SIE,
+  input  logic [`XLEN-1:0]                     MEDELEG_REGW,                                    // exception delegation SR
-  input logic 		   InstrValidM, wfiM, CommittedM, CommittedF,
+  input  logic 		                             STATUS_MIE, STATUS_SIE,                          // machine/supervisor interrupt enables
-  output logic 		   TrapM, RetM,
+  input  logic 		                             InstrValidM,                                     // current instruction is valid, not flushed
-  output logic 		   InterruptM, IntPendingM, DelegateM, WFIStallM,
+  input  logic                                 CommittedM, CommittedF,                          // LSU/IFU has committed to a bus operation that can't be interrupted
-  output logic [`LOG_XLEN-1:0] CauseM 
+  output logic 		                             TrapM,                                           // Trap is occurring
+  output logic 		                             RetM,                                            // Return instruction being executed
+  output logic 		                             InterruptM,                                      // Interrupt is occurring
+  output logic 		                             IntPendingM,                                     // Interrupt is pending, might occur if enabled
+  output logic 		                             DelegateM,                                       // Delegate trap to supervisor handler
+  output logic 		                             WFIStallM,                                       // Stall due to WFI instruction
+  output logic [`LOG_XLEN-1:0]                 CauseM                                           // trap cause
 );
 
-  logic MIntGlobalEnM, SIntGlobalEnM;
+  logic                                        MIntGlobalEnM, SIntGlobalEnM;                    // Global interupt enables
-  logic ExceptionM;
+  logic                                        ExceptionM;                                      // exception is occurring
-  logic Committed;
+  logic                                        Committed;                                       // LSU or IFU has committed to a bus operation that can't be interrupted
-  logic BothInstrAccessFaultM;
+  logic                                        BothInstrAccessFaultM;                           // instruction or HPTW ITLB fill caused an Instruction Access Fault
-  
+  (* mark_debug = "true" *) logic [11:0]       PendingIntsM, ValidIntsM, EnabledIntsM;          // interrupts are pending, valid, or enabled
-  (* mark_debug = "true" *) logic [11:0] PendingIntsM, ValidIntsM, EnabledIntsM; 
 
   ///////////////////////////////////////////
   // Determine pending enabled interrupts
@@ -57,6 +63,7 @@ module trap (
   // & with a M stage valid bit to avoid interrupts from interrupt a nonexistent flushed instruction (in the M stage)
   // & with ~CommittedM to make sure MEPC isn't chosen so as to rerun the same instr twice
   ///////////////////////////////////////////
+
   assign MIntGlobalEnM = (PrivilegeModeW != `M_MODE) | STATUS_MIE; // if M ints enabled or lower priv 3.1.9
   assign SIntGlobalEnM = (PrivilegeModeW == `U_MODE) | ((PrivilegeModeW == `S_MODE) & STATUS_SIE); // if in lower priv mode, or if S ints enabled and not in higher priv mode 3.1.9
   assign PendingIntsM = MIP_REGW & MIE_REGW;
@@ -74,6 +81,7 @@ module trap (
   // According to RISC-V Spec Section 1.6, exceptions are caused by instructions.  Interrupts are external asynchronous.
   // Traps are the union of exceptions and interrupts.
   ///////////////////////////////////////////
+  
   assign BothInstrAccessFaultM = InstrAccessFaultM | HPTWInstrAccessFaultM;
   assign ExceptionM = InstrMisalignedFaultM | BothInstrAccessFaultM | IllegalInstrFaultM |
                       LoadMisalignedFaultM | StoreAmoMisalignedFaultM |
@@ -87,6 +95,7 @@ module trap (
   // Cause priority defined in table 3.7 of 20190608 privileged spec
   // Exceptions are of lower priority than all interrupts (3.1.9)
   ///////////////////////////////////////////
+
   always_comb
     if      (reset)                    CauseM = 0; // hard reset 3.3
     else if (ValidIntsM[11])           CauseM = 11; // Machine External Int