[apple/xnu.git] / osfmk / mach / memory_object.defs

/*
 * Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 * 
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/*
 * @OSF_COPYRIGHT@
 */
/* 
 * Mach Operating System
 * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
 * All Rights Reserved.
 * 
 * Permission to use, copy, modify and distribute this software and its
 * documentation is hereby granted, provided that both the copyright
 * notice and this permission notice appear in all copies of the
 * software, derivative works or modified versions, and any portions
 * thereof, and that both notices appear in supporting documentation.
 * 
 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
 * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
 * 
 * Carnegie Mellon requests users of this software to return to
 * 
 *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
 *  School of Computer Science
 *  Carnegie Mellon University
 *  Pittsburgh PA 15213-3890
 * 
 * any improvements or extensions that they make and grant Carnegie Mellon
 * the rights to redistribute these changes.
 */
/*
 */
/*
 * File:	mach/memory_object.defs
 *
 * Abstract:
 *	Basic Mach external memory management interface declaration.
 */

subsystem
#if	KERNEL_USER
	  KernelUser
#endif	/* KERNEL_USER */
#if	KERNEL_SERVER
	  KernelServer
#endif	/* KERNEL_SERVER */
		     memory_object 2200;

#ifdef	MACH_KERNEL
#include <advisory_pageout.h>
#endif	/* MACH_KERNEL */

#include <mach/std_types.defs>
#include <mach/mach_types.defs>

#if	KERNEL_SERVER
serverprefix dp_;
#endif

/*
 *	Initialize the specified memory object, providing
 *	a memory object control reference on which to make
 *   cache control calls.
 *	[To allow the mapping of this object to be used, the
 *	memory manager must call memory_object_set_attributes,
 *	specifying the "ready" parameter as TRUE.  To reject
 *	all mappings of this object, the memory manager may
 *	use memory_object_destroy.]
 */
routine	memory_object_init(
		memory_object		: memory_object_t;
		memory_control	: memory_object_control_t;
		memory_object_page_size	: memory_object_cluster_size_t);


/*
 *	Indicates that the specified memory object is no longer
 *	mapped (or cached -- see memory_object_set_attributes),
 *	and that further mappings will cause another memory_object_init
 *	call to be made.  
 *
 *	[The kernel will release its reference on the memory object
 *	after this call returns.  The memory object control associated
 *	with the memory object is no longer usable - the pager should
 *	drop the control reference granted to it by memory_object_init.]
 */
routine	memory_object_terminate(
		memory_object		: memory_object_t);

/*
 *	Request data from this memory object.  At least
 *	the specified data should be returned with at
 *	least the specified access permitted.
 *
 *	[Response should be upl commit over the specified range.]
 */
routine	memory_object_data_request(
		memory_object		: memory_object_t;
		offset			: memory_object_offset_t;
		length			: memory_object_cluster_size_t;
		desired_access		: vm_prot_t;
		fault_info		: memory_object_fault_info_t);

/*
 *	Return data to manager.  This call is used in place of data_write
 *	for objects initialized by object_ready instead of set_attributes.
 *	This call indicates whether the returned data is dirty and whether
 *	the kernel kept a copy.  Precious data remains precious if the
 *	kernel keeps a copy.  The indication that the kernel kept a copy
 *	is only a hint if the data is not precious; the cleaned copy may
 *	be discarded without further notifying the manager.
 *
 *	[response should be a upl_commit over the range specified]
 */
routine   memory_object_data_return(
		memory_object		: memory_object_t;
		offset		 	: memory_object_offset_t;
		size			: memory_object_cluster_size_t;
	out	resid_offset	 	: memory_object_offset_t;
	out	io_error		: int;
		dirty			: boolean_t;
		kernel_copy		: boolean_t;
		upl_flags		: int);

/*
 *	Provide initial data contents for this region of
 *	the memory object.  If data has already been written
 *	to the object, this value must be discarded; otherwise,
 *	this call acts identically to memory_object_data_return.
 *
 *	[response should be UPL commit over the specified range.]
 */
routine	memory_object_data_initialize(
		memory_object		: memory_object_t;
		offset			: memory_object_offset_t;
		size			: memory_object_cluster_size_t);

/*
 *	Request that the specified portion of this
 *	memory object be unlocked to allow the specified
 *	forms of access; the kernel already has the data.
 *
 *	[Response should be memory_object_lock_request when
 *	the operation is fully complete.]
 */
routine	memory_object_data_unlock(
		memory_object		: memory_object_t;
		offset			: memory_object_offset_t;
		size			: memory_object_size_t;
		desired_access		: vm_prot_t);


/*
 *	Request that the specified portion of this
 *	memory object be synchronized with its backing
 *	store according to the supplied flags.
 *
 *	[Response should be memory_object_synchronize_completed when
 *	the operation is fully complete.]
 */
routine memory_object_synchronize(
		memory_object           : memory_object_t;
		offset          	: memory_object_offset_t;
		size	          	: memory_object_size_t;
		sync_flags 	     	: vm_sync_t );

/*
 *	Notify the pager that the specified memory object
 *	has no other (mapped) references besides the named
 *	reference held by the pager itself.
 *
 *	[Response should be a release of the named reference when
 *	the pager deems that appropriate.]
 */
routine memory_object_map(
		memory_object		: memory_object_t;
		prot			: vm_prot_t);
routine memory_object_last_unmap(
		memory_object           : memory_object_t);

routine	memory_object_data_reclaim(
		memory_object		: memory_object_t;
		reclaim_backing_store	: boolean_t);

/* vim: set ft=c : */
Commit	Line	Data
1c79356b	1	/*
91447636	2	* Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
1c79356b	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b	5	*
2d21ac55 A	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.
8f6c56a5	14	*
2d21ac55 A	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
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	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.
8f6c56a5	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b A	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
	65	subsystem
	66	#if KERNEL_USER
	67	KernelUser
55e303ae	68	#endif /* KERNEL_USER */
1c79356b A	69	#if KERNEL_SERVER
1c79356b A	70	KernelServer
55e303ae	71	#endif /* KERNEL_SERVER */
1c79356b A	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
	82	serverprefix dp_;
1c79356b A	83	#endif
	84
	85	/*
	86	* Initialize the specified memory object, providing
0b4e3aa0 A	87	* a memory object control reference on which to make
0b4e3aa0 A	88	* cache control calls.
1c79356b A	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	*/
0b4e3aa0	95	routine memory_object_init(
1c79356b	96	memory_object : memory_object_t;
0b4e3aa0	97	memory_control : memory_object_control_t;
91447636	98	memory_object_page_size : memory_object_cluster_size_t);
1c79356b A	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
0b4e3aa0	105	* call to be made.
1c79356b	106	*
0b4e3aa0 A	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.]
1c79356b	111	*/
0b4e3aa0 A	112	routine memory_object_terminate(
0b4e3aa0 A	113	memory_object : memory_object_t);
1c79356b A	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	*
0b4e3aa0	120	* [Response should be upl commit over the specified range.]
1c79356b	121	*/
0b4e3aa0	122	routine memory_object_data_request(
1c79356b	123	memory_object : memory_object_t;
1c79356b	124	offset : memory_object_offset_t;
91447636	125	length : memory_object_cluster_size_t;
2d21ac55 A	126	desired_access : vm_prot_t;
2d21ac55 A	127	fault_info : memory_object_fault_info_t);
1c79356b	128
1c79356b A	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	*
0b4e3aa0	138	* [response should be a upl_commit over the range specified]
1c79356b	139	*/
0b4e3aa0	140	routine memory_object_data_return(
1c79356b	141	memory_object : memory_object_t;
1c79356b	142	offset : memory_object_offset_t;
91447636 A	143	size : memory_object_cluster_size_t;
	144	out resid_offset : memory_object_offset_t;
	145	out io_error : int;
1c79356b	146	dirty : boolean_t;
91447636 A	147	kernel_copy : boolean_t;
91447636 A	148	upl_flags : int);
1c79356b	149
0b4e3aa0 A	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	*/
	158	routine memory_object_data_initialize(
	159	memory_object : memory_object_t;
	160	offset : memory_object_offset_t;
91447636	161	size : memory_object_cluster_size_t);
0b4e3aa0 A	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	*/
	171	routine memory_object_data_unlock(
	172	memory_object : memory_object_t;
	173	offset : memory_object_offset_t;
b0d623f7	174	size : memory_object_size_t;
0b4e3aa0	175	desired_access : vm_prot_t);
1c79356b	176
1c79356b	177
0b4e3aa0 A	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	*/
	186	routine memory_object_synchronize(
	187	memory_object : memory_object_t;
	188	offset : memory_object_offset_t;
b0d623f7	189	size : memory_object_size_t;
0b4e3aa0	190	sync_flags : vm_sync_t );
1c79356b A	191
1c79356b A	192	/*
0b4e3aa0 A	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.]
1c79356b	199	*/
593a1d5f A	200	routine memory_object_map(
	201	memory_object : memory_object_t;
	202	prot : vm_prot_t);
	203	routine memory_object_last_unmap(
0b4e3aa0 A	204	memory_object : memory_object_t);
0b4e3aa0 A	205
6d2010ae A	206	routine memory_object_data_reclaim(
	207	memory_object : memory_object_t;
	208	reclaim_backing_store : boolean_t);
	209
2d21ac55	210	/* vim: set ft=c : */