2 * Copyright (c) 2000-2005 Apple Computer, Inc. All rights reserved.
4 * @APPLE_LICENSE_OSREFERENCE_HEADER_START@
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
10 * License may not be used to create, or enable the creation or
11 * redistribution of, unlawful or unlicensed copies of an Apple operating
12 * system, or to circumvent, violate, or enable the circumvention or
13 * violation of, any terms of an Apple operating system software license
16 * Please obtain a copy of the License at
17 * http://www.opensource.apple.com/apsl/ and read it before using this
20 * The Original Code and all software distributed under the License are
21 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
22 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
23 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
24 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
25 * Please see the License for the specific language governing rights and
26 * limitations under the License.
28 * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
34 * Mach Operating System
35 * Copyright (c) 1991,1990,1989,1988 Carnegie Mellon University
36 * All Rights Reserved.
38 * Permission to use, copy, modify and distribute this software and its
39 * documentation is hereby granted, provided that both the copyright
40 * notice and this permission notice appear in all copies of the
41 * software, derivative works or modified versions, and any portions
42 * thereof, and that both notices appear in supporting documentation.
44 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
45 * CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
46 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
48 * Carnegie Mellon requests users of this software to return to
50 * Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
51 * School of Computer Science
52 * Carnegie Mellon University
53 * Pittsburgh PA 15213-3890
55 * any improvements or extensions that they make and grant Carnegie Mellon
56 * the rights to redistribute these changes.
61 * File: memory_object.h
62 * Author: Michael Wayne Young
64 * External memory management interface definition.
67 #ifndef _MACH_MEMORY_OBJECT_TYPES_H_
68 #define _MACH_MEMORY_OBJECT_TYPES_H_
71 * User-visible types used in the external memory
72 * management interface:
75 #include <mach/port.h>
76 #include <mach/message.h>
77 #include <mach/vm_prot.h>
78 #include <mach/vm_sync.h>
79 #include <mach/vm_types.h>
80 #include <mach/machine/vm_types.h>
82 #include <sys/cdefs.h>
84 #define VM_64_BIT_DATA_OBJECTS
86 typedef unsigned long long memory_object_offset_t
;
87 typedef unsigned long long memory_object_size_t
;
88 typedef natural_t memory_object_cluster_size_t
;
92 * Temporary until real EMMI version gets re-implemented
97 struct memory_object_pager_ops
; /* forward declaration */
99 typedef struct memory_object
{
100 const struct memory_object_pager_ops
*mo_pager_ops
;
103 typedef struct memory_object_control
{
104 struct vm_object
*moc_object
;
105 unsigned int moc_ikot
; /* XXX fake ip_kotype */
106 } *memory_object_control_t
;
108 typedef const struct memory_object_pager_ops
{
109 void (*memory_object_reference
)(
110 memory_object_t mem_obj
);
111 void (*memory_object_deallocate
)(
112 memory_object_t mem_obj
);
113 kern_return_t (*memory_object_init
)(
114 memory_object_t mem_obj
,
115 memory_object_control_t mem_control
,
116 memory_object_cluster_size_t size
);
117 kern_return_t (*memory_object_terminate
)(
118 memory_object_t mem_obj
);
119 kern_return_t (*memory_object_data_request
)(
120 memory_object_t mem_obj
,
121 memory_object_offset_t offset
,
122 memory_object_cluster_size_t length
,
123 vm_prot_t desired_access
);
124 kern_return_t (*memory_object_data_return
)(
125 memory_object_t mem_obj
,
126 memory_object_offset_t offset
,
128 memory_object_offset_t
*resid_offset
,
131 boolean_t kernel_copy
,
133 kern_return_t (*memory_object_data_initialize
)(
134 memory_object_t mem_obj
,
135 memory_object_offset_t offset
,
137 kern_return_t (*memory_object_data_unlock
)(
138 memory_object_t mem_obj
,
139 memory_object_offset_t offset
,
141 vm_prot_t desired_access
);
142 kern_return_t (*memory_object_synchronize
)(
143 memory_object_t mem_obj
,
144 memory_object_offset_t offset
,
146 vm_sync_t sync_flags
);
147 kern_return_t (*memory_object_unmap
)(
148 memory_object_t mem_obj
);
149 const char *memory_object_pager_name
;
150 } * memory_object_pager_ops_t
;
152 #else /* KERNEL_PRIVATE */
154 typedef mach_port_t memory_object_t
;
155 typedef mach_port_t memory_object_control_t
;
157 #endif /* KERNEL_PRIVATE */
159 typedef memory_object_t
*memory_object_array_t
;
160 /* A memory object ... */
161 /* Used by the kernel to retrieve */
164 typedef mach_port_t memory_object_name_t
;
165 /* Used to describe the memory ... */
166 /* object in vm_regions() calls */
168 typedef mach_port_t memory_object_default_t
;
169 /* Registered with the host ... */
170 /* for creating new internal objects */
172 #define MEMORY_OBJECT_NULL ((memory_object_t) 0)
173 #define MEMORY_OBJECT_CONTROL_NULL ((memory_object_control_t) 0)
174 #define MEMORY_OBJECT_NAME_NULL ((memory_object_name_t) 0)
175 #define MEMORY_OBJECT_DEFAULT_NULL ((memory_object_default_t) 0)
178 typedef int memory_object_copy_strategy_t
;
179 /* How memory manager handles copy: */
180 #define MEMORY_OBJECT_COPY_NONE 0
181 /* ... No special support */
182 #define MEMORY_OBJECT_COPY_CALL 1
183 /* ... Make call on memory manager */
184 #define MEMORY_OBJECT_COPY_DELAY 2
185 /* ... Memory manager doesn't
186 * change data externally.
188 #define MEMORY_OBJECT_COPY_TEMPORARY 3
189 /* ... Memory manager doesn't
190 * change data externally, and
191 * doesn't need to see changes.
193 #define MEMORY_OBJECT_COPY_SYMMETRIC 4
194 /* ... Memory manager doesn't
195 * change data externally,
196 * doesn't need to see changes,
197 * and object will not be
201 * Not yet safe for non-kernel use.
204 #define MEMORY_OBJECT_COPY_INVALID 5
205 /* ... An invalid copy strategy,
206 * for external objects which
207 * have not been initialized.
208 * Allows copy_strategy to be
209 * examined without also
210 * examining pager_ready and
214 typedef int memory_object_return_t
;
215 /* Which pages to return to manager
216 this time (lock_request) */
217 #define MEMORY_OBJECT_RETURN_NONE 0
218 /* ... don't return any. */
219 #define MEMORY_OBJECT_RETURN_DIRTY 1
220 /* ... only dirty pages. */
221 #define MEMORY_OBJECT_RETURN_ALL 2
222 /* ... dirty and precious pages. */
223 #define MEMORY_OBJECT_RETURN_ANYTHING 3
224 /* ... any resident page. */
227 * Data lock request flags
230 #define MEMORY_OBJECT_DATA_FLUSH 0x1
231 #define MEMORY_OBJECT_DATA_NO_CHANGE 0x2
232 #define MEMORY_OBJECT_DATA_PURGE 0x4
233 #define MEMORY_OBJECT_COPY_SYNC 0x8
234 #define MEMORY_OBJECT_DATA_SYNC 0x10
235 #define MEMORY_OBJECT_IO_SYNC 0x20
238 * Types for the memory object flavor interfaces
241 #define MEMORY_OBJECT_INFO_MAX (1024)
242 typedef int *memory_object_info_t
;
243 typedef int memory_object_flavor_t
;
244 typedef int memory_object_info_data_t
[MEMORY_OBJECT_INFO_MAX
];
247 #define MEMORY_OBJECT_PERFORMANCE_INFO 11
248 #define MEMORY_OBJECT_ATTRIBUTE_INFO 14
249 #define MEMORY_OBJECT_BEHAVIOR_INFO 15
253 #define OLD_MEMORY_OBJECT_BEHAVIOR_INFO 10
254 #define OLD_MEMORY_OBJECT_ATTRIBUTE_INFO 12
256 struct old_memory_object_behave_info
{
257 memory_object_copy_strategy_t copy_strategy
;
259 boolean_t invalidate
;
262 struct old_memory_object_attr_info
{ /* old attr list */
263 boolean_t object_ready
;
265 memory_object_copy_strategy_t copy_strategy
;
268 typedef struct old_memory_object_behave_info
*old_memory_object_behave_info_t
;
269 typedef struct old_memory_object_behave_info old_memory_object_behave_info_data_t
;
270 typedef struct old_memory_object_attr_info
*old_memory_object_attr_info_t
;
271 typedef struct old_memory_object_attr_info old_memory_object_attr_info_data_t
;
273 #define OLD_MEMORY_OBJECT_BEHAVE_INFO_COUNT ((mach_msg_type_number_t) \
274 (sizeof(old_memory_object_behave_info_data_t)/sizeof(int)))
275 #define OLD_MEMORY_OBJECT_ATTR_INFO_COUNT ((mach_msg_type_number_t) \
276 (sizeof(old_memory_object_attr_info_data_t)/sizeof(int)))
281 extern void memory_object_reference(memory_object_t object
);
282 extern void memory_object_deallocate(memory_object_t object
);
284 extern void memory_object_default_reference(memory_object_default_t
);
285 extern void memory_object_default_deallocate(memory_object_default_t
);
287 extern void memory_object_control_reference(memory_object_control_t control
);
288 extern void memory_object_control_deallocate(memory_object_control_t control
);
289 extern int memory_object_control_uiomove(memory_object_control_t
, memory_object_offset_t
, void *, int, int, int);
296 struct memory_object_perf_info
{
297 memory_object_cluster_size_t cluster_size
;
301 struct memory_object_attr_info
{
302 memory_object_copy_strategy_t copy_strategy
;
303 memory_object_cluster_size_t cluster_size
;
304 boolean_t may_cache_object
;
308 struct memory_object_behave_info
{
309 memory_object_copy_strategy_t copy_strategy
;
311 boolean_t invalidate
;
312 boolean_t silent_overwrite
;
313 boolean_t advisory_pageout
;
317 typedef struct memory_object_behave_info
*memory_object_behave_info_t
;
318 typedef struct memory_object_behave_info memory_object_behave_info_data_t
;
320 typedef struct memory_object_perf_info
*memory_object_perf_info_t
;
321 typedef struct memory_object_perf_info memory_object_perf_info_data_t
;
323 typedef struct memory_object_attr_info
*memory_object_attr_info_t
;
324 typedef struct memory_object_attr_info memory_object_attr_info_data_t
;
326 #define MEMORY_OBJECT_BEHAVE_INFO_COUNT ((mach_msg_type_number_t) \
327 (sizeof(memory_object_behave_info_data_t)/sizeof(int)))
328 #define MEMORY_OBJECT_PERF_INFO_COUNT ((mach_msg_type_number_t) \
329 (sizeof(memory_object_perf_info_data_t)/sizeof(int)))
330 #define MEMORY_OBJECT_ATTR_INFO_COUNT ((mach_msg_type_number_t) \
331 (sizeof(memory_object_attr_info_data_t)/sizeof(int)))
333 #define invalid_memory_object_flavor(f) \
334 (f != MEMORY_OBJECT_ATTRIBUTE_INFO && \
335 f != MEMORY_OBJECT_PERFORMANCE_INFO && \
336 f != OLD_MEMORY_OBJECT_BEHAVIOR_INFO && \
337 f != MEMORY_OBJECT_BEHAVIOR_INFO && \
338 f != OLD_MEMORY_OBJECT_ATTRIBUTE_INFO)
342 * Used to support options on memory_object_release_name call
344 #define MEMORY_OBJECT_TERMINATE_IDLE 0x1
345 #define MEMORY_OBJECT_RESPECT_CACHE 0x2
346 #define MEMORY_OBJECT_RELEASE_NO_OP 0x4
349 /* named entry processor mapping options */
351 #define MAP_MEM_NOOP 0
352 #define MAP_MEM_COPYBACK 1
354 #define MAP_MEM_WTHRU 3
355 #define MAP_MEM_WCOMB 4 /* Write combining mode */
356 /* aka store gather */
358 #define GET_MAP_MEM(flags) \
359 ((((unsigned int)(flags)) >> 24) & 0xFF)
361 #define SET_MAP_MEM(caching, flags) \
362 ((flags) = ((((unsigned int)(caching)) << 24) \
363 & 0xFF000000) | ((flags) & 0xFFFFFF));
365 /* leave room for vm_prot bits */
366 #define MAP_MEM_ONLY 0x10000 /* change processor caching */
367 #define MAP_MEM_NAMED_CREATE 0x20000 /* create extant object */
368 #define MAP_MEM_PURGABLE 0x40000 /* create a purgable VM object */
369 #define MAP_MEM_NAMED_REUSE 0x80000 /* reuse provided entry if identical */
374 * Universal Page List data structures
376 * A UPL describes a bounded set of physical pages
377 * associated with some range of an object or map
378 * and a snapshot of the attributes associated with
379 * each of those pages.
382 #define MAX_UPL_TRANSFER 256
384 struct upl_page_info
{
385 ppnum_t phys_addr
; /* physical page index number */
387 #ifdef XNU_KERNEL_PRIVATE
388 pageout
:1, /* page is to be removed on commit */
389 absent
:1, /* No valid data in this page */
390 dirty
:1, /* Page must be cleaned (O) */
391 precious
:1, /* must be cleaned, we have only copy */
392 device
:1, /* no page data, mapped dev memory */
393 :0; /* force to long boundary */
395 opaque
; /* use upl_page_xxx() accessor funcs */
396 #endif /* XNU_KERNEL_PRIVATE */
401 struct upl_page_info
{
402 unsigned int opaque
[2]; /* use upl_page_xxx() accessor funcs */
407 typedef struct upl_page_info upl_page_info_t
;
408 typedef upl_page_info_t
*upl_page_info_array_t
;
409 typedef upl_page_info_array_t upl_page_list_ptr_t
;
411 typedef uint32_t upl_offset_t
; /* page-aligned byte offset */
412 typedef uint32_t upl_size_t
; /* page-aligned byte size */
414 /* upl invocation flags */
415 /* top nibble is used by super upl */
417 #define UPL_FLAGS_NONE 0x00000000
418 #define UPL_COPYOUT_FROM 0x00000001
419 #define UPL_PRECIOUS 0x00000002
420 #define UPL_NO_SYNC 0x00000004
421 #define UPL_CLEAN_IN_PLACE 0x00000008
422 #define UPL_NOBLOCK 0x00000010
423 #define UPL_RET_ONLY_DIRTY 0x00000020
424 #define UPL_SET_INTERNAL 0x00000040
425 #define UPL_QUERY_OBJECT_TYPE 0x00000080
426 #define UPL_RET_ONLY_ABSENT 0x00000100 /* used only for COPY_FROM = FALSE */
427 #define UPL_FILE_IO 0x00000200
428 #define UPL_SET_LITE 0x00000400
429 #define UPL_SET_INTERRUPTIBLE 0x00000800
430 #define UPL_SET_IO_WIRE 0x00001000
431 #define UPL_FOR_PAGEOUT 0x00002000
432 #define UPL_WILL_BE_DUMPED 0x00004000
433 #define UPL_FORCE_DATA_SYNC 0x00008000
434 /* continued after the ticket bits... */
436 #define UPL_PAGE_TICKET_MASK 0x000F0000
437 #define UPL_PAGE_TICKET_SHIFT 16
439 /* ... flags resume here */
440 #define UPL_BLOCK_ACCESS 0x00100000
441 #define UPL_ENCRYPT 0x00200000
442 #define UPL_NOZEROFILL 0x00400000
443 #define UPL_WILL_MODIFY 0x00800000 /* caller will modify the pages */
445 #define UPL_NEED_32BIT_ADDR 0x01000000
447 /* UPL flags known by this kernel */
448 #define UPL_VALID_FLAGS 0x01FFFFFF
451 /* upl abort error flags */
452 #define UPL_ABORT_RESTART 0x1
453 #define UPL_ABORT_UNAVAILABLE 0x2
454 #define UPL_ABORT_ERROR 0x4
455 #define UPL_ABORT_FREE_ON_EMPTY 0x8 /* only implemented in wrappers */
456 #define UPL_ABORT_DUMP_PAGES 0x10
457 #define UPL_ABORT_NOTIFY_EMPTY 0x20
458 #define UPL_ABORT_ALLOW_ACCESS 0x40
460 /* upl pages check flags */
461 #define UPL_CHECK_DIRTY 0x1
465 * upl pagein/pageout flags
468 * when I/O is issued from this UPL it should be done synchronously
470 #define UPL_IOSYNC 0x1
473 * the passed in UPL should not have either a commit or abort
474 * applied to it by the underlying layers... the site that
475 * created the UPL is responsible for cleaning it up.
477 #define UPL_NOCOMMIT 0x2
480 * turn off any speculative read-ahead applied at the I/O layer
482 #define UPL_NORDAHEAD 0x4
485 * pageout request is targeting a real file
486 * as opposed to a swap file.
489 #define UPL_VNODE_PAGER 0x8
491 * this pageout is being originated as part of an explicit
492 * memory synchronization operation... no speculative clustering
493 * should be applied, only the range specified should be pushed.
495 #define UPL_MSYNC 0x10
500 #ifdef MACH_KERNEL_PRIVATE
501 #define UPL_PAGING_ENCRYPTED 0x20
502 #endif /* MACH_KERNEL_PRIVATE */
505 * this pageout is being originated as part of an explicit
506 * memory synchronization operation that is checking for I/O
507 * errors and taking it's own action... if an error occurs,
508 * just abort the pages back into the cache unchanged
510 #define UPL_KEEPCACHED 0x40
514 /* upl commit flags */
515 #define UPL_COMMIT_FREE_ON_EMPTY 0x1 /* only implemented in wrappers */
516 #define UPL_COMMIT_CLEAR_DIRTY 0x2
517 #define UPL_COMMIT_SET_DIRTY 0x4
518 #define UPL_COMMIT_INACTIVATE 0x8
519 #define UPL_COMMIT_NOTIFY_EMPTY 0x10
520 #define UPL_COMMIT_ALLOW_ACCESS 0x20
522 /* flags for return of state from vm_map_get_upl, vm_upl address space */
524 #define UPL_DEV_MEMORY 0x1
525 #define UPL_PHYS_CONTIG 0x2
529 * Flags for the UPL page ops routine. This routine is not exported
530 * out of the kernel at the moment and so the defs live here.
532 #define UPL_POP_DIRTY 0x1
533 #define UPL_POP_PAGEOUT 0x2
534 #define UPL_POP_PRECIOUS 0x4
535 #define UPL_POP_ABSENT 0x8
536 #define UPL_POP_BUSY 0x10
538 #define UPL_POP_PHYSICAL 0x10000000
539 #define UPL_POP_DUMP 0x20000000
540 #define UPL_POP_SET 0x40000000
541 #define UPL_POP_CLR 0x80000000
544 * Flags for the UPL range op routine. This routine is not exported
545 * out of the kernel at the moemet and so the defs live here.
548 * UPL_ROP_ABSENT: Returns the extent of the range presented which
549 * is absent, starting with the start address presented
551 #define UPL_ROP_ABSENT 0x01
553 * UPL_ROP_PRESENT: Returns the extent of the range presented which
554 * is present (i.e. resident), starting with the start address presented
556 #define UPL_ROP_PRESENT 0x02
558 * UPL_ROP_DUMP: Dump the pages which are found in the target object
559 * for the target range.
561 #define UPL_ROP_DUMP 0x04
565 /* access macros for upl_t */
567 #define UPL_DEVICE_PAGE(upl) \
568 (((upl)[(index)].phys_addr != 0) ? (!((upl)[0].device)) : FALSE)
570 #define UPL_PAGE_PRESENT(upl, index) \
571 ((upl)[(index)].phys_addr != 0)
573 #define UPL_PHYS_PAGE(upl, index) \
574 ((upl)[(index)].phys_addr)
576 #define UPL_DIRTY_PAGE(upl, index) \
577 (((upl)[(index)].phys_addr != 0) ? ((upl)[(index)].dirty) : FALSE)
579 #define UPL_PRECIOUS_PAGE(upl, index) \
580 (((upl)[(index)].phys_addr != 0) ? ((upl)[(index)].precious) : FALSE)
582 #define UPL_VALID_PAGE(upl, index) \
583 (((upl)[(index)].phys_addr != 0) ? (!((upl)[(index)].absent)) : FALSE)
585 #define UPL_PAGEOUT_PAGE(upl, index) \
586 (((upl)[(index)].phys_addr != 0) ? ((upl)[(index)].pageout) : FALSE)
588 #define UPL_SET_PAGE_FREE_ON_COMMIT(upl, index) \
589 (((upl)[(index)].phys_addr != 0) ? \
590 ((upl)[(index)].pageout = TRUE) : FALSE)
592 #define UPL_CLR_PAGE_FREE_ON_COMMIT(upl, index) \
593 (((upl)[(index)].phys_addr != 0) ? \
594 ((upl)[(index)].pageout = FALSE) : FALSE)
596 /* The call prototyped below is used strictly by UPL_GET_INTERNAL_PAGE_LIST */
598 extern vm_size_t upl_offset_to_pagelist
;
599 extern vm_size_t
upl_get_internal_pagelist_offset(void);
601 /* UPL_GET_INTERNAL_PAGE_LIST is only valid on internal objects where the */
602 /* list request was made with the UPL_INTERNAL flag */
604 #define UPL_GET_INTERNAL_PAGE_LIST(upl) \
605 ((upl_page_info_t *)((upl_offset_to_pagelist == 0) ? \
606 (unsigned int)upl + (unsigned int)(upl_offset_to_pagelist = upl_get_internal_pagelist_offset()): \
607 (unsigned int)upl + (unsigned int)upl_offset_to_pagelist))
611 extern ppnum_t
upl_phys_page(upl_page_info_t
*upl
, int index
);
612 extern void upl_clear_dirty(upl_t upl
, boolean_t value
);
620 extern boolean_t
upl_page_present(upl_page_info_t
*upl
, int index
);
621 extern boolean_t
upl_dirty_page(upl_page_info_t
*upl
, int index
);
622 extern boolean_t
upl_valid_page(upl_page_info_t
*upl
, int index
);
623 extern void upl_deallocate(upl_t upl
);
629 #endif /* _MACH_MEMORY_OBJECT_TYPES_H_ */