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