osfmk/mach/memory_object.defs

   1 /*
   2  * Copyright (c) 2000-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_COPYRIGHT@
  32  */
  33 /*
  34  * Mach Operating System
  35  * Copyright (c) 1991,1990,1989,1988,1987 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/memory_object.defs
  62  *
  63  * Abstract:
  64  *      Basic Mach external memory management interface declaration.
  65  */
  66
  67 subsystem
  68 #if     KERNEL_USER
  69           KernelUser
  70 #endif  /* KERNEL_USER */
  71 #if     KERNEL_SERVER
  72           KernelServer
  73 #endif  /* KERNEL_SERVER */
  74                      memory_object 2200;
  75
  76 #ifdef  MACH_KERNEL
  77 #include <advisory_pageout.h>
  78 #endif  /* MACH_KERNEL */
  79
  80 #include <mach/std_types.defs>
  81 #include <mach/mach_types.defs>
  82
  83 #if     KERNEL_SERVER
  84 serverprefix dp_;
  85 #endif
  86
  87 /*
  88  *      Initialize the specified memory object, providing
  89  *      a memory object control reference on which to make
  90  *   cache control calls.
  91  *      [To allow the mapping of this object to be used, the
  92  *      memory manager must call memory_object_set_attributes,
  93  *      specifying the "ready" parameter as TRUE.  To reject
  94  *      all mappings of this object, the memory manager may
  95  *      use memory_object_destroy.]
  96  */
  97 routine memory_object_init(
  98                 memory_object           : memory_object_t;
  99                 memory_control  : memory_object_control_t;
 100                 memory_object_page_size : memory_object_cluster_size_t);
 101
 102
 103 /*
 104  *      Indicates that the specified memory object is no longer
 105  *      mapped (or cached -- see memory_object_set_attributes),
 106  *      and that further mappings will cause another memory_object_init
 107  *      call to be made.
 108  *
 109  *      [The kernel will release its reference on the memory object
 110  *      after this call returns.  The memory object control associated
 111  *      with the memory object is no longer usable - the pager should
 112  *      drop the control reference granted to it by memory_object_init.]
 113  */
 114 routine memory_object_terminate(
 115                 memory_object           : memory_object_t);
 116
 117 /*
 118  *      Request data from this memory object.  At least
 119  *      the specified data should be returned with at
 120  *      least the specified access permitted.
 121  *
 122  *      [Response should be upl commit over the specified range.]
 123  */
 124 routine memory_object_data_request(
 125                 memory_object           : memory_object_t;
 126                 offset                  : memory_object_offset_t;
 127                 length                  : memory_object_cluster_size_t;
 128                 desired_access          : vm_prot_t);
 129
 130 /*
 131  *      Return data to manager.  This call is used in place of data_write
 132  *      for objects initialized by object_ready instead of set_attributes.
 133  *      This call indicates whether the returned data is dirty and whether
 134  *      the kernel kept a copy.  Precious data remains precious if the
 135  *      kernel keeps a copy.  The indication that the kernel kept a copy
 136  *      is only a hint if the data is not precious; the cleaned copy may
 137  *      be discarded without further notifying the manager.
 138  *
 139  *      [response should be a upl_commit over the range specified]
 140  */
 141 routine   memory_object_data_return(
 142                 memory_object           : memory_object_t;
 143                 offset                  : memory_object_offset_t;
 144                 size                    : memory_object_cluster_size_t;
 145         out     resid_offset            : memory_object_offset_t;
 146         out     io_error                : int;
 147                 dirty                   : boolean_t;
 148                 kernel_copy             : boolean_t;
 149                 upl_flags               : int);
 150
 151 /*
 152  *      Provide initial data contents for this region of
 153  *      the memory object.  If data has already been written
 154  *      to the object, this value must be discarded; otherwise,
 155  *      this call acts identically to memory_object_data_return.
 156  *
 157  *      [response should be UPL commit over the specified range.]
 158  */
 159 routine memory_object_data_initialize(
 160                 memory_object           : memory_object_t;
 161                 offset                  : memory_object_offset_t;
 162                 size                    : memory_object_cluster_size_t);
 163
 164 /*
 165  *      Request that the specified portion of this
 166  *      memory object be unlocked to allow the specified
 167  *      forms of access; the kernel already has the data.
 168  *
 169  *      [Response should be memory_object_lock_request when
 170  *      the operation is fully complete.]
 171  */
 172 routine memory_object_data_unlock(
 173                 memory_object           : memory_object_t;
 174                 offset                  : memory_object_offset_t;
 175                 size                    : memory_object_cluster_size_t;
 176                 desired_access          : vm_prot_t);
 177
 178
 179 /*
 180  *      Request that the specified portion of this
 181  *      memory object be synchronized with its backing
 182  *      store according to the supplied flags.
 183  *
 184  *      [Response should be memory_object_synchronize_completed when
 185  *      the operation is fully complete.]
 186  */
 187 routine memory_object_synchronize(
 188                 memory_object           : memory_object_t;
 189                 offset                  : memory_object_offset_t;
 190                 size                    : memory_object_cluster_size_t;
 191                 sync_flags              : vm_sync_t );
 192
 193 /*
 194  *      Notify the pager that the specified memory object
 195  *      has no other (mapped) references besides the named
 196  *      reference held by the pager itself.
 197  *
 198  *      [Response should be a release of the named reference when
 199  *      the pager deems that appropriate.]
 200  */
 201 routine memory_object_unmap(
 202                 memory_object           : memory_object_t);
 203
 204