home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 14 Text / 14-Text.zip / machdocs.zip / manual2.doc < prev    next >
Internet Message Format  |  1993-02-26  |  65KB
  1. From Pa.dec.com!nobody Thu Feb 25 20:15:35 1993
  2. Return-Path: <Pa.dec.com!nobody>
  3. Received: by ukelele.GCR.COM (Smail3.1.28.1 #1)
  4.     id m0nRtfq-0001S0a; Thu, 25 Feb 93 20:15 EST
  5. Received: from inet-gw-2.pa.dec.com by uu5.psi.com (5.65b/4.0.071791-PSI/PSINet) via SMTP;
  6.         id AA01560 for spj@ukelele.GCR.COM; Thu, 25 Feb 93 19:09:07 -0500
  7. Received: by inet-gw-2.pa.dec.com; id AA28402; Thu, 25 Feb 93 16:09:11 -0800
  8. Date: Thu, 25 Feb 93 16:09:11 -0800
  9. Message-Id: <9302260009.AA28402@inet-gw-2.pa.dec.com>
  10. From: "ftpmail service on inet-gw-2.pa.dec.com" <nobody@Pa.dec.com>
  11. To: spj@ukelele.GCR.COM
  12. Subject: part 002 of /.0/Mach/doc/manual.doc (@gatekeeper.dec.com) [Mach Dox] (ascii)
  13. X-Complaints-To: ftpmail-admin@inet-gw-2.pa.dec.com
  14. X-Service-Address: ftpmail@inet-gw-2.pa.dec.com
  15. X-Job-Number: 730680718.24209
  16. Precedence: bulk
  17. Reply-To: <nobody@inet-gw-2.pa.dec.com>
  18. Content-Type: text
  19. Content-Length: 64036
  20. Status: O
  21.  
  22. new thread to run, first thread_create  is  called  to  get  the  new  thread's
  23. identifier,(child_thread).  Then  thread_set_state is called to set a processor
  24. state, and finally thread_resume is called  to  get  the  thread  scheduled  to
  25. execute.
  26.  
  27.   When the thread is created send rights to its thread kernel port are given to
  28. it and returned to the caller in child_thread.  The new thread's exception port
  29. is set to PORT_NULL.
  30.  
  31. Arguments
  32.  
  33.   parent_task     The task which is to contain the new thread.
  34.  
  35.   child_thread    The new thread.
  36.  
  37. Returns
  38.  
  39.   KERN_SUCCESS    A new thread has been created.
  40.  
  41.   KERN_INVALID_ARGUMENT
  42.                   parent_task is not a valid task.
  43.  
  44.   KERN_RESOURCE_SHORTAGE
  45.                   Some critical kernel resource is not available.
  46.  
  47. See Also
  48.  
  49.   task_create,  task_threads,  thread_terminate, thread_suspend, thread_resume,
  50. thread_special_ports, thread_set_state
  51. thread_terminate
  52.  
  53. #include <mach.h>
  54.  
  55. kern_return_t thread_terminate(target_thread)
  56.         thread_t        target_thread;
  57.  
  58.  
  59. Arguments
  60.  
  61.   target_thread   The thread to be destroyed.
  62.  
  63. Description
  64.  
  65.   thread_terminate destroys the thread specified by target_thread.
  66.  
  67. Returns
  68.  
  69.   KERN_SUCCESS    The thread has been killed.
  70.  
  71.   KERN_INVALID_ARGUMENT
  72.                   target_thread is not a thread.
  73.  
  74. See Also
  75.  
  76.   task_terminate, task_threads, thread_create, thread_resume, thread_suspend
  77. thread_suspend
  78.  
  79. #include <mach.h>
  80.  
  81. kern_return_t thread_suspend(target_thread);
  82.         thread_t        target_thread;
  83.  
  84.  
  85. Arguments
  86.  
  87.   target_thread   The thread to be suspended.
  88.  
  89. Description
  90.  
  91.   Increments  the thread's suspend count and prevents the thread from executing
  92. any more user level instructions. In this context a user level  instruction  is
  93. either a machine instruction executed in user mode or a system trap instruction
  94. including page faults.  Thus if a thread is currently executing within a system
  95. trap the kernel code may continue to execute until it reaches the system return
  96. code or it may supend within the kernel code. In either case, when  the  thread
  97. is  resumed the system trap will return. This could cause unpredictible results
  98. if the user did a suspend and then altered the user  state  of  the  thread  in
  99. order  to change its direction upon a resume. The call thread_abort is provided
  100. to allow the user to abort any system call that is in progress in a predictable
  101. way.
  102.  
  103.   The  suspend  count  may become greater than one with the effect that it will
  104. take more than one resume call to restart the thread.
  105.  
  106. Returns
  107.  
  108.   KERN_SUCCESS    The thread has been suspended.
  109.  
  110.   KERN_INVALID_ARGUMENT
  111.                   target_thread is not a thread.
  112.  
  113. See Also
  114.  
  115.   task_suspend,    task_resume,   thread_info,   thread_state,   thread_resume,
  116. thread_terminate, thread_abort
  117. thread_resume
  118.  
  119. #include <mach.h>
  120.  
  121. kern_return_t thread_resume(target_thread)
  122.         thread_t        target_thread;
  123.  
  124.  
  125. Arguments
  126.  
  127.   target_thread   The thread to be resumed.
  128.  
  129. Description
  130.  
  131.   Decrements the threads's suspend count. If the count becomes zero the  thread
  132. is  resumed. If it is still positive, the thread is left suspended. The suspend
  133. count may not become negative.
  134.  
  135. Returns
  136.  
  137.   KERN_SUCCESS    The thread has been resumed.
  138.  
  139.   KERN_FAILURE    The suspend count is already zero.
  140.  
  141.   KERN_INVALID_ARGUMENT
  142.                   target_thread is not a thread.
  143.  
  144. See Also
  145.  
  146.   task_suspend,   task_resume   thread_info,  thread_create,  thread_terminate,
  147. thread_suspend
  148. thread_abort
  149.  
  150. #include <mach.h>
  151.  
  152. kern_return_t thread_abort(target_thread)
  153.         thread_t        target_thread;
  154.  
  155.  
  156. Arguments
  157.  
  158.   target_thread   The thread to be interrupted.
  159.  
  160. Description
  161.  
  162.   thread_abort aborts the kernel primitives: msg_send, msg_receive and  msg_rpc
  163. and  page-faults,  making  the  call  return  a  code  indicating  that  it was
  164. interrupted.  The call is interrupted  whether  or  not  the  thread  (or  task
  165. containing it) is currently suspended.  If it is supsended, the thread receives
  166. the interupt when it is resumed.
  167.  
  168.   A thread will retry an aborted page-fault if its state is not modified before
  169. it   is  resumed.    Msg_send  returns  SEND_INTERRUPTED;  msg_receive  returns
  170. RCV_INTERRUPTED; msg_rpc returns either  SEND_INTERRUPTED  or  RCV_INTERRUPTED,
  171. depending on which half of the RPC was interrupted.
  172.  
  173.   The  main  reason  for  this primitive is to allow one thread to cleanly stop
  174. another thread in a manner that will allow the future execution of  the  target
  175. thread  to  be controlled in a predictable way. thread_suspend keeps the target
  176. thread from executing any further instructions at the user level, including the
  177. return  from  a  system  call.  thread_get/set_state  allows the examination or
  178. modification of the user state of a target  thread.  However,  if  a  suspended
  179. thread  was  executing  within  a system call, it also has associated with it a
  180. kernel state. This kernel state can not be modified  by  thread_set_state  with
  181. the  result that when the thread is resumed the system call may return changing
  182. the user state and possibly user memory.  thread_abort aborts the  kernel  call
  183. from  the  target  thread's point of view by resetting the kernel state so that
  184. the thread will resume execution at the system call return with the return code
  185. value  set  to one of the interrupted codes. The system call itself will either
  186. be entirely completed or entirely aborted, depending on the precise  moment  at
  187. which the abort was received.  Thus if the thread's user state has been changed
  188. by thread_set_state, it will not be modified by any unexpected system call side
  189. effects.
  190.  
  191.   For example to simulate a Unix signal, the following sequence of calls may be
  192. used:
  193.  
  194.   thread_suspend Stops the thread
  195.  
  196.   thread_abort Interrupts any system call in progress, setting the return value
  197. to  'interrupted'.    Since  the  thread is stopped, it will not return to user
  198. code.
  199.  
  200.   thread_set_state Alters thread's state to simulate a procedure  call  to  the
  201. signal handler
  202.  
  203.   thread_resume Resumes execution at the signal handler.  If the thread's stack
  204. has been correctly set up, the thread may  return  to  the  interrupted  system
  205. call.
  206.  
  207.   (of course, the code to push an extra stack frame and change the registers is
  208. VERY machine-dependent.)
  209.  
  210.   Calling thread_abort on a non-suspended thread is pretty risky, since  it  is
  211. very  difficult  to  know exactly what system trap, if any, the thread might be
  212. executing and whether  an  interrupt  return  would  cause  the  thread  to  do
  213. something useful.
  214.  
  215. Returns
  216.  
  217.   KERN_SUCCESS    The thread received an interrupt
  218.  
  219.   KERN_INVALID_ARGUMENT
  220.                   target_thread is not a thread.
  221.  
  222. See Also
  223.  
  224.   thread_info, thread_state, thread_terminate, thread_suspend
  225. thread_special_ports
  226.  
  227. #include <mach.h>
  228.  
  229. kern_return_t thread_get_special_port(thread, which_port, special_port)
  230.         thread_t        thread;
  231.         int             which_port;
  232.         port_t          *special_port;
  233.  
  234. kern_return_t thread_set_special_port(thread, which_port, special_port)
  235.         thread_t        thread;
  236.         int             which_port;
  237.         port_t          special_port;
  238.  
  239. thread_t thread_self()
  240.  
  241. port_t thread_reply()
  242.  
  243.  
  244. Arguments
  245.  
  246.   thread          The thread for which to get the port
  247.  
  248.   which_port      the port that is requested. Is one  of  THREAD_REPLY_PORT  or
  249.                   THREAD_EXCEPTION_PORT.
  250.  
  251.   special_port    the value of the port that is being requested or being set.
  252.  
  253. Description
  254.  
  255.   get_special_port returns send rights to one of a set of special ports for the
  256. thread  specified  by  thread.  In  the  case  of  getting  the  thread's   own
  257. thread_reply_port, receive and ownership rights are also given to the thread.
  258.  
  259.   set_special_port  sets one of a set of special ports for the thread specified
  260. by thread.
  261.  
  262.   thread_self returns  the  port  to  which  kernel  calls  for  the  currently
  263. executing thread should be directed.  Currently, thread_self returns the thread
  264. kernel port which is a port for which the kernel has receive rights  and  which
  265. it  uses  to identify a thread. In the future it may be possible for one thread
  266. to  interpose  a  port  as  another's  thread's  kernel  port.  At  that  time,
  267. thread_self  will  still  return  the port to which the executing thread should
  268. direct kernel calls, but it may no longer be a port on  which  the  kernel  has
  269. receive rights.
  270.  
  271.   If  one thread, the controller, has send access to the kernel port of another
  272. thread, the subject thread, then  the  controller  thread  can  perform  kernel
  273. operations  for  the  subject  thread.  Normally only the thread itself and its
  274. parent task will have access to the thread kernel port, but any thread may pass
  275. rights to its kernel port to any other thread.
  276.  
  277.   thread_reply  returns receive, ownership and send rights to the reply port of
  278. the calling thread. The reply port is a port to which the  thread  has  receive
  279. rights.  It  is used to receive any initialization messages and as a reply port
  280. for early remote procedure calls.
  281.  
  282.   The following macros to call thread_get/set_special_port for a specific  port
  283. are    defined    in    <mach/thread_special_ports.h>:   thread_get_reply_port,
  284. thread_set_reply_port, thread_get_exception_port and thread_set_exception_port.
  285.  
  286.   A thread also has access to its task's special ports.
  287.  
  288. Returns
  289.  
  290.   KERN_SUCCESS    The port was returned or set.
  291.  
  292.   KERN_INVALID_ARGUMENT
  293.                   thread  is  not  a  thread  or  which_port is an invalid port
  294.                   selector.
  295.  
  296. See Also
  297.  
  298.   task_special_ports,thread_create
  299.  
  300. Notes
  301.  
  302.   THREAD_KERNEL_PORT   may   be   added   to   the   set    of    ports    that
  303. thread_set_special_port accepts.
  304. thread_info
  305.  
  306. #include <mach.h>
  307.  
  308. /* the definition of thread_info_data_t from mach.h - mach/thread_info.h is */
  309.  
  310.    typedef      int     *thread_info_t; /* variable length array of int */
  311.  
  312. /* only current interpretation of thread_info */
  313.  
  314.    struct thread_basic_info {
  315.         time_value_t    user_time;      /* user run time */
  316.         time_value_t    system_time;    /* system run time */
  317.         int             cpu_usage;      /* scaled cpu usage percentage */
  318.         int             base_priority;  /* base scheduling priority */
  319.         int             cur_priority;   /* current scheduling priority */
  320.         int             run_state;      /* run state (see below) */
  321.         int             flags;          /* various flags (see below) */
  322.         int             suspend_count;  /* suspend count for thread */
  323.         long            sleep_time;     /* number of seconds that thread
  324.                                            has been sleeping */
  325.    };
  326.    typedef struct thread_basic_info     *thread_basic_info_t;
  327.  
  328.    The possible values of the run_state field are:
  329.         TH_STATE_RUNNING, thread is running normally
  330.         TH_STATE_STOPPED, thread is suspended
  331.         TH_STATE_WAITING, thread is waiting normally
  332.         TH_STATE_UNINTERRUPTIBLE, thread is in an uninterruptible wait
  333.         TH_STATE_HALTED, thread is halted at a clean point
  334.  
  335.    The possible values of the flags field are:
  336.         TH_FLAGS_SWAPPED, thread is swapped out
  337.         TH_FLAGS_IDLE, thread is an idle thread
  338.  
  339.  
  340. kern_return_t thread_info(target_thread, flavor, thread_info,
  341.                                 thread_infoCnt)
  342.         thread_t                target_thread;
  343.         int                     flavor;
  344.         thread_info_t           thread_info;    /* in and out */
  345.         unsigned int            *thread_infoCnt;  /* in and out */
  346.  
  347.  
  348. Arguments
  349.  
  350.   target_thread   The thread to be affected.
  351.  
  352.   flavor          The  type  of  statistics  that  are  wanted.  Currently only
  353.                   THREAD_BASIC_INFO is implemented.
  354.  
  355.   thread_info     Statistics about the thread specified by target_thread.
  356.  
  357.   thread_infoCnt  Size    of    the    info    structure.    Currently     only
  358.                   THREAD_BASIC_INFO_COUNT is implemented.
  359.  
  360. Description
  361.  
  362.   Returns  the selected information array for a thread, as specified by flavor.
  363. thread_info is an array of integers that is supplied by the caller and returned
  364. filled  with  specified  information. thread_infoCnt is supplied as the maximum
  365. number of integers in thread_info. On return, it contains the actual number  of
  366. integers in thread_info.
  367.  
  368.   Currently  there  is  only  one  flavor  of  information  which is defined by
  369. THREAD_BASIC_INFO. Its size is defined by THREAD_BASIC_INFO_COUNT.
  370.  
  371. Returns
  372.  
  373.   KERN_SUCCESS    The call succeeded.
  374.  
  375.   KERN_INVALID_ARGUMENT
  376.                   target_thread is not a thread or flavor is not recognized.
  377.  
  378.   MIG_ARRAY_TOO_LARGE
  379.                   Returned info array is too large for thread_info. thread_info
  380.                   is  filled as much as possible.  thread_infoCnt is set to the
  381.                   number of elements that would have  been  returned  if  there
  382.                   were enough room.
  383.  
  384. See Also
  385.  
  386.   thread_special_ports, task_threads, task_info, thread_state
  387. thread_state
  388.  
  389. #include <mach.h>
  390.  
  391. kern_return_t thread_get_state(target_thread, flavor, old_state,
  392.                                 old_stateCnt)
  393.         thread_t                target_thread;
  394.         int                     flavor;
  395.         thread_state_data_t     old_state;      /* in and out */
  396.         unsigned int            *old_stateCnt;  /* in and out */
  397.  
  398. kern_return_t thread_set_state(target_thread, flavor, new_state,
  399.                                 new_stateCnt)
  400.         thread_t                target_thread;
  401.         int                     flavor;
  402.         thread_state_data_t     new_state;
  403.         unsigned int            new_stateCnt;
  404.  
  405.  
  406. Arguments
  407.  
  408.   target_thread   thread to get or set the state for.
  409.  
  410.   flavor          The  type  of state that is to be manipulated. Currently must
  411.                   be   one   of   the   following   values:   VAX_THREAD_STATE,
  412.                   ROMP_THREAD_STATE,                     SUN_THREAD_STATE_REGS,
  413.                   SUN_THREAD_STATE_FPA
  414.  
  415.   new_state       an array of state information
  416.  
  417.   old_state       an array of state information
  418.  
  419.   new_stateCnt    the size of the state information array.  Currently  must  be
  420.                   one   of   the   following   values:  VAX_THREAD_STATE_COUNT,
  421.                   ROMP_THREAD_STATE_COUNT,         SUN_THREAD_STATE_REGS_COUNT,
  422.                   SUN_THREAD_STATE_FPA_COUNT
  423.  
  424.   old_stateCnt    same as new_stateCnt
  425.  
  426. Description
  427.  
  428.   thread_get_state  returns the state component (e.g. the machine registers) of
  429. target_thread as specified by flavor.  The old_state is an  array  of  integers
  430. that  is  provided  by  the  caller  and  returned  filled  with  the specified
  431. information. old_stateCnt is input set to the maximum  number  of  integers  in
  432. old_state and returned equal to the actual number of integers in old_state.
  433.  
  434.   thread_set_state  sets  the  state  component (e.g. the machine registers) of
  435. target_thread as specified by flavor.  The new_state is an array  of  integers.
  436. new_stateCnt  is  the  number  of  elements  in  new_state.  The  entire set of
  437. registers is reset. This will do unpredictable things if target_thread  is  not
  438. suspended.
  439.  
  440.   target_thread may not be thread_self for either of these calls.
  441.  
  442.   The    definition    of    the    state    structures   can   be   found   in
  443. <machine/thread_status.h>
  444.  
  445. Returns
  446.  
  447.   KERN_SUCCESS    The state has been set or returned
  448.  
  449.   MIG_ARRAY_TOO_LARGE
  450.                   Returned   state  is  too  large  for  the  new_state  array.
  451.                   new_state is filled in as much as possible  and  new_stateCnt
  452.                   is  set  to  the number of elements that would be returned if
  453.                   there were enough room.
  454.  
  455.   KERN_INVALID_ARGUMENT
  456.                   target_thread  is not a thread or is thread_self or flavor is
  457.                   unrecogized for this machine.
  458.  
  459. See Also
  460.  
  461.   task_info, thread_info
  462. 5. Virtual memory primitives
  463.  
  464.  
  465.  
  466. 5.1. Basic terms
  467.   Each MACH task has a large virtual address space  within  which  its  threads
  468. execute.  A virtual address space is divided into fixed size pages. The size of
  469. a virtual page is set at system initialization  and  may  differ  on  different
  470. machines.  A  virtual address space may be sparse, that is, there may be ranges
  471. of addresses which are not allocated followed by ranges that are allocated.
  472.  
  473.   A task may allocate virtual memory in its address space; physical memory will
  474. be acquired only when necessary, and seldom-used memory may be paged to backing
  475. storage.
  476.  
  477.   A region of an address space is that  memory  associated  with  a  continuous
  478. range  of  addresses;  that  is,  a start address and an end address.  The MACH
  479. kernel will extend regions to include entire virtual  memory  pages  containing
  480. the  first  and  last  address  in a specified range.  Regions consist of pages
  481. which have different protection or inheritance characteristics.
  482.  
  483.   A task may protect the virtual pages of its address  space  to  allow/prevent
  484. access  to that memory.  The current protection is used to determine the access
  485. rights of an executing thread.  In addition, a maximum protection value  limits
  486. the current protection.
  487.  
  488.   A  task  may  specify  that  pages of its address space be inherited by child
  489. tasks in one of three ways: shared, copied, or  absent.    Inheritance  may  be
  490. changed  at  any  time;  only  at  the  time  of  task  creation is inheritance
  491. information used. The only way two MACH  tasks  can  share  the  same  physical
  492. memory  is  for  one  of  the  tasks  to inherit shared access to memory from a
  493. parent.  When a child task inherits memory from a  parent,  it  gets  the  same
  494. protection on that memory that its parent had.
  495.  
  496.   Protection  and  inheritance  is  attached to a task's address space, not the
  497. physical memory contained in that address space.  Tasks which share memory  may
  498. specify different protection or inheritance for their shared regions.
  499.  
  500.   Physical  pages in an address space have paging objects associated with them.
  501. These objects identify the backing storage to be used when a page is to be read
  502. in as the result of a reference or written to in order to free physical memory.
  503. A paging  object  is  identified  outside  of  the  kernel  by  an  unforgeable
  504. identifier (implemented as a port which is only used for identification and not
  505. message transmission), and inside the kernel by a data transmission port,  that
  506. will respond to get and put page calls.
  507.  
  508.   In  addition  to  memory  explicitly  allocated using vm_allocate, memory may
  509. appear in a task's address space as the result of a msg_receive operation.
  510. vm_allocate
  511.  
  512. #include <mach.h>
  513.  
  514. kern_return_t vm_allocate(target_task, address, size, anywhere)
  515.         vm_task_t       target_task;
  516.         vm_address_t    *address;       /* in/out */
  517.         vm_size_t       size;
  518.         boolean_t       anywhere;
  519.  
  520.  
  521. Arguments
  522.  
  523.   target_task     Task whose virtual address space is to be affected.
  524.  
  525.   address         Starting address.   If  the  anywhere  option  is  false,  an
  526.                   attempt  is  made to allocate virtual memory starting at this
  527.                   virtual address. If this address is not at the beginning of a
  528.                   virtual  page,  it  will be rounded down to one.  If there is
  529.                   not  enough  space  at  this  address,  no  memory  will   be
  530.                   allocated.    If the anywhere option is true, the input value
  531.                   of this address will  be  ignored,  and  the  space  will  be
  532.                   allocated  wherever  it  is  available.   In either case, the
  533.                   address at  which  memory  was  actually  allocated  will  be
  534.                   returned in address.
  535.  
  536.   size            Number  of  bytes  to  allocate  (rounded  by the system in a
  537.                   machine dependent  way  to  an  integral  number  of  virtual
  538.                   pages).
  539.  
  540.   anywhere        If  true,  the  kernel should find and allocate any region of
  541.                   the specified size, and return the address of  the  resulting
  542.                   region  in  address.    If  false,  virtual  memory  will  be
  543.                   allocated starting at address,  rounded  to  a  virtual  page
  544.                   boundary if there is sufficient space.
  545.  
  546. Description
  547.  
  548.   vm_allocate allocates a region of virtual memory, placing it in the specified
  549. task's address space.  The physical memory is not actually allocated until  the
  550. new  virtual memory is referenced.  By default, the kernel rounds all addresses
  551. down to the nearest page boundary and all memory sizes up to the  nearest  page
  552. size.    The  global  variable vm_page_size contains the page size.  task_self_
  553. returns the value of the  current  task  port  which  should  be  used  as  the
  554. target_task argument in order to allocate memory in the caller's address space.
  555. For languages other  than  C,  these  values  can  be  obtained  by  the  calls
  556. vm_statistics  and task_self.  Initially, the pages of allocated memory will be
  557. protected to allow all forms of access, and will be inherited in child tasks as
  558. a  copy.    Subsequent calls to vm_protection and vm_inheritance may be used to
  559. change these properties.  The allocated region is always zero-filled.
  560.  
  561. Returns
  562.  
  563.   KERN_SUCCESS    Memory allocated.
  564.  
  565.   KERN_INVALID_ADDRESS
  566.                   Illegal address specified.
  567.  
  568.   KERN_NO_SPACE   Not enough space left to satisfy this request
  569.  
  570. See Also
  571.  
  572.   vm_deallocate, vm_inherit, vm_protect, vm_regions, vm_statistics, task_self_
  573. vm_deallocate
  574.  
  575. #include <mach.h>
  576.  
  577. kern_return_t vm_deallocate(target_task, address, size)
  578.         vm_task_t       target_task;
  579.         vm_address_t    address;
  580.         vm_size_t       size;
  581.  
  582.  
  583. Arguments
  584.  
  585.   target_task     Task whose virtual memory is to be affected.
  586.  
  587.   address         Starting address (will be rounded down to a page boundary).
  588.  
  589.   size            Number  of  bytes to deallocate (will be rounded up to give a
  590.                   page boundary).
  591.  
  592. Description
  593.  
  594.   vm_deallocate relinquishes access to a region  of  a  task's  address  space,
  595. causing  further  access  to  that  memory to fail.  This address range will be
  596. available for reallocation.  Note, that because of the rounding to virtual page
  597. boundaries,  more  than  size  bytes  may  be  deallocated. Use vm_page_size or
  598. vm_statistics to find out the current virtual page size.
  599.  
  600.   This call may be used to deallocte memory that was passed  to  a  task  in  a
  601. message  (via  out  of  line  data). In that case, the rounding should cause no
  602. trouble, since the region of memory was allocated as a set of pages.
  603.  
  604.   The vm_deallocate call affects only the task specified  by  the  target_task.
  605. Other tasks which may have access to this memory may continue to reference it.
  606.  
  607. Returns
  608.  
  609.   KERN_SUCCESS    Memory deallocated.
  610.  
  611.   KERN_INVALID_ADDRESS
  612.                   Illegal or non-allocated address specified.
  613.  
  614. See Also
  615.  
  616.   vm_allocate, vm_statistics, msg_receive
  617. vm_read
  618.  
  619. #include <mach.h>
  620.  
  621. kern_return_t vm_read(target_task, address, size, data, data_count)
  622.         vm_task_t       target_task
  623.         vm_address_t    address;
  624.         vm_size_t       size;
  625.         pointer_t       *data;          /* out */
  626.         int             *data_count;    /* out */
  627.  
  628.  
  629. Arguments
  630.  
  631.   target_task     Task whose memory is to be read.
  632.  
  633.   address         The first address to be read (must be on a page boundary).
  634.  
  635.   size            The number of bytes of data to be read (must be  an  integral
  636.                   number of pages)
  637.  
  638.   data            The array of data copied from the given task.
  639.  
  640.   data_count      The  size  of  the data array in bytes.  (will be an integral
  641.                   number of pages).
  642.  
  643. Description
  644.  
  645.   vm_read allows one task's virtual memory to be read  by  another  task.  Note
  646. that  the  data array is returned in a newly allocated region; the task reading
  647. the data should vm_deallocate this region when it is done with the data.
  648.  
  649. Returns
  650.  
  651.   KERN_SUCCESS    Memory read.
  652.  
  653.   KERN_INVALID_ARGUMENT
  654.                   Either  the  address does not start on a page boundary or the
  655.                   size is not an integral number of pages.
  656.  
  657.   KERN_NO_SPACE   There is not enough room in the  callers  virtual  memory  to
  658.                   allocate space for the data to be returned.
  659.  
  660.   KERN_PROTECTION_FAILURE
  661.                   The address region in the target task  is  protected  against
  662.                   reading.
  663.  
  664.   KERN_INVALID_ADDRESS
  665.                   Illegal or non-allocated address specified, or there was  not
  666.                   size bytes of data following that address.
  667.  
  668. See Also
  669.  
  670.   vm_read, vm_write, vm_copy, vm_deallocate
  671. vm_write
  672.  
  673. #include <mach.h>
  674.  
  675. kern_return_t vm_write(target_task, address, data, data_count)
  676.         vm_task_t       target_task;
  677.         vm_address_t    address;
  678.         pointer_t       data;
  679.         int             data_count;
  680.  
  681.  
  682. Arguments
  683.  
  684.   target_task     Task whose memory is to be written.
  685.  
  686.   address         Starting  address  in  task  to  be  affected (must be a page
  687.                   boundary).
  688.  
  689.   data            An array of bytes to be written.
  690.  
  691.   data_count      The size of the data array (must be  an  integral  number  of
  692.                   pages).
  693.  
  694. Description
  695.  
  696.   vm_write  allows  a  task's virtual memory to be written by another task. Use
  697. vm_page_size or vm_statistics to find out the virtual page size.
  698.  
  699. Returns
  700.  
  701.   KERN_SUCCESS    Memory written.
  702.  
  703.   KERN_INVALID_ARGUMENT
  704.                   Either  the  address does not start on a page boundary or the
  705.                   size is not an integral number of pages.
  706.  
  707.   KERN_PROTECTION_FAILURE
  708.                   The  address  region  in the target task is protected against
  709.                   writing.
  710.  
  711.   KERN_INVALID_ADDRESS
  712.                   Illegal  or  non_allocated  address specified or there is not
  713.                   data_count of allocated memory starting at address.
  714.  
  715. See Also
  716.  
  717.   vm_copy, vm_protect, vm_read, vm_statistics
  718. vm_copy
  719.  
  720. #include <mach.h>
  721.  
  722. kern_return_t vm_copy (target_task, source_address, count, dest_address)
  723.         vm_task_t       target_task;
  724.         vm_address_t    source_address;
  725.         vm_size_t       count;
  726.         vm_address_t    dest_address;
  727.  
  728.  
  729. Arguments
  730.  
  731.   target_task     Task whose virtual memory is to be affected.
  732.  
  733.   source_address  Address in target_task of the start of the source range (must
  734.                   be a page boundary).
  735.  
  736.   count           Number  of  bytes  to  copy  (must  be  an integral number of
  737.                   pages).
  738.  
  739.   dest_address    Address in target_task of the start of the destination  range
  740.                   (must be a page boundary).
  741.  
  742. Description
  743.  
  744.   vm_copy  causes  the  source  memory  range  to  be copied to the destination
  745. address; the destination region  may  not  overlap  the  source  region.    The
  746. destination  address  range  must already be allocated and writable; the source
  747. range must be readable.
  748.  
  749. Returns
  750.  
  751.   KERN_SUCCESS    Memory copied.
  752.  
  753.   KERN_INVALID_ARGUMENT
  754.                   Either  the  address does not start on a page boundary or the
  755.                   size is not an integral number of pages.
  756.  
  757.   KERN_PROTECTION_FAILURE
  758.                   Either  the  destination  region was not not writable, or the
  759.                   source region was not readable.
  760.  
  761.   KERN_INVALID_ADDRESS
  762.                   Illegal  or  non-allocated  address specified or insufficient
  763.                   memory allocated at one of the addresses.
  764.  
  765. See Also
  766.  
  767.   vm_protect, vm_write, vm_statistics
  768. vm_region
  769.  
  770. #include <mach.h>
  771.  
  772. kern_return_t  vm_region(target_task, address, size, protection,
  773.                          max_protection, inheritance, shared,
  774.                          object_name, offset)
  775.         vm_task_t               target_task;
  776.         vm_address_t            *address;               /* in/out */
  777.         vm_size_t               *size;                  /* out */
  778.         vm_prot_t               *protection;            /* out */
  779.         vm_prot_t               *max_protection;        /* out */
  780.         vm_inherit_t            *inheritance;           /* out */
  781.         boolean_t               *shared;                /* out */
  782.         port_t                  *object_name;           /* out */
  783.         vm_offset_t             *offset;                /* out */
  784.  
  785.  
  786. Arguments
  787.  
  788.   target_task     The task for which an address space description is requested.
  789.  
  790.   address         The address at which to start looking for a region.
  791.  
  792.   size            The size (in bytes) of the located region.
  793.  
  794.   protection      The current protection of the region.
  795.  
  796.   max_protection  The maximum allowable protection for this region.
  797.  
  798.   inheritance     The inheritance attribute for this region.
  799.  
  800.   shared          Is this region shared or not.
  801.  
  802.   object_name     The port identifying the memory object associated  with  this
  803.                   region.  (See pager_init.)
  804.  
  805.   offset          The offset into the pager object that this region begins at.
  806.  
  807. Description
  808.  
  809.   vm_region  returns a description of the specified region of the target task's
  810. virtual address space.  vm_region begins at  address  and  looks  forward  thru
  811. memory  until it comes to an allocated region.  (If address is within a region,
  812. then that region is used.)  Various bits of information about  the  region  are
  813. returned.  If address was not within a region, then address is set to the start
  814. of the first region which follows the incoming value.  In this  way  an  entire
  815. address space can be scanned.
  816.  
  817. Returns
  818.  
  819.   KERN_SUCCESS    Region located and information returned.
  820.  
  821.   KERN_NO_SPACE   There is no region at or above address in the specified task.
  822.  
  823. See Also
  824.  
  825.   vm_allocate, vm_deallocate, vm_protect, vm_inherit
  826. vm_protect
  827.  
  828. #include <mach.h>
  829.  
  830. kern_return_t vm_protect(target_task, address, size, set_maximum,
  831.                                 new_protection)
  832.         vm_task_t       target_task;
  833.         vm_address_t    address;
  834.         vm_size_t       size;
  835.         boolean_t       set_maximum;
  836.         vm_prot_t       new_protection;
  837.  
  838.  
  839. Arguments
  840.  
  841.   target_task     Task whose virtual memory is to be affected.
  842.  
  843.   address         Starting address (will be rounded down to a page boundary).
  844.  
  845.   size            Size in bytes of the region for which protection is to change
  846.                   (will be rounded up to give a page boundary).
  847.  
  848.   set_maximum     If set, make the  protection  change  apply  to  the  maximum
  849.                   protection associated with this address range; otherwise, the
  850.                   current protection on this range is changed.  If the  maximum
  851.                   protection is reduced below the current protection, both will
  852.                   be changed to reflect the new maximum.
  853.  
  854.   new_protection  A  new  protection  value  for  this  region;   a   set   of:
  855.                   VM_PROT_READ, VM_PROT_WRITE, VM_PROT_EXECUTE.
  856.  
  857. Description
  858.  
  859.   vm_protect sets the virtual memory access privileges for a range of allocated
  860. addresses in a task's virtual address space.  The protection argument describes
  861. a combination of read, write, and execute accesses that should be permitted.
  862.  
  863.   The  enforcement  of  virtual  memory  protection is machine-dependent.  Some
  864. combinations of access rights may not be supported.  In particular, the  kernel
  865. interface  allows  any  of  the  following:    write  permission may imply read
  866. permission;  read  permission  may  imply  execute  permission;   or,   execute
  867. permission may imply read permission.
  868.  
  869.   All architectures must support the following access combinations:  all (read,
  870. write, and execute) access;  write-protected  (read  and  execute)  access;  no
  871. access.
  872.  
  873.   For the Vax, RT/PC, and Sun3, all three of the reductions stated above apply.
  874. That is:  VM_PROT_WRITE allows read, execute and write access, VM_PROT_READ  or
  875. VM_PROT_EXECUTE allows read and execute access, but not write access.
  876.  
  877. Returns
  878.  
  879.   KERN_SUCCESS    Memory protected.
  880.  
  881.   KERN_PROTECTION_FAILURE
  882.                   An attempt was  made  to  increase  the  current  or  maximum
  883.                   protection beyond the existing maximum protection value.
  884.  
  885.   KERN_INVALID_ADDRESS
  886.                   Illegal or non-allocated address specified.
  887. vm_inherit
  888.  
  889. #include <mach.h>
  890.  
  891. kern_return_t vm_inherit(target_task, address, size, new_inheritance)
  892.         vm_task_t       target_task;
  893.         vm_address_t    address;
  894.         vm_size_t       size;
  895.         vm_inherit_t    new_inheritance;
  896.  
  897.  
  898. Arguments
  899.  
  900.   target_task     Task whose virtual memory is to be affected.
  901.  
  902.   address         Starting address (will be rounded down to a page boundary).
  903.  
  904.   size            Size in bytes of the  region  for  which  inheritance  is  to
  905.                   change (will be rounded up to give a page boundary).
  906.  
  907.   new_inheritance How   this   memory  is  to  be  inherited  in  child  tasks.
  908.                   Inheritance is specified by  using  one  of  these  following
  909.                   three values:
  910.  
  911.   VM_INHERIT_SHARE
  912.                   Child tasks will share this memory with this task.
  913.  
  914.   VM_INHERIT_COPY Child tasks will receive a copy of this region.
  915.  
  916.   VM_INHERIT_NONE This region will be absent from child tasks.
  917.  
  918. Description
  919.  
  920.   vm_inherit specifies how a region of a task's address space is to  be  passed
  921. to  child  tasks  at the time of task creation.  Inheritance is an attribute of
  922. virtual pages, thus the addresses and size of memory to be set will be  rounded
  923. out to refer to whole pages.
  924.  
  925.   Setting  vm_inherit  to VM_INHERIT_SHARE and forking a child task is the only
  926. way two Mach tasks can share physical memory.  Remember that all the theads  of
  927. a given task share all the same memory.
  928.  
  929. Returns
  930.  
  931.   KERN_SUCCESS    Memory protected.
  932.  
  933.   KERN_INVALID_ADDRESS
  934.                   Illegal address specified.
  935.  
  936. See Also
  937.  
  938.   task_create, vm_regions
  939. vm_statistics
  940.  
  941. #include <mach.h>
  942.  
  943. struct vm_statistics {
  944.         long    pagesize;               /* page size in bytes */
  945.         long    free_count;             /* # of pages free */
  946.         long    active_count;           /* # of pages active */
  947.         long    inactive_count;         /* # of pages inactive */
  948.         long    wire_count;             /* # of pages wired down */
  949.         long    zero_fill_count;        /* # of zero fill pages */
  950.         long    reactivations;          /* # of pages reactivated */
  951.         long    pageins;                /* # of pageins */
  952.         long    pageouts;               /* # of pageouts */
  953.         long    faults;                 /* # of faults */
  954.         long    cow_faults;             /* # of copy-on-writes */
  955.         long    lookups;                /* object cache lookups */
  956.         long    hits;                   /* object cache hits */
  957. };
  958.  
  959. typedef struct vm_statistics    vm_statistics_data_t;
  960.  
  961. kern_return_t   vm_statistics(target_task, vm_stats)
  962.         task_t                  target_task;
  963.         vm_statistics_data_t    *vm_stats;      /* out */
  964.  
  965.  
  966. Arguments
  967.  
  968.   target_task     Task which is requesting statistics.
  969.  
  970.   vm_stats        The structure that will receive the statistics.
  971.  
  972. Description
  973.  
  974.   vm_statistics returns the statistics about the kernel's use of virtual memory
  975. since  the  kernel was booted.  pagesize can also be found as a global variable
  976. vm_page_size which is set at task initialization and remains constant  for  the
  977. life of the task.
  978.  
  979. Returns
  980.  
  981.   KERN_SUCCESS
  982. 6. Ancillary primitives
  983. mach_ports
  984.  
  985. #include <mach.h>
  986.  
  987. kern_return_t mach_ports_register(target_task,
  988.                                 init_port_set, init_port_array_count)
  989.         task_t          target_task;
  990.         port_array_t    init_port_set;         /* array */
  991.         int             init_port_array_count;
  992.  
  993. kern_return_t mach_ports_lookup(target_task,
  994.                                 init_port_set, init_port_array_count)
  995.         task_t          target_task;
  996.         port_array_t    *init_port_set;         /* out array */
  997.         int             *init_port_array_count; /* out */
  998.  
  999.  
  1000. Arguments
  1001.  
  1002.   target_task     Task to be affected.
  1003.  
  1004.   init_port_set   An  array  of  system  ports  to  be registered, or returned.
  1005.                   Although the array size is given as variable, the MACH kernel
  1006.                   will only accept a limited number of ports.
  1007.  
  1008.   init_port_array_count
  1009.                   The number of ports returned in init_port_set.
  1010.  
  1011. Description
  1012.  
  1013.   mach_ports_register registers an array of well-known system  ports  with  the
  1014. kernel on behalf of a specific task.  Currently the ports to be registered are:
  1015. the port to the Network Name Server, the port to the Environment Manager, and a
  1016. port  to the Service server. These port values must be placed in specific slots
  1017. in the init_port_set. The slot  numbers  are  given  by  the  global  constants
  1018. defined  in  mach_init.h: NAME_SERVER_SLOT, ENVIRONMENT_SLOT, and SERVICE_SLOT.
  1019. These ports may later be retrieved with mach_ports_lookup.
  1020.  
  1021.   When a new task is created (see task_create), the child task  will  be  given
  1022. access  to these ports.  Only port send rights may be registered.  Furthermore,
  1023. the number of ports which may be registered is fixed and given  by  the  global
  1024. constant MACH_PORT_SLOTS_USED.  Attempts to register too many ports will fail.
  1025.  
  1026.   It  is intended that this mechanism be used only for task initialization, and
  1027. then only by runtime support modules.  A  parent  task  has  three  choices  in
  1028. passing these system ports to a child task. Most commonly it can do nothing and
  1029. its child will inherit access to the same init_port_set that the parent has; or
  1030. a  parent  task  may register a set of ports it wishes to have passed to all of
  1031. its children by calling mach_ports_register using its task port; or it may make
  1032. necessary  modifications  to  the  set of ports it wishes its child to see, and
  1033. then register those ports using the child's task port  prior  to  starting  the
  1034. child's  thread(s).    The mach_ports_lookup call which is done by mach_init in
  1035. the child task will acquire these initial ports for the child.
  1036.  
  1037.   Tasks other than the Network Name Server and the Environment Mangager  should
  1038. not  need  access to the Service port. The Network Name Server port is the same
  1039. for all tasks on a given machine. The Environment port is the only port  likely
  1040. to have different values for different tasks.
  1041.  
  1042.   Since  the  number  of  ports which may be registered is limited, ports other
  1043. than those used by the runtime system to initialize a task should be passed  to
  1044. children  either through an initial message, or through the Network Name Server
  1045. for public ports, or the Environment Manager for private ports.
  1046.  
  1047. Returns
  1048.  
  1049.   KERN_SUCCESS    Memory allocated.
  1050.  
  1051.   KERN_INVALID_ARGUMENT
  1052.                   An  attempt  was made to register more ports than the current
  1053.                   kernel implementation allows.
  1054.  
  1055. See Also
  1056.  
  1057.   mach_init, netname, env_mgr, service
  1058. host_ipc_statistics
  1059.  
  1060. #include <mach.h>
  1061.  
  1062. kern_return_t host_ipc_statistics(task, statistics)
  1063.         task_t target_task;
  1064.         ipc_statistics_t *statistics;   /* inout */
  1065.  
  1066.  
  1067. Arguments
  1068.  
  1069.   task            Task running on the kernel whose statistics are desired.
  1070.  
  1071.   statistics      The returned statistics.
  1072.  
  1073. Description
  1074.  
  1075.   host_ipc_statistics returns the statistics about MACH IPC, since  the  kernel
  1076. was  booted.  statistics  is  a  fixed  length array provided by the user.  See
  1077. <kern/ipc_statistics.h> for a description of what is returned.
  1078.  
  1079. Returns
  1080.  
  1081.   KERN_SUCCESS    The call succeeded.
  1082.  
  1083. Notes
  1084.  
  1085.   Only kernels compiled with MACH_IPCSTATS enabled support this call.
  1086.  
  1087.   The first argument should be a host port of some kind.
  1088.  
  1089.   The meaning of the statistics varies; not all fields are used.
  1090. 7. External memory management primitives
  1091.  
  1092.  
  1093.  
  1094. 7.1. Memory Managers
  1095.   The MACH kernel allows  users  to  provide  memory  managment  (i.e.  paging)
  1096. services  outside the kernel. A server that provides such functions is called a
  1097. memory manager. There is a default memory manager that is part  of  the  kernel
  1098. and  is  normally  used  to  handle  paging  to both files and temporary memory
  1099. objects.  Users may provide additional memory managers to handle special  kinds
  1100. of  objects,  such  as  fault-tolerant  objects, objects whose backing store is
  1101. across a network link, or objects whose backing store is on devices  for  which
  1102. the kernel does not provide drivers.
  1103.  
  1104.   The  protocol  defined  in  this section consists of messages that the kernel
  1105. will send to memory managers and the primitives that the  kernel  provides  for
  1106. the  use  of  memory  managers.    Use  of  these primitives involves increased
  1107. responsibility. A memory manager is expected to respond in a timely fashion  to
  1108. all  the  requests  that  the  kernel makes of it, otherwise threads within the
  1109. kernel are left hanging and the client task that is attempting to reference the
  1110. memory object is also left hanging.
  1111.  
  1112.   It  is  also  possible  for  a  privileged user to replace the default memory
  1113. manager. This involves increased reliability and responsibility as now all  the
  1114. users of the system will be dependent on the new server.
  1115.  
  1116.  
  1117. 7.1.1. Memory objects: definitions and basics
  1118.   In  MACH,  physical  memory  is  used as a cache of the contents of secondary
  1119. storage objects called memory objects.  The virtual address space of a task  is
  1120. represented  as  a series of mappings from contiguous virtual address ranges to
  1121. such memory objects.  For each memory object the kernel keeps  track  of  those
  1122. pages  that  are  currently  in  the  physical memory cache and it allows tasks
  1123. mapped to that memory to use those physical pages.
  1124.  
  1125.   When a virtual memory request occurs that cannot be resolved through the  use
  1126. of  a  previously  cached  physical page, the kernel must make a request of the
  1127. memory object for the required data.  As the physical page cache becomes  full,
  1128. the  kernel must replace pages from the cache, writing the contents of modified
  1129. pages back to the corresponding memory objects.
  1130.  
  1131.   When a task uses the vm_allocate call, the kernel allocates a  memory  object
  1132. that provides zero-filled memory on reference; this memory object is managed by
  1133. a default memory manager.
  1134.  
  1135.   Alternatively, a task may map a specific memory object into its address space
  1136. by  issuing  a  vm_map  call.    Included  in  this  call is the memory object,
  1137. represented by a port, that is to manage the data in the allocated region.  The
  1138. kernel will use the memory object port to make requests for data, or to request
  1139. that data be written back to the object.  The memory  manager  must  act  as  a
  1140. server  for  these  requests.  The memory manager server interface differs from
  1141. other servers only in that the kernel does not synchronously await replies.
  1142.  
  1143.   A given memory object may be mapped into an arbitrary number of tasks, at any
  1144. addresses  available  in  those  tasks.  When a vm_map call is issued, the MACH
  1145. kernel will recognize the memory object if  it  has  been  mapped  before;  any
  1146. physical memory pages from this memory object already cached from previous uses
  1147. may be shared by later mappings as well.    A  single  MACH  kernel  keeps  the
  1148. physical  memory  cache consistent across all uses of the same memory object at
  1149. similar page alignments on that host.
  1150.  
  1151.   Furthermore, a single memory object may  be  mapped  into  tasks  created  on
  1152. different  hosts  (and therefore be cached by different MACH kernels).  In this
  1153. case, the memory manager is responsible for maintaining any desired consistency
  1154. among the various hosts on which its data resides.
  1155.  
  1156.  
  1157. 7.1.2. Initialization and termination
  1158.   The memory manager must define a protocol for giving out memory object ports.
  1159. This could take the form of the memory manager registering  a  general  service
  1160. port somewhere that clients could find and exporting an object create or object
  1161. lookup call that will return a memory object port. This is  the  port  that  is
  1162. passed to the kernel in the vm_map call.
  1163.  
  1164.   Upon  processing  the  first  vm_map call for a given memory object, the MACH
  1165. kernel will make a memory_object_init call, providing the memory  manager  with
  1166. two  ports:  a  control  port, and a name port.  The memory manager may use the
  1167. memory object control port to supply the kernel with data for it to  cache,  or
  1168. to perform other cache management functions.  These requests will be covered in
  1169. the next section.
  1170.  
  1171.   The memory object name, a port, will only  be  used  by  the  kernel  in  the
  1172. results  from  a  vm_region  call  to  describe  the source of data for a given
  1173. region.  Since this port is not to be used for requests for  data,  the  memory
  1174. manager  may  wish  to provide this port to clients to identify memory which it
  1175. supplies.
  1176.  
  1177.   The initialization call also includes the system page size for  the  host  on
  1178. which  the  mapping took place.  This allows the memory manager to provide data
  1179. to the kernel in whole pages, and  to  detect  mappings  at  inconsistent  page
  1180. alignments.
  1181.  
  1182.   In  order  to  indicate  its readiness to accept requests, the memory manager
  1183. must    respond    to    the    initialization     call     by     making     a
  1184. memory_object_set_attributes call, asserting the readiness parameter.
  1185.  
  1186.   Normally, when a memory object is no longer referenced by any virtual address
  1187. space, the MACH kernel will deallocate its port rights to  that  memory  object
  1188. after   sending  all  port  rights  for  the  control  and  name  ports  in  an
  1189. memory_object_terminate call.  To enhance performance,  a  memory  manager  may
  1190. allow  a MACH kernel to maintain its memory cache for a memory object after all
  1191. virtual address space references to it  are  gone,  by  asserting  the  caching
  1192. parameter  to the memory_object_set_attributes call.  However, allowing caching
  1193. does not prevent the kernel from terminating an object.
  1194.  
  1195.   In the event that a memory manager destroys a  memory  object  port  that  is
  1196. currently mapped into one or more virtual address spaces, future page faults on
  1197. addresses mapped to this object (for which data is not available in the  cache)
  1198. will result in a memory exception.
  1199.  
  1200.  
  1201. 7.1.3. Kernel-created memory objects
  1202.   As noted earlier, memory created using vm_allocate results in the creation of
  1203. a memory object; this object is created by the kernel, and  is  passed  to  the
  1204. default  memory manager, using the memory_object_create call.  Since the memory
  1205. object is initially zero-filled, it only contains data that has been modified.
  1206.  
  1207.   The memory_object_create request will only be  made  of  the  default  memory
  1208. manager.  The default memory manager must not allow any memory object passed in
  1209. a memory_object_create call to be used in any other task,  as  the  kernel  may
  1210. make  assumptions  about  such  an  object that could adversely affect external
  1211. consistency.
  1212.  
  1213.  
  1214.  
  1215. 7.2. Kernel calls supporting memory managers
  1216. vm_map
  1217.  
  1218. #include <mach.h>
  1219.  
  1220. kern_return_t vm_map(target_task, address, size, mask, anywhere,
  1221.                                 memory_object, offset, copy,
  1222.                                 cur_protection, max_protection,
  1223.                                 inheritance)
  1224.         task_t          target_task;
  1225.         vm_offset_t     *address;       /* in/out */
  1226.         vm_size_t       size;
  1227.         vm_offset_t     mask;
  1228.         boolean_t       anywhere;
  1229.         memory_object_t memory_object;
  1230.         vm_offset_t     offset;
  1231.         boolean_t       copy;
  1232.         vm_prot_t       cur_protection;
  1233.         vm_prot_t       max_protection;
  1234.         vm_inherit_t    inheritance;
  1235.  
  1236.  
  1237.  
  1238. Description
  1239.  
  1240.   vm_map maps a region of virtual memory at the specified  address,  for  which
  1241. data is to be supplied by the given memory object, starting at the given offset
  1242. within that object.  In addition to the  arguments  used  in  vm_allocate,  the
  1243. vm_map  call allows the specification of an address alignment parameter, and of
  1244. the initial protection and  inheritance  values.    [See  the  descriptions  of
  1245. vm_allocate, vm_protect, and vm_inherit.]
  1246.  
  1247.   If  the  memory  object  in question is not currently in use, the MACH kernel
  1248. will perform a memory_object_init call at this time.  If the copy parameter  is
  1249. asserted,  the  specified  region  of  the memory object will be copied to this
  1250. address space; changes made to this object by other tasks will not  be  visible
  1251. in this mapping, and changes made in this mapping will not be visible to others
  1252. (or returned to the memory object).
  1253.  
  1254.   The vm_map call returns once the mapping is established.  Completion  of  the
  1255. call does not require any action on the part of the memory manager.
  1256.  
  1257.   Warning:  Only  memory objects that are provided by bona fide memory managers
  1258. should be used in the vm_map call.  A memory manager must implement the  memory
  1259. object  interface described elsewhere in this manual.  If other ports are used,
  1260. a thread that accesses the mapped virtual memory may become permanently hung or
  1261. may receive a memory exception.
  1262.  
  1263. Arguments
  1264.  
  1265.   target_task     Task to be affected.
  1266.  
  1267.   address         Starting  address.    If  the  anywhere  option is used, this
  1268.                   address is ignored.  The address actually allocated  will  be
  1269.                   returned in address.
  1270.  
  1271.   size            Number  of  bytes  to  allocate  (rounded  by the system in a
  1272.                   machine dependent way).
  1273.  
  1274.   mask            Alignment restriction.  Bits asserted in this mask  must  not
  1275.                   be asserted in the address returned.
  1276.  
  1277.   anywhere        If set, the kernel should find and allocate any region of the
  1278.                   specified size, and  return  the  address  of  the  resulting
  1279.                   region in address.
  1280.  
  1281.   memory_object   Port that represents the memory object: used by user tasks in
  1282.                   vm_map; used by the MACH kernel to make requests for data  or
  1283.                   other    management    actions.        If    this   port   is
  1284.                   MEMORY_OBJECT_NULL,  then  zero-filled  memory  is  allocated
  1285.                   instead.
  1286.  
  1287.   offset          An  offset  within  a  memory object, in bytes.  This must be
  1288.                   page aligned.
  1289.  
  1290.   copy            If set, the range of the memory object should  be  copied  to
  1291.                   the target task, rather than mapped read-write.
  1292.  
  1293. Returns
  1294.  
  1295.   KERN_SUCCESS    The object is mapped.
  1296.  
  1297.   KERN_NO_SPACE   No  unused  region  of  the task's virtual address space that
  1298.                   meets the address, size,  and  alignment  criteria  could  be
  1299.                   found.
  1300.  
  1301.   KERN_INVALID_ARGUMENT
  1302.                   An illegal argument was provided.
  1303.  
  1304. See Also
  1305.  
  1306.   memory_object_server, vm_allocate
  1307. memory_object_set_attributes
  1308.  
  1309. #include <mach.h>
  1310.  
  1311. kern_return_t memory_object_set_attributes(memory_control,
  1312.                                 object_ready, may_cache_object,
  1313.                                 copy_strategy)
  1314.         memory_object_control_t
  1315.                         memory_control;
  1316.         boolean_t       object_ready;
  1317.         boolean_t       may_cache_object;
  1318.         memory_object_copy_strategy_t
  1319.                         copy_strategy;
  1320.  
  1321.  
  1322. Description
  1323.  
  1324.   memory_object_set_attributes controls how the MACH  kernel  uses  the  memory
  1325. object.    The  kernel  will  only  make data or unlock requests when the ready
  1326. attribute is asserted.  If the caching attribute is  asserted,  the  kernel  is
  1327. permitted  (and encouraged) to maintain cached data for this memory object even
  1328. after no virtual address space contains this data.
  1329.  
  1330.   There are three possible caching  strategies:  MEMORY_OBJECT_COPY_NONE  which
  1331. specifies  that  nothing  special  should  be  done  when data in the object is
  1332. copied; MEMORY_OBJECT_COPY_CALL which specifies that the memory manager  should
  1333. be  notified  via  a  memory_object_copy  call before any part of the object is
  1334. copied; and MEMORY_OBJECT_COPY_DELAY which guarantees that the  memory  manager
  1335. does  not  externally  modify  the  data  so that the kernel can use its normal
  1336. copy-on-write  algorithms.    MEMORY_OBJECT_COPY_DELAY  is  the  strategy  most
  1337. commonly used.
  1338.  
  1339. Arguments
  1340.  
  1341.   memory_control  The  port,  provided  by  the  kernel in a memory_object_init
  1342.                   call, to which cache management requests may be issued.
  1343.  
  1344.   object_ready    When set, the kernel may issue new data and  unlock  requests
  1345.                   on the associated memory object.
  1346.  
  1347.   may_cache_object
  1348.                   If set, the kernel may keep data associated with this  memory
  1349.                   object, even after virtual memory references to it are gone.
  1350.  
  1351.   copy_strategy   How  the  kernel should copy regions of the associated memory
  1352.                   object.
  1353.  
  1354. Returns
  1355.  
  1356.   KERN_SUCCESS    This  routine  does  not  receive  a   reply   message   (and
  1357.                   consequently   has   no   return   value),  so  only  message
  1358.                   transmission errors apply.
  1359.  
  1360. See Also
  1361.  
  1362.   memory_object_init, memory_object_copy, memory_object_attributes
  1363. memory_object_get_attributes
  1364.  
  1365. #include <mach.h>
  1366.  
  1367. kern_return_t memory_object_get_attributes(memory_control,
  1368.                                 object_ready, may_cache_object,
  1369.                                 copy_strategy)
  1370.         memory_object_control_t
  1371.                         memory_control;
  1372.         boolean_t       *object_ready;
  1373.         boolean_t       *may_cache_object;
  1374.         memory_object_copy_strategy_t
  1375.                         *copy_strategy;
  1376.  
  1377.  
  1378. Description
  1379.  
  1380.   memory_object_get_attributes retrieves the current attributes associated with
  1381. the memory object.
  1382.  
  1383. Arguments
  1384.  
  1385.   memory_control  The  port,  provided  by  the  kernel in a memory_object_init
  1386.                   call, to which cache management requests may be issued.
  1387.  
  1388.   object_ready    When set, the kernel may issue new data and  unlock  requests
  1389.                   on the associated memory object.
  1390.  
  1391.   may_cache_object
  1392.                   If set, the kernel may keep data associated with this  memory
  1393.                   object, even after virtual memory references to it are gone.
  1394.  
  1395.   copy_strategy   How  the  kernel should copy regions of the associated memory
  1396.                   object.
  1397.  
  1398. Returns
  1399.  
  1400.   KERN_SUCCESS    This  routine  does  not  receive  a   reply   message   (and
  1401.                   consequently   has   no   return   value),  so  only  message
  1402.                   transmission errors apply.
  1403.  
  1404. See Also
  1405.  
  1406.   memory_object_set_attributes, memory_object_copy
  1407. memory_object_lock_request
  1408.  
  1409. #include <mach.h>
  1410.  
  1411. kern_return_t   memory_object_lock_request(memory_control,
  1412.                                 offset, size, should_clean
  1413.                                 should_flush, lock_value, reply_to)
  1414.         memory_object_control_t
  1415.                         memory_control;
  1416.         vm_offset_t     offset;
  1417.         vm_size_t       size;
  1418.         boolean_t       should_clean;
  1419.         boolean_t       should_flush;
  1420.         vm_prot_t       lock_value;
  1421.         port_t          reply_to;
  1422.  
  1423.  
  1424. Description
  1425.  
  1426.   memory_object_lock_request allows a memory manager to make  cache  management
  1427. requests.    As  specified  in  arguments  to the call, the kernel will:  clean
  1428. (i.e., write back using memory_object_data_write) any  cached  data  which  has
  1429. been  modified since the last time it was written; flush (i.e., remove any uses
  1430. of) that data from memory; lock (i.e., prohibit  the  specified  uses  of)  the
  1431. cached  data.  Locks applied to cached data are not cumulative; new lock values
  1432. override previous ones.  Thus, data may also be unlocked using this  primitive.
  1433. The  lock  values  must  be one or more of the following values:  VM_PROT_NONE,
  1434. VM_PROT_READ, VM_PROT_WRITE, VM_PROT_EXECUTE  and  VM_PROT_ALL  as  defined  in
  1435. <mach/vm_prot.h>.
  1436.  
  1437.   Only  data  which  is  cached  at  the time of this call is affected.  When a
  1438. running thread requires a prohibited access to cached  data,  the  MACH  kernel
  1439. will  issue  a  memory_object_data_unlock  call  specifying the forms of access
  1440. required.  Once all of the actions requested by this call have been  completed,
  1441. the MACH kernel will issue a memory_object_lock_completed call on the specified
  1442. reply port.
  1443.  
  1444. Arguments
  1445.  
  1446.   memory_control  The port, provided by  the  kernel  in  a  memory_object_init
  1447.                   call, to which cache management requests may be issued.
  1448.  
  1449.   offset          An  offset  within  a  memory object, in bytes.  This must be
  1450.                   page aligned.
  1451.  
  1452.   size            The amount of cached data (starting at offset) to be handled,
  1453.                   must be an integral multiple of the memory object page size.
  1454.  
  1455.   should_clean    If  set,  modified  data should be written back to the memory
  1456.                   manager.
  1457.  
  1458.   should_flush    If set, the specified cached data should be invalidated,  and
  1459.                   all uses of that data should be revoked.
  1460.  
  1461.   lock_value      A  protection  value  indicating  those  forms of access that
  1462.                   should not be permitted to the specified cached data.
  1463.  
  1464.   reply_to        A port on which a memory_object_lock_completed call should be
  1465.                   issued, or PORT_NULL if no acknowledgement is desired.
  1466.  
  1467. Returns
  1468.  
  1469.   KERN_SUCCESS    This   routine   does   not  receive  a  reply  message  (and
  1470.                   consequently  has  no  return   value),   so   only   message
  1471.                   transmission errors apply.
  1472.  
  1473. See Also
  1474.  
  1475.   memory_object_lock_completed, memory_object_data_unlock
  1476. memory_object_data_provided
  1477.  
  1478. #include <mach.h>
  1479.  
  1480. kern_return_t memory_object_data_provided(memory_control,
  1481.                                 offset, data, data_count, lock_value)
  1482.         memory_object_control_t
  1483.                         memory_control;
  1484.         vm_offset_t     offset;
  1485.         pointer_t       data;
  1486.         int             data_count;
  1487.         vm_prot_t       lock_value;
  1488.  
  1489.  
  1490.  
  1491. Description
  1492.  
  1493.   memory_object_data_provided  supplies  the kernel with data for the specified
  1494. memory object.  Ordinarily, memory managers should only provide data in reponse
  1495. to  memory_object_data_request calls from the kernel.  The lock_value specifies
  1496. what type of access will not be allowed to the data range. The lock values must
  1497. be  one  or  more  of  the  set:    VM_PROT_NONE,  VM_PROT_READ, VM_PROT_WRITE,
  1498. VM_PROT_EXECUTE and VM_PROT_ALL as defined in <mach/vm_prot.h>.
  1499.  
  1500. Arguments
  1501.  
  1502.   memory_control  The port, provided by  the  kernel  in  a  memory_object_init
  1503.                   call, to which cache management requests may be issued.
  1504.  
  1505.   offset          An  offset  within  a  memory object, in bytes.  This must be
  1506.                   page aligned.
  1507.  
  1508.   data            Data that is being provided to the kernel. This is a  pointer
  1509.                   to the data.
  1510.  
  1511.   data_count      The  amount  of  data  to  be  provided.  Must be an integral
  1512.                   number of memory object pages.
  1513.  
  1514.   lock_value      A protection value indicating  those  forms  of  access  that
  1515.                   should not be permitted to the specified cached data.
  1516.  
  1517. Returns
  1518.  
  1519.   KERN_SUCCESS    This   routine   does   not  receive  a  reply  message  (and
  1520.                   consequently  has  no  return   value),   so   only   message
  1521.                   transmission errors apply.
  1522.  
  1523. See Also
  1524.  
  1525.   memory_object_data_request,                         memory_object_data_error,
  1526. memory_object_lock_request
  1527. memory_object_data_unavailable
  1528.  
  1529. #include <mach.h>
  1530.  
  1531. kern_return_t memory_object_data_unavailable(memory_control,
  1532.                                 offset, size);
  1533.         memory_object_control_t
  1534.                         memory_control;
  1535.         vm_offset_t     offset;
  1536.         vm_size_t       size;
  1537.  
  1538.  
  1539. Description
  1540.  
  1541.   memory_object_data_unavailable indicates that the memory object does not have
  1542. data  for the given region and that the kernel should provide the data for this
  1543. range. The memory manager may use this call in three different  situations.  1)
  1544. The  object  was  created  by  memory_object_create  and the kernel has not yet
  1545. provided data for this range (either via a memory_object_data_initialize  or  a
  1546. memory_object_data_write.  In  this  case  the kernel should supply zero-filled
  1547. pages for the object. 2) The object was created by  an  memory_object_data_copy
  1548. and  the kernel should copy this region from the original memory object. 3) The
  1549. object is a normal user-created memory object  and  the  kernel  should  supply
  1550. unlocked zero-filled pages for the range.
  1551.  
  1552. Arguments
  1553.  
  1554.   memory_control  The  port,  provided  by  the  kernel in a memory_object_init
  1555.                   call, to which cache management requests may be issued.
  1556.  
  1557.   offset          An offset within a memory object, in bytes.    This  must  be
  1558.                   page aligned.
  1559.  
  1560.   size            The amount of cached data (starting at offset) to be handled.
  1561.                   This must be an integral multiple of the memory  object  page
  1562.                   size.
  1563.  
  1564. Returns
  1565.  
  1566.   KERN_SUCCESS    This   routine   does   not  receive  a  reply  message  (and
  1567.                   consequently  has  no  return   value),   so   only   message
  1568.                   transmission errors apply.
  1569.  
  1570. See Also
  1571.  
  1572.   memory_object_create, memory_object_data_request, memory_object_data_error
  1573. memory_object_data_error
  1574.  
  1575. #include <mach.h>
  1576.  
  1577. kern_return_t memory_object_data_error(memory_control,
  1578.                                 offset, size, reason);
  1579.         memory_object_control_t
  1580.                         memory_control;
  1581.         vm_offset_t     offset;
  1582.         vm_size_t       size;
  1583.         kern_return_t   reason;
  1584.  
  1585.  
  1586. Description
  1587.  
  1588.   memory_object_data_error  indicates that the memory manager cannot return the
  1589. data requested for the given region, specifying a reason for the error.    This
  1590. is typically used when a hardware error is encountered.
  1591.  
  1592. Arguments
  1593.  
  1594.   memory_control  The  port,  provided  by  the  kernel in a memory_object_init
  1595.                   call, to which cache management requests may be issued.
  1596.  
  1597.   offset          An offset within a memory object, in bytes.    This  must  be
  1598.                   page aligned.
  1599.  
  1600.   size            The amount of cached data (starting at offset) to be handled.
  1601.                   This must be an integral multiple of the memory  object  page
  1602.                   size.
  1603.  
  1604.   reason          Could be a Unix error code for a hardware error.
  1605.  
  1606. Returns
  1607.  
  1608.   KERN_SUCCESS    This   routine   does   not  receive  a  reply  message  (and
  1609.                   consequently  has  no  return   value),   so   only   message
  1610.                   transmission errors apply.
  1611.  
  1612. See Also
  1613.  
  1614.   memory_object_data_request, memory_object_data_provided
  1615.  
  1616. Notes
  1617.  
  1618.   The error code is currently ignored.
  1619. memory_object_destroy
  1620.  
  1621. #include <mach.h>
  1622.  
  1623. kern_return_t memory_object_destroy(memory_control, reason);
  1624.         memory_object_control_t
  1625.                         memory_control;
  1626.         kern_return_t   reason;
  1627.  
  1628.  
  1629. Description
  1630.  
  1631.   memory_object_destroy  tells the kernel to shut down the memory object.  As a
  1632. result of this call the kernel will no longer support paging  activity  or  any
  1633. memory_object  calls  on this object, and all rights to the memory object port,
  1634. the memory control port and the memory name port will be returned to the memory
  1635. manager  in  a memory_object_terminate call. If the memory manager is concerned
  1636. that any  modified  cached  data  be  returned  to  it  before  the  object  is
  1637. terminated, it should call memory_object_lock_request with should_flush set and
  1638. a lock value of VM_PROT_WRITE before making this call.
  1639.  
  1640. Arguments
  1641.  
  1642.   memory_control  The port, provided by  the  kernel  in  a  memory_object_init
  1643.                   call, to which cache management requests may be issued.
  1644.  
  1645.   reason          An error code indicating when the object must be destroyed.
  1646.  
  1647. Returns
  1648.  
  1649.   KERN_SUCCESS    This   routine   does   not  receive  a  reply  message  (and
  1650.                   consequently  has  no  return   value),   so   only   message
  1651.                   transmission errors apply.
  1652.  
  1653. See Also
  1654.  
  1655.   memory_object_terminate, memory_object_lock_request
  1656.  
  1657. Notes
  1658.  
  1659.   The error code is currently ingnored.
  1660. vm_set_default_memory_manager
  1661.  
  1662. #include <mach.h>
  1663.  
  1664. routine vm_set_default_memory_manager(host,default_manager)
  1665.         task_t          host;
  1666.         memory_object_t default_manager;        /* in/out */
  1667.  
  1668.  
  1669. Description
  1670.  
  1671.   vm_set_default_memory_manager  sets  the kernel's default memory manager.  It
  1672. sets the port to which newly-created temporary memory objects are delivered  by
  1673. memory_object_create to the host.  The old memory manager port is returned.  If
  1674. default_manager is PORT_NULL then this routine just returns the current default
  1675. manager port without changing it.
  1676.  
  1677. Arguments
  1678.  
  1679.   host            A  task port to the kernel whose default memory manager is to
  1680.  
  1681.