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