-#ifndef HEADER_THREAD_H
-#define HEADER_THREAD_H 1
+#ifndef THREADS_THREAD_H
+#define THREADS_THREAD_H
+#include <debug.h>
+#include <list.h>
#include <stdint.h>
-#include "debug.h"
-#include "list.h"
#ifdef USERPROG
-#include "addrspace.h"
+#include "userprog/addrspace.h"
#endif
-enum thread_status
+/* States in a thread's life cycle. */
+enum thread_status
{
- THREAD_INITIALIZING,
- THREAD_RUNNING,
- THREAD_READY,
- THREAD_BLOCKED,
- THREAD_DYING
+ THREAD_RUNNING, /* Running thread. */
+ THREAD_READY, /* Not running but ready to run. */
+ THREAD_BLOCKED, /* Waiting for an event to trigger. */
+ THREAD_DYING /* About to be destroyed. */
};
-struct thread
+/* Thread identifier type.
+ You can redefine this to whatever type you like. */
+typedef int tid_t;
+#define TID_ERROR ((tid_t) -1) /* Error value for tid_t. */
+
+/* Thread priorities. */
+#define PRI_MIN 0 /* Lowest priority. */
+#define PRI_DEFAULT 29 /* Default priority. */
+#define PRI_MAX 59 /* Highest priority. */
+
+/* A kernel thread or user process.
+
+ Each thread structure is stored in its own 4 kB page. The
+ thread structure itself sits at the very bottom of the page
+ (at offset 0). The rest of the page is reserved for the
+ thread's kernel stack, which grows downward from the top of
+ the page (at offset 4 kB). Here's an illustration:
+
+ 4 kB +---------------------------------+
+ | kernel stack |
+ | | |
+ | | |
+ | V |
+ | grows downward |
+ | |
+ | |
+ | |
+ | |
+ | |
+ | |
+ | |
+ | |
+ +---------------------------------+
+ | magic |
+ | : |
+ | : |
+ | name |
+ | status |
+ 0 kB +---------------------------------+
+
+ The upshot of this is twofold:
+
+ 1. First, `struct thread' must not be allowed to grow too
+ big. If it does, then there will not be enough room for
+ the kernel stack. Our base `struct thread' is only a
+ few bytes in size. It probably should stay well under 1
+ kB.
+
+ 2. Second, kernel stacks must not be allowed to grow too
+ large. If a stack overflows, it will corrupt the thread
+ state. Thus, kernel functions should not allocate large
+ structures or arrays as non-static local variables. Use
+ dynamic allocation with malloc() or palloc_get()
+ instead.
+
+ The first symptom of either of these problems will probably be
+ an assertion failure in thread_current(), which checks that
+ the `magic' member of the running thread's `struct thread' is
+ set to THREAD_MAGIC. Stack overflow will normally change this
+ value, triggering the assertion. */
+/* The `elem' member has a dual purpose. It can be an element in
+ the run queue (thread.c), or it can be an element in a
+ semaphore wait list (synch.c). It can be used these two ways
+ only because they are mutually exclusive: only a thread in the
+ ready state is on the run queue, whereas only a thread in the
+ blocked state is on a semaphore wait list. */
+struct thread
{
- enum thread_status status;
- char name[16];
- uint8_t *stack;
- list_elem rq_elem;
+ /* Owned by thread.c. */
+ tid_t tid; /* Thread identifier. */
+ enum thread_status status; /* Thread state. */
+ char name[16]; /* Name (for debugging purposes). */
+ uint8_t *stack; /* Saved stack pointer. */
+ int priority; /* Priority. */
+
+ /* Shared between thread.c and synch.c. */
+ list_elem elem; /* List element. */
+
#ifdef USERPROG
- struct addrspace addrspace;
+ /* Owned by userprog/addrspace.c. */
+ uint32_t *pagedir; /* Page directory. */
#endif
+
+ /* Owned by thread.c */
+ unsigned magic; /* Detects stack overflow. */
};
-void thread_init (const char *name, void (*) (void *aux), void *) NO_RETURN;
+void thread_init (void);
+void thread_start (void);
-struct thread *thread_create (const char *name, void (*) (void *aux), void *);
+typedef void thread_func (void *aux);
+tid_t thread_create (const char *name, int priority, thread_func *, void *);
#ifdef USERPROG
-bool thread_execute (const char *filename);
+tid_t thread_execute (const char *filename);
#endif
-void thread_destroy (struct thread *);
-void thread_ready (struct thread *);
+void thread_unblock (struct thread *);
struct thread *thread_current (void);
+tid_t thread_tid (void);
+const char *thread_name (void);
void thread_exit (void) NO_RETURN;
void thread_yield (void);
-void thread_sleep (void);
+void thread_block (void);
+
+/* This function will be implemented in problem 1-2. */
+void thread_join (tid_t);
+
+/* These functions will be implemented in problem 1-3. */
+void thread_set_priority (int);
+int thread_get_priority (void);
-#endif /* thread.h */
+#endif /* threads/thread.h */