Return to memory_object.defs CVS log

Up to [Apple Darwin 0.x] / kernel / mach

Annotation of kernel/mach/memory_object.defs, revision 1.1

1.1     ! root        1: /*
        !             2:  * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
        !             3:  *
        !             4:  * @APPLE_LICENSE_HEADER_START@
        !             5:  * 
        !             6:  * Portions Copyright (c) 1999 Apple Computer, Inc.  All Rights
        !             7:  * Reserved.  This file contains Original Code and/or Modifications of
        !             8:  * Original Code as defined in and that are subject to the Apple Public
        !             9:  * Source License Version 1.1 (the "License").  You may not use this file
        !            10:  * except in compliance with the License.  Please obtain a copy of the
        !            11:  * License at http://www.apple.com/publicsource and read it before using
        !            12:  * this file.
        !            13:  * 
        !            14:  * The Original Code and all software distributed under the License are
        !            15:  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
        !            16:  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
        !            17:  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
        !            18:  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
        !            19:  * License for the specific language governing rights and limitations
        !            20:  * under the License.
        !            21:  * 
        !            22:  * @APPLE_LICENSE_HEADER_END@
        !            23:  */
        !            24: 
        !            25: /* 
        !            26:  * Mach Operating System
        !            27:  * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
        !            28:  * All Rights Reserved.
        !            29:  * 
        !            30:  * Permission to use, copy, modify and distribute this software and its
        !            31:  * documentation is hereby granted, provided that both the copyright
        !            32:  * notice and this permission notice appear in all copies of the
        !            33:  * software, derivative works or modified versions, and any portions
        !            34:  * thereof, and that both notices appear in supporting documentation.
        !            35:  * 
        !            36:  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
        !            37:  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
        !            38:  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
        !            39:  * 
        !            40:  * Carnegie Mellon requests users of this software to return to
        !            41:  * 
        !            42:  *  Software Distribution Coordinator  or  [email protected]
        !            43:  *  School of Computer Science
        !            44:  *  Carnegie Mellon University
        !            45:  *  Pittsburgh PA 15213-3890
        !            46:  * 
        !            47:  * any improvements or extensions that they make and grant Carnegie Mellon
        !            48:  * the rights to redistribute these changes.
        !            49:  */
        !            50: /*
        !            51:  * HISTORY
        !            52:  * $Log: memory_object.defs,v $
        !            53:  * Revision 1.1.1.1.666.4  1999/03/16 17:05:40  wsanchez
        !            54:  * Substitute License
        !            55:  *
        !            56:  * Revision 1.1.1.1.666.3  1999/03/16 15:28:03  wsanchez
        !            57:  * Substitute copyright
        !            58:  *
        !            59:  * Revision 1.1.1.1.666.2  1999/03/16 10:37:39  umeshv
        !            60:  * Fixed errors in previous commit.
        !            61:  *
        !            62:  * Revision 1.1.1.1.666.1  1999/03/11 09:52:50  umeshv
        !            63:  * Added copyrights.
        !            64:  *
        !            65:  * Revision 1.1.1.1  1997/09/30 02:44:51  wsanchez
        !            66:  * Import of kernel from umeshv/kernel
        !            67:  *
        !            68:  * Revision 2.9  91/08/28  11:15:19  jsb
        !            69:  *     Added conditionalized sequence number support.
        !            70:  *     [91/08/13            rpd]
        !            71:  *     Fixed memory_object_supply_completed and memory_object_data_return
        !            72:  *     to use mach_port_t as the C type name for port arguments.
        !            73:  *     [91/08/02            rpd]
        !            74:  *     Update types in new memory object routines.  Add
        !            75:  *     memory_object_change_completed.
        !            76:  *     [91/07/03  14:05:39  dlb]
        !            77:  * 
        !            78:  * Revision 2.8  91/07/01  08:25:16  jsb
        !            79:  *     From David Black at OSF: added memory_object_supply_completed
        !            80:  *     and memory_object_data_return.
        !            81:  *     [91/06/29  14:54:47  jsb]
        !            82:  * 
        !            83:  * Revision 2.7  91/06/25  10:30:30  rpd
        !            84:  *     Changed the port-based type declarations
        !            85:  *     to use mach_port_t as the C type name.
        !            86:  *     [91/05/23            rpd]
        !            87:  * 
        !            88:  * Revision 2.6  91/06/17  15:47:26  jsb
        !            89:  *     If KERNEL and NORMA_VM, then use a userprefix (to allow interposition).
        !            90:  *     [91/06/17  10:55:06  jsb]
        !            91:  * 
        !            92:  * Revision 2.5  91/05/14  16:55:36  mrt
        !            93:  *     Correcting copyright
        !            94:  * 
        !            95:  * Revision 2.4  91/02/05  17:33:53  mrt
        !            96:  *     Changed to new Mach copyright
        !            97:  *     [91/02/01  17:19:02  mrt]
        !            98:  * 
        !            99:  * Revision 2.3  90/08/06  17:06:11  rpd
        !           100:  *     For compatibility with Mach 2.5, added dealloc to
        !           101:  *     arguments of memory_object_terminate and memory_object_copy.
        !           102:  *     [90/08/04            rpd]
        !           103:  * 
        !           104:  * Revision 2.2  90/06/02  14:58:51  rpd
        !           105:  *     Changed memory_object argument to memory_object_lock_completed
        !           106:  *     to default to a send-once right but still allow send rights.
        !           107:  *     [90/05/31            rpd]
        !           108:  * 
        !           109:  *     Converted to new IPC.
        !           110:  *     [90/03/26  22:35:02  rpd]
        !           111:  * 
        !           112:  * Revision 2.1  89/08/03  17:18:02  rwd
        !           113:  * Created.
        !           114:  * 
        !           115:  * Revision 2.3  89/02/25  18:38:17  gm0w
        !           116:  *     Changes for cleanup.
        !           117:  * 
        !           118:  * Revision 2.2  89/01/15  16:31:06  rpd
        !           119:  *     Moved from kern/ to mach/.
        !           120:  *     [89/01/15  14:40:04  rpd]
        !           121:  * 
        !           122:  * Revision 2.6  89/01/12  07:58:12  rpd
        !           123:  *     Fixed includes.
        !           124:  *     [89/01/12  04:52:21  rpd]
        !           125:  * 
        !           126:  * Revision 2.5  88/12/19  02:46:15  mwyoung
        !           127:  *     Change argument to memory_object_init to avoid lint in the MiG
        !           128:  *     output.
        !           129:  *     [88/12/18            mwyoung]
        !           130:  *     
        !           131:  *     Add memory_object_copy.
        !           132:  *     [88/11/07            mwyoung]
        !           133:  * 
        !           134:  * Revision 2.4  88/08/25  18:16:54  mwyoung
        !           135:  *     Add memory_object_terminate.
        !           136:  *     [88/08/11  18:46:46  mwyoung]
        !           137:  * 
        !           138:  * 29-Jun-88  Michael Young (mwyoung) at Carnegie-Mellon University
        !           139:  *     Use new types.
        !           140:  *
        !           141:  * 29-Jun-88  Michael Young (mwyoung) at Carnegie-Mellon University
        !           142:  *     Moved data type declarations to "mach_types.defs".
        !           143:  *
        !           144:  *  9-Dec-87  Michael Young (mwyoung) at Carnegie-Mellon University
        !           145:  *     Split that part of the interface applicable only to default
        !           146:  *     pagers into a separate interface definition.
        !           147:  *
        !           148:  *     Documented the interface.
        !           149:  *     
        !           150:  *     Purged history.  Contributors so far: jle, mwyoung, bolosky.
        !           151:  *
        !           152:  */
        !           153: /*
        !           154:  * File:       mach/memory_object.defs
        !           155:  *
        !           156:  * Abstract:
        !           157:  *     Basic Mach external memory management interface declaration.
        !           158:  */
        !           159: 
        !           160: subsystem
        !           161: #if    KERNEL_USER
        !           162:          KernelUser
        !           163: #endif KERNEL_USER
        !           164: #if    KERNEL_SERVER
        !           165:          KernelServer
        !           166: #endif KERNEL_SERVER
        !           167:                     memory_object 2200;
        !           168: 
        !           169: #include <mach/std_types.defs>
        !           170: #include <mach/mach_types.defs>
        !           171: 
        !           172: #if    SEQNOS
        !           173: serverprefix seqnos_;
        !           174: serverdemux seqnos_memory_object_server;
        !           175: #endif SEQNOS
        !           176: 
        !           177: /*
        !           178:  *     Initialize the specified memory object, providing
        !           179:  *     a reqeust port on which control calls can be made, and
        !           180:  *     a name port that identifies this object to callers of
        !           181:  *     vm_regions.
        !           182:  *     [To allow the mapping of this object to be used, the
        !           183:  *     memory manager must call memory_object_set_attributes,
        !           184:  *     specifying the "ready" parameter as TRUE.  To reject
        !           185:  *     all mappings of this object, the memory manager may
        !           186:  *     use memory_object_destroy.]
        !           187:  */
        !           188: simpleroutine  memory_object_init(
        !           189:                memory_object           : memory_object_t;
        !           190: #if    SEQNOS
        !           191:        msgseqno seqno                  : mach_port_seqno_t;
        !           192: #endif SEQNOS
        !           193:                memory_control          : memory_object_control_t =
        !           194:                                                MACH_MSG_TYPE_MAKE_SEND
        !           195:                                                ctype: mach_port_t;
        !           196:                memory_object_name      : memory_object_name_t =
        !           197:                                                MACH_MSG_TYPE_MAKE_SEND
        !           198:                                                ctype: mach_port_t;
        !           199:                memory_object_page_size : vm_size_t);
        !           200: 
        !           201: /*
        !           202:  *     Indicates that the specified memory object is no longer
        !           203:  *     mapped (or cached -- see memory_object_set_attributes),
        !           204:  *     and that further mappings will cause another memory_object_init
        !           205:  *     call to be made.  No further calls will be made on
        !           206:  *     the memory object by this kernel.
        !           207:  *
        !           208:  *     [All rights to the control and name ports are included
        !           209:  *     in this call.  The memory manager should use port_deallocate
        !           210:  *     to release them once they are no longer needed.]
        !           211:  */
        !           212: simpleroutine  memory_object_terminate(
        !           213:                memory_object           : memory_object_t =
        !           214:                                                MACH_MSG_TYPE_MOVE_SEND
        !           215:                                                ctype: mach_port_t;
        !           216: #if    SEQNOS
        !           217:        msgseqno seqno                  : mach_port_seqno_t;
        !           218: #endif SEQNOS
        !           219:                memory_control          : memory_object_control_t =
        !           220:                                                MACH_MSG_TYPE_MOVE_RECEIVE
        !           221:                                                ctype: mach_port_t
        !           222: #if    KERNEL_USER
        !           223:                /* for compatibility with Mach 2.5 kernels */
        !           224:                                                , dealloc
        !           225: #endif KERNEL_USER
        !           226:                                                ;
        !           227:                memory_object_name      : memory_object_name_t =
        !           228:                                                MACH_MSG_TYPE_MOVE_RECEIVE
        !           229:                                                ctype: mach_port_t
        !           230: #if    KERNEL_USER
        !           231:                /* for compatibility with Mach 2.5 kernels */
        !           232:                                                , dealloc
        !           233: #endif KERNEL_USER
        !           234:                                                );
        !           235: 
        !           236: /*
        !           237:  *     Indicates that a copy has been made of the specified range of
        !           238:  *     the given original memory object.  The kernel will use the new
        !           239:  *     memory object, control and name ports to refer to the new copy
        !           240:  *     (once the memory manager has asserted its "ready" attribute).
        !           241:  *
        !           242:  *     Cached pages from the original memory object at the time of
        !           243:  *     the copy operation are handled as follows:
        !           244:  *             Readable pages may be silently copied to the new
        !           245:  *              memory object (with all access permissions).
        !           246:  *             Pages not copied are locked to prevent write access.
        !           247:  *
        !           248:  *     This call includes only the new memory object itself; a
        !           249:  *     memory_object_init call will be made on the new memory
        !           250:  *     object after the actions above are completed.
        !           251:  *
        !           252:  *     The new memory object is *temporary*, meaning that the
        !           253:  *     memory manager should not change its contents or allow
        !           254:  *     the memory object to be mapped in another client.  The
        !           255:  *     memory manager may use the memory_object_data_unavailable
        !           256:  *     call to indicate that the appropriate page of the original
        !           257:  *     memory object may be used to fulfill a data request.
        !           258:  *
        !           259:  *     [Reply should be memory_object_set_attributes on the
        !           260:  *     new memory object control port to indicate readiness.]
        !           261:  */
        !           262: simpleroutine  memory_object_copy(
        !           263:                old_memory_object       : memory_object_t;
        !           264: #if    SEQNOS
        !           265:        msgseqno seqno                  : mach_port_seqno_t;
        !           266: #endif SEQNOS
        !           267:                old_memory_control      : memory_object_control_t =
        !           268:                                                MACH_MSG_TYPE_MAKE_SEND
        !           269:                                                ctype: mach_port_t;
        !           270:                offset                  : vm_offset_t;
        !           271:                length                  : vm_size_t;
        !           272:                new_memory_object       : memory_object_t =
        !           273:                                                MACH_MSG_TYPE_MOVE_RECEIVE
        !           274:                                                ctype: mach_port_t
        !           275: #if    KERNEL_USER
        !           276:                /* for compatibility with Mach 2.5 kernels */
        !           277:                                                , dealloc
        !           278: #endif KERNEL_USER
        !           279:                                                );
        !           280: 
        !           281: /*
        !           282:  *     Request data from this memory object.  At least
        !           283:  *     the specified data should be returned with at
        !           284:  *     least the specified access permitted.
        !           285:  *
        !           286:  *     [Reply should be memory_object_data_provided.]
        !           287:  */
        !           288: simpleroutine  memory_object_data_request(
        !           289:                memory_object           : memory_object_t;
        !           290: #if    SEQNOS
        !           291:        msgseqno seqno                  : mach_port_seqno_t;
        !           292: #endif SEQNOS
        !           293:                memory_control          : memory_object_control_t =
        !           294:                                                MACH_MSG_TYPE_MAKE_SEND
        !           295:                                                ctype: mach_port_t;
        !           296:                offset                  : vm_offset_t;
        !           297:                length                  : vm_size_t;
        !           298:                desired_access          : vm_prot_t);
        !           299: 
        !           300: /*
        !           301:  *     Request that the specified portion of this
        !           302:  *     memory object be unlocked to allow the specified
        !           303:  *     forms of access; the kernel already has the data.
        !           304:  *
        !           305:  *     [Reply should be memory_object_lock_request.]
        !           306:  */
        !           307: simpleroutine  memory_object_data_unlock(
        !           308:                memory_object           : memory_object_t;
        !           309: #if    SEQNOS
        !           310:        msgseqno seqno                  : mach_port_seqno_t;
        !           311: #endif SEQNOS
        !           312:                memory_control          : memory_object_control_t =
        !           313:                                                MACH_MSG_TYPE_MAKE_SEND
        !           314:                                                ctype: mach_port_t;
        !           315:                offset                  : vm_offset_t;
        !           316:                length                  : vm_size_t;
        !           317:                desired_access          : vm_prot_t);
        !           318: 
        !           319: /*
        !           320:  *     Write back modifications made to this portion of
        !           321:  *     the memory object while in memory.
        !           322:  *
        !           323:  *     Unless explicitly requested by a memory_object_lock_request
        !           324:  *     (clean, but not flush), the kernel will not retain
        !           325:  *     the data.
        !           326:  *
        !           327:  *     [Reply should be vm_deallocate to release the data.]
        !           328:  */
        !           329: simpleroutine  memory_object_data_write(
        !           330:                memory_object           : memory_object_t;
        !           331: #if    SEQNOS
        !           332:        msgseqno seqno                  : mach_port_seqno_t;
        !           333: #endif SEQNOS
        !           334:                memory_control          : memory_object_control_t =
        !           335:                                                MACH_MSG_TYPE_MAKE_SEND
        !           336:                                                ctype: mach_port_t;
        !           337:                offset                  : vm_offset_t;
        !           338:                data                    : pointer_t);
        !           339: 
        !           340: /*
        !           341:  *     Indicate that a previous memory_object_lock_reqeust has been
        !           342:  *     completed.  Note that this call is made on whatever
        !           343:  *     port is specified in the memory_object_lock_request; that port
        !           344:  *     need not be the memory object port itself.
        !           345:  *
        !           346:  *     [No reply expected.]
        !           347:  */
        !           348: simpleroutine  memory_object_lock_completed(
        !           349:                memory_object           : memory_object_t =
        !           350:                        polymorphic|MACH_MSG_TYPE_PORT_SEND_ONCE
        !           351:                        ctype: mach_port_t;
        !           352: #if    SEQNOS
        !           353:        msgseqno seqno                  : mach_port_seqno_t;
        !           354: #endif SEQNOS
        !           355:                memory_control          : memory_object_control_t =
        !           356:                                                MACH_MSG_TYPE_MAKE_SEND
        !           357:                                                ctype: mach_port_t;
        !           358:                offset                  : vm_offset_t;
        !           359:                length                  : vm_size_t);
        !           360: 
        !           361: /*
        !           362:  *     Indicate that a previous memory_object_data_supply has been
        !           363:  *     completed.  Note that this call is made on whatever
        !           364:  *     port is specified in the memory_object_data_supply; that port
        !           365:  *     need not be the memory object port itself.
        !           366:  *
        !           367:  *     The result parameter indicates what happened during the supply.
        !           368:  *     If it is not KERN_SUCCESS, then error_offset identifies the
        !           369:  *     first offset at which a problem occurred.  The pagein operation
        !           370:  *     stopped at this point.  Note that the only failures reported
        !           371:  *     by this mechanism are KERN_MEMORY_PRESENT.  All other failures
        !           372:  *     (invalid argument, error on pagein of supplied data in manager's
        !           373:  *     address space) cause the entire operation to fail.
        !           374:  *
        !           375:  *     XXX Check what actually happens in latter case!
        !           376:  *
        !           377:  *     [No reply expected.]
        !           378:  */
        !           379: simpleroutine  memory_object_supply_completed(
        !           380:                memory_object           : memory_object_t =
        !           381:                        polymorphic|MACH_MSG_TYPE_PORT_SEND_ONCE
        !           382:                        ctype: mach_port_t;
        !           383: #if    SEQNOS
        !           384:        msgseqno seqno                  : mach_port_seqno_t;
        !           385: #endif SEQNOS
        !           386:                memory_control          : memory_object_control_t =
        !           387:                                                MACH_MSG_TYPE_MAKE_SEND
        !           388:                                                ctype: mach_port_t;
        !           389:                offset                  : vm_offset_t;
        !           390:                length                  : vm_size_t;
        !           391:                result                  : kern_return_t;
        !           392:                error_offset            : vm_offset_t);
        !           393: 
        !           394: /*
        !           395:  *     Return data to manager.  This call is used in place of data_write
        !           396:  *     for objects initialized by object_ready instead of set_attributes.
        !           397:  *     This call indicates whether the returned data is dirty and whether
        !           398:  *     the kernel kept a copy.  Precious data remains precious if the
        !           399:  *     kernel keeps a copy.  The indication that the kernel kept a copy
        !           400:  *     is only a hint if the data is not precious; the cleaned copy may
        !           401:  *     be discarded without further notifying the manager.
        !           402:  *
        !           403:  *     [Reply should be vm_deallocate to release the data.]
        !           404:  */
        !           405: simpleroutine   memory_object_data_return(
        !           406:                memory_object           : memory_object_t;
        !           407: #if    SEQNOS
        !           408:        msgseqno seqno                  : mach_port_seqno_t;
        !           409: #endif SEQNOS
        !           410:                memory_control          : memory_object_control_t =
        !           411:                                                MACH_MSG_TYPE_MAKE_SEND
        !           412:                                                ctype: mach_port_t;
        !           413:                offset                  : vm_offset_t;
        !           414:                data                    : pointer_t;
        !           415:                dirty                   : boolean_t;
        !           416:                kernel_copy             : boolean_t);
        !           417: 
        !           418: /*
        !           419:  * XXX Warning:  This routine does NOT contain a memory_object_control_t
        !           420:  * XXX because the memory_object_change_attributes call may cause
        !           421:  * XXX  memory object termination (by uncaching the object).  This would
        !           422:  * XXX  yield an invalid port.
        !           423:  */
        !           424: 
        !           425: simpleroutine  memory_object_change_completed(
        !           426:                memory_object           : memory_object_t =
        !           427:                        polymorphic|MACH_MSG_TYPE_PORT_SEND_ONCE
        !           428:                        ctype: mach_port_t;
        !           429: #if    SEQNOS
        !           430:        msgseqno seqno                  : mach_port_seqno_t;
        !           431: #endif SEQNOS
        !           432:                may_cache               : boolean_t;
        !           433:                copy_strategy           : memory_object_copy_strategy_t);

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.