osfmk/mach/mach_vm.defs

   1 /*
   2  * Copyright (c) 2004 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_vm.defs
  62  *
  63  *      Exported kernel VM calls (for any task on the platform).
  64  */
  65
  66 subsystem
  67 #if     KERNEL_SERVER
  68           KernelServer
  69 #endif  /* KERNEL_SERVER */
  70 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
  71           mach_vm
  72 #else
  73           vm_map_lp64_local
  74 #endif
  75           4800;
  76
  77 #include <mach/std_types.defs>
  78 #include <mach/mach_types.defs>
  79 #include <mach_debug/mach_debug_types.defs>
  80
  81 /*
  82  *      Allocate zero-filled memory in the address space
  83  *      of the target task, either at the specified address,
  84  *      or wherever space can be found (controlled by flags),
  85  *      of the specified size.  The address at which the
  86  *      allocation actually took place is returned.
  87  */
  88 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
  89 routine mach_vm_allocate(
  90 #else
  91 routine vm_allocate(
  92 #endif
  93                 target          : vm_task_entry_t;
  94         inout   address         : mach_vm_address_t;
  95                 size            : mach_vm_size_t;
  96                 flags           : int);
  97
  98 /*
  99  *      Deallocate the specified range from the virtual
 100  *      address space of the target virtual memory map.
 101  */
 102 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 103 routine mach_vm_deallocate(
 104 #else
 105 routine vm_deallocate(
 106 #endif
 107                 target          : vm_task_entry_t;
 108                 address         : mach_vm_address_t;
 109                 size            : mach_vm_size_t);
 110
 111 /*
 112  *      Set the current or maximum protection attribute
 113  *      for the specified range of the virtual address
 114  *      space of the target virtual memory map.  The current
 115  *      protection limits the memory access rights of threads
 116  *      within the map; the maximum protection limits the accesses
 117  *      that may be given in the current protection.
 118  *      Protections are specified as a set of {read, write, execute}
 119  *      *permissions*.
 120  */
 121 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 122 routine mach_vm_protect(
 123 #else
 124 routine vm_protect(
 125 #endif
 126                 target_task     : vm_task_entry_t;
 127                 address         : mach_vm_address_t;
 128                 size            : mach_vm_size_t;
 129                 set_maximum     : boolean_t;
 130                 new_protection  : vm_prot_t);
 131
 132 /*
 133  *      Set the inheritance attribute for the specified range
 134  *      of the virtual address space of the target address space.
 135  *      The inheritance value is one of {none, copy, share}, and
 136  *      specifies how the child address space should acquire
 137  *      this memory at the time of a task_create call.
 138  */
 139 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 140 routine mach_vm_inherit(
 141 #else
 142 routine vm_inherit(
 143 #endif
 144                 target_task     : vm_task_entry_t;
 145                 address         : mach_vm_address_t;
 146                 size            : mach_vm_size_t;
 147                 new_inheritance : vm_inherit_t);
 148
 149 /*
 150  *      Returns the contents of the specified range of the
 151  *      virtual address space of the target task.  [The
 152  *      range must be aligned on a virtual page boundary,
 153  *      and must be a multiple of pages in extent.  The
 154  *      protection on the specified range must permit reading.]
 155  */
 156 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 157 routine mach_vm_read(
 158 #else
 159 routine vm_read(
 160 #endif
 161                 target_task     : vm_map_t;
 162                 address         : mach_vm_address_t;
 163                 size            : mach_vm_size_t;
 164         out     data            : pointer_t);
 165
 166 /*
 167  * List corrollary to vm_read, returns mapped contents of specified
 168  * ranges within target address space.
 169  */
 170 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 171 routine mach_vm_read_list(
 172 #else
 173 routine vm_read_list(
 174 #endif
 175                 target_task     : vm_map_t;
 176         inout   data_list       : mach_vm_read_entry_t;
 177                 count           : natural_t);
 178
 179 /*
 180  *      Writes the contents of the specified range of the
 181  *      virtual address space of the target task.  [The
 182  *      range must be aligned on a virtual page boundary,
 183  *      and must be a multiple of pages in extent.  The
 184  *      protection on the specified range must permit writing.]
 185  */
 186 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 187 routine mach_vm_write(
 188 #else
 189 routine vm_write(
 190 #endif
 191                 target_task     : vm_map_t;
 192                 address         : mach_vm_address_t;
 193                 data            : pointer_t);
 194
 195 /*
 196  *      Copy the contents of the source range of the virtual
 197  *      address space of the target task to the destination
 198  *      range in that same address space.  [Both of the
 199  *      ranges must be aligned on a virtual page boundary,
 200  *      and must be multiples of pages in extent.  The
 201  *      protection on the source range must permit reading,
 202  *      and the protection on the destination range must
 203  *      permit writing.]
 204  */
 205 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 206 routine mach_vm_copy(
 207 #else
 208 routine vm_copy(
 209 #endif
 210                 target_task     : vm_map_t;
 211                 source_address  : mach_vm_address_t;
 212                 size            : mach_vm_size_t;
 213                 dest_address    : mach_vm_address_t);
 214
 215 /*
 216  *      Returns the contents of the specified range of the
 217  *      virtual address space of the target task.  [There
 218  *      are no alignment restrictions, and the results will
 219  *      overwrite the area pointed to by data - which must
 220  *      already exist. The protection on the specified range
 221  *      must permit reading.]
 222  */
 223 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 224 routine mach_vm_read_overwrite(
 225 #else
 226 routine vm_read_overwrite(
 227 #endif
 228                 target_task     : vm_map_t;
 229                 address         : mach_vm_address_t;
 230                 size            : mach_vm_size_t;
 231                 data            : mach_vm_address_t;
 232         out     outsize         : mach_vm_size_t);
 233
 234
 235 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 236 routine mach_vm_msync(
 237 #else
 238 routine vm_msync(
 239 #endif
 240                 target_task     : vm_map_t;
 241                 address         : mach_vm_address_t;
 242                 size            : mach_vm_size_t;
 243                 sync_flags      : vm_sync_t );
 244
 245 /*
 246  *      Set the paging behavior attribute for the specified range
 247  *      of the virtual address space of the target task.
 248  *      The behavior value is one of {default, random, forward
 249  *      sequential, reverse sequential} and indicates the expected
 250  *      page reference pattern for the specified range.
 251  */
 252 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 253 routine mach_vm_behavior_set(
 254 #else
 255 routine vm_behavior_set(
 256 #endif
 257                 target_task     : vm_map_t;
 258                 address         : mach_vm_address_t;
 259                 size            : mach_vm_size_t;
 260                 new_behavior    : vm_behavior_t);
 261
 262
 263 /*
 264  *      Map a user-supplie memory object into the virtual address
 265  *      space of the target task.  If desired (anywhere is TRUE),
 266  *      the kernel will find a suitable address range of the
 267  *      specified size; else, the specific address will be allocated.
 268  *
 269  *      The beginning address of the range will be aligned on a virtual
 270  *      page boundary, be at or beyond the address specified, and
 271  *      meet the mask requirements (bits turned on in the mask must not
 272  *      be turned on in the result); the size of the range, in bytes,
 273  *      will be rounded up to an integral number of virtual pages.
 274  *
 275  *      The memory in the resulting range will be associated with the
 276  *      specified memory object, with the beginning of the memory range
 277  *      referring to the specified offset into the memory object.
 278  *
 279  *      The mapping will take the current and maximum protections and
 280  *      the inheritance attributes specified; see the vm_protect and
 281  *      vm_inherit calls for a description of these attributes.
 282  *
 283  *      If desired (copy is TRUE), the memory range will be filled
 284  *      with a copy of the data from the memory object; this copy will
 285  *      be private to this mapping in this target task.  Otherwise,
 286  *      the memory in this mapping will be shared with other mappings
 287  *      of the same memory object at the same offset (in this task or
 288  *      in other tasks).  [The Mach kernel only enforces shared memory
 289  *      consistency among mappings on one host with similar page alignments.
 290  *      The user-defined memory manager for this object is responsible
 291  *      for further consistency.]
 292  */
 293 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 294 routine mach_vm_map(
 295 #else
 296 routine vm_map(
 297 #endif
 298                 target_task     : vm_task_entry_t;
 299         inout   address         : mach_vm_address_t;
 300                 size            : mach_vm_size_t;
 301                 mask            : mach_vm_offset_t;
 302                 flags           : int;
 303                 object          : mem_entry_name_port_t;
 304                 offset          : memory_object_offset_t;
 305                 copy            : boolean_t;
 306                 cur_protection  : vm_prot_t;
 307                 max_protection  : vm_prot_t;
 308                 inheritance     : vm_inherit_t);
 309
 310 /*
 311  *      Set/Get special properties of memory associated
 312  *      to some virtual address range, such as cachability,
 313  *      migrability, replicability.  Machine-dependent.
 314  */
 315 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 316 routine mach_vm_machine_attribute(
 317 #else
 318 routine vm_machine_attribute(
 319 #endif
 320                 target_task     : vm_map_t;
 321                 address         : mach_vm_address_t;
 322                 size            : mach_vm_size_t;
 323                 attribute       : vm_machine_attribute_t;
 324         inout   value           : vm_machine_attribute_val_t);
 325
 326 /*
 327  *      Map portion of a task's address space.
 328  */
 329 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 330 routine mach_vm_remap(
 331 #else
 332 routine vm_remap(
 333 #endif
 334                 target_task     : vm_map_t;
 335         inout   target_address  : mach_vm_address_t;
 336                 size            : mach_vm_size_t;
 337                 mask            : mach_vm_offset_t;
 338                 anywhere        : boolean_t;
 339                 src_task        : vm_map_t;
 340                 src_address     : mach_vm_address_t;
 341                 copy            : boolean_t;
 342         out     cur_protection  : vm_prot_t;
 343         out     max_protection  : vm_prot_t;
 344                 inheritance     : vm_inherit_t);
 345
 346 /*
 347  *      Give the caller information on the given location in a virtual
 348  *      address space.  If a page is mapped return ref and dirty info.
 349  */
 350 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 351 routine mach_vm_page_query(
 352 #else
 353 routine vm_map_page_query(
 354 #endif
 355                 target_map      :vm_map_t;
 356                 offset          :mach_vm_offset_t;
 357         out     disposition     :integer_t;
 358         out     ref_count       :integer_t);
 359
 360
 361 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 362 routine mach_vm_region_recurse(
 363 #else
 364 routine vm_region_recurse_64(
 365 #endif
 366                 target_task     : vm_map_t;
 367         inout   address         : mach_vm_address_t;
 368         out     size            : mach_vm_size_t;
 369         inout   nesting_depth   : natural_t;
 370         out     info            : vm_region_recurse_info_t,CountInOut);
 371
 372 /*
 373  *      Returns information about the contents of the virtual
 374  *      address space of the target task at the specified
 375  *      address.  The returned protection, inheritance, sharing
 376  *      and memory object values apply to the entire range described
 377  *      by the address range returned; the memory object offset
 378  *      corresponds to the beginning of the address range.
 379  *      [If the specified address is not allocated, the next
 380  *      highest address range is described.  If no addresses beyond
 381  *      the one specified are allocated, the call returns KERN_NO_SPACE.]
 382  */
 383 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 384 routine mach_vm_region(
 385 #else
 386 routine vm_region_64(
 387 #endif
 388                 target_task     : vm_map_t;
 389         inout   address         : mach_vm_address_t;
 390         out     size            : mach_vm_size_t;
 391                 flavor          : vm_region_flavor_t;
 392         out     info            : vm_region_info_t, CountInOut;
 393         out     object_name     : memory_object_name_t =
 394                                         MACH_MSG_TYPE_MOVE_SEND
 395                                         ctype: mach_port_t);
 396
 397 /*
 398  *      Allow application level processes to create named entries which
 399  *      correspond to mapped portions of their address space.  These named
 400  *      entries can then be manipulated, shared with other processes in
 401  *      other address spaces and ultimately mapped in ohter address spaces
 402  *
 403  *      THIS INTERFACE IS STILL EVOLVING.
 404  */
 405 #if !defined(_MACH_VM_PUBLISH_AS_LOCAL_)
 406 routine _mach_make_memory_entry(
 407 #else
 408 routine mach_make_memory_entry_64(
 409 #endif
 410                 target_task     :vm_map_t;
 411         inout   size            :memory_object_size_t;
 412                 offset          :memory_object_offset_t;
 413                 permission      :vm_prot_t;
 414         out     object_handle   :mem_entry_name_port_move_send_t;
 415                 parent_handle   :mem_entry_name_port_t);
 416
 417
 418 /****************************** Legacy section ***************************/
 419 /*  The following definitions are exist to provide compatibility with    */
 420 /*  the legacy APIs.  They are no different.  We just need to produce    */
 421 /*  the user-level stub interface for them.                              */
 422 /****************************** Legacy section ***************************/
 423
 424
 425 /*
 426  * These interfaces just aren't supported in the new (wide) model:
 427  *
 428  *      mach_vm_region_info() -
 429  *      vm_map_pages_info() -
 430  *              no user-level replacement for these MACH_DEBUG interfaces
 431  *      vm_map_get_upl() -
 432  *              no user-level replacement at the moment
 433  *      vm_region_info() -
 434  *              use mach_vm_region_info() or vm_region_info_64()
 435  *      vm_region_recurse() -
 436  *              use mach_vm_region_recurse() or vm_region_recurse_64()
 437  */
 438
 439 /*
 440  * The following legacy interfaces are provides as macro wrappers to the new
 441  * interfaces.  You should strive to use the new ones instead:
 442  *
 443  *      vm_map() -
 444  *              use mach_vm_map() or vm_map_64()
 445  *      vm_region() -
 446  *              use mach_vm_region() or vm_region_64()
 447  *      mach_make_memory_entry() -
 448  *              use mach_vm_make_memory_entry() or mach_make_memory_entry_64()
 449  */