osfmk/mach/thread_act.defs

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