osfmk/mach/thread_act.defs

   1 /*
   2  * Copyright (c) 2000-2007 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*
  29  * @OSF_FREE_COPYRIGHT@
  30  */
  31 /*
  32  * Mach Operating System
  33  * Copyright (c) 1991,1990,1989 Carnegie Mellon University
  34  * All Rights Reserved.
  35  *
  36  * Permission to use, copy, modify and distribute this software and its
  37  * documentation is hereby granted, provided that both the copyright
  38  * notice and this permission notice appear in all copies of the
  39  * software, derivative works or modified versions, and any portions
  40  * thereof, and that both notices appear in supporting documentation.
  41  *
  42  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  43  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  44  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  45  *
  46  * Carnegie Mellon requests users of this software to return to
  47  *
  48  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  49  *  School of Computer Science
  50  *  Carnegie Mellon University
  51  *  Pittsburgh PA 15213-3890
  52  *
  53  * any improvements or extensions that they make and grant Carnegie Mellon
  54  * the rights to redistribute these changes.
  55  */
  56 /*
  57  */
  58 /*
  59  *      File:   mach/mach_port.defs
  60  *      Author: Rich Draves
  61  *
  62  *      Exported kernel calls.
  63  */
  64
  65 subsystem
  66 #if     KERNEL_SERVER
  67           KernelServer
  68 #endif  /* KERNEL_SERVER */
  69           thread_act 3600;
  70
  71 #include <mach/std_types.defs>
  72 #include <mach/mach_types.defs>
  73
  74 #if !KERNEL && !LIBSYSCALL_INTERFACE
  75 #define PREFIX(NAME) _kernelrpc_ ## NAME
  76 #else
  77 #define PREFIX(NAME) NAME
  78 #endif
  79
  80 /*
  81  *      Destroy the target thread.
  82  *
  83  *      JMM - For legacy reasons this consumes a reference to the
  84  *      target thread.  This will have to change in the future because
  85  *      we want the interfaces to be able to be defined in more standard
  86  *      IDLs and transports, and most of them do not support the notion
  87  *      of reference ownership transfers (just sharing).
  88  */
  89 routine thread_terminate(
  90                 target_act      : thread_act_consume_ref_t);
  91
  92
  93 /*
  94  *      Return the selected state information for the target
  95  *      thr_act.  If the thr_act is currently executing, the results
  96  *      may be stale.  [Flavor THREAD_STATE_FLAVOR_LIST provides a
  97  *      list of valid flavors for the target thread.]
  98  */
  99 routine
 100 #ifdef KERNEL_SERVER
 101 act_get_state_to_user(
 102 #else
 103 act_get_state(
 104 #endif
 105                 target_act      : thread_read_t;
 106                 flavor          : int;
 107         out     old_state       : thread_state_t, CountInOut);
 108
 109 /*
 110  *      Set the selected state information for the target thread.
 111  *      If the thread is currently executing, the state change
 112  *      may be ill-defined.
 113  */
 114 routine
 115 #ifdef KERNEL_SERVER
 116 act_set_state_from_user(
 117 #else
 118 act_set_state(
 119 #endif
 120                 target_act      : thread_act_t;
 121                 flavor          : int;
 122                 new_state       : thread_state_t);
 123
 124 /*
 125  * Backward compatible old-style thread routines.
 126  * These have different semantics than the new activation versions.
 127  *
 128  *      Return the selected state information for the target
 129  *      thread.  If the thread is currently executing, the results
 130  *      may be stale.  [Flavor THREAD_STATE_FLAVOR_LIST provides a
 131  *      list of valid flavors for the target thr_act.]
 132  */
 133 routine
 134 #ifdef KERNEL_SERVER
 135 thread_get_state_to_user(
 136 #else
 137 thread_get_state(
 138 #endif
 139                 target_act      : thread_read_t;
 140                 flavor          : thread_state_flavor_t;
 141         out     old_state       : thread_state_t, CountInOut);
 142
 143 /*
 144  *      Set the selected state information for the target thread.
 145  *      If the thread is currently executing, the state change
 146  *      may be ill-defined.
 147  */
 148 routine
 149 #ifdef KERNEL_SERVER
 150 thread_set_state_from_user(
 151 #else
 152 thread_set_state(
 153 #endif
 154                 target_act      : thread_act_t;
 155                 flavor          : thread_state_flavor_t;
 156                 new_state       : thread_state_t);
 157
 158 /*
 159  *      Increment the suspend count for the target thread.
 160  *      Once this call has completed, the thread will not
 161  *      execute any further user or meta- instructions.
 162  *      Once suspended, a thread may not execute again until
 163  *      its suspend count is zero, and the suspend count
 164  *      for its task is also zero.
 165  */
 166 routine thread_suspend(
 167                 target_act      : thread_read_t);
 168
 169 /*
 170  *      Decrement the suspend count for the target thread,
 171  *      if that count is not already zero.
 172  */
 173 routine thread_resume(
 174                 target_act      : thread_read_t);
 175
 176 /*
 177  *      Cause any user or meta- instructions currently being
 178  *      executed by the target thread to be aborted.  [Meta-
 179  *      instructions consist of the basic traps for IPC
 180  *      (e.g., msg_send, msg_receive) and self-identification
 181  *      (e.g., task_self, thread_self, thread_reply).  Calls
 182  *      described by MiG interfaces are not meta-instructions
 183  *      themselves.]
 184  */
 185 routine thread_abort(
 186                 target_act      : thread_act_t);
 187
 188 /*
 189  *      Cause any user or meta- instructions currently being
 190  *      executed by the target thread to be aborted so that
 191  *      they are transparently restartable.  This call fails
 192  *      if the abort would result in a non-restartable condition.
 193  *      Retry is the caller's responsibility.  [Meta-
 194  *      instructions consist of the basic traps for IPC
 195  *      (e.g., msg_send, msg_receive) and self-identification
 196  *      (e.g., task_self, thread_self, thread_reply).  Calls
 197  *      described by MiG interfaces are not meta-instructions
 198  *      themselves.]
 199  */
 200 routine thread_abort_safely(
 201                 target_act      : thread_act_t);
 202
 203
 204 routine
 205 #ifdef KERNEL_SERVER
 206 thread_depress_abort_from_user(
 207 #else
 208 thread_depress_abort(
 209 #endif
 210                 thread          : thread_act_t);
 211
 212
 213 /*
 214  *      Returns the current value of the selected special port
 215  *      associated with the target thread.
 216  */
 217 routine
 218 #ifdef KERNEL_SERVER
 219 thread_get_special_port_from_user(
 220                 port            : mach_port_t;
 221 #else
 222 thread_get_special_port(
 223                 thr_act         : thread_inspect_t;
 224 #endif
 225                 which_port      : int;
 226         out     special_port    : mach_port_t);
 227
 228
 229 /*
 230  *      Set one of the special ports associated with the
 231  *      target thread.
 232  */
 233 routine thread_set_special_port(
 234                 thr_act         : thread_act_t;
 235                 which_port      : int;
 236                 special_port    : mach_port_t);
 237
 238 /*
 239  *      Returns information about the target thread.
 240  */
 241 routine thread_info(
 242                 target_act      : thread_inspect_t;
 243                 flavor          : thread_flavor_t;
 244         out     thread_info_out : thread_info_t, CountInOut);
 245
 246 /*
 247  * Set an exception handler for a thread on one or more exception types
 248  */
 249 routine         thread_set_exception_ports(
 250                         thread          : thread_act_t;
 251                         exception_mask  : exception_mask_t;
 252                         new_port        : mach_port_t;
 253                         behavior        : exception_behavior_t;
 254                         new_flavor      : thread_state_flavor_t);
 255
 256 /*
 257  * Lookup some of the old exception handlers for a thread
 258  */
 259 routine
 260 #if KERNEL_SERVER
 261 thread_get_exception_ports_from_user(
 262                         port        : mach_port_t;
 263 #else
 264 thread_get_exception_ports(
 265                         thread          : thread_act_t;
 266 #endif
 267                         exception_mask  : exception_mask_t;
 268                   out   masks           : exception_mask_array_t;
 269                   out   old_handlers    : exception_handler_array_t, SameCount;
 270                   out   old_behaviors   : exception_behavior_array_t, SameCount;
 271                   out   old_flavors     : exception_flavor_array_t, SameCount);
 272
 273 /*
 274  * Set an exception handler for a thread on one or more exception types.
 275  * At the same time, return the previously defined exception handlers for
 276  * those types.
 277  */
 278 routine         thread_swap_exception_ports(
 279                         thread          : thread_act_t;
 280                         exception_mask  : exception_mask_t;
 281                         new_port        : mach_port_t;
 282                         behavior        : exception_behavior_t;
 283                         new_flavor      : thread_state_flavor_t;
 284                   out   masks           : exception_mask_array_t;
 285                   out   old_handlers    : exception_handler_array_t, SameCount;
 286                   out   old_behaviors   : exception_behavior_array_t, SameCount;
 287                   out   old_flavors     : exception_flavor_array_t, SameCount);
 288
 289 /*
 290  * OBSOLETE interface.
 291  */
 292 routine PREFIX(thread_policy)(
 293         thr_act                 : thread_act_t;
 294         policy                  : policy_t;
 295         base                    : policy_base_t;
 296         set_limit               : boolean_t);
 297
 298 /*
 299  * Set/get policy information for a thread.
 300  * (Approved Mac OS X microkernel interface)
 301  */
 302
 303 routine PREFIX(thread_policy_set)(
 304         thread                  : thread_act_t;
 305         flavor                  : thread_policy_flavor_t;
 306         policy_info             : thread_policy_t);
 307
 308 routine thread_policy_get(
 309         thread                  : thread_inspect_t;
 310         flavor                  : thread_policy_flavor_t;
 311 out     policy_info             : thread_policy_t, CountInOut;
 312 inout   get_default             : boolean_t);
 313
 314 /*
 315  *      Removed from the kernel.
 316  */
 317 #if KERNEL_SERVER
 318 skip;
 319 #else
 320 routine thread_sample(
 321                 thread          : thread_act_t;
 322                 reply           : mach_port_make_send_t);
 323 #endif
 324
 325 /*
 326  *      ETAP has been removed from the kernel.
 327  */
 328 #if KERNEL_SERVER
 329 skip;
 330 #else
 331 routine etap_trace_thread(
 332                 target_act      : thread_act_t;
 333                 trace_status    : boolean_t);
 334 #endif
 335
 336 /*
 337  *      Assign thread to processor set.
 338  */
 339 routine thread_assign(
 340                 thread          : thread_act_t;
 341                 new_set         : processor_set_t);
 342
 343 /*
 344  *      Assign thread to default set.
 345  */
 346 routine thread_assign_default(
 347                 thread          : thread_act_t);
 348
 349 /*
 350  *      Get current assignment for thread.
 351  */
 352 routine thread_get_assignment(
 353                 thread          : thread_inspect_t;
 354         out     assigned_set    : processor_set_name_t);
 355
 356 /*
 357  * OBSOLETE interface.
 358  */
 359 routine PREFIX(thread_set_policy)(
 360                 thr_act         : thread_act_t;
 361                 pset            : processor_set_t;
 362                 policy          : policy_t;
 363                 base            : policy_base_t;
 364                 limit           : policy_limit_t);
 365
 366 routine thread_get_mach_voucher(
 367                 thr_act         : thread_read_t;
 368                 which           : mach_voucher_selector_t;
 369         out     voucher         : ipc_voucher_t);
 370
 371 routine thread_set_mach_voucher(
 372                 thr_act         : thread_act_t;
 373                 voucher         : ipc_voucher_t);
 374
 375 routine thread_swap_mach_voucher(
 376                 thr_act         : thread_act_t;
 377                 new_voucher     : ipc_voucher_t;
 378         inout   old_voucher     : ipc_voucher_t);
 379
 380 routine thread_convert_thread_state(
 381                 thread          : thread_act_t;
 382                 direction       : int;
 383                 flavor          : thread_state_flavor_t;
 384                 in_state        : thread_state_t;
 385         out     out_state       : thread_state_t, CountInOut);
 386
 387 #ifdef XNU_KERNEL_PRIVATE
 388         skip;
 389 #else
 390         skip;
 391 #endif /* XNU_KERNEL_PRIVATE */
 392
 393 routine thread_get_exception_ports_info(
 394                 port : mach_port_t;
 395                 exception_mask  : exception_mask_t;
 396         out     masks           : exception_mask_array_t;
 397         out     old_handlers_info       : exception_handler_info_array_t, SameCount;
 398         out     old_behaviors   : exception_behavior_array_t, SameCount;
 399         out     old_flavors     : exception_flavor_array_t, SameCount);
 400
 401 /* vim: set ft=c : */