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