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  * 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_COPYRIGHT@
  24  */
  25 /*
  26  * Mach Operating System
  27  * Copyright (c) 1991,1990,1989,1988,1987 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/memory_object.defs
  54  *
  55  * Abstract:
  56  *      Basic Mach external memory management interface declaration.
  57  */
  58
  59 subsystem
  60 #if     KERNEL_USER
  61           KernelUser
  62 #endif  /* KERNEL_USER */
  63 #if     KERNEL_SERVER
  64           KernelServer
  65 #endif  /* KERNEL_SERVER */
  66                      memory_object 2200;
  67
  68 #ifdef  MACH_KERNEL
  69 #include <advisory_pageout.h>
  70 #endif  /* MACH_KERNEL */
  71
  72 #include <mach/std_types.defs>
  73 #include <mach/mach_types.defs>
  74
  75 #if     KERNEL_SERVER
  76 serverprefix dp_;
  77 #endif
  78
  79 /*
  80  *      Initialize the specified memory object, providing
  81  *      a memory object control reference on which to make
  82  *   cache control calls.
  83  *      [To allow the mapping of this object to be used, the
  84  *      memory manager must call memory_object_set_attributes,
  85  *      specifying the "ready" parameter as TRUE.  To reject
  86  *      all mappings of this object, the memory manager may
  87  *      use memory_object_destroy.]
  88  */
  89 routine memory_object_init(
  90                 memory_object           : memory_object_t;
  91                 memory_control  : memory_object_control_t;
  92                 memory_object_page_size : memory_object_cluster_size_t);
  93
  94
  95 /*
  96  *      Indicates that the specified memory object is no longer
  97  *      mapped (or cached -- see memory_object_set_attributes),
  98  *      and that further mappings will cause another memory_object_init
  99  *      call to be made.
 100  *
 101  *      [The kernel will release its reference on the memory object
 102  *      after this call returns.  The memory object control associated
 103  *      with the memory object is no longer usable - the pager should
 104  *      drop the control reference granted to it by memory_object_init.]
 105  */
 106 routine memory_object_terminate(
 107                 memory_object           : memory_object_t);
 108
 109 /*
 110  *      Request data from this memory object.  At least
 111  *      the specified data should be returned with at
 112  *      least the specified access permitted.
 113  *
 114  *      [Response should be upl commit over the specified range.]
 115  */
 116 routine memory_object_data_request(
 117                 memory_object           : memory_object_t;
 118                 offset                  : memory_object_offset_t;
 119                 length                  : memory_object_cluster_size_t;
 120                 desired_access          : vm_prot_t);
 121
 122 /*
 123  *      Return data to manager.  This call is used in place of data_write
 124  *      for objects initialized by object_ready instead of set_attributes.
 125  *      This call indicates whether the returned data is dirty and whether
 126  *      the kernel kept a copy.  Precious data remains precious if the
 127  *      kernel keeps a copy.  The indication that the kernel kept a copy
 128  *      is only a hint if the data is not precious; the cleaned copy may
 129  *      be discarded without further notifying the manager.
 130  *
 131  *      [response should be a upl_commit over the range specified]
 132  */
 133 routine   memory_object_data_return(
 134                 memory_object           : memory_object_t;
 135                 offset                  : memory_object_offset_t;
 136                 size                    : memory_object_cluster_size_t;
 137         out     resid_offset            : memory_object_offset_t;
 138         out     io_error                : int;
 139                 dirty                   : boolean_t;
 140                 kernel_copy             : boolean_t;
 141                 upl_flags               : int);
 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                    : memory_object_cluster_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                    : memory_object_cluster_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                    : memory_object_cluster_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