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

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