parlib: Add uthread_create()
[akaros.git] / user / parlib / include / parlib / uthread.h
1 #pragma once
2
3 #include <parlib/vcore.h>
4 #include <parlib/signal.h>
5 #include <parlib/spinlock.h>
6 #include <parlib/parlib.h>
7 #include <parlib/kref.h>
8 #include <ros/syscall.h>
9 #include <sys/queue.h>
10 #include <time.h>
11
12 __BEGIN_DECLS
13
14 #define UTHREAD_DONT_MIGRATE            0x001 /* don't move to another vcore */
15 #define UTHREAD_SAVED                           0x002 /* uthread's state is in utf */
16 #define UTHREAD_FPSAVED                         0x004 /* uthread's FP state is in uth->as */
17 #define UTHREAD_IS_THREAD0                      0x008 /* thread0: glibc's main() thread */
18
19 /* Thread States */
20 #define UT_RUNNING              1
21 #define UT_NOT_RUNNING  2
22
23 /* Externally blocked thread reasons (for uthread_has_blocked()) */
24 #define UTH_EXT_BLK_MUTEX                       1
25 #define UTH_EXT_BLK_EVENTQ                      2
26 #define UTH_EXT_BLK_JUSTICE                     3       /* whatever.  might need more options */
27
28 /* One per joiner, usually kept on the stack. */
29 struct uth_join_kicker {
30         struct kref                                     kref;
31         struct uthread                          *joiner;
32 };
33
34 /* Join states, stored in the join_ctl */
35 #define UTH_JOIN_DETACHED               1
36 #define UTH_JOIN_JOINABLE               2
37 #define UTH_JOIN_HAS_JOINER             3
38 #define UTH_JOIN_EXITED                 4
39
40 /* One per uthread, to encapsulate all the join fields. */
41 struct uth_join_ctl {
42         atomic_t                                        state;
43         void                                            *retval;
44         void                                            **retval_loc;
45         struct uth_join_kicker          *kicker;
46 };
47
48 /* Bare necessities of a user thread.  2LSs should allocate a bigger struct and
49  * cast their threads to uthreads when talking with vcore code.  Vcore/default
50  * 2LS code won't touch udata or beyond. */
51 struct uthread {
52         struct user_context u_ctx;
53         struct ancillary_state as;
54         void *tls_desc;
55         int flags;
56         int state;
57         struct uth_join_ctl join_ctl;
58         struct sigstate sigstate;
59         int notif_disabled_depth;
60         TAILQ_ENTRY(uthread) sync_next;
61         struct syscall *sysc;   /* syscall we're blocking on, if any */
62         struct syscall local_sysc;      /* for when we don't want to use the stack */
63         void (*yield_func)(struct uthread*, void*);
64         void *yield_arg;
65         int err_no;
66         char err_str[MAX_ERRSTR_LEN];
67 };
68 TAILQ_HEAD(uth_tailq, uthread);
69
70 extern __thread struct uthread *current_uthread;
71
72
73 /* This struct is undefined.  We use it instead of void * so we can get
74  * compiler warnings if someone passes the wrong pointer type.  Internally, 2LSs
75  * and the default implementation use another object type. */
76 typedef struct __uth_sync_opaque * uth_sync_t;
77
78 /* 2LS-independent synchronization code (e.g. uthread mutexes) uses these
79  * helpers to access 2LS-specific functions.
80  *
81  * Note the spinlock associated with the higher-level sync primitive is held for
82  * these (where applicable). */
83 uth_sync_t __uth_sync_alloc(void);
84 void __uth_sync_free(uth_sync_t sync);
85 struct uthread *__uth_sync_get_next(uth_sync_t sync);
86 bool __uth_sync_get_uth(uth_sync_t sync, struct uthread *uth);
87 /* 2LSs that use default sync objs will call this in their has_blocked op. */
88 void __uth_default_sync_enqueue(struct uthread *uth, uth_sync_t sync);
89
90 /* 2L-Scheduler operations.  Examples in pthread.c. */
91 struct schedule_ops {
92         /**** These functions must be defined ****/
93         /* Functions supporting thread ops */
94         void (*sched_entry)(void);
95         void (*thread_runnable)(struct uthread *);
96         void (*thread_paused)(struct uthread *);
97         void (*thread_blockon_sysc)(struct uthread *, void *);
98         void (*thread_has_blocked)(struct uthread *, uth_sync_t, int);
99         void (*thread_refl_fault)(struct uthread *, struct user_context *);
100         void (*thread_exited)(struct uthread *);
101         struct uthread *(*thread_create)(void *(*)(void *), void *);
102         /**** Defining these functions is optional. ****/
103         uth_sync_t (*sync_alloc)(void);
104         void (*sync_free)(uth_sync_t);
105         struct uthread *(*sync_get_next)(uth_sync_t);
106         bool (*sync_get_uth)(uth_sync_t, struct uthread *);
107         /* Functions event handling wants */
108         void (*preempt_pending)(void);
109 };
110 extern struct schedule_ops *sched_ops;
111
112 /* Low-level _S code calls this for basic uthreading without a 2LS */
113 void uthread_lib_init(void);
114 /* Call this from your 2LS init routines.  Pass it a uthread representing
115  * thread0, your 2LS ops, and your syscall handler + data.
116  *
117  * When it returns, you're in _M mode (thread0 on vcore0) */
118 void uthread_2ls_init(struct uthread *uthread, struct schedule_ops *ops,
119                       void (*handle_sysc)(struct event_msg *, unsigned int,
120                                           void *),
121                       void *data);
122 /* Call this to become an mcp capable of worling with uthreads. */
123 void uthread_mcp_init(void);
124
125 /* Functions to make/manage uthreads.  Can be called by functions such as
126  * pthread_create(), which can wrap these with their own stuff (like attrs,
127  * retvals, etc). */
128
129 struct uth_thread_attr {
130         bool want_tls;          /* default, no */
131         bool detached;          /* default, no */
132 };
133
134 struct uth_join_request {
135         struct uthread                          *uth;
136         void                                            **retval_loc;
137 };
138
139 /* uthread_init() does the uthread initialization of a uthread that the caller
140  * created.  Call this whenever you are "starting over" with a thread.  Pass in
141  * attr, if you want to override any defaults. */
142 void uthread_init(struct uthread *new_thread, struct uth_thread_attr *attr);
143 /* uthread_create() is a front-end for getting the 2LS to make and run a thread
144  * appropriate for running func(arg) in the GCC/glibc environment.  The thread
145  * will have TLS and not be detached. */
146 struct uthread *uthread_create(void *(*func)(void *), void *arg);
147 void uthread_detach(struct uthread *uth);
148 void uthread_join(struct uthread *uth, void **retval_loc);
149 void uthread_join_arr(struct uth_join_request reqs[], size_t nr_req);
150
151 /* Call this when you are done with a uthread, forever, but before you free it */
152 void uthread_cleanup(struct uthread *uthread);
153 void uthread_runnable(struct uthread *uthread);
154 void uthread_yield(bool save_state, void (*yield_func)(struct uthread*, void*),
155                    void *yield_arg);
156 void uthread_sleep(unsigned int seconds);
157 void uthread_usleep(unsigned int usecs);
158 void __attribute__((noreturn)) uthread_sleep_forever(void);
159 void uthread_has_blocked(struct uthread *uthread, uth_sync_t sync, int flags);
160 void uthread_paused(struct uthread *uthread);
161
162 /* Utility functions */
163 bool __check_preempt_pending(uint32_t vcoreid); /* careful: check the code */
164 void uth_disable_notifs(void);
165 void uth_enable_notifs(void);
166
167 /* Helpers, which the 2LS can call */
168 void __block_uthread_on_async_sysc(struct uthread *uth);
169 void highjack_current_uthread(struct uthread *uthread);
170 struct uthread *stop_current_uthread(void);
171 void __attribute__((noreturn)) run_current_uthread(void);
172 void __attribute__((noreturn)) run_uthread(struct uthread *uthread);
173 void __attribute__((noreturn)) uth_2ls_thread_exit(void *retval);
174
175 /* Asking for trouble with this API, when we just want stacktop (or whatever
176  * the SP will be). */
177 static inline void init_uthread_ctx(struct uthread *uth, void (*entry)(void),
178                                     void *stack_bottom, uint32_t size)
179 {
180         init_user_ctx(&uth->u_ctx, (long)entry, (long)(stack_bottom) + size);
181 }
182
183 /* When we look at the current_uthread, its context might be in the uthread
184  * struct or it might be in VCPD.  This returns a pointer to the right place. */
185 static inline struct user_context *get_cur_uth_ctx(void)
186 {
187         if (current_uthread->flags & UTHREAD_SAVED)
188                 return &current_uthread->u_ctx;
189         else
190                 return &vcpd_of(vcore_id())->uthread_ctx;
191 }
192
193 #define uthread_set_tls_var(uth, name, val)                                    \
194 ({                                                                             \
195         typeof(val) __val = val;                                                   \
196         begin_access_tls_vars(((struct uthread*)(uth))->tls_desc);                 \
197         name = __val;                                                              \
198         end_access_tls_vars();                                                     \
199 })
200
201 #define uthread_get_tls_var(uth, name)                                         \
202 ({                                                                             \
203         typeof(name) val;                                                          \
204         begin_access_tls_vars(((struct uthread*)(uth))->tls_desc);                 \
205         val = name;                                                                \
206         end_access_tls_vars();                                                     \
207         val;                                                                       \
208 })
209
210 /* Uthread Mutexes / CVs / etc. */
211
212 typedef struct uth_semaphore uth_semaphore_t;
213 typedef struct uth_semaphore uth_mutex_t;
214 typedef struct uth_recurse_mutex uth_recurse_mutex_t;
215 typedef struct uth_cond_var uth_cond_var_t;
216
217 struct uth_semaphore {
218         struct spin_pdr_lock            lock;
219         uth_sync_t                                      sync_obj;
220         unsigned int                            count;
221         parlib_once_t                           once_ctl;
222 };
223 #define UTH_SEMAPHORE_INIT(n) { .once_ctl = PARLIB_ONCE_INIT, .count = (n) }
224 #define UTH_MUTEX_INIT { .once_ctl = PARLIB_ONCE_INIT }
225
226 struct uth_recurse_mutex {
227         uth_mutex_t                                     mtx;
228         struct uthread                          *lockholder;
229         unsigned int                            count;
230         parlib_once_t                           once_ctl;
231 };
232 #define UTH_RECURSE_MUTEX_INIT { .once_ctl = PARLIB_ONCE_INIT }
233
234 struct uth_cond_var {
235         struct spin_pdr_lock            lock;
236         uth_sync_t                                      sync_obj;
237         parlib_once_t                           once_ctl;
238 };
239 #define UTH_COND_VAR_INIT { .once_ctl = PARLIB_ONCE_INIT }
240
241 void uth_semaphore_init(uth_semaphore_t *sem, unsigned int count);
242 void uth_semaphore_destroy(uth_semaphore_t *sem);
243 uth_semaphore_t *uth_semaphore_alloc(unsigned int count);
244 void uth_semaphore_free(uth_semaphore_t *sem);
245 bool uth_semaphore_timed_down(uth_semaphore_t *sem,
246                               const struct timespec *abs_timeout);
247 void uth_semaphore_down(uth_semaphore_t *sem);
248 bool uth_semaphore_trydown(uth_semaphore_t *sem);
249 void uth_semaphore_up(uth_semaphore_t *sem);
250
251 void uth_mutex_init(uth_mutex_t *m);
252 void uth_mutex_destroy(uth_mutex_t *m);
253 uth_mutex_t *uth_mutex_alloc(void);
254 void uth_mutex_free(uth_mutex_t *m);
255 bool uth_mutex_timed_lock(uth_mutex_t *m, const struct timespec *abs_timeout);
256 void uth_mutex_lock(uth_mutex_t *m);
257 bool uth_mutex_trylock(uth_mutex_t *m);
258 void uth_mutex_unlock(uth_mutex_t *m);
259
260 void uth_recurse_mutex_init(uth_recurse_mutex_t *r_m);
261 void uth_recurse_mutex_destroy(uth_recurse_mutex_t *r_m);
262 uth_recurse_mutex_t *uth_recurse_mutex_alloc(void);
263 void uth_recurse_mutex_free(uth_recurse_mutex_t *r_m);
264 bool uth_recurse_mutex_timed_lock(uth_recurse_mutex_t *m,
265                                   const struct timespec *abs_timeout);
266 void uth_recurse_mutex_lock(uth_recurse_mutex_t *r_m);
267 bool uth_recurse_mutex_trylock(uth_recurse_mutex_t *r_m);
268 void uth_recurse_mutex_unlock(uth_recurse_mutex_t *r_m);
269
270 /* Callers to cv_wait must hold the mutex, which it will atomically wait and
271  * unlock, then relock when it returns.  Callers to signal and broadcast may
272  * hold the mutex, if they choose. */
273 void uth_cond_var_init(uth_cond_var_t *cv);
274 void uth_cond_var_destroy(uth_cond_var_t *cv);
275 uth_cond_var_t *uth_cond_var_alloc(void);
276 void uth_cond_var_free(uth_cond_var_t *cv);
277 bool uth_cond_var_timed_wait(uth_cond_var_t *cv, uth_mutex_t *m,
278                              const struct timespec *abs_timeout);
279 void uth_cond_var_wait(uth_cond_var_t *cv, uth_mutex_t *m);
280 bool uth_cond_var_timed_wait_recurse(uth_cond_var_t *cv,
281                                      uth_recurse_mutex_t *r_mtx,
282                                      const struct timespec *abs_timeout);
283 void uth_cond_var_wait_recurse(uth_cond_var_t *cv, uth_recurse_mutex_t *r_mtx);
284 void uth_cond_var_signal(uth_cond_var_t *cv);
285 void uth_cond_var_broadcast(uth_cond_var_t *cv);
286
287 /* Called by gcc to see if we are multithreaded. */
288 bool uth_2ls_is_multithreaded(void);
289
290 __END_DECLS