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