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 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: 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 */
84extern 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 */
100extern 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 */
110extern 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 */
128extern 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 */
146extern 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 */
159extern kern_return_t memory_object_map(
160 memory_object_t memory_object,
161 vm_prot_t prot);
162
163extern 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