osfmk/mach/thread_act.defs

   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_FREE_COPYRIGHT@
  27  */
  28 /*
  29  * Mach Operating System
  30  * Copyright (c) 1991,1990,1989 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:   mach/mach_port.defs
  57  *      Author: Rich Draves
  58  *
  59  *      Exported kernel calls.
  60  */
  61
  62 subsystem
  63 #if     KERNEL_SERVER
  64           KernelServer
  65 #endif  KERNEL_SERVER
  66           thread_act 3600;
  67
  68 #include <mach/std_types.defs>
  69 #include <mach/mach_types.defs>
  70
  71 /*
  72  *      Destroy the target thread.
  73  *
  74  *      JMM - For legacy reasons this consumes a reference to the
  75  *      target thread.  This will have to change in the future because
  76  *      we want the interfaces to be able to be defined in more standard
  77  *      IDLs and transports, and most of them do not support the notion
  78  *      of reference ownership transfers (just sharing).
  79  */
  80 routine thread_terminate(
  81                 target_act      : thread_act_consume_ref_t);
  82
  83
  84 /*
  85  *      Return the selected state information for the target
  86  *      thr_act.  If the thr_act is currently executing, the results
  87  *      may be stale.  [Flavor THREAD_STATE_FLAVOR_LIST provides a
  88  *      list of valid flavors for the target thread.]
  89  */
  90 routine act_get_state(
  91                 target_act      : thread_act_t;
  92                 flavor          : int;
  93         out     old_state       : thread_state_t, CountInOut);
  94
  95 /*
  96  *      Set the selected state information for the target thread.
  97  *      If the thread is currently executing, the state change
  98  *      may be ill-defined.
  99  */
 100 routine act_set_state(
 101                 target_act      : thread_act_t;
 102                 flavor          : int;
 103                 new_state       : thread_state_t);
 104
 105 /*
 106  * Backward compatible old-style thread routines.
 107  * These have different semantics than the new activation versions.
 108  *
 109  *      Return the selected state information for the target
 110  *      thread.  If the thread is currently executing, the results
 111  *      may be stale.  [Flavor THREAD_STATE_FLAVOR_LIST provides a
 112  *      list of valid flavors for the target thr_act.]
 113  */
 114 routine thread_get_state(
 115                 target_act      : thread_act_t;
 116                 flavor          : thread_state_flavor_t;
 117         out     old_state       : thread_state_t, CountInOut);
 118
 119 /*
 120  *      Set the selected state information for the target thread.
 121  *      If the thread is currently executing, the state change
 122  *      may be ill-defined.
 123  */
 124 routine thread_set_state(
 125                 target_act      : thread_act_t;
 126                 flavor          : thread_state_flavor_t;
 127                 new_state       : thread_state_t);
 128
 129 /*
 130  *      Increment the suspend count for the target thread.
 131  *      Once this call has completed, the thread will not
 132  *      execute any further user or meta- instructions.
 133  *      Once suspended, a thread may not execute again until
 134  *      its suspend count is zero, and the suspend count
 135  *      for its task is also zero.
 136  */
 137 routine thread_suspend(
 138                 target_act      : thread_act_t);
 139
 140 /*
 141  *      Decrement the suspend count for the target thread,
 142  *      if that count is not already zero.
 143  */
 144 routine thread_resume(
 145                 target_act      : thread_act_t);
 146
 147 /*
 148  *      Cause any user or meta- instructions currently being
 149  *      executed by the target thread to be aborted.  [Meta-
 150  *      instructions consist of the basic traps for IPC
 151  *      (e.g., msg_send, msg_receive) and self-identification
 152  *      (e.g., task_self, thread_self, thread_reply).  Calls
 153  *      described by MiG interfaces are not meta-instructions
 154  *      themselves.]
 155  */
 156 routine thread_abort(
 157                 target_act      : thread_act_t);
 158
 159 /*
 160  *      Cause any user or meta- instructions currently being
 161  *      executed by the target thread to be aborted so that
 162  *      they are transparently restartable.  This call fails
 163  *      if the abort would result in a non-restartable condition.
 164  *      Retry is the caller's responsibility.  [Meta-
 165  *      instructions consist of the basic traps for IPC
 166  *      (e.g., msg_send, msg_receive) and self-identification
 167  *      (e.g., task_self, thread_self, thread_reply).  Calls
 168  *      described by MiG interfaces are not meta-instructions
 169  *      themselves.]
 170  */
 171 routine thread_abort_safely(
 172                 target_act      : thread_act_t);
 173
 174
 175 routine thread_depress_abort(
 176                 thread          : thread_act_t);
 177
 178
 179 /*
 180  *      Returns the current value of the selected special port
 181  *      associated with the target thread.
 182  */
 183 routine thread_get_special_port(
 184                 thr_act         : thread_act_t;
 185                 which_port      : int;
 186         out     special_port    : mach_port_t);
 187
 188 /*
 189  *      Set one of the special ports associated with the
 190  *      target thread.
 191  */
 192 routine thread_set_special_port(
 193                 thr_act         : thread_act_t;
 194                 which_port      : int;
 195                 special_port    : mach_port_t);
 196
 197 /*
 198  *      Returns information about the target thread.
 199  */
 200 routine thread_info(
 201                 target_act      : thread_act_t;
 202                 flavor          : thread_flavor_t;
 203         out     thread_info_out : thread_info_t, CountInOut);
 204
 205 /*
 206  * Set an exception handler for a thread on one or more exception types
 207  */
 208 routine         thread_set_exception_ports(
 209                         thread          : thread_act_t;
 210                         exception_mask  : exception_mask_t;
 211                         new_port        : mach_port_t;
 212                         behavior        : exception_behavior_t;
 213                         new_flavor      : thread_state_flavor_t);
 214
 215 /*
 216  * Lookup some of the old exception handlers for a thread
 217  */
 218 routine         thread_get_exception_ports(
 219                         thread          : thread_act_t;
 220                         exception_mask  : exception_mask_t;
 221                   out   masks           : exception_mask_array_t;
 222                   out   old_handlers    : exception_handler_array_t, SameCount;
 223                   out   old_behaviors   : exception_behavior_array_t, SameCount;
 224                   out   old_flavors     : exception_flavor_array_t, SameCount);
 225
 226 /*
 227  * Set an exception handler for a thread on one or more exception types.
 228  * At the same time, return the previously defined exception handlers for
 229  * those types.
 230  */
 231 routine         thread_swap_exception_ports(
 232                         thread          : thread_act_t;
 233                         exception_mask  : exception_mask_t;
 234                         new_port        : mach_port_t;
 235                         behavior        : exception_behavior_t;
 236                         new_flavor      : thread_state_flavor_t;
 237                   out   masks           : exception_mask_array_t;
 238                   out   old_handlers    : exception_handler_array_t, SameCount;
 239                   out   old_behaviors   : exception_behavior_array_t, SameCount;
 240                   out   old_flavors     : exception_flavor_array_t, SameCount);
 241
 242 /*
 243  * OBSOLETE interface.
 244  */
 245 routine thread_policy(
 246         thr_act                 : thread_act_t;
 247         policy                  : policy_t;
 248         base                    : policy_base_t;
 249         set_limit               : boolean_t);
 250
 251 /*
 252  * Set/get policy information for a thread.
 253  * (Approved Mac OS X microkernel interface)
 254  */
 255
 256 routine thread_policy_set(
 257         thread                  : thread_act_t;
 258         flavor                  : thread_policy_flavor_t;
 259         policy_info             : thread_policy_t);
 260
 261 routine thread_policy_get(
 262         thread                  : thread_act_t;
 263         flavor                  : thread_policy_flavor_t;
 264 out     policy_info             : thread_policy_t, CountInOut;
 265 inout   get_default             : boolean_t);
 266
 267 /*
 268  * Thread profiling
 269  * This call is only valid for MACH_PROF compiled kernels.
 270  * Otherwise, KERN_FAILURE is returned.
 271  */
 272 routine thread_sample(
 273                 thread          : thread_act_t;
 274                 reply           : mach_port_make_send_t);
 275
 276 /*
 277  * JMM - Keep etap and processor_set related things at the end
 278  * because they are likely to be removed.
 279  */
 280 /*
 281  *      Sets the ETAP trace status of the target thread.
 282  */
 283 routine etap_trace_thread(
 284                 target_act      : thread_act_t;
 285                 trace_status    : boolean_t);
 286
 287 /*
 288  *      Assign thread to processor set.
 289  */
 290 routine thread_assign(
 291                 thread          : thread_act_t;
 292                 new_set         : processor_set_t);
 293
 294 /*
 295  *      Assign thread to default set.
 296  */
 297 routine thread_assign_default(
 298                 thread          : thread_act_t);
 299
 300 /*
 301  *      Get current assignment for thread.
 302  */
 303 routine thread_get_assignment(
 304                 thread          : thread_act_t;
 305         out     assigned_set    : processor_set_name_t);
 306
 307
 308 /*
 309  * OBSOLETE interface.
 310  */
 311 routine thread_set_policy(
 312         thr_act                 : thread_act_t;
 313         pset                    : processor_set_t;
 314         policy                  : policy_t;
 315         base                    : policy_base_t;
 316         limit                   : policy_limit_t);