memguard: improved comments, code structure and cleaned code

src/memguard/memguard.c

@@ -519,10 +519,6 @@ void memguard_task_switch_out()
     if(task_info != NULL){
         task_info->counter_val = pmu_read_counter(MEMGUARD_CNTR_ID);
 
-        /*  Setting the counter to 0 in order to prevent it from overflowing
-	    during the context switch */
-        pmu_write_counter(MEMGUARD_CNTR_ID, 0);
-
         #if(INCLUDE_memguard_benchmark)
         {
             stop_benchmark_trace();
@@ -646,8 +642,11 @@ static int setup_pmu_overflow_interrupt()
         return XST_FAILURE;
     }
 
-    /*  Setting the priority of the PMU interrupts to low value, in order to
-	make the PMU interrupts preemtable by the timer or ICI interrupts.
+    /* Setting the priority of the PMU interrupts to low value, in order to
+    make the PMU interrupts preemtable by the timer or ICI interrupts.
+    This precaution is taken in order to avoid overflow interrupts while the
+    window reset is already started. This situation would create problems in the
+    MemGuard workflow.
 	Trigger type: 0b01 => Active HIGH level sensitive */
     XScuGic_SetPriorityTriggerType(int_controller_ptr, PMU_INT_ID,
 								   (u8)PMU_OVERFLOW_INT_PRIORITY, 0b01);
@@ -691,7 +690,11 @@ static void check_if_cores_are_ready()
 
 /**
  * This function sets up the window timer. It is supposed to be executed
- * inside a Task context in order to execute properly.
+ * inside a Task context in order to execute properly. We are using an
+ * independent timer which allows more fine grained observation of the memory
+ * bandwidth (eg. 1ms time window) and allows a window to span between 2
+ * different ticks. For more information refer to the original paper at the
+ * Subsection 6.2.
  */
 static void memguard_timer_setup()
 {
@@ -855,7 +858,10 @@ static void memguard_reset_window_routine(void *pvParameter1,
         XTtcPs_Start(&memguard_timer);
     }
 
-    /*  Resuming scheduler to start the new window */
+    /*  Resuming the scheduler to start the new window. There is no reason to
+    wait for the other cores to be ready as restarting the window doesn't
+    influence the other cores activity. The core will allow its tasks to run
+    using only their allocated bandwidth. */
     xTaskResumeAll();
 
     #if (INCLUDE_memguard_benchmark)
@@ -876,7 +882,9 @@ static void memguard_overflow_interrupt_handler(void *callback_ref)
         trace_entrance_overflow_handler();
     #endif
 
-    /*  Checks if PMU has really really overflowed for the BUS_ACCESS counter */
+    /*  Checks if PMU has really really overflowed for the BUS_ACCESS counter.
+    It may happend that another counter has overflowed triggering the
+    interrupt handler, but our handler is not responsible for that counter. */
     if(!pmu_counter_has_overflowed(MEMGUARD_CNTR_ID)){
         #if (INCLUDE_memguard_benchmark == 1)
             stop_memguard_trace();
@@ -948,7 +956,8 @@ static void memguard_overflow_interrupt_handler(void *callback_ref)
     #if( PROPORTIONAL_SHARE == 1)
     {
         /*  If total budget used exceeds the minimum guaranteed bandwidth then
-	    a new time window has to be started */
+	    a new time window has to be started. We reach this situation if the
+        tasks from all the cores have finished their budget.*/
         if (sum_of_quota_used >= MIN_GUARANTEED_BUDGET){
             int status;
 

src/memguard/perfmon.c

@@ -75,9 +75,9 @@
  ******************************************************************************/
 
 #if(configUSE_PMU_IN_USER_MODE == 1)
-    /**
-     * It enables user-mode access to counters. It is important in order to
-     * be able to use the counters in FreeRTOS
+   /**
+    * It enables user-mode access (EL0: applications) to counters. It is
+    * important in order to be able to use the counters in FreeRTOS.
     */
     static inline void enable_user_access_to_counters()
     {
@@ -100,7 +100,7 @@ static inline void pmu_enable_counter(uint32_t idx)
 }
 
 /**
- * This function disables the selected counter in order to make it count.
+ * This function disables the selected counter.
  * @idx: The counter n index
  */
 static inline void pmu_disable_counter(uint32_t idx)
@@ -154,13 +154,13 @@ static inline void pmu_counter_select(uint32_t idx)
 }
 
 /**
- * This function selects for the selected counter the type of event to be
+ * This function sets, for the given counter, the type of event to be
  * monitored and counted
  * @param idx of the counter of which it is being selected the event
  * @param type of the event to be monitored. Events that can be monitored are
  * contained in the file events.h
  */
-static inline void pmu_type_select(uint32_t idx, uint32_t type)
+static inline void pmu_counter_set_event_type(uint32_t idx, uint32_t type)
 {
 	pmu_counter_select(idx);
 	write_register(PMXEVTYPER_EL0, type);
@@ -185,7 +185,7 @@ void pmu_init_counters()
 void pmu_enable_counter_for_event(uint32_t idx, uint32_t event_type)
 {
 	pmu_disable_counter(idx);
-	pmu_type_select(idx, event_type);
+	pmu_counter_set_event_type(idx, event_type);
 	pmu_enable_counter(idx);
 }