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