osfmk/kern/sched_prim.h

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