![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mach.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GnuMach] / Gnu-Mach / doc|
Return to mach.texi CVS log | Up to [GnuMach] / Gnu-Mach / doc |
1.1 root 1: \input texinfo @c -*- Texinfo -*-
2: @setfilename mach.info
3: @settitle The GNU Mach Reference Manual
4: @setchapternewpage odd
5:
6: @comment Tell install-info what to do.
7: @dircategory Kernel
8: @direntry
9: * GNUMach: (mach). Using and programming the GNU Mach microkernel.
10: @end direntry
11:
12: @c Should have a glossary.
13: @c Unify some of our indices.
14: @syncodeindex pg cp
15: @syncodeindex vr fn
16: @syncodeindex tp fn
17:
18: @c Get the Mach version we are documenting.
19: @include version.texi
20: @set EDITION 0.4
21: @c @set ISBN X-XXXXXX-XX-X
22:
1.1.1.2 root 23: @copying
1.1 root 24: This file documents the GNU Mach microkernel.
25:
1.1.1.2 root 26: This is edition @value{EDITION}, last updated on @value{UPDATED}, of @cite{The
27: GNU Mach Reference Manual}, for version @value{VERSION}.
1.1 root 28:
1.1.1.2 root 29: Copyright @copyright{} 2001, 2002, 2006, 2007, 2008 Free Software
30: Foundation, Inc.
1.1 root 31:
1.1.1.2 root 32: @c @sp 2
33: @c Published by the Free Software Foundation @*
34: @c 59 Temple Place -- Suite 330, @*
35: @c Boston, MA 02111-1307 USA @*
36: @c ISBN @value{ISBN} @*
37:
38: @quotation
1.1 root 39: Permission is granted to copy, distribute and/or modify this document
1.1.1.2 root 40: under the terms of the GNU Free Documentation License, Version 1.2 or
41: any later version published by the Free Software Foundation; with no
42: Invariant Section, with no Front-Cover Texts, and with no Back-Cover
43: Texts. A copy of the license is included in the section entitled
44: ``GNU Free Documentation License''.
1.1 root 45:
46: This work is based on manual pages under the following copyright and license:
47:
48: @noindent
49: Mach Operating System@*
50: Copyright @copyright{} 1991,1990 Carnegie Mellon University@*
51: All Rights Reserved.
52:
53: Permission to use, copy, modify and distribute this software and its
54: documentation is hereby granted, provided that both the copyright
55: notice and this permission notice appear in all copies of the
56: software, derivative works or modified versions, and any portions
57: thereof, and that both notices appear in supporting documentation.
58:
59: CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
60: CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
61: ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
1.1.1.2 root 62: @end quotation
63: @end copying
1.1 root 64:
65: @iftex
66: @shorttitlepage The GNU Mach Reference Manual
67: @end iftex
68: @titlepage
69: @center @titlefont{The GNU Mach}
70: @sp 1
71: @center @titlefont{Reference Manual}
72: @sp 2
73: @center Marcus Brinkmann
74: @center with
75: @center Gordon Matzigkeit, Gibran Hasnaoui,
76: @center Robert V. Baron, Richard P. Draves, Mary R. Thompson, Joseph S. Barrera
77: @sp 3
78: @center Edition @value{EDITION}
79: @sp 1
80: @center last updated @value{UPDATED}
81: @sp 1
82: @center for version @value{VERSION}
83: @page
84: @vskip 0pt plus 1filll
1.1.1.2 root 85: @insertcopying
1.1 root 86: @end titlepage
87: @c @titlepage
88: @c @finalout
89: @c @title The GNU Mach Reference Manual
90: @c @author Marcus Brinkmann
91: @c @author Gordon Matzigkeit
92: @c @author Gibran Hasnaoui
93:
94: @c @author Robert V. Baron @c (rvb)
95: @c @author Richard P. Draves @c (rpd)
96: @c @author Mary R. Thompson @c (mrt)
97: @c @author Joseph S. Barrera @c (jsb)
1.1.1.2 root 98: @c @c The following occur rarely in the rcs commit logs of the man pages:
1.1 root 99: @c @c Dan Stodolsky, (danner)
100: @c @c David B. Golub, (dbg)
101: @c @c Terri Watson, (elf)
102: @c @c Lori Iannamico, (lli) [distribution coordinator]
103: @c @c Further authors of kernel_interfaces.ps:
104: @c @c David Black [OSF]
105: @c @c William Bolosky
106: @c @c Jonathan Chew
107: @c @c Alessandro Forin
108: @c @c Richard F. Rashid
109: @c @c Avadis Tevanian Jr.
110: @c @c Michael W. Young
111: @c @c See also
112: @c @c http://www.cs.cmu.edu/afs/cs/project/mach/public/www/people-former.html
113: @page
114:
115: @ifnottex
116: @node Top
117: @top Main Menu
1.1.1.2 root 118:
119: @insertcopying
1.1 root 120: @end ifnottex
121:
122: @menu
123: * Introduction:: How to use this manual.
124: * Installing:: Setting up GNU Mach on your computer.
125: * Bootstrap:: Running GNU Mach on your machine.
126: * Inter Process Communication:: Communication between process.
127: * Virtual Memory Interface:: Allocating and deallocating virtual memory.
128: * External Memory Management:: Handling memory pages in user space.
129: * Threads and Tasks:: Handling of threads and tasks.
130: * Host Interface:: Interface to a Mach host.
131: * Processors and Processor Sets:: Handling processors and sets of processors.
1.1.1.2 root 132: * Device Interface:: Accessing kernel devices.
1.1 root 133: * Kernel Debugger:: How to use the built-in kernel debugger.
134:
135: Appendices
136:
137: * Copying:: The GNU General Public License says how you
138: can copy and share the GNU Mach microkernel.
139: * Documentation License:: This manual is under the GNU Free
140: Documentation License.
141:
142: Indices
143:
144: * Concept Index:: Index of concepts and programs.
145: * Function and Data Index:: Index of functions, variables and data types.
146:
147:
148: @detailmenu
149: --- The Detailed Node Listing ---
150:
151: Introduction
152:
153: * Audience:: The people for whom this manual is written.
154: * Features:: Reasons to install and use GNU Mach.
155: * Overview:: Basic architecture of the Mach microkernel.
156: * History:: The story about Mach.
157:
158: Installing
159:
160: * Binary Distributions:: Obtaining ready-to-run GNU distributions.
161: * Compilation:: Building GNU Mach from its source code.
162: * Configuration:: Configuration options at compilation time.
163: * Cross-Compilation:: Building GNU Mach from another system.
164:
165: Bootstrap
166:
167: * Bootloader:: Starting the microkernel, or other OSes.
168: * Modules:: Starting the first task of the OS.
169:
170: Inter Process Communication
171:
172: * Major Concepts:: The concepts behind the Mach IPC system.
173: * Messaging Interface:: Composing, sending and receiving messages.
174: * Port Manipulation Interface:: Manipulating ports, port rights, port sets.
175:
176: Messaging Interface
177:
178: * Mach Message Call:: Sending and receiving messages.
179: * Message Format:: The format of Mach messages.
180: * Exchanging Port Rights:: Sending and receiving port rights.
181: * Memory:: Passing memory regions in messages.
182: * Message Send:: Sending messages.
183: * Message Receive:: Receiving messages.
184: * Atomicity:: Atomicity of port rights.
185:
186: Port Manipulation Interface
187:
188: * Port Creation:: How to create new ports and port sets.
189: * Port Destruction:: How to destroy ports and port sets.
190: * Port Names:: How to query and manipulate port names.
191: * Port Rights:: How to work with port rights.
192: * Ports and other Tasks:: How to move rights between tasks.
193: * Receive Rights:: How to work with receive rights.
194: * Port Sets:: How to work with port sets.
195: * Request Notifications:: How to request notifications for events.
1.1.1.3 ! root 196: * Inherited Ports:: How to work with the inherited system ports.
1.1 root 197:
198: Virtual Memory Interface
199:
200: * Memory Allocation:: Allocation of new virtual memory.
201: * Memory Deallocation:: Freeing unused virtual memory.
202: * Data Transfer:: Reading, writing and copying memory.
203: * Memory Attributes:: Tweaking memory regions.
204: * Mapping Memory Objects:: How to map memory objects.
205: * Memory Statistics:: How to get statistics about memory usage.
206:
207: External Memory Management
208:
209: * Memory Object Server:: The basics of external memory management.
210: * Memory Object Creation:: How new memory objects are created.
211: * Memory Object Termination:: How memory objects are terminated.
212: * Memory Objects and Data:: Data transfer to and from memory objects.
213: * Memory Object Locking:: How memory objects are locked.
214: * Memory Object Attributes:: Manipulating attributes of memory objects.
215: * Default Memory Manager:: Setting and using the default memory manager.
216:
217: Threads and Tasks
218:
219: * Thread Interface:: Manipulating threads.
220: * Task Interface:: Manipulating tasks.
221: * Profiling:: Profiling threads and tasks.
222:
223: Thread Interface
224:
225: * Thread Creation:: Creating threads.
226: * Thread Termination:: Terminating threads.
227: * Thread Information:: How to get informations on threads.
228: * Thread Settings:: How to set threads related informations.
229: * Thread Execution:: How to control the thread's machine state.
230: * Scheduling:: Operations on thread scheduling.
231: * Thread Special Ports:: How to handle the thread's special ports.
232: * Exceptions:: Managing exceptions.
233:
234: Scheduling
235:
236: * Thread Priority:: Changing the priority of a thread.
237: * Hand-Off Scheduling:: Switch to a new thread.
238: * Scheduling Policy:: Setting the scheduling policy.
239:
240: Task Interface
241:
242: * Task Creation:: Creating tasks.
243: * Task Termination:: Terminating tasks.
244: * Task Information:: Informations on tasks.
245: * Task Execution:: Thread scheduling in a task.
246: * Task Special Ports:: How to get and set the task's special ports.
247: * Syscall Emulation:: How to emulate system calls.
248:
249: Host Interface
250:
251: * Host Ports:: Ports representing a host.
252: * Host Information:: Query information about a host.
253: * Host Time:: Functions to query manipulate the host time.
254: * Host Reboot:: Rebooting the system.
255:
256: Processors and Processor Sets
257:
258: * Processor Set Interface:: How to work with processor sets.
259: * Processor Interface:: How to work with individual processors.
260:
261: Processor Set Interface
262:
263: * Processor Set Ports:: Ports representing a processor set.
264: * Processor Set Access:: How the processor sets are accessed.
265: * Processor Set Creation:: How new processor sets are created.
266: * Processor Set Destruction:: How processor sets are destroyed.
267: * Tasks and Threads on Sets:: Assigning tasks or threads to processor sets.
268: * Processor Set Priority:: Specifying the priority of a processor set.
269: * Processor Set Policy:: Changing the processor set policies.
270: * Processor Set Info:: Obtaining information about a processor set.
271:
272: Processor Interface
273:
274: * Hosted Processors:: Getting a list of all processors on a host.
275: * Processor Control:: Starting, stopping, controlling processors.
276: * Processors and Sets:: Combining processors into processor sets.
277: * Processor Info:: Obtaining information on processors.
278:
279: Device Interface
280:
281: * Device Open:: Opening hardware devices.
282: * Device Close:: Closing hardware devices.
283: * Device Read:: Reading data from the device.
284: * Device Write:: Writing data to the device.
285: * Device Map:: Mapping devices into virtual memory.
286: * Device Status:: Querying and manipulating a device.
287: * Device Filter:: Filtering packets arriving on a device.
288:
289: Kernel Debugger
290:
291: * Operation:: Basic architecture of the kernel debugger.
292: * Commands:: Available commands in the kernel debugger.
293: * Variables:: Access of variables from the kernel debugger.
294: * Expressions:: Usage of expressions in the kernel debugger.
295:
296: Documentation License
297:
1.1.1.2 root 298: * GNU Free Documentation License:: The GNU Free Documentation License.
1.1 root 299: * CMU License:: The CMU license applies to the original Mach
300: kernel and its documentation.
301:
302: @end detailmenu
303: @end menu
304:
305:
306: @node Introduction
307: @chapter Introduction
308:
309: GNU Mach is the microkernel of the GNU Project. It is the base of the
310: operating system, and provides its functionality to the Hurd servers,
311: the GNU C Library and all user applications. The microkernel itself
312: does not provide much functionality of the system, just enough to make
313: it possible for the Hurd servers and the C library to implement the missing
314: features you would expect from a POSIX compatible operating system.
315:
316: @menu
317: * Audience:: The people for whom this manual is written.
318: * Features:: Reasons to install and use GNU Mach.
319: * Overview:: Basic architecture of the Mach microkernel.
320: * History:: The story about Mach.
321: @end menu
322:
323:
324: @node Audience
325: @section Audience
326:
327: This manual is designed to be useful to everybody who is interested in
328: using, administering, or programming the Mach microkernel.
329:
330: If you are an end-user and you are looking for help on running the Mach
331: kernel, the first few chapters of this manual describe the essential
332: parts of installing and using the kernel in the GNU operating system.
333:
334: The rest of this manual is a technical discussion of the Mach
335: programming interface and its implementation, and would not be helpful
336: until you want to learn how to extend the system or modify the kernel.
337:
338: This manual is organized according to the subsystems of Mach, and each
339: chapter begins with descriptions of conceptual ideas that are related to
340: that subsystem. If you are a programmer and want to learn more about,
341: say, the Mach IPC subsystem, you can skip to the IPC chapter
342: (@pxref{Inter Process Communication}), and read about the related
343: concepts and interface definitions.
344:
345:
346: @node Features
347: @section Features
348:
349: GNU Mach is not the most advanced microkernel known to the planet,
350: nor is it the fastest or smallest, but it has a rich set of interfaces and
351: some features which make it useful as the base of the Hurd system.
352:
353: @table @asis
354: @item it's free software
355: Anybody can use, modify, and redistribute it under the terms of the GNU
356: General Public License (@pxref{Copying}). GNU Mach is part of the GNU
357: system, which is a complete operating system licensed under the GPL.
358:
359: @item it's built to survive
360: As a microkernel, GNU Mach doesn't implement a lot of the features
361: commonly found in an operating system, but only the bare minimum
362: that is required to implement a full operating system on top of it.
363: This means that a lot of the operating system code is maintained outside
364: of GNU Mach, and while this code may go through a complete redesign, the
365: code of the microkernel can remain comparatively stable.
366:
367: @item it's scalable
368: Mach is particularly well suited for SMP and network cluster techniques.
369: Thread support is provided at the kernel level, and the kernel itself
370: takes advantage of that. Network transparency at the IPC level makes
371: resources of the system available across machine boundaries (with NORMA
372: IPC, currently not available in GNU Mach).
373:
374: @item it exists
375: The Mach microkernel is real software that works Right Now.
376: It is not a research or a proposal. You don't have to wait at all
377: before you can start using and developing it. Mach has been used in
378: many operating systems in the past, usually as the base for a single
379: UNIX server. In the GNU system, Mach is the base of a functional
380: multi-server operating system, the Hurd.
381: @end table
382:
383:
384: @node Overview
385: @section Overview
386:
387: @c This paragraph by Gordon Matzigkeit from the Hurd manual.
388: An operating system kernel provides a framework for programs to share a
389: computer's hardware resources securely and efficiently. This requires
1.1.1.2 root 390: that the programs are separated and protected from each other. To make
1.1 root 391: running multiple programs in parallel useful, there also needs to be a
392: facility for programs to exchange information by communication.
393:
394: The Mach microkernel provides abstractions of the underlying hardware
395: resources like devices and memory. It organizes the running programs
396: into tasks and threads (points of execution in the tasks). In addition,
397: Mach provides a rich interface for inter-process communication.
398:
399: What Mach does not provide is a POSIX compatible programming interface.
400: In fact, it has no understanding of file systems, POSIX process semantics,
401: network protocols and many more. All this is implemented in tasks
402: running on top of the microkernel. In the GNU operating system, the Hurd
403: servers and the C library share the responsibility to implement the POSIX
404: interface, and the additional interfaces which are specific to the GNU
405: system.
406:
407:
408: @node History
409: @section History
410:
411: XXX A few lines about the history of Mach here.
412:
413:
414: @node Installing
415: @chapter Installing
416:
417: Before you can use the Mach microkernel in your system you'll need to install
418: it and all components you want to use with it, e.g. the rest of the operating
419: system. You also need a bootloader to load the kernel from the storage
420: medium and run it when the computer is started.
421:
422: GNU Mach is only available for Intel i386-compatible architectures
423: (such as the Pentium) currently. If you have a different architecture
424: and want to run the GNU Mach microkernel, you will need to port the
425: kernel and all other software of the system to your machine's architecture.
426: Porting is an involved process which requires considerable programming skills,
427: and it is not recommended for the faint-of-heart.
428: If you have the talent and desire to do a port, contact
429: @email{bug-hurd@@gnu.org} in order to coordinate the effort.
430:
431: @menu
432: * Binary Distributions:: Obtaining ready-to-run GNU distributions.
433: * Compilation:: Building GNU Mach from its source code.
434: * Configuration:: Configuration options at compile time.
435: * Cross-Compilation:: Building GNU Mach from another system.
436: @end menu
437:
438:
439: @node Binary Distributions
440: @section Binary Distributions
441:
442: By far the easiest and best way to install GNU Mach and the operating
443: system is to obtain a GNU binary distribution. The GNU operating
444: system consists of GNU Mach, the Hurd, the C library and many applications.
445: Without the GNU operating system, you will only have a microkernel, which
446: is not very useful by itself, without the other programs.
447:
448: Building the whole operating system takes a huge effort, and you are well
449: advised to not do it yourself, but to get a binary distribution of the
450: GNU operating system. The distribution also includes a binary of the
451: GNU Mach microkernel.
452:
453: Information on how to obtain the GNU system can be found in the Hurd
454: info manual.
455:
456:
457: @node Compilation
458: @section Compilation
459:
460: If you already have a running GNU system, and only want to recompile
461: the kernel, for example to select a different set of included hardware
462: drivers, you can easily do this. You need the GNU C compiler and
1.1.1.2 root 463: MIG, the Mach interface generator, which both come in their own
1.1 root 464: packages.
465:
466: Building and installing the kernel is as easy as with any other GNU
467: software package. The configure script is used to configure the source
468: and set the compile time options. The compilation is done by running:
469:
470: @example
471: make
472: @end example
473:
474: To install the kernel and its header files, just enter the command:
475:
476: @example
477: make install
478: @end example
479:
1.1.1.2 root 480: This will install the kernel as @file{EXEC_PREFIX/boot/gnumach}, the header
481: files into @file{PREFIX/include/}, the list of message ids as
482: @file{PREFIX/share/msgids/gnumach.msgids} and the documentation into
483: @file{PREFIX/share/info/}.
484:
485: Note that there is also a way to only install the header and documentation
486: files without having to actually build the whole package: run @command{make
487: install-data} after having ran @command{configure} to do so. (This is needed
488: for bootstrapping a cross compiler and similar procedures.)
1.1 root 489:
490: @node Configuration
491: @section Configuration
492:
1.1.1.2 root 493: See the following tables for the options can be passed to the
494: @command{configure} script as command line arguments to control what components
495: are built into the kernel, how certain things are configured and so on.
496:
497: See the top-level @file{INSTALL} file for information about generic
498: @command{configure} options, like under which paths to install the package's
499: components. It also describes how to control the process by setting
500: environment variables.
501:
502: The file @file{i386/README-Drivers} has some i386-specific information for
503: device drivers. You should only need to consult this file in case a device
504: driver is not working for you.
1.1 root 505:
1.1.1.2 root 506: @subsection Table of configure switches not related to device drivers
1.1 root 507:
508: @table @code
509: @item --enable-kdb
1.1.1.2 root 510: In-kernel debugger. This is only useful if you actually anticipate debugging
511: the kernel. It is not enabled by default because it adds considerably to the
512: unpageable memory footprint of the kernel. @xref{Kernel Debugger}.
513: @end table
514:
515: @table @code
516: @item --enable-pae
517: @acronym{PAE, Physical Address Extension} feature (@samp{ix86}-only),
518: which is available on modern @samp{ix86} processors; on @samp{ix86-at} disabled
519: by default, on @samp{ix86-xen} enabled by default.
520: @end table
521:
522: @subsection Turning device drivers on or off
1.1 root 523:
1.1.1.2 root 524: Each device driver has an associated configure switch. The following table
525: indicates whether a device driver is enabled by default or not. It also gives
526: --- if possible at all --- the configure switches to use for disabling or
527: enabling device drivers, in case you're not satisfied with the default choices.
528: You can specify @samp{--enable-device-drivers=WHICH} (where WHICH on
529: @samp{ix86-at} must be one of @samp{default}, @samp{qemu}, @samp{none}) to
530: preset a certain subset of all available device drivers.
531: @samp{--enable-device-drivers} is sugar for
532: @samp{--enable-device-drivers=default} (and is the implicit default
533: nevertheless) and @samp{--disable-device-drivers} is short for
534: @samp{--enable-device-drivers=none}. @samp{qemu} will include only the set of
535: device drivers that is useful when using the resulting kernel binary to drive a
536: Hurd system in the @acronym{QEMU} system emulator. This is only useful for
537: reducing the kernel build time and the kernel image size.
538:
539: @subsection What the configure switches do
540:
541: Each configure switch has two effects. First, it defines a @acronym{CPP}
542: symbol that turns on or off the hooks that autoconfigure the device and add it
543: to the list of available devices. Second, it adds the source code for the
544: driver to a make variable so that the code for the driver is compiled and
545: linked into the kernel. Also follow this route to find the file(s) which are
546: implementing a certain device driver.
547:
548: @subsection Table of configure switches related to device drivers
549:
550: (@samp{%d} in the following denotes a unit number, starting with @samp{0}.)
551:
552: @table @code
553: @item --disable-kmsg
554: Kernel message device @samp{kmsg}.
1.1 root 555:
556: @item --enable-lpr
1.1.1.2 root 557: Parallel port device driver for the @samp{lpr%d} devices. On @samp{ix86-at}
558: enabled by @samp{default}.
1.1 root 559:
560: @item --enable-floppy
1.1.1.2 root 561: PC floppy disk controller device driver for the @samp{fd%d} devices. On
562: @samp{ix86-at} enabled by @samp{default} and for @samp{qemu}.
1.1 root 563:
564: @item --enable-ide
1.1.1.2 root 565: IDE controller device driver for the @samp{hd%d} and @samp{hd%ds%d} (disks and
566: their partitions) devices. On @samp{ix86-at} enabled by @samp{default} and for
567: @samp{qemu}.
1.1 root 568: @end table
569:
1.1.1.2 root 570: The following options control drivers for various SCSI controller. SCSI
571: devices are named @samp{sd%d} and @samp{sd%ds$d} (disks and their partitions)
572: or @samp{cd%d} (CD ROMs).
1.1 root 573:
574: @table @code
575: @item --enable-advansys
1.1.1.2 root 576: AdvanSys SCSI controller device driver. On @samp{ix86-at} enabled by
577: @samp{default}.
1.1 root 578:
579: @item --enable-buslogic
1.1.1.2 root 580: BusLogic SCSI controller device driver. On @samp{ix86-at} enabled by
581: @samp{default}.
1.1 root 582:
1.1.1.2 root 583: @item --enable-flashpoint
584: Only meaningful in conjunction with the above BusLogic SCSI controller device
585: driver. Enable the FlashPoint support.
586:
587: @item --enable-u14-34f
588: UltraStor 14F/34F SCSI controller device driver. On @samp{ix86-at} enabled by
589: @samp{default}.
1.1 root 590:
591: @item --enable-ultrastor
1.1.1.2 root 592: UltraStor SCSI controller device driver. On @samp{ix86-at} enabled by
593: @samp{default}.
1.1 root 594:
595: @item --enable-aha152x
1.1.1.2 root 596: Adaptec AHA-152x/2825 SCSI controller device driver. On @samp{ix86-at} enabled
597: by @samp{default}.
1.1 root 598:
599: @item --enable-aha1542
1.1.1.2 root 600: Adaptec AHA-1542 SCSI controller device driver. On @samp{ix86-at} enabled by
601: @samp{default}.
1.1 root 602:
603: @item --enable-aha1740
1.1.1.2 root 604: Adaptec AHA-1740 SCSI controller device driver. On @samp{ix86-at} enabled by
605: @samp{default}.
1.1 root 606:
607: @item --enable-aic7xxx
1.1.1.2 root 608: Adaptec AIC7xxx SCSI controller device driver. On @samp{ix86-at} enabled by
609: @samp{default}.
1.1 root 610:
1.1.1.2 root 611: @item --enable-fdomain
612: Future Domain 16xx SCSI controller device driver. On @samp{ix86-at} enabled by
613: @samp{default}.
1.1 root 614:
615: @item --enable-in2000
1.1.1.2 root 616: Always IN 2000 SCSI controller device driver. On @samp{ix86-at} enabled by
617: @samp{default}.
1.1 root 618:
1.1.1.2 root 619: @item --enable-g_NCR5380
620: Generic NCR5380/53c400 SCSI controller device driver.
1.1 root 621:
1.1.1.2 root 622: @item --enable-NCR53c406a
623: NCR53c406a SCSI controller device driver.
1.1 root 624:
625: @item --enable-pas16
1.1.1.2 root 626: PAS16 SCSI controller device driver. On @samp{ix86-at} enabled by
627: @samp{default}.
1.1 root 628:
629: @item --enable-seagate
1.1.1.2 root 630: Seagate ST02 and Future Domain TMC-8xx SCSI controller device driver. On
631: @samp{ix86-at} enabled by @samp{default}.
1.1 root 632:
633: @item --enable-t128
1.1.1.2 root 634: Trantor T128/T128F/T228 SCSI controller device driver. On @samp{ix86-at}
635: enabled by @samp{default}.
636:
637: @item --enable-53c78xx
638: NCR53C7,8xx SCSI controller device driver. On @samp{ix86-at} enabled by
639: @samp{default}.
640:
641: @item --enable-eata_dma
642: EATA-DMA (DPT, NEC, AT&T, SNI, AST, Olivetti, Alphatronix) SCSI controller
643: device driver.
644:
645: @item --enable-eata_pio
646: EATA-PIO (old DPT PM2001, PM2012A) SCSI controller device driver. On
647: @samp{ix86-at} enabled by @samp{default}.
1.1 root 648:
649: @item --enable-wd7000
1.1.1.2 root 650: WD 7000 SCSI controller device driver. On @samp{ix86-at} enabled by
651: @samp{default}.
1.1 root 652:
653: @item --enable-eata
1.1.1.2 root 654: EATA ISA/EISA/PCI (DPT and generic EATA/DMA-compliant boards) SCSI controller
655: device driver. On @samp{ix86-at} enabled by @samp{default}.
1.1 root 656:
657: @item --enable-am53c974
1.1.1.2 root 658: AM53/79C974 SCSI controller device driver. On @samp{ix86-at} enabled by
659: @samp{default}.
1.1 root 660:
1.1.1.2 root 661: @item --enable-dtc
662: DTC3180/3280 SCSI controller device driver. On @samp{ix86-at} enabled by
663: @samp{default}.
1.1 root 664:
665: @item --enable-ncr53c8xx
1.1.1.2 root 666: NCR53C8XX, dc390w, dc390u, dc390f SCSI controller device driver. On
667: @samp{ix86-at} enabled by @samp{default}.
668:
669: @item --enable-tmscsim
670: Tekram DC-390(T) SCSI controller device driver. On @samp{ix86-at} enabled by
671: @samp{default}.
1.1 root 672:
673: @item --enable-ppa
1.1.1.2 root 674: IOMEGA Parallel Port ZIP drive device driver. On @samp{ix86-at} enabled by
675: @samp{default}.
1.1 root 676:
677: @item --enable-qlogicfas
1.1.1.2 root 678: Qlogic FAS SCSI controller device driver. On @samp{ix86-at} enabled by
679: @samp{default}.
1.1 root 680:
681: @item --enable-qlogicisp
1.1.1.2 root 682: Qlogic ISP SCSI controller device driver. On @samp{ix86-at} enabled by
683: @samp{default}.
1.1 root 684:
685: @item --enable-gdth
1.1.1.2 root 686: GDT SCSI Disk Array controller device driver. On @samp{ix86-at} enabled by
687: @samp{default}.
1.1 root 688: @end table
689:
1.1.1.2 root 690: The following options enable drivers for various ethernet cards. NIC devices
691: are usually named @samp{eth%d}, except for the pocket adaptors.
1.1 root 692:
1.1.1.2 root 693: @c GNU Mach does only autodetect one ethernet card. To enable any further
694: @c cards, the source code has to be edited.
1.1 root 695: @c XXX Reference to the source code.
696:
697: @table @code
1.1.1.2 root 698: @item --enable-ne
699: NE2000/NE1000 ISA network card device driver. On @samp{ix86-at} enabled by
700: @samp{default} and for @samp{qemu}.
1.1 root 701:
702: @item --enable-3c503
1.1.1.2 root 703: 3Com 503 (Etherlink II) network card device driver. On @samp{ix86-at} enabled
704: by @samp{default}.
1.1 root 705:
706: @item --enable-3c509
1.1.1.2 root 707: 3Com 509/579 (Etherlink III) network card device driver. On @samp{ix86-at}
708: enabled by @samp{default}.
1.1 root 709:
1.1.1.2 root 710: @item --enable-wd
711: WD80X3 network card device driver. On @samp{ix86-at} enabled by
712: @samp{default}.
1.1 root 713:
714: @item --enable-3c501
1.1.1.2 root 715: 3COM 501/Etherlink I network card device driver. On @samp{ix86-at} enabled by
716: @samp{default}.
1.1 root 717:
1.1.1.2 root 718: @item --enable-smc-ultra
719: SMC Ultra network card device driver. On @samp{ix86-at} enabled by
720: @samp{default}.
721:
722: @item --enable-smc-ultra32
723: SMC Ultra 32 network card device driver. On @samp{ix86-at} enabled by
724: @samp{default}.
725:
726: @item --enable-hp-plus
727: HP PCLAN+ (27247B and 27252A) network card device driver. On @samp{ix86-at}
728: enabled by @samp{default}.
729:
730: @item --enable-hp
731: HP PCLAN (27245 and other 27xxx series) network card device driver. On
732: @samp{ix86-at} enabled by @samp{default}.
1.1 root 733:
734: @item --enable-3c59x
1.1.1.2 root 735: 3Com 590/900 series (592/595/597/900/905) "Vortex/Boomerang" network card
736: device driver. On @samp{ix86-at} enabled by @samp{default}.
1.1 root 737:
738: @item --enable-seeq8005
1.1.1.2 root 739: Seeq8005 network card device driver. On @samp{ix86-at} enabled by
740: @samp{default}.
1.1 root 741:
742: @item --enable-hp100
1.1.1.2 root 743: HP 10/100VG PCLAN (ISA, EISA, PCI) network card device driver. On
744: @samp{ix86-at} enabled by @samp{default}.
1.1 root 745:
746: @item --enable-ac3200
1.1.1.2 root 747: Ansel Communications EISA 3200 network card device driver. On @samp{ix86-at}
748: enabled by @samp{default}.
1.1 root 749:
750: @item --enable-e2100
1.1.1.2 root 751: Cabletron E21xx network card device driver. On @samp{ix86-at} enabled by
752: @samp{default}.
1.1 root 753:
754: @item --enable-at1700
1.1.1.2 root 755: AT1700 (Fujitsu 86965) network card device driver. On @samp{ix86-at} enabled
756: by @samp{default}.
1.1 root 757:
758: @item --enable-eth16i
1.1.1.2 root 759: ICL EtherTeam 16i/32 network card device driver. On @samp{ix86-at} enabled by
760: @samp{default}.
1.1 root 761:
762: @item --enable-znet
1.1.1.2 root 763: Zenith Z-Note network card device driver. On @samp{ix86-at} enabled by
764: @samp{default}.
1.1 root 765:
766: @item --enable-eexpress
1.1.1.2 root 767: EtherExpress 16 network card device driver. On @samp{ix86-at} enabled by
768: @samp{default}.
1.1 root 769:
1.1.1.2 root 770: @item --enable-eepro
771: EtherExpressPro network card device driver. On @samp{ix86-at} enabled by
772: @samp{default}.
773:
774: @item --enable-eepro100
775: Intel EtherExpressPro PCI 10+/100B/100+ network card device driver. On
776: @samp{ix86-at} enabled by @samp{default}.
1.1 root 777:
778: @item --enable-depca
1.1.1.2 root 779: DEPCA, DE10x, DE200, DE201, DE202, DE210, DE422 network card device driver. On
780: @samp{ix86-at} enabled by @samp{default}.
1.1 root 781:
782: @item --enable-ewrk3
1.1.1.2 root 783: EtherWORKS 3 (DE203, DE204, DE205) network card device driver. On
784: @samp{ix86-at} enabled by @samp{default}.
1.1 root 785:
786: @item --enable-de4x5
1.1.1.2 root 787: DE425, DE434, DE435, DE450, DE500 network card device driver. On
788: @samp{ix86-at} enabled by @samp{default}.
1.1 root 789:
790: @item --enable-apricot
1.1.1.2 root 791: Apricot XEN-II on board ethernet network card device driver. On @samp{ix86-at}
792: enabled by @samp{default}.
1.1 root 793:
794: @item --enable-wavelan
1.1.1.2 root 795: AT&T WaveLAN & DEC RoamAbout DS network card device driver.
1.1 root 796:
797: @item --enable-3c507
1.1.1.2 root 798: 3Com 507 network card device driver. On @samp{ix86-at} enabled by
799: @samp{default}.
1.1 root 800:
801: @item --enable-3c505
1.1.1.2 root 802: 3Com 505/Etherlink II network card device driver. On @samp{ix86-at} enabled by
803: @samp{default}.
1.1 root 804:
805: @item --enable-de600
1.1.1.2 root 806: D-Link DE-600 network card device driver. On @samp{ix86-at} enabled by
807: @samp{default}.
1.1 root 808:
809: @item --enable-de620
1.1.1.2 root 810: D-Link DE-620 network card device driver. On @samp{ix86-at} enabled by
811: @samp{default}.
1.1 root 812:
1.1.1.2 root 813: @item --enable-sk_g16
814: Schneider & Koch G16 network card device driver. On @samp{ix86-at} enabled by
815: @samp{default}.
1.1 root 816:
817: @item --enable-ni52
1.1.1.2 root 818: NI5210 network card device driver. On @samp{ix86-at} enabled by
819: @samp{default}.
1.1 root 820:
821: @item --enable-ni65
1.1.1.2 root 822: NI6510 network card device driver. On @samp{ix86-at} enabled by
823: @samp{default}.
1.1 root 824:
825: @item --enable-atp
1.1.1.2 root 826: AT-LAN-TEC/RealTek pocket adaptor network card device driver for the
827: @samp{atp%d} devices.
1.1 root 828:
829: @item --enable-lance
1.1.1.2 root 830: AMD LANCE and PCnet (AT1500 and NE2100) network card device driver. On
831: @samp{ix86-at} enabled by @samp{default}.
832:
833: @item --enable-tulip
834: DECchip Tulip (dc21x4x) PCI network card device driver. On @samp{ix86-at}
835: enabled by @samp{default}.
1.1 root 836:
837: @item --enable-fmv18x
1.1.1.2 root 838: FMV-181/182/183/184 network card device driver. On @samp{ix86-at} enabled by
839: @samp{default}.
1.1 root 840:
841: @item --enable-3c515
1.1.1.2 root 842: 3Com 515 ISA Fast EtherLink network card device driver. On @samp{ix86-at}
843: enabled by @samp{default}.
1.1 root 844:
845: @item --enable-pcnet32
1.1.1.2 root 846: AMD PCI PCnet32 (PCI bus NE2100 cards) network card device driver. On
847: @samp{ix86-at} enabled by @samp{default}.
1.1 root 848:
1.1.1.2 root 849: @item --enable-ne2k-pci
850: PCI NE2000 network card device driver. On @samp{ix86-at} enabled by
851: @samp{default}.
1.1 root 852:
853: @item --enable-yellowfin
1.1.1.2 root 854: Packet Engines Yellowfin Gigabit-NIC network card device driver. On
855: @samp{ix86-at} enabled by @samp{default}.
1.1 root 856:
857: @item --enable-rtl8139
1.1.1.2 root 858: RealTek 8129/8139 (not 8019/8029!) network card device driver. On
859: @samp{ix86-at} enabled by @samp{default}.
860:
861: @item --enable-epic100
862: SMC 83c170/175 EPIC/100 (EtherPower II) network card device driver. On
863: @samp{ix86-at} enabled by @samp{default}.
1.1 root 864:
865: @item --enable-tlan
1.1.1.2 root 866: TI ThunderLAN network card device driver. On @samp{ix86-at} enabled by
867: @samp{default}.
868:
869: @item --enable-via-rhine
870: VIA Rhine network card device driver. On @samp{ix86-at} enabled by
871: @samp{default}.
872:
873: @item --enable-hamachi
874: Packet Engines "Hamachi" GNIC-2 Gigabit Ethernet device driver. On
875: @samp{ix86-at} enabled by @samp{default}.
876:
877: @item --enable-intel-gige
878: Intel PCI Gigabit Ethernet device driver. On @samp{ix86-at} enabled by
879: @samp{default}.
880:
881: @item --enable-myson803
882: Myson MTD803 Ethernet adapter series device driver. On @samp{ix86-at} enabled
883: by @samp{default}.
884:
885: @item --enable-natsemi
886: National Semiconductor DP8381x series PCI Ethernet device driver. On
887: @samp{ix86-at} enabled by @samp{default}.
1.1 root 888:
1.1.1.2 root 889: @item --enable-ns820
890: National Semiconductor DP8382x series PCI Ethernet device driver. On
891: @samp{ix86-at} enabled by @samp{default}.
892:
893: @item --enable-starfire
894: Adaptec Starfire network adapter device driver. On @samp{ix86-at} enabled by
895: @samp{default}.
896:
897: @item --enable-sundance
898: Sundance ST201 "Alta" PCI Ethernet device driver. On @samp{ix86-at} enabled by
899: @samp{default}.
900:
901: @item --enable-winbond-840
902: Winbond W89c840 PCI Ethernet device driver. On @samp{ix86-at} enabled by
903: @samp{default}.
904: @end table
905:
906: The following options either control device drivers for supported PCMCIA
907: bridges or control the overall behaviour of the GNU Mach PCMCIA core. To make
908: use of GNU Mach PCMCIA support you need to have the corresponding userland
909: applications (GNU Mach Card Services) installed.
910:
911: @table @code
912: @item --enable-i82365
913: Device driver for the Intel 82365 and compatible PC Card controllers, and
914: Yenta-compatible PCI-to-CardBus controllers. On @samp{ix86-at} enabled by
915: @samp{default}.
916:
917: @item --enable-pcmcia-isa
918: ISA bus related bits in the GNU Mach PCMCIA core. Keeping it enabled is
919: generally a good idea, since it does not only have effect if your PC Card
920: bridge is attached to the ISA bus, but provides more (ISA) interrupts to the
921: Card Services for it to assign to the cards in turn. On @samp{ix86-at} enabled
922: by @samp{default}.
923: @end table
924:
925: The following options control device drivers for supported PCMCIA Ethernet
926: controllers. NIC devices are usually named @samp{eth%d}.
927:
928: @table @code
929: @item --enable-3c574_cs
930: PCMCIA ethernet driver for the 3Com 3c574 ``RoadRunner''. On @samp{ix86-at}
931: enabled by @samp{default}.
932:
933: @item --enable-3c589_cs
934: Driver for the 3Com 3c589 PCMCIA card. On @samp{ix86-at} enabled by
935: @samp{default}.
936:
937: @item --enable-axnet_cs
938: Driver for the Asix AX88190-based PCMCIA cards. On @samp{ix86-at} enabled by
939: @samp{default}.
940:
941: @item --enable-fmvj18x_cs
942: Driver for PCMCIA cards with the fmvj18x chipset. On @samp{ix86-at} enabled by
943: @samp{default}.
944:
945: @item --enable-nmclan_cs
946: Driver for the New Media Ethernet LAN PCMCIA cards. On @samp{ix86-at} enabled
947: by @samp{default}.
948:
949: @item --enable-pcnet_cs
950: Driver for NS8390-based PCMCIA cards. This driver supports the D-Link DE-650
951: and Linksys EthernetCard cards, the newer D-Link and Linksys combo cards,
952: Accton EN2212 cards, the RPTI EP400, and the PreMax PE-200 in non-shared-memory
953: mode, and the IBM Credit Card Adapter, the NE4100, the Thomas Conrad ethernet
954: card, and the Kingston KNE-PCM/x in shared-memory mode. It will also handle
955: the Socket EA card in either mode. On @samp{ix86-at} enabled by
956: @samp{default}.
957:
958: @item --enable-smc91c92_cs
959: Driver for SMC91c92-based PCMCIA cards. On @samp{ix86-at} enabled by
960: @samp{default}.
961:
962: @item --enable-xirc2ps_cs
963: Driver for Xircom CreditCard and Realport PCMCIA ethernet adapters. On
964: @samp{ix86-at} enabled by @samp{default}.
965: @end table
966:
967: The following options control device drivers for supported PCMCIA Wireless LAN
968: network controllers. NIC devices are usually named @samp{eth%d}.
969:
970: Please mind, that you need to have some userland applications (the GNU Mach
971: Wireless Tools) installed, in order to make use of these devices.
972:
973: @table @code
974: @item --enable-orinoco_cs
975: Driver for the Hermes or Prism 2 chipset based PCMCIA wireless adapters, with
976: Lucent/Agere, Intersil or Symbol firmware. This driver is suitable for PCMCIA
977: wireless adapters, such as the Lucent WavelanIEEE/Orinoco cards and their OEM
978: (Cabletron/EnteraSys RoamAbout 802.11, ELSA Airlancer, Melco Buffalo and
979: others). It should also be usable on various Prism II based cards such as the
980: Linksys, D-Link and Farallon Skyline. It should also work on Symbol cards such
981: as the 3Com AirConnect and Ericsson WLAN. On @samp{ix86-at} enabled by
982: @samp{default}.
1.1 root 983: @end table
984:
985:
986: @node Cross-Compilation
987: @section Cross-Compilation
988:
989: Another way to install the kernel is to use an existing operating system
990: in order to compile the kernel binary.
991: This is called @dfn{cross-compiling}, because it is done between two
992: different platforms. If the pre-built kernels are not working for
993: you, and you can't ask someone to compile a custom kernel for your
994: machine, this is your last chance to get a kernel that boots on your
995: hardware.
996:
997: Luckily, the kernel does have light dependencies. You don't even
998: need a cross compiler if your build machine has a compiler and is
999: the same architecture as the system you want to run GNU Mach on.
1000:
1001: You need a cross-mig, though.
1002:
1003: XXX More info needed.
1004:
1005:
1006: @node Bootstrap
1007: @chapter Bootstrap
1008:
1009: Bootstrapping@footnote{The term @dfn{bootstrapping} refers to a Dutch
1010: legend about a boy who was able to fly by pulling himself up by his
1011: bootstraps. In computers, this term refers to any process where a
1012: simple system activates a more complicated system.} is the procedure by
1013: which your machine loads the microkernel and transfers control to the
1014: operating system.
1015:
1016:
1017: @menu
1018: * Bootloader:: Starting the microkernel, or other OSes.
1019: * Modules:: Starting the first task of the OS.
1020: @end menu
1021:
1022: @node Bootloader
1023: @section Bootloader
1024:
1025: The @dfn{bootloader} is the first software that runs on your machine.
1026: Many hardware architectures have a very simple startup routine which
1027: reads a very simple bootloader from the beginning of the internal hard
1028: disk, then transfers control to it. Other architectures have startup
1029: routines which are able to understand more of the contents of the hard
1030: disk, and directly start a more advanced bootloader.
1031:
1032: @cindex GRUB
1033: @cindex GRand Unified Bootloader
1.1.1.2 root 1034: @dfn{GRUB}@footnote{The GRand Unified Bootloader, available
1035: from @uref{http://gnu.org/software/grub/}.} is the GNU bootloader.
1.1 root 1036: GRUB provides advanced functionality, and is capable of loading several
1037: different kernels (such as Mach, Linux, DOS, and the *BSD family).
1038: @xref{Top, , Introduction, grub, GRUB Manual}.
1039:
1040: GNU Mach conforms to the Multiboot specification which defines an
1041: interface between the bootloader and the components that run very early
1042: at startup. GNU Mach can be started by any bootloader which supports
1043: the multiboot standard. After the bootloader loaded the kernel image to
1044: a designated address in the system memory, it jumps into the startup
1045: code of the kernel. This code initializes the kernel and detects the
1046: available hardware devices. Afterwards, the first system task is
1047: started. @xref{Top, , Overview, multiboot, Multiboot Specification}.
1048:
1049:
1050: @node Modules
1051: @section Modules
1052: @pindex serverboot
1053:
1.1.1.2 root 1054: This is outdated.
1055:
1.1 root 1056: Because the microkernel does not provide filesystem support and other
1057: features necessary to load the first system task from a storage medium,
1058: the first task is loaded by the bootloader as a module to a specified
1059: address. In the GNU system, this first program is the @code{serverboot}
1060: executable. GNU Mach inserts the host control port and the device
1061: master port into this task and appends the port numbers to the command
1062: line before executing it.
1063:
1064: The @code{serverboot} program is responsible for loading and executing
1065: the rest of the Hurd servers. Rather than containing specific
1066: instructions for starting the Hurd, it follows general steps given in a
1067: user-supplied boot script.
1068:
1069: XXX More about boot scripts.
1070:
1071:
1072: @node Inter Process Communication
1073: @chapter Inter Process Communication
1074:
1075: This chapter describes the details of the Mach IPC system. First the
1076: actual calls concerned with sending and receiving messages are
1077: discussed, then the details of the port system are described in detail.
1078:
1079: @menu
1080: * Major Concepts:: The concepts behind the Mach IPC system.
1081: * Messaging Interface:: Composing, sending and receiving messages.
1082: * Port Manipulation Interface:: Manipulating ports, port rights, port sets.
1083: @end menu
1084:
1085:
1086: @node Major Concepts
1087: @section Major Concepts
1088: @cindex interprocess communication (IPC)
1089: @cindex IPC (interprocess communication)
1090: @cindex communication between tasks
1091: @cindex remote procedure calls (RPC)
1092: @cindex RPC (remote procedure calls)
1093: @cindex messages
1094:
1095: The Mach kernel provides message-oriented, capability-based interprocess
1096: communication. The interprocess communication (IPC) primitives
1097: efficiently support many different styles of interaction, including
1098: remote procedure calls (RPC), object-oriented distributed programming,
1099: streaming of data, and sending very large amounts of data.
1100:
1101: The IPC primitives operate on three abstractions: messages, ports, and
1102: port sets. User tasks access all other kernel services and abstractions
1103: via the IPC primitives.
1104:
1105: The message primitives let tasks send and receive messages. Tasks send
1106: messages to ports. Messages sent to a port are delivered reliably
1107: (messages may not be lost) and are received in the order in which they
1108: were sent. Messages contain a fixed-size header and a variable amount
1109: of typed data following the header. The header describes the
1110: destination and size of the message.
1111:
1112: The IPC implementation makes use of the VM system to efficiently
1113: transfer large amounts of data. The message body can contain the
1114: address of a region in the sender's address space which should be
1115: transferred as part of the message. When a task receives a message
1116: containing an out-of-line region of data, the data appears in an unused
1117: portion of the receiver's address space. This transmission of
1118: out-of-line data is optimized so that sender and receiver share the
1119: physical pages of data copy-on-write, and no actual data copy occurs
1120: unless the pages are written. Regions of memory up to the size of a
1121: full address space may be sent in this manner.
1122:
1123: Ports hold a queue of messages. Tasks operate on a port to send and
1124: receive messages by exercising capabilities for the port. Multiple
1125: tasks can hold send capabilities, or rights, for a port. Tasks can also
1126: hold send-once rights, which grant the ability to send a single message.
1127: Only one task can hold the receive capability, or receive right, for a
1128: port. Port rights can be transferred between tasks via messages. The
1129: sender of a message can specify in the message body that the message
1130: contains a port right. If a message contains a receive right for a
1131: port, then the receive right is removed from the sender of the message
1132: and the right is transferred to the receiver of the message. While the
1133: receive right is in transit, tasks holding send rights can still send
1134: messages to the port, and they are queued until a task acquires the
1135: receive right and uses it to receive the messages.
1136:
1137: Tasks can receive messages from ports and port sets. The port set
1138: abstraction allows a single thread to wait for a message from any of
1139: several ports. Tasks manipulate port sets with a capability, or
1140: port-set right, which is taken from the same space as the port
1141: capabilities. The port-set right may not be transferred in a message.
1142: A port set holds receive rights, and a receive operation on a port set
1143: blocks waiting for a message sent to any of the constituent ports. A
1144: port may not belong to more than one port set, and if a port is a member
1145: of a port set, the holder of the receive right can't receive directly
1146: from the port.
1147:
1148: Port rights are a secure, location-independent way of naming ports. The
1149: port queue is a protected data structure, only accessible via the
1150: kernel's exported message primitives. Rights are also protected by the
1151: kernel; there is no way for a malicious user task to guess a port name
1152: and send a message to a port to which it shouldn't have access. Port
1153: rights do not carry any location information. When a receive right for
1154: a port moves from task to task, and even between tasks on different
1155: machines, the send rights for the port remain unchanged and continue to
1156: function.
1157:
1158: @node Messaging Interface
1159: @section Messaging Interface
1160:
1161: This section describes how messages are composed, sent and received
1162: within the Mach IPC system.
1163:
1164: @menu
1165: * Mach Message Call:: Sending and receiving messages.
1166: * Message Format:: The format of Mach messages.
1167: * Exchanging Port Rights:: Sending and receiving port rights.
1168: * Memory:: Passing memory regions in messages.
1169: * Message Send:: Sending messages.
1170: * Message Receive:: Receiving messages.
1171: * Atomicity:: Atomicity of port rights.
1172: @end menu
1173:
1174:
1175: @node Mach Message Call
1176: @subsection Mach Message Call
1177:
1178: To use the @code{mach_msg} call, you can include the header files
1179: @file{mach/port.h} and @file{mach/message.h}.
1180:
1181: @deftypefun mach_msg_return_t mach_msg (@w{mach_msg_header_t *@var{msg}}, @w{mach_msg_option_t @var{option}}, @w{mach_msg_size_t @var{send_size}}, @w{mach_msg_size_t @var{rcv_size}}, @w{mach_port_t @var{rcv_name}}, @w{mach_msg_timeout_t @var{timeout}}, @w{mach_port_t @var{notify}})
1182: The @code{mach_msg} function is used to send and receive messages. Mach
1183: messages contain typed data, which can include port rights and
1184: references to large regions of memory.
1185:
1186: @var{msg} is the address of a buffer in the caller's address space.
1187: Message buffers should be aligned on long-word boundaries. The message
1188: options @var{option} are bit values, combined with bitwise-or. One or
1189: both of @code{MACH_SEND_MSG} and @code{MACH_RCV_MSG} should be used.
1190: Other options act as modifiers. When sending a message, @var{send_size}
1191: specifies the size of the message buffer. Otherwise zero should be
1192: supplied. When receiving a message, @var{rcv_size} specifies the size
1193: of the message buffer. Otherwise zero should be supplied. When
1194: receiving a message, @var{rcv_name} specifies the port or port set.
1195: Otherwise @code{MACH_PORT_NULL} should be supplied. When using the
1196: @code{MACH_SEND_TIMEOUT} and @code{MACH_RCV_TIMEOUT} options,
1197: @var{timeout} specifies the time in milliseconds to wait before giving
1198: up. Otherwise @code{MACH_MSG_TIMEOUT_NONE} should be supplied. When
1199: using the @code{MACH_SEND_NOTIFY}, @code{MACH_SEND_CANCEL}, and
1200: @code{MACH_RCV_NOTIFY} options, @var{notify} specifies the port used for
1201: the notification. Otherwise @code{MACH_PORT_NULL} should be supplied.
1202:
1203: If the option argument is @code{MACH_SEND_MSG}, it sends a message. The
1204: @var{send_size} argument specifies the size of the message to send. The
1205: @code{msgh_remote_port} field of the message header specifies the
1206: destination of the message.
1207:
1208: If the option argument is @code{MACH_RCV_MSG}, it receives a message.
1209: The @var{rcv_size} argument specifies the size of the message buffer
1210: that will receive the message; messages larger than @var{rcv_size} are
1211: not received. The @var{rcv_name} argument specifies the port or port
1212: set from which to receive.
1213:
1214: If the option argument is @code{MACH_SEND_MSG|MACH_RCV_MSG}, then
1215: @code{mach_msg} does both send and receive operations. If the send
1216: operation encounters an error (any return code other than
1217: @code{MACH_MSG_SUCCESS}), then the call returns immediately without
1218: attempting the receive operation. Semantically the combined call is
1219: equivalent to separate send and receive calls, but it saves a system
1220: call and enables other internal optimizations.
1221:
1222: If the option argument specifies neither @code{MACH_SEND_MSG} nor
1223: @code{MACH_RCV_MSG}, then @code{mach_msg} does nothing.
1224:
1225: Some options, like @code{MACH_SEND_TIMEOUT} and @code{MACH_RCV_TIMEOUT},
1226: share a supporting argument. If these options are used together, they
1227: make independent use of the supporting argument's value.
1228: @end deftypefun
1229:
1230: @deftp {Data type} mach_msg_timeout_t
1231: This is a @code{natural_t} used by the timeout mechanism. The units are
1232: milliseconds. The value to be used when there is no timeout is
1233: @code{MACH_MSG_TIMEOUT_NONE}.
1234: @end deftp
1235:
1236:
1237: @node Message Format
1238: @subsection Message Format
1239: @cindex message format
1240: @cindex format of a message
1241: @cindex composing messages
1242: @cindex message composition
1243:
1244: A Mach message consists of a fixed size message header, a
1245: @code{mach_msg_header_t}, followed by zero or more data items. Data
1246: items are typed. Each item has a type descriptor followed by the actual
1247: data (or the address of the data, for out-of-line memory regions).
1248:
1249: The following data types are related to Mach ports:
1250:
1251: @deftp {Data type} mach_port_t
1252: The @code{mach_port_t} data type is an unsigned integer type which
1253: represents a port name in the task's port name space. In GNU Mach, this
1254: is an @code{unsigned int}.
1255: @end deftp
1256:
1257: @c This is defined elsewhere.
1258: @c @deftp {Data type} mach_port_seqno_t
1259: @c The @code{mach_port_seqno_t} data type is an unsigned integer type which
1260: @c represents a sequence number of a message. In GNU Mach, this is an
1261: @c @code{unsigned int}.
1262: @c @end deftp
1263:
1264: The following data types are related to Mach messages:
1265:
1266: @deftp {Data type} mach_msg_bits_t
1267: The @code{mach_msg_bits_t} data type is an @code{unsigned int} used to
1268: store various flags for a message.
1269: @end deftp
1270:
1271: @deftp {Data type} mach_msg_size_t
1272: The @code{mach_msg_size_t} data type is an @code{unsigned int} used to
1273: store the size of a message.
1274: @end deftp
1275:
1276: @deftp {Data type} mach_msg_id_t
1277: The @code{mach_msg_id_t} data type is an @code{integer_t} typically used to
1278: convey a function or operation id for the receiver.
1279: @end deftp
1280:
1281: @deftp {Data type} mach_msg_header_t
1282: This structure is the start of every message in the Mach IPC system. It
1283: has the following members:
1284:
1285: @table @code
1286: @item mach_msg_bits_t msgh_bits
1287: The @code{msgh_bits} field has the following bits defined, all other
1288: bits should be zero:
1289:
1290: @table @code
1291: @item MACH_MSGH_BITS_REMOTE_MASK
1292: @itemx MACH_MSGH_BITS_LOCAL_MASK
1293: The remote and local bits encode @code{mach_msg_type_name_t} values that
1294: specify the port rights in the @code{msgh_remote_port} and
1295: @code{msgh_local_port} fields. The remote value must specify a send or
1296: send-once right for the destination of the message. If the local value
1297: doesn't specify a send or send-once right for the message's reply port,
1298: it must be zero and msgh_local_port must be @code{MACH_PORT_NULL}.
1299:
1300: @item MACH_MSGH_BITS_COMPLEX
1301: The complex bit must be specified if the message body contains port
1302: rights or out-of-line memory regions. If it is not specified, then the
1303: message body carries no port rights or memory, no matter what the type
1304: descriptors may seem to indicate.
1305: @end table
1306:
1307: @code{MACH_MSGH_BITS_REMOTE} and @code{MACH_MSGH_BITS_LOCAL} macros
1308: return the appropriate @code{mach_msg_type_name_t} values, given a
1309: @code{msgh_bits} value. The @code{MACH_MSGH_BITS} macro constructs a
1310: value for @code{msgh_bits}, given two @code{mach_msg_type_name_t}
1311: values.
1312:
1313: @item mach_msg_size_t msgh_size
1314: The @code{msgh_size} field in the header of a received message contains
1315: the message's size. The message size, a byte quantity, includes the
1316: message header, type descriptors, and in-line data. For out-of-line
1317: memory regions, the message size includes the size of the in-line
1318: address, not the size of the actual memory region. There are no
1319: arbitrary limits on the size of a Mach message, the number of data items
1320: in a message, or the size of the data items.
1321:
1322: @item mach_port_t msgh_remote_port
1323: The @code{msgh_remote_port} field specifies the destination port of the
1324: message. The field must carry a legitimate send or send-once right for
1325: a port.
1326:
1327: @item mach_port_t msgh_local_port
1328: The @code{msgh_local_port} field specifies an auxiliary port right,
1329: which is conventionally used as a reply port by the recipient of the
1330: message. The field must carry a send right, a send-once right,
1331: @code{MACH_PORT_NULL}, or @code{MACH_PORT_DEAD}.
1332:
1.1.1.3 ! root 1333: @item unsigned long msgh_protected_payload
! 1334: The @code{msgh_protected_payload} field carries a payload that is set
! 1335: by the kernel during message delivery. The payload is an opaque
! 1336: identifier that can be used by the receiver to lookup the associated
! 1337: data structure.
! 1338:
! 1339: It is only valid in received messages. See @ref{Message Receive} for
! 1340: further information.
! 1341:
1.1 root 1342: @item mach_port_seqno_t msgh_seqno
1343: The @code{msgh_seqno} field provides a sequence number for the message.
1344: It is only valid in received messages; its value in sent messages is
1345: overwritten.
1346: @c XXX The "MESSAGE RECEIVE" section discusses message sequence numbers.
1347:
1348: @item mach_msg_id_t msgh_id
1349: The @code{mach_msg} call doesn't use the @code{msgh_id} field, but it
1350: conventionally conveys an operation or function id.
1351: @end table
1352: @end deftp
1353:
1354: @deftypefn Macro mach_msg_bits_t MACH_MSGH_BITS (@w{mach_msg_type_name_t @var{remote}}, @w{mach_msg_type_name_t @var{local}})
1355: This macro composes two @code{mach_msg_type_name_t} values that specify
1356: the port rights in the @code{msgh_remote_port} and
1357: @code{msgh_local_port} fields of a @code{mach_msg} call into an
1358: appropriate @code{mach_msg_bits_t} value.
1359: @end deftypefn
1360:
1361: @deftypefn Macro mach_msg_type_name_t MACH_MSGH_BITS_REMOTE (@w{mach_msg_bits_t @var{bits}})
1362: This macro extracts the @code{mach_msg_type_name_t} value for the remote
1363: port right in a @code{mach_msg_bits_t} value.
1364: @end deftypefn
1365:
1366: @deftypefn Macro mach_msg_type_name_t MACH_MSGH_BITS_LOCAL (@w{mach_msg_bits_t @var{bits}})
1367: This macro extracts the @code{mach_msg_type_name_t} value for the local
1368: port right in a @code{mach_msg_bits_t} value.
1369: @end deftypefn
1370:
1371: @deftypefn Macro mach_msg_bits_t MACH_MSGH_BITS_PORTS (@w{mach_msg_bits_t @var{bits}})
1372: This macro extracts the @code{mach_msg_bits_t} component consisting of
1373: the @code{mach_msg_type_name_t} values for the remote and local port
1374: right in a @code{mach_msg_bits_t} value.
1375: @end deftypefn
1376:
1377: @deftypefn Macro mach_msg_bits_t MACH_MSGH_BITS_OTHER (@w{mach_msg_bits_t @var{bits}})
1378: This macro extracts the @code{mach_msg_bits_t} component consisting of
1379: everything except the @code{mach_msg_type_name_t} values for the remote
1380: and local port right in a @code{mach_msg_bits_t} value.
1381: @end deftypefn
1382:
1383: Each data item has a type descriptor, a @code{mach_msg_type_t} or a
1384: @code{mach_msg_type_long_t}. The @code{mach_msg_type_long_t} type
1385: descriptor allows larger values for some fields. The
1386: @code{msgtl_header} field in the long descriptor is only used for its
1387: inline, longform, and deallocate bits.
1388:
1389: @deftp {Data type} mach_msg_type_name_t
1390: This is an @code{unsigned int} and can be used to hold the
1391: @code{msgt_name} component of the @code{mach_msg_type_t} and
1392: @code{mach_msg_type_long_t} structure.
1393: @end deftp
1394:
1395: @deftp {Data type} mach_msg_type_size_t
1396: This is an @code{unsigned int} and can be used to hold the
1397: @code{msgt_size} component of the @code{mach_msg_type_t} and
1398: @code{mach_msg_type_long_t} structure.
1399: @end deftp
1400:
1401: @deftp {Data type} mach_msg_type_number_t
1402: This is an @code{natural_t} and can be used to hold the
1403: @code{msgt_number} component of the @code{mach_msg_type_t} and
1404: @code{mach_msg_type_long_t} structure.
1405: @c XXX This is used for the size of arrays, too. Mmh?
1406: @end deftp
1407:
1408: @deftp {Data type} mach_msg_type_t
1409: This structure has the following members:
1410:
1411: @table @code
1412: @item unsigned int msgt_name : 8
1413: The @code{msgt_name} field specifies the data's type. The following
1414: types are predefined:
1415:
1416: @table @code
1417: @item MACH_MSG_TYPE_UNSTRUCTURED
1418: @item MACH_MSG_TYPE_BIT
1419: @item MACH_MSG_TYPE_BOOLEAN
1420: @item MACH_MSG_TYPE_INTEGER_16
1421: @item MACH_MSG_TYPE_INTEGER_32
1422: @item MACH_MSG_TYPE_CHAR
1423: @item MACH_MSG_TYPE_BYTE
1424: @item MACH_MSG_TYPE_INTEGER_8
1425: @item MACH_MSG_TYPE_REAL
1426: @item MACH_MSG_TYPE_STRING
1427: @item MACH_MSG_TYPE_STRING_C
1428: @item MACH_MSG_TYPE_PORT_NAME
1.1.1.3 ! root 1429: @item MACH_MSG_TYPE_PROTECTED_PAYLOAD
1.1 root 1430: @end table
1431:
1432: The following predefined types specify port rights, and receive special
1433: treatment. The next section discusses these types in detail. The type
1434: @c XXX cross ref
1435: @code{MACH_MSG_TYPE_PORT_NAME} describes port right names, when no
1436: rights are being transferred, but just names. For this purpose, it
1437: should be used in preference to @code{MACH_MSG_TYPE_INTEGER_32}.
1438:
1439: @table @code
1440: @item MACH_MSG_TYPE_MOVE_RECEIVE
1441: @item MACH_MSG_TYPE_MOVE_SEND
1442: @item MACH_MSG_TYPE_MOVE_SEND_ONCE
1443: @item MACH_MSG_TYPE_COPY_SEND
1444: @item MACH_MSG_TYPE_MAKE_SEND
1445: @item MACH_MSG_TYPE_MAKE_SEND_ONCE
1446: @end table
1447:
1.1.1.3 ! root 1448: The type @code{MACH_MSG_TYPE_PROTECTED_PAYLOAD} is used by the kernel
! 1449: to indicate that a delivered message carries a payload in the
! 1450: @code{msgh_protected_payload} field. See @ref{Message Receive} for
! 1451: more information.
! 1452:
1.1 root 1453: @item msgt_size : 8
1454: The @code{msgt_size} field specifies the size of each datum, in bits. For
1455: example, the msgt_size of @code{MACH_MSG_TYPE_INTEGER_32} data is 32.
1456:
1457: @item msgt_number : 12
1458: The @code{msgt_number} field specifies how many data elements comprise
1459: the data item. Zero is a legitimate number.
1460:
1461: The total length specified by a type descriptor is @w{@code{(msgt_size *
1462: msgt_number)}}, rounded up to an integral number of bytes. In-line data
1463: is then padded to an integral number of long-words. This ensures that
1464: type descriptors always start on long-word boundaries. It implies that
1465: message sizes are always an integral multiple of a long-word's size.
1466:
1467: @item msgt_inline : 1
1468: The @code{msgt_inline} bit specifies, when @code{FALSE}, that the data
1469: actually resides in an out-of-line region. The address of the memory
1470: region (a @code{vm_offset_t} or @code{vm_address_t}) follows the type
1471: descriptor in the message body. The @code{msgt_name}, @code{msgt_size},
1472: and @code{msgt_number} fields describe the memory region, not the
1473: address.
1474:
1475: @item msgt_longform : 1
1476: The @code{msgt_longform} bit specifies, when @code{TRUE}, that this type
1477: descriptor is a @code{mach_msg_type_long_t} instead of a
1478: @code{mach_msg_type_t}. The @code{msgt_name}, @code{msgt_size}, and
1479: @code{msgt_number} fields should be zero. Instead, @code{mach_msg} uses
1480: the following @code{msgtl_name}, @code{msgtl_size}, and
1481: @code{msgtl_number} fields.
1482:
1483: @item msgt_deallocate : 1
1484: The @code{msgt_deallocate} bit is used with out-of-line regions. When
1485: @code{TRUE}, it specifies that the memory region should be deallocated
1486: from the sender's address space (as if with @code{vm_deallocate}) when
1487: the message is sent.
1488:
1489: @item msgt_unused : 1
1490: The @code{msgt_unused} bit should be zero.
1491: @end table
1492: @end deftp
1493:
1494: @deftypefn Macro boolean_t MACH_MSG_TYPE_PORT_ANY (mach_msg_type_name_t type)
1495: This macro returns @code{TRUE} if the given type name specifies a port
1496: type, otherwise it returns @code{FALSE}.
1497: @end deftypefn
1498:
1499: @deftypefn Macro boolean_t MACH_MSG_TYPE_PORT_ANY_SEND (mach_msg_type_name_t type)
1500: This macro returns @code{TRUE} if the given type name specifies a port
1501: type with a send or send-once right, otherwise it returns @code{FALSE}.
1502: @end deftypefn
1503:
1504: @deftypefn Macro boolean_t MACH_MSG_TYPE_PORT_ANY_RIGHT (mach_msg_type_name_t type)
1505: This macro returns @code{TRUE} if the given type name specifies a port
1506: right type which is moved, otherwise it returns @code{FALSE}.
1507: @end deftypefn
1508:
1509: @deftp {Data type} mach_msg_type_long_t
1510: This structure has the following members:
1511:
1512: @table @code
1513: @item mach_msg_type_t msgtl_header
1514: Same meaning as @code{msgt_header}.
1515: @c XXX cross ref
1516:
1517: @item unsigned short msgtl_name
1518: Same meaning as @code{msgt_name}.
1519:
1520: @item unsigned short msgtl_size
1521: Same meaning as @code{msgt_size}.
1522:
1523: @item unsigned int msgtl_number
1524: Same meaning as @code{msgt_number}.
1525: @end table
1526: @end deftp
1527:
1528:
1529: @node Exchanging Port Rights
1530: @subsection Exchanging Port Rights
1531: @cindex sending port rights
1532: @cindex receiving port rights
1533: @cindex moving port rights
1534:
1535: Each task has its own space of port rights. Port rights are named with
1536: positive integers. Except for the reserved values
1537: @w{@code{MACH_PORT_NULL (0)}@footnote{In the Hurd system, we don't make
1538: the assumption that @code{MACH_PORT_NULL} is zero and evaluates to
1539: false, but rather compare port names to @code{MACH_PORT_NULL}
1.1.1.2 root 1540: explicitly}} and @w{@code{MACH_PORT_DEAD (~0)}}, this is a full 32-bit
1.1 root 1541: name space. When the kernel chooses a name for a new right, it is free
1542: to pick any unused name (one which denotes no right) in the space.
1543:
1544: There are five basic kinds of rights: receive rights, send rights,
1545: send-once rights, port-set rights, and dead names. Dead names are not
1546: capabilities. They act as place-holders to prevent a name from being
1547: otherwise used.
1548:
1549: A port is destroyed, or dies, when its receive right is deallocated.
1550: When a port dies, send and send-once rights for the port turn into dead
1551: names. Any messages queued at the port are destroyed, which deallocates
1552: the port rights and out-of-line memory in the messages.
1553:
1554: Tasks may hold multiple user-references for send rights and dead names.
1555: When a task receives a send right which it already holds, the kernel
1556: increments the right's user-reference count. When a task deallocates a
1557: send right, the kernel decrements its user-reference count, and the task
1558: only loses the send right when the count goes to zero.
1559:
1560: Send-once rights always have a user-reference count of one, although a
1561: port can have multiple send-once rights, because each send-once right
1562: held by a task has a different name. In contrast, when a task holds
1563: send rights or a receive right for a port, the rights share a single
1564: name.
1565:
1566: A message body can carry port rights; the @code{msgt_name}
1567: (@code{msgtl_name}) field in a type descriptor specifies the type of
1568: port right and how the port right is to be extracted from the caller.
1569: The values @code{MACH_PORT_NULL} and @code{MACH_PORT_DEAD} are always
1570: valid in place of a port right in a message body. In a sent message,
1571: the following @code{msgt_name} values denote port rights:
1572:
1573: @table @code
1574: @item MACH_MSG_TYPE_MAKE_SEND
1575: The message will carry a send right, but the caller must supply a
1576: receive right. The send right is created from the receive right, and
1577: the receive right's make-send count is incremented.
1578:
1579: @item MACH_MSG_TYPE_COPY_SEND
1580: The message will carry a send right, and the caller should supply a send
1581: right. The user reference count for the supplied send right is not
1582: changed. The caller may also supply a dead name and the receiving task
1583: will get @code{MACH_PORT_DEAD}.
1584:
1585: @item MACH_MSG_TYPE_MOVE_SEND
1586: The message will carry a send right, and the caller should supply a send
1587: right. The user reference count for the supplied send right is
1588: decremented, and the right is destroyed if the count becomes zero.
1589: Unless a receive right remains, the name becomes available for
1590: recycling. The caller may also supply a dead name, which loses a user
1591: reference, and the receiving task will get @code{MACH_PORT_DEAD}.
1592:
1593: @item MACH_MSG_TYPE_MAKE_SEND_ONCE
1594: The message will carry a send-once right, but the caller must supply a
1595: receive right. The send-once right is created from the receive right.
1596:
1597: @item MACH_MSG_TYPE_MOVE_SEND_ONCE
1598: The message will carry a send-once right, and the caller should supply a
1599: send-once right. The caller loses the supplied send-once right. The
1600: caller may also supply a dead name, which loses a user reference, and
1601: the receiving task will get @code{MACH_PORT_DEAD}.
1602:
1603: @item MACH_MSG_TYPE_MOVE_RECEIVE
1604: The message will carry a receive right, and the caller should supply a
1605: receive right. The caller loses the supplied receive right, but retains
1606: any send rights with the same name.
1607: @end table
1608:
1609: If a message carries a send or send-once right, and the port dies while
1610: the message is in transit, then the receiving task will get
1611: @code{MACH_PORT_DEAD} instead of a right. The following
1612: @code{msgt_name} values in a received message indicate that it carries
1613: port rights:
1614:
1615: @table @code
1616: @item MACH_MSG_TYPE_PORT_SEND
1617: This name is an alias for @code{MACH_MSG_TYPE_MOVE_SEND}. The message
1618: carried a send right. If the receiving task already has send and/or
1619: receive rights for the port, then that name for the port will be reused.
1620: Otherwise, the new right will have a new name. If the task already has
1621: send rights, it gains a user reference for the right (unless this would
1622: cause the user-reference count to overflow). Otherwise, it acquires the
1623: send right, with a user-reference count of one.
1624:
1625: @item MACH_MSG_TYPE_PORT_SEND_ONCE
1626: This name is an alias for @code{MACH_MSG_TYPE_MOVE_SEND_ONCE}. The
1627: message carried a send-once right. The right will have a new name.
1628:
1629: @item MACH_MSG_TYPE_PORT_RECEIVE
1630: This name is an alias for @code{MACH_MSG_TYPE_MOVE_RECEIVE}. The
1631: message carried a receive right. If the receiving task already has send
1632: rights for the port, then that name for the port will be reused.
1633: Otherwise, the right will have a new name. The make-send count of the
1634: receive right is reset to zero, but the port retains other attributes
1635: like queued messages, extant send and send-once rights, and requests for
1636: port-destroyed and no-senders notifications.
1637: @end table
1638:
1639: When the kernel chooses a new name for a port right, it can choose any
1640: name, other than @code{MACH_PORT_NULL} and @code{MACH_PORT_DEAD}, which
1641: is not currently being used for a port right or dead name. It might
1642: choose a name which at some previous time denoted a port right, but is
1643: currently unused.
1644:
1645:
1646: @node Memory
1647: @subsection Memory
1648: @cindex sending memory
1649: @cindex receiving memory
1650:
1651: A message body can contain the address of a region in the sender's
1652: address space which should be transferred as part of the message. The
1653: message carries a logical copy of the memory, but the kernel uses VM
1654: techniques to defer any actual page copies. Unless the sender or the
1655: receiver modifies the data, the physical pages remain shared.
1656:
1657: An out-of-line transfer occurs when the data's type descriptor specifies
1658: @code{msgt_inline} as @code{FALSE}. The address of the memory region (a
1659: @code{vm_offset_t} or @code{vm_address_t}) should follow the type
1660: descriptor in the message body. The type descriptor and the address
1661: contribute to the message's size (@code{send_size}, @code{msgh_size}).
1662: The out-of-line data does not contribute to the message's size.
1663:
1664: The name, size, and number fields in the type descriptor describe the
1665: type and length of the out-of-line data, not the in-line address.
1666: Out-of-line memory frequently requires long type descriptors
1667: (@code{mach_msg_type_long_t}), because the @code{msgt_number} field is
1668: too small to describe a page of 4K bytes.
1669:
1670: Out-of-line memory arrives somewhere in the receiver's address space as
1671: new memory. It has the same inheritance and protection attributes as
1672: newly @code{vm_allocate}'d memory. The receiver has the responsibility
1673: of deallocating (with @code{vm_deallocate}) the memory when it is no
1674: longer needed. Security-conscious receivers should exercise caution
1675: when using out-of-line memory from untrustworthy sources, because the
1676: memory may be backed by an unreliable memory manager.
1677:
1678: Null out-of-line memory is legal. If the out-of-line region size is
1679: zero (for example, because @code{msgtl_number} is zero), then the
1680: region's specified address is ignored. A received null out-of-line
1681: memory region always has a zero address.
1682:
1683: Unaligned addresses and region sizes that are not page multiples are
1684: legal. A received message can also contain memory with unaligned
1685: addresses and funny sizes. In the general case, the first and last
1686: pages in the new memory region in the receiver do not contain only data
1687: from the sender, but are partly zero.@footnote{Sending out-of-line
1688: memory with a non-page-aligned address, or a size which is not a page
1689: multiple, works but with a caveat. The extra bytes in the first and
1690: last page of the received memory are not zeroed, so the receiver can
1691: peek at more data than the sender intended to transfer. This might be a
1692: security problem for the sender.} The received address points to the
1693: start of the data in the first page. This possibility doesn't
1694: complicate deallocation, because @code{vm_deallocate} does the right
1695: thing, rounding the start address down and the end address up to
1696: deallocate all arrived pages.
1697:
1698: Out-of-line memory has a deallocate option, controlled by the
1699: @code{msgt_deallocate} bit. If it is @code{TRUE} and the out-of-line
1700: memory region is not null, then the region is implicitly deallocated
1701: from the sender, as if by @code{vm_deallocate}. In particular, the
1702: start and end addresses are rounded so that every page overlapped by the
1703: memory region is deallocated. The use of @code{msgt_deallocate}
1704: effectively changes the memory copy into a memory movement. In a
1705: received message, @code{msgt_deallocate} is @code{TRUE} in type
1706: descriptors for out-of-line memory.
1707:
1708: Out-of-line memory can carry port rights.
1709:
1710:
1711: @node Message Send
1712: @subsection Message Send
1713: @cindex sending messages
1714:
1715: The send operation queues a message to a port. The message carries a
1716: copy of the caller's data. After the send, the caller can freely modify
1717: the message buffer or the out-of-line memory regions and the message
1718: contents will remain unchanged.
1719:
1720: Message delivery is reliable and sequenced. Messages are not lost, and
1721: messages sent to a port, from a single thread, are received in the order
1722: in which they were sent.
1723:
1724: If the destination port's queue is full, then several things can happen.
1725: If the message is sent to a send-once right (@code{msgh_remote_port}
1726: carries a send-once right), then the kernel ignores the queue limit and
1727: delivers the message. Otherwise the caller blocks until there is room
1728: in the queue, unless the @code{MACH_SEND_TIMEOUT} or
1729: @code{MACH_SEND_NOTIFY} options are used. If a port has several blocked
1730: senders, then any of them may queue the next message when space in the
1731: queue becomes available, with the proviso that a blocked sender will not
1732: be indefinitely starved.
1733:
1734: These options modify @code{MACH_SEND_MSG}. If @code{MACH_SEND_MSG} is
1735: not also specified, they are ignored.
1736:
1737: @table @code
1738: @item MACH_SEND_TIMEOUT
1739: The timeout argument should specify a maximum time (in milliseconds) for
1740: the call to block before giving up.@footnote{If MACH_SEND_TIMEOUT is
1741: used without MACH_SEND_INTERRUPT, then the timeout duration might not be
1742: accurate. When the call is interrupted and automatically retried, the
1743: original timeout is used. If interrupts occur frequently enough, the
1744: timeout interval might never expire.} If the message can't be queued
1745: before the timeout interval elapses, then the call returns
1746: @code{MACH_SEND_TIMED_OUT}. A zero timeout is legitimate.
1747:
1748: @item MACH_SEND_NOTIFY
1749: The notify argument should specify a receive right for a notify port.
1750: If the send were to block, then instead the message is queued,
1751: @code{MACH_SEND_WILL_NOTIFY} is returned, and a msg-accepted
1752: notification is requested. If @code{MACH_SEND_TIMEOUT} is also
1753: specified, then @code{MACH_SEND_NOTIFY} doesn't take effect until the
1754: timeout interval elapses.
1755:
1756: With @code{MACH_SEND_NOTIFY}, a task can forcibly queue to a send right
1.1.1.2 root 1757: one message at a time. A msg-accepted notification is sent to the
1.1 root 1758: notify port when another message can be forcibly queued. If an attempt
1759: is made to use @code{MACH_SEND_NOTIFY} before then, the call returns a
1760: @code{MACH_SEND_NOTIFY_IN_PROGRESS} error.
1761:
1762: The msg-accepted notification carries the name of the send right. If
1763: the send right is deallocated before the msg-accepted notification is
1764: generated, then the msg-accepted notification carries the value
1765: @code{MACH_PORT_NULL}. If the destination port is destroyed before the
1766: notification is generated, then a send-once notification is generated
1767: instead.
1768:
1769: @item MACH_SEND_INTERRUPT
1770: If specified, the @code{mach_msg} call will return
1771: @code{MACH_SEND_INTERRUPTED} if a software interrupt aborts the call.
1772: Otherwise, the send operation will be retried.
1773:
1774: @item MACH_SEND_CANCEL
1775: The notify argument should specify a receive right for a notify port.
1776: If the send operation removes the destination port right from the
1777: caller, and the removed right had a dead-name request registered for it,
1778: and notify is the notify port for the dead-name request, then the
1779: dead-name request may be silently canceled (instead of resulting in a
1780: port-deleted notification).
1781:
1782: This option is typically used to cancel a dead-name request made with
1783: the @code{MACH_RCV_NOTIFY} option. It should only be used as an optimization.
1784: @end table
1785:
1786: The send operation can generate the following return codes. These
1787: return codes imply that the call did nothing:
1788:
1789: @table @code
1790: @item MACH_SEND_MSG_TOO_SMALL
1791: The specified send_size was smaller than the minimum size for a message.
1792:
1793: @item MACH_SEND_NO_BUFFER
1794: A resource shortage prevented the kernel from allocating a message
1795: buffer.
1796:
1797: @item MACH_SEND_INVALID_DATA
1798: The supplied message buffer was not readable.
1799:
1800: @item MACH_SEND_INVALID_HEADER
1801: The @code{msgh_bits} value was invalid.
1802:
1803: @item MACH_SEND_INVALID_DEST
1804: The @code{msgh_remote_port} value was invalid.
1805:
1806: @item MACH_SEND_INVALID_REPLY
1807: The @code{msgh_local_port} value was invalid.
1808:
1809: @item MACH_SEND_INVALID_NOTIFY
1810: When using @code{MACH_SEND_CANCEL}, the notify argument did not denote a
1811: valid receive right.
1812: @end table
1813:
1814: These return codes imply that some or all of the message was destroyed:
1815:
1816: @table @code
1817: @item MACH_SEND_INVALID_MEMORY
1818: The message body specified out-of-line data that was not readable.
1819:
1820: @item MACH_SEND_INVALID_RIGHT
1821: The message body specified a port right which the caller didn't possess.
1822:
1823: @item MACH_SEND_INVALID_TYPE
1824: A type descriptor was invalid.
1825:
1826: @item MACH_SEND_MSG_TOO_SMALL
1827: The last data item in the message ran over the end of the message.
1828: @end table
1829:
1830: These return codes imply that the message was returned to the caller
1831: with a pseudo-receive operation:
1832:
1833: @table @code
1834: @item MACH_SEND_TIMED_OUT
1835: The timeout interval expired.
1836:
1837: @item MACH_SEND_INTERRUPTED
1838: A software interrupt occurred.
1839:
1840: @item MACH_SEND_INVALID_NOTIFY
1841: When using @code{MACH_SEND_NOTIFY}, the notify argument did not denote a
1842: valid receive right.
1843:
1844: @item MACH_SEND_NO_NOTIFY
1845: A resource shortage prevented the kernel from setting up a msg-accepted
1846: notification.
1847:
1848: @item MACH_SEND_NOTIFY_IN_PROGRESS
1849: A msg-accepted notification was already requested, and hasn't yet been
1850: generated.
1851: @end table
1852:
1853: These return codes imply that the message was queued:
1854:
1855: @table @code
1856: @item MACH_SEND_WILL_NOTIFY
1857: The message was forcibly queued, and a msg-accepted notification was
1858: requested.
1859:
1860: @item MACH_MSG_SUCCESS
1861: The message was queued.
1862: @end table
1863:
1864: Some return codes, like @code{MACH_SEND_TIMED_OUT}, imply that the
1865: message was almost sent, but could not be queued. In these situations,
1866: the kernel tries to return the message contents to the caller with a
1867: pseudo-receive operation. This prevents the loss of port rights or
1868: memory which only exist in the message. For example, a receive right
1869: which was moved into the message, or out-of-line memory sent with the
1870: deallocate bit.
1871:
1872: The pseudo-receive operation is very similar to a normal receive
1873: operation. The pseudo-receive handles the port rights in the message
1874: header as if they were in the message body. They are not reversed.
1875: After the pseudo-receive, the message is ready to be resent. If the
1876: message is not resent, note that out-of-line memory regions may have
1877: moved and some port rights may have changed names.
1878:
1879: The pseudo-receive operation may encounter resource shortages. This is
1880: similar to a @code{MACH_RCV_BODY_ERROR} return code from a receive
1881: operation. When this happens, the normal send return codes are
1882: augmented with the @code{MACH_MSG_IPC_SPACE}, @code{MACH_MSG_VM_SPACE},
1883: @code{MACH_MSG_IPC_KERNEL}, and @code{MACH_MSG_VM_KERNEL} bits to
1884: indicate the nature of the resource shortage.
1885:
1886: The queueing of a message carrying receive rights may create a circular
1887: loop of receive rights and messages, which can never be received. For
1888: example, a message carrying a receive right can be sent to that receive
1889: right. This situation is not an error, but the kernel will
1890: garbage-collect such loops, destroying the messages and ports involved.
1891:
1892:
1893: @node Message Receive
1894: @subsection Message Receive
1895:
1896: The receive operation dequeues a message from a port. The receiving
1897: task acquires the port rights and out-of-line memory regions carried in
1898: the message.
1899:
1900: The @code{rcv_name} argument specifies a port or port set from which to
1901: receive. If a port is specified, the caller must possess the receive
1902: right for the port and the port must not be a member of a port set. If
1903: no message is present, then the call blocks, subject to the
1904: @code{MACH_RCV_TIMEOUT} option.
1905:
1906: If a port set is specified, the call will receive a message sent to any
1907: of the member ports. It is permissible for the port set to have no
1908: member ports, and ports may be added and removed while a receive from
1909: the port set is in progress. The received message can come from any of
1910: the member ports which have messages, with the proviso that a member
1911: port with messages will not be indefinitely starved. The
1912: @code{msgh_local_port} field in the received message header specifies
1913: from which port in the port set the message came.
1914:
1915: The @code{rcv_size} argument specifies the size of the caller's message
1916: buffer. The @code{mach_msg} call will not receive a message larger than
1917: @code{rcv_size}. Messages that are too large are destroyed, unless the
1918: @code{MACH_RCV_LARGE} option is used.
1919:
1920: The destination and reply ports are reversed in a received message
1921: header. The @code{msgh_local_port} field names the destination port,
1922: from which the message was received, and the @code{msgh_remote_port}
1923: field names the reply port right. The bits in @code{msgh_bits} are also
1924: reversed. The @code{MACH_MSGH_BITS_LOCAL} bits have the value
1925: @code{MACH_MSG_TYPE_PORT_SEND} if the message was sent to a send right,
1926: and the value @code{MACH_MSG_TYPE_PORT_SEND_ONCE} if was sent to a
1927: send-once right. The @code{MACH_MSGH_BITS_REMOTE} bits describe the
1928: reply port right.
1929:
1930: A received message can contain port rights and out-of-line memory. The
1931: @code{msgh_local_port} field does not receive a port right; the act of
1932: receiving the message destroys the send or send-once right for the
1933: destination port. The msgh_remote_port field does name a received port
1934: right, the reply port right, and the message body can carry port rights
1935: and memory if @code{MACH_MSGH_BITS_COMPLEX} is present in msgh_bits.
1936: Received port rights and memory should be consumed or deallocated in
1937: some fashion.
1938:
1939: In almost all cases, @code{msgh_local_port} will specify the name of a
1940: receive right, either @code{rcv_name} or if @code{rcv_name} is a port
1941: set, a member of @code{rcv_name}. If other threads are concurrently
1942: manipulating the receive right, the situation is more complicated. If
1943: the receive right is renamed during the call, then
1944: @code{msgh_local_port} specifies the right's new name. If the caller
1945: loses the receive right after the message was dequeued from it, then
1946: @code{mach_msg} will proceed instead of returning
1947: @code{MACH_RCV_PORT_DIED}. If the receive right was destroyed, then
1948: @code{msgh_local_port} specifies @code{MACH_PORT_DEAD}. If the receive
1949: right still exists, but isn't held by the caller, then
1950: @code{msgh_local_port} specifies @code{MACH_PORT_NULL}.
1951:
1.1.1.3 ! root 1952: Servers usually associate some state with a receive right. To that
! 1953: end, they might use a hash table to look up the state for the port a
! 1954: message was sent to. To optimize this, a task may associate an opaque
! 1955: @var{payload} with a receive right using the
! 1956: @code{mach_port_set_protected_payload} function. Once this is done,
! 1957: the kernel will set the @code{msgh_protected_payload} field to
! 1958: @var{payload} when delivering a message to this right and indicate
! 1959: this by setting the local part of @code{msgh_bits} to
! 1960: @code{MACH_MSG_TYPE_PROTECTED_PAYLOAD}.
! 1961:
! 1962: The support for protected payloads was added to GNU Mach. To preserve
! 1963: binary compatibility, the @code{msgh_local_port} and
! 1964: @code{msgh_local_port} share the same location. This makes it
! 1965: possible to add the payload information without increasing the size of
! 1966: @code{mach_msg_header_t}. This is an implementation detail. Which
! 1967: field is valid is determined by the local part of the
! 1968: @code{msgh_bits}. Existing software is not affected. When a receive
! 1969: right is transferred to another task, its payload is cleared.
! 1970:
1.1 root 1971: Received messages are stamped with a sequence number, taken from the
1972: port from which the message was received. (Messages received from a
1973: port set are stamped with a sequence number from the appropriate member
1974: port.) Newly created ports start with a zero sequence number, and the
1975: sequence number is reset to zero whenever the port's receive right moves
1976: between tasks. When a message is dequeued from the port, it is stamped
1977: with the port's sequence number and the port's sequence number is then
1978: incremented. The dequeue and increment operations are atomic, so that
1979: multiple threads receiving messages from a port can use the
1980: @code{msgh_seqno} field to reconstruct the original order of the
1981: messages.
1982:
1983: These options modify @code{MACH_RCV_MSG}. If @code{MACH_RCV_MSG} is not
1984: also specified, they are ignored.
1985:
1986: @table @code
1987: @item MACH_RCV_TIMEOUT
1988: The timeout argument should specify a maximum time (in milliseconds) for
1989: the call to block before giving up.@footnote{If MACH_RCV_TIMEOUT is used
1990: without MACH_RCV_INTERRUPT, then the timeout duration might not be
1991: accurate. When the call is interrupted and automatically retried, the
1992: original timeout is used. If interrupts occur frequently enough, the
1993: timeout interval might never expire.} If no message arrives before the
1994: timeout interval elapses, then the call returns
1995: @code{MACH_RCV_TIMED_OUT}. A zero timeout is legitimate.
1996:
1997: @item MACH_RCV_NOTIFY
1998: The notify argument should specify a receive right for a notify port.
1999: If receiving the reply port creates a new port right in the caller, then
2000: the notify port is used to request a dead-name notification for the new
2001: port right.
2002:
2003: @item MACH_RCV_INTERRUPT
2004: If specified, the @code{mach_msg} call will return
2005: @code{MACH_RCV_INTERRUPTED} if a software interrupt aborts the call.
2006: Otherwise, the receive operation will be retried.
2007:
2008: @item MACH_RCV_LARGE
2009: If the message is larger than @code{rcv_size}, then the message remains
2010: queued instead of being destroyed. The call returns
2011: @code{MACH_RCV_TOO_LARGE} and the actual size of the message is returned
2012: in the @code{msgh_size} field of the message header.
2013: @end table
2014:
2015: The receive operation can generate the following return codes. These
2016: return codes imply that the call did not dequeue a message:
2017:
2018: @table @code
2019: @item MACH_RCV_INVALID_NAME
2020: The specified @code{rcv_name} was invalid.
2021:
2022: @item MACH_RCV_IN_SET
2023: The specified port was a member of a port set.
2024:
2025: @item MACH_RCV_TIMED_OUT
2026: The timeout interval expired.
2027:
2028: @item MACH_RCV_INTERRUPTED
2029: A software interrupt occurred.
2030:
2031: @item MACH_RCV_PORT_DIED
2032: The caller lost the rights specified by @code{rcv_name}.
2033:
2034: @item MACH_RCV_PORT_CHANGED
2035: @code{rcv_name} specified a receive right which was moved into a port
2036: set during the call.
2037:
2038: @item MACH_RCV_TOO_LARGE
2039: When using @code{MACH_RCV_LARGE}, and the message was larger than
2040: @code{rcv_size}. The message is left queued, and its actual size is
2041: returned in the @code{msgh_size} field of the message buffer.
2042: @end table
2043:
2044: These return codes imply that a message was dequeued and destroyed:
2045:
2046: @table @code
2047: @item MACH_RCV_HEADER_ERROR
2048: A resource shortage prevented the reception of the port rights in the
2049: message header.
2050:
2051: @item MACH_RCV_INVALID_NOTIFY
2052: When using @code{MACH_RCV_NOTIFY}, the notify argument did not denote a
2053: valid receive right.
2054:
2055: @item MACH_RCV_TOO_LARGE
2056: When not using @code{MACH_RCV_LARGE}, a message larger than
2057: @code{rcv_size} was dequeued and destroyed.
2058: @end table
2059:
2060: In these situations, when a message is dequeued and then destroyed, the
2061: reply port and all port rights and memory in the message body are
2062: destroyed. However, the caller receives the message's header, with all
2063: fields correct, including the destination port but excepting the reply
2064: port, which is @code{MACH_PORT_NULL}.
2065:
2066: These return codes imply that a message was received:
2067:
2068: @table @code
2069: @item MACH_RCV_BODY_ERROR
2070: A resource shortage prevented the reception of a port right or
2071: out-of-line memory region in the message body. The message header,
2072: including the reply port, is correct. The kernel attempts to transfer
2073: all port rights and memory regions in the body, and only destroys those
2074: that can't be transferred.
2075:
2076: @item MACH_RCV_INVALID_DATA
2077: The specified message buffer was not writable. The calling task did
2078: successfully receive the port rights and out-of-line memory regions in
2079: the message.
2080:
2081: @item MACH_MSG_SUCCESS
2082: A message was received.
2083: @end table
2084:
2085: Resource shortages can occur after a message is dequeued, while
2086: transferring port rights and out-of-line memory regions to the receiving
2087: task. The @code{mach_msg} call returns @code{MACH_RCV_HEADER_ERROR} or
2088: @code{MACH_RCV_BODY_ERROR} in this situation. These return codes always
2089: carry extra bits (bitwise-ored) that indicate the nature of the resource
2090: shortage:
2091:
2092: @table @code
2093: @item MACH_MSG_IPC_SPACE
2094: There was no room in the task's IPC name space for another port name.
2095:
2096: @item MACH_MSG_VM_SPACE
2097: There was no room in the task's VM address space for an out-of-line
2098: memory region.
2099:
2100: @item MACH_MSG_IPC_KERNEL
2101: A kernel resource shortage prevented the reception of a port right.
2102:
2103: @item MACH_MSG_VM_KERNEL
2104: A kernel resource shortage prevented the reception of an out-of-line
2105: memory region.
2106: @end table
2107:
2108: If a resource shortage prevents the reception of a port right, the port
2109: right is destroyed and the caller sees the name @code{MACH_PORT_NULL}.
2110: If a resource shortage prevents the reception of an out-of-line memory
2111: region, the region is destroyed and the caller receives a zero address.
2112: In addition, the @code{msgt_size} (@code{msgtl_size}) field in the
2113: data's type descriptor is changed to zero. If a resource shortage
2114: prevents the reception of out-of-line memory carrying port rights, then
2115: the port rights are always destroyed if the memory region can not be
2116: received. A task never receives port rights or memory regions that it
2117: isn't told about.
2118:
2119:
2120: @node Atomicity
2121: @subsection Atomicity
2122:
2123: The @code{mach_msg} call handles port rights in a message header
2124: atomically. Port rights and out-of-line memory in a message body do not
2125: enjoy this atomicity guarantee. The message body may be processed
2126: front-to-back, back-to-front, first out-of-line memory then port rights,
2127: in some random order, or even atomically.
2128:
2129: For example, consider sending a message with the destination port
2130: specified as @code{MACH_MSG_TYPE_MOVE_SEND} and the reply port specified
2131: as @code{MACH_MSG_TYPE_COPY_SEND}. The same send right, with one
2132: user-reference, is supplied for both the @code{msgh_remote_port} and
2133: @code{msgh_local_port} fields. Because @code{mach_msg} processes the
2134: message header atomically, this succeeds. If @code{msgh_remote_port}
2135: were processed before @code{msgh_local_port}, then @code{mach_msg} would
2136: return @code{MACH_SEND_INVALID_REPLY} in this situation.
2137:
2138: On the other hand, suppose the destination and reply port are both
2139: specified as @code{MACH_MSG_TYPE_MOVE_SEND}, and again the same send
2140: right with one user-reference is supplied for both. Now the send
2141: operation fails, but because it processes the header atomically,
2142: mach_msg can return either @code{MACH_SEND_INVALID_DEST} or
2143: @code{MACH_SEND_INVALID_REPLY}.
2144:
2145: For example, consider receiving a message at the same time another
2146: thread is deallocating the destination receive right. Suppose the reply
2147: port field carries a send right for the destination port. If the
2148: deallocation happens before the dequeuing, then the receiver gets
2149: @code{MACH_RCV_PORT_DIED}. If the deallocation happens after the
2150: receive, then the @code{msgh_local_port} and the @code{msgh_remote_port}
2151: fields both specify the same right, which becomes a dead name when the
2152: receive right is deallocated. If the deallocation happens between the
2153: dequeue and the receive, then the @code{msgh_local_port} and
2154: @code{msgh_remote_port} fields both specify @code{MACH_PORT_DEAD}.
2155: Because the header is processed atomically, it is not possible for just
2156: one of the two fields to hold @code{MACH_PORT_DEAD}.
2157:
2158: The @code{MACH_RCV_NOTIFY} option provides a more likely example.
2159: Suppose a message carrying a send-once right reply port is received with
2160: @code{MACH_RCV_NOTIFY} at the same time the reply port is destroyed. If
2161: the reply port is destroyed first, then @code{msgh_remote_port}
2162: specifies @code{MACH_PORT_DEAD} and the kernel does not generate a
2163: dead-name notification. If the reply port is destroyed after it is
2164: received, then @code{msgh_remote_port} specifies a dead name for which
2165: the kernel generates a dead-name notification. It is not possible to
2166: receive the reply port right and have it turn into a dead name before
2167: the dead-name notification is requested; as part of the message header
2168: the reply port is received atomically.
2169:
2170:
2171: @node Port Manipulation Interface
2172: @section Port Manipulation Interface
2173:
2174: This section describes the interface to create, destroy and manipulate
2175: ports, port rights and port sets.
2176:
2177: @cindex IPC space port
2178: @cindex port representing an IPC space
2179: @deftp {Data type} ipc_space_t
2180: This is a @code{task_t} (and as such a @code{mach_port_t}), which holds
2181: a port name associated with a port that represents an IPC space in the
2182: kernel. An IPC space is used by the kernel to manage the port names and
2183: rights available to a task. The IPC space doesn't get a port name of
2184: its own. Instead the port name of the task containing the IPC space is
2185: used to name the IPC space of the task (as is indicated by the fact that
2186: the type of @code{ipc_space_t} is actually @code{task_t}).
2187:
2188: The IPC spaces of tasks are the only ones accessible outside of
2189: the kernel.
2190: @end deftp
2191:
2192: @menu
2193: * Port Creation:: How to create new ports and port sets.
2194: * Port Destruction:: How to destroy ports and port sets.
2195: * Port Names:: How to query and manipulate port names.
2196: * Port Rights:: How to work with port rights.
2197: * Ports and other Tasks:: How to move rights between tasks.
2198: * Receive Rights:: How to work with receive rights.
2199: * Port Sets:: How to work with port sets.
2200: * Request Notifications:: How to request notifications for events.
1.1.1.3 ! root 2201: * Inherited Ports:: How to work with the inherited system ports.
1.1 root 2202: @end menu
2203:
2204:
2205: @node Port Creation
2206: @subsection Port Creation
2207:
2208: @deftypefun kern_return_t mach_port_allocate (@w{ipc_space_t @var{task}}, @w{mach_port_right_t @var{right}}, @w{mach_port_t *@var{name}})
2209: The @code{mach_port_allocate} function creates a new right in the
2210: specified task. The new right's name is returned in @var{name}, which
2211: may be any name that wasn't in use.
2212:
2213: The @var{right} argument takes the following values:
2214:
2215: @table @code
2216: @item MACH_PORT_RIGHT_RECEIVE
2217: @code{mach_port_allocate} creates a port. The new port is not a member
2218: of any port set. It doesn't have any extant send or send-once rights.
2219: Its make-send count is zero, its sequence number is zero, its queue
2220: limit is @code{MACH_PORT_QLIMIT_DEFAULT}, and it has no queued messages.
2221: @var{name} denotes the receive right for the new port.
2222:
2223: @var{task} does not hold send rights for the new port, only the receive
2224: right. @code{mach_port_insert_right} and @code{mach_port_extract_right}
2225: can be used to convert the receive right into a combined send/receive
2226: right.
2227:
2228: @item MACH_PORT_RIGHT_PORT_SET
2229: @code{mach_port_allocate} creates a port set. The new port set has no
2230: members.
2231:
2232: @item MACH_PORT_RIGHT_DEAD_NAME
2233: @code{mach_port_allocate} creates a dead name. The new dead name has
2234: one user reference.
2235: @end table
2236:
2237: The function returns @code{KERN_SUCCESS} if the call succeeded,
2238: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2239: @code{KERN_INVALID_VALUE} if @var{right} was invalid, @code{KERN_NO_SPACE} if
2240: there was no room in @var{task}'s IPC name space for another right and
2241: @code{KERN_RESOURCE_SHORTAGE} if the kernel ran out of memory.
2242:
2243: The @code{mach_port_allocate} call is actually an RPC to @var{task},
2244: normally a send right for a task port, but potentially any send right.
2245: In addition to the normal diagnostic return codes from the call's server
2246: (normally the kernel), the call may return @code{mach_msg} return codes.
2247: @end deftypefun
2248:
2249: @deftypefun mach_port_t mach_reply_port ()
2250: The @code{mach_reply_port} system call creates a reply port in the
2251: calling task.
2252:
2253: @code{mach_reply_port} creates a port, giving the calling task the
2254: receive right for the port. The call returns the name of the new
2255: receive right.
2256:
2257: This is very much like creating a receive right with the
2258: @code{mach_port_allocate} call, with two differences. First,
2259: @code{mach_reply_port} is a system call and not an RPC (which requires a
2260: reply port). Second, the port created by @code{mach_reply_port} may be
2261: optimized for use as a reply port.
2262:
2263: The function returns @code{MACH_PORT_NULL} if a resource shortage
2264: prevented the creation of the receive right.
2265: @end deftypefun
2266:
2267: @deftypefun kern_return_t mach_port_allocate_name (@w{ipc_space_t @var{task}}, @w{mach_port_right_t @var{right}}, @w{mach_port_t @var{name}})
2268: The function @code{mach_port_allocate_name} creates a new right in the
2269: specified task, with a specified name for the new right. @var{name}
2270: must not already be in use for some right, and it can't be the reserved
2271: values @code{MACH_PORT_NULL} and @code{MACH_PORT_DEAD}.
2272:
2273: The @var{right} argument takes the following values:
2274:
2275: @table @code
2276: @item MACH_PORT_RIGHT_RECEIVE
2277: @code{mach_port_allocate_name} creates a port. The new port is not a
2278: member of any port set. It doesn't have any extant send or send-once
2279: rights. Its make-send count is zero, its sequence number is zero, its
2280: queue limit is @code{MACH_PORT_QLIMIT_DEFAULT}, and it has no queued
2281: messages. @var{name} denotes the receive right for the new port.
2282:
2283: @var{task} does not hold send rights for the new port, only the receive
2284: right. @code{mach_port_insert_right} and @code{mach_port_extract_right}
2285: can be used to convert the receive right into a combined send/receive
2286: right.
2287:
2288: @item MACH_PORT_RIGHT_PORT_SET
2289: @code{mach_port_allocate_name} creates a port set. The new port set has
2290: no members.
2291:
2292: @item MACH_PORT_RIGHT_DEAD_NAME
2293: @code{mach_port_allocate_name} creates a new dead name. The new dead
2294: name has one user reference.
2295: @end table
2296:
2297: The function returns @code{KERN_SUCCESS} if the call succeeded,
2298: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2299: @code{KERN_INVALID_VALUE} if @var{right} was invalid or @var{name} was
2300: @code{MACH_PORT_NULL} or @code{MACH_PORT_DEAD}, @code{KERN_NAME_EXISTS}
2301: if @var{name} was already in use for a port right and
2302: @code{KERN_RESOURCE_SHORTAGE} if the kernel ran out of memory.
2303:
2304: The @code{mach_port_allocate_name} call is actually an RPC to
2305: @var{task}, normally a send right for a task port, but potentially any
2306: send right. In addition to the normal diagnostic return codes from the
2307: call's server (normally the kernel), the call may return @code{mach_msg}
2308: return codes.
2309: @end deftypefun
2310:
2311:
2312: @node Port Destruction
2313: @subsection Port Destruction
2314:
2315: @deftypefun kern_return_t mach_port_deallocate (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}})
2316: The function @code{mach_port_deallocate} releases a user reference for a
2317: right in @var{task}'s IPC name space. It allows a task to release a
2318: user reference for a send or send-once right without failing if the port
2319: has died and the right is now actually a dead name.
2320:
2321: If @var{name} denotes a dead name, send right, or send-once right, then
2322: the right loses one user reference. If it only had one user reference,
2323: then the right is destroyed.
2324:
2325: The function returns @code{KERN_SUCCESS} if the call succeeded,
2326: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2327: @code{KERN_INVALID_NAME} if @var{name} did not denote a right and
2328: @code{KERN_INVALID_RIGHT} if @var{name} denoted an invalid right.
2329:
2330: The @code{mach_port_deallocate} call is actually an RPC to
2331: @var{task}, normally a send right for a task port, but potentially any
2332: send right. In addition to the normal diagnostic return codes from the
2333: call's server (normally the kernel), the call may return @code{mach_msg}
2334: return codes.
2335: @end deftypefun
2336:
2337: @deftypefun kern_return_t mach_port_destroy (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}})
2338: The function @code{mach_port_destroy} deallocates all rights denoted by
2339: a name. The name becomes immediately available for reuse.
2340:
2341: For most purposes, @code{mach_port_mod_refs} and
2342: @code{mach_port_deallocate} are preferable.
2343:
2344: If @var{name} denotes a port set, then all members of the port set are
2345: implicitly removed from the port set.
2346:
2347: If @var{name} denotes a receive right that is a member of a port set,
2348: the receive right is implicitly removed from the port set. If there is
2349: a port-destroyed request registered for the port, then the receive right
2350: is not actually destroyed, but instead is sent in a port-destroyed
2351: notification to the backup port. If there is no registered
2352: port-destroyed request, remaining messages queued to the port are
2353: destroyed and extant send and send-once rights turn into dead names. If
2354: those send and send-once rights have dead-name requests registered, then
2355: dead-name notifications are generated for them.
2356:
2357: If @var{name} denotes a send-once right, then the send-once right is
2358: used to produce a send-once notification for the port.
2359:
2360: If @var{name} denotes a send-once, send, and/or receive right, and it
2361: has a dead-name request registered, then the registered send-once right
2362: is used to produce a port-deleted notification for the name.
2363:
2364: The function returns @code{KERN_SUCCESS} if the call succeeded,
2365: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2366: @code{KERN_INVALID_NAME} if @var{name} did not denote a right.
2367:
2368: The @code{mach_port_destroy} call is actually an RPC to
2369: @var{task}, normally a send right for a task port, but potentially any
2370: send right. In addition to the normal diagnostic return codes from the
2371: call's server (normally the kernel), the call may return @code{mach_msg}
2372: return codes.
2373: @end deftypefun
2374:
2375:
2376: @node Port Names
2377: @subsection Port Names
2378:
2379: @deftypefun kern_return_t mach_port_names (@w{ipc_space_t @var{task}}, @w{mach_port_array_t *@var{names}}, @w{mach_msg_type_number_t *@var{ncount}}, @w{mach_port_type_array_t *@var{types}}, @w{mach_msg_type_number_t *@var{tcount}})
2380: The function @code{mach_port_names} returns information about
2381: @var{task}'s port name space. For each name, it also returns what type
2382: of rights @var{task} holds. (The same information returned by
2383: @code{mach_port_type}.) @var{names} and @var{types} are arrays that are
2384: automatically allocated when the reply message is received. The user
2385: should @code{vm_deallocate} them when the data is no longer needed.
2386:
2387: @code{mach_port_names} will return in @var{names} the names of the
2388: ports, port sets, and dead names in the task's port name space, in no
2389: particular order and in @var{ncount} the number of names returned. It
2390: will return in @var{types} the type of each corresponding name, which
2391: indicates what kind of rights the task holds with that name.
2392: @var{tcount} should be the same as @var{ncount}.
2393:
2394: The function returns @code{KERN_SUCCESS} if the call succeeded,
2395: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2396: @code{KERN_RESOURCE_SHORTAGE} if the kernel ran out of memory.
2397:
2398: The @code{mach_port_names} call is actually an RPC to @var{task},
2399: normally a send right for a task port, but potentially any send right.
2400: In addition to the normal diagnostic return codes from the call's server
2401: (normally the kernel), the call may return @code{mach_msg} return codes.
2402: @end deftypefun
2403:
2404: @deftypefun kern_return_t mach_port_type (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_port_type_t *@var{ptype}})
2405: The function @code{mach_port_type} returns information about
2406: @var{task}'s rights for a specific name in its port name space. The
2407: returned @var{ptype} is a bitmask indicating what rights @var{task}
2408: holds for the port, port set or dead name. The bitmask is composed of
2409: the following bits:
2410:
2411: @table @code
2412: @item MACH_PORT_TYPE_SEND
2413: The name denotes a send right.
2414:
2415: @item MACH_PORT_TYPE_RECEIVE
2416: The name denotes a receive right.
2417:
2418: @item MACH_PORT_TYPE_SEND_ONCE
2419: The name denotes a send-once right.
2420:
2421: @item MACH_PORT_TYPE_PORT_SET
2422: The name denotes a port set.
2423:
2424: @item MACH_PORT_TYPE_DEAD_NAME
2425: The name is a dead name.
2426:
2427: @item MACH_PORT_TYPE_DNREQUEST
2428: A dead-name request has been registered for the right.
2429:
2430: @item MACH_PORT_TYPE_MAREQUEST
2431: A msg-accepted request for the right is pending.
2432:
2433: @item MACH_PORT_TYPE_COMPAT
2434: The port right was created in the compatibility mode.
2435: @end table
2436:
2437: The function returns @code{KERN_SUCCESS} if the call succeeded,
2438: @code{KERN_INVALID_TASK} if @var{task} was invalid and
2439: @code{KERN_INVALID_NAME} if @var{name} did not denote a right.
2440:
2441: The @code{mach_port_type} call is actually an RPC to @var{task},
2442: normally a send right for a task port, but potentially any send right.
2443: In addition to the normal diagnostic return codes from the call's server
2444: (normally the kernel), the call may return @code{mach_msg} return codes.
2445: @end deftypefun
2446:
2447: @deftypefun kern_return_t mach_port_rename (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{old_name}}, @w{mach_port_t @var{new_name}})
2448: The function @code{mach_port_rename} changes the name by which a port,
2449: port set, or dead name is known to @var{task}. @var{old_name} is the
2450: original name and @var{new_name} the new name for the port right.
2451: @var{new_name} must not already be in use, and it can't be the
2452: distinguished values @code{MACH_PORT_NULL} and @code{MACH_PORT_DEAD}.
2453:
2454: The function returns @code{KERN_SUCCESS} if the call succeeded,
2455: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2456: @code{KERN_INVALID_NAME} if @var{old_name} did not denote a right,
2457: @code{KERN_INVALID_VALUE} if @var{new_name} was @code{MACH_PORT_NULL} or
2458: @code{MACH_PORT_DEAD}, @code{KERN_NAME_EXISTS} if @code{new_name}
2459: already denoted a right and @code{KERN_RESOURCE_SHORTAGE} if the kernel
2460: ran out of memory.
2461:
2462: The @code{mach_port_rename} call is actually an RPC to @var{task},
2463: normally a send right for a task port, but potentially any send right.
2464: In addition to the normal diagnostic return codes from the call's server
2465: (normally the kernel), the call may return @code{mach_msg} return codes.
2466: @end deftypefun
2467:
2468:
2469: @node Port Rights
2470: @subsection Port Rights
2471:
2472: @deftypefun kern_return_t mach_port_get_refs (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_port_right_t @var{right}}, @w{mach_port_urefs_t *@var{refs}})
2473: The function @code{mach_port_get_refs} returns the number of user
2474: references a task has for a right.
2475:
2476: The @var{right} argument takes the following values:
2477: @itemize @bullet
2478: @item @code{MACH_PORT_RIGHT_SEND}
2479: @item @code{MACH_PORT_RIGHT_RECEIVE}
2480: @item @code{MACH_PORT_RIGHT_SEND_ONCE}
2481: @item @code{MACH_PORT_RIGHT_PORT_SET}
2482: @item @code{MACH_PORT_RIGHT_DEAD_NAME}
2483: @end itemize
2484:
2485: If @var{name} denotes a right, but not the type of right specified, then
2486: zero is returned. Otherwise a positive number of user references is
2487: returned. Note that a name may simultaneously denote send and receive
2488: rights.
2489:
2490: The function returns @code{KERN_SUCCESS} if the call succeeded,
2491: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2492: @code{KERN_INVALID_VALUE} if @var{right} was invalid and
2493: @code{KERN_INVALID_NAME} if @var{name} did not denote a right.
2494:
2495: The @code{mach_port_get_refs} call is actually an RPC to @var{task},
2496: normally a send right for a task port, but potentially any send right.
2497: In addition to the normal diagnostic return codes from the call's server
2498: (normally the kernel), the call may return @code{mach_msg} return codes.
2499: @end deftypefun
2500:
2501: @deftypefun kern_return_t mach_port_mod_refs (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_port_right_t @var{right}}, @w{mach_port_delta_t @var{delta}})
2502: The function @code{mach_port_mod_refs} requests that the number of user
2503: references a task has for a right be changed. This results in the right
2504: being destroyed, if the number of user references is changed to zero.
2505: The task holding the right is @var{task}, @var{name} should denote the
2506: specified right. @var{right} denotes the type of right being modified.
2507: @var{delta} is the signed change to the number of user references.
2508:
2509: The @var{right} argument takes the following values:
2510: @itemize @bullet
2511: @item @code{MACH_PORT_RIGHT_SEND}
2512: @item @code{MACH_PORT_RIGHT_RECEIVE}
2513: @item @code{MACH_PORT_RIGHT_SEND_ONCE}
2514: @item @code{MACH_PORT_RIGHT_PORT_SET}
2515: @item @code{MACH_PORT_RIGHT_DEAD_NAME}
2516: @end itemize
2517:
2518: The number of user references for the right is changed by the amount
2519: @var{delta}, subject to the following restrictions: port sets, receive
2520: rights, and send-once rights may only have one user reference. The
2521: resulting number of user references can't be negative. If the resulting
2522: number of user references is zero, the effect is to deallocate the
2523: right. For dead names and send rights, there is an
2524: implementation-defined maximum number of user references.
2525:
2526: If the call destroys the right, then the effect is as described for
2527: @code{mach_port_destroy}, with the exception that
2528: @code{mach_port_destroy} simultaneously destroys all the rights denoted
2529: by a name, while @code{mach_port_mod_refs} can only destroy one right.
2530: The name will be available for reuse if it only denoted the one right.
2531:
2532: The function returns @code{KERN_SUCCESS} if the call succeeded,
2533: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2534: @code{KERN_INVALID_VALUE} if @var{right} was invalid or the
2535: user-reference count would become negative, @code{KERN_INVALID_NAME} if
2536: @var{name} did not denote a right, @code{KERN_INVALID_RIGHT} if
2537: @var{name} denoted a right, but not the specified right and
2538: @code{KERN_UREFS_OVERFLOW} if the user-reference count would overflow.
2539:
2540: The @code{mach_port_mod_refs} call is actually an RPC to @var{task},
2541: normally a send right for a task port, but potentially any send right.
2542: In addition to the normal diagnostic return codes from the call's server
2543: (normally the kernel), the call may return @code{mach_msg} return codes.
2544: @end deftypefun
2545:
2546:
2547: @node Ports and other Tasks
2548: @subsection Ports and other Tasks
2549:
2550: @deftypefun kern_return_t mach_port_insert_right (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_port_t @var{right}}, @w{mach_msg_type_name_t @var{right_type}})
2551: The function @var{mach_port_insert_right} inserts into @var{task} the
2552: caller's right for a port, using a specified name for the right in the
2553: target task.
2554:
2555: The specified @var{name} can't be one of the reserved values
2556: @code{MACH_PORT_NULL} or @code{MACH_PORT_DEAD}. The @var{right} can't
2557: be @code{MACH_PORT_NULL} or @code{MACH_PORT_DEAD}.
2558:
2559: The argument @var{right_type} specifies a right to be inserted and how
2560: that right should be extracted from the caller. It should be a value
2561: appropriate for @var{msgt_name}; see @code{mach_msg}. @c XXX cross ref
2562:
2563: If @var{right_type} is @code{MACH_MSG_TYPE_MAKE_SEND},
2564: @code{MACH_MSG_TYPE_MOVE_SEND}, or @code{MACH_MSG_TYPE_COPY_SEND}, then
2565: a send right is inserted. If the target already holds send or receive
2566: rights for the port, then @var{name} should denote those rights in the
2567: target. Otherwise, @var{name} should be unused in the target. If the
2568: target already has send rights, then those send rights gain an
2569: additional user reference. Otherwise, the target gains a send right,
2570: with a user reference count of one.
2571:
2572: If @var{right_type} is @code{MACH_MSG_TYPE_MAKE_SEND_ONCE} or
2573: @code{MACH_MSG_TYPE_MOVE_SEND_ONCE}, then a send-once right is inserted.
2574: The name should be unused in the target. The target gains a send-once
2575: right.
2576:
2577: If @var{right_type} is @code{MACH_MSG_TYPE_MOVE_RECEIVE}, then a receive
2578: right is inserted. If the target already holds send rights for the
2579: port, then name should denote those rights in the target. Otherwise,
2580: name should be unused in the target. The receive right is moved into
2581: the target task.
2582:
2583: The function returns @code{KERN_SUCCESS} if the call succeeded,
2584: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2585: @code{KERN_INVALID_VALUE} if @var{right} was not a port right or
2586: @var{name} was @code{MACH_PORT_NULL} or @code{MACH_PORT_DEAD},
2587: @code{KERN_NAME_EXISTS} if @var{name} already denoted a right,
2588: @code{KERN_INVALID_CAPABILITY} if @var{right} was @code{MACH_PORT_NULL}
2589: or @code{MACH_PORT_DEAD} @code{KERN_RIGHT_EXISTS} if @var{task} already
2590: had rights for the port, with a different name,
2591: @code{KERN_UREFS_OVERFLOW} if the user-reference count would overflow
2592: and @code{KERN_RESOURCE_SHORTAGE} if the kernel ran out of memory.
2593:
2594: The @code{mach_port_insert_right} call is actually an RPC to @var{task},
2595: normally a send right for a task port, but potentially any send right.
2596: In addition to the normal diagnostic return codes from the call's server
2597: (normally the kernel), the call may return @code{mach_msg} return codes.
2598: @end deftypefun
2599:
2600: @deftypefun kern_return_t mach_port_extract_right (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_msg_type_name_t @var{desired_type}}, @w{mach_port_t *@var{right}}, @w{mach_msg_type_name_t *@var{acquired_type}})
2601: The function @var{mach_port_extract_right} extracts a port right from
2602: the target @var{task} and returns it to the caller as if the task sent
2603: the right voluntarily, using @var{desired_type} as the value of
2604: @var{msgt_name}. @xref{Mach Message Call}.
2605:
2606: The returned value of @var{acquired_type} will be
2607: @code{MACH_MSG_TYPE_PORT_SEND} if a send right is extracted,
2608: @code{MACH_MSG_TYPE_PORT_RECEIVE} if a receive right is extracted, and
2609: @code{MACH_MSG_TYPE_PORT_SEND_ONCE} if a send-once right is extracted.
2610:
2611: The function returns @code{KERN_SUCCESS} if the call succeeded,
2612: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2613: @code{KERN_INVALID_NAME} if @var{name} did not denote a right,
2614: @code{KERN_INVALID_RIGHT} if @var{name} denoted a right, but an invalid one,
2615: @code{KERN_INVALID_VALUE} if @var{desired_type} was invalid.
2616:
2617: The @code{mach_port_extract_right} call is actually an RPC to
2618: @var{task}, normally a send right for a task port, but potentially any
2619: send right. In addition to the normal diagnostic return codes from the
2620: call's server (normally the kernel), the call may return @code{mach_msg}
2621: return codes.
2622: @end deftypefun
2623:
2624:
2625: @node Receive Rights
2626: @subsection Receive Rights
2627:
2628: @deftp {Data type} mach_port_seqno_t
2629: The @code{mach_port_seqno_t} data type is an @code{unsigned int} which
2630: contains the sequence number of a port.
2631: @end deftp
2632:
2633: @deftp {Data type} mach_port_mscount_t
2634: The @code{mach_port_mscount_t} data type is an @code{unsigned int} which
2635: contains the make-send count for a port.
2636: @end deftp
2637:
2638: @deftp {Data type} mach_port_msgcount_t
2639: The @code{mach_port_msgcount_t} data type is an @code{unsigned int} which
2640: contains a number of messages.
2641: @end deftp
2642:
2643: @deftp {Data type} mach_port_rights_t
2644: The @code{mach_port_rights_t} data type is an @code{unsigned int} which
2645: contains a number of rights for a port.
2646: @end deftp
2647:
2648: @deftp {Data type} mach_port_status_t
2649: This structure contains some status information about a port, which can
2650: be queried with @code{mach_port_get_receive_status}. It has the following
2651: members:
2652:
2653: @table @code
2654: @item mach_port_t mps_pset
2655: The containing port set.
2656:
2657: @item mach_port_seqno_t mps_seqno
2658: The sequence number.
2659:
2660: @item mach_port_mscount_t mps_mscount
2661: The make-send count.
2662:
2663: @item mach_port_msgcount_t mps_qlimit
2664: The maximum number of messages in the queue.
2665:
2666: @item mach_port_msgcount_t mps_msgcount
2667: The current number of messages in the queue.
2668:
2669: @item mach_port_rights_t mps_sorights
2670: The number of send-once rights that exist.
2671:
2672: @item boolean_t mps_srights
2673: @code{TRUE} if send rights exist.
2674:
2675: @item boolean_t mps_pdrequest
2676: @code{TRUE} if port-deleted notification is requested.
2677:
2678: @item boolean_t mps_nsrequest
2679: @code{TRUE} if no-senders notification is requested.
2680: @end table
2681: @end deftp
2682:
2683: @deftypefun kern_return_t mach_port_get_receive_status (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_port_status_t *@var{status}})
2684: The function @code{mach_port_get_receive_status} returns the current
2685: status of the specified receive right.
2686:
2687: The function returns @code{KERN_SUCCESS} if the call succeeded,
2688: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2689: @code{KERN_INVALID_NAME} if @var{name} did not denote a right and
2690: @code{KERN_INVALID_RIGHT} if @var{name} denoted a right, but not a
2691: receive right.
2692:
2693: The @code{mach_port_get_receive_status} call is actually an RPC to @var{task},
2694: normally a send right for a task port, but potentially any send right.
2695: In addition to the normal diagnostic return codes from the call's server
2696: (normally the kernel), the call may return @code{mach_msg} return codes.
2697: @end deftypefun
2698:
2699: @deftypefun kern_return_t mach_port_set_mscount (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_port_mscount_t @var{mscount}})
2700: The function @code{mach_port_set_mscount} changes the make-send count of
2701: @var{task}'s receive right named @var{name} to @var{mscount}. All
2702: values for @var{mscount} are valid.
2703:
2704: The function returns @code{KERN_SUCCESS} if the call succeeded,
2705: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2706: @code{KERN_INVALID_NAME} if @var{name} did not denote a right and
2707: @code{KERN_INVALID_RIGHT} if @var{name} denoted a right, but not a
2708: receive right.
2709:
2710: The @code{mach_port_set_mscount} call is actually an RPC to @var{task},
2711: normally a send right for a task port, but potentially any send right.
2712: In addition to the normal diagnostic return codes from the call's server
2713: (normally the kernel), the call may return @code{mach_msg} return codes.
2714: @end deftypefun
2715:
2716: @deftypefun kern_return_t mach_port_set_qlimit (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_port_msgcount_t @var{qlimit}})
2717: The function @code{mach_port_set_qlimit} changes the queue limit
2718: @var{task}'s receive right named @var{name} to @var{qlimit}. Valid
2719: values for @var{qlimit} are between zero and
2720: @code{MACH_PORT_QLIMIT_MAX}, inclusive.
2721:
2722: The function returns @code{KERN_SUCCESS} if the call succeeded,
2723: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2724: @code{KERN_INVALID_NAME} if @var{name} did not denote a right,
2725: @code{KERN_INVALID_RIGHT} if @var{name} denoted a right, but not a
2726: receive right and @code{KERN_INVALID_VALUE} if @var{qlimit} was invalid.
2727:
2728: The @code{mach_port_set_qlimit} call is actually an RPC to @var{task},
2729: normally a send right for a task port, but potentially any send right.
2730: In addition to the normal diagnostic return codes from the call's server
2731: (normally the kernel), the call may return @code{mach_msg} return codes.
2732: @end deftypefun
2733:
2734: @deftypefun kern_return_t mach_port_set_seqno (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_port_seqno_t @var{seqno}})
2735: The function @code{mach_port_set_seqno} changes the sequence number
2736: @var{task}'s receive right named @var{name} to @var{seqno}. All
2737: sequence number values are valid. The next message received from the
2738: port will be stamped with the specified sequence number.
2739:
2740: The function returns @code{KERN_SUCCESS} if the call succeeded,
2741: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2742: @code{KERN_INVALID_NAME} if @var{name} did not denote a right and
2743: @code{KERN_INVALID_RIGHT} if @var{name} denoted a right, but not a
2744: receive right.
2745:
2746: The @code{mach_port_set_seqno} call is actually an RPC to @var{task},
2747: normally a send right for a task port, but potentially any send right.
2748: In addition to the normal diagnostic return codes from the call's server
2749: (normally the kernel), the call may return @code{mach_msg} return codes.
2750: @end deftypefun
2751:
1.1.1.3 ! root 2752: @deftypefun kern_return_t mach_port_set_protected_payload (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{unsigned long @var{payload}})
! 2753: The function @code{mach_port_set_protected_payload} sets the protected
! 2754: payload associated with the right @var{name} to @var{payload}.
! 2755: Section @ref{Message Receive} describes how setting a protected
! 2756: payload affects the messages delivered to @var{name}.
! 2757:
! 2758: The function returns @code{KERN_SUCCESS} if the call succeeded,
! 2759: @code{KERN_INVALID_TASK} if @var{task} was invalid,
! 2760: @code{KERN_INVALID_NAME} if @var{name} did not denote a right and
! 2761: @code{KERN_INVALID_RIGHT} if @var{name} denoted a right, but not a
! 2762: receive right.
! 2763:
! 2764: The @code{mach_port_set_protected_payload} call is actually an RPC to
! 2765: @var{task}, normally a send right for a task port, but potentially any
! 2766: send right. In addition to the normal diagnostic return codes from
! 2767: the call's server (normally the kernel), the call may return
! 2768: @code{mach_msg} return codes.
! 2769: @end deftypefun
! 2770:
! 2771: @deftypefun kern_return_t mach_port_clear_protected_payload (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{unsigned long @var{payload}})
! 2772: The function @code{mach_port_clear_protected_payload} clears the
! 2773: protected payload associated with the right @var{name}.
! 2774:
! 2775: The function returns @code{KERN_SUCCESS} if the call succeeded,
! 2776: @code{KERN_INVALID_TASK} if @var{task} was invalid,
! 2777: @code{KERN_INVALID_NAME} if @var{name} did not denote a right and
! 2778: @code{KERN_INVALID_RIGHT} if @var{name} denoted a right, but not a
! 2779: receive right.
! 2780:
! 2781: The @code{mach_port_clear_protected_payload} call is actually an RPC
! 2782: to @var{task}, normally a send right for a task port, but potentially
! 2783: any send right. In addition to the normal diagnostic return codes
! 2784: from the call's server (normally the kernel), the call may return
! 2785: @code{mach_msg} return codes.
! 2786: @end deftypefun
1.1 root 2787:
2788: @node Port Sets
2789: @subsection Port Sets
2790:
2791: @deftypefun kern_return_t mach_port_get_set_status (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_port_array_t *@var{members}}, @w{mach_msg_type_number_t *@var{count}})
2792: The function @code{mach_port_get_set_status} returns the members of a
2793: port set. @var{members} is an array that is automatically allocated
2794: when the reply message is received. The user should
2795: @code{vm_deallocate} it when the data is no longer needed.
2796:
2797: The function returns @code{KERN_SUCCESS} if the call succeeded,
2798: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2799: @code{KERN_INVALID_NAME} if @var{name} did not denote a right,
2800: @code{KERN_INVALID_RIGHT} if @var{name} denoted a right, but not a
2801: receive right and @code{KERN_RESOURCE_SHORTAGE} if the kernel ran out of
2802: memory.
2803:
2804: The @code{mach_port_get_set_status} call is actually an RPC to
2805: @var{task}, normally a send right for a task port, but potentially any
2806: send right. In addition to the normal diagnostic return codes from the
2807: call's server (normally the kernel), the call may return @code{mach_msg}
2808: return codes.
2809: @end deftypefun
2810:
2811: @deftypefun kern_return_t mach_port_move_member (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{member}}, @w{mach_port_t @var{after}})
2812: The function @var{mach_port_move_member} moves the receive right
2813: @var{member} into the port set @var{after}. If the receive right is
2814: already a member of another port set, it is removed from that set first
2815: (the whole operation is atomic). If the port set is
2816: @code{MACH_PORT_NULL}, then the receive right is not put into a port
2817: set, but removed from its current port set.
2818:
2819: The function returns @code{KERN_SUCCESS} if the call succeeded,
2820: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2821: @code{KERN_INVALID_NAME} if @var{member} or @var{after} did not denote a
2822: right, @code{KERN_INVALID_RIGHT} if @var{member} denoted a right, but
2823: not a receive right or @var{after} denoted a right, but not a port set,
2824: and @code{KERN_NOT_IN_SET} if @var{after} was @code{MACH_PORT_NULL}, but
2825: @code{member} wasn't currently in a port set.
2826:
2827: The @code{mach_port_move_member} call is actually an RPC to @var{task},
2828: normally a send right for a task port, but potentially any send right.
2829: In addition to the normal diagnostic return codes from the call's server
2830: (normally the kernel), the call may return @code{mach_msg} return codes.
2831: @end deftypefun
2832:
2833:
2834: @node Request Notifications
2835: @subsection Request Notifications
2836:
2837: @deftypefun kern_return_t mach_port_request_notification (@w{ipc_space_t @var{task}}, @w{mach_port_t @var{name}}, @w{mach_msg_id_t @var{variant}}, @w{mach_port_mscount_t @var{sync}}, @w{mach_port_t @var{notify}}, @w{mach_msg_type_name_t @var{notify_type}}, @w{mach_port_t *@var{previous}})
2838: The function @code{mach_port_request_notification} registers a request
2839: for a notification and supplies the send-once right @var{notify} to
2840: which the notification will be sent. The @var{notify_type} denotes the
2841: IPC type for the send-once right, which can be
2842: @code{MACH_MSG_TYPE_MAKE_SEND_ONCE} or
2843: @code{MACH_MSG_TYPE_MOVE_SEND_ONCE}. It is an atomic swap, returning
2844: the previously registered send-once right (or @code{MACH_PORT_NULL} for
2845: none) in @var{previous}. A previous notification request may be
2846: cancelled by providing @code{MACH_PORT_NULL} for @var{notify}.
2847:
2848: The @var{variant} argument takes the following values:
2849:
2850: @table @code
2851: @item MACH_NOTIFY_PORT_DESTROYED
2852: @var{sync} must be zero. The @var{name} must specify a receive right,
2853: and the call requests a port-destroyed notification for the receive
2854: right. If the receive right were to have been destroyed, say by
2855: @code{mach_port_destroy}, then instead the receive right will be sent in
2856: a port-destroyed notification to the registered send-once right.
2857:
2858: @item MACH_NOTIFY_DEAD_NAME
2859: The call requests a dead-name notification. @var{name} specifies send,
2860: receive, or send-once rights for a port. If the port is destroyed (and
2861: the right remains, becoming a dead name), then a dead-name notification
2862: which carries the name of the right will be sent to the registered
2863: send-once right. If @var{notify} is not null and sync is non-zero, the
2864: name may specify a dead name, and a dead-name notification is
2865: immediately generated.
2866:
2867: Whenever a dead-name notification is generated, the user reference count
2868: of the dead name is incremented. For example, a send right with two
2869: user refs has a registered dead-name request. If the port is destroyed,
2870: the send right turns into a dead name with three user refs (instead of
2871: two), and a dead-name notification is generated.
2872:
2873: If the name is made available for reuse, perhaps because of
2874: @code{mach_port_destroy} or @code{mach_port_mod_refs}, or the name
2875: denotes a send-once right which has a message sent to it, then the
2876: registered send-once right is used to generate a port-deleted
2877: notification.
2878:
2879: @item MACH_NOTIFY_NO_SENDERS
2880: The call requests a no-senders notification. @var{name} must specify a
2881: receive right. If @var{notify} is not null, and the receive right's
2882: make-send count is greater than or equal to the sync value, and it has
2883: no extant send rights, than an immediate no-senders notification is
2884: generated. Otherwise the notification is generated when the receive
2885: right next loses its last extant send right. In either case, any
2886: previously registered send-once right is returned.
2887:
2888: The no-senders notification carries the value the port's make-send count
2889: had when it was generated. The make-send count is incremented whenever
2890: @code{MACH_MSG_TYPE_MAKE_SEND} is used to create a new send right from
2891: the receive right. The make-send count is reset to zero when the
2892: receive right is carried in a message.
2893: @end table
2894:
2895: The function returns @code{KERN_SUCCESS} if the call succeeded,
2896: @code{KERN_INVALID_TASK} if @var{task} was invalid,
2897: @code{KERN_INVALID_VALUE} if @var{variant} was invalid,
2898: @code{KERN_INVALID_NAME} if @var{name} did not denote a right,
2899: @code{KERN_INVALID_RIGHT} if @var{name} denoted an invalid right and
2900: @code{KERN_INVALID_CAPABILITY} if @var{notify} was invalid.
2901:
2902: When using @code{MACH_NOTIFY_PORT_DESTROYED}, the function returns
2903: @code{KERN_INVALID_VALUE} if @var{sync} wasn't zero.
2904:
2905: When using @code{MACH_NOTIFY_DEAD_NAME}, the function returns
2906: @code{KERN_RESOURCE_SHORTAGE} if the kernel ran out of memory,
2907: @code{KERN_INVALID_ARGUMENT} if @var{name} denotes a dead name, but
2908: @var{sync} is zero or @var{notify} is @code{MACH_PORT_NULL}, and
2909: @code{KERN_UREFS_OVERFLOW} if @var{name} denotes a dead name, but
2910: generating an immediate dead-name notification would overflow the name's
2911: user-reference count.
2912:
2913: The @code{mach_port_request_notification} call is actually an RPC to
2914: @var{task}, normally a send right for a task port, but potentially any
2915: send right. In addition to the normal diagnostic return codes from the
2916: call's server (normally the kernel), the call may return @code{mach_msg}
2917: return codes.
2918: @end deftypefun
2919:
1.1.1.3 ! root 2920: @node Inherited Ports
! 2921: @subsection Inherited Ports
1.1 root 2922:
1.1.1.3 ! root 2923: The inherited ports concept is not used in the Hurd, and so the _SLOT
! 2924: macros are not defined in GNU Mach.
1.1 root 2925:
1.1.1.3 ! root 2926: The following section documents how @code{mach_ports_register} and
! 2927: @code{mach_ports_lookup} were originally intended to be used.
! 2928:
! 2929: @deftypefun kern_return_t mach_ports_register (@w{task_t @var{target_task}}, @w{port_array_t @var{init_port_set}}, @w{int @var{init_port_array_count}})
! 2930: @deftypefunx kern_return_t mach_ports_lookup (@w{task_t @var{target_task}}, @w{port_array_t *@var{init_port_set}}, @w{int *@var{init_port_array_count}})
! 2931: @code{mach_ports_register} manipulates the inherited ports array,
! 2932: @code{mach_ports_lookup} is used to acquire specific parent ports.
! 2933: @var{target_task} is the task to be affected. @var{init_port_set} is an
! 2934: array of system ports to be registered, or returned. Although the array
! 2935: size is given as variable, the kernel will only accept a limited number
! 2936: of ports. @var{init_port_array_count} is the number of ports returned
! 2937: in @var{init_port_set}.
! 2938:
! 2939: @code{mach_ports_register} registers an array of well-known system ports
! 2940: with the kernel on behalf of a specific task. Currently the ports to be
! 2941: registered are: the port to the Network Name Server, the port to the
! 2942: Environment Manager, and a port to the Service server. These port
! 2943: values must be placed in specific slots in the init_port_set. The slot
! 2944: numbers are given by the global constants defined in @file{mach_init.h}:
! 2945: @code{NAME_SERVER_SLOT}, @code{ENVIRONMENT_SLOT}, and
! 2946: @code{SERVICE_SLOT}. These ports may later be retrieved with
! 2947: @code{mach_ports_lookup}.
! 2948:
! 2949: When a new task is created (see @code{task_create}), the child task will
! 2950: be given access to these ports. Only port send rights may be
! 2951: registered. Furthermore, the number of ports which may be registered is
! 2952: fixed and given by the global constant @code{MACH_PORT_SLOTS_USED}
! 2953: Attempts to register too many ports will fail.
! 2954:
! 2955: It is intended that this mechanism be used only for task initialization,
! 2956: and then only by runtime support modules. A parent task has three
! 2957: choices in passing these system ports to a child task. Most commonly it
! 2958: can do nothing and its child will inherit access to the same
! 2959: @var{init_port_set} that the parent has; or a parent task may register a
! 2960: set of ports it wishes to have passed to all of its children by calling
! 2961: @code{mach_ports_register} using its task port; or it may make necessary
! 2962: modifications to the set of ports it wishes its child to see, and then
! 2963: register those ports using the child's task port prior to starting the
! 2964: child's thread(s). The @code{mach_ports_lookup} call which is done by
! 2965: @code{mach_init} in the child task will acquire these initial ports for
! 2966: the child.
! 2967:
! 2968: Tasks other than the Network Name Server and the Environment Manager
! 2969: should not need access to the Service port. The Network Name Server port
! 2970: is the same for all tasks on a given machine. The Environment port is
! 2971: the only port likely to have different values for different tasks.
! 2972:
! 2973: Since the number of ports which may be registered is limited, ports
! 2974: other than those used by the runtime system to initialize a task should
! 2975: be passed to children either through an initial message, or through the
! 2976: Network Name Server for public ports, or the Environment Manager for
! 2977: private ports.
! 2978:
! 2979: The function returns @code{KERN_SUCCESS} if the memory was allocated,
! 2980: and @code{KERN_INVALID_ARGUMENT} if an attempt was made to register more
! 2981: ports than the current kernel implementation allows.
! 2982: @end deftypefun
1.1 root 2983:
2984:
2985: @node Virtual Memory Interface
2986: @chapter Virtual Memory Interface
2987:
2988: @cindex virtual memory map port
2989: @cindex port representing a virtual memory map
2990: @deftp {Data type} vm_task_t
2991: This is a @code{task_t} (and as such a @code{mach_port_t}), which holds
2992: a port name associated with a port that represents a virtual memory map
2993: in the kernel. An virtual memory map is used by the kernel to manage
2994: the address space of a task. The virtual memory map doesn't get a port
2995: name of its own. Instead the port name of the task provided with the
2996: virtual memory is used to name the virtual memory map of the task (as is
2997: indicated by the fact that the type of @code{vm_task_t} is actually
2998: @code{task_t}).
2999:
3000: The virtual memory maps of tasks are the only ones accessible outside of
3001: the kernel.
3002: @end deftp
3003:
3004: @menu
3005: * Memory Allocation:: Allocation of new virtual memory.
3006: * Memory Deallocation:: Freeing unused virtual memory.
3007: * Data Transfer:: Reading, writing and copying memory.
3008: * Memory Attributes:: Tweaking memory regions.
3009: * Mapping Memory Objects:: How to map memory objects.
3010: * Memory Statistics:: How to get statistics about memory usage.
3011: @end menu
3012:
3013: @node Memory Allocation
3014: @section Memory Allocation
3015:
3016: @deftypefun kern_return_t vm_allocate (@w{vm_task_t @var{target_task}}, @w{vm_address_t *@var{address}}, @w{vm_size_t @var{size}}, @w{boolean_t @var{anywhere}})
3017: The function @code{vm_allocate} allocates a region of virtual memory,
3018: placing it in the specified @var{task}'s address space.
3019:
3020: The starting address is @var{address}. If the @var{anywhere} option is
3021: false, an attempt is made to allocate virtual memory starting at this
3022: virtual address. If this address is not at the beginning of a virtual
3023: page, it will be rounded down to one. If there is not enough space at
3024: this address, no memory will be allocated. If the @var{anywhere} option
3025: is true, the input value of this address will be ignored, and the space
3026: will be allocated wherever it is available. In either case, the address
3027: at which memory was actually allocated will be returned in
3028: @var{address}.
3029:
3030: @var{size} is the number of bytes to allocate (rounded by the system in
3031: a machine dependent way to an integral number of virtual pages).
3032:
3033: If @var{anywhere} is true, the kernel should find and allocate any
3034: region of the specified size, and return the address of the resulting
3035: region in address address, rounded to a virtual page boundary if there
3036: is sufficient space.
3037:
3038: The physical memory is not actually allocated until the new virtual
3039: memory is referenced. By default, the kernel rounds all addresses down
3040: to the nearest page boundary and all memory sizes up to the nearest page
3041: size. The global variable @code{vm_page_size} contains the page size.
3042: @code{mach_task_self} returns the value of the current task port which
3043: should be used as the @var{target_task} argument in order to allocate
3044: memory in the caller's address space. For languages other than C, these
3045: values can be obtained by the calls @code{vm_statistics} and
3046: @code{mach_task_self}. Initially, the pages of allocated memory will be
3047: protected to allow all forms of access, and will be inherited in child
3048: tasks as a copy. Subsequent calls to @code{vm_protect} and
3049: @code{vm_inherit} may be used to change these properties. The allocated
3050: region is always zero-filled.
3051:
3052: The function returns @code{KERN_SUCCESS} if the memory was successfully
3053: allocated, @code{KERN_INVALID_ADDRESS} if an invalid address was
3054: specified and @code{KERN_NO_SPACE} if there was not enough space left to
3055: satisfy the request.
3056: @end deftypefun
3057:
3058:
3059: @node Memory Deallocation
3060: @section Memory Deallocation
3061:
3062: @deftypefun kern_return_t vm_deallocate (@w{vm_task_t @var{target_task}}, @w{vm_address_t @var{address}}, @w{vm_size_t @var{size}})
3063: @code{vm_deallocate} relinquishes access to a region of a @var{task}'s
3064: address space, causing further access to that memory to fail. This
3065: address range will be available for reallocation. @var{address} is the
3066: starting address, which will be rounded down to a page boundary.
3067: @var{size} is the number of bytes to deallocate, which will be rounded
3068: up to give a page boundary. Note, that because of the rounding to
3069: virtual page boundaries, more than @var{size} bytes may be deallocated.
3070: Use @code{vm_page_size} or @code{vm_statistics} to find out the current
3071: virtual page size.
3072:
1.1.1.2 root 3073: This call may be used to deallocate memory that was passed to a task in a
1.1 root 3074: message (via out of line data). In that case, the rounding should cause
3075: no trouble, since the region of memory was allocated as a set of pages.
3076:
3077: The @code{vm_deallocate} call affects only the task specified by the
3078: @var{target_task}. Other tasks which may have access to this memory may
3079: continue to reference it.
3080:
3081: The function returns @code{KERN_SUCCESS} if the memory was successfully
3082: deallocated and @code{KERN_INVALID_ADDRESS} if an invalid or
3083: non-allocated address was specified.
3084: @end deftypefun
3085:
3086:
3087: @node Data Transfer
3088: @section Data Transfer
3089:
3090: @deftypefun kern_return_t vm_read (@w{vm_task_t @var{target_task}}, @w{vm_address_t @var{address}}, @w{vm_size_t @var{size}}, @w{vm_offset_t *@var{data}}, @w{mach_msg_type_number_t *@var{data_count}})
3091: The function @code{vm_read} allows one task's virtual memory to be read
3092: by another task. The @var{target_task} is the task whose memory is to
3093: be read. @var{address} is the first address to be read and must be on a
3094: page boundary. @var{size} is the number of bytes of data to be read and
3095: must be an integral number of pages. @var{data} is the array of data
3096: copied from the given task, and @var{data_count} is the size of the data
3097: array in bytes (will be an integral number of pages).
3098:
3099: Note that the data array is returned in a newly allocated region; the
3100: task reading the data should @code{vm_deallocate} this region when it is
3101: done with the data.
3102:
3103: The function returns @code{KERN_SUCCESS} if the memory was successfully
3104: read, @code{KERN_INVALID_ADDRESS} if an invalid or non-allocated address
3105: was specified or there was not @var{size} bytes of data following the
3106: address, @code{KERN_INVALID_ARGUMENT} if the address does not start on a
3107: page boundary or the size is not an integral number of pages,
3108: @code{KERN_PROTECTION_FAILURE} if the address region in the target task
3109: is protected against reading and @code{KERN_NO_SPACE} if there was not
3110: enough room in the callers virtual memory to allocate space for the data
3111: to be returned.
3112: @end deftypefun
3113:
3114: @deftypefun kern_return_t vm_write (@w{vm_task_t @var{target_task}}, @w{vm_address_t @var{address}}, @w{vm_offset_t @var{data}}, @w{mach_msg_type_number_t @var{data_count}})
1.1.1.2 root 3115: The function @code{vm_write} allows a task to write to the virtual memory
1.1 root 3116: of @var{target_task}. @var{address} is the starting address in task to
3117: be affected. @var{data} is an array of bytes to be written, and
3118: @var{data_count} the size of the @var{data} array.
3119:
3120: The current implementation requires that @var{address}, @var{data} and
3121: @var{data_count} all be page-aligned. Otherwise,
3122: @code{KERN_INVALID_ARGUMENT} is returned.
3123:
3124: The function returns @code{KERN_SUCCESS} if the memory was successfully
3125: written, @code{KERN_INVALID_ADDRESS} if an invalid or non-allocated
3126: address was specified or there was not @var{data_count} bytes of
3127: allocated memory starting at @var{address} and
3128: @code{KERN_PROTECTION_FAILURE} if the address region in the target task
3129: is protected against writing.
3130: @end deftypefun
3131:
3132: @deftypefun kern_return_t vm_copy (@w{vm_task_t @var{target_task}}, @w{vm_address_t @var{source_address}}, @w{vm_size_t @var{count}}, @w{vm_offset_t @var{dest_address}})
3133: The function @code{vm_copy} causes the source memory range to be copied
3134: to the destination address. The source and destination memory ranges
3135: may overlap. The destination address range must already be allocated
3136: and writable; the source range must be readable.
3137:
3138: @code{vm_copy} is equivalent to @code{vm_read} followed by
3139: @code{vm_write}.
3140:
3141: The current implementation requires that @var{address}, @var{data} and
3142: @var{data_count} all be page-aligned. Otherwise,
3143: @code{KERN_INVALID_ARGUMENT} is returned.
3144:
3145: The function returns @code{KERN_SUCCESS} if the memory was successfully
3146: written, @code{KERN_INVALID_ADDRESS} if an invalid or non-allocated
3147: address was specified or there was insufficient memory allocated at one
3148: of the addresses and @code{KERN_PROTECTION_FAILURE} if the destination
3149: region was not writable or the source region was not readable.
3150: @end deftypefun
3151:
3152:
3153: @node Memory Attributes
3154: @section Memory Attributes
3155:
3156: @deftypefun kern_return_t vm_region (@w{vm_task_t @var{target_task}}, @w{vm_address_t *@var{address}}, @w{vm_size_t *@var{size}}, @w{vm_prot_t *@var{protection}}, @w{vm_prot_t *@var{max_protection}}, @w{vm_inherit_t *@var{inheritance}}, @w{boolean_t *@var{shared}}, @w{memory_object_name_t *@var{object_name}}, @w{vm_offset_t *@var{offset}})
3157: The function @code{vm_region} returns a description of the specified
3158: region of @var{target_task}'s virtual address space. @code{vm_region}
3159: begins at @var{address} and looks forward through memory until it comes
3160: to an allocated region. If address is within a region, then that region
3161: is used. Various bits of information about the region are returned. If
3162: @var{address} was not within a region, then @var{address} is set to the
3163: start of the first region which follows the incoming value. In this way
3164: an entire address space can be scanned.
3165:
3166: The @var{size} returned is the size of the located region in bytes.
3167: @var{protection} is the current protection of the region,
3168: @var{max_protection} is the maximum allowable protection for this
3169: region. @var{inheritance} is the inheritance attribute for this region.
3170: @var{shared} tells if the region is shared or not. The port
3171: @var{object_name} identifies the memory object associated with this
3172: region, and @var{offset} is the offset into the pager object that this
3173: region begins at.
3174: @c XXX cross ref pager_init
3175:
3176: The function returns @code{KERN_SUCCESS} if the memory region was
3177: successfully located and the information returned and @code{KERN_NO_SPACE} if
3178: there is no region at or above @var{address} in the specified task.
3179: @end deftypefun
3180:
3181: @deftypefun kern_return_t vm_protect (@w{vm_task_t @var{target_task}}, @w{vm_address_t @var{address}}, @w{vm_size_t @var{size}}, @w{boolean_t @var{set_maximum}}, @w{vm_prot_t @var{new_protection}})
3182: The function @code{vm_protect} sets the virtual memory access privileges
3183: for a range of allocated addresses in @var{target_task}'s virtual
3184: address space. The protection argument describes a combination of read,
3185: write, and execute accesses that should be @emph{permitted}.
3186:
3187: @var{address} is the starting address, which will be rounded down to a
3188: page boundary. @var{size} is the size in bytes of the region for which
3189: protection is to change, and will be rounded up to give a page boundary.
3190: If @var{set_maximum} is set, make the protection change apply to the
3191: maximum protection associated with this address range; otherwise, the
3192: current protection on this range is changed. If the maximum protection
3193: is reduced below the current protection, both will be changed to reflect
3194: the new maximum. @var{new_protection} is the new protection value for
3195: this region; a set of: @code{VM_PROT_READ}, @code{VM_PROT_WRITE},
3196: @code{VM_PROT_EXECUTE}.
3197:
3198: The enforcement of virtual memory protection is machine-dependent.
3199: Nominally read access requires @code{VM_PROT_READ} permission, write
3200: access requires @code{VM_PROT_WRITE} permission, and execute access
3201: requires @code{VM_PROT_EXECUTE} permission. However, some combinations
3202: of access rights may not be supported. In particular, the kernel
3203: interface allows write access to require @code{VM_PROT_READ} and
3204: @code{VM_PROT_WRITE} permission and execute access to require
3205: @code{VM_PROT_READ} permission.
3206:
3207: The function returns @code{KERN_SUCCESS} if the memory was successfully
3208: protected, @code{KERN_INVALID_ADDRESS} if an invalid or non-allocated
3209: address was specified and @code{KERN_PROTECTION_FAILURE} if an attempt
3210: was made to increase the current or maximum protection beyond the
3211: existing maximum protection value.
3212: @end deftypefun
3213:
3214: @deftypefun kern_return_t vm_inherit (@w{vm_task_t @var{target_task}}, @w{vm_address_t @var{address}}, @w{vm_size_t @var{size}}, @w{vm_inherit_t @var{new_inheritance}})
3215: The function @code{vm_inherit} specifies how a region of
3216: @var{target_task}'s address space is to be passed to child tasks at the
3217: time of task creation. Inheritance is an attribute of virtual pages, so
3218: @var{address} to start from will be rounded down to a page boundary and
1.1.1.2 root 3219: @var{size}, the size in bytes of the region for which inheritance is to
1.1 root 3220: change, will be rounded up to give a page boundary. How this memory is
3221: to be inherited in child tasks is specified by @var{new_inheritance}.
3222: Inheritance is specified by using one of these following three values:
3223:
3224: @table @code
3225: @item VM_INHERIT_SHARE
3226: Child tasks will share this memory with this task.
3227:
3228: @item VM_INHERIT_COPY
3229: Child tasks will receive a copy of this region.
3230:
3231: @item VM_INHERIT_NONE
3232: This region will be absent from child tasks.
3233: @end table
3234:
3235: Setting @code{vm_inherit} to @code{VM_INHERIT_SHARE} and forking a child
3236: task is the only way two Mach tasks can share physical memory. Remember
1.1.1.2 root 3237: that all the threads of a given task share all the same memory.
1.1 root 3238:
3239: The function returns @code{KERN_SUCCESS} if the memory inheritance was
3240: successfully set and @code{KERN_INVALID_ADDRESS} if an invalid or
3241: non-allocated address was specified.
3242: @end deftypefun
3243:
3244: @deftypefun kern_return_t vm_wire (@w{host_priv_t @var{host_priv}}, @w{vm_task_t @var{target_task}}, @w{vm_address_t @var{address}}, @w{vm_size_t @var{size}}, @w{vm_prot_t @var{access}})
3245: The function @code{vm_wire} allows privileged applications to control
3246: memory pageability. @var{host_priv} is the privileged host port for the
3247: host on which @var{target_task} resides. @var{address} is the starting
3248: address, which will be rounded down to a page boundary. @var{size} is
3249: the size in bytes of the region for which protection is to change, and
3250: will be rounded up to give a page boundary. @var{access} specifies the
3251: types of accesses that must not cause page faults.
3252:
3253: The semantics of a successful @code{vm_wire} operation are that memory
3254: in the specified range will not cause page faults for any accesses
3255: included in access. Data memory can be made non-pageable (wired) with a
3256: access argument of @code{VM_PROT_READ | VM_PROT_WRITE}. A special case
3257: is that @code{VM_PROT_NONE} makes the memory pageable.
3258:
3259: The function returns @code{KERN_SUCCESS} if the call succeeded,
3260: @code{KERN_INVALID_HOST} if @var{host_priv} was not the privileged host
3261: port, @code{KERN_INVALID_TASK} if @var{task} was not a valid task,
3262: @code{KERN_INVALID_VALUE} if @var{access} specified an invalid access
3263: mode, @code{KERN_FAILURE} if some memory in the specified range is not
3264: present or has an inappropriate protection value, and
3265: @code{KERN_INVALID_ARGUMENT} if unwiring (@var{access} is
3266: @code{VM_PROT_NONE}) and the memory is not already wired.
3267:
3268: The @code{vm_wire} call is actually an RPC to @var{host_priv}, normally
3269: a send right for a privileged host port, but potentially any send right.
3270: In addition to the normal diagnostic return codes from the call's server
3271: (normally the kernel), the call may return @code{mach_msg} return codes.
3272: @end deftypefun
3273:
3274: @deftypefun kern_return_t vm_machine_attribute (@w{vm_task_t @var{task}}, @w{vm_address_t @var{address}}, @w{vm_size_t @var{size}}, @w{vm_prot_t @var{access}}, @w{vm_machine_attribute_t @var{attribute}}, @w{vm_machine_attribute_val_t @var{value}})
3275: The function @code{vm_machine_attribute} specifies machine-specific
3276: attributes for a VM mapping, such as cachability, migrability,
3277: replicability. This is used on machines that allow the user control
3278: over the cache (this is the case for MIPS architectures) or placement of
3279: memory pages as in NUMA architectures (Non-Uniform Memory Access time)
3280: such as the IBM ACE multiprocessor.
3281:
3282: Machine-specific attributes can be consider additions to the
3283: machine-independent ones such as protection and inheritance, but they
3284: are not guaranteed to be supported by any given machine. Moreover,
3285: implementations of Mach on new architectures might find the need for new
3286: attribute types and or values besides the ones defined in the initial
3287: implementation.
3288:
3289: The types currently defined are
3290: @table @code
3291: @item MATTR_CACHE
3292: Controls caching of memory pages
3293:
3294: @item MATTR_MIGRATE
3295: Controls migrability of memory pages
3296:
3297: @item MATTR_REPLICATE
3298: Controls replication of memory pages
3299: @end table
3300:
3301: Corresponding values, and meaning of a specific call to
3302: @code{vm_machine_attribute}
3303: @table @code
3304: @item MATTR_VAL_ON
3305: Enables the attribute. Being enabled is the default value for any
3306: applicable attribute.
3307:
3308: @item MATTR_VAL_OFF
3309: Disables the attribute, making memory non-cached, or non-migratable, or
3310: non-replicatable.
3311:
3312: @item MATTR_VAL_GET
3313: Returns the current value of the attribute for the memory segment. If
3314: the attribute does not apply uniformly to the given range the value
3315: returned applies to the initial portion of the segment only.
3316:
3317: @item MATTR_VAL_CACHE_FLUSH
3318: Flush the memory pages from the Cache. The size value in this case
3319: might be meaningful even if not a multiple of the page size, depending
3320: on the implementation.
3321:
3322: @item MATTR_VAL_ICACHE_FLUSH
3323: Same as above, applied to the Instruction Cache alone.
3324:
3325: @item MATTR_VAL_DCACHE_FLUSH
3326: Same as above, applied to the Data Cache alone.
3327: @end table
3328:
3329: The function returns @code{KERN_SUCCESS} if call succeeded, and
3330: @code{KERN_INVALID_ARGUMENT} if @var{task} is not a task, or
3331: @var{address} and @var{size} do not define a valid address range in
3332: task, or @var{attribute} is not a valid attribute type, or it is not
3333: implemented, or @var{value} is not a permissible value for attribute.
3334: @end deftypefun
3335:
3336:
3337: @node Mapping Memory Objects
3338: @section Mapping Memory Objects
3339:
3340: @deftypefun kern_return_t vm_map (@w{vm_task_t @var{target_task}}, @w{vm_address_t *@var{address}}, @w{vm_size_t @var{size}}, @w{vm_address_t @var{mask}}, @w{boolean_t @var{anywhere}}, @w{memory_object_t @var{memory_object}}, @w{vm_offset_t @var{offset}}, @w{boolean_t @var{copy}}, @w{vm_prot_t @var{cur_protection}}, @w{vm_prot_t @var{max_protection}}, @w{vm_inherit_t @var{inheritance}})
3341: The function @code{vm_map} maps a region of virtual memory at the
3342: specified address, for which data is to be supplied by the given memory
3343: object, starting at the given offset within that object. In addition to
3344: the arguments used in @code{vm_allocate}, the @code{vm_map} call allows
3345: the specification of an address alignment parameter, and of the initial
3346: protection and inheritance values.
3347: @c XXX See the descriptions of vm_allocate, vm_protect , and vm_inherit
3348:
3349: If the memory object in question is not currently in use, the kernel
3350: will perform a @code{memory_object_init} call at this time. If the copy
3351: parameter is asserted, the specified region of the memory object will be
3352: copied to this address space; changes made to this object by other tasks
3353: will not be visible in this mapping, and changes made in this mapping
3354: will not be visible to others (or returned to the memory object).
3355:
3356: The @code{vm_map} call returns once the mapping is established.
3357: Completion of the call does not require any action on the part of the
3358: memory manager.
3359:
3360: Warning: Only memory objects that are provided by bona fide memory
3361: managers should be used in the @code{vm_map} call. A memory manager
3362: must implement the memory object interface described elsewhere in this
3363: manual. If other ports are used, a thread that accesses the mapped
3364: virtual memory may become permanently hung or may receive a memory
3365: exception.
3366:
3367: @var{target_task} is the task to be affected. The starting address is
3368: @var{address}. If the @var{anywhere} option is used, this address is
1.1.1.3 ! root 3369: used as a starting hint. The address actually allocated will be returned in
1.1 root 3370: @var{address}. @var{size} is the number of bytes to allocate (rounded by
3371: the system in a machine dependent way). The alignment restriction is
3372: specified by @var{mask}. Bits asserted in this mask must not be
3373: asserted in the address returned. If @var{anywhere} is set, the kernel
3374: should find and allocate any region of the specified size, and return
3375: the address of the resulting region in @var{address}.
3376:
3377: @var{memory_object} is the port that represents the memory object: used
3378: by user tasks in @code{vm_map}; used by the make requests for data or
3379: other management actions. If this port is @code{MEMORY_OBJECT_NULL},
3380: then zero-filled memory is allocated instead. Within a memory object,
1.1.1.2 root 3381: @var{offset} specifies an offset in bytes. This must be page aligned.
1.1 root 3382: If @var{copy} is set, the range of the memory object should be copied to
3383: the target task, rather than mapped read-write.
3384:
3385: The function returns @code{KERN_SUCCESS} if the object is mapped,
3386: @code{KERN_NO_SPACE} if no unused region of the task's virtual address
3387: space that meets the address, size, and alignment criteria could be
3388: found, and @code{KERN_INVALID_ARGUMENT} if an invalid argument was provided.
3389: @end deftypefun
3390:
3391:
3392: @node Memory Statistics
3393: @section Memory Statistics
3394:
3395: @deftp {Data type} vm_statistics_data_t
3396: This structure is returned in @var{vm_stats} by the @code{vm_statistics}
3397: function and provides virtual memory statistics for the system. It has
3398: the following members:
3399:
3400: @table @code
3401: @item long pagesize
3402: The page size in bytes.
3403:
3404: @item long free_count
3405: The number of free pages.
3406:
3407: @item long active_count
3408: The umber of active pages.
3409:
3410: @item long inactive_count
3411: The number of inactive pages.
3412:
3413: @item long wire_count
3414: The number of pages wired down.
3415:
3416: @item long zero_fill_count
3417: The number of zero filled pages.
3418:
3419: @item long reactivations
3420: The number of reactivated pages.
3421:
3422: @item long pageins
3423: The number of pageins.
3424:
3425: @item long pageouts
3426: The number of pageouts.
3427:
3428: @item long faults
3429: The number of faults.
3430:
3431: @item long cow_faults
3432: The number of copy-on-writes.
3433:
3434: @item long lookups
3435: The number of object cache lookups.
3436:
3437: @item long hits
3438: The number of object cache hits.
3439: @end table
3440: @end deftp
3441:
3442: @deftypefun kern_return_t vm_statistics (@w{vm_task_t @var{target_task}}, @w{vm_statistics_data_t *@var{vm_stats}})
3443: The function @code{vm_statistics} returns the statistics about the
3444: kernel's use of virtual memory since the kernel was booted.
3445: @code{pagesize} can also be found as a global variable
3446: @code{vm_page_size} which is set at task initialization and remains
3447: constant for the life of the task.
3448: @end deftypefun
3449:
3450:
3451: @node External Memory Management
3452: @chapter External Memory Management
3453:
3454: @menu
3455: * Memory Object Server:: The basics of external memory management.
3456: * Memory Object Creation:: How new memory objects are created.
3457: * Memory Object Termination:: How memory objects are terminated.
3458: * Memory Objects and Data:: Data transfer to and from memory objects.
3459: * Memory Object Locking:: How memory objects are locked.
3460: * Memory Object Attributes:: Manipulating attributes of memory objects.
3461: * Default Memory Manager:: Setting and using the default memory manager.
3462: @end menu
3463:
3464:
3465: @node Memory Object Server
3466: @section Memory Object Server
3467:
3468: @deftypefun boolean_t memory_object_server (@w{msg_header_t *@var{in_msg}}, @w{msg_header_t *@var{out_msg}})
3469: @deftypefunx boolean_t memory_object_default_server (@w{msg_header_t *@var{in_msg}}, @w{msg_header_t *@var{out_msg}})
3470: @deftypefunx boolean_t seqnos_memory_object_server (@w{msg_header_t *@var{in_msg}}, @w{msg_header_t *@var{out_msg}})
3471: @deftypefunx boolean_t seqnos_memory_object_default_server (@w{msg_header_t *@var{in_msg}}, @w{msg_header_t *@var{out_msg}})
3472: A memory manager is a server task that responds to specific messages
3473: from the kernel in order to handle memory management functions for the
3474: kernel.
3475:
3476: In order to isolate the memory manager from the specifics of message
3477: formatting, the remote procedure call generator produces a procedure,
3478: @code{memory_object_server}, to handle a received message. This
3479: function does all necessary argument handling, and actually calls one of
3480: the following functions: @code{memory_object_init},
3481: @code{memory_object_data_write}, @code{memory_object_data_return},
3482: @code{memory_object_data_request}, @code{memory_object_data_unlock},
3483: @code{memory_object_lock_completed}, @code{memory_object_copy},
3484: @code{memory_object_terminate}. The @strong{default memory manager} may
3485: get two additional requests from the kernel: @code{memory_object_create}
3486: and @code{memory_object_data_initialize}. The remote procedure call
3487: generator produces a procedure @code{memory_object_default_server} to
3488: handle those functions specific to the default memory manager.
3489:
3490: The @code{seqnos_memory_object_server} and
3491: @code{seqnos_memory_object_default_server} differ from
3492: @code{memory_object_server} and @code{memory_object_default_server} in
3493: that they supply message sequence numbers to the server interfaces.
3494: They call the @code{seqnos_memory_object_*} functions, which complement
3495: the @code{memory_object_*} set of functions.
3496:
3497: The return value from the @code{memory_object_server} function indicates
3498: that the message was appropriate to the memory management interface
3499: (returning @code{TRUE}), or that it could not handle this message
3500: (returning @code{FALSE}).
3501:
3502: The @var{in_msg} argument is the message that has been received from the
3503: kernel. The @var{out_msg} is a reply message, but this is not used for
3504: this server.
3505:
3506: The function returns @code{TRUE} to indicate that the message in
3507: question was applicable to this interface, and that the appropriate
3508: routine was called to interpret the message. It returns @code{FALSE} to
3509: indicate that the message did not apply to this interface, and that no
3510: other action was taken.
3511: @end deftypefun
3512:
3513:
3514: @node Memory Object Creation
3515: @section Memory Object Creation
3516:
3517: @deftypefun kern_return_t memory_object_init (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{memory_object_name_t @var{memory_object_name}}, @w{vm_size_t @var{memory_object_page_size}})
3518: @deftypefunx kern_return_t seqnos_memory_object_init (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{memory_object_name_t @var{memory_object_name}}, @w{vm_size_t @var{memory_object_page_size}})
3519: The function @code{memory_object_init} serves as a notification that the
3520: kernel has been asked to map the given memory object into a task's
3521: virtual address space. Additionally, it provides a port on which the
3522: memory manager may issue cache management requests, and a port which the
3523: kernel will use to name this data region. In the event that different
3524: each will perform a @code{memory_object_init} call with new request and
3525: name ports. The virtual page size that is used by the calling kernel is
3526: included for planning purposes.
3527:
3528: When the memory manager is prepared to accept requests for data for this
3529: object, it must call @code{memory_object_ready} with the attribute.
3530: Otherwise the kernel will not process requests on this object. To
3531: reject all mappings of this object, the memory manager may use
3532: @code{memory_object_destroy}.
3533:
3534: The argument @var{memory_object} is the port that represents the memory
3535: object data, as supplied to the kernel in a @code{vm_map} call.
3536: @var{memory_control} is the request port to which a response is
3537: requested. (In the event that a memory object has been supplied to more
3538: than one the kernel that has made the request.)
3539: @var{memory_object_name} is a port used by the kernel to refer to the
1.1.1.2 root 3540: memory object data in response to @code{vm_region} calls.
1.1 root 3541: @code{memory_object_page_size} is the page size to be used by this
3542: kernel. All data sizes in calls involving this kernel must be an
3543: integral multiple of the page size. Note that different kernels,
3544: indicated by a different @code{memory_control}, may have different page
3545: sizes.
3546:
3547: The function should return @code{KERN_SUCCESS}, but since this routine
3548: is called by the kernel, which does not wait for a reply message, this
3549: value is ignored.
3550: @end deftypefun
3551:
3552: @deftypefun kern_return_t memory_object_ready (@w{memory_object_control_t @var{memory_control}}, @w{boolean_t @var{may_cache_object}}, @w{memory_object_copy_strategy_t @var{copy_strategy}})
3553: The function @code{memory_object_ready} informs the kernel that the
3554: memory manager is ready to receive data or unlock requests on behalf of
3555: the clients. The argument @var{memory_control} is the port, provided by
3556: the kernel in a @code{memory_object_init} call, to which cache
3557: management requests may be issued. If @var{may_cache_object} is set,
3558: the kernel may keep data associated with this memory object, even after
3559: virtual memory references to it are gone.
3560:
3561: @var{copy_strategy} tells how the kernel should copy regions of the
3562: associated memory object. There are three possible caching strategies:
3563: @code{MEMORY_OBJECT_COPY_NONE} which specifies that nothing special
3564: should be done when data in the object is copied;
3565: @code{MEMORY_OBJECT_COPY_CALL} which specifies that the memory manager
3566: should be notified via a @code{memory_object_copy} call before any part
3567: of the object is copied; and @code{MEMORY_OBJECT_COPY_DELAY} which
3568: guarantees that the memory manager does not externally modify the data
3569: so that the kernel can use its normal copy-on-write algorithms.
3570: @code{MEMORY_OBJECT_COPY_DELAY} is the strategy most commonly used.
3571:
3572: This routine does not receive a reply message (and consequently has no
3573: return value), so only message transmission errors apply.
3574: @end deftypefun
3575:
3576:
3577: @node Memory Object Termination
3578: @section Memory Object Termination
3579:
3580: @deftypefun kern_return_t memory_object_terminate (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{memory_object_name_t @var{memory_object_name}})
3581: @deftypefunx kern_return_t seqnos_memory_object_terminate (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{memory_object_name_t @var{memory_object_name}})
3582: The function @code{memory_object_terminate} indicates that the kernel
3583: has completed its use of the given memory object. All rights to the
3584: memory object control and name ports are included, so that the memory
3585: manager can destroy them (using @code{mach_port_deallocate}) after doing
3586: appropriate bookkeeping. The kernel will terminate a memory object only
3587: after all address space mappings of that memory object have been
3588: deallocated, or upon explicit request by the memory manager.
3589:
3590: The argument @var{memory_object} is the port that represents the memory
3591: object data, as supplied to the kernel in a @code{vm_map} call.
3592: @var{memory_control} is the request port to which a response is
3593: requested. (In the event that a memory object has been supplied to more
3594: than one the kernel that has made the request.)
3595: @var{memory_object_name} is a port used by the kernel to refer to the
1.1.1.2 root 3596: memory object data in response to @code{vm_region} calls.
1.1 root 3597:
3598: The function should return @code{KERN_SUCCESS}, but since this routine
3599: is called by the kernel, which does not wait for a reply message, this
3600: value is ignored.
3601: @end deftypefun
3602:
3603: @deftypefun kern_return_t memory_object_destroy (@w{memory_object_control_t @var{memory_control}}, @w{kern_return_t @var{reason}})
3604: The function @code{memory_object_destroy} tells the kernel to shut down
3605: the memory object. As a result of this call the kernel will no longer
3606: support paging activity or any @code{memory_object} calls on this
3607: object, and all rights to the memory object port, the memory control
3608: port and the memory name port will be returned to the memory manager in
3609: a memory_object_terminate call. If the memory manager is concerned that
3610: any modified cached data be returned to it before the object is
3611: terminated, it should call @code{memory_object_lock_request} with
3612: @var{should_flush} set and a lock value of @code{VM_PROT_WRITE} before
3613: making this call.
3614:
3615: The argument @var{memory_control} is the port, provided by the kernel in
3616: a @code{memory_object_init} call, to which cache management requests may
3617: be issued. @var{reason} is an error code indicating why the object
3618: must be destroyed.
1.1.1.2 root 3619: @c The error code is currently ignored.
1.1 root 3620:
3621: This routine does not receive a reply message (and consequently has no
3622: return value), so only message transmission errors apply.
3623: @end deftypefun
3624:
3625:
3626: @node Memory Objects and Data
3627: @section Memory Objects and Data
3628:
3629: @deftypefun kern_return_t memory_object_data_return (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}}, @w{boolean_t @var{dirty}}, @w{boolean_t @var{kernel_copy}})
3630: @deftypefunx kern_return_t seqnos_memory_object_data_return (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}}, @w{boolean_t @var{dirty}}, @w{boolean_t @var{kernel_copy}})
3631: The function @code{memory_object_data_return} provides the memory
3632: manager with data that has been modified while cached in physical
3633: memory. Once the memory manager no longer needs this data (e.g., it has
3634: been written to another storage medium), it should be deallocated using
3635: @code{vm_deallocate}.
3636:
3637: The argument @var{memory_object} is the port that represents the memory
3638: object data, as supplied to the kernel in a @code{vm_map} call.
3639: @var{memory_control} is the request port to which a response is
3640: requested. (In the event that a memory object has been supplied to more
3641: than one the kernel that has made the request.) @var{offset} is the
3642: offset within a memory object to which this call refers. This will be
3643: page aligned. @var{data} is the data which has been modified while
3644: cached in physical memory. @var{data_count} is the amount of data to be
3645: written, in bytes. This will be an integral number of memory object
3646: pages.
3647:
3648: The kernel will also use this call to return precious pages. If an
3649: unmodified precious age is returned, @var{dirty} is set to @code{FALSE},
3650: otherwise it is @code{TRUE}. If @var{kernel_copy} is @code{TRUE}, the
3651: kernel kept a copy of the page. Precious data remains precious if the
3652: kernel keeps a copy. The indication that the kernel kept a copy is only
3653: a hint if the data is not precious; the cleaned copy may be discarded
3654: without further notifying the manager.
3655:
3656: The function should return @code{KERN_SUCCESS}, but since this routine
3657: is called by the kernel, which does not wait for a reply message, this
3658: value is ignored.
3659: @end deftypefun
3660:
3661: @deftypefun kern_return_t memory_object_data_request (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{length}}, @w{vm_prot_t @var{desired_access}})
3662: @deftypefunx kern_return_t seqnos_memory_object_data_request (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{length}}, @w{vm_prot_t @var{desired_access}})
3663: The function @code{memory_object_data_request} is a request for data
3664: from the specified memory object, for at least the access specified.
3665: The memory manager is expected to return at least the specified data,
3666: with as much access as it can allow, using
3667: @code{memory_object_data_supply}. If the memory manager is unable to
3668: provide the data (for example, because of a hardware error), it may use
3669: the @code{memory_object_data_error} call. The
3670: @code{memory_object_data_unavailable} call may be used to tell the
3671: kernel to supply zero-filled memory for this region.
3672:
3673: The argument @var{memory_object} is the port that represents the memory
3674: object data, as supplied to the kernel in a @code{vm_map} call.
3675: @var{memory_control} is the request port to which a response is
3676: requested. (In the event that a memory object has been supplied to more
3677: than one the kernel that has made the request.) @var{offset} is the
3678: offset within a memory object to which this call refers. This will be
3679: page aligned. @var{length} is the number of bytes of data, starting at
3680: @var{offset}, to which this call refers. This will be an integral
3681: number of memory object pages. @var{desired_access} is a protection
3682: value describing the memory access modes which must be permitted on the
3683: specified cached data. One or more of: @code{VM_PROT_READ},
3684: @code{VM_PROT_WRITE} or @code{VM_PROT_EXECUTE}.
3685:
3686: The function should return @code{KERN_SUCCESS}, but since this routine
3687: is called by the kernel, which does not wait for a reply message, this
3688: value is ignored.
3689: @end deftypefun
3690:
3691: @deftypefun kern_return_t memory_object_data_supply (@w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}}, @w{vm_prot_t @var{lock_value}}, @w{boolean_t @var{precious}}, @w{mach_port_t @var{reply}})
3692: The function @code{memory_object_data_supply} supplies the kernel with
3693: data for the specified memory object. Ordinarily, memory managers
1.1.1.2 root 3694: should only provide data in response to @code{memory_object_data_request}
1.1 root 3695: calls from the kernel (but they may provide data in advance as desired).
3696: When data already held by this kernel is provided again, the new data is
3697: ignored. The kernel may not provide any data (or protection)
3698: consistency among pages with different virtual page alignments within
3699: the same object.
3700:
3701: The argument @var{memory_control} is the port, provided by the kernel in
3702: a @code{memory_object_init} call, to which cache management requests may
3703: be issued. @var{offset} is an offset within a memory object in bytes.
3704: This must be page aligned. @var{data} is the data that is being
3705: provided to the kernel. This is a pointer to the data.
3706: @var{data_count} is the amount of data to be provided. Only whole
3707: virtual pages of data can be accepted; partial pages will be discarded.
3708:
3709: @var{lock_value} is a protection value indicating those forms of access
3710: that should @strong{not} be permitted to the specified cached data. The
3711: lock values must be one or more of the set: @code{VM_PROT_NONE},
3712: @code{VM_PROT_READ}, @code{VM_PROT_WRITE}, @code{VM_PROT_EXECUTE} and
3713: @code{VM_PROT_ALL} as defined in @file{mach/vm_prot.h}.
3714:
3715: If @var{precious} is @code{FALSE}, the kernel treats the data as a
3716: temporary and may throw it away if it hasn't been changed. If the
3717: @var{precious} value is @code{TRUE}, the kernel treats its copy as a
3718: data repository and promises to return it to the manager; the manager
3719: may tell the kernel to throw it away instead by flushing and not
3720: cleaning the data (see @code{memory_object_lock_request}).
3721:
3722: If @var{reply_to} is not @code{MACH_PORT_NULL}, the kernel will send a
3723: completion message to the provided port (see
3724: @code{memory_object_supply_completed}).
3725:
3726: This routine does not receive a reply message (and consequently has no
3727: return value), so only message transmission errors apply.
3728: @end deftypefun
3729:
3730: @deftypefun kern_return_t memory_object_supply_completed (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{length}}, @w{kern_return_t @var{result}}, @w{vm_offset_t @var{error_offset}})
3731: @deftypefunx kern_return_t seqnos_memory_object_supply_completed (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{length}}, @w{kern_return_t @var{result}}, @w{vm_offset_t @var{error_offset}})
3732: The function @code{memory_object_supply_completed} indicates that a
3733: previous @code{memory_object_data_supply} has been completed. Note that
3734: this call is made on whatever port was specified in the
3735: @code{memory_object_data_supply} call; that port need not be the memory
3736: object port itself. No reply is expected after this call.
3737:
3738: The argument @var{memory_object} is the port that represents the memory
3739: object data, as supplied to the kernel in a @code{vm_map} call.
3740: @var{memory_control} is the request port to which a response is
3741: requested. (In the event that a memory object has been supplied to more
3742: than one the kernel that has made the request.) @var{offset} is the
3743: offset within a memory object to which this call refers. @var{length}
3744: is the length of the data covered by the lock request. The @var{result}
3745: parameter indicates what happened during the supply. If it is not
3746: @code{KERN_SUCCESS}, then @var{error_offset} identifies the first offset
3747: at which a problem occurred. The pagein operation stopped at this
3748: point. Note that the only failures reported by this mechanism are
3749: @code{KERN_MEMORY_PRESENT}. All other failures (invalid argument, error
3750: on pagein of supplied data in manager's address space) cause the entire
3751: operation to fail.
3752:
3753:
3754: @end deftypefun
3755:
3756: @deftypefun kern_return_t memory_object_data_error (@w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{size}}, @w{kern_return_t @var{reason}})
3757: The function @code{memory_object_data_error} indicates that the memory
3758: manager cannot return the data requested for the given region,
3759: specifying a reason for the error. This is typically used when a
3760: hardware error is encountered.
3761:
3762: The argument @var{memory_control} is the port, provided by the kernel in
3763: a @code{memory_object_init} call, to which cache management requests may
3764: be issued. @var{offset} is an offset within a memory object in bytes.
3765: This must be page aligned. @var{data} is the data that is being
3766: provided to the kernel. This is a pointer to the data. @var{size} is
3767: the amount of cached data (starting at @var{offset}) to be handled.
3768: This must be an integral number of the memory object page size.
1.1.1.2 root 3769: @var{reason} is an error code indicating what type of error occurred.
3770: @c The error code is currently ignored.
1.1 root 3771:
3772: This routine does not receive a reply message (and consequently has no
3773: return value), so only message transmission errors apply.
3774: @end deftypefun
3775:
3776: @deftypefun kern_return_t memory_object_data_unavailable (@w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{size}}, @w{kern_return_t @var{reason}})
3777: The function @code{memory_object_data_unavailable} indicates that the
3778: memory object does not have data for the given region and that the
3779: kernel should provide the data for this range. The memory manager may
3780: use this call in three different situations.
3781:
3782: @enumerate
3783: @item
3784: The object was created by @code{memory_object_create} and the kernel has
3785: not yet provided data for this range (either via a
3786: @code{memory_object_data_initialize}, @code{memory_object_data_write} or
3787: a @code{memory_object_data_return} for the object.
3788:
3789: @item
3790: The object was created by an @code{memory_object_data_copy} and the
3791: kernel should copy this region from the original memory object.
3792:
3793: @item
3794: The object is a normal user-created memory object and the kernel should
3795: supply unlocked zero-filled pages for the range.
3796: @end enumerate
3797:
3798: The argument @var{memory_control} is the port, provided by the kernel in
3799: a @code{memory_object_init} call, to which cache management requests may
3800: be issued. @var{offset} is an offset within a memory object, in bytes.
3801: This must be page aligned. @var{size} is the amount of cached data
3802: (starting at @var{offset}) to be handled. This must be an integral
3803: number of the memory object page size.
3804:
3805: This routine does not receive a reply message (and consequently has no
3806: return value), so only message transmission errors apply.
3807: @end deftypefun
3808:
3809: @deftypefun kern_return_t memory_object_copy (@w{memory_object_t @var{old_memory_object}}, @w{memory_object_control_t @var{old_memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{length}}, @w{memory_object_t @var{new_memory_object}})
3810: @deftypefunx kern_return_t seqnos_memory_object_copy (@w{memory_object_t @var{old_memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{old_memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{length}}, @w{memory_object_t @var{new_memory_object}})
3811: The function @code{memory_object_copy} indicates that a copy has been
3812: made of the specified range of the given original memory object. This
3813: call includes only the new memory object itself; a
3814: @code{memory_object_init} call will be made on the new memory object
3815: after the currently cached pages of the original object are prepared.
3816: After the memory manager receives the init call, it must reply with the
3817: @code{memory_object_ready} call to assert the "ready" attribute. The
3818: kernel will use the new memory object, control and name ports to refer
3819: to the new copy.
3820:
3821: This call is made when the original memory object had the caching
3822: parameter set to @code{MEMORY_OBJECT_COPY_CALL} and a user of the object
3823: has asked the kernel to copy it.
3824:
3825: Cached pages from the original memory object at the time of the copy
3826: operation are handled as follows: Readable pages may be silently copied
3827: to the new memory object (with all access permissions). Pages not
3828: copied are locked to prevent write access.
3829:
3830: The new memory object is @strong{temporary}, meaning that the memory
3831: manager should not change its contents or allow the memory object to be
3832: mapped in another client. The memory manager may use the
3833: @code{memory_object_data_unavailable} call to indicate that the
3834: appropriate pages of the original memory object may be used to fulfill
3835: the data request.
3836:
3837: The argument @var{old_memory_object} is the port that represents the old
3838: memory object data. @var{old_memory_control} is the kernel port for the
3839: old object. @var{offset} is the offset within a memory object to which
3840: this call refers. This will be page aligned. @var{length} is the
3841: number of bytes of data, starting at @var{offset}, to which this call
3842: refers. This will be an integral number of memory object pages.
3843: @var{new_memory_object} is a new memory object created by the kernel;
3844: see synopsis for further description. Note that all port rights
3845: (including receive rights) are included for the new memory object.
3846:
3847: The function should return @code{KERN_SUCCESS}, but since this routine
3848: is called by the kernel, which does not wait for a reply message, this
3849: value is ignored.
3850: @end deftypefun
3851:
1.1.1.2 root 3852: The remaining interfaces in this section are obsolete.
1.1 root 3853:
3854: @deftypefun kern_return_t memory_object_data_write (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}})
3855: @deftypefunx kern_return_t seqnos_memory_object_data_write (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}})
3856: The function @code{memory_object_data_write} provides the memory manager
3857: with data that has been modified while cached in physical memory. It is the old form of @code{memory_object_data_return}. Once
3858: the memory manager no longer needs this data (e.g., it has been written
3859: to another storage medium), it should be deallocated using
3860: @code{vm_deallocate}.
3861:
3862: The argument @var{memory_object} is the port that represents the memory
3863: object data, as supplied to the kernel in a @code{vm_map} call.
3864: @var{memory_control} is the request port to which a response is
3865: requested. (In the event that a memory object has been supplied to more
3866: than one the kernel that has made the request.) @var{offset} is the
3867: offset within a memory object to which this call refers. This will be
3868: page aligned. @var{data} is the data which has been modified while
3869: cached in physical memory. @var{data_count} is the amount of data to be
3870: written, in bytes. This will be an integral number of memory object
3871: pages.
3872:
3873: The function should return @code{KERN_SUCCESS}, but since this routine
3874: is called by the kernel, which does not wait for a reply message, this
3875: value is ignored.
3876: @end deftypefun
3877:
3878: @deftypefun kern_return_t memory_object_data_provided (@w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}}, @w{vm_prot_t @var{lock_value}})
3879: The function @code{memory_object_data_provided} supplies the kernel with
3880: data for the specified memory object. It is the old form of
3881: @code{memory_object_data_supply}. Ordinarily, memory managers should
1.1.1.2 root 3882: only provide data in response to @code{memory_object_data_request} calls
1.1 root 3883: from the kernel. The @var{lock_value} specifies what type of access
3884: will not be allowed to the data range. The lock values must be one or
3885: more of the set: @code{VM_PROT_NONE}, @code{VM_PROT_READ},
3886: @code{VM_PROT_WRITE}, @code{VM_PROT_EXECUTE} and @code{VM_PROT_ALL} as
3887: defined in @file{mach/vm_prot.h}.
3888:
3889: The argument @var{memory_control} is the port, provided by the kernel in
3890: a @code{memory_object_init} call, to which cache management requests may
3891: be issued. @var{offset} is an offset within a memory object in bytes.
3892: This must be page aligned. @var{data} is the data that is being
3893: provided to the kernel. This is a pointer to the data.
3894: @var{data_count} is the amount of data to be provided. This must be an
3895: integral number of memory object pages. @var{lock_value} is a
3896: protection value indicating those forms of access that should
3897: @strong{not} be permitted to the specified cached data.
3898:
3899: This routine does not receive a reply message (and consequently has no
3900: return value), so only message transmission errors apply.
3901: @end deftypefun
3902:
3903:
3904: @node Memory Object Locking
3905: @section Memory Object Locking
3906:
3907: @deftypefun kern_return_t memory_object_lock_request (@w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{size}}, @w{memory_object_return_t @var{should_clean}}, @w{boolean_t @var{should_flush}}, @w{vm_prot_t @var{lock_value}}, @w{mach_port_t @var{reply_to}})
3908: The function @code{memory_object_lock_request} allows a memory manager
3909: to make cache management requests. As specified in arguments to the
3910: call, the kernel will:
3911: @itemize
3912: @item
3913: clean (i.e., write back using @code{memory_object_data_supply} or
3914: @code{memory_object_data_write}) any cached data which has been modified
3915: since the last time it was written
3916:
3917: @item
3918: flush (i.e., remove any uses of) that data from memory
3919:
3920: @item
3921: lock (i.e., prohibit the specified uses of) the cached data
3922: @end itemize
3923:
3924: Locks applied to cached data are not cumulative; new lock values
3925: override previous ones. Thus, data may also be unlocked using this
3926: primitive. The lock values must be one or more of the following values:
3927: @code{VM_PROT_NONE}, @code{VM_PROT_READ}, @code{VM_PROT_WRITE},
3928: @code{VM_PROT_EXECUTE} and @code{VM_PROT_ALL} as defined in
3929: @file{mach/vm_prot.h}.
3930:
3931: Only data which is cached at the time of this call is affected. When a
3932: running thread requires a prohibited access to cached data, the kernel
3933: will issue a @code{memory_object_data_unlock} call specifying the forms
3934: of access required.
3935:
3936: Once all of the actions requested by this call have been completed, the
3937: kernel issues a @code{memory_object_lock_completed} call on the
3938: specified reply port.
3939:
3940: The argument @var{memory_control} is the port, provided by the kernel in
3941: a @code{memory_object_init} call, to which cache management requests may
3942: be issued. @var{offset} is an offset within a memory object, in bytes.
3943: This must be page aligned. @var{size} is the amount of cached data
3944: (starting at @var{offset}) to be handled. This must be an integral
3945: number of the memory object page size. If @var{should_clean} is set,
3946: modified data should be written back to the memory manager. If
3947: @var{should_flush} is set, the specified cached data should be
3948: invalidated, and all uses of that data should be revoked.
3949: @var{lock_value} is a protection value indicating those forms of access
3950: that should @strong{not} be permitted to the specified cached data.
1.1.1.2 root 3951: @var{reply_to} is a port on which a @code{memory_object_lock_completed}
1.1 root 3952: call should be issued, or @code{MACH_PORT_NULL} if no acknowledgement is
3953: desired.
3954:
3955: This routine does not receive a reply message (and consequently has no
3956: return value), so only message transmission errors apply.
3957: @end deftypefun
3958:
3959: @deftypefun kern_return_t memory_object_lock_completed (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{length}})
3960: @deftypefunx kern_return_t seqnos_memory_object_lock_completed (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{length}})
3961: The function @code{memory_object_lock_completed} indicates that a
3962: previous @code{memory_object_lock_request} has been completed. Note
3963: that this call is made on whatever port was specified in the
3964: @code{memory_object_lock_request} call; that port need not be the memory
3965: object port itself. No reply is expected after this call.
3966:
3967: The argument @var{memory_object} is the port that represents the memory
3968: object data, as supplied to the kernel in a @code{vm_map} call.
3969: @var{memory_control} is the request port to which a response is
3970: requested. (In the event that a memory object has been supplied to more
3971: than one the kernel that has made the request.) @var{offset} is the
3972: offset within a memory object to which this call refers. @var{length}
3973: is the length of the data covered by the lock request.
3974:
3975: The function should return @code{KERN_SUCCESS}, but since this routine
3976: is called by the kernel, which does not wait for a reply message, this
3977: value is ignored.
3978: @end deftypefun
3979:
3980: @deftypefun kern_return_t memory_object_data_unlock (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{length}}, @w{vm_prot_t @var{desired_access}})
3981: @deftypefunx kern_return_t seqnos_memory_object_data_unlock (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{length}}, @w{vm_prot_t @var{desired_access}})
3982: The function @code{memory_object_data_unlock} is a request that the
3983: memory manager permit at least the desired access to the specified data
3984: cached by the kernel. A call to @code{memory_object_lock_request} is
3985: expected in response.
3986:
3987: The argument @var{memory_object} is the port that represents the memory
3988: object data, as supplied to the kernel in a @code{vm_map} call.
3989: @var{memory_control} is the request port to which a response is
3990: requested. (In the event that a memory object has been supplied to more
3991: than one the kernel that has made the request.) @var{offset} is the
3992: offset within a memory object to which this call refers. This will be
3993: page aligned. @var{length} is the number of bytes of data, starting at
3994: @var{offset}, to which this call refers. This will be an integral
3995: number of memory object pages. @var{desired_access} a protection value
3996: describing the memory access modes which must be permitted on the
3997: specified cached data. One or more of: @code{VM_PROT_READ},
3998: @code{VM_PROT_WRITE} or @code{VM_PROT_EXECUTE}.
3999:
4000: The function should return @code{KERN_SUCCESS}, but since this routine
4001: is called by the kernel, which does not wait for a reply message, this
4002: value is ignored.
4003: @end deftypefun
4004:
4005:
4006: @node Memory Object Attributes
4007: @section Memory Object Attributes
4008:
4009: @deftypefun kern_return_t memory_object_get_attributes (@w{memory_object_control_t @var{memory_control}}, @w{boolean_t *@var{object_ready}}, @w{boolean_t *@var{may_cache_object}}, @w{memory_object_copy_strategy_t *@var{copy_strategy}})
4010: The function @code{memory_object_get_attribute} retrieves the current
4011: attributes associated with the memory object.
4012:
4013: The argument @var{memory_control} is the port, provided by the kernel in
4014: a @code{memory_object_init} call, to which cache management requests may
4015: be issued. If @var{object_ready} is set, the kernel may issue new data
4016: and unlock requests on the associated memory object. If
4017: @var{may_cache_object} is set, the kernel may keep data associated with
4018: this memory object, even after virtual memory references to it are gone.
4019: @var{copy_strategy} tells how the kernel should copy regions of the
4020: associated memory object.
4021:
4022: This routine does not receive a reply message (and consequently has no
4023: return value), so only message transmission errors apply.
4024: @end deftypefun
4025:
4026: @deftypefun kern_return_t memory_object_change_attributes (@w{memory_object_control_t @var{memory_control}}, @w{boolean_t @var{may_cache_object}}, @w{memory_object_copy_strategy_t @var{copy_strategy}}, @w{mach_port_t @var{reply_to}})
4027: The function @code{memory_object_change_attribute} sets
4028: performance-related attributes for the specified memory object. If the
4029: caching attribute is asserted, the kernel is permitted (and encouraged)
4030: to maintain cached data for this memory object even after no virtual
4031: address space contains this data.
4032:
4033: There are three possible caching strategies:
4034: @code{MEMORY_OBJECT_COPY_NONE} which specifies that nothing special
4035: should be done when data in the object is copied;
4036: @code{MEMORY_OBJECT_COPY_CALL} which specifies that the memory manager
4037: should be notified via a @code{memory_object_copy} call before any part
4038: of the object is copied; and @code{MEMORY_OBJECT_COPY_DELAY} which
4039: guarantees that the memory manager does not externally modify the data
4040: so that the kernel can use its normal copy-on-write algorithms.
4041: @code{MEMORY_OBJECT_COPY_DELAY} is the strategy most commonly used.
4042:
4043: The argument @var{memory_control} is the port, provided by the kernel in
4044: a @code{memory_object_init} call, to which cache management requests may
4045: be issued. If @var{may_cache_object} is set, the kernel may keep data
4046: associated with this memory object, even after virtual memory references
4047: to it are gone. @var{copy_strategy} tells how the kernel should copy
4048: regions of the associated memory object. @var{reply_to} is a port on
1.1.1.2 root 4049: which a @code{memory_object_change_completed} call will be issued upon
1.1 root 4050: completion of the attribute change, or @code{MACH_PORT_NULL} if no
4051: acknowledgement is desired.
4052:
4053: This routine does not receive a reply message (and consequently has no
4054: return value), so only message transmission errors apply.
4055: @end deftypefun
4056:
4057: @deftypefun kern_return_t memory_object_change_completed (@w{memory_object_t @var{memory_object}}, @w{boolean_t @var{may_cache_object}}, @w{memory_object_copy_strategy_t @var{copy_strategy}})
4058: @deftypefunx kern_return_t seqnos_memory_object_change_completed (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{boolean_t @var{may_cache_object}}, @w{memory_object_copy_strategy_t @var{copy_strategy}})
4059: The function @code{memory_object_change_completed} indicates the
4060: completion of an attribute change call.
4061:
4062: @c Warning: This routine does NOT contain a memory_object_control_t because
4063: @c the memory_object_change_attributes call may cause memory object
4064: @c termination (by uncaching the object). This would yield an invalid
4065: @c port.
4066: @end deftypefun
4067:
4068: The following interface is obsoleted by @code{memory_object_ready} and
4069: @code{memory_object_change_attributes}. If the old form
4070: @code{memory_object_set_attributes} is used to make a memory object
4071: ready, the kernel will write back data using the old
4072: @code{memory_object_data_write} interface rather than
4073: @code{memory_object_data_return}..
4074:
4075: @deftypefun kern_return_t memory_object_set_attributes (@w{memory_object_control_t @var{memory_control}}, @w{boolean @var{object_ready}}, @w{boolean_t @var{may_cache_object}}, @w{memory_object_copy_strategy_t @var{copy_strategy}})
1.1.1.2 root 4076: The function @code{memory_object_set_attribute} controls how the
1.1 root 4077: memory object. The kernel will only make data or unlock requests when
4078: the ready attribute is asserted. If the caching attribute is asserted,
4079: the kernel is permitted (and encouraged) to maintain cached data for
4080: this memory object even after no virtual address space contains this
4081: data.
4082:
4083: There are three possible caching strategies:
4084: @code{MEMORY_OBJECT_COPY_NONE} which specifies that nothing special
4085: should be done when data in the object is copied;
4086: @code{MEMORY_OBJECT_COPY_CALL} which specifies that the memory manager
4087: should be notified via a @code{memory_object_copy} call before any part
4088: of the object is copied; and @code{MEMORY_OBJECT_COPY_DELAY} which
4089: guarantees that the memory manager does not externally modify the data
4090: so that the kernel can use its normal copy-on-write algorithms.
4091: @code{MEMORY_OBJECT_COPY_DELAY} is the strategy most commonly used.
4092:
4093: The argument @var{memory_control} is the port, provided by the kernel in
4094: a @code{memory_object_init} call, to which cache management requests may
4095: be issued. If @var{object_ready} is set, the kernel may issue new data
4096: and unlock requests on the associated memory object. If
4097: @var{may_cache_object} is set, the kernel may keep data associated with
4098: this memory object, even after virtual memory references to it are gone.
4099: @var{copy_strategy} tells how the kernel should copy regions of the
4100: associated memory object.
4101:
4102: This routine does not receive a reply message (and consequently has no
4103: return value), so only message transmission errors apply.
4104: @end deftypefun
4105:
4106:
4107: @node Default Memory Manager
4108: @section Default Memory Manager
4109:
4110: @deftypefun kern_return_t vm_set_default_memory_manager (@w{host_t @var{host}}, @w{mach_port_t *@var{default_manager}})
4111: The function @code{vm_set_default_memory_manager} sets the kernel's
4112: default memory manager. It sets the port to which newly-created
4113: temporary memory objects are delivered by @code{memory_object_create} to
4114: the host. The old memory manager port is returned. If
4115: @var{default_manager} is @code{MACH_PORT_NULL} then this routine just returns
4116: the current default manager port without changing it.
4117:
4118: The argument @var{host} is a task port to the kernel whose default
4119: memory manager is to be changed. @var{default_manager} is an in/out
4120: parameter. As input, @var{default_manager} is the port that the new
4121: memory manager is listening on for @code{memory_object_create} calls.
4122: As output, it is the old default memory manager's port.
4123:
4124: The function returns @code{KERN_SUCCESS} if the new memory manager is
4125: installed, and @code{KERN_INVALID_ARGUMENT} if this task does not have
4126: the privileges required for this call.
4127: @end deftypefun
4128:
4129: @deftypefun kern_return_t memory_object_create (@w{memory_object_t @var{old_memory_object}}, @w{memory_object_t @var{new_memory_object}}, @w{vm_size_t @var{new_object_size}}, @w{memory_object_control_t @var{new_control}}, @w{memory_object_name_t @var{new_name}}, @w{vm_size_t @var{new_page_size}})
4130: @deftypefunx kern_return_t seqnos_memory_object_create (@w{memory_object_t @var{old_memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_t @var{new_memory_object}}, @w{vm_size_t @var{new_object_size}}, @w{memory_object_control_t @var{new_control}}, @w{memory_object_name_t @var{new_name}}, @w{vm_size_t @var{new_page_size}})
4131: The function @code{memory_object_create} is a request that the given
4132: memory manager accept responsibility for the given memory object created
4133: by the kernel. This call will only be made to the system
4134: @strong{default memory manager}. The memory object in question
4135: initially consists of zero-filled memory; only memory pages that are
4136: actually written will ever be provided to
4137: @code{memory_object_data_request} calls, the default memory manager must
4138: use @code{memory_object_data_unavailable} for any pages that have not
4139: previously been written.
4140:
4141: No reply is expected after this call. Since this call is directed to
4142: the default memory manager, the kernel assumes that it will be ready to
4143: handle data requests to this object and does not need the confirmation
4144: of a @code{memory_object_set_attributes} call.
4145:
4146: The argument @var{old_memory_object} is a memory object provided by the
4147: default memory manager on which the kernel can make
4148: @code{memory_object_create} calls. @var{new_memory_object} is a new
4149: memory object created by the kernel; see synopsis for further
4150: description. Note that all port rights (including receive rights) are
4151: included for the new memory object. @var{new_object_size} is the
4152: maximum size of the new object. @var{new_control} is a port, created by
4153: the kernel, on which a memory manager may issue cache management
4154: requests for the new object. @var{new_name} a port used by the kernel
4155: to refer to the new memory object data in response to @code{vm_region}
4156: calls. @var{new_page_size} is the page size to be used by this kernel.
4157: All data sizes in calls involving this kernel must be an integral
4158: multiple of the page size. Note that different kernels, indicated by
4159: different a @code{memory_control}, may have different page sizes.
4160:
4161: The function should return @code{KERN_SUCCESS}, but since this routine
4162: is called by the kernel, which does not wait for a reply message, this
4163: value is ignored.
4164: @end deftypefun
4165:
4166: @deftypefun kern_return_t memory_object_data_initialize (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}})
4167: @deftypefunx kern_return_t seqnos_memory_object_data_initialize (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}})
4168: The function @code{memory_object_data_initialize} provides the memory
4169: manager with initial data for a kernel-created memory object. If the
4170: memory manager already has been supplied data (by a previous
4171: @code{memory_object_data_initialize}, @code{memory_object_data_write} or
4172: @code{memory_object_data_return}), then this data should be ignored.
4173: Otherwise, this call behaves exactly as does
4174: @code{memory_object_data_return} on memory objects created by the kernel
4175: via @code{memory_object_create} and thus will only be made to default
4176: memory managers. This call will not be made on objects created via
4177: @code{memory_object_copy}.
4178:
4179: The argument @var{memory_object} the port that represents the memory
4180: object data, as supplied by the kernel in a @code{memory_object_create}
4181: call. @var{memory_control} is the request port to which a response is
4182: requested. (In the event that a memory object has been supplied to more
4183: than one the kernel that has made the request.) @var{offset} is the
4184: offset within a memory object to which this call refers. This will be
1.1.1.2 root 4185: page aligned. @var{data} is the data which has been modified while
1.1 root 4186: cached in physical memory. @var{data_count} is the amount of data to be
4187: written, in bytes. This will be an integral number of memory object
4188: pages.
4189:
4190: The function should return @code{KERN_SUCCESS}, but since this routine
4191: is called by the kernel, which does not wait for a reply message, this
4192: value is ignored.
4193: @end deftypefun
4194:
4195:
4196: @node Threads and Tasks
4197: @chapter Threads and Tasks
4198:
4199: @menu
4200: * Thread Interface:: Manipulating threads.
4201: * Task Interface:: Manipulating tasks.
4202: * Profiling:: Profiling threads and tasks.
4203: @end menu
4204:
4205:
4206: @node Thread Interface
4207: @section Thread Interface
4208:
4209: @cindex thread port
4210: @cindex port representing a thread
4211: @deftp {Data type} thread_t
4212: This is a @code{mach_port_t} and used to hold the port name of a
4213: thread port that represents the thread. Manipulations of the thread are
4214: implemented as remote procedure calls to the thread port. A thread can
4215: get a port to itself with the @code{mach_thread_self} system call.
4216: @end deftp
4217:
4218: @menu
4219: * Thread Creation:: Creating new threads.
4220: * Thread Termination:: Terminating existing threads.
4221: * Thread Information:: How to get informations on threads.
4222: * Thread Settings:: How to set threads related informations.
4223: * Thread Execution:: How to control the thread's machine state.
4224: * Scheduling:: Operations on thread scheduling.
4225: * Thread Special Ports:: How to handle the thread's special ports.
4226: * Exceptions:: Managing exceptions.
4227: @end menu
4228:
4229:
4230: @node Thread Creation
4231: @subsection Thread Creation
4232:
4233: @deftypefun kern_return_t thread_create (@w{task_t @var{parent_task}}, @w{thread_t *@var{child_thread}})
4234: The function @code{thread_create} creates a new thread within the task
4235: specified by @var{parent_task}. The new thread has no processor state,
4236: and has a suspend count of 1. To get a new thread to run, first
4237: @code{thread_create} is called to get the new thread's identifier,
4238: (@var{child_thread}). Then @code{thread_set_state} is called to set a
4239: processor state, and finally @code{thread_resume} is called to get the
4240: thread scheduled to execute.
4241:
4242: When the thread is created send rights to its thread kernel port are
4243: given to it and returned to the caller in @var{child_thread}. The new
4244: thread's exception port is set to @code{MACH_PORT_NULL}.
4245:
4246: The function returns @code{KERN_SUCCESS} if a new thread has been
4247: created, @code{KERN_INVALID_ARGUMENT} if @var{parent_task} is not a
4248: valid task and @code{KERN_RESOURCE_SHORTAGE} if some critical kernel
4249: resource is not available.
4250: @end deftypefun
4251:
4252:
4253: @node Thread Termination
4254: @subsection Thread Termination
4255:
4256: @deftypefun kern_return_t thread_terminate (@w{thread_t @var{target_thread}})
4257: The function @code{thread_terminate} destroys the thread specified by
4258: @var{target_thread}.
4259:
4260: The function returns @code{KERN_SUCCESS} if the thread has been killed
4261: and @code{KERN_INVALID_ARGUMENT} if @var{target_thread} is not a thread.
4262: @end deftypefun
4263:
4264:
4265: @node Thread Information
4266: @subsection Thread Information
4267:
4268: @deftypefun thread_t mach_thread_self ()
4269: The @code{mach_thread_self} system call returns the calling thread's
4270: thread port.
4271:
4272: @code{mach_thread_self} has an effect equivalent to receiving a send
4273: right for the thread port. @code{mach_thread_self} returns the name of
4274: the send right. In particular, successive calls will increase the
4275: calling task's user-reference count for the send right.
4276:
4277: @c author{marcus}
4278: As a special exception, the kernel will overrun the user reference count
4279: of the thread name port, so that this function can not fail for that
4280: reason. Because of this, the user should not deallocate the port right
4281: if an overrun might have happened. Otherwise the reference count could
4282: drop to zero and the send right be destroyed while the user still
4283: expects to be able to use it. As the kernel does not make use of the
4284: number of extant send rights anyway, this is safe to do (the thread port
4285: itself is not destroyed, even when there are no send rights anymore).
4286:
4287: The function returns @code{MACH_PORT_NULL} if a resource shortage
4288: prevented the reception of the send right or if the thread port is
4289: currently null and @code{MACH_PORT_DEAD} if the thread port is currently
4290: dead.
4291: @end deftypefun
4292:
4293: @deftypefun kern_return_t thread_info (@w{thread_t @var{target_thread}}, @w{int @var{flavor}}, @w{thread_info_t @var{thread_info}}, @w{mach_msg_type_number_t *@var{thread_infoCnt}})
4294: The function @code{thread_info} returns the selected information array
4295: for a thread, as specified by @var{flavor}.
4296:
4297: @var{thread_info} is an array of integers that is supplied by the caller
4298: and returned filled with specified information. @var{thread_infoCnt} is
4299: supplied as the maximum number of integers in @var{thread_info}. On
4300: return, it contains the actual number of integers in @var{thread_info}.
4301: The maximum number of integers returned by any flavor is
4302: @code{THREAD_INFO_MAX}.
4303:
4304: The type of information returned is defined by @var{flavor}, which can
4305: be one of the following:
4306:
4307: @table @code
4308: @item THREAD_BASIC_INFO
4309: The function returns basic information about the thread, as defined by
4310: @code{thread_basic_info_t}. This includes the user and system time, the
4311: run state, and scheduling priority. The number of integers returned is
4312: @code{THREAD_BASIC_INFO_COUNT}.
4313:
4314: @item THREAD_SCHED_INFO
1.1.1.2 root 4315: The function returns information about the scheduling policy for the
1.1 root 4316: thread as defined by @code{thread_sched_info_t}. The number of integers
4317: returned is @code{THREAD_SCHED_INFO_COUNT}.
4318: @end table
4319:
4320: The function returns @code{KERN_SUCCESS} if the call succeeded and
4321: @code{KERN_INVALID_ARGUMENT} if @var{target_thread} is not a thread or
4322: @var{flavor} is not recognized. The function returns
4323: @code{MIG_ARRAY_TOO_LARGE} if the returned info array is too large for
4324: @var{thread_info}. In this case, @var{thread_info} is filled as much as
4325: possible and @var{thread_infoCnt} is set to the number of elements that
4326: would have been returned if there were enough room.
4327: @end deftypefun
4328:
4329: @deftp {Data type} {struct thread_basic_info}
4330: This structure is returned in @var{thread_info} by the
4331: @code{thread_info} function and provides basic information about the
4332: thread. You can cast a variable of type @code{thread_info_t} to a
4333: pointer of this type if you provided it as the @var{thread_info}
4334: parameter for the @code{THREAD_BASIC_INFO} flavor of @code{thread_info}.
4335: It has the following members:
4336:
4337: @table @code
4338: @item time_value_t user_time
4339: user run time
4340:
4341: @item time_value_t system_time
4342: system run time
4343: @item int cpu_usage
4344: Scaled cpu usage percentage. The scale factor is @code{TH_USAGE_SCALE}.
4345:
4346: @item int base_priority
4347: The base scheduling priority of the thread.
4348:
4349: @item int cur_priority
4350: The current scheduling priority of the thread.
4351:
4352: @item integer_t run_state
1.1.1.2 root 4353: The run state of the thread. The possible values of this field are:
1.1 root 4354: @table @code
4355: @item TH_STATE_RUNNING
4356: The thread is running normally.
4357:
4358: @item TH_STATE_STOPPED
4359: The thread is suspended.
4360:
4361: @item TH_STATE_WAITING
4362: The thread is waiting normally.
4363:
4364: @item TH_STATE_UNINTERRUPTIBLE
4365: The thread is in an uninterruptible wait.
4366:
4367: @item TH_STATE_HALTED
4368: The thread is halted at a clean point.
4369: @end table
4370:
4371: @item flags
4372: Various flags. The possible values of this field are:
4373: @table @code
4374: @item TH_FLAGS_SWAPPED
4375: The thread is swapped out.
4376:
4377: @item TH_FLAGS_IDLE
4378: The thread is an idle thread.
4379: @end table
4380:
4381: @item int suspend_count
4382: The suspend count for the thread.
4383:
4384: @item int sleep_time
4385: The number of seconds that the thread has been sleeping.
4386:
4387: @item time_value_t creation_time
4388: The time stamp of creation.
4389: @end table
4390: @end deftp
4391:
4392: @deftp {Data type} thread_basic_info_t
4393: This is a pointer to a @code{struct thread_basic_info}.
4394: @end deftp
4395:
4396: @deftp {Data type} {struct thread_sched_info}
4397: This structure is returned in @var{thread_info} by the
4398: @code{thread_info} function and provides schedule information about the
4399: thread. You can cast a variable of type @code{thread_info_t} to a
4400: pointer of this type if you provided it as the @var{thread_info}
4401: parameter for the @code{THREAD_SCHED_INFO} flavor of @code{thread_info}.
4402: It has the following members:
4403:
4404: @table @code
4405: @item int policy
4406: The scheduling policy of the thread, @ref{Scheduling Policy}.
4407:
4408: @item integer_t data
4409: Policy-dependent scheduling information, @ref{Scheduling Policy}.
4410:
4411: @item int base_priority
4412: The base scheduling priority of the thread.
4413:
4414: @item int max_priority
4415: The maximum scheduling priority of the thread.
4416:
4417: @item int cur_priority
4418: The current scheduling priority of the thread.
4419:
4420: @item int depressed
4421: @code{TRUE} if the thread is depressed.
4422:
4423: @item int depress_priority
4424: The priority the thread was depressed from.
4425: @end table
4426: @end deftp
4427:
4428: @deftp {Data type} thread_sched_info_t
4429: This is a pointer to a @code{struct thread_sched_info}.
4430: @end deftp
4431:
4432:
4433: @node Thread Settings
4434: @subsection Thread Settings
4435:
4436: @deftypefun kern_return_t thread_wire (@w{host_priv_t @var{host_priv}}, @w{thread_t @var{thread}}, @w{boolean_t @var{wired}})
4437: The function @code{thread_wire} controls the VM privilege level of the
4438: thread @var{thread}. A VM-privileged thread never waits inside the
4439: kernel for memory allocation from the kernel's free list of pages or for
4440: allocation of a kernel stack.
4441:
4442: Threads that are part of the default pageout path should be
4443: VM-privileged, to prevent system deadlocks. Threads that are not part
4444: of the default pageout path should not be VM-privileged, to prevent the
4445: kernel's free list of pages from being exhausted.
4446:
4447: The functions returns @code{KERN_SUCCESS} if the call succeeded,
4448: @code{KERN_INVALID_ARGUMENT} if @var{host_priv} or @var{thread} was
4449: invalid.
4450:
4451: The @code{thread_wire} call is actually an RPC to @var{host_priv},
4452: normally a send right for a privileged host port, but potentially any
4453: send right. In addition to the normal diagnostic return codes from the
4454: call's server (normally the kernel), the call may return @code{mach_msg}
4455: return codes.
4456: @c See also: vm_wire(2), vm_set_default_memory_manager(2).
4457: @end deftypefun
4458:
4459:
4460: @node Thread Execution
4461: @subsection Thread Execution
4462:
4463: @deftypefun kern_return_t thread_suspend (@w{thread_t @var{target_thread}})
4464: Increments the thread's suspend count and prevents the thread from
4465: executing any more user level instructions. In this context a user
4466: level instruction is either a machine instruction executed in user mode
4467: or a system trap instruction including page faults. Thus if a thread is
4468: currently executing within a system trap the kernel code may continue to
1.1.1.2 root 4469: execute until it reaches the system return code or it may suspend within
1.1 root 4470: the kernel code. In either case, when the thread is resumed the system
1.1.1.2 root 4471: trap will return. This could cause unpredictable results if the user
1.1 root 4472: did a suspend and then altered the user state of the thread in order to
4473: change its direction upon a resume. The call @code{thread_abort} is
4474: provided to allow the user to abort any system call that is in progress
4475: in a predictable way.
4476:
4477: The suspend count may become greater than one with the effect that it
4478: will take more than one resume call to restart the thread.
4479:
4480: The function returns @code{KERN_SUCCESS} if the thread has been
4481: suspended and @code{KERN_INVALID_ARGUMENT} if @var{target_thread} is not
4482: a thread.
4483: @end deftypefun
4484:
4485: @deftypefun kern_return_t thread_resume (@w{thread_t @var{target_thread}})
1.1.1.2 root 4486: Decrements the thread's suspend count. If the count becomes zero the
1.1 root 4487: thread is resumed. If it is still positive, the thread is left
4488: suspended. The suspend count may not become negative.
4489:
4490: The function returns @code{KERN_SUCCESS} if the thread has been resumed,
4491: @code{KERN_FAILURE} if the suspend count is already zero and
4492: @code{KERN_INVALID_ARGUMENT} if @var{target_thread} is not a thread.
4493: @end deftypefun
4494:
4495: @deftypefun kern_return_t thread_abort (@w{thread_t @var{target_thread}})
4496: The function @code{thread_abort} aborts the kernel primitives:
4497: @code{mach_msg}, @code{msg_send}, @code{msg_receive} and @code{msg_rpc}
4498: and page-faults, making the call return a code indicating that it was
4499: interrupted. The call is interrupted whether or not the thread (or task
1.1.1.2 root 4500: containing it) is currently suspended. If it is suspended, the thread
4501: receives the interrupt when it is resumed.
1.1 root 4502:
4503: A thread will retry an aborted page-fault if its state is not modified
4504: before it is resumed. @code{msg_send} returns @code{SEND_INTERRUPTED};
4505: @code{msg_receive} returns @code{RCV_INTERRUPTED}; @code{msg_rpc}
4506: returns either @code{SEND_INTERRUPTED} or @code{RCV_INTERRUPTED},
4507: depending on which half of the RPC was interrupted.
4508:
4509: The main reason for this primitive is to allow one thread to cleanly
4510: stop another thread in a manner that will allow the future execution of
4511: the target thread to be controlled in a predictable way.
4512: @code{thread_suspend} keeps the target thread from executing any further
4513: instructions at the user level, including the return from a system call.
4514: @code{thread_get_state}/@code{thread_set_state} allows the examination
4515: or modification of the user state of a target thread. However, if a
4516: suspended thread was executing within a system call, it also has
4517: associated with it a kernel state. This kernel state can not be
4518: modified by @code{thread_set_state} with the result that when the thread
4519: is resumed the system call may return changing the user state and
4520: possibly user memory. @code{thread_abort} aborts the kernel call from
4521: the target thread's point of view by resetting the kernel state so that
4522: the thread will resume execution at the system call return with the
4523: return code value set to one of the interrupted codes. The system call
4524: itself will either be entirely completed or entirely aborted, depending
4525: on the precise moment at which the abort was received. Thus if the
4526: thread's user state has been changed by @code{thread_set_state}, it will
4527: not be modified by any unexpected system call side effects.
4528:
4529: For example to simulate a Unix signal, the following sequence of calls
4530: may be used:
4531:
4532: @enumerate
4533: @item
4534: @code{thread_suspend}: Stops the thread.
4535:
4536: @item
4537: @code{thread_abort}: Interrupts any system call in progress, setting the
4538: return value to `interrupted'. Since the thread is stopped, it will not
4539: return to user code.
4540:
4541: @item
4542: @code{thread_set_state}: Alters thread's state to simulate a procedure
4543: call to the signal handler
4544:
4545: @item
4546: @code{thread_resume}: Resumes execution at the signal handler. If the
4547: thread's stack has been correctly set up, the thread may return to the
4548: interrupted system call. (Of course, the code to push an extra stack
4549: frame and change the registers is VERY machine-dependent.)
4550: @end enumerate
4551:
4552: Calling @code{thread_abort} on a non-suspended thread is pretty risky,
4553: since it is very difficult to know exactly what system trap, if any, the
4554: thread might be executing and whether an interrupt return would cause
4555: the thread to do something useful.
4556:
4557: The function returns @code{KERN_SUCCESS} if the thread received an
4558: interrupt and @code{KERN_INVALID_ARGUMENT} if @var{target_thread} is not
4559: a thread.
4560: @end deftypefun
4561:
4562: @deftypefun kern_return_t thread_get_state (@w{thread_t @var{target_thread}}, @w{int @var{flavor}}, @w{thread_state_t @var{old_state}}, @w{mach_msg_type_number_t *@var{old_stateCnt}})
4563: The function @code{thread_get_state} returns the execution state
4564: (e.g. the machine registers) of @var{target_thread} as specified by
4565: @var{flavor}. The @var{old_state} is an array of integers that is
4566: provided by the caller and returned filled with the specified
4567: information. @var{old_stateCnt} is input set to the maximum number of
4568: integers in @var{old_state} and returned equal to the actual number of
4569: integers in @var{old_state}.
4570:
4571: @var{target_thread} may not be @code{mach_thread_self()}.
4572:
4573: The definition of the state structures can be found in
4574: @file{machine/thread_status.h}.
4575:
4576: The function returns @code{KERN_SUCCESS} if the state has been returned,
4577: @code{KERN_INVALID_ARGUMENT} if @var{target_thread} is not a thread or
1.1.1.2 root 4578: is @code{mach_thread_self} or @var{flavor} is unrecognized for this machine.
1.1 root 4579: The function returns @code{MIG_ARRAY_TOO_LARGE} if the returned state is
4580: too large for @var{old_state}. In this case, @var{old_state} is filled
4581: as much as possible and @var{old_stateCnt} is set to the number of
4582: elements that would have been returned if there were enough room.
4583: @end deftypefun
4584:
4585: @deftypefun kern_return_t thread_set_state (@w{thread_t @var{target_thread}}, @w{int @var{flavor}}, @w{thread_state_t @var{new_state}}, @w{mach_msg_type_number_t @var{new_state_count}})
4586: The function @code{thread_set_state} sets the execution state (e.g. the
4587: machine registers) of @var{target_thread} as specified by @var{flavor}.
4588: The @var{new_state} is an array of integers. @var{new_state_count} is
4589: the number of elements in @var{new_state}. The entire set of registers
4590: is reset. This will do unpredictable things if @var{target_thread} is
4591: not suspended.
4592:
4593: @var{target_thread} may not be @code{mach_thread_self}.
4594:
4595: The definition of the state structures can be found in
4596: @file{machine/thread_status.h}.
4597:
4598: The function returns @code{KERN_SUCCESS} if the state has been set and
4599: @code{KERN_INVALID_ARGUMENT} if @var{target_thread} is not a thread or
1.1.1.2 root 4600: is @code{mach_thread_self} or @var{flavor} is unrecognized for this
1.1 root 4601: machine.
4602: @end deftypefun
4603:
4604:
4605: @node Scheduling
4606: @subsection Scheduling
4607:
4608: @menu
4609: * Thread Priority:: Changing the priority of a thread.
4610: * Hand-Off Scheduling:: Switching to a new thread.
4611: * Scheduling Policy:: Setting the scheduling policy.
4612: @end menu
4613:
4614:
4615: @node Thread Priority
4616: @subsubsection Thread Priority
4617:
4618: Threads have three priorities associated with them by the system, a
4619: priority, a maximum priority, and a scheduled priority. The scheduled
4620: priority is used to make scheduling decisions about the thread. It is
4621: determined from the priority by the policy (for timesharing, this means
4622: adding an increment derived from cpu usage). The priority can be set
4623: under user control, but may never exceed the maximum priority. Changing
4624: the maximum priority requires presentation of the control port for the
4625: thread's processor set; since the control port for the default processor
4626: set is privileged, users cannot raise their maximum priority to unfairly
4627: compete with other users on that set. Newly created threads obtain
4628: their priority from their task and their max priority from the thread.
4629:
4630: @deftypefun kern_return_t thread_priority (@w{thread_t @var{thread}}, @w{int @var{prority}}, @w{boolean_t @var{set_max}})
4631: The function @code{thread_priority} changes the priority and optionally
1.1.1.3 ! root 4632: the maximum priority of @var{thread}. Priorities range from 0 to 49,
1.1 root 4633: where lower numbers denote higher priorities. If the new priority is
4634: higher than the priority of the current thread, preemption may occur as
4635: a result of this call. The maximum priority of the thread is also set
4636: if @var{set_max} is @code{TRUE}. This call will fail if @var{priority}
4637: is greater than the current maximum priority of the thread. As a
4638: result, this call can only lower the value of a thread's maximum
4639: priority.
4640:
4641: The functions returns @code{KERN_SUCCESS} if the operation completed
4642: successfully, @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a
1.1.1.3 ! root 4643: thread or @var{priority} is out of range (not in 0..49), and
1.1 root 4644: @code{KERN_FAILURE} if the requested operation would violate the
4645: thread's maximum priority (thread_priority).
4646: @end deftypefun
4647:
4648: @deftypefun kern_return_t thread_max_priority (@w{thread_t @var{thread}}, @w{processor_set_t @var{processor_set}}, @w{int @var{priority}})
4649: The function @code{thread_max_priority} changes the maximum priority of
4650: the thread. Because it requires presentation of the corresponding
4651: processor set port, this call can reset the maximum priority to any
4652: legal value.
4653:
4654: The functions returns @code{KERN_SUCCESS} if the operation completed
4655: successfully, @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a
4656: thread or @var{processor_set} is not a control port for a processor set
1.1.1.3 ! root 4657: or @var{priority} is out of range (not in 0..49), and
1.1 root 4658: @code{KERN_FAILURE} if the thread is not assigned to the processor set
4659: whose control port was presented.
4660: @end deftypefun
4661:
4662:
4663: @node Hand-Off Scheduling
4664: @subsubsection Hand-Off Scheduling
4665:
4666: @deftypefun kern_return_t thread_switch (@w{thread_t @var{new_thread}}, @w{int @var{option}}, @w{int @var{time}})
4667: The function @code{thread_switch} provides low-level access to the
4668: scheduler's context switching code. @var{new_thread} is a hint that
4669: implements hand-off scheduling. The operating system will attempt to
1.1.1.2 root 4670: switch directly to the new thread (bypassing the normal logic that
1.1 root 4671: selects the next thread to run) if possible. Since this is a hint, it
4672: may be incorrect; it is ignored if it doesn't specify a thread on the
4673: same host as the current thread or if that thread can't be switched to
1.1.1.2 root 4674: (i.e., not runnable or already running on another processor or giving
4675: a plainly invalid hint, such as @code{MACH_PORT_NULL}). In this case,
4676: the normal logic to select the next thread to run is used; the current
4677: thread may continue running if there is no other appropriate thread to
4678: run.
1.1 root 4679:
4680: Options for @var{option} are defined in @file{mach/thread_switch.h} and
4681: specify the interpretation of @var{time}. The possible values for
4682: @var{option} are:
4683:
4684: @table @code
4685: @item SWITCH_OPTION_NONE
4686: No options, the time argument is ignored.
4687:
4688: @item SWITCH_OPTION_WAIT
1.1.1.2 root 4689: The thread is blocked for the specified time (in milliseconds;
4690: specifying @code{0} will wait for the next tick). This can be aborted
4691: by @code{thread_abort}.
1.1 root 4692:
4693: @item SWITCH_OPTION_DEPRESS
4694: The thread's priority is depressed to the lowest possible value for the
4695: specified time. This can be aborted by @code{thread_depress_abort}.
4696: This depression is independent of operations that change the thread's
4697: priority (e.g. @code{thread_priority} will not abort the depression).
4698: The minimum time and units of time can be obtained as the
4699: @code{min_timeout} value from @code{host_info}. The depression is also
1.1.1.2 root 4700: aborted when the current thread is next run (either via hand-off
1.1 root 4701: scheduling or because the processor set has nothing better to do).
4702: @end table
4703:
4704: @code{thread_switch} is often called when the current thread can proceed
4705: no further for some reason; the various options and arguments allow
4706: information about this reason to be transmitted to the kernel. The
4707: @var{new_thread} argument (handoff scheduling) is useful when the
4708: identity of the thread that must make progress before the current thread
4709: runs again is known. The @code{WAIT} option is used when the amount of
4710: time that the current thread must wait before it can do anything useful
4711: can be estimated and is fairly long. The @code{DEPRESS} option is used
4712: when the amount of time that must be waited is fairly short, especially
4713: when the identity of the thread that is being waited for is not known.
4714:
4715: Users should beware of calling @code{thread_switch} with an invalid hint
4716: (e.g. @code{MACH_PORT_NULL}) and no option. Because the time-sharing
4717: scheduler varies the priority of threads based on usage, this may result
4718: in a waste of cpu time if the thread that must be run is of lower
4719: priority. The use of the @code{DEPRESS} option in this situation is
4720: highly recommended.
4721:
4722: @code{thread_switch} ignores policies. Users relying on the preemption
4723: semantics of a fixed time policy should be aware that
4724: @code{thread_switch} ignores these semantics; it will run the specified
1.1.1.2 root 4725: @var{new_thread} independent of its priority and the priority of any other
1.1 root 4726: threads that could be run instead.
4727:
4728: The function returns @code{KERN_SUCCESS} if the call succeeded,
4729: @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a thread or
4730: @var{option} is not a recognized option, and @code{KERN_FAILURE} if
4731: @code{kern_depress_abort} failed because the thread was not depressed.
4732: @end deftypefun
4733:
4734: @deftypefun kern_return_t thread_depress_abort (@w{thread_t @var{thread}})
4735: The function @code{thread_depress_abort} cancels any priority depression
4736: for @var{thread} caused by a @code{swtch_pri} or @code{thread_switch}
4737: call.
4738:
4739: The function returns @code{KERN_SUCCESS} if the call succeeded and
4740: @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a valid thread.
4741: @end deftypefun
4742:
4743: @deftypefun boolean_t swtch ()
4744: @c XXX Clear up wording.
4745: The system trap @code{swtch} attempts to switch the current thread off
4746: the processor. The return value indicates if more than the current
4747: thread is running in the processor set. This is useful for lock
4748: management routines.
4749:
4750: The call returns @code{FALSE} if the thread is justified in becoming a
4751: resource hog by continuing to spin because there's nothing else useful
4752: that the processor could do. @code{TRUE} is returned if the thread
4753: should make one more check on the lock and then be a good citizen and
4754: really suspend.
4755: @end deftypefun
4756:
4757: @deftypefun boolean_t swtch_pri (@w{int @var{priority}})
4758: The system trap @code{swtch_pri} attempts to switch the current thread
4759: off the processor as @code{swtch} does, but depressing the priority of
4760: the thread to the minimum possible value during the time.
4761: @var{priority} is not used currently.
4762:
4763: The return value is as for @code{swtch}.
4764: @end deftypefun
4765:
4766:
4767: @node Scheduling Policy
4768: @subsubsection Scheduling Policy
4769:
4770: @deftypefun kern_return_t thread_policy (@w{thread_t @var{thread}}, @w{int @var{policy}}, @w{int @var{data}})
4771: The function @code{thread_policy} changes the scheduling policy for
4772: @var{thread} to @var{policy}.
4773:
4774: @var{data} is policy-dependent scheduling information. There are
4775: currently two supported policies: @code{POLICY_TIMESHARE} and
4776: @code{POLICY_FIXEDPRI} defined in @file{mach/policy.h}; this file is
4777: included by @file{mach.h}. @var{data} is meaningless for timesharing,
4778: but is the quantum to be used (in milliseconds) for the fixed priority
4779: policy. To be meaningful, this quantum must be a multiple of the basic
4780: system quantum (min_quantum) which can be obtained from
4781: @code{host_info}. The system will always round up to the next multiple
4782: of the quantum.
4783:
4784: Processor sets may restrict the allowed policies, so this call will fail
4785: if the processor set to which @var{thread} is currently assigned does
4786: not permit @var{policy}.
4787:
4788: The function returns @code{KERN_SUCCESS} if the call succeeded.
4789: @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a thread or
4790: @var{policy} is not a recognized policy, and @code{KERN_FAILURE} if the
4791: processor set to which @var{thread} is currently assigned does not
4792: permit @var{policy}.
4793: @end deftypefun
4794:
4795:
4796: @node Thread Special Ports
4797: @subsection Thread Special Ports
4798:
4799: @deftypefun kern_return_t thread_get_special_port (@w{thread_t @var{thread}}, @w{int @var{which_port}}, @w{mach_port_t *@var{special_port}})
4800: The function @code{thread_get_special_port} returns send rights to one
4801: of a set of special ports for the thread specified by @var{thread}.
4802:
4803: The possible values for @var{which_port} are @code{THREAD_KERNEL_PORT}
4804: and @code{THREAD_EXCEPTION_PORT}. A thread also has access to its
4805: task's special ports.
4806:
4807: The function returns @code{KERN_SUCCESS} if the port was returned and
4808: @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a thread or
4809: @var{which_port} is an invalid port selector.
4810: @end deftypefun
4811:
4812: @deftypefun kern_return_t thread_get_kernel_port (@w{thread_t @var{thread}}, @w{mach_port_t *@var{kernel_port}})
4813: The function @code{thread_get_kernel_port} is equivalent to the function
4814: @code{thread_get_special_port} with the @var{which_port} argument set to
4815: @code{THREAD_KERNEL_PORT}.
4816: @end deftypefun
4817:
4818: @deftypefun kern_return_t thread_get_exception_port (@w{thread_t @var{thread}}, @w{mach_port_t *@var{exception_port}})
4819: The function @code{thread_get_exception_port} is equivalent to the
4820: function @code{thread_get_special_port} with the @var{which_port}
4821: argument set to @code{THREAD_EXCEPTION_PORT}.
4822: @end deftypefun
4823:
4824: @deftypefun kern_return_t thread_set_special_port (@w{thread_t @var{thread}}, @w{int @var{which_port}}, @w{mach_port_t @var{special_port}})
4825: The function @code{thread_set_special_port} sets one of a set of special
4826: ports for the thread specified by @var{thread}.
4827:
4828: The possible values for @var{which_port} are @code{THREAD_KERNEL_PORT}
4829: and @code{THREAD_EXCEPTION_PORT}. A thread also has access to its
4830: task's special ports.
4831:
4832: The function returns @code{KERN_SUCCESS} if the port was set and
4833: @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a thread or
4834: @var{which_port} is an invalid port selector.
4835: @end deftypefun
4836:
4837: @deftypefun kern_return_t thread_set_kernel_port (@w{thread_t @var{thread}}, @w{mach_port_t @var{kernel_port}})
4838: The function @code{thread_set_kernel_port} is equivalent to the function
4839: @code{thread_set_special_port} with the @var{which_port} argument set to
4840: @code{THREAD_KERNEL_PORT}.
4841: @end deftypefun
4842:
4843: @deftypefun kern_return_t thread_set_exception_port (@w{thread_t @var{thread}}, @w{mach_port_t @var{exception_port}})
4844: The function @code{thread_set_exception_port} is equivalent to the
4845: function @code{thread_set_special_port} with the @var{which_port}
4846: argument set to @code{THREAD_EXCEPTION_PORT}.
4847: @end deftypefun
4848:
4849:
4850: @node Exceptions
4851: @subsection Exceptions
4852:
4853: @deftypefun kern_return_t catch_exception_raise (@w{mach_port_t @var{exception_port}}, @w{thread_t @var{thread}}, @w{task_t @var{task}}, @w{int @var{exception}}, @w{int @var{code}}, @w{int @var{subcode}})
4854: XXX Fixme
4855: @end deftypefun
4856:
4857: @deftypefun kern_return_t exception_raise (@w{mach_port_t @var{exception_port}}, @w{mach_port_t @var{thread}}, @w{mach_port_t @var{task}}, @w{integer_t @var{exception}}, @w{integer_t @var{code}}, @w{integer_t @var{subcode}})
4858: XXX Fixme
4859: @end deftypefun
4860:
4861: @deftypefun kern_return_t evc_wait (@w{unsigned int @var{event}})
4862: @c XXX This is for user space drivers, the description is incomplete.
4863: The system trap @code{evc_wait} makes the calling thread wait for the
4864: event specified by @var{event}.
4865:
1.1.1.2 root 4866: The call returns @code{KERN_SUCCESS} if the event has occurred,
1.1 root 4867: @code{KERN_NO_SPACE} if another thread is waiting for the same event and
4868: @code{KERN_INVALID_ARGUMENT} if the event object is invalid.
4869: @end deftypefun
4870:
4871:
4872: @node Task Interface
4873: @section Task Interface
4874:
4875: @cindex task port
4876: @cindex port representing a task
4877: @deftp {Data type} task_t
4878: This is a @code{mach_port_t} and used to hold the port name of a task
4879: port that represents the thread. Manipulations of the task are
4880: implemented as remote procedure calls to the task port. A task can get
4881: a port to itself with the @code{mach_task_self} system call.
4882:
4883: The task port name is also used to identify the task's IPC space
4884: (@pxref{Port Manipulation Interface}) and the task's virtual memory map
4885: (@pxref{Virtual Memory Interface}).
4886: @end deftp
4887:
4888: @menu
4889: * Task Creation:: Creating tasks.
4890: * Task Termination:: Terminating tasks.
4891: * Task Information:: Informations on tasks.
4892: * Task Execution:: Thread scheduling in a task.
4893: * Task Special Ports:: How to get and set the task's special ports.
4894: * Syscall Emulation:: How to emulate system calls.
4895: @end menu
4896:
4897:
4898: @node Task Creation
4899: @subsection Task Creation
4900:
4901: @deftypefun kern_return_t task_create (@w{task_t @var{parent_task}}, @w{boolean_t @var{inherit_memory}}, @w{task_t *@var{child_task}})
4902: The function @code{task_create} creates a new task from
4903: @var{parent_task}; the resulting task (@var{child_task}) acquires shared
4904: or copied parts of the parent's address space (see @code{vm_inherit}).
4905: The child task initially contains no threads.
4906:
4907: If @var{inherit_memory} is set, the child task's address space is built
4908: from the parent task according to its memory inheritance values;
4909: otherwise, the child task is given an empty address space.
4910:
4911: The child task gets the three special ports created or copied for it at
4912: task creation. The @code{TASK_KERNEL_PORT} is created and send rights
4913: for it are given to the child and returned to the caller.
4914: @c The following is only relevant if MACH_IPC_COMPAT is used.
4915: @c The @code{TASK_NOTIFY_PORT} is created and receive, ownership and send rights
4916: @c for it are given to the child. The caller has no access to it.
4917: The @code{TASK_BOOTSTRAP_PORT} and the @code{TASK_EXCEPTION_PORT} are
4918: inherited from the parent task. The new task can get send rights to
4919: these ports with the call @code{task_get_special_port}.
4920:
4921: The function returns @code{KERN_SUCCESS} if a new task has been created,
4922: @code{KERN_INVALID_ARGUMENT} if @var{parent_task} is not a valid task
4923: port and @code{KERN_RESOURCE_SHORTAGE} if some critical kernel resource
4924: is unavailable.
4925: @end deftypefun
4926:
4927:
4928: @node Task Termination
4929: @subsection Task Termination
4930:
4931: @deftypefun kern_return_t task_terminate (@w{task_t @var{target_task}})
4932: The function @code{task_terminate} destroys the task specified by
4933: @var{target_task} and all its threads. All resources that are used only
4934: by this task are freed. Any port to which this task has receive and
4935: ownership rights is destroyed.
4936:
4937: The function returns @code{KERN_SUCCESS} if the task has been killed,
4938: @code{KERN_INVALID_ARGUMENT} if @var{target_task} is not a task.
4939: @end deftypefun
4940:
4941:
4942: @node Task Information
4943: @subsection Task Information
4944: @deftypefun task_t mach_task_self ()
4945: The @code{mach_task_self} system call returns the calling thread's task
4946: port.
4947:
4948: @code{mach_task_self} has an effect equivalent to receiving a send right
4949: for the task port. @code{mach_task_self} returns the name of the send
4950: right. In particular, successive calls will increase the calling task's
4951: user-reference count for the send right.
4952:
4953: As a special exception, the kernel will overrun the user reference count
4954: of the task name port, so that this function can not fail for that
4955: reason. Because of this, the user should not deallocate the port right
4956: if an overrun might have happened. Otherwise the reference count could
4957: drop to zero and the send right be destroyed while the user still
4958: expects to be able to use it. As the kernel does not make use of the
4959: number of extant send rights anyway, this is safe to do (the task port
4960: itself is not destroyed, even when there are no send rights anymore).
4961:
1.1.1.2 root 4962: The function returns @code{MACH_PORT_NULL} if a resource shortage
1.1 root 4963: prevented the reception of the send right, @code{MACH_PORT_NULL} if the
4964: task port is currently null, @code{MACH_PORT_DEAD} if the task port is
4965: currently dead.
4966: @end deftypefun
4967:
4968: @deftypefun kern_return_t task_threads (@w{task_t @var{target_task}}, @w{thread_array_t *@var{thread_list}}, @w{mach_msg_type_number_t *@var{thread_count}})
4969: The function @code{task_threads} gets send rights to the kernel port for
4970: each thread contained in @var{target_task}. @var{thread_list} is an
4971: array that is created as a result of this call. The caller may wish to
4972: @code{vm_deallocate} this array when the data is no longer needed.
4973:
4974: The function returns @code{KERN_SUCCESS} if the call succeeded and
4975: @code{KERN_INVALID_ARGUMENT} if @var{target_task} is not a task.
4976: @end deftypefun
4977:
4978: @deftypefun kern_return_t task_info (@w{task_t @var{target_task}}, @w{int @var{flavor}}, @w{task_info_t @var{task_info}}, @w{mach_msg_type_number_t *@var{task_info_count}})
4979: The function @code{task_info} returns the selected information array for
4980: a task, as specified by @var{flavor}. @var{task_info} is an array of
4981: integers that is supplied by the caller, and filled with specified
4982: information. @var{task_info_count} is supplied as the maximum number of
4983: integers in @var{task_info}. On return, it contains the actual number
4984: of integers in @var{task_info}. The maximum number of integers returned
4985: by any flavor is @code{TASK_INFO_MAX}.
4986:
4987: The type of information returned is defined by @var{flavor}, which can
4988: be one of the following:
4989:
4990: @table @code
4991: @item TASK_BASIC_INFO
4992: The function returns basic information about the task, as defined by
4993: @code{task_basic_info_t}. This includes the user and system time and
4994: memory consumption. The number of integers returned is
4995: @code{TASK_BASIC_INFO_COUNT}.
4996:
4997: @item TASK_EVENTS_INFO
4998: The function returns information about events for the task as defined by
4999: @code{thread_sched_info_t}. This includes statistics about virtual
5000: memory and IPC events like pageouts, pageins and messages sent and
5001: received. The number of integers returned is
5002: @code{TASK_EVENTS_INFO_COUNT}.
5003:
5004: @item TASK_THREAD_TIMES_INFO
5005: The function returns information about the total time for live threads
5006: as defined by @code{task_thread_times_info_t}. The number of integers
5007: returned is @code{TASK_THREAD_TIMES_INFO_COUNT}.
5008: @end table
5009:
5010: The function returns @code{KERN_SUCCESS} if the call succeeded and
5011: @code{KERN_INVALID_ARGUMENT} if @var{target_task} is not a thread or
5012: @var{flavor} is not recognized. The function returns
5013: @code{MIG_ARRAY_TOO_LARGE} if the returned info array is too large for
5014: @var{task_info}. In this case, @var{task_info} is filled as much as
5015: possible and @var{task_infoCnt} is set to the number of elements that
5016: would have been returned if there were enough room.
5017: @end deftypefun
5018:
5019: @deftp {Data type} {struct task_basic_info}
5020: This structure is returned in @var{task_info} by the @code{task_info}
5021: function and provides basic information about the task. You can cast a
5022: variable of type @code{task_info_t} to a pointer of this type if you
5023: provided it as the @var{task_info} parameter for the
5024: @code{TASK_BASIC_INFO} flavor of @code{task_info}. It has the following
5025: members:
5026:
5027: @table @code
5028: @item integer_t suspend_count
5029: suspend count for task
5030:
5031: @item integer_t base_priority
5032: base scheduling priority
5033:
5034: @item vm_size_t virtual_size
5035: number of virtual pages
5036:
5037: @item vm_size_t resident_size
5038: number of resident pages
5039:
5040: @item time_value_t user_time
5041: total user run time for terminated threads
5042:
5043: @item time_value_t system_time
5044: total system run time for terminated threads
5045:
5046: @item time_value_t creation_time
5047: creation time stamp
5048: @end table
5049: @end deftp
5050:
5051: @deftp {Data type} task_basic_info_t
5052: This is a pointer to a @code{struct task_basic_info}.
5053: @end deftp
5054:
5055: @deftp {Data type} {struct task_events_info}
5056: This structure is returned in @var{task_info} by the @code{task_info}
5057: function and provides event statistics for the task. You can cast a
5058: variable of type @code{task_info_t} to a pointer of this type if you
5059: provided it as the @var{task_info} parameter for the
5060: @code{TASK_EVENTS_INFO} flavor of @code{task_info}. It has the
5061: following members:
5062:
5063: @table @code
5064: @item natural_t faults
5065: number of page faults
5066:
5067: @item natural_t zero_fills
5068: number of zero fill pages
5069:
5070: @item natural_t reactivations
5071: number of reactivated pages
5072:
5073: @item natural_t pageins
5074: number of actual pageins
5075:
5076: @item natural_t cow_faults
5077: number of copy-on-write faults
5078:
5079: @item natural_t messages_sent
5080: number of messages sent
5081:
5082: @item natural_t messages_received
5083: number of messages received
5084: @end table
5085: @end deftp
5086:
5087: @deftp {Data type} task_events_info_t
5088: This is a pointer to a @code{struct task_events_info}.
5089: @end deftp
5090:
5091: @deftp {Data type} {struct task_thread_times_info}
5092: This structure is returned in @var{task_info} by the @code{task_info}
5093: function and provides event statistics for the task. You can cast a
5094: variable of type @code{task_info_t} to a pointer of this type if you
5095: provided it as the @var{task_info} parameter for the
5096: @code{TASK_THREAD_TIMES_INFO} flavor of @code{task_info}. It has the
5097: following members:
5098:
5099: @table @code
5100: @item time_value_t user_time
5101: total user run time for live threads
5102:
5103: @item time_value_t system_time
5104: total system run time for live threads
5105: @end table
5106: @end deftp
5107:
5108: @deftp {Data type} task_thread_times_info_t
5109: This is a pointer to a @code{struct task_thread_times_info}.
5110: @end deftp
5111:
1.1.1.3 ! root 5112: @deftypefun kern_return_t task_set_name (@w{task_t @var{target_task}}, @w{kernel_debug_name_t @var{name}})
! 5113:
! 5114: The function @code{task_set_name} sets the name of @var{target_task}
! 5115: to @var{name}, truncating it if necessary.
! 5116:
! 5117: This is a debugging aid. The name is used in diagnostic messages
! 5118: printed by the kernel.
! 5119:
! 5120: The function returns @code{KERN_SUCCESS} if the call succeeded.
! 5121: @end deftypefun
! 5122:
1.1 root 5123:
5124: @node Task Execution
5125: @subsection Task Execution
5126:
5127: @deftypefun kern_return_t task_suspend (@w{task_t @var{target_task}})
5128: The function @code{task_suspend} increments the task's suspend count and
5129: stops all threads in the task. As long as the suspend count is positive
5130: newly created threads will not run. This call does not return until all
5131: threads are suspended.
5132:
5133: The count may become greater than one, with the effect that it will take
5134: more than one resume call to restart the task.
5135:
5136: The function returns @code{KERN_SUCCESS} if the task has been suspended
5137: and @code{KERN_INVALID_ARGUMENT} if @var{target_task} is not a task.
5138: @end deftypefun
5139:
5140: @deftypefun kern_return_t task_resume (@w{task_t @var{target_task}})
5141: The function @code{task_resume} decrements the task's suspend count. If
5142: it becomes zero, all threads with zero suspend counts in the task are
5143: resumed. The count may not become negative.
5144:
5145: The function returns @code{KERN_SUCCESS} if the task has been resumed,
5146: @code{KERN_FAILURE} if the suspend count is already at zero and
5147: @code{KERN_INVALID_ARGUMENT} if @var{target_task} is not a task.
5148: @end deftypefun
5149:
5150: @c XXX Should probably be in the "Scheduling" node of the Thread Interface.
5151: @deftypefun kern_return_t task_priority (@w{task_t @var{task}}, @w{int @var{priority}}, @w{boolean_t @var{change_threads}})
5152: The priority of a task is used only for creation of new threads; a new
5153: thread's priority is set to the enclosing task's priority.
5154: @code{task_priority} changes this task priority. It also sets the
5155: priorities of all threads in the task to this new priority if
5156: @var{change_threads} is @code{TRUE}. Existing threads are not affected
5157: otherwise. If this priority change violates the maximum priority of
5158: some threads, as many threads as possible will be changed and an error
5159: code will be returned.
5160:
5161: The function returns @code{KERN_SUCCESS} if the call succeeded,
5162: @code{KERN_INVALID_ARGUMENT} if @var{task} is not a task, or
5163: @var{priority} is not a valid priority and @code{KERN_FAILURE} if
5164: @var{change_threads} was @code{TRUE} and the attempt to change the
5165: priority of at least one existing thread failed because the new priority
5166: would have exceeded that thread's maximum priority.
5167: @end deftypefun
5168:
5169: @deftypefun kern_return_t task_ras_control (@w{task_t @var{target_task}}, @w{vm_address_t @var{start_pc}}, @w{vm_address_t @var{end_pc}}, @w{int @var{flavor}})
5170: The function @code{task_ras_control} manipulates a task's set of
5171: restartable atomic sequences. If a sequence is installed, and any
5172: thread in the task is preempted within the range
5173: [@var{start_pc},@var{end_pc}], then the thread is resumed at
5174: @var{start_pc}. This enables applications to build atomic sequences
5175: which, when executed to completion, will have executed atomically.
5176: Restartable atomic sequences are intended to be used on systems that do
5177: not have hardware support for low-overhead atomic primitives.
5178:
5179: As a thread can be rolled-back, the code in the sequence should have no
5180: side effects other than a final store at @var{end_pc}. The kernel does
5181: not guarantee that the sequence is restartable. It assumes the
5182: application knows what it's doing.
5183:
5184: A task may have a finite number of atomic sequences that is defined at
5185: compile time.
5186:
1.1.1.2 root 5187: The flavor specifies the particular operation that should be applied to
1.1 root 5188: this restartable atomic sequence. Possible values for flavor can be:
5189:
5190: @table @code
5191: @item TASK_RAS_CONTROL_PURGE_ALL
5192: Remove all registered sequences for this task.
5193:
5194: @item TASK_RAS_CONTROL_PURGE_ONE
5195: Remove the named registered sequence for this task.
5196:
5197: @item TASK_RAS_CONTROL_PURGE_ALL_AND_INSTALL_ONE
5198: Atomically remove all registered sequences and install the named
5199: sequence.
5200:
5201: @item TASK_RAS_CONTROL_INSTALL_ONE
5202: Install this sequence.
5203: @end table
5204:
5205: The function returns @code{KERN_SUCCESS} if the operation has been
5206: performed, @code{KERN_INVALID_ADDRESS} if the @var{start_pc} or
5207: @var{end_pc} values are not a valid address for the requested operation
5208: (for example, it is invalid to purge a sequence that has not been
5209: registered), @code{KERN_RESOURCE_SHORTAGE} if an attempt was made to
5210: install more restartable atomic sequences for a task than can be
5211: supported by the kernel, @code{KERN_INVALID_VALUE} if a bad flavor was
5212: specified, @code{KERN_INVALID_ARGUMENT} if @var{target_task} is not a
5213: task and @code{KERN_FAILURE} if the call is not not supported on this
5214: configuration.
5215: @end deftypefun
5216:
5217:
5218: @node Task Special Ports
5219: @subsection Task Special Ports
5220:
5221: @deftypefun kern_return_t task_get_special_port (@w{task_t @var{task}}, @w{int @var{which_port}}, @w{mach_port_t *@var{special_port}})
5222: The function @code{task_get_special_port} returns send rights to one of
5223: a set of special ports for the task specified by @var{task}.
5224:
5225: The special ports associated with a task are the kernel port
5226: (@code{TASK_KERNEL_PORT}), the bootstrap port
5227: (@code{TASK_BOOTSTRAP_PORT}) and the exception port
5228: (@code{TASK_EXCEPTION_PORT}). The bootstrap port is a port to which a
5229: task may send a message requesting other system service ports. This
5230: port is not used by the kernel. The task's exception port is the port
5231: to which messages are sent by the kernel when an exception occurs and
5232: the thread causing the exception has no exception port of its own.
5233:
5234: The following macros to call @code{task_get_special_port} for a specific
5235: port are defined in @code{mach/task_special_ports.h}:
5236: @code{task_get_exception_port} and @code{task_get_bootstrap_port}.
5237:
5238: The function returns @code{KERN_SUCCESS} if the port was returned and
5239: @code{KERN_INVALID_ARGUMENT} if @var{task} is not a task or
5240: @var{which_port} is an invalid port selector.
5241: @end deftypefun
5242:
5243: @deftypefun kern_return_t task_get_kernel_port (@w{task_t @var{task}}, @w{mach_port_t *@var{kernel_port}})
5244: The function @code{task_get_kernel_port} is equivalent to the function
5245: @code{task_get_special_port} with the @var{which_port} argument set to
5246: @code{TASK_KERNEL_PORT}.
5247: @end deftypefun
5248:
5249: @deftypefun kern_return_t task_get_exception_port (@w{task_t @var{task}}, @w{mach_port_t *@var{exception_port}})
5250: The function @code{task_get_exception_port} is equivalent to the
5251: function @code{task_get_special_port} with the @var{which_port} argument
5252: set to @code{TASK_EXCEPTION_PORT}.
5253: @end deftypefun
5254:
5255: @deftypefun kern_return_t task_get_bootstrap_port (@w{task_t @var{task}}, @w{mach_port_t *@var{bootstrap_port}})
5256: The function @code{task_get_bootstrap_port} is equivalent to the
5257: function @code{task_get_special_port} with the @var{which_port} argument
5258: set to @code{TASK_BOOTSTRAP_PORT}.
5259: @end deftypefun
5260:
5261: @deftypefun kern_return_t task_set_special_port (@w{task_t @var{task}}, @w{int @var{which_port}}, @w{mach_port_t @var{special_port}})
5262: The function @code{thread_set_special_port} sets one of a set of special
5263: ports for the task specified by @var{task}.
5264:
5265: The special ports associated with a task are the kernel port
5266: (@code{TASK_KERNEL_PORT}), the bootstrap port
5267: (@code{TASK_BOOTSTRAP_PORT}) and the exception port
5268: (@code{TASK_EXCEPTION_PORT}). The bootstrap port is a port to which a
5269: thread may send a message requesting other system service ports. This
5270: port is not used by the kernel. The task's exception port is the port
5271: to which messages are sent by the kernel when an exception occurs and
5272: the thread causing the exception has no exception port of its own.
5273:
5274: The function returns @code{KERN_SUCCESS} if the port was set and
5275: @code{KERN_INVALID_ARGUMENT} if @var{task} is not a task or
5276: @var{which_port} is an invalid port selector.
5277: @end deftypefun
5278:
5279: @deftypefun kern_return_t task_set_kernel_port (@w{task_t @var{task}}, @w{mach_port_t @var{kernel_port}})
5280: The function @code{task_set_kernel_port} is equivalent to the function
5281: @code{task_set_special_port} with the @var{which_port} argument set to
5282: @code{TASK_KERNEL_PORT}.
5283: @end deftypefun
5284:
5285: @deftypefun kern_return_t task_set_exception_port (@w{task_t @var{task}}, @w{mach_port_t @var{exception_port}})
5286: The function @code{task_set_exception_port} is equivalent to the
5287: function @code{task_set_special_port} with the @var{which_port} argument
5288: set to @code{TASK_EXCEPTION_PORT}.
5289: @end deftypefun
5290:
5291: @deftypefun kern_return_t task_set_bootstrap_port (@w{task_t @var{task}}, @w{mach_port_t @var{bootstrap_port}})
5292: The function @code{task_set_bootstrap_port} is equivalent to the
5293: function @code{task_set_special_port} with the @var{which_port} argument
5294: set to @code{TASK_BOOTSTRAP_PORT}.
5295: @end deftypefun
5296:
5297:
5298: @node Syscall Emulation
5299: @subsection Syscall Emulation
5300:
5301: @deftypefun kern_return_t task_get_emulation_vector (@w{task_t @var{task}}, @w{int *@var{vector_start}}, @w{emulation_vector_t *@var{emulation_vector}}, @w{mach_msg_type_number_t *@var{emulation_vector_count}})
5302: The function @code{task_get_emulation_vector} gets the user-level
5303: handler entry points for all emulated system calls.
5304: @c XXX Fixme
5305: @end deftypefun
5306:
5307: @deftypefun kern_return_t task_set_emulation_vector (@w{task_t @var{task}}, @w{int @var{vector_start}}, @w{emulation_vector_t @var{emulation_vector}}, @w{mach_msg_type_number_t @var{emulation_vector_count}})
5308: The function @code{task_set_emulation_vector} establishes user-level
5309: handlers for the specified system calls. Non-emulated system calls are
5310: specified with an entry of @code{EML_ROUTINE_NULL}. System call
1.1.1.2 root 5311: emulation handlers are inherited by the children of @var{task}.
1.1 root 5312: @c XXX Fixme
5313: @end deftypefun
5314:
5315: @deftypefun kern_return_t task_set_emulation (@w{task_t @var{task}}, @w{vm_address_t @var{routine_entry_pt}}, @w{int @var{routine_number}})
5316: The function @code{task_set_emulation} establishes a user-level handler
5317: for the specified system call. System call emulation handlers are
1.1.1.2 root 5318: inherited by the children of @var{task}.
1.1 root 5319: @c XXX Fixme
5320: @end deftypefun
5321:
5322: @c XXX Fixme datatype emulation_vector_t
5323:
5324:
5325: @node Profiling
5326: @section Profiling
5327:
5328: @deftypefun kern_return_t task_enable_pc_sampling (@w{task_t @var{task}}, @w{int *@var{ticks}}, @w{sampled_pc_flavor_t @var{flavor}})
5329: @deftypefunx kern_return_t thread_enable_pc_sampling (@w{thread_t @var{thread}}, @w{int *@var{ticks}}, @w{sampled_pc_flavor_t @var{flavor}})
5330: The function @code{task_enable_pc_sampling} enables PC sampling for
5331: @var{task}, the function @code{thread_enable_pc_sampling} enables PC
5332: sampling for @var{thread}. The kernel's idea of clock granularity is
5333: returned in @var{ticks} in usecs. (this value should not be trusted). The
5334: sampling flavor is specified by @var{flavor}.
5335:
5336: The function returns @code{KERN_SUCCESS} if the operation is completed successfully
5337: and @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a valid thread.
5338: @end deftypefun
5339:
5340: @deftypefun kern_return_t task_disable_pc_sampling (@w{task_t @var{task}}, @w{int *@var{sample_count}})
5341: @deftypefunx kern_return_t thread_disable_pc_sampling (@w{thread_t @var{thread}}, @w{int *@var{sample_count}})
5342: The function @code{task_disable_pc_sampling} disables PC sampling for
5343: @var{task}, the function @code{thread_disable_pc_sampling} disables PC
5344: sampling for @var{thread}. The number of sample elements in the kernel
5345: for the thread is returned in @var{sample_count}.
5346:
5347: The function returns @code{KERN_SUCCESS} if the operation is completed successfully
5348: and @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a valid thread.
5349: @end deftypefun
5350:
5351: @deftypefun kern_return_t task_get_sampled_pcs (@w{task_t @var{task}}, @w{sampled_pc_seqno_t *@var{seqno}}, @w{sampled_pc_array_t @var{sampled_pcs}}, @w{mach_msg_type_number_t *@var{sample_count}})
5352: @deftypefunx kern_return_t thread_get_sampled_pcs (@w{thread_t @var{thread}}, @w{sampled_pc_seqno_t *@var{seqno}}, @w{sampled_pc_array_t @var{sampled_pcs}}, @w{int *@var{sample_count}})
5353: The function @code{task_get_sampled_pcs} extracts the PC samples for
5354: @var{task}, the function @code{thread_get_sampled_pcs} extracts the PC
5355: samples for @var{thread}. @var{seqno} is the sequence number of the
5356: sampled PCs. This is useful for determining when a collector thread has
5357: missed a sample. The sampled PCs for the thread are returned in
5358: @var{sampled_pcs}. @var{sample_count} contains the number of sample
5359: elements returned.
5360:
5361: The function returns @code{KERN_SUCCESS} if the operation is completed successfully,
5362: @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a valid thread and
5363: @code{KERN_FAILURE} if @var{thread} is not sampled.
5364: @end deftypefun
5365:
5366:
5367: @deftp {Data type} sampled_pc_t
5368: This structure is returned in @var{sampled_pcs} by the
5369: @code{thread_get_sampled_pcs} and @code{task_get_sampled_pcs} functions
5370: and provides pc samples for threads or tasks. It has the following
5371: members:
5372:
5373: @table @code
5374: @item natural_t id
5375: A thread-specific unique identifier.
5376:
5377: @item vm_offset_t pc
5378: A pc value.
5379:
5380: @item sampled_pc_flavor_t sampletype
5381: The type of the sample as per flavor.
5382: @end table
5383: @end deftp
5384:
5385:
5386: @deftp {Data type} sampled_pc_flavor_t
5387: This data type specifies a pc sample flavor, either as argument passed
5388: in @var{flavor} to the @code{thread_enable_pc_sample} and
5389: @code{thread_disable_pc_sample} functions, or as member
5390: @code{sampletype} in the @code{sample_pc_t} data type. The flavor is a
5391: bitwise-or of the possible flavors defined in @file{mach/pc_sample.h}:
5392:
5393: @table @code
5394: @item SAMPLED_PC_PERIODIC
5395: default
5396: @item SAMPLED_PC_VM_ZFILL_FAULTS
5397: zero filled fault
5398: @item SAMPLED_PC_VM_REACTIVATION_FAULTS
5399: reactivation fault
5400: @item SAMPLED_PC_VM_PAGEIN_FAULTS
5401: pagein fault
5402: @item SAMPLED_PC_VM_COW_FAULTS
5403: copy-on-write fault
5404: @item SAMPLED_PC_VM_FAULTS_ANY
5405: any fault
5406: @item SAMPLED_PC_VM_FAULTS
5407: the bitwise-or of @code{SAMPLED_PC_VM_ZFILL_FAULTS},
5408: @code{SAMPLED_PC_VM_REACTIVATION_FAULTS},
5409: @code{SAMPLED_PC_VM_PAGEIN_FAULTS} and @code{SAMPLED_PC_VM_COW_FAULTS}.
5410: @end table
5411: @end deftp
5412:
5413: @c XXX sampled_pc_array_t, sampled_pc_seqno_t
5414:
5415:
5416: @node Host Interface
5417: @chapter Host Interface
5418: @cindex host interface
5419:
5420: This section describes the Mach interface to a host executing a Mach
5421: kernel. The interface allows to query statistics about a host and
5422: control its behaviour.
5423:
5424: A host is represented by two ports, a name port @var{host} used to query
5425: information about the host accessible to everyone, and a control port
5426: @var{host_priv} used to manipulate it. For example, you can query the
5427: current time using the name port, but to change the time you need to
5428: send a message to the host control port.
5429:
5430: Everything described in this section is declared in the header file
5431: @file{mach.h}.
5432:
5433: @menu
5434: * Host Ports:: Ports representing a host.
5435: * Host Information:: Retrieval of information about a host.
5436: * Host Time:: Operations on the time as seen by a host.
5437: * Host Reboot:: Rebooting the system.
5438: @end menu
5439:
5440:
5441: @node Host Ports
5442: @section Host Ports
5443: @cindex host ports
5444: @cindex ports representing a host
5445:
5446: @cindex host name port
5447: @deftp {Data type} host_t
5448: This is a @code{mach_port_t} and used to hold the port name of a host
5449: name port (or short: host port). Any task can get a send right to the
5450: name port of the host running the task using the @code{mach_host_self}
5451: system call. The name port can be used query information about the
5452: host, for example the current time.
5453: @end deftp
5454:
5455: @deftypefun host_t mach_host_self ()
5456: The @code{mach_host_self} system call returns the calling thread's host
5457: name port. It has an effect equivalent to receiving a send right for
5458: the host port. @code{mach_host_self} returns the name of the send
5459: right. In particular, successive calls will increase the calling task's
5460: user-reference count for the send right.
5461:
5462: As a special exception, the kernel will overrun the user reference count
5463: of the host name port, so that this function can not fail for that
5464: reason. Because of this, the user should not deallocate the port right
5465: if an overrun might have happened. Otherwise the reference count could
5466: drop to zero and the send right be destroyed while the user still
5467: expects to be able to use it. As the kernel does not make use of the
5468: number of extant send rights anyway, this is safe to do (the host port
5469: itself is never destroyed).
5470:
5471: The function returns @code{MACH_PORT_NULL} if a resource shortage
5472: prevented the reception of the send right.
5473:
5474: This function is also available in @file{mach/mach_traps.h}.
5475: @end deftypefun
5476:
5477: @cindex host control port
5478: @deftp {Data type} host_priv_t
5479: This is a @code{mach_port_t} and used to hold the port name of a
5480: privileged host control port. A send right to the host control port is
5481: inserted into the first task at bootstrap (@pxref{Modules}). This is
5482: the only way to get access to the host control port in Mach, so the
5483: initial task has to preserve the send right carefully, moving a copy of
5484: it to other privileged tasks if necessary and denying access to
5485: unprivileged tasks.
5486: @end deftp
5487:
5488:
5489: @node Host Information
5490: @section Host Information
5491:
5492: @deftypefun kern_return_t host_info (@w{host_t @var{host}}, @w{int @var{flavor}}, @w{host_info_t @var{host_info}}, @w{mach_msg_type_number_t *@var{host_info_count}})
5493: The @code{host_info} function returns various information about
5494: @var{host}. @var{host_info} is an array of integers that is supplied by
5495: the caller. It will be filled with the requested information.
5496: @var{host_info_count} is supplied as the maximum number of integers in
5497: @var{host_info}. On return, it contains the actual number of integers
5498: in @var{host_info}. The maximum number of integers returned by any
5499: flavor is @code{HOST_INFO_MAX}.
5500:
5501: The type of information returned is defined by @var{flavor}, which can
5502: be one of the following:
5503:
5504: @table @code
5505: @item HOST_BASIC_INFO
5506: The function returns basic information about the host, as defined by
5507: @code{host_basic_info_t}. This includes the number of processors, their
5508: type, and the amount of memory installed in the system. The number of
5509: integers returned is @code{HOST_BASIC_INFO_COUNT}. For how to get more
5510: information about the processor, see @ref{Processor Interface}.
5511:
5512: @item HOST_PROCESSOR_SLOTS
5513: The function returns the numbers of the slots with active processors in
5514: them. The number of integers returned can be up to @code{max_cpus}, as
5515: returned by the @code{HOST_BASIC_INFO} flavor of @code{host_info}.
5516:
5517: @item HOST_SCHED_INFO
5518: The function returns information of interest to schedulers as defined by
5519: @code{host_sched_info_t}. The number of integers returned is
5520: @code{HOST_SCHED_INFO_COUNT}.
5521: @end table
5522:
5523: The function returns @code{KERN_SUCCESS} if the call succeeded and
5524: @code{KERN_INVALID_ARGUMENT} if @var{host} is not a host or @var{flavor}
5525: is not recognized. The function returns @code{MIG_ARRAY_TOO_LARGE} if
5526: the returned info array is too large for @var{host_info}. In this case,
5527: @var{host_info} is filled as much as possible and @var{host_info_count}
5528: is set to the number of elements that would be returned if there were
5529: enough room.
5530: @c BUGS Availability limited. Systems without this call support a
5531: @c host_info call with an incompatible calling sequence.
5532: @end deftypefun
5533:
5534: @deftp {Data type} {struct host_basic_info}
5535: A pointer to this structure is returned in @var{host_info} by the
5536: @code{host_info} function and provides basic information about the host.
5537: You can cast a variable of type @code{host_info_t} to a pointer of this
5538: type if you provided it as the @var{host_info} parameter for the
5539: @code{HOST_BASIC_INFO} flavor of @code{host_info}. It has the following
5540: members:
5541:
5542: @table @code
5543: @item int max_cpus
5544: The maximum number of possible processors for which the kernel is
5545: configured.
5546:
5547: @item int avail_cpus
5548: The number of cpus currently available.
5549:
5550: @item vm_size_t memory_size
5551: The size of physical memory in bytes.
5552:
5553: @item cpu_type_t cpu_type
5554: The type of the master processor.
5555:
5556: @item cpu_subtype_t cpu_subtype
5557: The subtype of the master processor.
5558: @end table
5559:
5560: The type and subtype of the individual processors are also available
5561: by @code{processor_info}, see @ref{Processor Interface}.
5562: @end deftp
5563:
5564: @deftp {Data type} host_basic_info_t
5565: This is a pointer to a @code{struct host_basic_info}.
5566: @end deftp
5567:
5568: @deftp {Data type} {struct host_sched_info}
5569: A pointer to this structure is returned in @var{host_info} by the
5570: @code{host_info} function and provides information of interest to
5571: schedulers. You can cast a variable of type @code{host_info_t} to a
5572: pointer of this type if you provided it as the @var{host_info} parameter
5573: for the @code{HOST_SCHED_INFO} flavor of @code{host_info}. It has the
5574: following members:
5575:
5576: @table @code
5577: @item int min_timeout
5578: The minimum timeout and unit of time in milliseconds.
5579:
5580: @item int min_quantum
5581: The minimum quantum and unit of quantum in milliseconds.
5582: @end table
5583: @end deftp
5584:
5585: @deftp {Data type} host_sched_info_t
5586: This is a pointer to a @code{struct host_sched_info}.
5587: @end deftp
5588:
5589: @deftypefun kern_return_t host_kernel_version (@w{host_t @var{host}}, @w{kernel_version_t *@var{version}})
5590: The @code{host_kernel_version} function returns the version string
5591: compiled into the kernel executing on @var{host} at the time it was
5592: built in the character string @var{version}. This string describes the
5593: version of the kernel. The constant @code{KERNEL_VERSION_MAX} should be
5594: used to dimension storage for the returned string if the
5595: @code{kernel_version_t} declaration is not used.
5596:
5597: If the version string compiled into the kernel is longer than
5598: @code{KERNEL_VERSION_MAX}, the result is truncated and not necessarily
5599: null-terminated.
5600:
5601: If @var{host} is not a valid send right to a host port, the function
5602: returns @code{KERN_INVALID_ARGUMENT}. If @var{version} points to
5603: inaccessible memory, it returns @code{KERN_INVALID_ADDRESS}, and
5604: @code{KERN_SUCCESS} otherwise.
5605: @end deftypefun
5606:
5607: @deftypefun kern_return_t host_get_boot_info (@w{host_priv_t @var{host_priv}}, @w{kernel_boot_info_t @var{boot_info}})
5608: The @code{host_get_boot_info} function returns the boot-time information
5609: string supplied by the operator to the kernel executing on
5610: @var{host_priv} in the character string @var{boot_info}. The constant
5611: @code{KERNEL_BOOT_INFO_MAX} should be used to dimension storage for the
5612: returned string if the @code{kernel_boot_info_t} declaration is not
5613: used.
5614:
5615: If the boot-time information string supplied by the operator is longer
5616: than @code{KERNEL_BOOT_INFO_MAX}, the result is truncated and not
5617: necessarily null-terminated.
5618: @end deftypefun
5619:
5620:
5621: @node Host Time
5622: @section Host Time
5623:
5624: @deftp {Data type} time_value_t
5625: This is the representation of a time in Mach. It is a @code{struct
5626: time_value} and consists of the following members:
5627:
5628: @table @code
5629: @item integer_t seconds
5630: The number of seconds.
5631: @item integer_t microseconds
5632: The number of microseconds.
5633: @end table
5634: @end deftp
5635:
5636: The number of microseconds should always be smaller than
5637: @code{TIME_MICROS_MAX} (100000). A time with this property is
5638: @dfn{normalized}. Normalized time values can be manipulated with the
5639: following macros:
5640:
5641: @defmac time_value_add_usec (@w{time_value_t *@var{val}}, @w{integer_t *@var{micros}})
5642: Add @var{micros} microseconds to @var{val}. If @var{val} is normalized
5643: and @var{micros} smaller than @code{TIME_MICROS_MAX}, @var{val} will be
5644: normalized afterwards.
5645: @end defmac
5646:
5647: @defmac time_value_add (@w{time_value_t *@var{result}}, @w{time_value_t *@var{addend}})
5648: Add the values in @var{addend} to @var{result}. If both are normalized,
5649: @var{result} will be normalized afterwards.
5650: @end defmac
5651:
5652: A variable of type @code{time_value_t} can either represent a duration
5653: or a fixed point in time. In the latter case, it shall be interpreted as
5654: the number of seconds and microseconds after the epoch 1. Jan 1970.
5655:
5656: @deftypefun kern_return_t host_get_time (@w{host_t @var{host}}, @w{time_value_t *@var{current_time}})
5657: Get the current time as seen by @var{host}. On success, the time passed
5658: since the epoch is returned in @var{current_time}.
5659: @end deftypefun
5660:
5661: @deftypefun kern_return_t host_set_time (@w{host_priv_t @var{host_priv}}, @w{time_value_t @var{new_time}})
5662: Set the time of @var{host_priv} to @var{new_time}.
5663: @end deftypefun
5664:
5665: @deftypefun kern_return_t host_adjust_time (@w{host_priv_t @var{host_priv}}, @w{time_value_t @var{new_adjustment}}, @w{time_value_t *@var{old_adjustment}})
5666: Arrange for the current time as seen by @var{host_priv} to be gradually
5667: changed by the adjustment value @var{new_adjustment}, and return the old
5668: adjustment value in @var{old_adjustment}.
5669: @end deftypefun
5670:
5671: For efficiency, the current time is available through a mapped-time
5672: interface.
5673:
5674: @deftp {Data type} mapped_time_value_t
5675: This structure defines the mapped-time interface. It has the following
5676: members:
5677:
5678: @table @code
5679: @item integer_t seconds
5680: The number of seconds.
5681:
5682: @item integer_t microseconds
5683: The number of microseconds.
5684:
5685: @item integer_t check_seconds
5686: This is a copy of the seconds value, which must be checked to protect
5687: against a race condition when reading out the two time values.
5688: @end table
5689: @end deftp
5690:
5691: Here is an example how to read out the current time using the
5692: mapped-time interface:
5693:
5694: @c XXX Complete the example.
5695: @example
5696: do
5697: @{
5698: secs = mtime->seconds;
5699: usecs = mtime->microseconds;
5700: @}
5701: while (secs != mtime->check_seconds);
5702: @end example
5703:
5704:
5705: @node Host Reboot
5706: @section Host Reboot
5707:
5708: @deftypefun kern_return_t host_reboot (@w{host_priv_t @var{host_priv}}, @w{int @var{options}})
5709: Reboot the host specified by @var{host_priv}. The argument
5710: @var{options} specifies the flags. The available flags are defined in
5711: @file{sys/reboot.h}:
5712:
5713: @table @code
5714: @item RB_HALT
5715: Do not reboot, but halt the machine.
5716:
5717: @item RB_DEBUGGER
5718: Do not reboot, but enter kernel debugger from user space.
5719: @end table
5720:
5721: If successful, the function might not return.
5722: @end deftypefun
5723:
5724:
5725: @node Processors and Processor Sets
5726: @chapter Processors and Processor Sets
5727:
5728: This section describes the Mach interface to processor sets and
5729: individual processors. The interface allows to group processors into
5730: sets and control the processors and processor sets.
5731:
5732: A processor is not a central part of the interface. It is mostly of
5733: relevance as a part of a processor set. Threads are always assigned to
5734: processor sets, and all processors in a set are equally involved in
5735: executing all threads assigned to that set.
5736:
5737: The processor set is represented by two ports, a name port
5738: @var{processor_set_name} used to query information about the host
5739: accessible to everyone, and a control port @var{processor_set} used to
5740: manipulate it.
5741:
5742: @menu
5743: * Processor Set Interface:: How to work with processor sets.
5744: * Processor Interface:: How to work with individual processors.
5745: @end menu
5746:
5747:
5748: @node Processor Set Interface
5749: @section Processor Set Interface
5750:
5751: @menu
5752: * Processor Set Ports:: Ports representing a processor set.
5753: * Processor Set Access:: How the processor sets are accessed.
5754: * Processor Set Creation:: How new processor sets are created.
5755: * Processor Set Destruction:: How processor sets are destroyed.
5756: * Tasks and Threads on Sets:: Assigning tasks, threads to processor sets.
5757: * Processor Set Priority:: Specifying the priority of a processor set.
5758: * Processor Set Policy:: Changing the processor set policies.
5759: * Processor Set Info:: Obtaining information about a processor set.
5760: @end menu
5761:
5762:
5763: @node Processor Set Ports
5764: @subsection Processor Set Ports
5765: @cindex processor set ports
5766: @cindex ports representing a processor set
5767:
5768: @cindex processor set name port
5769: @cindex port representing a processor set name
5770: @deftp {Data type} processor_set_name_t
5771: This is a @code{mach_port_t} and used to hold the port name of a
5772: processor set name port that names the processor set. Any task can get
5773: a send right to name port of a processor set. The processor set name
5774: port allows to get information about the processor set.
5775: @end deftp
5776:
5777: @cindex processor set port
5778: @deftp {Data type} processor_set_t
5779: This is a @code{mach_port_t} and used to hold the port name of a
5780: privileged processor set control port that represents the processor set.
5781: Operations on the processor set are implemented as remote procedure
5782: calls to the processor set port. The processor set port allows to
5783: manipulate the processor set.
5784: @end deftp
5785:
5786:
5787: @node Processor Set Access
5788: @subsection Processor Set Access
5789:
5790: @deftypefun kern_return_t host_processor_sets (@w{host_t @var{host}}, @w{processor_set_name_array_t *@var{processor_sets}}, @w{mach_msg_type_number_t *@var{processor_sets_count}})
5791: The function @code{host_processor_sets} gets send rights to the name
5792: port for each processor set currently assigned to @var{host}.
5793:
5794: @code{host_processor_set_priv} can be used to obtain the control ports
5795: from these if desired. @var{processor_sets} is an array that is
5796: created as a result of this call. The caller may wish to
5797: @code{vm_deallocate} this array when the data is no longer needed.
5798: @var{processor_sets_count} is set to the number of processor sets in the
5799: @var{processor_sets}.
5800:
5801: This function returns @code{KERN_SUCCESS} if the call succeeded and
5802: @code{KERN_INVALID_ARGUMENT} if @var{host} is not a host.
5803: @end deftypefun
5804:
5805: @deftypefun kern_return_t host_processor_set_priv (@w{host_priv_t @var{host_priv}}, @w{processor_set_name_t @var{set_name}}, @w{processor_set_t *@var{set}})
5806: The function @code{host_processor_set_priv} allows a privileged
5807: application to obtain the control port @var{set} for an existing
5808: processor set from its name port @var{set_name}. The privileged host
5809: port @var{host_priv} is required.
5810:
5811: This function returns @code{KERN_SUCCESS} if the call succeeded and
5812: @code{KERN_INVALID_ARGUMENT} if @var{host_priv} is not a valid host
5813: control port.
5814: @end deftypefun
5815:
5816: @deftypefun kern_return_t processor_set_default (@w{host_t @var{host}}, @w{processor_set_name_t *@var{default_set}})
5817: The function @code{processor_set_default} returns the default processor
5818: set of @var{host} in @var{default_set}. The default processor set is
5819: used by all threads, tasks, and processors that are not explicitly
5820: assigned to other sets. processor_set_default returns a port that can
5821: be used to obtain information about this set (e.g. how many threads are
5822: assigned to it). This port cannot be used to perform operations on that
5823: set.
5824:
5825: This function returns @code{KERN_SUCCESS} if the call succeeded,
5826: @code{KERN_INVALID_ARGUMENT} if @var{host} is not a host and
5827: @code{KERN_INVALID_ADDRESS} if @var{default_set} points to
5828: inaccessible memory.
5829: @end deftypefun
5830:
5831:
5832: @node Processor Set Creation
5833: @subsection Processor Set Creation
5834:
5835: @deftypefun kern_return_t processor_set_create (@w{host_t @var{host}}, @w{processor_set_t *@var{new_set}}, @w{processor_set_name_t *@var{new_name}})
5836: The function @code{processor_set_create} creates a new processor set on
5837: @var{host} and returns the two ports associated with it. The port
5838: returned in @var{new_set} is the actual port representing the set. It
5839: is used to perform operations such as assigning processors, tasks, or
5840: threads. The port returned in @var{new_name} identifies the set, and is
5841: used to obtain information about the set.
5842:
5843: This function returns @code{KERN_SUCCESS} if the call succeeded,
5844: @code{KERN_INVALID_ARGUMENT} if @var{host} is not a host,
5845: @code{KERN_INVALID_ADDRESS} if @var{new_set} or @var{new_name} points to
5846: inaccessible memory and @code{KERN_FAILURE} is the operating system does
5847: not support processor allocation.
5848: @end deftypefun
5849:
5850:
5851: @node Processor Set Destruction
5852: @subsection Processor Set Destruction
5853:
5854: @deftypefun kern_return_t processor_set_destroy (@w{processor_set_t @var{processor_set}})
5855: The function @code{processor_set_destroy} destroys the specified
5856: processor set. Any assigned processors, tasks, or threads are
5857: reassigned to the default set. The object port for the processor set is
5858: required (not the name port). The default processor set cannot be
5859: destroyed.
5860:
5861: This function returns @code{KERN_SUCCESS} if the set was destroyed,
5862: @code{KERN_FAILURE} if an attempt was made to destroy the default
5863: processor set, or the operating system does not support processor
5864: allocation, and @code{KERN_INVALID_ARGUMENT} if @var{processor_set} is
5865: not a valid processor set control port.
5866: @end deftypefun
5867:
5868:
5869: @node Tasks and Threads on Sets
5870: @subsection Tasks and Threads on Sets
5871:
5872: @deftypefun kern_return_t processor_set_tasks (@w{processor_set_t @var{processor_set}}, @w{task_array_t *@var{task_list}}, @w{mach_msg_type_number_t *@var{task_count}})
5873: The function @code{processor_set_tasks} gets send rights to the kernel
5874: port for each task currently assigned to @var{processor_set}.
5875:
5876: @var{task_list} is an array that is created as a result of this call.
5877: The caller may wish to @code{vm_deallocate} this array when the data is
5878: no longer needed. @var{task_count} is set to the number of tasks in the
5879: @var{task_list}.
5880:
5881: This function returns @code{KERN_SUCCESS} if the call succeeded and
5882: @code{KERN_INVALID_ARGUMENT} if @var{processor_set} is not a processor
5883: set.
5884: @end deftypefun
5885:
5886: @deftypefun kern_return_t processor_set_threads (@w{processor_set_t @var{processor_set}}, @w{thread_array_t *@var{thread_list}}, @w{mach_msg_type_number_t *@var{thread_count}})
5887: The function @code{processor_set_thread} gets send rights to the kernel
5888: port for each thread currently assigned to @var{processor_set}.
5889:
5890: @var{thread_list} is an array that is created as a result of this call.
5891: The caller may wish to @code{vm_deallocate} this array when the data is
5892: no longer needed. @var{thread_count} is set to the number of threads in
5893: the @var{thread_list}.
5894:
5895: This function returns @code{KERN_SUCCESS} if the call succeeded and
5896: @code{KERN_INVALID_ARGUMENT} if @var{processor_set} is not a processor
5897: set.
5898: @end deftypefun
5899:
5900: @deftypefun kern_return_t task_assign (@w{task_t @var{task}}, @w{processor_set_t @var{processor_set}}, @w{boolean_t @var{assign_threads}})
5901: The function @code{task_assign} assigns @var{task} the set
5902: @var{processor_set}. This assignment is for the purposes of determining
5903: the initial assignment of newly created threads in task. Any previous
5904: assignment of the task is nullified. Existing threads within the task
5905: are also reassigned if @var{assign_threads} is @code{TRUE}. They are
5906: not affected if it is @code{FALSE}.
5907:
5908: This function returns @code{KERN_SUCCESS} if the assignment has been
5909: performed and @code{KERN_INVALID_ARGUMENT} if @var{task} is not a task,
5910: or @var{processor_set} is not a processor set on the same host as
5911: @var{task}.
5912: @end deftypefun
5913:
5914: @deftypefun kern_return_t task_assign_default (@w{task_t @var{task}}, @w{boolean_t @var{assign_threads}})
5915: The function @code{task_assign_default} is a variant of
5916: @code{task_assign} that assigns the task to the default processor set on
5917: that task's host. This variant exists because the control port for the
1.1.1.2 root 5918: default processor set is privileged and not usually available to users.
1.1 root 5919:
5920: This function returns @code{KERN_SUCCESS} if the assignment has been
5921: performed and @code{KERN_INVALID_ARGUMENT} if @var{task} is not a task.
5922: @end deftypefun
5923:
5924: @deftypefun kern_return_t task_get_assignment (@w{task_t @var{task}}, @w{processor_set_name_t *@var{assigned_set}})
5925: The function @code{task_get_assignment} returns the name of the
5926: processor set to which the thread is currently assigned in
5927: @var{assigned_set}. This port can only be used to obtain information
5928: about the processor set.
5929:
5930: This function returns @code{KERN_SUCCESS} if the assignment has been
5931: performed, @code{KERN_INVALID_ADDRESS} if @var{processor_set} points to
5932: inaccessible memory, and @code{KERN_INVALID_ARGUMENT} if @var{task} is
5933: not a task.
5934: @end deftypefun
5935:
5936: @deftypefun kern_return_t thread_assign (@w{thread_t @var{thread}}, @w{processor_set_t @var{processor_set}})
5937: The function @code{thread_assign} assigns @var{thread} the set
5938: @var{processor_set}. After the assignment is completed, the thread only
5939: executes on processors assigned to the designated processor set. If
5940: there are no such processors, then the thread is unable to execute. Any
5941: previous assignment of the thread is nullified. Unix system call
5942: compatibility code may temporarily force threads to execute on the
5943: master processor.
5944:
5945: This function returns @code{KERN_SUCCESS} if the assignment has been
5946: performed and @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a
5947: thread, or @var{processor_set} is not a processor set on the same host
5948: as @var{thread}.
5949: @end deftypefun
5950:
5951: @deftypefun kern_return_t thread_assign_default (@w{thread_t @var{thread}})
5952: The function @code{thread_assign_default} is a variant of
5953: @code{thread_assign} that assigns the thread to the default processor
5954: set on that thread's host. This variant exists because the control port
1.1.1.2 root 5955: for the default processor set is privileged and not usually available
1.1 root 5956: to users.
5957:
5958: This function returns @code{KERN_SUCCESS} if the assignment has been
5959: performed and @code{KERN_INVALID_ARGUMENT} if @var{thread} is not a
5960: thread.
5961: @end deftypefun
5962:
5963: @deftypefun kern_return_t thread_get_assignment (@w{thread_t @var{thread}}, @w{processor_set_name_t *@var{assigned_set}})
5964: The function @code{thread_get_assignment} returns the name of the
5965: processor set to which the thread is currently assigned in
5966: @var{assigned_set}. This port can only be used to obtain information
5967: about the processor set.
5968:
5969: This function returns @code{KERN_SUCCESS} if the assignment has been
5970: performed, @code{KERN_INVALID_ADDRESS} if @var{processor_set} points to
5971: inaccessible memory, and @code{KERN_INVALID_ARGUMENT} if @var{thread} is
5972: not a thread.
5973: @end deftypefun
5974:
5975:
5976: @node Processor Set Priority
5977: @subsection Processor Set Priority
5978:
5979: @deftypefun kern_return_t processor_set_max_priority (@w{processor_set_t @var{processor_set}}, @w{int @var{max_priority}}, @w{boolean_t @var{change_threads}})
5980: The function @code{processor_set_max_priority} is used to set the
5981: maximum priority for a processor set. The priority of a processor set
5982: is used only for newly created threads (thread's maximum priority is set
5983: to processor set's) and the assignment of threads to the set (thread's
5984: maximum priority is reduced if it exceeds the set's maximum priority,
5985: thread's priority is similarly reduced).
5986: @code{processor_set_max_priority} changes this priority. It also sets
5987: the maximum priority of all threads assigned to the processor set to
5988: this new priority if @var{change_threads} is @code{TRUE}. If this
5989: maximum priority is less than the priorities of any of these threads,
5990: their priorities will also be set to this new value.
5991:
5992: This function returns @code{KERN_SUCCESS} if the call succeeded and
5993: @code{KERN_INVALID_ARGUMENT} if @var{processor_set} is not a processor
5994: set or @var{priority} is not a valid priority.
5995: @end deftypefun
5996:
5997:
5998: @node Processor Set Policy
5999: @subsection Processor Set Policy
6000:
6001: @deftypefun kern_return_t processor_set_policy_enable (@w{processor_set_t @var{processor_set}}, @w{int @var{policy}})
6002: @deftypefunx kern_return_t processor_set_policy_disable (@w{processor_set_t @var{processor_set}}, @w{int @var{policy}}, @w{boolean_t @var{change_threads}})
6003: Processor sets may restrict the scheduling policies to be used for
6004: threads assigned to them. These two calls provide the mechanism for
6005: designating permitted and forbidden policies. The current set of
6006: permitted policies can be obtained from @code{processor_set_info}.
6007: Timesharing may not be forbidden by any processor set. This is a
6008: compromise to reduce the complexity of the assign operation; any thread
6009: whose policy is forbidden by the target processor set has its policy
6010: reset to timesharing. If the @var{change_threads} argument to
6011: @code{processor_set_policy_disable} is true, threads currently assigned
6012: to this processor set and using the newly disabled policy will have
6013: their policy reset to timesharing.
6014:
6015: @file{mach/policy.h} contains the allowed policies; it is included by
6016: @file{mach.h}. Not all policies (e.g. fixed priority) are supported by
6017: all systems.
6018:
6019: This function returns @code{KERN_SUCCESS} if the operation was completed
6020: successfully and @code{KERN_INVALID_ARGUMENT} if @var{processor_set} is
6021: not a processor set or @var{policy} is not a valid policy, or an attempt
6022: was made to disable timesharing.
6023: @end deftypefun
6024:
6025:
6026: @node Processor Set Info
6027: @subsection Processor Set Info
6028:
6029: @deftypefun kern_return_t processor_set_info (@w{processor_set_name_t @var{set_name}}, @w{int @var{flavor}}, @w{host_t *@var{host}}, @w{processor_set_info_t @var{processor_set_info}}, @w{mach_msg_type_number_t *@var{processor_set_info_count}})
6030: The function @code{processor_set_info} returns the selected information array
6031: for a processor set, as specified by @var{flavor}.
6032:
6033: @var{host} is set to the host on which the processor set resides. This
6034: is the non-privileged host port.
6035:
6036: @var{processor_set_info} is an array of integers that is supplied by the
6037: caller and returned filled with specified information.
6038: @var{processor_set_info_count} is supplied as the maximum number of
6039: integers in @var{processor_set_info}. On return, it contains the actual
6040: number of integers in @var{processor_set_info}. The maximum number of
6041: integers returned by any flavor is @code{PROCESSOR_SET_INFO_MAX}.
6042:
6043: The type of information returned is defined by @var{flavor}, which can
6044: be one of the following:
6045:
6046: @table @code
6047: @item PROCESSOR_SET_BASIC_INFO
6048: The function returns basic information about the processor set, as
6049: defined by @code{processor_set_basic_info_t}. This includes the number
6050: of tasks and threads assigned to the processor set. The number of
6051: integers returned is @code{PROCESSOR_SET_BASIC_INFO_COUNT}.
6052:
6053: @item PROCESSOR_SET_SCHED_INFO
1.1.1.2 root 6054: The function returns information about the scheduling policy for the
1.1 root 6055: processor set as defined by @code{processor_set_sched_info_t}. The
6056: number of integers returned is @code{PROCESSOR_SET_SCHED_INFO_COUNT}.
6057: @end table
6058:
6059: Some machines may define additional (machine-dependent) flavors.
6060:
6061: The function returns @code{KERN_SUCCESS} if the call succeeded and
6062: @code{KERN_INVALID_ARGUMENT} if @var{processor_set} is not a processor
6063: set or @var{flavor} is not recognized. The function returns
6064: @code{MIG_ARRAY_TOO_LARGE} if the returned info array is too large for
6065: @var{processor_set_info}. In this case, @var{processor_set_info} is
6066: filled as much as possible and @var{processor_set_info_count} is set to the
6067: number of elements that would have been returned if there were enough
6068: room.
6069: @end deftypefun
6070:
6071: @deftp {Data type} {struct processor_set_basic_info}
6072: This structure is returned in @var{processor_set_info} by the
6073: @code{processor_set_info} function and provides basic information about
6074: the processor set. You can cast a variable of type
6075: @code{processor_set_info_t} to a pointer of this type if you provided it
6076: as the @var{processor_set_info} parameter for the
6077: @code{PROCESSOR_SET_BASIC_INFO} flavor of @code{processor_set_info}. It
6078: has the following members:
6079:
6080: @table @code
6081: @item int processor_count
6082: number of processors
6083:
6084: @item int task_count
6085: number of tasks
6086:
6087: @item int thread_count
6088: number of threads
6089:
6090: @item int load_average
6091: scaled load average
6092:
6093: @item int mach_factor
6094: scaled mach factor
6095: @end table
6096: @end deftp
6097:
6098: @deftp {Data type} processor_set_basic_info_t
6099: This is a pointer to a @code{struct processor_set_basic_info}.
6100: @end deftp
6101:
6102: @deftp {Data type} {struct processor_set_sched_info}
6103: This structure is returned in @var{processor_set_info} by the
6104: @code{processor_set_info} function and provides schedule information
6105: about the processor set. You can cast a variable of type
6106: @code{processor_set_info_t} to a pointer of this type if you provided it
6107: as the @var{processor_set_info} parameter for the
6108: @code{PROCESSOR_SET_SCHED_INFO} flavor of @code{processor_set_info}. It
6109: has the following members:
6110:
6111: @table @code
6112: @item int policies
6113: allowed policies
6114:
6115: @item int max_priority
6116: max priority for new threads
6117: @end table
6118: @end deftp
6119:
6120: @deftp {Data type} processor_set_sched_info_t
6121: This is a pointer to a @code{struct processor_set_sched_info}.
6122: @end deftp
6123:
6124:
6125: @node Processor Interface
6126: @section Processor Interface
6127:
6128: @cindex processor port
6129: @cindex port representing a processor
6130: @deftp {Data type} processor_t
6131: This is a @code{mach_port_t} and used to hold the port name of a
6132: processor port that represents the processor. Operations on the
6133: processor are implemented as remote procedure calls to the processor
6134: port.
6135: @end deftp
6136:
6137: @menu
6138: * Hosted Processors:: Getting a list of all processors on a host.
6139: * Processor Control:: Starting, stopping, controlling processors.
6140: * Processors and Sets:: Combining processors into processor sets.
6141: * Processor Info:: Obtaining information on processors.
6142: @end menu
6143:
6144:
6145: @node Hosted Processors
6146: @subsection Hosted Processors
6147:
6148: @deftypefun kern_return_t host_processors (@w{host_priv_t @var{host_priv}}, @w{processor_array_t *@var{processor_list}}, @w{mach_msg_type_number_t *@var{processor_count}})
6149: The function @code{host_processors} gets send rights to the processor
6150: port for each processor existing on @var{host_priv}. This is the
6151: privileged port that allows its holder to control a processor.
6152:
6153: @var{processor_list} is an array that is created as a result of this
6154: call. The caller may wish to @code{vm_deallocate} this array when the
6155: data is no longer needed. @var{processor_count} is set to the number of
6156: processors in the @var{processor_list}.
6157:
6158: This function returns @code{KERN_SUCCESS} if the call succeeded,
6159: @code{KERN_INVALID_ARGUMENT} if @var{host_priv} is not a privileged host
6160: port, and @code{KERN_INVALID_ADDRESS} if @var{processor_count} points to
6161: inaccessible memory.
6162: @end deftypefun
6163:
6164:
6165: @node Processor Control
6166: @subsection Processor Control
6167:
6168: @deftypefun kern_return_t processor_start (@w{processor_t @var{processor}})
6169: @deftypefunx kern_return_t processor_exit (@w{processor_t @var{processor}})
6170: @deftypefunx kern_return_t processor_control (@w{processor_t @var{processor}}, @w{processor_info_t *@var{cmd}}, @w{mach_msg_type_number_t @var{count}})
6171: Some multiprocessors may allow privileged software to control
6172: processors. The @code{processor_start}, @code{processor_exit}, and
6173: @code{processor_control} operations implement this. The interpretation
6174: of the command in @var{cmd} is machine dependent. A newly started
6175: processor is assigned to the default processor set. An exited processor
6176: is removed from the processor set to which it was assigned and ceases to
6177: be active.
6178:
6179: @var{count} contains the length of the command @var{cmd} as a number of
6180: ints.
6181:
6182: Availability limited. All of these operations are machine-dependent.
6183: They may do nothing. The ability to restart an exited processor is also
6184: machine-dependent.
6185:
6186: This function returns @code{KERN_SUCCESS} if the operation was
6187: performed, @code{KERN_FAILURE} if the operation was not performed (a
6188: likely reason is that it is not supported on this processor),
6189: @code{KERN_INVALID_ARGUMENT} if @var{processor} is not a processor, and
6190: @code{KERN_INVALID_ADDRESS} if @var{cmd} points to inaccessible memory.
6191: @end deftypefun
6192:
6193: @node Processors and Sets
6194: @subsection Processors and Sets
6195:
6196: @deftypefun kern_return_t processor_assign (@w{processor_t @var{processor}}, @w{processor_set_t @var{processor_set}}, @w{boolean_t @var{wait}})
1.1.1.2 root 6197: The function @code{processor_assign} assigns @var{processor} to the
1.1 root 6198: set @var{processor_set}. After the assignment is completed, the
6199: processor only executes threads that are assigned to that processor set.
6200: Any previous assignment of the processor is nullified. The master
6201: processor cannot be reassigned. All processors take clock interrupts at
6202: all times. The @var{wait} argument indicates whether the caller should
6203: wait for the assignment to be completed or should return immediately.
6204: Dedicated kernel threads are used to perform processor assignment, so
6205: setting wait to @code{FALSE} allows assignment requests to be queued and
6206: performed faster, especially if the kernel has more than one dedicated
6207: internal thread for processor assignment. Redirection of other device
6208: interrupts away from processors assigned to other than the default
6209: processor set is machine-dependent. Intermediaries that interpose on
6210: ports must be sure to interpose on both ports involved in this call if
6211: they interpose on either.
6212:
6213: This function returns @code{KERN_SUCCESS} if the assignment has been
6214: performed, @code{KERN_INVALID_ARGUMENT} if @var{processor} is not a
6215: processor, or @var{processor_set} is not a processor set on the same
6216: host as @var{processor}.
6217: @end deftypefun
6218:
6219: @deftypefun kern_return_t processor_get_assignment (@w{processor_t @var{processor}}, @w{processor_set_name_t *@var{assigned_set}})
6220: The function @code{processor_get_assignment} obtains the current
6221: assignment of a processor. The name port of the processor set is
6222: returned in @var{assigned_set}.
6223: @end deftypefun
6224:
6225: @node Processor Info
6226: @subsection Processor Info
6227:
6228: @deftypefun kern_return_t processor_info (@w{processor_t @var{processor}}, @w{int @var{flavor}}, @w{host_t *@var{host}}, @w{processor_info_t @var{processor_info}}, @w{mach_msg_type_number_t *@var{processor_info_count}})
6229: The function @code{processor_info} returns the selected information array
6230: for a processor, as specified by @var{flavor}.
6231:
6232: @var{host} is set to the host on which the processor set resides. This
6233: is the non-privileged host port.
6234:
6235: @var{processor_info} is an array of integers that is supplied by the
6236: caller and returned filled with specified information.
6237: @var{processor_info_count} is supplied as the maximum number of integers in
6238: @var{processor_info}. On return, it contains the actual number of
6239: integers in @var{processor_info}. The maximum number of integers
6240: returned by any flavor is @code{PROCESSOR_INFO_MAX}.
6241:
6242: The type of information returned is defined by @var{flavor}, which can
6243: be one of the following:
6244:
6245: @table @code
6246: @item PROCESSOR_BASIC_INFO
6247: The function returns basic information about the processor, as defined
6248: by @code{processor_basic_info_t}. This includes the slot number of the
6249: processor. The number of integers returned is
6250: @code{PROCESSOR_BASIC_INFO_COUNT}.
6251: @end table
6252:
6253: Machines which require more configuration information beyond the slot
6254: number are expected to define additional (machine-dependent) flavors.
6255:
6256: The function returns @code{KERN_SUCCESS} if the call succeeded and
6257: @code{KERN_INVALID_ARGUMENT} if @var{processor} is not a processor or
6258: @var{flavor} is not recognized. The function returns
6259: @code{MIG_ARRAY_TOO_LARGE} if the returned info array is too large for
6260: @var{processor_info}. In this case, @var{processor_info} is filled as
6261: much as possible and @var{processor_infoCnt} is set to the number of
6262: elements that would have been returned if there were enough room.
6263: @end deftypefun
6264:
6265: @deftp {Data type} {struct processor_basic_info}
6266: This structure is returned in @var{processor_info} by the
6267: @code{processor_info} function and provides basic information about the
6268: processor. You can cast a variable of type @code{processor_info_t} to a
6269: pointer of this type if you provided it as the @var{processor_info}
6270: parameter for the @code{PROCESSOR_BASIC_INFO} flavor of
6271: @code{processor_info}. It has the following members:
6272:
6273: @table @code
6274: @item cpu_type_t cpu_type
6275: cpu type
6276:
6277: @item cpu_subtype_t cpu_subtype
6278: cpu subtype
6279:
6280: @item boolean_t running
6281: is processor running?
6282:
6283: @item int slot_num
6284: slot number
6285:
6286: @item boolean_t is_master
6287: is this the master processor
6288: @end table
6289: @end deftp
6290:
6291: @deftp {Data type} processor_basic_info_t
6292: This is a pointer to a @code{struct processor_basic_info}.
6293: @end deftp
6294:
6295:
6296: @node Device Interface
6297: @chapter Device Interface
6298:
6299: The GNU Mach microkernel provides a simple device interface that allows
6300: the user space programs to access the underlying hardware devices. Each
6301: device has a unique name, which is a string up to 127 characters long.
6302: To open a device, the device master port has to be supplied. The device
6303: master port is only available through the bootstrap port. Anyone who
6304: has control over the device master port can use all hardware devices.
6305: @c XXX FIXME bootstrap port, bootstrap
6306:
6307: @cindex device port
6308: @cindex port representing a device
6309: @deftp {Data type} device_t
6310: This is a @code{mach_port_t} and used to hold the port name of a
6311: device port that represents the device. Operations on the device are
6312: implemented as remote procedure calls to the device port. Each device
6313: provides a sequence of records. The length of a record is specific to
6314: the device. Data can be transferred ``out-of-line'' or ``in-line''
6315: (@pxref{Memory}).
6316: @end deftp
6317:
6318: All constants and functions in this chapter are defined in
6319: @file{device/device.h}.
6320:
6321: @menu
6322: * Device Reply Server:: Handling device reply messages.
6323: * Device Open:: Opening hardware devices.
6324: * Device Close:: Closing hardware devices.
6325: * Device Read:: Reading data from the device.
6326: * Device Write:: Writing data to the device.
6327: * Device Map:: Mapping devices into virtual memory.
6328: * Device Status:: Querying and manipulating a device.
6329: * Device Filter:: Filtering packets arriving on a device.
6330: @end menu
6331:
6332:
6333: @node Device Reply Server
6334: @section Device Reply Server
6335:
6336: Beside the usual synchronous interface, an asynchronous interface is
6337: provided. For this, the caller has to receive and handle the reply
1.1.1.2 root 6338: messages separately from the function call.
1.1 root 6339:
6340: @deftypefun boolean_t device_reply_server (@w{msg_header_t *@var{in_msg}}, @w{msg_header_t *@var{out_msg}})
6341: The function @code{device_reply_server} is produced by the
6342: remote procedure call generator to handle a received message. This
6343: function does all necessary argument handling, and actually calls one of
6344: the following functions: @code{ds_device_open_reply},
6345: @code{ds_device_read_reply}, @code{ds_device_read_reply_inband},
6346: @code{ds_device_write_reply} and @code{ds_device_write_reply_inband}.
6347:
6348: The @var{in_msg} argument is the message that has been received from the
6349: kernel. The @var{out_msg} is a reply message, but this is not used for
6350: this server.
6351:
6352: The function returns @code{TRUE} to indicate that the message in
6353: question was applicable to this interface, and that the appropriate
6354: routine was called to interpret the message. It returns @code{FALSE} to
6355: indicate that the message did not apply to this interface, and that no
6356: other action was taken.
6357: @end deftypefun
6358:
6359:
6360: @node Device Open
6361: @section Device Open
6362:
6363: @deftypefun kern_return_t device_open (@w{mach_port_t @var{master_port}}, @w{dev_mode_t @var{mode}}, @w{dev_name_t @var{name}}, @w{device_t *@var{device}})
6364: The function @code{device_open} opens the device @var{name} and returns
6365: a port to it in @var{device}. The open count for the device is
6366: incremented by one. If the open count was 0, the open handler for the
6367: device is invoked.
6368:
6369: @var{master_port} must hold the master device port. @var{name}
6370: specifies the device to open, and is a string up to 128 characters long.
6371: @var{mode} is the open mode. It is a bitwise-or of the following
6372: constants:
6373:
6374: @table @code
6375: @item D_READ
6376: Request read access for the device.
6377:
6378: @item D_WRITE
6379: Request write access for the device.
6380:
6381: @item D_NODELAY
6382: Do not delay an open.
6383: @c XXX Is this really used at all? Maybe for tape drives? What does it mean?
6384: @end table
6385:
6386: The function returns @code{D_SUCCESS} if the device was successfully
6387: opened, @code{D_INVALID_OPERATION} if @var{master_port} is not the
6388: master device port, @code{D_WOULD_BLOCK} is the device is busy and
6389: @code{D_NOWAIT} was specified in mode, @code{D_ALREADY_OPEN} if the
6390: device is already open in an incompatible mode and
6391: @code{D_NO_SUCH_DEVICE} if @var{name} does not denote a know device.
6392: @end deftypefun
6393:
6394: @deftypefun kern_return_t device_open_request (@w{mach_port_t @var{master_port}}, @w{mach_port_t @var{reply_port}}, @w{dev_mode_t @var{mode}}, @w{dev_name_t @var{name}})
6395: @deftypefunx kern_return_t ds_device_open_reply (@w{mach_port_t @var{reply_port}}, @w{kern_return_t @var{return}}, @w{device_t *@var{device}})
6396: This is the asynchronous form of the @code{device_open} function.
6397: @code{device_open_request} performs the open request. The meaning for
6398: the parameters is as in @code{device_open}. Additionally, the caller
6399: has to supply a reply port to which the @code{ds_device_open_reply}
6400: message is sent by the kernel when the open has been performed. The
6401: return value of the open operation is stored in @var{return_code}.
6402:
6403: As neither function receives a reply message, only message transmission
6404: errors apply. If no error occurs, @code{KERN_SUCCESS} is returned.
6405: @end deftypefun
6406:
6407:
6408: @node Device Close
6409: @section Device Close
6410:
6411: @deftypefun kern_return_t device_close (@w{device_t @var{device}})
6412: The function @code{device_close} decrements the open count of the device
6413: by one. If the open count drops to zero, the close handler for the
6414: device is called. The device to close is specified by its port
6415: @var{device}.
6416:
6417: The function returns @code{D_SUCCESS} if the device was successfully
6418: closed and @code{D_NO_SUCH_DEVICE} if @var{device} does not denote a
6419: device port.
6420: @end deftypefun
6421:
6422:
6423: @node Device Read
6424: @section Device Read
6425:
6426: @deftypefun kern_return_t device_read (@w{device_t @var{device}}, @w{dev_mode_t @var{mode}}, @w{recnum_t @var{recnum}}, @w{int @var{bytes_wanted}}, @w{io_buf_ptr_t *@var{data}}, @w{mach_msg_type_number_t *@var{data_count}})
6427: The function @code{device_read} reads @var{bytes_wanted} bytes from
6428: @var{device}, and stores them in a buffer allocated with
6429: @code{vm_allocate}, which address is returned in @var{data}. The caller
6430: must deallocated it if it is no longer needed. The number of bytes
6431: actually returned is stored in @var{data_count}.
6432:
6433: If @var{mode} is @code{D_NOWAIT}, the operation does not block.
6434: Otherwise @var{mode} should be 0. @var{recnum} is the record number to
6435: be read, its meaning is device specific.
6436:
6437: The function returns @code{D_SUCCESS} if some data was successfully
6438: read, @code{D_WOULD_BLOCK} if no data is currently available and
6439: @code{D_NOWAIT} is specified, and @code{D_NO_SUCH_DEVICE} if
6440: @var{device} does not denote a device port.
6441: @end deftypefun
6442:
6443: @deftypefun kern_return_t device_read_inband (@w{device_t @var{device}}, @w{dev_mode_t @var{mode}}, @w{recnum_t @var{recnum}}, @w{int @var{bytes_wanted}}, @w{io_buf_ptr_inband_t *@var{data}}, @w{mach_msg_type_number_t *@var{data_count}})
6444: The @code{device_read_inband} function works as the @code{device_read}
6445: function, except that the data is returned ``in-line'' in the reply IPC
6446: message (@pxref{Memory}).
6447: @end deftypefun
6448:
6449: @deftypefun kern_return_t device_read_request (@w{device_t @var{device}}, @w{mach_port_t @var{reply_port}}, @w{dev_mode_t @var{mode}}, @w{recnum_t @var{recnum}}, @w{int @var{bytes_wanted}})
6450: @deftypefunx kern_return_t ds_device_read_reply (@w{mach_port_t @var{reply_port}}, @w{kern_return_t @var{return_code}}, @w{io_buf_ptr_t @var{data}}, @w{mach_msg_type_number_t @var{data_count}})
6451: This is the asynchronous form of the @code{device_read} function.
6452: @code{device_read_request} performs the read request. The meaning for
6453: the parameters is as in @code{device_read}. Additionally, the caller
6454: has to supply a reply port to which the @code{ds_device_read_reply}
6455: message is sent by the kernel when the read has been performed. The
6456: return value of the read operation is stored in @var{return_code}.
6457:
6458: As neither function receives a reply message, only message transmission
6459: errors apply. If no error occurs, @code{KERN_SUCCESS} is returned.
6460: @end deftypefun
6461:
6462: @deftypefun kern_return_t device_read_request_inband (@w{device_t @var{device}}, @w{mach_port_t @var{reply_port}}, @w{dev_mode_t @var{mode}}, @w{recnum_t @var{recnum}}, @w{int @var{bytes_wanted}})
6463: @deftypefunx kern_return_t ds_device_read_reply_inband (@w{mach_port_t @var{reply_port}}, @w{kern_return_t @var{return_code}}, @w{io_buf_ptr_t @var{data}}, @w{mach_msg_type_number_t @var{data_count}})
6464: The @code{device_read_request_inband} and
6465: @code{ds_device_read_reply_inband} functions work as the
6466: @code{device_read_request} and @code{ds_device_read_reply} functions,
6467: except that the data is returned ``in-line'' in the reply IPC message
6468: (@pxref{Memory}).
6469: @end deftypefun
6470:
6471:
6472: @node Device Write
6473: @section Device Write
6474:
6475: @deftypefun kern_return_t device_write (@w{device_t @var{device}}, @w{dev_mode_t @var{mode}}, @w{recnum_t @var{recnum}}, @w{io_buf_ptr_t @var{data}}, @w{mach_msg_type_number_t @var{data_count}}, @w{int *@var{bytes_written}})
6476: The function @code{device_write} writes @var{data_count} bytes from the
6477: buffer @var{data} to @var{device}. The number of bytes actually written
6478: is returned in @var{bytes_written}.
6479:
6480: If @var{mode} is @code{D_NOWAIT}, the function returns without waiting
6481: for I/O completion. Otherwise @var{mode} should be 0. @var{recnum} is
6482: the record number to be written, its meaning is device specific.
6483:
6484: The function returns @code{D_SUCCESS} if some data was successfully
6485: written and @code{D_NO_SUCH_DEVICE} if @var{device} does not denote a
6486: device port or the device is dead or not completely open.
6487: @end deftypefun
6488:
6489: @deftypefun kern_return_t device_write_inband (@w{device_t @var{device}}, @w{dev_mode_t @var{mode}}, @w{recnum_t @var{recnum}}, @w{int @var{bytes_wanted}}, @w{io_buf_ptr_inband_t *@var{data}}, @w{mach_msg_type_number_t *@var{data_count}})
6490: The @code{device_write_inband} function works as the @code{device_write}
6491: function, except that the data is sent ``in-line'' in the request IPC
6492: message (@pxref{Memory}).
6493: @end deftypefun
6494:
6495: @deftypefun kern_return_t device_write_request (@w{device_t @var{device}}, @w{mach_port_t @var{reply_port}}, @w{dev_mode_t @var{mode}}, @w{recnum_t @var{recnum}}, @w{io_buf_ptr_t @var{data}}, @w{mach_msg_type_number_t @var{data_count}})
6496: @deftypefunx kern_return_t ds_device_write_reply (@w{mach_port_t @var{reply_port}}, @w{kern_return_t @var{return_code}}, @w{int @var{bytes_written}})
6497: This is the asynchronous form of the @code{device_write} function.
6498: @code{device_write_request} performs the write request. The meaning for
6499: the parameters is as in @code{device_write}. Additionally, the caller
6500: has to supply a reply port to which the @code{ds_device_write_reply}
6501: message is sent by the kernel when the write has been performed. The
6502: return value of the write operation is stored in @var{return_code}.
6503:
6504: As neither function receives a reply message, only message transmission
6505: errors apply. If no error occurs, @code{KERN_SUCCESS} is returned.
6506: @end deftypefun
6507:
6508: @deftypefun kern_return_t device_write_request_inband (@w{device_t @var{device}}, @w{mach_port_t @var{reply_port}}, @w{dev_mode_t @var{mode}}, @w{recnum_t @var{recnum}}, @w{io_buf_ptr_t @var{data}}, @w{mach_msg_type_number_t @var{data_count}})
6509: @deftypefunx kern_return_t ds_device_write_reply_inband (@w{mach_port_t @var{reply_port}}, @w{kern_return_t @var{return_code}}, @w{int @var{bytes_written}})
6510: The @code{device_write_request_inband} and
6511: @code{ds_device_write_reply_inband} functions work as the
6512: @code{device_write_request} and @code{ds_device_write_reply} functions,
6513: except that the data is sent ``in-line'' in the request IPC message
6514: (@pxref{Memory}).
6515: @end deftypefun
6516:
6517:
6518: @node Device Map
6519: @section Device Map
6520:
6521: @deftypefun kern_return_t device_map (@w{device_t @var{device}}, @w{vm_prot_t @var{prot}}, @w{vm_offset_t @var{offset}}, @w{vm_size_t @var{size}}, @w{mach_port_t *@var{pager}}, @w{int @var{unmap}})
6522: The function @code{device_map} creates a new memory manager for
6523: @var{device} and returns a port to it in @var{pager}. The memory
6524: manager is usable as a memory object in a @code{vm_map} call. The call
1.1.1.2 root 6525: is device dependent.
1.1 root 6526:
6527: The protection for the memory object is specified by @var{prot}. The
6528: memory object starts at @var{offset} within the device and extends
6529: @var{size} bytes. @var{unmap} is currently unused.
6530: @c XXX I suppose the caller should set it to 0.
6531:
6532: The function returns @code{D_SUCCESS} if some data was successfully
6533: written and @code{D_NO_SUCH_DEVICE} if @var{device} does not denote a
6534: device port or the device is dead or not completely open.
6535: @end deftypefun
6536:
6537:
6538: @node Device Status
6539: @section Device Status
6540:
6541: @deftypefun kern_return_t device_set_status (@w{device_t @var{device}}, @w{dev_flavor_t @var{flavor}}, @w{dev_status_t @var{status}}, @w{mach_msg_type_number_t @var{status_count}})
6542: The function @code{device_set_status} sets the status of a device. The
6543: possible values for @var{flavor} and their interpretation is device
6544: specific.
6545:
6546: The function returns @code{D_SUCCESS} if some data was successfully
6547: written and @code{D_NO_SUCH_DEVICE} if @var{device} does not denote a
6548: device port or the device is dead or not completely open.
6549: @end deftypefun
6550:
6551: @deftypefun kern_return_t device_get_status (@w{device_t @var{device}}, @w{dev_flavor_t @var{flavor}}, @w{dev_status_t @var{status}}, @w{mach_msg_type_number_t *@var{status_count}})
6552: The function @code{device_get_status} gets the status of a device. The
6553: possible values for @var{flavor} and their interpretation is device
6554: specific.
6555:
6556: The function returns @code{D_SUCCESS} if some data was successfully
6557: written and @code{D_NO_SUCH_DEVICE} if @var{device} does not denote a
6558: device port or the device is dead or not completely open.
6559: @end deftypefun
6560:
6561:
6562: @node Device Filter
6563: @section Device Filter
6564:
6565: @deftypefun kern_return_t device_set_filter (@w{device_t @var{device}}, @w{mach_port_t @var{receive_port}}, @w{mach_msg_type_name_t @var{receive_port_type}}, @w{int @var{priority}}, @w{filter_array_t @var{filter}}, @w{mach_msg_type_number_t @var{filter_count}})
6566: The function @code{device_set_filter} makes it possible to filter out
1.1.1.2 root 6567: selected data arriving at or leaving the device and forward it to a port.
1.1 root 6568: @var{filter} is a list of filter commands, which are applied to incoming
6569: data to determine if the data should be sent to @var{receive_port}. The
6570: IPC type of the send right is specified by @var{receive_port_right}, it
6571: is either @code{MACH_MSG_TYPE_MAKE_SEND} or
6572: @code{MACH_MSG_TYPE_MOVE_SEND}. The @var{priority} value is used to
6573: order multiple filters.
6574:
6575: There can be up to @code{NET_MAX_FILTER} commands in @var{filter}. The
6576: actual number of commands is passed in @var{filter_count}. For the
6577: purpose of the filter test, an internal stack is provided. After all
6578: commands have been processed, the value on the top of the stack
6579: determines if the data is forwarded or the next filter is tried.
6580:
1.1.1.2 root 6581: The first command is a header which contains two fields: one for flags
6582: and the other for the type of interpreter used to run the rest of the
6583: commands.
6584:
6585: Any combination of the following flags is allowed but at least one of them
6586: must be specified.
6587:
6588: @table @code
6589: @item NETF_IN
6590: The filter will be applied to data received by the device.
6591:
6592: @item NETF_OUT
6593: The filter will be applied to data transmitted by the device.
6594: @end table
6595:
6596: Unless the type is given explicitly the native NETF interpreter will be used.
6597: To select an alternative implementation use one of the following types:
6598:
6599: @table @code
6600: @item NETF_BPF
6601: Use Berkeley Packet Filter.
6602: @end table
6603:
6604: For the listener to know what kind of packet is being received, when the
6605: filter code accepts a packet the message sent to @var{receive_port} is
6606: tagged with either NETF_IN or NETF_OUT.
6607:
1.1 root 6608: @c XXX The following description was taken verbatim from the
6609: @c kernel_interface.pdf document.
6610: Each word of the command list specifies a data (push) operation (high
6611: order NETF_NBPO bits) as well as a binary operator (low order NETF_NBPA
6612: bits). The value to be pushed onto the stack is chosen as follows.
6613:
6614: @table @code
6615: @item NETF_PUSHLIT
6616: Use the next short word of the filter as the value.
6617:
6618: @item NETF_PUSHZERO
6619: Use 0 as the value.
6620:
6621: @item NETF_PUSHWORD+N
6622: Use short word N of the ``data'' portion of the message as the value.
6623:
6624: @item NETF_PUSHHDR+N
6625: Use short word N of the ``header'' portion of the message as the value.
6626:
6627: @item NETF_PUSHIND+N
6628: Pops the top long word from the stack and then uses short word N of the
6629: ``data'' portion of the message as the value.
6630:
6631: @item NETF_PUSHHDRIND+N
6632: Pops the top long word from the stack and then uses short word N of the
6633: ``header'' portion of the message as the value.
6634:
6635: @item NETF_PUSHSTK+N
6636: Use long word N of the stack (where the top of stack is long word 0) as
6637: the value.
6638:
6639: @item NETF_NOPUSH
6640: Don't push a value.
6641: @end table
6642:
6643: The unsigned value so chosen is promoted to a long word before being
6644: pushed. Once a value is pushed (except for the case of
6645: @code{NETF_NOPUSH}), the top two long words of the stack are popped and
6646: a binary operator applied to them (with the old top of stack as the
6647: second operand). The result of the operator is pushed on the stack.
6648: These operators are:
6649:
6650: @table @code
6651: @item NETF_NOP
6652: Don't pop off any values and do no operation.
6653:
6654: @item NETF_EQ
6655: Perform an equal comparison.
6656:
6657: @item NETF_LT
6658: Perform a less than comparison.
6659:
6660: @item NETF_LE
6661: Perform a less than or equal comparison.
6662:
6663: @item NETF_GT
6664: Perform a greater than comparison.
6665:
6666: @item NETF_GE
6667: Perform a greater than or equal comparison.
6668:
6669: @item NETF_AND
6670: Perform a bitise boolean AND operation.
6671:
6672: @item NETF_OR
6673: Perform a bitise boolean inclusive OR operation.
6674:
6675: @item NETF_XOR
6676: Perform a bitise boolean exclusive OR operation.
6677:
6678: @item NETF_NEQ
6679: Perform a not equal comparison.
6680:
6681: @item NETF_LSH
6682: Perform a left shift operation.
6683:
6684: @item NETF_RSH
6685: Perform a right shift operation.
6686:
6687: @item NETF_ADD
6688: Perform an addition.
6689:
6690: @item NETF_SUB
6691: Perform a subtraction.
6692:
6693: @item NETF_COR
6694: Perform an equal comparison. If the comparison is @code{TRUE}, terminate
6695: the filter list. Otherwise, pop the result of the comparison off the
6696: stack.
6697:
6698: @item NETF_CAND
6699: Perform an equal comparison. If the comparison is @code{FALSE},
6700: terminate the filter list. Otherwise, pop the result of the comparison
6701: off the stack.
6702:
6703: @item NETF_CNOR
6704: Perform a not equal comparison. If the comparison is @code{FALSE},
6705: terminate the filter list. Otherwise, pop the result of the comparison
6706: off the stack.
6707:
6708: @item NETF_CNAND
6709: Perform a not equal comparison. If the comparison is @code{TRUE},
6710: terminate the filter list. Otherwise, pop the result of the comparison
6711: off the stack. The scan of the filter list terminates when the filter
6712: list is emptied, or a @code{NETF_C...} operation terminates the list. At
6713: this time, if the final value of the top of the stack is @code{TRUE},
6714: then the message is accepted for the filter.
6715: @end table
6716:
6717: The function returns @code{D_SUCCESS} if some data was successfully
6718: written, @code{D_INVALID_OPERATION} if @var{receive_port} is not a valid
6719: send right, and @code{D_NO_SUCH_DEVICE} if @var{device} does not denote
6720: a device port or the device is dead or not completely open.
6721: @end deftypefun
6722:
6723:
6724: @node Kernel Debugger
6725: @chapter Kernel Debugger
6726:
6727: The GNU Mach kernel debugger @code{ddb} is a powerful built-in debugger
6728: with a gdb like syntax. It is enabled at compile time using the
6729: @option{--enable-kdb} option. Whenever you want to enter the debugger
6730: while running the kernel, you can press the key combination
6731: @key{Ctrl-Alt-D}.
6732:
6733: @menu
6734: * Operation:: Basic architecture of the kernel debugger.
6735: * Commands:: Available commands in the kernel debugger.
6736: * Variables:: Access of variables from the kernel debugger.
6737: * Expressions:: Usage of expressions in the kernel debugger.
6738: @end menu
6739:
6740:
6741: @node Operation
6742: @section Operation
6743:
6744: The current location is called @dfn{dot}. The dot is displayed with a
6745: hexadecimal format at a prompt. Examine and write commands update dot
6746: to the address of the last line examined or the last location modified,
6747: and set @dfn{next} to the address of the next location to be examined or
6748: changed. Other commands don't change dot, and set next to be the same
6749: as dot.
6750:
6751: The general command syntax is:
6752:
6753: @example
6754: @var{command}[/@var{modifier}] @var{address} [,@var{count}]
6755: @end example
6756:
6757: @kbd{!!} repeats the previous command, and a blank line repeats from the
6758: address next with count 1 and no modifiers. Specifying @var{address} sets
6759: dot to the address. Omitting @var{address} uses dot. A missing @var{count}
6760: is taken to be 1 for printing commands or infinity for stack traces.
6761:
6762: Current @code{ddb} is enhanced to support multi-thread debugging. A
6763: break point can be set only for a specific thread, and the address space
6764: or registers of non current thread can be examined or modified if
6765: supported by machine dependent routines. For example,
6766:
6767: @example
6768: break/t mach_msg_trap $task11.0
6769: @end example
6770:
6771: sets a break point at @code{mach_msg_trap} for the first thread of task
6772: 11 listed by a @code{show all threads} command.
6773:
6774: In the above example, @code{$task11.0} is translated to the
6775: corresponding thread structure's address by variable translation
6776: mechanism described later. If a default target thread is set in a
6777: variable @code{$thread}, the @code{$task11.0} can be omitted. In
6778: general, if @code{t} is specified in a modifier of a command line, a
6779: specified thread or a default target thread is used as a target thread
6780: instead of the current one. The @code{t} modifier in a command line is
6781: not valid in evaluating expressions in a command line. If you want to
6782: get a value indirectly from a specific thread's address space or access
6783: to its registers within an expression, you have to specify a default
6784: target thread in advance, and to use @code{:t} modifier immediately
6785: after the indirect access or the register reference like as follows:
6786:
6787: @example
6788: set $thread $task11.0
6789: print $eax:t *(0x100):tuh
6790: @end example
6791:
6792: No sign extension and indirection @code{size(long, half word, byte)} can
6793: be specified with @code{u}, @code{l}, @code{h} and @code{b} respectively
6794: for the indirect access.
6795:
6796: Note: Support of non current space/register access and user space break
6797: point depend on the machines. If not supported, attempts of such
6798: operation may provide incorrect information or may cause strange
6799: behavior. Even if supported, the user space access is limited to the
6800: pages resident in the main memory at that time. If a target page is not
6801: in the main memory, an error will be reported.
6802:
6803: @code{ddb} has a feature like a command @code{more} for the output. If
6804: an output line exceeds the number set in the @code{$lines} variable, it
6805: displays @samp{--db_more--} and waits for a response. The valid
6806: responses for it are:
6807:
6808: @table @kbd
6809: @item @key{SPC}
6810: one more page
6811:
6812: @item @key{RET}
6813: one more line
6814:
6815: @item q
6816: abort the current command, and return to the command input mode
6817: @end table
6818:
6819:
6820: @node Commands
6821: @section Commands
6822:
6823: @table @code
6824: @item examine(x) [/@var{modifier}] @var{addr}[,@var{count}] [ @var{thread} ]
6825: Display the addressed locations according to the formats in the
6826: modifier. Multiple modifier formats display multiple locations. If no
6827: format is specified, the last formats specified for this command is
6828: used. Address space other than that of the current thread can be
6829: specified with @code{t} option in the modifier and @var{thread}
6830: parameter. The format characters are
6831:
6832: @table @code
6833: @item b
6834: look at by bytes(8 bits)
6835:
6836: @item h
6837: look at by half words(16 bits)
6838:
6839: @item l
6840: look at by long words(32 bits)
6841:
6842: @item a
6843: print the location being displayed
6844:
6845: @item ,
6846: skip one unit producing no output
6847:
6848: @item A
6849: print the location with a line number if possible
6850:
6851: @item x
6852: display in unsigned hex
6853:
6854: @item z
6855: display in signed hex
6856:
6857: @item o
6858: display in unsigned octal
6859:
6860: @item d
6861: display in signed decimal
6862:
6863: @item u
6864: display in unsigned decimal
6865:
6866: @item r
6867: display in current radix, signed
6868:
6869: @item c
6870: display low 8 bits as a character. Non-printing characters are
6871: displayed as an octal escape code (e.g. '\000').
6872:
6873: @item s
6874: display the null-terminated string at the location. Non-printing
6875: characters are displayed as octal escapes.
6876:
6877: @item m
6878: display in unsigned hex with character dump at the end of each line.
6879: The location is also displayed in hex at the beginning of each line.
6880:
6881: @item i
6882: display as an instruction
6883:
6884: @item I
6885: display as an instruction with possible alternate formats depending on
6886: the machine:
6887:
6888: @table @code
6889: @item vax
6890: don't assume that each external label is a procedure entry mask
6891:
6892: @item i386
6893: don't round to the next long word boundary
6894:
6895: @item mips
6896: print register contents
6897: @end table
6898: @end table
6899:
6900: @item xf
6901: Examine forward. It executes an examine command with the last specified
6902: parameters to it except that the next address displayed by it is used as
6903: the start address.
6904:
6905: @item xb
6906: Examine backward. It executes an examine command with the last
6907: specified parameters to it except that the last start address subtracted
6908: by the size displayed by it is used as the start address.
6909:
6910: @item print[/axzodurc] @var{addr1} [ @var{addr2} @dots{} ]
6911: Print @var{addr}'s according to the modifier character. Valid formats
6912: are: @code{a} @code{x} @code{z} @code{o} @code{d} @code{u} @code{r}
6913: @code{c}. If no modifier is specified, the last one specified to it is
6914: used. @var{addr} can be a string, and it is printed as it is. For
6915: example,
6916:
6917: @example
6918: print/x "eax = " $eax "\necx = " $ecx "\n"
6919: @end example
6920:
6921: will print like
6922:
6923: @example
6924: eax = xxxxxx
6925: ecx = yyyyyy
6926: @end example
6927:
6928: @item write[/bhlt] @var{addr} [ @var{thread} ] @var{expr1} [ @var{expr2} @dots{} ]
6929: Write the expressions at succeeding locations. The write unit size can
6930: be specified in the modifier with a letter b (byte), h (half word) or
6931: l(long word) respectively. If omitted, long word is assumed. Target
6932: address space can also be specified with @code{t} option in the modifier
6933: and @var{thread} parameter. Warning: since there is no delimiter
6934: between expressions, strange things may happen. It's best to enclose
6935: each expression in parentheses.
6936:
6937: @item set $@var{variable} [=] @var{expr}
6938: Set the named variable or register with the value of @var{expr}. Valid
6939: variable names are described below.
6940:
6941: @item break[/tuTU] @var{addr}[,@var{count}] [ @var{thread1} @dots{} ]
6942: Set a break point at @var{addr}. If count is supplied, continues
6943: (@var{count}-1) times before stopping at the break point. If the break
6944: point is set, a break point number is printed with @samp{#}. This
6945: number can be used in deleting the break point or adding conditions to
6946: it.
6947:
6948: @table @code
6949: @item t
6950: Set a break point only for a specific thread. The thread is specified
6951: by @var{thread} parameter, or default one is used if the parameter is
6952: omitted.
6953:
6954: @item u
6955: Set a break point in user space address. It may be combined with
6956: @code{t} or @code{T} option to specify the non-current target user
6957: space. Without @code{u} option, the address is considered in the kernel
6958: space, and wrong space address is rejected with an error message. This
6959: option can be used only if it is supported by machine dependent
6960: routines.
6961:
6962: @item T
6963: Set a break point only for threads in a specific task. It is like
6964: @code{t} option except that the break point is valid for all threads
6965: which belong to the same task as the specified target thread.
6966:
6967: @item U
6968: Set a break point in shared user space address. It is like @code{u}
6969: option, except that the break point is valid for all threads which share
6970: the same address space even if @code{t} option is specified. @code{t}
6971: option is used only to specify the target shared space. Without
6972: @code{t} option, @code{u} and @code{U} have the same meanings. @code{U}
6973: is useful for setting a user space break point in non-current address
6974: space with @code{t} option such as in an emulation library space. This
6975: option can be used only if it is supported by machine dependent
6976: routines.
6977: @end table
6978:
6979: Warning: if a user text is shadowed by a normal user space debugger,
6980: user space break points may not work correctly. Setting a break point
6981: at the low-level code paths may also cause strange behavior.
6982:
6983: @item delete[/tuTU] @var{addr}|#@var{number} [ @var{thread1} @dots{} ]
6984: Delete the break point. The target break point can be specified by a
6985: break point number with @code{#}, or by @var{addr} like specified in
6986: @code{break} command.
6987:
6988: @item cond #@var{number} [ @var{condition} @var{commands} ]
6989: Set or delete a condition for the break point specified by the
6990: @var{number}. If the @var{condition} and @var{commands} are null, the
6991: condition is deleted. Otherwise the condition is set for it. When the
6992: break point is hit, the @var{condition} is evaluated. The
6993: @var{commands} will be executed if the condition is true and the break
6994: point count set by a break point command becomes zero. @var{commands}
6995: is a list of commands separated by semicolons. Each command in the list
6996: is executed in that order, but if a @code{continue} command is executed,
6997: the command execution stops there, and the stopped thread resumes
6998: execution. If the command execution reaches the end of the list, and it
6999: enters into a command input mode. For example,
7000:
7001: @example
7002: set $work0 0
7003: break/Tu xxx_start $task7.0
7004: cond #1 (1) set $work0 1; set $work1 0; cont
7005: break/T vm_fault $task7.0
7006: cond #2 ($work0) set $work1 ($work1+1); cont
7007: break/Tu xxx_end $task7.0
7008: cond #3 ($work0) print $work1 " faults\n"; set $work0 0
7009: cont
7010: @end example
7011:
7012: will print page fault counts from @code{xxx_start} to @code{xxx_end} in
7013: @code{task7}.
7014:
7015: @item step[/p] [,@var{count}]
7016: Single step @var{count} times. If @code{p} option is specified, print
7017: each instruction at each step. Otherwise, only print the last
7018: instruction.
7019:
7020: Warning: depending on machine type, it may not be possible to
7021: single-step through some low-level code paths or user space code. On
7022: machines with software-emulated single-stepping (e.g., pmax), stepping
7023: through code executed by interrupt handlers will probably do the wrong
7024: thing.
7025:
7026: @item continue[/c]
7027: Continue execution until a breakpoint or watchpoint. If @code{/c},
7028: count instructions while executing. Some machines (e.g., pmax) also
7029: count loads and stores.
7030:
7031: Warning: when counting, the debugger is really silently single-stepping.
7032: This means that single-stepping on low-level code may cause strange
7033: behavior.
7034:
7035: @item until
7036: Stop at the next call or return instruction.
7037:
7038: @item next[/p]
7039: Stop at the matching return instruction. If @code{p} option is
7040: specified, print the call nesting depth and the cumulative instruction
7041: count at each call or return. Otherwise, only print when the matching
7042: return is hit.
7043:
7044: @item match[/p]
7045: A synonym for @code{next}.
7046:
7047: @item trace[/tu] [ @var{frame_addr}|@var{thread} ][,@var{count}]
7048: Stack trace. @code{u} option traces user space; if omitted, only traces
7049: kernel space. If @code{t} option is specified, it shows the stack trace
7050: of the specified thread or a default target thread. Otherwise, it shows
7051: the stack trace of the current thread from the frame address specified
7052: by a parameter or from the current frame. @var{count} is the number of
7053: frames to be traced. If the @var{count} is omitted, all frames are
7054: printed.
7055:
7056: Warning: If the target thread's stack is not in the main memory at that
7057: time, the stack trace will fail. User space stack trace is valid only
7058: if the machine dependent code supports it.
7059:
7060: @item search[/bhl] @var{addr} @var{value} [@var{mask}] [,@var{count}]
7061: Search memory for a value. This command might fail in interesting ways
7062: if it doesn't find the searched-for value. This is because @code{ddb}
7063: doesn't always recover from touching bad memory. The optional count
7064: argument limits the search.
7065:
7066: @item macro @var{name} @var{commands}
7067: Define a debugger macro as @var{name}. @var{commands} is a list of
7068: commands to be associated with the macro. In the expressions of the
7069: command list, a variable @code{$argxx} can be used to get a parameter
7070: passed to the macro. When a macro is called, each argument is evaluated
7071: as an expression, and the value is assigned to each parameter,
7072: @code{$arg1}, @code{$arg2}, @dots{} respectively. 10 @code{$arg}
7073: variables are reserved to each level of macros, and they can be used as
7074: local variables. The nesting of macro can be allowed up to 5 levels.
7075: For example,
7076:
7077: @example
7078: macro xinit set $work0 $arg1
7079: macro xlist examine/m $work0,4; set $work0 *($work0)
7080: xinit *(xxx_list)
7081: xlist
7082: @enddots{}
7083: @end example
7084:
7085: will print the contents of a list starting from @code{xxx_list} by each
7086: @code{xlist} command.
7087:
7088: @item dmacro @var{name}
7089: Delete the macro named @var{name}.
7090:
7091: @item show all threads[/ul]
7092: Display all tasks and threads information. This version of @code{ddb}
7093: prints more information than previous one. It shows UNIX process
7094: information like @command{ps} for each task. The UNIX process
7095: information may not be shown if it is not supported in the machine, or
7096: the bottom of the stack of the target task is not in the main memory at
7097: that time. It also shows task and thread identification numbers. These
7098: numbers can be used to specify a task or a thread symbolically in
7099: various commands. The numbers are valid only in the same debugger
7100: session. If the execution is resumed again, the numbers may change.
7101: The current thread can be distinguished from others by a @code{#} after
7102: the thread id instead of @code{:}. Without @code{l} option, it only
7103: shows thread id, thread structure address and the status for each
1.1.1.3 ! root 7104: thread. The status consists of 6 letters, R(run), W(wait), S(suspended),
! 7105: O(swapped out), N(interruptible), and F(loating) point arithmetic used (if
! 7106: supported by the platform). If the corresponding
1.1 root 7107: status bit is off, @code{.} is printed instead. If @code{l} option is
7108: specified, more detail information is printed for each thread.
7109:
7110: @item show task [ @var{addr} ]
7111: Display the information of a task specified by @var{addr}. If
7112: @var{addr} is omitted, current task information is displayed.
7113:
7114: @item show thread [ @var{addr} ]
7115: Display the information of a thread specified by @var{addr}. If
7116: @var{addr} is omitted, current thread information is displayed.
7117:
7118: @item show registers[/tu [ @var{thread} ]]
7119: Display the register set. Target thread can be specified with @code{t}
7120: option and @var{thread} parameter. If @code{u} option is specified, it
7121: displays user registers instead of kernel or currently saved one.
7122:
7123: Warning: The support of @code{t} and @code{u} option depends on the
7124: machine. If not supported, incorrect information will be displayed.
7125:
7126: @item show map @var{addr}
7127: Prints the @code{vm_map} at @var{addr}.
7128:
7129: @item show object @var{addr}
7130: Prints the @code{vm_object} at @var{addr}.
7131:
7132: @item show page @var{addr}
7133: Prints the @code{vm_page} structure at @var{addr}.
7134:
7135: @item show port @var{addr}
7136: Prints the @code{ipc_port} structure at @var{addr}.
7137:
7138: @item show ipc_port[/t [ @var{thread} ]]
7139: Prints all @code{ipc_port} structure's addresses the target thread has.
7140: The target thread is a current thread or that specified by a parameter.
7141:
7142: @item show macro [ @var{name} ]
7143: Show the definitions of macros. If @var{name} is specified, only the
7144: definition of it is displayed. Otherwise, definitions of all macros are
7145: displayed.
7146:
7147: @item show watches
7148: Displays all watchpoints.
7149:
7150: @item watch[/T] @var{addr},@var{size} [ @var{task} ]
7151: Set a watchpoint for a region. Execution stops when an attempt to
7152: modify the region occurs. The @var{size} argument defaults to 4.
7153: Without @code{T} option, @var{addr} is assumed to be a kernel address.
7154: If you want to set a watch point in user space, specify @code{T} and
7155: @var{task} parameter where the address belongs to. If the @var{task}
7156: parameter is omitted, a task of the default target thread or a current
7157: task is assumed. If you specify a wrong space address, the request is
7158: rejected with an error message.
7159:
7160: Warning: Attempts to watch wired kernel memory may cause unrecoverable
7161: error in some systems such as i386. Watchpoints on user addresses work
7162: best.
1.1.1.2 root 7163:
7164: @item dwatch[/T] @var{addr} [ @var{task} ]
7165: Clears a watchpoint previously set for a region.
7166: Without @code{T} option, @var{addr} is assumed to be a kernel address.
7167: If you want to clear a watch point in user space, specify @code{T} and
7168: @var{task} parameter where the address belongs to. If the @var{task}
7169: parameter is omitted, a task of the default target thread or a current
7170: task is assumed. If you specify a wrong space address, the request is
7171: rejected with an error message.
1.1 root 7172: @end table
7173:
7174:
7175: @node Variables
7176: @section Variables
7177:
7178: The debugger accesses registers and variables as $@var{name}. Register
7179: names are as in the @code{show registers} command. Some variables are
7180: suffixed with numbers, and may have some modifier following a colon
7181: immediately after the variable name. For example, register variables
7182: can have @code{u} and @code{t} modifier to indicate user register and
7183: that of a default target thread instead of that of the current thread
7184: (e.g. @code{$eax:tu}).
7185:
7186: Built-in variables currently supported are:
7187:
7188: @table @code
7189: @item task@var{xx}[.@var{yy}]
7190: Task or thread structure address. @var{xx} and @var{yy} are task and
7191: thread identification numbers printed by a @code{show all threads}
7192: command respectively. This variable is read only.
7193:
7194: @item thread
7195: The default target thread. The value is used when @code{t} option is
7196: specified without explicit thread structure address parameter in command
7197: lines or expression evaluation.
7198:
7199: @item radix
7200: Input and output radix
7201:
7202: @item maxoff
7203: Addresses are printed as @var{symbol}+@var{offset} unless offset is greater than
7204: maxoff.
7205:
7206: @item maxwidth
7207: The width of the displayed line.
7208:
7209: @item lines
7210: The number of lines. It is used by @code{more} feature.
7211:
7212: @item tabstops
7213: Tab stop width.
7214:
7215: @item arg@var{xx}
7216: Parameters passed to a macro. @var{xx} can be 1 to 10.
7217:
7218: @item work@var{xx}
7219: Work variable. @var{xx} can be 0 to 31.
7220: @end table
7221:
7222:
7223: @node Expressions
7224: @section Expressions
7225:
7226: Almost all expression operators in C are supported except @code{~},
7227: @code{^}, and unary @code{&}. Special rules in @code{ddb} are:
7228:
7229: @table @code
7230: @item @var{identifier}
7231: name of a symbol. It is translated to the address(or value) of it.
7232: @code{.} and @code{:} can be used in the identifier. If supported by
7233: an object format dependent routine,
7234: [@var{file_name}:]@var{func}[:@var{line_number}]
7235: [@var{file_name}:]@var{variable}, and
7236: @var{file_name}[:@var{line_number}] can be accepted as a symbol. The
7237: symbol may be prefixed with @code{@var{symbol_table_name}::} like
7238: @code{emulator::mach_msg_trap} to specify other than kernel symbols.
7239:
7240: @item @var{number}
7241: radix is determined by the first two letters:
7242: @table @code
7243: @item 0x
7244: hex
7245: @item 0o
7246: octal
7247: @item 0t
7248: decimal
7249: @end table
7250:
7251: otherwise, follow current radix.
7252:
7253: @item .
7254: dot
7255:
7256: @item +
7257: next
7258:
7259: @item ..
7260: address of the start of the last line examined. Unlike dot or next,
7261: this is only changed by @code{examine} or @code{write} command.
7262:
7263: @item �
7264: last address explicitly specified.
7265:
7266: @item $@var{variable}
7267: register name or variable. It is translated to the value of it. It may
7268: be followed by a @code{:} and modifiers as described above.
7269:
7270: @item a
7271: multiple of right hand side.
7272:
7273: @item *@var{expr}
7274: indirection. It may be followed by a @code{:} and modifiers as
7275: described above.
7276: @end table
7277:
7278: @include gpl.texi
7279:
7280: @node Documentation License
7281: @appendix Documentation License
7282:
7283: This manual is copyrighted and licensed under the GNU Free Documentation
7284: license.
7285:
7286: Parts of this manual are derived from the Mach manual packages
7287: originally provided by Carnegie Mellon University.
7288:
7289: @menu
1.1.1.2 root 7290: * GNU Free Documentation License:: The GNU Free Documentation License.
1.1 root 7291: * CMU License:: The CMU license applies to the original Mach
7292: kernel and its documentation.
7293: @end menu
7294:
7295: @include fdl.texi
7296:
7297: @node CMU License
7298: @appendixsec CMU License
7299:
7300: @quotation
7301: @display
7302: Mach Operating System
7303: Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
7304: All Rights Reserved.
7305: @end display
7306:
7307: Permission to use, copy, modify and distribute this software and its
7308: documentation is hereby granted, provided that both the copyright
7309: notice and this permission notice appear in all copies of the
7310: software, derivative works or modified versions, and any portions
7311: thereof, and that both notices appear in supporting documentation.
7312:
7313: @sc{carnegie mellon allows free use of this software in its ``as is''
7314: condition. carnegie mellon disclaims any liability of any kind for
7315: any damages whatsoever resulting from the use of this software.}
7316:
7317: Carnegie Mellon requests users of this software to return to
7318:
7319: @display
7320: Software Distribution Coordinator
7321: School of Computer Science
7322: Carnegie Mellon University
7323: Pittsburgh PA 15213-3890
7324: @end display
7325:
7326: @noindent
7327: or @email{Software.Distribution@@CS.CMU.EDU} any improvements or
7328: extensions that they make and grant Carnegie Mellon the rights to
7329: redistribute these changes.
7330: @end quotation
7331:
7332: @node Concept Index
7333: @unnumbered Concept Index
7334:
7335: @printindex cp
7336:
7337:
7338: @node Function and Data Index
7339: @unnumbered Function and Data Index
7340:
7341: @printindex fn
7342:
7343:
7344: @summarycontents
7345: @contents
7346: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.