![[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.