Interrupts2 lecture

commit 0a905af3b19fc32250d07a783dc5f42d884a653c
Author: Julie Zelenski <[email protected]>
Date:   Mon Nov 11 01:14:55 2024 -0800

    Interrupts2 lecture

Author: zelenski

_data/unreleased.csv

@@ -1,7 +1,6 @@
 permalink,title,released
 "/assignments/assign7/","Assignment 7: System Monitor with Interrupts",false
 "/project/","Final Project",false
-"/labs/lab7/","Lab 7: Mango Pi, Interrupted",false
 "/labs/projectlab1/","Lab 8: Project Team Meeting 1",false
 "/labs/projectlab2/","Lab 9: Project Team Meeting 2",false
 "/lectures/FloatingPoint_Sound/","Floating Point and Sound",false

cs107e/lib/libmango.a

@@ -58,9 +58,8 @@ static gpio_int_group_t *get_int_group(gpio_id_t gpio, int *p_index) {
     return &module.groups[p.group];
 }
 
-// register dispatch_to_pin with top-level interrupts module
-// as handler for all GPIO interrupt sources
-// Aux data will be pointer to interrupt group
+// register private function dispatch_to_pin with top-level interrupts module
+// as handler for all GPIO interrupt sources, use pointer to interrupt group as aux_data
 void gpio_interrupt_init(void) {
     for (int i = 0; i < GPIO_NGROUPS; i++) {
         interrupts_register_handler(module.groups[i].source, dispatch_to_pin, &module.groups[i]);
@@ -82,6 +81,8 @@ void gpio_interrupt_register_handler(gpio_id_t gpio, handlerfn_t fn, void *aux_d
 // per-pin handlers that have been registered with this module
 static void dispatch_to_pin(void *aux_data) {
     gpio_int_group_t *gp = aux_data;
+    // find 'on' bit in status register to determine which pin had interrupt
+    // use clz to count number of leading zero bits before first one bit
     int pin_index = 31 - __builtin_clz(gp->eint->regs.status);
     gp->handlers[pin_index].fn(gp->handlers[pin_index].aux_data);
 }
@@ -93,9 +94,9 @@ static void gpio_interrupt_set_enabled(gpio_id_t gpio, bool state) {
     gpio_int_group_t *gp = get_int_group(gpio, &pin_index);
     unsigned int mask = (1 << pin_index);
     if (state) {
-        gp->eint->regs.ctl |= mask;
+        gp->eint->regs.ctl |= mask;     // set enable bit
     } else {
-        gp->eint->regs.ctl &= ~mask;
+        gp->eint->regs.ctl &= ~mask;    // clear enable bit
     }
 }
 
@@ -113,8 +114,8 @@ void gpio_interrupt_clear(gpio_id_t gpio) {
     int pin_index;
     gpio_int_group_t *gp = get_int_group(gpio, &pin_index);
     unsigned int mask = (1 << pin_index);
-    if ((gp->eint->regs.status & mask) != 0) { // is pending
-        gp->eint->regs.status |= mask; // write 1 to clear
+    if ((gp->eint->regs.status & mask) != 0) {  // if pending bit set for this pin
+        gp->eint->regs.status |= mask;          // write 1 to clear
     }
 }
 
@@ -129,12 +130,12 @@ void gpio_interrupt_config(gpio_id_t gpio, gpio_event_t event, bool debounce) {
     unsigned int mask = ((1 << 4) - 1);
     gp->eint->regs.cfg[bank] = (gp->eint->regs.cfg[bank] & ~(mask << shift)) | ((event & mask) << shift);
     gpio_set_function(gpio, GPIO_FN_INTERRUPT); // change pin function to interrupt
-    if (debounce) {
-        // 32Khz clock, predivide 2^5, will filter to ~1 event per ms
+    if (debounce) { // if debounce requested
+        // apply 32Khz clock, predivide 2^5, will filter to ~1 event per ms
         gp->eint->regs.debounce = (5 << 4) | 0;
     } else {
-        // 24Mhz clock, no predivide, no filter
+        // apply 24Mhz clock, no predivide, no filter
         gp->eint->regs.debounce = (0 << 4) | 1;
     }
-    gpio_interrupt_clear(gpio); // cancel any stale event
+    gpio_interrupt_clear(gpio); // clear any past event, start anew with updated config
 }

cs107e/src/gpio_interrupt.c

@@ -13,7 +13,7 @@ typedef union {
     struct {
         uint32_t ctrl;
         uint32_t intv_lo;   // lower 32 bits of interval (see docs note above)
-        uint32_t intv_hi;   // uppper 32 bits of interval
+        uint32_t intv_hi;   // upper 32 bits of interval
         uint32_t cur_lo;    // lower 32 bits of cur value
         uint32_t cur_hi;    // upper 32 bits of cur value
     } regs;
@@ -50,23 +50,23 @@ static struct {
  */
 void hstimer_init(hstimer_id_t index, long usecs) {
     if (index != HSTIMER0 && index != HSTIMER1) return;
-    long rate = ccu_ungate_bus_clock(CCU_HSTIMER_BGR_REG);   // clock up peripheral
-    module.timers[index].regs.ctrl = (0 << 7) | (0 << 4);  // config for normal mode, periodic (not one-shot), prescale = 2^0, disabled
-    uint64_t count = (usecs * rate)/(1000*1000); // calculate count based on clock frequency
+    long rate = ccu_ungate_bus_clock(CCU_HSTIMER_BGR_REG);  // clock up peripheral
+    module.timers[index].regs.ctrl = (0 << 7) | (0 << 4);   // config mode normal periodic (not one-shot), prescale = 2^0, not enabled
+    uint64_t count = (usecs * rate)/(1000*1000);            // calculate count based on clock frequency
     module.timers[index].regs.intv_lo = count & 0xffffffff; // must set low before high (see docs note above)
     module.timers[index].regs.intv_hi = count >> 32;
-    module.timers[index].regs.ctrl |= (1 << 1);     // reload interval into cur
+    module.timers[index].regs.ctrl |= (1 << 1);             // reload interval into cur
     module.interrupt->regs.irq_en |= (1 << index);          // enable interrupts
 }
 
 void hstimer_enable(hstimer_id_t index) {
     if (index != HSTIMER0 && index != HSTIMER1) return;
-    module.timers[index].regs.ctrl |= 1;   // enable will start (or resume) countdown
+    module.timers[index].regs.ctrl |= 1;   // set ctrl bit will start/resume countdown
 }
 
 void hstimer_disable(hstimer_id_t index) {
     if (index != HSTIMER0 && index != HSTIMER1) return;
-    module.timers[index].regs.ctrl &= ~1; // disable will pause countdown
+    module.timers[index].regs.ctrl &= ~1; // clear ctrl bit will pause countdown
 }
 
 void hstimer_interrupt_clear(hstimer_id_t index) {

cs107e/src/hstimer.c

@@ -22,9 +22,9 @@ void interrupts_set_mtvec(void *);
 // structs defined to match layout of hardware registers
 typedef union {
     struct {
-        uint32_t priority[1024];    // only first 256 used (N_SOURCES)
-        uint32_t pending[1024];     // only first 8 used (one pending bit per source)
-        uint32_t enable[1024];      // only first 8 used (one enable bit per source)
+        uint32_t priority[1024];    // only first 256 indexes are used (priority per source)
+        uint32_t pending[1024];     // only first 8 indexes used (pending bit per source, 256/32 = 8)
+        uint32_t enable[1024];      // only first 8 indexes used (enable bit per source, 256/32 = 8)
     } regs;
 } source_t;
 
@@ -85,10 +85,10 @@ __attribute__((interrupt("machine"))) void _trap_handler(void) {
     long mcause = interrupts_get_mcause();
 #define EXTERNAL_INTERRUPT ((1L << 63) | 0xb)
     if (mcause == EXTERNAL_INTERRUPT) { // trap is interrupt
-        // no need to search pending bits to identify source, claim reg has it
+        // do not need to search pending bits to identify which source, claim reg has source number
         uint32_t source = module.plic->regs.claim_complete; // read claim_complete to "claim" (atomically clears pending bit)
         module.handlers[source].fn(module.handlers[source].aux_data); // dispatch to registered handler
-        module.plic->regs.claim_complete = source;   // write claim_complete to "complete"
+        module.plic->regs.claim_complete = source;   // write claim_complete to clear
     } else { // trap is exception
         long mtval = interrupts_get_mtval();
         void *mepc = (void *)interrupts_get_mepc();
@@ -110,17 +110,17 @@ __attribute__((interrupt("machine"))) void _trap_handler(void) {
 void interrupts_init(void) {
     if (module.initialized) error("interrupts_init() must be called only once");
     interrupts_global_disable();
-    module.plic->regs.ctrl = 0;         // machine mode only
-    module.plic->regs.threshhold = 0;   // accept interrupts of any priority
-    interrupts_set_mtvec(_trap_handler);            // install trap handler
-    for (int i = 0; i < 8; i++) {       // all sources start disabled
-        module.sources->regs.pending[i] = 0;
+    module.plic->regs.ctrl = 0;             // machine mode only
+    module.plic->regs.threshhold = 0;       // accept interrupts of any priority
+    interrupts_set_mtvec(_trap_handler);    // install trap handler
+    for (int i = 0; i < N_SOURCES/32; i++) {
+        module.sources->regs.pending[i] = 0;// all sources initially disabled
         module.sources->regs.enable[i] = 0;
     }
     for (int i = 0; i < N_SOURCES; i++) {
         module.sources->regs.priority[i] = 0;
-        module.handlers[i].fn = NULL;
-        module.plic->regs.claim_complete = i; // mark any pending request completed
+        module.handlers[i].fn = NULL;           // all sources initially have NULL handler
+        module.plic->regs.claim_complete = i;   // reset any pending claim
     }
     module.initialized = true;
 }
@@ -144,10 +144,10 @@ static void set_source_enabled(interrupt_source_t source, bool enabled) {
     int shift = source % 32;
     if (enabled) {
         module.sources->regs.priority[source] = 1; // priority at 1 (0 is disable, 1 is lowest)
-        module.sources->regs.enable[bank] |= (1 << shift);
+        module.sources->regs.enable[bank] |= (1 << shift); // set enable bit
     } else {
         module.sources->regs.priority[source] = 0;
-        module.sources->regs.enable[bank] &= ~(1 << shift);
+        module.sources->regs.enable[bank] &= ~(1 << shift); // clear enable bit
     }
 }
 
@@ -162,6 +162,6 @@ void interrupts_disable_source(interrupt_source_t source) {
 void interrupts_register_handler(interrupt_source_t source, handlerfn_t fn, void *aux_data) {
     if (!module.initialized) error("interrupts_init() has not been called!\n");
     if (!is_valid_source(source)) error("request to register handler for interrupt source that is not valid");
-    module.handlers[source].fn = fn;
-    module.handlers[source].aux_data = aux_data;
+    module.handlers[source].fn = fn;                // store handler function and
+    module.handlers[source].aux_data = aux_data;    // aux_data pointer into array at index corresponding to source
 }

cs107e/src/interrupts.c

@@ -5,36 +5,36 @@
 
 .globl interrupts_global_enable
 interrupts_global_enable:
-    li a0,1<<3
-    csrs mstatus,a0
-    li a0,1<<11
-    csrs mie,a0
+    li a0,1<<11         # MEIE bit 11 (m-mode external interrupts)
+    csrs mie,a0         # set bit in mie register
+    li a0,1<<3          # MIE bit 3 (global enable m-mode interrupts)
+    csrs mstatus,a0     # set bit in mstatus register
     ret
 
 .globl interrupts_global_disable
 interrupts_global_disable:
+    li a0,1<<11         # (reverse steps from global enable)
+    csrc mie,a0         # clear bit in mie
     li a0,1<<3
-    csrc mstatus,a0
-    li a0,1<<11
-    csrc mie,a0
+    csrc mstatus,a0     # clear bit in mstatus
     ret
 
 .globl interrupts_get_mcause
 interrupts_get_mcause:
-    csrr a0,mcause
+    csrr a0,mcause      # retrieve mcause
     ret
 
 .globl interrupts_get_mepc
 interrupts_get_mepc:
-    csrr a0,mepc
+    csrr a0,mepc        # retrieve mepc
     ret
 
 .globl interrupts_get_mtval
 interrupts_get_mtval:
-    csrr a0,mtval
+    csrr a0,mtval       # retrieve mtval
     ret
 
 .globl interrupts_set_mtvec
 interrupts_set_mtvec:
-    csrw mtvec,a0
+    csrw mtvec,a0       # mtvec holds addr of handler to call on trap
     ret

cs107e/src/interrupts_asm.s

@@ -22,7 +22,7 @@
  * Both head and tail advance circularly, i.e. index = (index + 1) % LENGTH
  * The ring buffer is empty if tail == head
  * The ring buffer is full if tail + 1 == head
- * (Note: one slot remains permanently empty to distinguish full from empty)
+ * (Note: one slot permanently unused to distinguish full from empty)
  */
 
 struct ringbuffer {