pintos-os.org Git - pintos-anon/blob - src/threads/thread.h

   1 #ifndef THREADS_THREAD_H
   2 #define THREADS_THREAD_H
   3
   4 #include <debug.h>
   5 #include <list.h>
   6 #include <stdint.h>
   7
   8 #ifdef USERPROG
   9 #include "userprog/addrspace.h"
  10 #endif
  11
  12 /* States in a thread's life cycle. */
  13 enum thread_status
  14   {
  15     THREAD_RUNNING,     /* Running thread. */
  16     THREAD_READY,       /* Not running but ready to run. */
  17     THREAD_BLOCKED,     /* Waiting for an event to trigger. */
  18     THREAD_DYING        /* About to be destroyed. */
  19   };
  20
  21 /* Thread identifier type.
  22    You can redefine this to whatever type you like. */
  23 typedef int tid_t;
  24 #define TID_ERROR ((tid_t) -1)          /* Error value for tid_t. */
  25
  26 /* A kernel thread or user process.
  27
  28    Each thread structure is stored in its own 4 kB page.  The
  29    thread structure itself sits at the very bottom of the page
  30    (at offset 0).  The rest of the page is reserved for the
  31    thread's kernel stack, which grows downward from the top of
  32    the page (at offset 4 kB).  Here's an illustration:
  33
  34         4 kB +---------------------------------+
  35              |          kernel stack           |
  36              |                |                |
  37              |                |                |
  38              |                V                |
  39              |         grows downward          |
  40              |                                 |
  41              |                                 |
  42              |                                 |
  43              |                                 |
  44              |                                 |
  45              |                                 |
  46              |                                 |
  47              |                                 |
  48              +---------------------------------+
  49              |             magic               |
  50              |               :                 |
  51              |               :                 |
  52              |              name               |
  53              |             status              |
  54         0 kB +---------------------------------+
  55
  56    The upshot of this is twofold:
  57
  58       1. First, `struct thread' must not be allowed to grow too
  59          big.  If it does, then there will not be enough room for
  60          the kernel stack.  Our base `struct thread' is only a
  61          few bytes in size.  It probably should stay well under 1
  62          kB.
  63
  64       2. Second, kernel stacks must not be allowed to grow too
  65          large.  If a stack overflows, it will corrupt the thread
  66          state.  Thus, kernel functions should not allocate large
  67          structures or arrays as non-static local variables.  Use
  68          dynamic allocation with malloc() or palloc_get()
  69          instead.
  70
  71    The first symptom of either of these problems will probably be
  72    an assertion failure in thread_current(), which checks that
  73    the `magic' member of the running thread's `struct thread' is
  74    set to THREAD_MAGIC.  Stack overflow will normally change this
  75    value, triggering the assertion. */
  76 /* The `elem' member has a dual purpose.  It can be an element in
  77    the run queue (thread.c), or it can be an element in a
  78    semaphore wait list (synch.c).  It can be used these two ways
  79    only because they are mutually exclusive: only a thread in the
  80    ready state is on the run queue, whereas only a thread in the
  81    blocked state is on a semaphore wait list. */
  82 struct thread
  83   {
  84     /* These members are owned by thread.c. */
  85     tid_t tid;                          /* Thread identifier. */
  86     enum thread_status status;          /* Thread state. */
  87     char name[16];                      /* Name (for debugging purposes). */
  88     uint8_t *stack;                     /* Saved stack pointer. */
  89
  90     /* Shared between thread.c and synch.c. */
  91     list_elem elem;                     /* List element. */
  92
  93 #ifdef USERPROG
  94     /* These members are owned by userprog/addrspace.c. */
  95     uint32_t *pagedir;                  /* Page directory. */
  96 #endif
  97
  98     /* Marker to detect stack overflow. */
  99     unsigned magic;                     /* Always set to THREAD_MAGIC. */
 100   };
 101
 102 void thread_init (void);
 103 void thread_start (void);
 104
 105 typedef void thread_func (void *aux);
 106 tid_t thread_create (const char *name, thread_func *, void *);
 107 #ifdef USERPROG
 108 tid_t thread_execute (const char *filename);
 109 #endif
 110
 111 void thread_unblock (struct thread *);
 112
 113 struct thread *thread_current (void);
 114 tid_t thread_tid (void);
 115 const char *thread_name (void);
 116 void thread_exit (void) NO_RETURN;
 117 void thread_yield (void);
 118 void thread_block (void);
 119
 120 /* These functions will be implemented in project 1. */
 121 void thread_join (tid_t);
 122 void thread_set_priority (tid_t, int);
 123 int thread_get_priority (tid_t);
 124
 125 #endif /* threads/thread.h */