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