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
  73 #include <sys/appleapiopts.h>
  74
  75 #ifdef  __APPLE_API_PRIVATE
  76
  77 #ifdef  MACH_KERNEL_PRIVATE
  78
  79 #include <mach_ldebug.h>
  80 /*
  81  *      Exported interface to sched_prim.c.
  82  *      A few of these functions are actually defined in
  83  *      ipc_sched.c, for historical reasons.
  84  */
  85
  86 /* Initialize scheduler module */
  87 extern void             sched_init(void);
  88
  89 extern void             sched_timebase_init(void);
  90
  91 /*
  92  * Set up thread timeout element(s) when thread is created.
  93  */
  94 extern void             thread_timer_setup(
  95                                         thread_t                thread);
  96
  97 extern void             thread_timer_terminate(void);
  98
  99 /*
 100  * Stop a thread and wait for it to stop running.
 101  */
 102 extern boolean_t        thread_stop(
 103                                                 thread_t        thread);
 104
 105 /*
 106  * Wait for a thread to stop running.
 107  */
 108 extern boolean_t        thread_wait(
 109                                                 thread_t        thread);
 110
 111 /* Select a thread to run on a particular processor */
 112 extern thread_t thread_select(
 113                                                 processor_t     myprocessor);
 114
 115 extern kern_return_t thread_go_locked(
 116                                                 thread_t                thread,
 117                                                 wait_result_t   result);
 118
 119 /* Stop old thread and run new thread */
 120 extern boolean_t thread_invoke(
 121                                                 thread_t                old_thread,
 122                                                 thread_t                new_thread,
 123                                                 int                             reason,
 124                                                 thread_continue_t continuation);
 125
 126 /* Called when current thread is given new stack */
 127 extern void             thread_continue(
 128                                                 thread_t                old_thread);
 129
 130 /* Switch directly to a particular thread */
 131 extern int              thread_run(
 132                                                 thread_t                old_thread,
 133                                                 thread_continue_t continuation,
 134                                                 thread_t                new_thread);
 135
 136 /* Dispatch a thread not on a run queue */
 137 extern void             thread_dispatch(
 138                                                 thread_t                thread);
 139
 140 /* Invoke continuation */
 141 extern void             call_continuation(
 142                                                 thread_continue_t continuation);
 143
 144 /* Set the current scheduled priority */
 145 extern void             set_sched_pri(
 146                                         thread_t                thread,
 147                                         int                             priority);
 148
 149 /* Set base priority of the specified thread */
 150 extern void             set_priority(
 151                                         thread_t                thread,
 152                                         int                             priority);
 153
 154 /* Reset scheduled priority of thread */
 155 extern void             compute_priority(
 156                                         thread_t                thread,
 157                                         boolean_t               override_depress);
 158
 159 /* Adjust scheduled priority of thread during execution */
 160 extern void             compute_my_priority(
 161                                         thread_t                thread);
 162
 163 /* Periodic scheduler activity */
 164 extern void             sched_tick_init(void);
 165
 166 /*
 167  * Update thread to the current scheduler tick.
 168  */
 169 extern void             update_priority(
 170                                         thread_t                thread);
 171
 172 /* Idle thread loop */
 173 extern void             idle_thread(void);
 174
 175 /*
 176  *      Machine-dependent code must define these functions.
 177  */
 178
 179 /* Start thread running */
 180 extern void             thread_bootstrap_return(void);
 181
 182 /* Return from exception */
 183 extern void             thread_exception_return(void);
 184
 185 /* Continuation return from syscall */
 186 extern void     thread_syscall_return(
 187                         kern_return_t   ret);
 188
 189 /*
 190  *      These functions are either defined in kern/thread.c
 191  *      or are defined directly by machine-dependent code.
 192  */
 193
 194 /* Block current thread, indicating reason */
 195 extern wait_result_t    thread_block_reason(
 196                                                         thread_continue_t       continuation,
 197                                                         ast_t                           reason);
 198
 199 /* Dispatch a thread for execution */
 200 extern void             thread_setrun(
 201                                         thread_t        thread,
 202                                         integer_t       options);
 203
 204 #define SCHED_TAILQ             0
 205 #define SCHED_HEADQ             1
 206 #define SCHED_PREEMPT   2
 207
 208 /* Bind thread to a particular processor */
 209 extern processor_t              thread_bind(
 210                                                         thread_t                thread,
 211                                                         processor_t             processor);
 212
 213 /* Set the maximum interrupt level for the thread */
 214 __private_extern__ wait_interrupt_t thread_interrupt_level(
 215                                                 wait_interrupt_t interruptible);
 216
 217 __private_extern__ wait_result_t thread_mark_wait_locked(
 218                                                 thread_t                 thread,
 219                                                 wait_interrupt_t interruptible);
 220
 221 /* Sleep, unlocking and then relocking a usimple_lock in the process */
 222 __private_extern__ wait_result_t thread_sleep_fast_usimple_lock(
 223                                                 event_t                 event,
 224                                                 simple_lock_t   lock,
 225                                                 wait_interrupt_t interruptible);
 226
 227 /* Wake up locked thread directly, passing result */
 228 __private_extern__ kern_return_t clear_wait_internal(
 229                                                 thread_t                thread,
 230                                                 wait_result_t   result);
 231
 232 __private_extern__
 233         wait_queue_t    wait_event_wait_queue(
 234                                                 event_t                 event);
 235
 236 #endif /* MACH_KERNEL_PRIVATE */
 237
 238 extern wait_result_t    assert_wait_prim(
 239                                                         event_t                         event,
 240                                                         thread_roust_t          roust_hint,
 241                                                         uint64_t                        deadline,
 242                                                         wait_interrupt_t        interruptible);
 243
 244 /*
 245  ****************** Only exported until BSD stops using ********************
 246  */
 247
 248 /*
 249  * Cancel a stop and unblock the thread if already stopped.
 250  */
 251 extern void             thread_unstop(
 252                                                 thread_t                thread);
 253
 254 /* Wake up thread directly, passing result */
 255 extern kern_return_t clear_wait(
 256                                                 thread_t                thread,
 257                                                 wait_result_t   result);
 258
 259 #endif  /* __APPLE_API_PRIVATE */
 260
 261 /*
 262  * *********************   PUBLIC APIs ************************************
 263  */
 264
 265 /* Set timer for current thread */
 266 extern void             thread_set_timer(
 267                                         uint32_t                interval,
 268                                         uint32_t                scale_factor);
 269
 270 extern void             thread_set_timer_deadline(
 271                                         uint64_t                deadline);
 272
 273 extern void             thread_cancel_timer(void);
 274
 275 /* Declare thread will wait on a particular event */
 276 extern wait_result_t assert_wait(
 277                                                 event_t                  event,
 278                                                 wait_interrupt_t interruptflag);
 279
 280 /* Assert that the thread intends to wait for a timeout */
 281 extern wait_result_t assert_wait_timeout(
 282                                                 natural_t                msecs,
 283                                                 wait_interrupt_t interruptflags);
 284
 285 /* Sleep, unlocking and then relocking a usimple_lock in the process */
 286 extern wait_result_t thread_sleep_usimple_lock(
 287                                                 event_t                 event,
 288                                                 usimple_lock_t  lock,
 289                                                 wait_interrupt_t interruptible);
 290
 291 /* Sleep, unlocking and then relocking a mutex in the process */
 292 extern wait_result_t thread_sleep_mutex(
 293                                                 event_t                 event,
 294                                                 mutex_t                 *mutex,
 295                                                 wait_interrupt_t interruptible);
 296
 297 /* Sleep with a deadline, unlocking and then relocking a mutex in the process */
 298 extern wait_result_t thread_sleep_mutex_deadline(
 299                                                 event_t                 event,
 300                                                 mutex_t                 *mutex,
 301                                                 uint64_t                deadline,
 302                                                 wait_interrupt_t interruptible);
 303
 304 /* Sleep, unlocking and then relocking a write lock in the process */
 305 extern wait_result_t thread_sleep_lock_write(
 306                                                 event_t                 event,
 307                                                 lock_t                  *lock,
 308                                                 wait_interrupt_t interruptible);
 309
 310 /* Sleep, hinting that a thread funnel may be involved in the process */
 311 extern wait_result_t thread_sleep_funnel(
 312                                                 event_t                 event,
 313                                                 wait_interrupt_t interruptible);
 314
 315 /* Wake up thread (or threads) waiting on a particular event */
 316 extern kern_return_t thread_wakeup_prim(
 317                                                 event_t                 event,
 318                                                 boolean_t               one_thread,
 319                                                 wait_result_t   result);
 320
 321 #ifdef  __APPLE_API_UNSTABLE
 322
 323 /* Block current thread (Block reason) */
 324 extern wait_result_t thread_block(
 325                                                 thread_continue_t continuation);
 326
 327 #endif  /* __APPLE_API_UNSTABLE */
 328
 329 /*
 330  *      Routines defined as macros
 331  */
 332
 333 #define thread_wakeup(x)                                        \
 334                         thread_wakeup_prim((x), FALSE, THREAD_AWAKENED)
 335 #define thread_wakeup_with_result(x, z)         \
 336                         thread_wakeup_prim((x), FALSE, (z))
 337 #define thread_wakeup_one(x)                            \
 338                         thread_wakeup_prim((x), TRUE, THREAD_AWAKENED)
 339
 340 #if             !defined(MACH_KERNEL_PRIVATE) && !defined(ABSOLUTETIME_SCALAR_TYPE)
 341
 342 #include <libkern/OSBase.h>
 343
 344 #define thread_set_timer_deadline(a)    \
 345         thread_set_timer_deadline(__OSAbsoluteTime(a))
 346
 347 #endif
 348
 349 #endif  /* _KERN_SCHED_PRIM_H_ */