osfmk/mach/task.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           task 3400;
  67
  68 #include <mach/std_types.defs>
  69 #include <mach/mach_types.defs>
  70 /*
  71  *      Create a new task with an empty set of IPC rights,
  72  *      and having an address space constructed from the
  73  *      target task (or empty, if inherit_memory is FALSE).
  74  */
  75 routine task_create(
  76                 target_task     : task_t;
  77                 ledgers         : ledger_array_t;
  78                 inherit_memory  : boolean_t;
  79         out     child_task      : task_t);
  80
  81 /*
  82  *      Destroy the target task, causing all of its threads
  83  *      to be destroyed, all of its IPC rights to be deallocated,
  84  *      and all of its address space to be deallocated.
  85  */
  86 routine task_terminate(
  87                 target_task     : task_t);
  88
  89 /*
  90  *      Returns the set of threads belonging to the target task.
  91  */
  92 routine task_threads(
  93                 target_task     : task_t;
  94         out     act_list        : thread_act_array_t);
  95
  96 /*
  97  *      Stash a handful of ports for the target task; child
  98  *      tasks inherit this stash at task_create time.
  99  */
 100 routine mach_ports_register(
 101                 target_task     : task_t;
 102                 init_port_set   : mach_port_array_t =
 103                                         ^array[] of mach_port_t);
 104
 105 /*
 106  *      Retrieve the stashed ports for the target task.
 107  */
 108 routine mach_ports_lookup(
 109                 target_task     : task_t;
 110         out     init_port_set   : mach_port_array_t =
 111                                         ^array[] of mach_port_t);
 112
 113 /*
 114  *      Returns information about the target task.
 115  */
 116 routine task_info(
 117                 target_task     : task_t;
 118                 flavor          : task_flavor_t;
 119         out     task_info_out   : task_info_t, CountInOut);
 120
 121 /*
 122  * Set task information.
 123  */
 124 routine task_set_info(
 125                 target_task     : task_t;
 126                 flavor          : task_flavor_t;
 127                 task_info_in    : task_info_t);
 128
 129 /*
 130  *      Increment the suspend count for the target task.
 131  *      No threads within a task may run when the suspend
 132  *      count for that task is non-zero.
 133  */
 134 routine task_suspend(
 135                 target_task     : task_t);
 136
 137
 138 /*
 139  *      Decrement the suspend count for the target task,
 140  *      if the count is currently non-zero.  If the resulting
 141  *      suspend count is zero, then threads within the task
 142  *      that also have non-zero suspend counts may execute.
 143  */
 144 routine task_resume(
 145                 target_task     : task_t);
 146
 147 /*
 148  *      Returns the current value of the selected special port
 149  *      associated with the target task.
 150  */
 151 routine task_get_special_port(
 152                 task            : task_t;
 153                 which_port      : int;
 154         out     special_port    : mach_port_t);
 155
 156 /*
 157  *      Set one of the special ports associated with the
 158  *      target task.
 159  */
 160 routine task_set_special_port(
 161                 task            : task_t;
 162                 which_port      : int;
 163                 special_port    : mach_port_t);
 164
 165 /*
 166  *      Create a new thread within the target task, returning
 167  *      the port representing the first thr_act in that new thread.  The
 168  *      initial execution state of the thread is undefined.
 169  */
 170 routine thread_create(
 171                 parent_task     : task_t;
 172         out     child_act       : thread_act_t);
 173
 174 /*
 175  *      Create a new thread within the target task, returning
 176  *      the port representing that new thread.  The new thread
 177  *      is not suspended; its initial execution state is given
 178  *      by flavor and new_state. Returns the port representing
 179  *      the new thread.
 180  */
 181 routine thread_create_running(
 182                 parent_task     : task_t;
 183                 flavor          : thread_state_flavor_t;
 184                 new_state       : thread_state_t;
 185         out     child_act       : thread_act_t);
 186
 187 /*
 188  * Set an exception handler for a task on one or more exception types.
 189  * These handlers are invoked for all threads in the task if there are
 190  * no thread-specific exception handlers or those handlers returned an
 191  * error.
 192  */
 193 routine task_set_exception_ports(
 194                 task            : task_t;
 195                 exception_mask  : exception_mask_t;
 196                 new_port        : mach_port_t;
 197                 behavior        : exception_behavior_t;
 198                 new_flavor      : thread_state_flavor_t);
 199
 200
 201 /*
 202  * Lookup some of the old exception handlers for a task
 203  */
 204 routine task_get_exception_ports(
 205                 task            : task_t;
 206                 exception_mask  : exception_mask_t;
 207           out   masks           : exception_mask_array_t;
 208           out   old_handlers    : exception_handler_array_t, SameCount;
 209           out   old_behaviors   : exception_behavior_array_t, SameCount;
 210           out   old_flavors     : exception_flavor_array_t, SameCount);
 211
 212
 213 /*
 214  * Set an exception handler for a thread on one or more exception types.
 215  * At the same time, return the previously defined exception handlers for
 216  * those types.
 217  */
 218 routine task_swap_exception_ports(
 219                 task            : task_t;
 220                 exception_mask  : exception_mask_t;
 221                 new_port        : mach_port_t;
 222                 behavior        : exception_behavior_t;
 223                 new_flavor      : thread_state_flavor_t;
 224           out   masks           : exception_mask_array_t;
 225           out   old_handlerss   : exception_handler_array_t, SameCount;
 226           out   old_behaviors   : exception_behavior_array_t, SameCount;
 227           out   old_flavors     : exception_flavor_array_t, SameCount);
 228
 229 /*
 230  * Create and destroy lock_set and semaphore synchronizers on a
 231  * per-task basis (i.e. the task owns them).
 232  */
 233 routine lock_set_create(
 234                 task            : task_t;
 235         out     new_lock_set    : lock_set_t;
 236                 n_ulocks        : int;
 237                 policy          : int);
 238
 239 routine lock_set_destroy(
 240                 task            : task_t;
 241                 lock_set        : lock_set_t);
 242
 243 routine semaphore_create(
 244                 task            : task_t;
 245         out     semaphore       : semaphore_t;
 246                 policy          : int;
 247                 value           : int);
 248
 249 routine semaphore_destroy(
 250                 task            : task_t;
 251                 semaphore       : semaphore_consume_ref_t);
 252
 253 /*
 254  * Set/get policy information for a task.
 255  * (Approved Mac OS X microkernel interface)
 256  */
 257
 258 routine task_policy_set(
 259         task                    : task_t;
 260         flavor                  : task_policy_flavor_t;
 261         policy_info             : task_policy_t);
 262
 263 routine task_policy_get(
 264         task                    : task_t;
 265         flavor                  : task_policy_flavor_t;
 266 out     policy_info             : task_policy_t, CountInOut;
 267 inout   get_default             : boolean_t);
 268
 269 /*
 270  * Task profiling.
 271  */
 272 routine task_sample(
 273                 task            : task_t;
 274                 reply           : mach_port_make_send_t);
 275
 276 /*
 277  * JMM - Everything from here down is likely to go away soon
 278  */
 279 /*
 280  * OBSOLETE interface.
 281  */
 282 routine task_policy(
 283         task                    : task_t;
 284         policy                  : policy_t;
 285         base                    : policy_base_t;
 286         set_limit               : boolean_t;
 287         change                  : boolean_t);
 288
 289
 290 /*
 291  *      Establish a user-level handler for the specified
 292  *      system call.
 293  */
 294 routine task_set_emulation(
 295                 target_port     : task_t;
 296                 routine_entry_pt: vm_address_t;
 297                 routine_number  : int);
 298
 299 /*
 300  *      Get user-level handler entry points for all
 301  *      emulated system calls.
 302  */
 303 routine task_get_emulation_vector(
 304                 task            : task_t;
 305         out     vector_start    : int;
 306         out     emulation_vector: emulation_vector_t);
 307
 308 /*
 309  *      Establish user-level handlers for the specified
 310  *      system calls. Non-emulated system calls are specified
 311  *      with emulation_vector[i] == EML_ROUTINE_NULL.
 312  */
 313 routine task_set_emulation_vector(
 314                 task            : task_t;
 315                 vector_start    : int;
 316                 emulation_vector: emulation_vector_t);
 317
 318
 319 /*
 320  *      Establish restart pc for interrupted atomic sequences.
 321  */
 322 routine task_set_ras_pc(
 323                 target_task     : task_t;
 324                 basepc          : vm_address_t;
 325                 boundspc        : vm_address_t);
 326
 327
 328 /*
 329  * JMM - Want to eliminate kernel tasks and processor_set so
 330  * keep them at the end.
 331  */
 332 /*
 333  *      Create a new task in the kernel's address space with
 334  *      an empty set of IPC rights, with a map allocated from
 335  *      the kernel's map starting at map_base of length map_size.
 336  */
 337 routine kernel_task_create(
 338                 target_task     : task_t;
 339                 map_base        : vm_offset_t;
 340                 map_size        : vm_size_t;
 341         out     child_task      : task_t);
 342
 343 /*
 344  *      Assign task to processor set.
 345  */
 346 routine task_assign(
 347                 task            : task_t;
 348                 new_set         : processor_set_t;
 349                 assign_threads  : boolean_t);
 350
 351 /*
 352  *      Assign task to default set.
 353  */
 354 routine task_assign_default(
 355                 task            : task_t;
 356                 assign_threads  : boolean_t);
 357
 358 /*
 359  *      Get current assignment for task.
 360  */
 361 routine task_get_assignment(
 362                 task            : task_t;
 363         out     assigned_set    : processor_set_name_t);
 364
 365 /*
 366  * OBSOLETE interface.
 367  */
 368 routine task_set_policy(
 369         task                    : task_t;
 370         pset                    : processor_set_t;
 371         policy                  : policy_t;
 372         base                    : policy_base_t;
 373         limit                   : policy_limit_t;
 374         change                  : boolean_t);
 375