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