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