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

/*
 * Copyright (c) 2000 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_control.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_control 2000;

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

/*
 *      Retrieves the attributes currently associated with
 *      a memory object.
 */
routine memory_object_get_attributes(
                memory_control	: memory_object_control_t;
		flavor		: memory_object_flavor_t;
	out	attributes	: memory_object_info_t, CountInOut);


routine memory_object_change_attributes(
                memory_control	: memory_object_control_t;
                flavor          : memory_object_flavor_t;
        	attributes      : memory_object_info_t
		);

routine memory_object_synchronize_completed (
		memory_control	: memory_object_control_t;
		offset		: memory_object_offset_t;
		length		: memory_object_size_t);

/*
 *	Control use of the data associated with the given
 *	memory object.  For each page in the given range,
 *	perform the following operations, in order:
 *		1)  restrict access to the page (disallow
 *		    forms specified by "prot");
 *		2)  write back modifications (if "should_return"
 *		    is RETURN_DIRTY and the page is dirty, or
 *		    "should_return" is RETURN_ALL and the page
 * 		    is either dirty or precious); and,
 *		3)  flush the cached copy (if "should_flush"
 *		    is asserted).
 *	The set of pages is defined by a starting offset
 *	("offset") and size ("size").  Only pages with the
 *	same page alignment as the starting offset are
 *	considered.
 */
routine memory_object_lock_request(
		memory_control	: memory_object_control_t;
		offset		: memory_object_offset_t;
		size		: memory_object_size_t;
	out	resid_offset	: memory_object_offset_t;
	out	io_errno	: integer_t;
		should_return	: memory_object_return_t;
		flags		: integer_t;
		lock_value	: vm_prot_t
		);


/*
 */
routine memory_object_destroy(
		memory_control	: memory_object_control_t;
		reason		: kern_return_t);

/*
 *	The pager gets memory_object_data_request and memory_object_data_return
 *	calls to inform it that data within the memory object needs to be
 *	manipulated.  Those requests simply identify the range in the memory
 *	object that needs servicing, but not the data itself.  The pager
 *	turns around and requests one (or several) Universal Page Lists (UPLs)
 *	from the VM cache object associated with the memory object via one
 *	of the following calls.  These UPLs are then committed (or aborted)
 *	in whole (or in ranges) as the processing completes.
 */

routine memory_object_upl_request(
		memory_control	: memory_object_control_t;
	in	offset		: memory_object_offset_t;
	in	size		: upl_size_t;
	out	upl		: upl_t;
	out	page_list	: upl_page_info_array_t, CountInOut;
	in	cntrl_flags	: integer_t);

routine memory_object_super_upl_request(
		memory_control		: memory_object_control_t;
	in	offset		: memory_object_offset_t;
	in	size		: upl_size_t;
	in	super_size	: upl_size_t;
	out	upl		: upl_t;
	out	page_list	: upl_page_info_array_t, CountInOut;
	in	cntrl_flags	: integer_t);


routine memory_object_cluster_size(
		control		: memory_object_control_t;
	out	start		: memory_object_offset_t;
	out	length		: vm_size_t;
	out	io_streaming	: uint32_t;
	in	fault_info	: memory_object_fault_info_t);

/*
 * This functions allows a single page to be manipulated with less overhead
 * than creating a UPL.
 */
routine memory_object_page_op(
		memory_control	: memory_object_control_t;
	in	offset		: memory_object_offset_t;
	in	ops		: integer_t;
	out	phys_entry	: uint32_t;
	out	flags		: integer_t);

routine memory_object_recover_named(
		memory_control	: memory_object_control_t;
	in	wait_on_terminating : boolean_t);

routine memory_object_release_name(
		memory_control	: memory_object_control_t;
		flags		: integer_t);

routine memory_object_range_op(
		memory_control	: memory_object_control_t;
	in	offset_beg	: memory_object_offset_t;
	in	offset_end	: memory_object_offset_t;
	in      ops             : integer_t;
	out     range		: integer_t);

/* vim: set ft=c : */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
6601e61a	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.
6601e61a	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	/*
0b4e3aa0	59	* File: mach/memory_object_control.defs
1c79356b A	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_control 2000;
1c79356b A	73
1c79356b A	74	#include <mach/std_types.defs>
	75	#include <mach/mach_types.defs>
	76
1c79356b A	77	/*
	78	* Retrieves the attributes currently associated with
	79	* a memory object.
	80	*/
	81	routine memory_object_get_attributes(
0b4e3aa0	82	memory_control : memory_object_control_t;
1c79356b A	83	flavor : memory_object_flavor_t;
	84	out attributes : memory_object_info_t, CountInOut);
	85
	86
0b4e3aa0 A	87	routine memory_object_change_attributes(
0b4e3aa0 A	88	memory_control : memory_object_control_t;
1c79356b A	89	flavor : memory_object_flavor_t;
1c79356b A	90	attributes : memory_object_info_t
1c79356b A	91	);
1c79356b A	92
0b4e3aa0 A	93	routine memory_object_synchronize_completed (
	94	memory_control : memory_object_control_t;
	95	offset : memory_object_offset_t;
b0d623f7	96	length : memory_object_size_t);
1c79356b A	97
	98	/*
	99	* Control use of the data associated with the given
	100	* memory object. For each page in the given range,
	101	* perform the following operations, in order:
	102	* 1) restrict access to the page (disallow
	103	* forms specified by "prot");
	104	* 2) write back modifications (if "should_return"
	105	* is RETURN_DIRTY and the page is dirty, or
	106	* "should_return" is RETURN_ALL and the page
	107	* is either dirty or precious); and,
	108	* 3) flush the cached copy (if "should_flush"
	109	* is asserted).
	110	* The set of pages is defined by a starting offset
	111	* ("offset") and size ("size"). Only pages with the
	112	* same page alignment as the starting offset are
	113	* considered.
1c79356b	114	*/
0b4e3aa0 A	115	routine memory_object_lock_request(
0b4e3aa0 A	116	memory_control : memory_object_control_t;
1c79356b A	117	offset : memory_object_offset_t;
1c79356b A	118	size : memory_object_size_t;
91447636 A	119	out resid_offset : memory_object_offset_t;
91447636 A	120	out io_errno : integer_t;
1c79356b A	121	should_return : memory_object_return_t;
	122	flags : integer_t;
	123	lock_value : vm_prot_t
1c79356b A	124	);
	125
	126
1c79356b A	127	/*
1c79356b A	128	*/
0b4e3aa0 A	129	routine memory_object_destroy(
0b4e3aa0 A	130	memory_control : memory_object_control_t;
1c79356b A	131	reason : kern_return_t);
	132
	133	/*
0b4e3aa0 A	134	* The pager gets memory_object_data_request and memory_object_data_return
	135	* calls to inform it that data within the memory object needs to be
	136	* manipulated. Those requests simply identify the range in the memory
	137	* object that needs servicing, but not the data itself. The pager
	138	* turns around and requests one (or several) Universal Page Lists (UPLs)
	139	* from the VM cache object associated with the memory object via one
	140	* of the following calls. These UPLs are then committed (or aborted)
	141	* in whole (or in ranges) as the processing completes.
1c79356b A	142	*/
1c79356b A	143
0b4e3aa0 A	144	routine memory_object_upl_request(
	145	memory_control : memory_object_control_t;
	146	in offset : memory_object_offset_t;
b0d623f7	147	in size : upl_size_t;
0b4e3aa0 A	148	out upl : upl_t;
	149	out page_list : upl_page_info_array_t, CountInOut;
	150	in cntrl_flags : integer_t);
	151
	152	routine memory_object_super_upl_request(
	153	memory_control : memory_object_control_t;
	154	in offset : memory_object_offset_t;
b0d623f7 A	155	in size : upl_size_t;
b0d623f7 A	156	in super_size : upl_size_t;
0b4e3aa0 A	157	out upl : upl_t;
	158	out page_list : upl_page_info_array_t, CountInOut;
	159	in cntrl_flags : integer_t);
	160
2d21ac55 A	161
	162	routine memory_object_cluster_size(
	163	control : memory_object_control_t;
	164	out start : memory_object_offset_t;
	165	out length : vm_size_t;
b0d623f7	166	out io_streaming : uint32_t;
2d21ac55 A	167	in fault_info : memory_object_fault_info_t);
2d21ac55 A	168
0b4e3aa0 A	169	/*
	170	* This functions allows a single page to be manipulated with less overhead
	171	* than creating a UPL.
	172	*/
	173	routine memory_object_page_op(
	174	memory_control : memory_object_control_t;
	175	in offset : memory_object_offset_t;
	176	in ops : integer_t;
55e303ae	177	out phys_entry : uint32_t;
0b4e3aa0 A	178	out flags : integer_t);
	179
	180	routine memory_object_recover_named(
	181	memory_control : memory_object_control_t;
	182	in wait_on_terminating : boolean_t);
	183
	184	routine memory_object_release_name(
	185	memory_control : memory_object_control_t;
	186	flags : integer_t);
	187
55e303ae A	188	routine memory_object_range_op(
	189	memory_control : memory_object_control_t;
	190	in offset_beg : memory_object_offset_t;
	191	in offset_end : memory_object_offset_t;
	192	in ops : integer_t;
	193	out range : integer_t);
0b4e3aa0	194
2d21ac55	195	/* vim: set ft=c : */