osfmk/mach/thread_act.defs

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