Added some more doc comments + removed unused global variable wait_state

os/include/arch/devices.h

@@ -33,21 +33,35 @@ typedef struct iodev {
  * \return The desired I/O device descriptor.
  */
 extern iodev_t get_iodev(size_t *cmd_addr);
+
+/**
+ * \brief Activates every interrupt line on a given status.
+ * \param[in,out] prev The status to be updated.
+ */
 extern void status_il_on_all(size_t *prev);
+
+/**
+ * \brief Activates a given line on a given status.
+ * \param[in,out] prev The status to be updated.
+ * \param[in] line The line to be activated.
+ */
 extern void status_il_on(size_t *prev, int line);
 
-/** \brief Stores the time of day.
+/**
+ * \brief Stores the time of day.
  * \param[out] time The address of the variable where the time of day is to be
  * stored.
  */
 extern void store_tod(int *time);
 
-/** \brief Loads a new value for the interval timer.
+/**
+ * \brief Loads a new value for the interval timer.
  * \param[in] time The new value for the interval timer.
  */
 extern void load_interval_timer(int time);
 
-/** \brief Loads a new value for the local timer.
+/**
+ * \brief Loads a new value for the local timer.
  * \param[in] time The new value for the local timer.
  */
 extern void load_local_timer(int time);

os/include/arch/processor.h

@@ -15,7 +15,7 @@
 
 #ifdef __x86_64__
 #define STATE_GPR_LEN 7
-/* Mock a generic processor state with the bare mimum register for the nucleus
+/** Mock a generic processor state with the bare mimum register for the nucleus
  */
 typedef struct state {
     size_t cause;
@@ -31,26 +31,26 @@ typedef struct state {
 #define reg_t9 gpr[5]
 #define reg_sp gpr[6]
 #else
-/* Use the architecture-provided state_t */
+/** Use the architecture-provided state_t */
 #include <umps/types.h>
 #endif
 
 typedef signed int cpu_t;
 
-/* Page Table Entry descriptor */
+/** Page Table Entry descriptor */
 typedef struct pte_entry_t {
     unsigned int pte_entry_hi;
     unsigned int pte_entry_lo;
 } pte_entry_t;
 
-/* Support level context */
+/** Support level context */
 typedef struct context_t {
     unsigned int stack_ptr;
     unsigned int status;
     unsigned int pc;
 } context_t;
 
-/* Support level descriptor */
+/** Support level descriptor */
 typedef struct support_t {
     int sup_asid;                    /* process ID */
     state_t sup_except_state[2];     /* old state exceptions */

os/include/os/scheduler.h

@@ -14,15 +14,25 @@
 #include "os/pcb.h"
 #include "os/types.h"
 
+/** Keeps track of the total number of processes. */
 extern size_t process_count;
+/** Keeps track of the number of processes in the BLOCKED state. */
 extern size_t softblock_count;
-extern list_head ready_queue_lo, ready_queue_hi;
+/** Low priority process queue. */
+extern list_head ready_queue_lo;
+/** High priority process queue. */
+extern list_head ready_queue_hi;
+/** A pointer to the current running process. */
 extern pcb_t *active_process;
+/** A pointer to the process who just requested a yield operation. */
 extern pcb_t *yield_process;
+/** Initializer for the time of day. */
 extern cpu_t start_tod;
-extern state_t *wait_state;
 
 #ifdef PANDOS_TESTING
+/** \brief Getter for the current value of the PIDs' recycle count.
+ * \return The current value of the PIDs' recycle count.
+ */
 size_t get_recycle_count();
 #endif
 

os/include/os/util.h

@@ -23,7 +23,7 @@
 
 /**
  * \brief Checks whether both fields of a list head are NULL.
- * \param[in] l The list head to be checked.
+ * \param[in] head The list head to be checked.
  * \return true if both fields are NULL, or false otherwise.
  */
 static inline int list_null(const list_head *head)

phase2/include/semaphores_impl.h

@@ -12,6 +12,10 @@
 
 #define SEMAPHORES_NUM (DEVINTNUM + 1) * DEVPERINT + 1
 
+/**
+ * \brief Provides a pointer to the first element of the semaphores array.
+ * \return A pointer to the first element of the semaphores array.
+ */
 extern int *get_semaphores();
 
 #endif /* PANDOS_SEMAPHORE_IMPL_H */

test/include/test/test.h

@@ -12,7 +12,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-/* Name of the current test. */
+/** Name of the current test. */
 char *test = NULL;
 
 /** \brief Runs the following test with an "ensure" prefix in the message