osfmk/kern/sched_prim.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23  * @OSF_COPYRIGHT@
  24  */
  25 /*
  26  * Mach Operating System
  27  * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
  28  * All Rights Reserved.
  29  *
  30  * Permission to use, copy, modify and distribute this software and its
  31  * documentation is hereby granted, provided that both the copyright
  32  * notice and this permission notice appear in all copies of the
  33  * software, derivative works or modified versions, and any portions
  34  * thereof, and that both notices appear in supporting documentation.
  35  *
  36  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  37  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  38  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  39  *
  40  * Carnegie Mellon requests users of this software to return to
  41  *
  42  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  43  *  School of Computer Science
  44  *  Carnegie Mellon University
  45  *  Pittsburgh PA 15213-3890
  46  *
  47  * any improvements or extensions that they make and grant Carnegie Mellon
  48  * the rights to redistribute these changes.
  49  */
  50 /*
  51  */
  52 /*
  53  *      File:   sched_prim.h
  54  *      Author: David Golub
  55  *
  56  *      Scheduling primitive definitions file
  57  *
  58  */
  59
  60 #ifndef _KERN_SCHED_PRIM_H_
  61 #define _KERN_SCHED_PRIM_H_
  62
  63 #include <mach/boolean.h>
  64 #include <mach/machine/vm_types.h>
  65 #include <mach/kern_return.h>
  66 #include <kern/clock.h>
  67 #include <kern/kern_types.h>
  68 #include <kern/thread.h>
  69 #include <kern/lock.h>
  70 #include <kern/time_out.h>      /*** ??? temp - remove me soon ***/
  71 #include <kern/cpu_data.h>
  72 #include <kern/wait_queue.h>
  73
  74 #ifdef MACH_KERNEL_PRIVATE
  75
  76 #include <mach_ldebug.h>
  77 /*
  78  *      Exported interface to sched_prim.c.
  79  *      A few of these functions are actually defined in
  80  *      ipc_sched.c, for historical reasons.
  81  */
  82
  83 /* Initialize scheduler module */
  84 extern void             sched_init(void);
  85
  86 /*
  87  * Set up thread timeout element(s) when thread is created.
  88  */
  89 extern void             thread_timer_setup(
  90                                         thread_t                thread);
  91
  92 extern void             thread_timer_terminate(void);
  93
  94 #define thread_bind_locked(thread, processor)   \
  95                 (thread)->bound_processor = (processor)
  96
  97 /*
  98  * Prevent a thread from restarting after it blocks interruptibly
  99  */
 100 extern boolean_t        thread_stop(
 101                                                 thread_t        thread);
 102
 103 /*
 104  * wait for a thread to stop
 105  */
 106 extern boolean_t        thread_wait(
 107                                                 thread_t        thread);
 108
 109 /* Select a thread to run on a particular processor */
 110 extern thread_t thread_select(
 111                                                 processor_t     myprocessor);
 112
 113 extern void             thread_go_locked(
 114                                                 thread_t        thread,
 115                                                 int             result);
 116
 117 /* Stop old thread and run new thread */
 118 extern boolean_t thread_invoke(
 119                                                 thread_t        old_thread,
 120                                                 thread_t        new_thread,
 121                                                 int                     reason,
 122                                                 void        (*continuation)(void));
 123
 124 /* Called when current thread is given new stack */
 125 extern void             thread_continue(
 126                                                 thread_t        old_thread);
 127
 128 /* Switch directly to a particular thread */
 129 extern int              thread_run(
 130                                                 thread_t        old_thread,
 131                                                 void            (*continuation)(void),
 132                                                 thread_t        new_thread);
 133
 134 /* Dispatch a thread not on a run queue */
 135 extern void             thread_dispatch(
 136                                                 thread_t        thread);
 137
 138 /* Invoke continuation */
 139 extern void             call_continuation(
 140                                                 void            (*continuation)(void));
 141
 142 /* Compute effective priority of the specified thread */
 143 extern void             compute_priority(
 144                                                 thread_t        thread,
 145                                                 int                     resched);
 146
 147 /* Version of compute_priority for current thread or
 148  * thread being manipuldated by scheduler.
 149  */
 150 extern void             compute_my_priority(
 151                                                 thread_t        thread);
 152
 153 /* Periodic scheduler activity */
 154 extern void             sched_tick_thread(void);
 155
 156 /* Update priority of thread that has been sleeping or suspended.
 157  * Used to "catch up" with the system.
 158  */
 159 extern void             update_priority(
 160                                                 thread_t        thread);
 161
 162 /* Idle thread loop */
 163 extern void             idle_thread(void);
 164
 165 /*
 166  *      thread_sleep_interlock:
 167  *
 168  *      Cause the current thread to wait until the specified event
 169  *      occurs.  The specified HW interlock is unlocked before releasing
 170  *      the cpu.  (This is a convenient way to sleep without manually
 171  *      calling assert_wait).
 172  */
 173
 174 #define thread_sleep_interlock(event, lock, interruptible)      \
 175 MACRO_BEGIN                                                                                                     \
 176         assert_wait(event, interruptible);                                              \
 177         interlock_unlock(lock);                                                                 \
 178         thread_block((void (*)(void)) 0);                                               \
 179 MACRO_END
 180
 181 /*
 182  *      Machine-dependent code must define these functions.
 183  */
 184
 185 /* Start thread running */
 186 extern void             thread_bootstrap_return(void);
 187
 188 /* Return from exception */
 189 extern void             thread_exception_return(void);
 190
 191 /* Continuation return from syscall */
 192 extern void     thread_syscall_return(
 193                         kern_return_t   ret);
 194
 195 extern thread_t switch_context(
 196                                                 thread_t        old_thread,
 197                                                 void            (*continuation)(void),
 198                                                 thread_t        new_thread);
 199
 200 /* Attach stack to thread */
 201 extern void             machine_kernel_stack_init(
 202                                                 thread_t        thread,
 203                                                 void            (*start_pos)(thread_t));
 204
 205 extern void             load_context(
 206                                                 thread_t        thread);
 207
 208 extern thread_act_t             switch_act(
 209                                                         thread_act_t    act);
 210
 211 extern void             machine_switch_act(
 212                                                         thread_t                thread,
 213                                                         thread_act_t    old,
 214                                                         thread_act_t    new,
 215                                                         int                             cpu);
 216
 217 /*
 218  *      These functions are either defined in kern/thread.c
 219  *      or are defined directly by machine-dependent code.
 220  */
 221
 222 /* Allocate an activation stack */
 223 extern vm_offset_t      stack_alloc(thread_t thread, void (*start_pos)(thread_t));
 224
 225 /* Free an activation stack */
 226 extern void             stack_free(thread_t thread);
 227
 228 /* Collect excess kernel stacks */
 229 extern void             stack_collect(void);
 230
 231 extern void             set_pri(
 232                                         thread_t        thread,
 233                                         int                     pri,
 234                                         boolean_t       resched);
 235
 236 /* Block current thread, indicating reason (Block or Quantum expiration) */
 237 extern int              thread_block_reason(
 238                                                 void            (*continuation)(void),
 239                                                 int             reason);
 240
 241 /* Make thread runnable */
 242 extern void             thread_setrun(
 243                                                 thread_t        thread,
 244                                                 boolean_t       may_preempt,
 245                                                 boolean_t       tail);
 246 /*
 247  *      Flags for thread_setrun()
 248  */
 249
 250 #define HEAD_Q          0               /* FALSE */
 251 #define TAIL_Q          1               /* TRUE */
 252
 253 /* Bind thread to a particular processor */
 254 extern void             thread_bind(
 255                                                 thread_t        thread,
 256                                                 processor_t     processor);
 257
 258 extern void             thread_mark_wait_locked(
 259                                                 thread_t        thread,
 260                                                 int                     interruptible);
 261
 262 #endif /* MACH_KERNEL_PRIVATE */
 263
 264 /*
 265  ****************** Only exported until BSD stops using ********************
 266  */
 267
 268 /*
 269  * Cancel a stop and continue the thread if necessary.
 270  */
 271 extern void             thread_unstop(
 272                                                 thread_t        thread);
 273
 274 /* Wake up thread directly, passing result */
 275 extern void             clear_wait(
 276                                                 thread_t        thread,
 277                                                 int             result);
 278
 279 /* Bind thread to a particular processor */
 280 extern void             thread_bind(
 281                                                 thread_t        thread,
 282                                                 processor_t     processor);
 283
 284
 285 /*
 286  * *********************   PUBLIC APIs ************************************
 287  */
 288
 289 /* Set timer for current thread */
 290 extern void             thread_set_timer(
 291                                         natural_t               interval,
 292                                         natural_t               scale_factor);
 293
 294 extern void             thread_set_timer_deadline(
 295                                         AbsoluteTime    deadline);
 296
 297 extern void             thread_cancel_timer(void);
 298
 299 /*
 300  * thread_stop a thread then wait for it to stop (both of the above)
 301  */
 302 extern boolean_t        thread_stop_wait(
 303                                                 thread_t        thread);
 304
 305 /* Declare thread will wait on a particular event */
 306 extern void             assert_wait(
 307                                                 event_t         event,
 308                                                 int             interruptflag);
 309
 310 /* Assert that the thread intends to wait for a timeout */
 311 extern void             assert_wait_timeout(
 312                                                 natural_t       msecs,
 313                                                 int             interruptflags);
 314
 315 /* Wake up thread (or threads) waiting on a particular event */
 316 extern void             thread_wakeup_prim(
 317                                                 event_t         event,
 318                                                 boolean_t       one_thread,
 319                                                 int             result);
 320
 321 /* Block current thread (Block reason) */
 322 extern int              thread_block(
 323                                                 void            (*continuation)(void));
 324
 325
 326 /*
 327  *      Routines defined as macros
 328  */
 329
 330 #define thread_wakeup(x)                                        \
 331                         thread_wakeup_prim((x), FALSE, THREAD_AWAKENED)
 332 #define thread_wakeup_with_result(x, z)         \
 333                         thread_wakeup_prim((x), FALSE, (z))
 334 #define thread_wakeup_one(x)                            \
 335                         thread_wakeup_prim((x), TRUE, THREAD_AWAKENED)
 336
 337 /*
 338  *      thread_sleep_mutex:
 339  *
 340  *      Cause the current thread to wait until the specified event
 341  *      occurs.  The specified mutex is unlocked before releasing
 342  *      the cpu.  (This is a convenient way to sleep without manually
 343  *      calling assert_wait).
 344  */
 345
 346 #define thread_sleep_mutex(event, lock, interruptible)  \
 347 MACRO_BEGIN                                                                                             \
 348         assert_wait(event, interruptible);                                      \
 349         mutex_unlock(lock);                                                                     \
 350         thread_block((void (*)(void)) 0);                                       \
 351 MACRO_END
 352
 353 /*
 354  *      thread_sleep_simple_lock:
 355  *
 356  *      Cause the current thread to wait until the specified event
 357  *      occurs.  The specified simple_lock is unlocked before releasing
 358  *      the cpu.  (This is a convenient way to sleep without manually
 359  *      calling assert_wait).
 360  */
 361
 362 #define thread_sleep_simple_lock(event, lock, interruptible)    \
 363 MACRO_BEGIN                                                                                                             \
 364         assert_wait(event, interruptible);                                                      \
 365         simple_unlock(lock);                                                                            \
 366         thread_block((void (*)(void)) 0);                                                       \
 367 MACRO_END
 368
 369
 370 #endif  /* _KERN_SCHED_PRIM_H_ */