Changeset 9cefba4 in mainline

Timestamp:

2005-10-16T19:18:19Z (19 years ago)

Author:

Jakub Jermar <jakub@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

ba1b2194

Parents:

0bed5d0

Message:

Doxygen-style comments.

Files:

• doc/arch/mips32 (modified) (1 diff)
• include/proc/scheduler.h (modified) (1 diff)
• include/proc/task.h (modified) (1 diff)
• include/proc/thread.h (modified) (3 diffs)
• include/synch/rwlock.h (modified) (1 diff)
• include/synch/synch.h (modified) (1 diff)
• include/synch/waitq.h (modified) (1 diff)
• include/typedefs.h (modified) (1 diff)

doc/arch/mips32

@@ -19 +19 @@
 
 EMULATORS AND VIRTUALIZERS
-        o msim 1.2.7
-        o msim 1.2.6 with lwl/lwr/swl/swr patch
+        o msim 1.2.8
         o gxemul - both big and little endian
         o simics 2.2.19

include/proc/scheduler.h

@@ -40 +40 @@
 struct runq {
         spinlock_t lock;
-        link_t rq_head;
-        int n;
+        link_t rq_head;         /**< List of ready threads. */
+        int n;                  /**< Number of threads in rq_ready. */
 };
 

include/proc/task.h

@@ -36 +36 @@
 struct task {
         spinlock_t lock;
-        link_t th_head;         /* list of threads contained in this task */
-        link_t tasks_link;      /* link to other tasks within the system */
+        link_t th_head;         /**< List of threads contained in this task. */
+        link_t tasks_link;      /**< Link to other tasks within the system. */
         vm_t *vm;
 };

include/proc/thread.h

@@ -46 +46 @@
 
 enum state {
-        Invalid,
-        Running,
-        Sleeping,
-        Ready,
-        Entering,
-        Exiting
+        Invalid,        /**< It is an error, if thread is found in this state. */
+        Running,        /**< State of a thread that is currently executing on some CPU. */
+        Sleeping,       /**< Thread in this state is waiting for an event. */
+        Ready,          /**< State of threads in a run queue. */
+        Entering,       /**< Threads are in this state before they are first readied. */
+        Exiting         /**< After a thread calls thread_exit(), it is put into Exiting state. */
 };
 
@@ -60 +60 @@
 
 struct thread {
-        link_t rq_link;                         /* run queue link */
-        link_t wq_link;                         /* wait queue link */
-        link_t th_link;                         /* links to threads within the parent task*/
-        link_t threads_link;
+        link_t rq_link;                         /**< Run queue link. */
+        link_t wq_link;                         /**< Wait queue link. */
+        link_t th_link;                         /**< Links to threads within containing task. */
+        link_t threads_link;                    /**< Link to the list of all threads. */
         
         /* items below are protected by lock */
         spinlock_t lock;
 
-        void (* thread_code)(void *);
-        void *thread_arg;
+        void (* thread_code)(void *);           /**< Function implementing the thread. */
+        void *thread_arg;                       /**< Argument passed to thread_code() function. */
 
-        context_t saved_context;
-        context_t sleep_timeout_context;
+        context_t saved_context;                /**< From here, the stored context is restored when the thread is scheduled. */
+        context_t sleep_timeout_context;        /**< From here, the stored failover context is restored when sleep times out. */
+
+        waitq_t *sleep_queue;                   /**< Wait queue in which this thread sleeps. */
+        timeout_t sleep_timeout;                /**< Timeout used for timeoutable sleeping.  */
+        volatile int timeout_pending;           /**< Flag signalling sleep timeout in progress. */
+
         fpu_context_t saved_fpu_context;
         int fpu_context_exists;
@@ -83 +88 @@
         int fpu_context_engaged;
 
-        waitq_t *sleep_queue;
-        timeout_t sleep_timeout;
-        volatile int timeout_pending;
+        rwlock_type_t rwlock_holder_type;
 
-        rwlock_type_t rwlock_holder_type;
-        void (* call_me)(void *);
-        void *call_me_with;
+        void (* call_me)(void *);               /**< Funtion to be called in scheduler before the thread is put asleep. */
+        void *call_me_with;                     /**< Argument passed to call_me(). */
 
-        int state;
-        int flags;
+        state_t state;                          /**< Thread's state. */
+        int flags;                              /**< Thread's flags. */
         
-        cpu_t *cpu;
-        task_t *task;
+        cpu_t *cpu;                             /**< Thread's CPU. */
+        task_t *task;                           /**< Containing task. */
 
-        __u64 ticks;
+        __u64 ticks;                            /**< Ticks before preemption. */
 
-        __u32 tid;
+        int pri;                                /**< Thread's priority. Implemented as index of run queue. */
+        __u32 tid;                              /**< Thread ID. */
         
-        int pri;
-        
-        ARCH_THREAD_DATA;
+        ARCH_THREAD_DATA;                       /**< Architecture-specific data. */
 
-        __u8 *kstack;
-        __u8 *ustack;
+        __u8 *kstack;                           /**< Thread's kernel stack. */
+        __u8 *ustack;                           /**< Thread's user stack. */
 };
 
-extern spinlock_t threads_lock;
-extern link_t threads_head;
+extern spinlock_t threads_lock;                 /**< Lock protecting threads_head list. */
+extern link_t threads_head;                     /**< List of all threads in the system. */
 
 static void cushion(void);

include/synch/rwlock.h

@@ -43 +43 @@
 struct rwlock {
         spinlock_t lock;
-        mutex_t exclusive;
-        int readers_in;
+        mutex_t exclusive;      /**< Mutex for writers, readers can bypass it if readers_in is positive. */
+        int readers_in;         /**< Number of readers in critical section. */
 };
 

include/synch/synch.h

@@ -30 +30 @@
 #define __SYNCH_H__
 
-#define SYNCH_NO_TIMEOUT        0
-#define SYNCH_BLOCKING          0
-#define SYNCH_NON_BLOCKING      1
+#define SYNCH_NO_TIMEOUT        0       /**< No timeout is request. */
+#define SYNCH_BLOCKING          0       /**< Blocking operation request. */
+#define SYNCH_NON_BLOCKING      1       /**< Non-blocking operation request. */
 
-#define ESYNCH_WOULD_BLOCK      1
-#define ESYNCH_TIMEOUT          2
-#define ESYNCH_OK_ATOMIC        4
-#define ESYNCH_OK_BLOCKED       8
+#define ESYNCH_WOULD_BLOCK      1       /**< Could not satisfy the request without going to sleep. */
+#define ESYNCH_TIMEOUT          2       /**< Timeout occurred. */
+#define ESYNCH_OK_ATOMIC        4       /**< Operation succeeded without sleeping. */
+#define ESYNCH_OK_BLOCKED       8       /**< Operation succeeded and did sleep. */
 
 #define SYNCH_FAILED(rc)        ((rc) & (ESYNCH_WOULD_BLOCK | ESYNCH_TIMEOUT))

include/synch/waitq.h

@@ -41 +41 @@
 struct waitq {
         spinlock_t lock;
-        int missed_wakeups;
-        link_t head;
+        int missed_wakeups;     /**< Number of waitq_wakeup() calls that didn't find a thread to wake up. */
+        link_t head;            /**< List of sleeping threads for wich there was no missed_wakeup. */
 };
 

include/typedefs.h

@@ -46 +46 @@
 typedef struct cpu_arch cpu_arch_t;
 typedef struct task task_t;
+typedef enum state state_t;
 typedef struct thread thread_t;
 typedef struct context context_t;