osfmk/mach/memory_object.defs

   1 /*
   2  * Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_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. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 /*
  24  * @OSF_COPYRIGHT@
  25  */
  26 /*
  27  * Mach Operating System
  28  * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
  29  * All Rights Reserved.
  30  *
  31  * Permission to use, copy, modify and distribute this software and its
  32  * documentation is hereby granted, provided that both the copyright
  33  * notice and this permission notice appear in all copies of the
  34  * software, derivative works or modified versions, and any portions
  35  * thereof, and that both notices appear in supporting documentation.
  36  *
  37  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  38  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  39  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  40  *
  41  * Carnegie Mellon requests users of this software to return to
  42  *
  43  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  44  *  School of Computer Science
  45  *  Carnegie Mellon University
  46  *  Pittsburgh PA 15213-3890
  47  *
  48  * any improvements or extensions that they make and grant Carnegie Mellon
  49  * the rights to redistribute these changes.
  50  */
  51 /*
  52  */
  53 /*
  54  * File:        mach/memory_object.defs
  55  *
  56  * Abstract:
  57  *      Basic Mach external memory management interface declaration.
  58  */
  59
  60 subsystem
  61 #if     KERNEL_USER
  62           KernelUser
  63 #endif  /* KERNEL_USER */
  64 #if     KERNEL_SERVER
  65           KernelServer
  66 #endif  /* KERNEL_SERVER */
  67                      memory_object 2200;
  68
  69 #ifdef  MACH_KERNEL
  70 #include <advisory_pageout.h>
  71 #endif  /* MACH_KERNEL */
  72
  73 #include <mach/std_types.defs>
  74 #include <mach/mach_types.defs>
  75
  76 #if     KERNEL_SERVER
  77 serverprefix dp_;
  78 #endif
  79
  80 /*
  81  *      Initialize the specified memory object, providing
  82  *      a memory object control reference on which to make
  83  *   cache control calls.
  84  *      [To allow the mapping of this object to be used, the
  85  *      memory manager must call memory_object_set_attributes,
  86  *      specifying the "ready" parameter as TRUE.  To reject
  87  *      all mappings of this object, the memory manager may
  88  *      use memory_object_destroy.]
  89  */
  90 routine memory_object_init(
  91                 memory_object           : memory_object_t;
  92                 memory_control  : memory_object_control_t;
  93                 memory_object_page_size : memory_object_cluster_size_t);
  94
  95
  96 /*
  97  *      Indicates that the specified memory object is no longer
  98  *      mapped (or cached -- see memory_object_set_attributes),
  99  *      and that further mappings will cause another memory_object_init
 100  *      call to be made.
 101  *
 102  *      [The kernel will release its reference on the memory object
 103  *      after this call returns.  The memory object control associated
 104  *      with the memory object is no longer usable - the pager should
 105  *      drop the control reference granted to it by memory_object_init.]
 106  */
 107 routine memory_object_terminate(
 108                 memory_object           : memory_object_t);
 109
 110 /*
 111  *      Request data from this memory object.  At least
 112  *      the specified data should be returned with at
 113  *      least the specified access permitted.
 114  *
 115  *      [Response should be upl commit over the specified range.]
 116  */
 117 routine memory_object_data_request(
 118                 memory_object           : memory_object_t;
 119                 offset                  : memory_object_offset_t;
 120                 length                  : memory_object_cluster_size_t;
 121                 desired_access          : vm_prot_t);
 122
 123 /*
 124  *      Return data to manager.  This call is used in place of data_write
 125  *      for objects initialized by object_ready instead of set_attributes.
 126  *      This call indicates whether the returned data is dirty and whether
 127  *      the kernel kept a copy.  Precious data remains precious if the
 128  *      kernel keeps a copy.  The indication that the kernel kept a copy
 129  *      is only a hint if the data is not precious; the cleaned copy may
 130  *      be discarded without further notifying the manager.
 131  *
 132  *      [response should be a upl_commit over the range specified]
 133  */
 134 routine   memory_object_data_return(
 135                 memory_object           : memory_object_t;
 136                 offset                  : memory_object_offset_t;
 137                 size                    : memory_object_cluster_size_t;
 138         out     resid_offset            : memory_object_offset_t;
 139         out     io_error                : int;
 140                 dirty                   : boolean_t;
 141                 kernel_copy             : boolean_t;
 142                 upl_flags               : int);
 143
 144 /*
 145  *      Provide initial data contents for this region of
 146  *      the memory object.  If data has already been written
 147  *      to the object, this value must be discarded; otherwise,
 148  *      this call acts identically to memory_object_data_return.
 149  *
 150  *      [response should be UPL commit over the specified range.]
 151  */
 152 routine memory_object_data_initialize(
 153                 memory_object           : memory_object_t;
 154                 offset                  : memory_object_offset_t;
 155                 size                    : memory_object_cluster_size_t);
 156
 157 /*
 158  *      Request that the specified portion of this
 159  *      memory object be unlocked to allow the specified
 160  *      forms of access; the kernel already has the data.
 161  *
 162  *      [Response should be memory_object_lock_request when
 163  *      the operation is fully complete.]
 164  */
 165 routine memory_object_data_unlock(
 166                 memory_object           : memory_object_t;
 167                 offset                  : memory_object_offset_t;
 168                 size                    : memory_object_cluster_size_t;
 169                 desired_access          : vm_prot_t);
 170
 171
 172 /*
 173  *      Request that the specified portion of this
 174  *      memory object be synchronized with its backing
 175  *      store according to the supplied flags.
 176  *
 177  *      [Response should be memory_object_synchronize_completed when
 178  *      the operation is fully complete.]
 179  */
 180 routine memory_object_synchronize(
 181                 memory_object           : memory_object_t;
 182                 offset                  : memory_object_offset_t;
 183                 size                    : memory_object_cluster_size_t;
 184                 sync_flags              : vm_sync_t );
 185
 186 /*
 187  *      Notify the pager that the specified memory object
 188  *      has no other (mapped) references besides the named
 189  *      reference held by the pager itself.
 190  *
 191  *      [Response should be a release of the named reference when
 192  *      the pager deems that appropriate.]
 193  */
 194 routine memory_object_unmap(
 195                 memory_object           : memory_object_t);
 196
 197