![[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.2 ! root 1: This is mach.info, produced by makeinfo version 5.2 from mach.texi. 1.1 root 2: 3: This file documents the GNU Mach microkernel. 4: 1.1.1.2 ! root 5: This is edition 0.4, last updated on 10 April 2015, of 'The GNU Mach ! 6: Reference Manual', for version 1.5. 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.2 ! root 48: This is edition 0.4, last updated on 10 April 2015, of 'The GNU Mach ! 49: Reference Manual', for version 1.5. 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 1478: positive integers. Except for the reserved values 'MACH_PORT_NULL (0)'(1) 1479: and 'MACH_PORT_DEAD (~0)', this is a full 32-bit name space. When the 1480: kernel chooses a name for a new right, it is free to pick any unused 1481: name (one which denotes no right) in the space. 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: 3219: -- Function: kern_return_t vm_wire (host_priv_t HOST_PRIV, 3220: vm_task_t TARGET_TASK, vm_address_t ADDRESS, vm_size_t SIZE, 3221: vm_prot_t ACCESS) 3222: The function 'vm_wire' allows privileged applications to control 3223: memory pageability. HOST_PRIV is the privileged host port for the 3224: host on which TARGET_TASK resides. ADDRESS is the starting 3225: address, which will be rounded down to a page boundary. SIZE is 3226: the size in bytes of the region for which protection is to change, 3227: and will be rounded up to give a page boundary. ACCESS specifies 3228: the types of accesses that must not cause page faults. 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, 3237: 'KERN_INVALID_HOST' if HOST_PRIV was not the privileged host port, 3238: 'KERN_INVALID_TASK' if TASK was not a valid task, 3239: 'KERN_INVALID_VALUE' if ACCESS specified an invalid access mode, 3240: 'KERN_FAILURE' if some memory in the specified range is not present 3241: or has an inappropriate protection value, and 3242: 'KERN_INVALID_ARGUMENT' if unwiring (ACCESS is 'VM_PROT_NONE') and 3243: the memory is not already wired. 3244: 3245: The 'vm_wire' call is actually an RPC to HOST_PRIV, normally a send 3246: right for a privileged host port, but potentially any send right. 3247: In addition to the normal diagnostic return codes from the call's 3248: server (normally the kernel), the call may return 'mach_msg' return 3249: codes. 3250: 3251: -- Function: kern_return_t vm_machine_attribute (vm_task_t TASK, 3252: vm_address_t ADDRESS, vm_size_t SIZE, vm_prot_t ACCESS, 3253: vm_machine_attribute_t ATTRIBUTE, 3254: vm_machine_attribute_val_t VALUE) 3255: The function 'vm_machine_attribute' specifies machine-specific 3256: attributes for a VM mapping, such as cachability, migrability, 3257: replicability. This is used on machines that allow the user 3258: control over the cache (this is the case for MIPS architectures) or 3259: placement of memory pages as in NUMA architectures (Non-Uniform 3260: Memory Access time) such as the IBM ACE multiprocessor. 3261: 3262: Machine-specific attributes can be consider additions to the 3263: machine-independent ones such as protection and inheritance, but 3264: they are not guaranteed to be supported by any given machine. 3265: Moreover, implementations of Mach on new architectures might find 3266: the need for new attribute types and or values besides the ones 3267: defined in the initial implementation. 3268: 3269: The types currently defined are 3270: 'MATTR_CACHE' 3271: Controls caching of memory pages 3272: 3273: 'MATTR_MIGRATE' 3274: Controls migrability of memory pages 3275: 3276: 'MATTR_REPLICATE' 3277: Controls replication of memory pages 3278: 3279: Corresponding values, and meaning of a specific call to 3280: 'vm_machine_attribute' 3281: 'MATTR_VAL_ON' 3282: Enables the attribute. Being enabled is the default value for 3283: any applicable attribute. 3284: 3285: 'MATTR_VAL_OFF' 3286: Disables the attribute, making memory non-cached, or 3287: non-migratable, or non-replicatable. 3288: 3289: 'MATTR_VAL_GET' 3290: Returns the current value of the attribute for the memory 3291: segment. If the attribute does not apply uniformly to the 3292: given range the value returned applies to the initial portion 3293: of the segment only. 3294: 3295: 'MATTR_VAL_CACHE_FLUSH' 3296: Flush the memory pages from the Cache. The size value in this 3297: case might be meaningful even if not a multiple of the page 3298: size, depending on the implementation. 3299: 3300: 'MATTR_VAL_ICACHE_FLUSH' 3301: Same as above, applied to the Instruction Cache alone. 3302: 3303: 'MATTR_VAL_DCACHE_FLUSH' 3304: Same as above, applied to the Data Cache alone. 3305: 3306: The function returns 'KERN_SUCCESS' if call succeeded, and 3307: 'KERN_INVALID_ARGUMENT' if TASK is not a task, or ADDRESS and SIZE 3308: do not define a valid address range in task, or ATTRIBUTE is not a 3309: valid attribute type, or it is not implemented, or VALUE is not a 3310: permissible value for attribute. 3311: 3312: 3313: File: mach.info, Node: Mapping Memory Objects, Next: Memory Statistics, Prev: Memory Attributes, Up: Virtual Memory Interface 3314: 3315: 5.5 Mapping Memory Objects 3316: ========================== 3317: 3318: -- Function: kern_return_t vm_map (vm_task_t TARGET_TASK, 3319: vm_address_t *ADDRESS, vm_size_t SIZE, vm_address_t MASK, 3320: boolean_t ANYWHERE, memory_object_t MEMORY_OBJECT, 3321: vm_offset_t OFFSET, boolean_t COPY, vm_prot_t CUR_PROTECTION, 3322: vm_prot_t MAX_PROTECTION, vm_inherit_t INHERITANCE) 3323: The function 'vm_map' maps a region of virtual memory at the 3324: specified address, for which data is to be supplied by the given 3325: memory object, starting at the given offset within that object. In 3326: addition to the arguments used in 'vm_allocate', the 'vm_map' call 3327: allows the specification of an address alignment parameter, and of 3328: the initial protection and inheritance values. 3329: 3330: If the memory object in question is not currently in use, the 3331: kernel will perform a 'memory_object_init' call at this time. If 3332: the copy parameter is asserted, the specified region of the memory 3333: object will be copied to this address space; changes made to this 3334: object by other tasks will not be visible in this mapping, and 3335: changes made in this mapping will not be visible to others (or 3336: returned to the memory object). 3337: 3338: The 'vm_map' call returns once the mapping is established. 3339: Completion of the call does not require any action on the part of 3340: the memory manager. 3341: 3342: Warning: Only memory objects that are provided by bona fide memory 3343: managers should be used in the 'vm_map' call. A memory manager 3344: must implement the memory object interface described elsewhere in 3345: this manual. If other ports are used, a thread that accesses the 3346: mapped virtual memory may become permanently hung or may receive a 3347: memory exception. 3348: 3349: TARGET_TASK is the task to be affected. The starting address is 1.1.1.2 ! root 3350: ADDRESS. If the ANYWHERE option is used, this address is used as a ! 3351: starting hint. The address actually allocated will be returned in ! 3352: ADDRESS. SIZE is the number of bytes to allocate (rounded by the ! 3353: system in a machine dependent way). The alignment restriction is ! 3354: specified by MASK. Bits asserted in this mask must not be asserted ! 3355: in the address returned. If ANYWHERE is set, the kernel should ! 3356: find and allocate any region of the specified size, and return the ! 3357: address of the resulting region in ADDRESS. 1.1 root 3358: 3359: MEMORY_OBJECT is the port that represents the memory object: used 3360: by user tasks in 'vm_map'; used by the make requests for data or 3361: other management actions. If this port is 'MEMORY_OBJECT_NULL', 3362: then zero-filled memory is allocated instead. Within a memory 3363: object, OFFSET specifies an offset in bytes. This must be page 3364: aligned. If COPY is set, the range of the memory object should be 3365: copied to the target task, rather than mapped read-write. 3366: 3367: The function returns 'KERN_SUCCESS' if the object is mapped, 3368: 'KERN_NO_SPACE' if no unused region of the task's virtual address 3369: space that meets the address, size, and alignment criteria could be 3370: found, and 'KERN_INVALID_ARGUMENT' if an invalid argument was 3371: provided. 3372: 3373: 3374: File: mach.info, Node: Memory Statistics, Prev: Mapping Memory Objects, Up: Virtual Memory Interface 3375: 3376: 5.6 Memory Statistics 3377: ===================== 3378: 3379: -- Data type: vm_statistics_data_t 3380: This structure is returned in VM_STATS by the 'vm_statistics' 3381: function and provides virtual memory statistics for the system. It 3382: has the following members: 3383: 3384: 'long pagesize' 3385: The page size in bytes. 3386: 3387: 'long free_count' 3388: The number of free pages. 3389: 3390: 'long active_count' 3391: The umber of active pages. 3392: 3393: 'long inactive_count' 3394: The number of inactive pages. 3395: 3396: 'long wire_count' 3397: The number of pages wired down. 3398: 3399: 'long zero_fill_count' 3400: The number of zero filled pages. 3401: 3402: 'long reactivations' 3403: The number of reactivated pages. 3404: 3405: 'long pageins' 3406: The number of pageins. 3407: 3408: 'long pageouts' 3409: The number of pageouts. 3410: 3411: 'long faults' 3412: The number of faults. 3413: 3414: 'long cow_faults' 3415: The number of copy-on-writes. 3416: 3417: 'long lookups' 3418: The number of object cache lookups. 3419: 3420: 'long hits' 3421: The number of object cache hits. 3422: 3423: -- Function: kern_return_t vm_statistics (vm_task_t TARGET_TASK, 3424: vm_statistics_data_t *VM_STATS) 3425: The function 'vm_statistics' returns the statistics about the 3426: kernel's use of virtual memory since the kernel was booted. 3427: 'pagesize' can also be found as a global variable 'vm_page_size' 3428: which is set at task initialization and remains constant for the 3429: life of the task. 3430: 3431: 3432: File: mach.info, Node: External Memory Management, Next: Threads and Tasks, Prev: Virtual Memory Interface, Up: Top 3433: 3434: 6 External Memory Management 3435: **************************** 3436: 3437: * Menu: 3438: 3439: * Memory Object Server:: The basics of external memory management. 3440: * Memory Object Creation:: How new memory objects are created. 3441: * Memory Object Termination:: How memory objects are terminated. 3442: * Memory Objects and Data:: Data transfer to and from memory objects. 3443: * Memory Object Locking:: How memory objects are locked. 3444: * Memory Object Attributes:: Manipulating attributes of memory objects. 3445: * Default Memory Manager:: Setting and using the default memory manager. 3446: 3447: 3448: File: mach.info, Node: Memory Object Server, Next: Memory Object Creation, Up: External Memory Management 3449: 3450: 6.1 Memory Object Server 3451: ======================== 3452: 3453: -- Function: boolean_t memory_object_server (msg_header_t *IN_MSG, 3454: msg_header_t *OUT_MSG) 3455: -- Function: boolean_t memory_object_default_server 3456: (msg_header_t *IN_MSG, msg_header_t *OUT_MSG) 3457: -- Function: boolean_t seqnos_memory_object_server 3458: (msg_header_t *IN_MSG, msg_header_t *OUT_MSG) 3459: -- Function: boolean_t seqnos_memory_object_default_server 3460: (msg_header_t *IN_MSG, msg_header_t *OUT_MSG) 3461: A memory manager is a server task that responds to specific 3462: messages from the kernel in order to handle memory management 3463: functions for the kernel. 3464: 3465: In order to isolate the memory manager from the specifics of 3466: message formatting, the remote procedure call generator produces a 3467: procedure, 'memory_object_server', to handle a received message. 3468: This function does all necessary argument handling, and actually 3469: calls one of the following functions: 'memory_object_init', 3470: 'memory_object_data_write', 'memory_object_data_return', 3471: 'memory_object_data_request', 'memory_object_data_unlock', 3472: 'memory_object_lock_completed', 'memory_object_copy', 3473: 'memory_object_terminate'. The *default memory manager* may get 3474: two additional requests from the kernel: 'memory_object_create' and 3475: 'memory_object_data_initialize'. The remote procedure call 3476: generator produces a procedure 'memory_object_default_server' to 3477: handle those functions specific to the default memory manager. 3478: 3479: The 'seqnos_memory_object_server' and 3480: 'seqnos_memory_object_default_server' differ from 3481: 'memory_object_server' and 'memory_object_default_server' in that 3482: they supply message sequence numbers to the server interfaces. 3483: They call the 'seqnos_memory_object_*' functions, which complement 3484: the 'memory_object_*' set of functions. 3485: 3486: The return value from the 'memory_object_server' function indicates 3487: that the message was appropriate to the memory management interface 3488: (returning 'TRUE'), or that it could not handle this message 3489: (returning 'FALSE'). 3490: 3491: The IN_MSG argument is the message that has been received from the 3492: kernel. The OUT_MSG is a reply message, but this is not used for 3493: this server. 3494: 3495: The function returns 'TRUE' to indicate that the message in 3496: question was applicable to this interface, and that the appropriate 3497: routine was called to interpret the message. It returns 'FALSE' to 3498: indicate that the message did not apply to this interface, and that 3499: no other action was taken. 3500: 3501: 3502: File: mach.info, Node: Memory Object Creation, Next: Memory Object Termination, Prev: Memory Object Server, Up: External Memory Management 3503: 3504: 6.2 Memory Object Creation 3505: ========================== 3506: 3507: -- Function: kern_return_t memory_object_init 3508: (memory_object_t MEMORY_OBJECT, 3509: memory_object_control_t MEMORY_CONTROL, 3510: memory_object_name_t MEMORY_OBJECT_NAME, 3511: vm_size_t MEMORY_OBJECT_PAGE_SIZE) 3512: -- Function: kern_return_t seqnos_memory_object_init 3513: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 3514: memory_object_control_t MEMORY_CONTROL, 3515: memory_object_name_t MEMORY_OBJECT_NAME, 3516: vm_size_t MEMORY_OBJECT_PAGE_SIZE) 3517: The function 'memory_object_init' serves as a notification that the 3518: kernel has been asked to map the given memory object into a task's 3519: virtual address space. Additionally, it provides a port on which 3520: the memory manager may issue cache management requests, and a port 3521: which the kernel will use to name this data region. In the event 3522: that different each will perform a 'memory_object_init' call with 3523: new request and name ports. The virtual page size that is used by 3524: the calling kernel is included for planning purposes. 3525: 3526: When the memory manager is prepared to accept requests for data for 3527: this object, it must call 'memory_object_ready' with the attribute. 3528: Otherwise the kernel will not process requests on this object. To 3529: reject all mappings of this object, the memory manager may use 3530: 'memory_object_destroy'. 3531: 3532: The argument MEMORY_OBJECT is the port that represents the memory 3533: object data, as supplied to the kernel in a 'vm_map' call. 3534: MEMORY_CONTROL is the request port to which a response is 3535: requested. (In the event that a memory object has been supplied to 3536: more than one the kernel that has made the request.) 3537: MEMORY_OBJECT_NAME is a port used by the kernel to refer to the 3538: memory object data in response to 'vm_region' calls. 3539: 'memory_object_page_size' is the page size to be used by this 3540: kernel. All data sizes in calls involving this kernel must be an 3541: integral multiple of the page size. Note that different kernels, 3542: indicated by a different 'memory_control', may have different page 3543: sizes. 3544: 3545: The function should return 'KERN_SUCCESS', but since this routine 3546: is called by the kernel, which does not wait for a reply message, 3547: this value is ignored. 3548: 3549: -- Function: kern_return_t memory_object_ready 3550: (memory_object_control_t MEMORY_CONTROL, 3551: boolean_t MAY_CACHE_OBJECT, 3552: memory_object_copy_strategy_t COPY_STRATEGY) 3553: The function 'memory_object_ready' informs the kernel that the 3554: memory manager is ready to receive data or unlock requests on 3555: behalf of the clients. The argument MEMORY_CONTROL is the port, 3556: provided by the kernel in a 'memory_object_init' call, to which 3557: cache management requests may be issued. If MAY_CACHE_OBJECT is 3558: set, the kernel may keep data associated with this memory object, 3559: even after virtual memory references to it are gone. 3560: 3561: COPY_STRATEGY tells how the kernel should copy regions of the 3562: associated memory object. There are three possible caching 3563: strategies: 'MEMORY_OBJECT_COPY_NONE' which specifies that nothing 3564: special should be done when data in the object is copied; 3565: 'MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager 3566: should be notified via a 'memory_object_copy' call before any part 3567: of the object is copied; and 'MEMORY_OBJECT_COPY_DELAY' which 3568: guarantees that the memory manager does not externally modify the 3569: data so that the kernel can use its normal copy-on-write 3570: algorithms. 'MEMORY_OBJECT_COPY_DELAY' is the strategy most 3571: commonly used. 3572: 3573: This routine does not receive a reply message (and consequently has 3574: no return value), so only message transmission errors apply. 3575: 3576: 3577: File: mach.info, Node: Memory Object Termination, Next: Memory Objects and Data, Prev: Memory Object Creation, Up: External Memory Management 3578: 3579: 6.3 Memory Object Termination 3580: ============================= 3581: 3582: -- Function: kern_return_t memory_object_terminate 3583: (memory_object_t MEMORY_OBJECT, 3584: memory_object_control_t MEMORY_CONTROL, 3585: memory_object_name_t MEMORY_OBJECT_NAME) 3586: -- Function: kern_return_t seqnos_memory_object_terminate 3587: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 3588: memory_object_control_t MEMORY_CONTROL, 3589: memory_object_name_t MEMORY_OBJECT_NAME) 3590: The function 'memory_object_terminate' indicates that the kernel 3591: has completed its use of the given memory object. All rights to 3592: the memory object control and name ports are included, so that the 3593: memory manager can destroy them (using 'mach_port_deallocate') 3594: after doing appropriate bookkeeping. The kernel will terminate a 3595: memory object only after all address space mappings of that memory 3596: object have been deallocated, or upon explicit request by the 3597: memory manager. 3598: 3599: The argument MEMORY_OBJECT is the port that represents the memory 3600: object data, as supplied to the kernel in a 'vm_map' call. 3601: MEMORY_CONTROL is the request port to which a response is 3602: requested. (In the event that a memory object has been supplied to 3603: more than one the kernel that has made the request.) 3604: MEMORY_OBJECT_NAME is a port used by the kernel to refer to the 3605: memory object data in response to 'vm_region' calls. 3606: 3607: The function should return 'KERN_SUCCESS', but since this routine 3608: is called by the kernel, which does not wait for a reply message, 3609: this value is ignored. 3610: 3611: -- Function: kern_return_t memory_object_destroy 3612: (memory_object_control_t MEMORY_CONTROL, kern_return_t REASON) 3613: The function 'memory_object_destroy' tells the kernel to shut down 3614: the memory object. As a result of this call the kernel will no 3615: longer support paging activity or any 'memory_object' calls on this 3616: object, and all rights to the memory object port, the memory 3617: control port and the memory name port will be returned to the 3618: memory manager in a memory_object_terminate call. If the memory 3619: manager is concerned that any modified cached data be returned to 3620: it before the object is terminated, it should call 3621: 'memory_object_lock_request' with SHOULD_FLUSH set and a lock value 3622: of 'VM_PROT_WRITE' before making this call. 3623: 3624: The argument MEMORY_CONTROL is the port, provided by the kernel in 3625: a 'memory_object_init' call, to which cache management requests may 3626: be issued. REASON is an error code indicating why the object must 3627: be destroyed. 3628: 3629: This routine does not receive a reply message (and consequently has 3630: no return value), so only message transmission errors apply. 3631: 3632: 3633: File: mach.info, Node: Memory Objects and Data, Next: Memory Object Locking, Prev: Memory Object Termination, Up: External Memory Management 3634: 3635: 6.4 Memory Objects and Data 3636: =========================== 3637: 3638: -- Function: kern_return_t memory_object_data_return 3639: (memory_object_t MEMORY_OBJECT, 3640: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3641: vm_offset_t DATA, vm_size_t DATA_COUNT, boolean_t DIRTY, 3642: boolean_t KERNEL_COPY) 3643: -- Function: kern_return_t seqnos_memory_object_data_return 3644: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 3645: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3646: vm_offset_t DATA, vm_size_t DATA_COUNT, boolean_t DIRTY, 3647: boolean_t KERNEL_COPY) 3648: The function 'memory_object_data_return' provides the memory 3649: manager with data that has been modified while cached in physical 3650: memory. Once the memory manager no longer needs this data (e.g., 3651: it has been written to another storage medium), it should be 3652: deallocated using 'vm_deallocate'. 3653: 3654: The argument MEMORY_OBJECT is the port that represents the memory 3655: object data, as supplied to the kernel in a 'vm_map' call. 3656: MEMORY_CONTROL is the request port to which a response is 3657: requested. (In the event that a memory object has been supplied to 3658: more than one the kernel that has made the request.) OFFSET is the 3659: offset within a memory object to which this call refers. This will 3660: be page aligned. DATA is the data which has been modified while 3661: cached in physical memory. DATA_COUNT is the amount of data to be 3662: written, in bytes. This will be an integral number of memory 3663: object pages. 3664: 3665: The kernel will also use this call to return precious pages. If an 3666: unmodified precious age is returned, DIRTY is set to 'FALSE', 3667: otherwise it is 'TRUE'. If KERNEL_COPY is 'TRUE', the kernel kept 3668: a copy of the page. Precious data remains precious if the kernel 3669: keeps a copy. The indication that the kernel kept a copy is only a 3670: hint if the data is not precious; the cleaned copy may be discarded 3671: without further notifying the manager. 3672: 3673: The function should return 'KERN_SUCCESS', but since this routine 3674: is called by the kernel, which does not wait for a reply message, 3675: this value is ignored. 3676: 3677: -- Function: kern_return_t memory_object_data_request 3678: (memory_object_t MEMORY_OBJECT, 3679: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3680: vm_offset_t LENGTH, vm_prot_t DESIRED_ACCESS) 3681: -- Function: kern_return_t seqnos_memory_object_data_request 3682: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 3683: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3684: vm_offset_t LENGTH, vm_prot_t DESIRED_ACCESS) 3685: The function 'memory_object_data_request' is a request for data 3686: from the specified memory object, for at least the access 3687: specified. The memory manager is expected to return at least the 3688: specified data, with as much access as it can allow, using 3689: 'memory_object_data_supply'. If the memory manager is unable to 3690: provide the data (for example, because of a hardware error), it may 3691: use the 'memory_object_data_error' call. The 3692: 'memory_object_data_unavailable' call may be used to tell the 3693: kernel to supply zero-filled memory for this region. 3694: 3695: The argument MEMORY_OBJECT is the port that represents the memory 3696: object data, as supplied to the kernel in a 'vm_map' call. 3697: MEMORY_CONTROL is the request port to which a response is 3698: requested. (In the event that a memory object has been supplied to 3699: more than one the kernel that has made the request.) OFFSET is the 3700: offset within a memory object to which this call refers. This will 3701: be page aligned. LENGTH is the number of bytes of data, starting 3702: at OFFSET, to which this call refers. This will be an integral 3703: number of memory object pages. DESIRED_ACCESS is a protection 3704: value describing the memory access modes which must be permitted on 3705: the specified cached data. One or more of: 'VM_PROT_READ', 3706: 'VM_PROT_WRITE' or 'VM_PROT_EXECUTE'. 3707: 3708: The function should return 'KERN_SUCCESS', but since this routine 3709: is called by the kernel, which does not wait for a reply message, 3710: this value is ignored. 3711: 3712: -- Function: kern_return_t memory_object_data_supply 3713: (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3714: vm_offset_t DATA, vm_size_t DATA_COUNT, vm_prot_t LOCK_VALUE, 3715: boolean_t PRECIOUS, mach_port_t REPLY) 3716: The function 'memory_object_data_supply' supplies the kernel with 3717: data for the specified memory object. Ordinarily, memory managers 3718: should only provide data in response to 3719: 'memory_object_data_request' calls from the kernel (but they may 3720: provide data in advance as desired). When data already held by 3721: this kernel is provided again, the new data is ignored. The kernel 3722: may not provide any data (or protection) consistency among pages 3723: with different virtual page alignments within the same object. 3724: 3725: The argument MEMORY_CONTROL is the port, provided by the kernel in 3726: a 'memory_object_init' call, to which cache management requests may 3727: be issued. OFFSET is an offset within a memory object in bytes. 3728: This must be page aligned. DATA is the data that is being provided 3729: to the kernel. This is a pointer to the data. DATA_COUNT is the 3730: amount of data to be provided. Only whole virtual pages of data 3731: can be accepted; partial pages will be discarded. 3732: 3733: LOCK_VALUE is a protection value indicating those forms of access 3734: that should *not* be permitted to the specified cached data. The 3735: lock values must be one or more of the set: 'VM_PROT_NONE', 3736: 'VM_PROT_READ', 'VM_PROT_WRITE', 'VM_PROT_EXECUTE' and 3737: 'VM_PROT_ALL' as defined in 'mach/vm_prot.h'. 3738: 3739: If PRECIOUS is 'FALSE', the kernel treats the data as a temporary 3740: and may throw it away if it hasn't been changed. If the PRECIOUS 3741: value is 'TRUE', the kernel treats its copy as a data repository 3742: and promises to return it to the manager; the manager may tell the 3743: kernel to throw it away instead by flushing and not cleaning the 3744: data (see 'memory_object_lock_request'). 3745: 3746: If REPLY_TO is not 'MACH_PORT_NULL', the kernel will send a 3747: completion message to the provided port (see 3748: 'memory_object_supply_completed'). 3749: 3750: This routine does not receive a reply message (and consequently has 3751: no return value), so only message transmission errors apply. 3752: 3753: -- Function: kern_return_t memory_object_supply_completed 3754: (memory_object_t MEMORY_OBJECT, 3755: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3756: vm_size_t LENGTH, kern_return_t RESULT, 3757: vm_offset_t ERROR_OFFSET) 3758: -- Function: kern_return_t seqnos_memory_object_supply_completed 3759: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 3760: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3761: vm_size_t LENGTH, kern_return_t RESULT, 3762: vm_offset_t ERROR_OFFSET) 3763: The function 'memory_object_supply_completed' indicates that a 3764: previous 'memory_object_data_supply' has been completed. Note that 3765: this call is made on whatever port was specified in the 3766: 'memory_object_data_supply' call; that port need not be the memory 3767: object port itself. No reply is expected after this call. 3768: 3769: The argument MEMORY_OBJECT is the port that represents the memory 3770: object data, as supplied to the kernel in a 'vm_map' call. 3771: MEMORY_CONTROL is the request port to which a response is 3772: requested. (In the event that a memory object has been supplied to 3773: more than one the kernel that has made the request.) OFFSET is the 3774: offset within a memory object to which this call refers. LENGTH is 3775: the length of the data covered by the lock request. The RESULT 3776: parameter indicates what happened during the supply. If it is not 3777: 'KERN_SUCCESS', then ERROR_OFFSET identifies the first offset at 3778: which a problem occurred. The pagein operation stopped at this 3779: point. Note that the only failures reported by this mechanism are 3780: 'KERN_MEMORY_PRESENT'. All other failures (invalid argument, error 3781: on pagein of supplied data in manager's address space) cause the 3782: entire operation to fail. 3783: 3784: -- Function: kern_return_t memory_object_data_error 3785: (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3786: vm_size_t SIZE, kern_return_t REASON) 3787: The function 'memory_object_data_error' indicates that the memory 3788: manager cannot return the data requested for the given region, 3789: specifying a reason for the error. This is typically used when a 3790: hardware error is encountered. 3791: 3792: The argument MEMORY_CONTROL is the port, provided by the kernel in 3793: a 'memory_object_init' call, to which cache management requests may 3794: be issued. OFFSET is an offset within a memory object in bytes. 3795: This must be page aligned. DATA is the data that is being provided 3796: to the kernel. This is a pointer to the data. SIZE is the amount 3797: of cached data (starting at OFFSET) to be handled. This must be an 3798: integral number of the memory object page size. REASON is an error 3799: code indicating what type of error occurred. 3800: 3801: This routine does not receive a reply message (and consequently has 3802: no return value), so only message transmission errors apply. 3803: 3804: -- Function: kern_return_t memory_object_data_unavailable 3805: (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3806: vm_size_t SIZE, kern_return_t REASON) 3807: The function 'memory_object_data_unavailable' indicates that the 3808: memory object does not have data for the given region and that the 3809: kernel should provide the data for this range. The memory manager 3810: may use this call in three different situations. 3811: 3812: 1. The object was created by 'memory_object_create' and the 3813: kernel has not yet provided data for this range (either via a 3814: 'memory_object_data_initialize', 'memory_object_data_write' or 3815: a 'memory_object_data_return' for the object. 3816: 3817: 2. The object was created by an 'memory_object_data_copy' and the 3818: kernel should copy this region from the original memory 3819: object. 3820: 3821: 3. The object is a normal user-created memory object and the 3822: kernel should supply unlocked zero-filled pages for the range. 3823: 3824: The argument MEMORY_CONTROL is the port, provided by the kernel in 3825: a 'memory_object_init' call, to which cache management requests may 3826: be issued. OFFSET is an offset within a memory object, in bytes. 3827: This must be page aligned. SIZE is the amount of cached data 3828: (starting at OFFSET) to be handled. This must be an integral 3829: number of the memory object page size. 3830: 3831: This routine does not receive a reply message (and consequently has 3832: no return value), so only message transmission errors apply. 3833: 3834: -- Function: kern_return_t memory_object_copy 3835: (memory_object_t OLD_MEMORY_OBJECT, 3836: memory_object_control_t OLD_MEMORY_CONTROL, 3837: vm_offset_t OFFSET, vm_size_t LENGTH, 3838: memory_object_t NEW_MEMORY_OBJECT) 3839: -- Function: kern_return_t seqnos_memory_object_copy 3840: (memory_object_t OLD_MEMORY_OBJECT, mach_port_seqno_t SEQNO, 3841: memory_object_control_t OLD_MEMORY_CONTROL, 3842: vm_offset_t OFFSET, vm_size_t LENGTH, 3843: memory_object_t NEW_MEMORY_OBJECT) 3844: The function 'memory_object_copy' indicates that a copy has been 3845: made of the specified range of the given original memory object. 3846: This call includes only the new memory object itself; a 3847: 'memory_object_init' call will be made on the new memory object 3848: after the currently cached pages of the original object are 3849: prepared. After the memory manager receives the init call, it must 3850: reply with the 'memory_object_ready' call to assert the "ready" 3851: attribute. The kernel will use the new memory object, control and 3852: name ports to refer to the new copy. 3853: 3854: This call is made when the original memory object had the caching 3855: parameter set to 'MEMORY_OBJECT_COPY_CALL' and a user of the object 3856: has asked the kernel to copy it. 3857: 3858: Cached pages from the original memory object at the time of the 3859: copy operation are handled as follows: Readable pages may be 3860: silently copied to the new memory object (with all access 3861: permissions). Pages not copied are locked to prevent write access. 3862: 3863: The new memory object is *temporary*, meaning that the memory 3864: manager should not change its contents or allow the memory object 3865: to be mapped in another client. The memory manager may use the 3866: 'memory_object_data_unavailable' call to indicate that the 3867: appropriate pages of the original memory object may be used to 3868: fulfill the data request. 3869: 3870: The argument OLD_MEMORY_OBJECT is the port that represents the old 3871: memory object data. OLD_MEMORY_CONTROL is the kernel port for the 3872: old object. OFFSET is the offset within a memory object to which 3873: this call refers. This will be page aligned. LENGTH is the number 3874: of bytes of data, starting at OFFSET, to which this call refers. 3875: This will be an integral number of memory object pages. 3876: NEW_MEMORY_OBJECT is a new memory object created by the kernel; see 3877: synopsis for further description. Note that all port rights 3878: (including receive rights) are included for the new memory object. 3879: 3880: The function should return 'KERN_SUCCESS', but since this routine 3881: is called by the kernel, which does not wait for a reply message, 3882: this value is ignored. 3883: 3884: The remaining interfaces in this section are obsolete. 3885: 3886: -- Function: kern_return_t memory_object_data_write 3887: (memory_object_t MEMORY_OBJECT, 3888: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3889: vm_offset_t DATA, vm_size_t DATA_COUNT) 3890: -- Function: kern_return_t seqnos_memory_object_data_write 3891: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 3892: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3893: vm_offset_t DATA, vm_size_t DATA_COUNT) 3894: The function 'memory_object_data_write' provides the memory manager 3895: with data that has been modified while cached in physical memory. 3896: It is the old form of 'memory_object_data_return'. Once the memory 3897: manager no longer needs this data (e.g., it has been written to 3898: another storage medium), it should be deallocated using 3899: 'vm_deallocate'. 3900: 3901: The argument MEMORY_OBJECT is the port that represents the memory 3902: object data, as supplied to the kernel in a 'vm_map' call. 3903: MEMORY_CONTROL is the request port to which a response is 3904: requested. (In the event that a memory object has been supplied to 3905: more than one the kernel that has made the request.) OFFSET is the 3906: offset within a memory object to which this call refers. This will 3907: be page aligned. DATA is the data which has been modified while 3908: cached in physical memory. DATA_COUNT is the amount of data to be 3909: written, in bytes. This will be an integral number of memory 3910: object pages. 3911: 3912: The function should return 'KERN_SUCCESS', but since this routine 3913: is called by the kernel, which does not wait for a reply message, 3914: this value is ignored. 3915: 3916: -- Function: kern_return_t memory_object_data_provided 3917: (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3918: vm_offset_t DATA, vm_size_t DATA_COUNT, vm_prot_t LOCK_VALUE) 3919: The function 'memory_object_data_provided' supplies the kernel with 3920: data for the specified memory object. It is the old form of 3921: 'memory_object_data_supply'. Ordinarily, memory managers should 3922: only provide data in response to 'memory_object_data_request' calls 3923: from the kernel. The LOCK_VALUE specifies what type of access will 3924: not be allowed to the data range. The lock values must be one or 3925: more of the set: 'VM_PROT_NONE', 'VM_PROT_READ', 'VM_PROT_WRITE', 3926: 'VM_PROT_EXECUTE' and 'VM_PROT_ALL' as defined in 'mach/vm_prot.h'. 3927: 3928: The argument MEMORY_CONTROL is the port, provided by the kernel in 3929: a 'memory_object_init' call, to which cache management requests may 3930: be issued. OFFSET is an offset within a memory object in bytes. 3931: This must be page aligned. DATA is the data that is being provided 3932: to the kernel. This is a pointer to the data. DATA_COUNT is the 3933: amount of data to be provided. This must be an integral number of 3934: memory object pages. LOCK_VALUE is a protection value indicating 3935: those forms of access that should *not* be permitted to the 3936: specified cached data. 3937: 3938: This routine does not receive a reply message (and consequently has 3939: no return value), so only message transmission errors apply. 3940: 3941: 3942: File: mach.info, Node: Memory Object Locking, Next: Memory Object Attributes, Prev: Memory Objects and Data, Up: External Memory Management 3943: 3944: 6.5 Memory Object Locking 3945: ========================= 3946: 3947: -- Function: kern_return_t memory_object_lock_request 3948: (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3949: vm_size_t SIZE, memory_object_return_t SHOULD_CLEAN, 3950: boolean_t SHOULD_FLUSH, vm_prot_t LOCK_VALUE, 3951: mach_port_t REPLY_TO) 3952: The function 'memory_object_lock_request' allows a memory manager 3953: to make cache management requests. As specified in arguments to 3954: the call, the kernel will: 3955: * clean (i.e., write back using 'memory_object_data_supply' or 3956: 'memory_object_data_write') any cached data which has been 3957: modified since the last time it was written 3958: 3959: * flush (i.e., remove any uses of) that data from memory 3960: 3961: * lock (i.e., prohibit the specified uses of) the cached data 3962: 3963: Locks applied to cached data are not cumulative; new lock values 3964: override previous ones. Thus, data may also be unlocked using this 3965: primitive. The lock values must be one or more of the following 3966: values: 'VM_PROT_NONE', 'VM_PROT_READ', 'VM_PROT_WRITE', 3967: 'VM_PROT_EXECUTE' and 'VM_PROT_ALL' as defined in 'mach/vm_prot.h'. 3968: 3969: Only data which is cached at the time of this call is affected. 3970: When a running thread requires a prohibited access to cached data, 3971: the kernel will issue a 'memory_object_data_unlock' call specifying 3972: the forms of access required. 3973: 3974: Once all of the actions requested by this call have been completed, 3975: the kernel issues a 'memory_object_lock_completed' call on the 3976: specified reply port. 3977: 3978: The argument MEMORY_CONTROL is the port, provided by the kernel in 3979: a 'memory_object_init' call, to which cache management requests may 3980: be issued. OFFSET is an offset within a memory object, in bytes. 3981: This must be page aligned. SIZE is the amount of cached data 3982: (starting at OFFSET) to be handled. This must be an integral 3983: number of the memory object page size. If SHOULD_CLEAN is set, 3984: modified data should be written back to the memory manager. If 3985: SHOULD_FLUSH is set, the specified cached data should be 3986: invalidated, and all uses of that data should be revoked. 3987: LOCK_VALUE is a protection value indicating those forms of access 3988: that should *not* be permitted to the specified cached data. 3989: REPLY_TO is a port on which a 'memory_object_lock_completed' call 3990: should be issued, or 'MACH_PORT_NULL' if no acknowledgement is 3991: desired. 3992: 3993: This routine does not receive a reply message (and consequently has 3994: no return value), so only message transmission errors apply. 3995: 3996: -- Function: kern_return_t memory_object_lock_completed 3997: (memory_object_t MEMORY_OBJECT, 3998: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 3999: vm_size_t LENGTH) 4000: -- Function: kern_return_t seqnos_memory_object_lock_completed 4001: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 4002: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 4003: vm_size_t LENGTH) 4004: The function 'memory_object_lock_completed' indicates that a 4005: previous 'memory_object_lock_request' has been completed. Note 4006: that this call is made on whatever port was specified in the 4007: 'memory_object_lock_request' call; that port need not be the memory 4008: object port itself. No reply is expected after this call. 4009: 4010: The argument MEMORY_OBJECT is the port that represents the memory 4011: object data, as supplied to the kernel in a 'vm_map' call. 4012: MEMORY_CONTROL is the request port to which a response is 4013: requested. (In the event that a memory object has been supplied to 4014: more than one the kernel that has made the request.) OFFSET is the 4015: offset within a memory object to which this call refers. LENGTH is 4016: the length of the data covered by the lock request. 4017: 4018: The function should return 'KERN_SUCCESS', but since this routine 4019: is called by the kernel, which does not wait for a reply message, 4020: this value is ignored. 4021: 4022: -- Function: kern_return_t memory_object_data_unlock 4023: (memory_object_t MEMORY_OBJECT, 4024: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 4025: vm_size_t LENGTH, vm_prot_t DESIRED_ACCESS) 4026: -- Function: kern_return_t seqnos_memory_object_data_unlock 4027: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 4028: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 4029: vm_size_t LENGTH, vm_prot_t DESIRED_ACCESS) 4030: The function 'memory_object_data_unlock' is a request that the 4031: memory manager permit at least the desired access to the specified 4032: data cached by the kernel. A call to 'memory_object_lock_request' 4033: is expected in response. 4034: 4035: The argument MEMORY_OBJECT is the port that represents the memory 4036: object data, as supplied to the kernel in a 'vm_map' call. 4037: MEMORY_CONTROL is the request port to which a response is 4038: requested. (In the event that a memory object has been supplied to 4039: more than one the kernel that has made the request.) OFFSET is the 4040: offset within a memory object to which this call refers. This will 4041: be page aligned. LENGTH is the number of bytes of data, starting 4042: at OFFSET, to which this call refers. This will be an integral 4043: number of memory object pages. DESIRED_ACCESS a protection value 4044: describing the memory access modes which must be permitted on the 4045: specified cached data. One or more of: 'VM_PROT_READ', 4046: 'VM_PROT_WRITE' or 'VM_PROT_EXECUTE'. 4047: 4048: The function should return 'KERN_SUCCESS', but since this routine 4049: is called by the kernel, which does not wait for a reply message, 4050: this value is ignored. 4051: 4052: 4053: File: mach.info, Node: Memory Object Attributes, Next: Default Memory Manager, Prev: Memory Object Locking, Up: External Memory Management 4054: 4055: 6.6 Memory Object Attributes 4056: ============================ 4057: 4058: -- Function: kern_return_t memory_object_get_attributes 4059: (memory_object_control_t MEMORY_CONTROL, 4060: boolean_t *OBJECT_READY, boolean_t *MAY_CACHE_OBJECT, 4061: memory_object_copy_strategy_t *COPY_STRATEGY) 4062: The function 'memory_object_get_attribute' retrieves the current 4063: attributes associated with the memory object. 4064: 4065: The argument MEMORY_CONTROL is the port, provided by the kernel in 4066: a 'memory_object_init' call, to which cache management requests may 4067: be issued. If OBJECT_READY is set, the kernel may issue new data 4068: and unlock requests on the associated memory object. If 4069: MAY_CACHE_OBJECT is set, the kernel may keep data associated with 4070: this memory object, even after virtual memory references to it are 4071: gone. COPY_STRATEGY tells how the kernel should copy regions of 4072: the associated memory object. 4073: 4074: This routine does not receive a reply message (and consequently has 4075: no return value), so only message transmission errors apply. 4076: 4077: -- Function: kern_return_t memory_object_change_attributes 4078: (memory_object_control_t MEMORY_CONTROL, 4079: boolean_t MAY_CACHE_OBJECT, 4080: memory_object_copy_strategy_t COPY_STRATEGY, 4081: mach_port_t REPLY_TO) 4082: The function 'memory_object_change_attribute' sets 4083: performance-related attributes for the specified memory object. If 4084: the caching attribute is asserted, the kernel is permitted (and 4085: encouraged) to maintain cached data for this memory object even 4086: after no virtual address space contains this data. 4087: 4088: There are three possible caching strategies: 4089: 'MEMORY_OBJECT_COPY_NONE' which specifies that nothing special 4090: should be done when data in the object is copied; 4091: 'MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager 4092: should be notified via a 'memory_object_copy' call before any part 4093: of the object is copied; and 'MEMORY_OBJECT_COPY_DELAY' which 4094: guarantees that the memory manager does not externally modify the 4095: data so that the kernel can use its normal copy-on-write 4096: algorithms. 'MEMORY_OBJECT_COPY_DELAY' is the strategy most 4097: commonly used. 4098: 4099: The argument MEMORY_CONTROL is the port, provided by the kernel in 4100: a 'memory_object_init' call, to which cache management requests may 4101: be issued. If MAY_CACHE_OBJECT is set, the kernel may keep data 4102: associated with this memory object, even after virtual memory 4103: references to it are gone. COPY_STRATEGY tells how the kernel 4104: should copy regions of the associated memory object. REPLY_TO is a 4105: port on which a 'memory_object_change_completed' call will be 4106: issued upon completion of the attribute change, or 'MACH_PORT_NULL' 4107: if no acknowledgement is desired. 4108: 4109: This routine does not receive a reply message (and consequently has 4110: no return value), so only message transmission errors apply. 4111: 4112: -- Function: kern_return_t memory_object_change_completed 4113: (memory_object_t MEMORY_OBJECT, boolean_t MAY_CACHE_OBJECT, 4114: memory_object_copy_strategy_t COPY_STRATEGY) 4115: -- Function: kern_return_t seqnos_memory_object_change_completed 4116: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 4117: boolean_t MAY_CACHE_OBJECT, 4118: memory_object_copy_strategy_t COPY_STRATEGY) 4119: The function 'memory_object_change_completed' indicates the 4120: completion of an attribute change call. 4121: 4122: The following interface is obsoleted by 'memory_object_ready' and 4123: 'memory_object_change_attributes'. If the old form 4124: 'memory_object_set_attributes' is used to make a memory object ready, 4125: the kernel will write back data using the old 'memory_object_data_write' 4126: interface rather than 'memory_object_data_return'.. 4127: 4128: -- Function: kern_return_t memory_object_set_attributes 4129: (memory_object_control_t MEMORY_CONTROL, boolean OBJECT_READY, 4130: boolean_t MAY_CACHE_OBJECT, 4131: memory_object_copy_strategy_t COPY_STRATEGY) 4132: The function 'memory_object_set_attribute' controls how the memory 4133: object. The kernel will only make data or unlock requests when the 4134: ready attribute is asserted. If the caching attribute is asserted, 4135: the kernel is permitted (and encouraged) to maintain cached data 4136: for this memory object even after no virtual address space contains 4137: this data. 4138: 4139: There are three possible caching strategies: 4140: 'MEMORY_OBJECT_COPY_NONE' which specifies that nothing special 4141: should be done when data in the object is copied; 4142: 'MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager 4143: should be notified via a 'memory_object_copy' call before any part 4144: of the object is copied; and 'MEMORY_OBJECT_COPY_DELAY' which 4145: guarantees that the memory manager does not externally modify the 4146: data so that the kernel can use its normal copy-on-write 4147: algorithms. 'MEMORY_OBJECT_COPY_DELAY' is the strategy most 4148: commonly used. 4149: 4150: The argument MEMORY_CONTROL is the port, provided by the kernel in 4151: a 'memory_object_init' call, to which cache management requests may 4152: be issued. If OBJECT_READY is set, the kernel may issue new data 4153: and unlock requests on the associated memory object. If 4154: MAY_CACHE_OBJECT is set, the kernel may keep data associated with 4155: this memory object, even after virtual memory references to it are 4156: gone. COPY_STRATEGY tells how the kernel should copy regions of 4157: the associated memory object. 4158: 4159: This routine does not receive a reply message (and consequently has 4160: no return value), so only message transmission errors apply. 4161: 4162: 4163: File: mach.info, Node: Default Memory Manager, Prev: Memory Object Attributes, Up: External Memory Management 4164: 4165: 6.7 Default Memory Manager 4166: ========================== 4167: 4168: -- Function: kern_return_t vm_set_default_memory_manager (host_t HOST, 4169: mach_port_t *DEFAULT_MANAGER) 4170: The function 'vm_set_default_memory_manager' sets the kernel's 4171: default memory manager. It sets the port to which newly-created 4172: temporary memory objects are delivered by 'memory_object_create' to 4173: the host. The old memory manager port is returned. If 4174: DEFAULT_MANAGER is 'MACH_PORT_NULL' then this routine just returns 4175: the current default manager port without changing it. 4176: 4177: The argument HOST is a task port to the kernel whose default memory 4178: manager is to be changed. DEFAULT_MANAGER is an in/out parameter. 4179: As input, DEFAULT_MANAGER is the port that the new memory manager 4180: is listening on for 'memory_object_create' calls. As output, it is 4181: the old default memory manager's port. 4182: 4183: The function returns 'KERN_SUCCESS' if the new memory manager is 4184: installed, and 'KERN_INVALID_ARGUMENT' if this task does not have 4185: the privileges required for this call. 4186: 4187: -- Function: kern_return_t memory_object_create 4188: (memory_object_t OLD_MEMORY_OBJECT, 4189: memory_object_t NEW_MEMORY_OBJECT, vm_size_t NEW_OBJECT_SIZE, 4190: memory_object_control_t NEW_CONTROL, 4191: memory_object_name_t NEW_NAME, vm_size_t NEW_PAGE_SIZE) 4192: -- Function: kern_return_t seqnos_memory_object_create 4193: (memory_object_t OLD_MEMORY_OBJECT, mach_port_seqno_t SEQNO, 4194: memory_object_t NEW_MEMORY_OBJECT, vm_size_t NEW_OBJECT_SIZE, 4195: memory_object_control_t NEW_CONTROL, 4196: memory_object_name_t NEW_NAME, vm_size_t NEW_PAGE_SIZE) 4197: The function 'memory_object_create' is a request that the given 4198: memory manager accept responsibility for the given memory object 4199: created by the kernel. This call will only be made to the system 4200: *default memory manager*. The memory object in question initially 4201: consists of zero-filled memory; only memory pages that are actually 4202: written will ever be provided to 'memory_object_data_request' 4203: calls, the default memory manager must use 4204: 'memory_object_data_unavailable' for any pages that have not 4205: previously been written. 4206: 4207: No reply is expected after this call. Since this call is directed 4208: to the default memory manager, the kernel assumes that it will be 4209: ready to handle data requests to this object and does not need the 4210: confirmation of a 'memory_object_set_attributes' call. 4211: 4212: The argument OLD_MEMORY_OBJECT is a memory object provided by the 4213: default memory manager on which the kernel can make 4214: 'memory_object_create' calls. NEW_MEMORY_OBJECT is a new memory 4215: object created by the kernel; see synopsis for further description. 4216: Note that all port rights (including receive rights) are included 4217: for the new memory object. NEW_OBJECT_SIZE is the maximum size of 4218: the new object. NEW_CONTROL is a port, created by the kernel, on 4219: which a memory manager may issue cache management requests for the 4220: new object. NEW_NAME a port used by the kernel to refer to the new 4221: memory object data in response to 'vm_region' calls. NEW_PAGE_SIZE 4222: is the page size to be used by this kernel. All data sizes in 4223: calls involving this kernel must be an integral multiple of the 4224: page size. Note that different kernels, indicated by different a 4225: 'memory_control', may have different page sizes. 4226: 4227: The function should return 'KERN_SUCCESS', but since this routine 4228: is called by the kernel, which does not wait for a reply message, 4229: this value is ignored. 4230: 4231: -- Function: kern_return_t memory_object_data_initialize 4232: (memory_object_t MEMORY_OBJECT, 4233: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 4234: vm_offset_t DATA, vm_size_t DATA_COUNT) 4235: -- Function: kern_return_t seqnos_memory_object_data_initialize 4236: (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, 4237: memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, 4238: vm_offset_t DATA, vm_size_t DATA_COUNT) 4239: The function 'memory_object_data_initialize' provides the memory 4240: manager with initial data for a kernel-created memory object. If 4241: the memory manager already has been supplied data (by a previous 4242: 'memory_object_data_initialize', 'memory_object_data_write' or 4243: 'memory_object_data_return'), then this data should be ignored. 4244: Otherwise, this call behaves exactly as does 4245: 'memory_object_data_return' on memory objects created by the kernel 4246: via 'memory_object_create' and thus will only be made to default 4247: memory managers. This call will not be made on objects created via 4248: 'memory_object_copy'. 4249: 4250: The argument MEMORY_OBJECT the port that represents the memory 4251: object data, as supplied by the kernel in a 'memory_object_create' 4252: call. MEMORY_CONTROL is the request port to which a response is 4253: requested. (In the event that a memory object has been supplied to 4254: more than one the kernel that has made the request.) OFFSET is the 4255: offset within a memory object to which this call refers. This will 4256: be page aligned. DATA is the data which has been modified while 4257: cached in physical memory. DATA_COUNT is the amount of data to be 4258: written, in bytes. This will be an integral number of memory 4259: object pages. 4260: 4261: The function should return 'KERN_SUCCESS', but since this routine 4262: is called by the kernel, which does not wait for a reply message, 4263: this value is ignored. 4264: 4265: 4266: File: mach.info, Node: Threads and Tasks, Next: Host Interface, Prev: External Memory Management, Up: Top 4267: 4268: 7 Threads and Tasks 4269: ******************* 4270: 4271: * Menu: 4272: 4273: * Thread Interface:: Manipulating threads. 4274: * Task Interface:: Manipulating tasks. 4275: * Profiling:: Profiling threads and tasks. 4276: 4277: 4278: File: mach.info, Node: Thread Interface, Next: Task Interface, Up: Threads and Tasks 4279: 4280: 7.1 Thread Interface 4281: ==================== 4282: 4283: -- Data type: thread_t 4284: This is a 'mach_port_t' and used to hold the port name of a thread 4285: port that represents the thread. Manipulations of the thread are 4286: implemented as remote procedure calls to the thread port. A thread 4287: can get a port to itself with the 'mach_thread_self' system call. 4288: 4289: * Menu: 4290: 4291: * Thread Creation:: Creating new threads. 4292: * Thread Termination:: Terminating existing threads. 4293: * Thread Information:: How to get informations on threads. 4294: * Thread Settings:: How to set threads related informations. 4295: * Thread Execution:: How to control the thread's machine state. 4296: * Scheduling:: Operations on thread scheduling. 4297: * Thread Special Ports:: How to handle the thread's special ports. 4298: * Exceptions:: Managing exceptions. 4299: 4300: 4301: File: mach.info, Node: Thread Creation, Next: Thread Termination, Up: Thread Interface 4302: 4303: 7.1.1 Thread Creation 4304: --------------------- 4305: 4306: -- Function: kern_return_t thread_create (task_t PARENT_TASK, 4307: thread_t *CHILD_THREAD) 4308: The function 'thread_create' creates a new thread within the task 4309: specified by PARENT_TASK. The new thread has no processor state, 4310: and has a suspend count of 1. To get a new thread to run, first 4311: 'thread_create' is called to get the new thread's identifier, 4312: (CHILD_THREAD). Then 'thread_set_state' is called to set a 4313: processor state, and finally 'thread_resume' is called to get the 4314: thread scheduled to execute. 4315: 4316: When the thread is created send rights to its thread kernel port 4317: are given to it and returned to the caller in CHILD_THREAD. The 4318: new thread's exception port is set to 'MACH_PORT_NULL'. 4319: 4320: The function returns 'KERN_SUCCESS' if a new thread has been 4321: created, 'KERN_INVALID_ARGUMENT' if PARENT_TASK is not a valid task 4322: and 'KERN_RESOURCE_SHORTAGE' if some critical kernel resource is 4323: not available. 4324: 4325: 4326: File: mach.info, Node: Thread Termination, Next: Thread Information, Prev: Thread Creation, Up: Thread Interface 4327: 4328: 7.1.2 Thread Termination 4329: ------------------------ 4330: 4331: -- Function: kern_return_t thread_terminate (thread_t TARGET_THREAD) 4332: The function 'thread_terminate' destroys the thread specified by 4333: TARGET_THREAD. 4334: 4335: The function returns 'KERN_SUCCESS' if the thread has been killed 4336: and 'KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread. 4337: 4338: 4339: File: mach.info, Node: Thread Information, Next: Thread Settings, Prev: Thread Termination, Up: Thread Interface 4340: 4341: 7.1.3 Thread Information 4342: ------------------------ 4343: 4344: -- Function: thread_t mach_thread_self () 4345: The 'mach_thread_self' system call returns the calling thread's 4346: thread port. 4347: 4348: 'mach_thread_self' has an effect equivalent to receiving a send 4349: right for the thread port. 'mach_thread_self' returns the name of 4350: the send right. In particular, successive calls will increase the 4351: calling task's user-reference count for the send right. 4352: 4353: As a special exception, the kernel will overrun the user reference 4354: count of the thread name port, so that this function can not fail 4355: for that reason. Because of this, the user should not deallocate 4356: the port right if an overrun might have happened. Otherwise the 4357: reference count could drop to zero and the send right be destroyed 4358: while the user still expects to be able to use it. As the kernel 4359: does not make use of the number of extant send rights anyway, this 4360: is safe to do (the thread port itself is not destroyed, even when 4361: there are no send rights anymore). 4362: 4363: The function returns 'MACH_PORT_NULL' if a resource shortage 4364: prevented the reception of the send right or if the thread port is 4365: currently null and 'MACH_PORT_DEAD' if the thread port is currently 4366: dead. 4367: 4368: -- Function: kern_return_t thread_info (thread_t TARGET_THREAD, 4369: int FLAVOR, thread_info_t THREAD_INFO, 4370: mach_msg_type_number_t *THREAD_INFOCNT) 4371: The function 'thread_info' returns the selected information array 4372: for a thread, as specified by FLAVOR. 4373: 4374: THREAD_INFO is an array of integers that is supplied by the caller 4375: and returned filled with specified information. THREAD_INFOCNT is 4376: supplied as the maximum number of integers in THREAD_INFO. On 4377: return, it contains the actual number of integers in THREAD_INFO. 4378: The maximum number of integers returned by any flavor is 4379: 'THREAD_INFO_MAX'. 4380: 4381: The type of information returned is defined by FLAVOR, which can be 4382: one of the following: 4383: 4384: 'THREAD_BASIC_INFO' 4385: The function returns basic information about the thread, as 4386: defined by 'thread_basic_info_t'. This includes the user and 4387: system time, the run state, and scheduling priority. The 4388: number of integers returned is 'THREAD_BASIC_INFO_COUNT'. 4389: 4390: 'THREAD_SCHED_INFO' 4391: The function returns information about the scheduling policy 4392: for the thread as defined by 'thread_sched_info_t'. The 4393: number of integers returned is 'THREAD_SCHED_INFO_COUNT'. 4394: 4395: The function returns 'KERN_SUCCESS' if the call succeeded and 4396: 'KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread or FLAVOR 4397: is not recognized. The function returns 'MIG_ARRAY_TOO_LARGE' if 4398: the returned info array is too large for THREAD_INFO. In this 4399: case, THREAD_INFO is filled as much as possible and THREAD_INFOCNT 4400: is set to the number of elements that would have been returned if 4401: there were enough room. 4402: 4403: -- Data type: struct thread_basic_info 4404: This structure is returned in THREAD_INFO by the 'thread_info' 4405: function and provides basic information about the thread. You can 4406: cast a variable of type 'thread_info_t' to a pointer of this type 4407: if you provided it as the THREAD_INFO parameter for the 4408: 'THREAD_BASIC_INFO' flavor of 'thread_info'. It has the following 4409: members: 4410: 4411: 'time_value_t user_time' 4412: user run time 4413: 4414: 'time_value_t system_time' 4415: system run time 4416: 'int cpu_usage' 4417: Scaled cpu usage percentage. The scale factor is 4418: 'TH_USAGE_SCALE'. 4419: 4420: 'int base_priority' 4421: The base scheduling priority of the thread. 4422: 4423: 'int cur_priority' 4424: The current scheduling priority of the thread. 4425: 4426: 'integer_t run_state' 4427: The run state of the thread. The possible values of this 4428: field are: 4429: 'TH_STATE_RUNNING' 4430: The thread is running normally. 4431: 4432: 'TH_STATE_STOPPED' 4433: The thread is suspended. 4434: 4435: 'TH_STATE_WAITING' 4436: The thread is waiting normally. 4437: 4438: 'TH_STATE_UNINTERRUPTIBLE' 4439: The thread is in an uninterruptible wait. 4440: 4441: 'TH_STATE_HALTED' 4442: The thread is halted at a clean point. 4443: 4444: 'flags' 4445: Various flags. The possible values of this field are: 4446: 'TH_FLAGS_SWAPPED' 4447: The thread is swapped out. 4448: 4449: 'TH_FLAGS_IDLE' 4450: The thread is an idle thread. 4451: 4452: 'int suspend_count' 4453: The suspend count for the thread. 4454: 4455: 'int sleep_time' 4456: The number of seconds that the thread has been sleeping. 4457: 4458: 'time_value_t creation_time' 4459: The time stamp of creation. 4460: 4461: -- Data type: thread_basic_info_t 4462: This is a pointer to a 'struct thread_basic_info'. 4463: 4464: -- Data type: struct thread_sched_info 4465: This structure is returned in THREAD_INFO by the 'thread_info' 4466: function and provides schedule information about the thread. You 4467: can cast a variable of type 'thread_info_t' to a pointer of this 4468: type if you provided it as the THREAD_INFO parameter for the 4469: 'THREAD_SCHED_INFO' flavor of 'thread_info'. It has the following 4470: members: 4471: 4472: 'int policy' 4473: The scheduling policy of the thread, *note Scheduling 4474: Policy::. 4475: 4476: 'integer_t data' 4477: Policy-dependent scheduling information, *note Scheduling 4478: Policy::. 4479: 4480: 'int base_priority' 4481: The base scheduling priority of the thread. 4482: 4483: 'int max_priority' 4484: The maximum scheduling priority of the thread. 4485: 4486: 'int cur_priority' 4487: The current scheduling priority of the thread. 4488: 4489: 'int depressed' 4490: 'TRUE' if the thread is depressed. 4491: 4492: 'int depress_priority' 4493: The priority the thread was depressed from. 4494: 4495: -- Data type: thread_sched_info_t 4496: This is a pointer to a 'struct thread_sched_info'. 4497: 4498: 4499: File: mach.info, Node: Thread Settings, Next: Thread Execution, Prev: Thread Information, Up: Thread Interface 4500: 4501: 7.1.4 Thread Settings 4502: --------------------- 4503: 4504: -- Function: kern_return_t thread_wire (host_priv_t HOST_PRIV, 4505: thread_t THREAD, boolean_t WIRED) 4506: The function 'thread_wire' controls the VM privilege level of the 4507: thread THREAD. A VM-privileged thread never waits inside the 4508: kernel for memory allocation from the kernel's free list of pages 4509: or for allocation of a kernel stack. 4510: 4511: Threads that are part of the default pageout path should be 4512: VM-privileged, to prevent system deadlocks. Threads that are not 4513: part of the default pageout path should not be VM-privileged, to 4514: prevent the kernel's free list of pages from being exhausted. 4515: 4516: The functions returns 'KERN_SUCCESS' if the call succeeded, 4517: 'KERN_INVALID_ARGUMENT' if HOST_PRIV or THREAD was invalid. 4518: 4519: The 'thread_wire' call is actually an RPC to HOST_PRIV, normally a 4520: send right for a privileged host port, but potentially any send 4521: right. In addition to the normal diagnostic return codes from the 4522: call's server (normally the kernel), the call may return 'mach_msg' 4523: return codes. 4524: 4525: 4526: File: mach.info, Node: Thread Execution, Next: Scheduling, Prev: Thread Settings, Up: Thread Interface 4527: 4528: 7.1.5 Thread Execution 4529: ---------------------- 4530: 4531: -- Function: kern_return_t thread_suspend (thread_t TARGET_THREAD) 4532: Increments the thread's suspend count and prevents the thread from 4533: executing any more user level instructions. In this context a user 4534: level instruction is either a machine instruction executed in user 4535: mode or a system trap instruction including page faults. Thus if a 4536: thread is currently executing within a system trap the kernel code 4537: may continue to execute until it reaches the system return code or 4538: it may suspend within the kernel code. In either case, when the 4539: thread is resumed the system trap will return. This could cause 4540: unpredictable results if the user did a suspend and then altered 4541: the user state of the thread in order to change its direction upon 4542: a resume. The call 'thread_abort' is provided to allow the user to 4543: abort any system call that is in progress in a predictable way. 4544: 4545: The suspend count may become greater than one with the effect that 4546: it will take more than one resume call to restart the thread. 4547: 4548: The function returns 'KERN_SUCCESS' if the thread has been 4549: suspended and 'KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a 4550: thread. 4551: 4552: -- Function: kern_return_t thread_resume (thread_t TARGET_THREAD) 4553: Decrements the thread's suspend count. If the count becomes zero 4554: the thread is resumed. If it is still positive, the thread is left 4555: suspended. The suspend count may not become negative. 4556: 4557: The function returns 'KERN_SUCCESS' if the thread has been resumed, 4558: 'KERN_FAILURE' if the suspend count is already zero and 4559: 'KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread. 4560: 4561: -- Function: kern_return_t thread_abort (thread_t TARGET_THREAD) 4562: The function 'thread_abort' aborts the kernel primitives: 4563: 'mach_msg', 'msg_send', 'msg_receive' and 'msg_rpc' and 4564: page-faults, making the call return a code indicating that it was 4565: interrupted. The call is interrupted whether or not the thread (or 4566: task containing it) is currently suspended. If it is suspended, 4567: the thread receives the interrupt when it is resumed. 4568: 4569: A thread will retry an aborted page-fault if its state is not 4570: modified before it is resumed. 'msg_send' returns 4571: 'SEND_INTERRUPTED'; 'msg_receive' returns 'RCV_INTERRUPTED'; 4572: 'msg_rpc' returns either 'SEND_INTERRUPTED' or 'RCV_INTERRUPTED', 4573: depending on which half of the RPC was interrupted. 4574: 4575: The main reason for this primitive is to allow one thread to 4576: cleanly stop another thread in a manner that will allow the future 4577: execution of the target thread to be controlled in a predictable 4578: way. 'thread_suspend' keeps the target thread from executing any 4579: further instructions at the user level, including the return from a 4580: system call. 'thread_get_state'/'thread_set_state' allows the 4581: examination or modification of the user state of a target thread. 4582: However, if a suspended thread was executing within a system call, 4583: it also has associated with it a kernel state. This kernel state 4584: can not be modified by 'thread_set_state' with the result that when 4585: the thread is resumed the system call may return changing the user 4586: state and possibly user memory. 'thread_abort' aborts the kernel 4587: call from the target thread's point of view by resetting the kernel 4588: state so that the thread will resume execution at the system call 4589: return with the return code value set to one of the interrupted 4590: codes. The system call itself will either be entirely completed or 4591: entirely aborted, depending on the precise moment at which the 4592: abort was received. Thus if the thread's user state has been 4593: changed by 'thread_set_state', it will not be modified by any 4594: unexpected system call side effects. 4595: 4596: For example to simulate a Unix signal, the following sequence of 4597: calls may be used: 4598: 4599: 1. 'thread_suspend': Stops the thread. 4600: 4601: 2. 'thread_abort': Interrupts any system call in progress, 4602: setting the return value to 'interrupted'. Since the thread 4603: is stopped, it will not return to user code. 4604: 4605: 3. 'thread_set_state': Alters thread's state to simulate a 4606: procedure call to the signal handler 4607: 4608: 4. 'thread_resume': Resumes execution at the signal handler. If 4609: the thread's stack has been correctly set up, the thread may 4610: return to the interrupted system call. (Of course, the code 4611: to push an extra stack frame and change the registers is VERY 4612: machine-dependent.) 4613: 4614: Calling 'thread_abort' on a non-suspended thread is pretty risky, 4615: since it is very difficult to know exactly what system trap, if 4616: any, the thread might be executing and whether an interrupt return 4617: would cause the thread to do something useful. 4618: 4619: The function returns 'KERN_SUCCESS' if the thread received an 4620: interrupt and 'KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a 4621: thread. 4622: 4623: -- Function: kern_return_t thread_get_state (thread_t TARGET_THREAD, 4624: int FLAVOR, thread_state_t OLD_STATE, 4625: mach_msg_type_number_t *OLD_STATECNT) 4626: The function 'thread_get_state' returns the execution state (e.g. 4627: the machine registers) of TARGET_THREAD as specified by FLAVOR. 4628: The OLD_STATE is an array of integers that is provided by the 4629: caller and returned filled with the specified information. 4630: OLD_STATECNT is input set to the maximum number of integers in 4631: OLD_STATE and returned equal to the actual number of integers in 4632: OLD_STATE. 4633: 4634: TARGET_THREAD may not be 'mach_thread_self()'. 4635: 4636: The definition of the state structures can be found in 4637: 'machine/thread_status.h'. 4638: 4639: The function returns 'KERN_SUCCESS' if the state has been returned, 4640: 'KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread or is 4641: 'mach_thread_self' or FLAVOR is unrecognized for this machine. The 4642: function returns 'MIG_ARRAY_TOO_LARGE' if the returned state is too 4643: large for OLD_STATE. In this case, OLD_STATE is filled as much as 4644: possible and OLD_STATECNT is set to the number of elements that 4645: would have been returned if there were enough room. 4646: 4647: -- Function: kern_return_t thread_set_state (thread_t TARGET_THREAD, 4648: int FLAVOR, thread_state_t NEW_STATE, 4649: mach_msg_type_number_t NEW_STATE_COUNT) 4650: The function 'thread_set_state' sets the execution state (e.g. the 4651: machine registers) of TARGET_THREAD as specified by FLAVOR. The 4652: NEW_STATE is an array of integers. NEW_STATE_COUNT is the number 4653: of elements in NEW_STATE. The entire set of registers is reset. 4654: This will do unpredictable things if TARGET_THREAD is not 4655: suspended. 4656: 4657: TARGET_THREAD may not be 'mach_thread_self'. 4658: 4659: The definition of the state structures can be found in 4660: 'machine/thread_status.h'. 4661: 4662: The function returns 'KERN_SUCCESS' if the state has been set and 4663: 'KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread or is 4664: 'mach_thread_self' or FLAVOR is unrecognized for this machine. 4665: 4666: 4667: File: mach.info, Node: Scheduling, Next: Thread Special Ports, Prev: Thread Execution, Up: Thread Interface 4668: 4669: 7.1.6 Scheduling 4670: ---------------- 4671: 4672: * Menu: 4673: 4674: * Thread Priority:: Changing the priority of a thread. 4675: * Hand-Off Scheduling:: Switching to a new thread. 4676: * Scheduling Policy:: Setting the scheduling policy. 4677: 4678: 4679: File: mach.info, Node: Thread Priority, Next: Hand-Off Scheduling, Up: Scheduling 4680: 4681: 7.1.6.1 Thread Priority 4682: ....................... 4683: 4684: Threads have three priorities associated with them by the system, a 4685: priority, a maximum priority, and a scheduled priority. The scheduled 4686: priority is used to make scheduling decisions about the thread. It is 4687: determined from the priority by the policy (for timesharing, this means 4688: adding an increment derived from cpu usage). The priority can be set 4689: under user control, but may never exceed the maximum priority. Changing 4690: the maximum priority requires presentation of the control port for the 4691: thread's processor set; since the control port for the default processor 4692: set is privileged, users cannot raise their maximum priority to unfairly 4693: compete with other users on that set. Newly created threads obtain 4694: their priority from their task and their max priority from the thread. 4695: 4696: -- Function: kern_return_t thread_priority (thread_t THREAD, 4697: int PRORITY, boolean_t SET_MAX) 4698: The function 'thread_priority' changes the priority and optionally 1.1.1.2 ! root 4699: the maximum priority of THREAD. Priorities range from 0 to 49, 1.1 root 4700: where lower numbers denote higher priorities. If the new priority 4701: is higher than the priority of the current thread, preemption may 4702: occur as a result of this call. The maximum priority of the thread 4703: is also set if SET_MAX is 'TRUE'. This call will fail if PRIORITY 4704: is greater than the current maximum priority of the thread. As a 4705: result, this call can only lower the value of a thread's maximum 4706: priority. 4707: 4708: The functions returns 'KERN_SUCCESS' if the operation completed 4709: successfully, 'KERN_INVALID_ARGUMENT' if THREAD is not a thread or 1.1.1.2 ! root 4710: PRIORITY is out of range (not in 0..49), and 'KERN_FAILURE' if the 1.1 root 4711: requested operation would violate the thread's maximum priority 4712: (thread_priority). 4713: 4714: -- Function: kern_return_t thread_max_priority (thread_t THREAD, 4715: processor_set_t PROCESSOR_SET, int PRIORITY) 4716: The function 'thread_max_priority' changes the maximum priority of 4717: the thread. Because it requires presentation of the corresponding 4718: processor set port, this call can reset the maximum priority to any 4719: legal value. 4720: 4721: The functions returns 'KERN_SUCCESS' if the operation completed 4722: successfully, 'KERN_INVALID_ARGUMENT' if THREAD is not a thread or 4723: PROCESSOR_SET is not a control port for a processor set or PRIORITY 1.1.1.2 ! root 4724: is out of range (not in 0..49), and 'KERN_FAILURE' if the thread is 1.1 root 4725: not assigned to the processor set whose control port was presented. 4726: 4727: 4728: File: mach.info, Node: Hand-Off Scheduling, Next: Scheduling Policy, Prev: Thread Priority, Up: Scheduling 4729: 4730: 7.1.6.2 Hand-Off Scheduling 4731: ........................... 4732: 4733: -- Function: kern_return_t thread_switch (thread_t NEW_THREAD, 4734: int OPTION, int TIME) 4735: The function 'thread_switch' provides low-level access to the 4736: scheduler's context switching code. NEW_THREAD is a hint that 4737: implements hand-off scheduling. The operating system will attempt 4738: to switch directly to the new thread (bypassing the normal logic 4739: that selects the next thread to run) if possible. Since this is a 4740: hint, it may be incorrect; it is ignored if it doesn't specify a 4741: thread on the same host as the current thread or if that thread 4742: can't be switched to (i.e., not runnable or already running on 4743: another processor or giving a plainly invalid hint, such as 4744: 'MACH_PORT_NULL'). In this case, the normal logic to select the 4745: next thread to run is used; the current thread may continue running 4746: if there is no other appropriate thread to run. 4747: 4748: Options for OPTION are defined in 'mach/thread_switch.h' and 4749: specify the interpretation of TIME. The possible values for OPTION 4750: are: 4751: 4752: 'SWITCH_OPTION_NONE' 4753: No options, the time argument is ignored. 4754: 4755: 'SWITCH_OPTION_WAIT' 4756: The thread is blocked for the specified time (in milliseconds; 4757: specifying '0' will wait for the next tick). This can be 4758: aborted by 'thread_abort'. 4759: 4760: 'SWITCH_OPTION_DEPRESS' 4761: The thread's priority is depressed to the lowest possible 4762: value for the specified time. This can be aborted by 4763: 'thread_depress_abort'. This depression is independent of 4764: operations that change the thread's priority (e.g. 4765: 'thread_priority' will not abort the depression). The minimum 4766: time and units of time can be obtained as the 'min_timeout' 4767: value from 'host_info'. The depression is also aborted when 4768: the current thread is next run (either via hand-off scheduling 4769: or because the processor set has nothing better to do). 4770: 4771: 'thread_switch' is often called when the current thread can proceed 4772: no further for some reason; the various options and arguments allow 4773: information about this reason to be transmitted to the kernel. The 4774: NEW_THREAD argument (handoff scheduling) is useful when the 4775: identity of the thread that must make progress before the current 4776: thread runs again is known. The 'WAIT' option is used when the 4777: amount of time that the current thread must wait before it can do 4778: anything useful can be estimated and is fairly long. The 'DEPRESS' 4779: option is used when the amount of time that must be waited is 4780: fairly short, especially when the identity of the thread that is 4781: being waited for is not known. 4782: 4783: Users should beware of calling 'thread_switch' with an invalid hint 4784: (e.g. 'MACH_PORT_NULL') and no option. Because the time-sharing 4785: scheduler varies the priority of threads based on usage, this may 4786: result in a waste of cpu time if the thread that must be run is of 4787: lower priority. The use of the 'DEPRESS' option in this situation 4788: is highly recommended. 4789: 4790: 'thread_switch' ignores policies. Users relying on the preemption 4791: semantics of a fixed time policy should be aware that 4792: 'thread_switch' ignores these semantics; it will run the specified 4793: NEW_THREAD independent of its priority and the priority of any 4794: other threads that could be run instead. 4795: 4796: The function returns 'KERN_SUCCESS' if the call succeeded, 4797: 'KERN_INVALID_ARGUMENT' if THREAD is not a thread or OPTION is not 4798: a recognized option, and 'KERN_FAILURE' if 'kern_depress_abort' 4799: failed because the thread was not depressed. 4800: 4801: -- Function: kern_return_t thread_depress_abort (thread_t THREAD) 4802: The function 'thread_depress_abort' cancels any priority depression 4803: for THREAD caused by a 'swtch_pri' or 'thread_switch' call. 4804: 4805: The function returns 'KERN_SUCCESS' if the call succeeded and 4806: 'KERN_INVALID_ARGUMENT' if THREAD is not a valid thread. 4807: 4808: -- Function: boolean_t swtch () 4809: The system trap 'swtch' attempts to switch the current thread off 4810: the processor. The return value indicates if more than the current 4811: thread is running in the processor set. This is useful for lock 4812: management routines. 4813: 4814: The call returns 'FALSE' if the thread is justified in becoming a 4815: resource hog by continuing to spin because there's nothing else 4816: useful that the processor could do. 'TRUE' is returned if the 4817: thread should make one more check on the lock and then be a good 4818: citizen and really suspend. 4819: 4820: -- Function: boolean_t swtch_pri (int PRIORITY) 4821: The system trap 'swtch_pri' attempts to switch the current thread 4822: off the processor as 'swtch' does, but depressing the priority of 4823: the thread to the minimum possible value during the time. PRIORITY 4824: is not used currently. 4825: 4826: The return value is as for 'swtch'. 4827: 4828: 4829: File: mach.info, Node: Scheduling Policy, Prev: Hand-Off Scheduling, Up: Scheduling 4830: 4831: 7.1.6.3 Scheduling Policy 4832: ......................... 4833: 4834: -- Function: kern_return_t thread_policy (thread_t THREAD, int POLICY, 4835: int DATA) 4836: The function 'thread_policy' changes the scheduling policy for 4837: THREAD to POLICY. 4838: 4839: DATA is policy-dependent scheduling information. There are 4840: currently two supported policies: 'POLICY_TIMESHARE' and 4841: 'POLICY_FIXEDPRI' defined in 'mach/policy.h'; this file is included 4842: by 'mach.h'. DATA is meaningless for timesharing, but is the 4843: quantum to be used (in milliseconds) for the fixed priority policy. 4844: To be meaningful, this quantum must be a multiple of the basic 4845: system quantum (min_quantum) which can be obtained from 4846: 'host_info'. The system will always round up to the next multiple 4847: of the quantum. 4848: 4849: Processor sets may restrict the allowed policies, so this call will 4850: fail if the processor set to which THREAD is currently assigned 4851: does not permit POLICY. 4852: 4853: The function returns 'KERN_SUCCESS' if the call succeeded. 4854: 'KERN_INVALID_ARGUMENT' if THREAD is not a thread or POLICY is not 4855: a recognized policy, and 'KERN_FAILURE' if the processor set to 4856: which THREAD is currently assigned does not permit POLICY. 4857: 4858: 4859: File: mach.info, Node: Thread Special Ports, Next: Exceptions, Prev: Scheduling, Up: Thread Interface 4860: 4861: 7.1.7 Thread Special Ports 4862: -------------------------- 4863: 4864: -- Function: kern_return_t thread_get_special_port (thread_t THREAD, 4865: int WHICH_PORT, mach_port_t *SPECIAL_PORT) 4866: The function 'thread_get_special_port' returns send rights to one 4867: of a set of special ports for the thread specified by THREAD. 4868: 4869: The possible values for WHICH_PORT are 'THREAD_KERNEL_PORT' and 4870: 'THREAD_EXCEPTION_PORT'. A thread also has access to its task's 4871: special ports. 4872: 4873: The function returns 'KERN_SUCCESS' if the port was returned and 4874: 'KERN_INVALID_ARGUMENT' if THREAD is not a thread or WHICH_PORT is 4875: an invalid port selector. 4876: 4877: -- Function: kern_return_t thread_get_kernel_port (thread_t THREAD, 4878: mach_port_t *KERNEL_PORT) 4879: The function 'thread_get_kernel_port' is equivalent to the function 4880: 'thread_get_special_port' with the WHICH_PORT argument set to 4881: 'THREAD_KERNEL_PORT'. 4882: 4883: -- Function: kern_return_t thread_get_exception_port (thread_t THREAD, 4884: mach_port_t *EXCEPTION_PORT) 4885: The function 'thread_get_exception_port' is equivalent to the 4886: function 'thread_get_special_port' with the WHICH_PORT argument set 4887: to 'THREAD_EXCEPTION_PORT'. 4888: 4889: -- Function: kern_return_t thread_set_special_port (thread_t THREAD, 4890: int WHICH_PORT, mach_port_t SPECIAL_PORT) 4891: The function 'thread_set_special_port' sets one of a set of special 4892: ports for the thread specified by THREAD. 4893: 4894: The possible values for WHICH_PORT are 'THREAD_KERNEL_PORT' and 4895: 'THREAD_EXCEPTION_PORT'. A thread also has access to its task's 4896: special ports. 4897: 4898: The function returns 'KERN_SUCCESS' if the port was set and 4899: 'KERN_INVALID_ARGUMENT' if THREAD is not a thread or WHICH_PORT is 4900: an invalid port selector. 4901: 4902: -- Function: kern_return_t thread_set_kernel_port (thread_t THREAD, 4903: mach_port_t KERNEL_PORT) 4904: The function 'thread_set_kernel_port' is equivalent to the function 4905: 'thread_set_special_port' with the WHICH_PORT argument set to 4906: 'THREAD_KERNEL_PORT'. 4907: 4908: -- Function: kern_return_t thread_set_exception_port (thread_t THREAD, 4909: mach_port_t EXCEPTION_PORT) 4910: The function 'thread_set_exception_port' is equivalent to the 4911: function 'thread_set_special_port' with the WHICH_PORT argument set 4912: to 'THREAD_EXCEPTION_PORT'. 4913: 4914: 4915: File: mach.info, Node: Exceptions, Prev: Thread Special Ports, Up: Thread Interface 4916: 4917: 7.1.8 Exceptions 4918: ---------------- 4919: 4920: -- Function: kern_return_t catch_exception_raise 4921: (mach_port_t EXCEPTION_PORT, thread_t THREAD, task_t TASK, 4922: int EXCEPTION, int CODE, int SUBCODE) 4923: XXX Fixme 4924: 4925: -- Function: kern_return_t exception_raise (mach_port_t EXCEPTION_PORT, 4926: mach_port_t THREAD, mach_port_t TASK, integer_t EXCEPTION, 4927: integer_t CODE, integer_t SUBCODE) 4928: XXX Fixme 4929: 4930: -- Function: kern_return_t evc_wait (unsigned int EVENT) 4931: The system trap 'evc_wait' makes the calling thread wait for the 4932: event specified by EVENT. 4933: 4934: The call returns 'KERN_SUCCESS' if the event has occurred, 4935: 'KERN_NO_SPACE' if another thread is waiting for the same event and 4936: 'KERN_INVALID_ARGUMENT' if the event object is invalid. 4937: 4938: 4939: File: mach.info, Node: Task Interface, Next: Profiling, Prev: Thread Interface, Up: Threads and Tasks 4940: 4941: 7.2 Task Interface 4942: ================== 4943: 4944: -- Data type: task_t 4945: This is a 'mach_port_t' and used to hold the port name of a task 4946: port that represents the thread. Manipulations of the task are 4947: implemented as remote procedure calls to the task port. A task can 4948: get a port to itself with the 'mach_task_self' system call. 4949: 4950: The task port name is also used to identify the task's IPC space 4951: (*note Port Manipulation Interface::) and the task's virtual memory 4952: map (*note Virtual Memory Interface::). 4953: 4954: * Menu: 4955: 4956: * Task Creation:: Creating tasks. 4957: * Task Termination:: Terminating tasks. 4958: * Task Information:: Informations on tasks. 4959: * Task Execution:: Thread scheduling in a task. 4960: * Task Special Ports:: How to get and set the task's special ports. 4961: * Syscall Emulation:: How to emulate system calls. 4962: 4963: 4964: File: mach.info, Node: Task Creation, Next: Task Termination, Up: Task Interface 4965: 4966: 7.2.1 Task Creation 4967: ------------------- 4968: 4969: -- Function: kern_return_t task_create (task_t PARENT_TASK, 4970: boolean_t INHERIT_MEMORY, task_t *CHILD_TASK) 4971: The function 'task_create' creates a new task from PARENT_TASK; the 4972: resulting task (CHILD_TASK) acquires shared or copied parts of the 4973: parent's address space (see 'vm_inherit'). The child task 4974: initially contains no threads. 4975: 4976: If INHERIT_MEMORY is set, the child task's address space is built 4977: from the parent task according to its memory inheritance values; 4978: otherwise, the child task is given an empty address space. 4979: 4980: The child task gets the three special ports created or copied for 4981: it at task creation. The 'TASK_KERNEL_PORT' is created and send 4982: rights for it are given to the child and returned to the caller. 4983: The 'TASK_BOOTSTRAP_PORT' and the 'TASK_EXCEPTION_PORT' are 4984: inherited from the parent task. The new task can get send rights 4985: to these ports with the call 'task_get_special_port'. 4986: 4987: The function returns 'KERN_SUCCESS' if a new task has been created, 4988: 'KERN_INVALID_ARGUMENT' if PARENT_TASK is not a valid task port and 4989: 'KERN_RESOURCE_SHORTAGE' if some critical kernel resource is 4990: unavailable. 4991: 4992: 4993: File: mach.info, Node: Task Termination, Next: Task Information, Prev: Task Creation, Up: Task Interface 4994: 4995: 7.2.2 Task Termination 4996: ---------------------- 4997: 4998: -- Function: kern_return_t task_terminate (task_t TARGET_TASK) 4999: The function 'task_terminate' destroys the task specified by 5000: TARGET_TASK and all its threads. All resources that are used only 5001: by this task are freed. Any port to which this task has receive 5002: and ownership rights is destroyed. 5003: 5004: The function returns 'KERN_SUCCESS' if the task has been killed, 5005: 'KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task. 5006: 5007: 5008: File: mach.info, Node: Task Information, Next: Task Execution, Prev: Task Termination, Up: Task Interface 5009: 5010: 7.2.3 Task Information 5011: ---------------------- 5012: 5013: -- Function: task_t mach_task_self () 5014: The 'mach_task_self' system call returns the calling thread's task 5015: port. 5016: 5017: 'mach_task_self' has an effect equivalent to receiving a send right 5018: for the task port. 'mach_task_self' returns the name of the send 5019: right. In particular, successive calls will increase the calling 5020: task's user-reference count for the send right. 5021: 5022: As a special exception, the kernel will overrun the user reference 5023: count of the task name port, so that this function can not fail for 5024: that reason. Because of this, the user should not deallocate the 5025: port right if an overrun might have happened. Otherwise the 5026: reference count could drop to zero and the send right be destroyed 5027: while the user still expects to be able to use it. As the kernel 5028: does not make use of the number of extant send rights anyway, this 5029: is safe to do (the task port itself is not destroyed, even when 5030: there are no send rights anymore). 5031: 5032: The function returns 'MACH_PORT_NULL' if a resource shortage 5033: prevented the reception of the send right, 'MACH_PORT_NULL' if the 5034: task port is currently null, 'MACH_PORT_DEAD' if the task port is 5035: currently dead. 5036: 5037: -- Function: kern_return_t task_threads (task_t TARGET_TASK, 5038: thread_array_t *THREAD_LIST, 5039: mach_msg_type_number_t *THREAD_COUNT) 5040: The function 'task_threads' gets send rights to the kernel port for 5041: each thread contained in TARGET_TASK. THREAD_LIST is an array that 5042: is created as a result of this call. The caller may wish to 5043: 'vm_deallocate' this array when the data is no longer needed. 5044: 5045: The function returns 'KERN_SUCCESS' if the call succeeded and 5046: 'KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task. 5047: 5048: -- Function: kern_return_t task_info (task_t TARGET_TASK, int FLAVOR, 5049: task_info_t TASK_INFO, 5050: mach_msg_type_number_t *TASK_INFO_COUNT) 5051: The function 'task_info' returns the selected information array for 5052: a task, as specified by FLAVOR. TASK_INFO is an array of integers 5053: that is supplied by the caller, and filled with specified 5054: information. TASK_INFO_COUNT is supplied as the maximum number of 5055: integers in TASK_INFO. On return, it contains the actual number of 5056: integers in TASK_INFO. The maximum number of integers returned by 5057: any flavor is 'TASK_INFO_MAX'. 5058: 5059: The type of information returned is defined by FLAVOR, which can be 5060: one of the following: 5061: 5062: 'TASK_BASIC_INFO' 5063: The function returns basic information about the task, as 5064: defined by 'task_basic_info_t'. This includes the user and 5065: system time and memory consumption. The number of integers 5066: returned is 'TASK_BASIC_INFO_COUNT'. 5067: 5068: 'TASK_EVENTS_INFO' 5069: The function returns information about events for the task as 5070: defined by 'thread_sched_info_t'. This includes statistics 5071: about virtual memory and IPC events like pageouts, pageins and 5072: messages sent and received. The number of integers returned 5073: is 'TASK_EVENTS_INFO_COUNT'. 5074: 5075: 'TASK_THREAD_TIMES_INFO' 5076: The function returns information about the total time for live 5077: threads as defined by 'task_thread_times_info_t'. The number 5078: of integers returned is 'TASK_THREAD_TIMES_INFO_COUNT'. 5079: 5080: The function returns 'KERN_SUCCESS' if the call succeeded and 5081: 'KERN_INVALID_ARGUMENT' if TARGET_TASK is not a thread or FLAVOR is 5082: not recognized. The function returns 'MIG_ARRAY_TOO_LARGE' if the 5083: returned info array is too large for TASK_INFO. In this case, 5084: TASK_INFO is filled as much as possible and TASK_INFOCNT is set to 5085: the number of elements that would have been returned if there were 5086: enough room. 5087: 5088: -- Data type: struct task_basic_info 5089: This structure is returned in TASK_INFO by the 'task_info' function 5090: and provides basic information about the task. You can cast a 5091: variable of type 'task_info_t' to a pointer of this type if you 5092: provided it as the TASK_INFO parameter for the 'TASK_BASIC_INFO' 5093: flavor of 'task_info'. It has the following members: 5094: 5095: 'integer_t suspend_count' 5096: suspend count for task 5097: 5098: 'integer_t base_priority' 5099: base scheduling priority 5100: 5101: 'vm_size_t virtual_size' 5102: number of virtual pages 5103: 5104: 'vm_size_t resident_size' 5105: number of resident pages 5106: 5107: 'time_value_t user_time' 5108: total user run time for terminated threads 5109: 5110: 'time_value_t system_time' 5111: total system run time for terminated threads 5112: 5113: 'time_value_t creation_time' 5114: creation time stamp 5115: 5116: -- Data type: task_basic_info_t 5117: This is a pointer to a 'struct task_basic_info'. 5118: 5119: -- Data type: struct task_events_info 5120: This structure is returned in TASK_INFO by the 'task_info' function 5121: and provides event statistics for the task. You can cast a 5122: variable of type 'task_info_t' to a pointer of this type if you 5123: provided it as the TASK_INFO parameter for the 'TASK_EVENTS_INFO' 5124: flavor of 'task_info'. It has the following members: 5125: 5126: 'natural_t faults' 5127: number of page faults 5128: 5129: 'natural_t zero_fills' 5130: number of zero fill pages 5131: 5132: 'natural_t reactivations' 5133: number of reactivated pages 5134: 5135: 'natural_t pageins' 5136: number of actual pageins 5137: 5138: 'natural_t cow_faults' 5139: number of copy-on-write faults 5140: 5141: 'natural_t messages_sent' 5142: number of messages sent 5143: 5144: 'natural_t messages_received' 5145: number of messages received 5146: 5147: -- Data type: task_events_info_t 5148: This is a pointer to a 'struct task_events_info'. 5149: 5150: -- Data type: struct task_thread_times_info 5151: This structure is returned in TASK_INFO by the 'task_info' function 5152: and provides event statistics for the task. You can cast a 5153: variable of type 'task_info_t' to a pointer of this type if you 5154: provided it as the TASK_INFO parameter for the 5155: 'TASK_THREAD_TIMES_INFO' flavor of 'task_info'. It has the 5156: following members: 5157: 5158: 'time_value_t user_time' 5159: total user run time for live threads 5160: 5161: 'time_value_t system_time' 5162: total system run time for live threads 5163: 5164: -- Data type: task_thread_times_info_t 5165: This is a pointer to a 'struct task_thread_times_info'. 5166: 1.1.1.2 ! root 5167: -- Function: kern_return_t task_set_name (task_t TARGET_TASK, ! 5168: kernel_debug_name_t NAME) ! 5169: ! 5170: The function 'task_set_name' sets the name of TARGET_TASK to NAME, ! 5171: truncating it if necessary. ! 5172: ! 5173: This is a debugging aid. The name is used in diagnostic messages ! 5174: printed by the kernel. ! 5175: ! 5176: The function returns 'KERN_SUCCESS' if the call succeeded. ! 5177: 1.1 root 5178: 5179: File: mach.info, Node: Task Execution, Next: Task Special Ports, Prev: Task Information, Up: Task Interface 5180: 5181: 7.2.4 Task Execution 5182: -------------------- 5183: 5184: -- Function: kern_return_t task_suspend (task_t TARGET_TASK) 5185: The function 'task_suspend' increments the task's suspend count and 5186: stops all threads in the task. As long as the suspend count is 5187: positive newly created threads will not run. This call does not 5188: return until all threads are suspended. 5189: 5190: The count may become greater than one, with the effect that it will 5191: take more than one resume call to restart the task. 5192: 5193: The function returns 'KERN_SUCCESS' if the task has been suspended 5194: and 'KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task. 5195: 5196: -- Function: kern_return_t task_resume (task_t TARGET_TASK) 5197: The function 'task_resume' decrements the task's suspend count. If 5198: it becomes zero, all threads with zero suspend counts in the task 5199: are resumed. The count may not become negative. 5200: 5201: The function returns 'KERN_SUCCESS' if the task has been resumed, 5202: 'KERN_FAILURE' if the suspend count is already at zero and 5203: 'KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task. 5204: 5205: -- Function: kern_return_t task_priority (task_t TASK, int PRIORITY, 5206: boolean_t CHANGE_THREADS) 5207: The priority of a task is used only for creation of new threads; a 5208: new thread's priority is set to the enclosing task's priority. 5209: 'task_priority' changes this task priority. It also sets the 5210: priorities of all threads in the task to this new priority if 5211: CHANGE_THREADS is 'TRUE'. Existing threads are not affected 5212: otherwise. If this priority change violates the maximum priority 5213: of some threads, as many threads as possible will be changed and an 5214: error code will be returned. 5215: 5216: The function returns 'KERN_SUCCESS' if the call succeeded, 5217: 'KERN_INVALID_ARGUMENT' if TASK is not a task, or PRIORITY is not a 5218: valid priority and 'KERN_FAILURE' if CHANGE_THREADS was 'TRUE' and 5219: the attempt to change the priority of at least one existing thread 5220: failed because the new priority would have exceeded that thread's 5221: maximum priority. 5222: 5223: -- Function: kern_return_t task_ras_control (task_t TARGET_TASK, 5224: vm_address_t START_PC, vm_address_t END_PC, int FLAVOR) 5225: The function 'task_ras_control' manipulates a task's set of 5226: restartable atomic sequences. If a sequence is installed, and any 5227: thread in the task is preempted within the range [START_PC,END_PC], 5228: then the thread is resumed at START_PC. This enables applications 5229: to build atomic sequences which, when executed to completion, will 5230: have executed atomically. Restartable atomic sequences are 5231: intended to be used on systems that do not have hardware support 5232: for low-overhead atomic primitives. 5233: 5234: As a thread can be rolled-back, the code in the sequence should 5235: have no side effects other than a final store at END_PC. The 5236: kernel does not guarantee that the sequence is restartable. It 5237: assumes the application knows what it's doing. 5238: 5239: A task may have a finite number of atomic sequences that is defined 5240: at compile time. 5241: 5242: The flavor specifies the particular operation that should be 5243: applied to this restartable atomic sequence. Possible values for 5244: flavor can be: 5245: 5246: 'TASK_RAS_CONTROL_PURGE_ALL' 5247: Remove all registered sequences for this task. 5248: 5249: 'TASK_RAS_CONTROL_PURGE_ONE' 5250: Remove the named registered sequence for this task. 5251: 5252: 'TASK_RAS_CONTROL_PURGE_ALL_AND_INSTALL_ONE' 5253: Atomically remove all registered sequences and install the 5254: named sequence. 5255: 5256: 'TASK_RAS_CONTROL_INSTALL_ONE' 5257: Install this sequence. 5258: 5259: The function returns 'KERN_SUCCESS' if the operation has been 5260: performed, 'KERN_INVALID_ADDRESS' if the START_PC or END_PC values 5261: are not a valid address for the requested operation (for example, 5262: it is invalid to purge a sequence that has not been registered), 5263: 'KERN_RESOURCE_SHORTAGE' if an attempt was made to install more 5264: restartable atomic sequences for a task than can be supported by 5265: the kernel, 'KERN_INVALID_VALUE' if a bad flavor was specified, 5266: 'KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task and 5267: 'KERN_FAILURE' if the call is not not supported on this 5268: configuration. 5269: 5270: 5271: File: mach.info, Node: Task Special Ports, Next: Syscall Emulation, Prev: Task Execution, Up: Task Interface 5272: 5273: 7.2.5 Task Special Ports 5274: ------------------------ 5275: 5276: -- Function: kern_return_t task_get_special_port (task_t TASK, 5277: int WHICH_PORT, mach_port_t *SPECIAL_PORT) 5278: The function 'task_get_special_port' returns send rights to one of 5279: a set of special ports for the task specified by TASK. 5280: 5281: The special ports associated with a task are the kernel port 5282: ('TASK_KERNEL_PORT'), the bootstrap port ('TASK_BOOTSTRAP_PORT') 5283: and the exception port ('TASK_EXCEPTION_PORT'). The bootstrap port 5284: is a port to which a task may send a message requesting other 5285: system service ports. This port is not used by the kernel. The 5286: task's exception port is the port to which messages are sent by the 5287: kernel when an exception occurs and the thread causing the 5288: exception has no exception port of its own. 5289: 5290: The following macros to call 'task_get_special_port' for a specific 5291: port are defined in 'mach/task_special_ports.h': 5292: 'task_get_exception_port' and 'task_get_bootstrap_port'. 5293: 5294: The function returns 'KERN_SUCCESS' if the port was returned and 5295: 'KERN_INVALID_ARGUMENT' if TASK is not a task or WHICH_PORT is an 5296: invalid port selector. 5297: 5298: -- Function: kern_return_t task_get_kernel_port (task_t TASK, 5299: mach_port_t *KERNEL_PORT) 5300: The function 'task_get_kernel_port' is equivalent to the function 5301: 'task_get_special_port' with the WHICH_PORT argument set to 5302: 'TASK_KERNEL_PORT'. 5303: 5304: -- Function: kern_return_t task_get_exception_port (task_t TASK, 5305: mach_port_t *EXCEPTION_PORT) 5306: The function 'task_get_exception_port' is equivalent to the 5307: function 'task_get_special_port' with the WHICH_PORT argument set 5308: to 'TASK_EXCEPTION_PORT'. 5309: 5310: -- Function: kern_return_t task_get_bootstrap_port (task_t TASK, 5311: mach_port_t *BOOTSTRAP_PORT) 5312: The function 'task_get_bootstrap_port' is equivalent to the 5313: function 'task_get_special_port' with the WHICH_PORT argument set 5314: to 'TASK_BOOTSTRAP_PORT'. 5315: 5316: -- Function: kern_return_t task_set_special_port (task_t TASK, 5317: int WHICH_PORT, mach_port_t SPECIAL_PORT) 5318: The function 'thread_set_special_port' sets one of a set of special 5319: ports for the task specified by TASK. 5320: 5321: The special ports associated with a task are the kernel port 5322: ('TASK_KERNEL_PORT'), the bootstrap port ('TASK_BOOTSTRAP_PORT') 5323: and the exception port ('TASK_EXCEPTION_PORT'). The bootstrap port 5324: is a port to which a thread may send a message requesting other 5325: system service ports. This port is not used by the kernel. The 5326: task's exception port is the port to which messages are sent by the 5327: kernel when an exception occurs and the thread causing the 5328: exception has no exception port of its own. 5329: 5330: The function returns 'KERN_SUCCESS' if the port was set and 5331: 'KERN_INVALID_ARGUMENT' if TASK is not a task or WHICH_PORT is an 5332: invalid port selector. 5333: 5334: -- Function: kern_return_t task_set_kernel_port (task_t TASK, 5335: mach_port_t KERNEL_PORT) 5336: The function 'task_set_kernel_port' is equivalent to the function 5337: 'task_set_special_port' with the WHICH_PORT argument set to 5338: 'TASK_KERNEL_PORT'. 5339: 5340: -- Function: kern_return_t task_set_exception_port (task_t TASK, 5341: mach_port_t EXCEPTION_PORT) 5342: The function 'task_set_exception_port' is equivalent to the 5343: function 'task_set_special_port' with the WHICH_PORT argument set 5344: to 'TASK_EXCEPTION_PORT'. 5345: 5346: -- Function: kern_return_t task_set_bootstrap_port (task_t TASK, 5347: mach_port_t BOOTSTRAP_PORT) 5348: The function 'task_set_bootstrap_port' is equivalent to the 5349: function 'task_set_special_port' with the WHICH_PORT argument set 5350: to 'TASK_BOOTSTRAP_PORT'. 5351: 5352: 5353: File: mach.info, Node: Syscall Emulation, Prev: Task Special Ports, Up: Task Interface 5354: 5355: 7.2.6 Syscall Emulation 5356: ----------------------- 5357: 5358: -- Function: kern_return_t task_get_emulation_vector (task_t TASK, 5359: int *VECTOR_START, emulation_vector_t *EMULATION_VECTOR, 5360: mach_msg_type_number_t *EMULATION_VECTOR_COUNT) 5361: The function 'task_get_emulation_vector' gets the user-level 5362: handler entry points for all emulated system calls. 5363: 5364: -- Function: kern_return_t task_set_emulation_vector (task_t TASK, 5365: int VECTOR_START, emulation_vector_t EMULATION_VECTOR, 5366: mach_msg_type_number_t EMULATION_VECTOR_COUNT) 5367: The function 'task_set_emulation_vector' establishes user-level 5368: handlers for the specified system calls. Non-emulated system calls 5369: are specified with an entry of 'EML_ROUTINE_NULL'. System call 5370: emulation handlers are inherited by the children of TASK. 5371: 5372: -- Function: kern_return_t task_set_emulation (task_t TASK, 5373: vm_address_t ROUTINE_ENTRY_PT, int ROUTINE_NUMBER) 5374: The function 'task_set_emulation' establishes a user-level handler 5375: for the specified system call. System call emulation handlers are 5376: inherited by the children of TASK. 5377: 5378: 5379: File: mach.info, Node: Profiling, Prev: Task Interface, Up: Threads and Tasks 5380: 5381: 7.3 Profiling 5382: ============= 5383: 5384: -- Function: kern_return_t task_enable_pc_sampling (task_t TASK, 5385: int *TICKS, sampled_pc_flavor_t FLAVOR) 5386: -- Function: kern_return_t thread_enable_pc_sampling (thread_t THREAD, 5387: int *TICKS, sampled_pc_flavor_t FLAVOR) 5388: The function 'task_enable_pc_sampling' enables PC sampling for 5389: TASK, the function 'thread_enable_pc_sampling' enables PC sampling 5390: for THREAD. The kernel's idea of clock granularity is returned in 5391: TICKS in usecs. (this value should not be trusted). The sampling 5392: flavor is specified by FLAVOR. 5393: 5394: The function returns 'KERN_SUCCESS' if the operation is completed 5395: successfully and 'KERN_INVALID_ARGUMENT' if THREAD is not a valid 5396: thread. 5397: 5398: -- Function: kern_return_t task_disable_pc_sampling (task_t TASK, 5399: int *SAMPLE_COUNT) 5400: -- Function: kern_return_t thread_disable_pc_sampling (thread_t THREAD, 5401: int *SAMPLE_COUNT) 5402: The function 'task_disable_pc_sampling' disables PC sampling for 5403: TASK, the function 'thread_disable_pc_sampling' disables PC 5404: sampling for THREAD. The number of sample elements in the kernel 5405: for the thread is returned in SAMPLE_COUNT. 5406: 5407: The function returns 'KERN_SUCCESS' if the operation is completed 5408: successfully and 'KERN_INVALID_ARGUMENT' if THREAD is not a valid 5409: thread. 5410: 5411: -- Function: kern_return_t task_get_sampled_pcs (task_t TASK, 5412: sampled_pc_seqno_t *SEQNO, sampled_pc_array_t SAMPLED_PCS, 5413: mach_msg_type_number_t *SAMPLE_COUNT) 5414: -- Function: kern_return_t thread_get_sampled_pcs (thread_t THREAD, 5415: sampled_pc_seqno_t *SEQNO, sampled_pc_array_t SAMPLED_PCS, 5416: int *SAMPLE_COUNT) 5417: The function 'task_get_sampled_pcs' extracts the PC samples for 5418: TASK, the function 'thread_get_sampled_pcs' extracts the PC samples 5419: for THREAD. SEQNO is the sequence number of the sampled PCs. This 5420: is useful for determining when a collector thread has missed a 5421: sample. The sampled PCs for the thread are returned in 5422: SAMPLED_PCS. SAMPLE_COUNT contains the number of sample elements 5423: returned. 5424: 5425: The function returns 'KERN_SUCCESS' if the operation is completed 5426: successfully, 'KERN_INVALID_ARGUMENT' if THREAD is not a valid 5427: thread and 'KERN_FAILURE' if THREAD is not sampled. 5428: 5429: -- Data type: sampled_pc_t 5430: This structure is returned in SAMPLED_PCS by the 5431: 'thread_get_sampled_pcs' and 'task_get_sampled_pcs' functions and 5432: provides pc samples for threads or tasks. It has the following 5433: members: 5434: 5435: 'natural_t id' 5436: A thread-specific unique identifier. 5437: 5438: 'vm_offset_t pc' 5439: A pc value. 5440: 5441: 'sampled_pc_flavor_t sampletype' 5442: The type of the sample as per flavor. 5443: 5444: -- Data type: sampled_pc_flavor_t 5445: This data type specifies a pc sample flavor, either as argument 5446: passed in FLAVOR to the 'thread_enable_pc_sample' and 5447: 'thread_disable_pc_sample' functions, or as member 'sampletype' in 5448: the 'sample_pc_t' data type. The flavor is a bitwise-or of the 5449: possible flavors defined in 'mach/pc_sample.h': 5450: 5451: 'SAMPLED_PC_PERIODIC' 5452: default 5453: 'SAMPLED_PC_VM_ZFILL_FAULTS' 5454: zero filled fault 5455: 'SAMPLED_PC_VM_REACTIVATION_FAULTS' 5456: reactivation fault 5457: 'SAMPLED_PC_VM_PAGEIN_FAULTS' 5458: pagein fault 5459: 'SAMPLED_PC_VM_COW_FAULTS' 5460: copy-on-write fault 5461: 'SAMPLED_PC_VM_FAULTS_ANY' 5462: any fault 5463: 'SAMPLED_PC_VM_FAULTS' 5464: the bitwise-or of 'SAMPLED_PC_VM_ZFILL_FAULTS', 5465: 'SAMPLED_PC_VM_REACTIVATION_FAULTS', 5466: 'SAMPLED_PC_VM_PAGEIN_FAULTS' and 'SAMPLED_PC_VM_COW_FAULTS'. 5467: 5468: 5469: File: mach.info, Node: Host Interface, Next: Processors and Processor Sets, Prev: Threads and Tasks, Up: Top 5470: 5471: 8 Host Interface 5472: **************** 5473: 5474: This section describes the Mach interface to a host executing a Mach 5475: kernel. The interface allows to query statistics about a host and 5476: control its behaviour. 5477: 5478: A host is represented by two ports, a name port HOST used to query 5479: information about the host accessible to everyone, and a control port 5480: HOST_PRIV used to manipulate it. For example, you can query the current 5481: time using the name port, but to change the time you need to send a 5482: message to the host control port. 5483: 5484: Everything described in this section is declared in the header file 5485: 'mach.h'. 5486: 5487: * Menu: 5488: 5489: * Host Ports:: Ports representing a host. 5490: * Host Information:: Retrieval of information about a host. 5491: * Host Time:: Operations on the time as seen by a host. 5492: * Host Reboot:: Rebooting the system. 5493: 5494: 5495: File: mach.info, Node: Host Ports, Next: Host Information, Up: Host Interface 5496: 5497: 8.1 Host Ports 5498: ============== 5499: 5500: -- Data type: host_t 5501: This is a 'mach_port_t' and used to hold the port name of a host 5502: name port (or short: host port). Any task can get a send right to 5503: the name port of the host running the task using the 5504: 'mach_host_self' system call. The name port can be used query 5505: information about the host, for example the current time. 5506: 5507: -- Function: host_t mach_host_self () 5508: The 'mach_host_self' system call returns the calling thread's host 5509: name port. It has an effect equivalent to receiving a send right 5510: for the host port. 'mach_host_self' returns the name of the send 5511: right. In particular, successive calls will increase the calling 5512: task's user-reference count for the send right. 5513: 5514: As a special exception, the kernel will overrun the user reference 5515: count of the host name port, so that this function can not fail for 5516: that reason. Because of this, the user should not deallocate the 5517: port right if an overrun might have happened. Otherwise the 5518: reference count could drop to zero and the send right be destroyed 5519: while the user still expects to be able to use it. As the kernel 5520: does not make use of the number of extant send rights anyway, this 5521: is safe to do (the host port itself is never destroyed). 5522: 5523: The function returns 'MACH_PORT_NULL' if a resource shortage 5524: prevented the reception of the send right. 5525: 5526: This function is also available in 'mach/mach_traps.h'. 5527: 5528: -- Data type: host_priv_t 5529: This is a 'mach_port_t' and used to hold the port name of a 5530: privileged host control port. A send right to the host control 5531: port is inserted into the first task at bootstrap (*note 5532: Modules::). This is the only way to get access to the host control 5533: port in Mach, so the initial task has to preserve the send right 5534: carefully, moving a copy of it to other privileged tasks if 5535: necessary and denying access to unprivileged tasks. 5536: 5537: 5538: File: mach.info, Node: Host Information, Next: Host Time, Prev: Host Ports, Up: Host Interface 5539: 5540: 8.2 Host Information 5541: ==================== 5542: 5543: -- Function: kern_return_t host_info (host_t HOST, int FLAVOR, 5544: host_info_t HOST_INFO, 5545: mach_msg_type_number_t *HOST_INFO_COUNT) 5546: The 'host_info' function returns various information about HOST. 5547: HOST_INFO is an array of integers that is supplied by the caller. 5548: It will be filled with the requested information. HOST_INFO_COUNT 5549: is supplied as the maximum number of integers in HOST_INFO. On 5550: return, it contains the actual number of integers in HOST_INFO. 5551: The maximum number of integers returned by any flavor is 5552: 'HOST_INFO_MAX'. 5553: 5554: The type of information returned is defined by FLAVOR, which can be 5555: one of the following: 5556: 5557: 'HOST_BASIC_INFO' 5558: The function returns basic information about the host, as 5559: defined by 'host_basic_info_t'. This includes the number of 5560: processors, their type, and the amount of memory installed in 5561: the system. The number of integers returned is 5562: 'HOST_BASIC_INFO_COUNT'. For how to get more information 5563: about the processor, see *note Processor Interface::. 5564: 5565: 'HOST_PROCESSOR_SLOTS' 5566: The function returns the numbers of the slots with active 5567: processors in them. The number of integers returned can be up 5568: to 'max_cpus', as returned by the 'HOST_BASIC_INFO' flavor of 5569: 'host_info'. 5570: 5571: 'HOST_SCHED_INFO' 5572: The function returns information of interest to schedulers as 5573: defined by 'host_sched_info_t'. The number of integers 5574: returned is 'HOST_SCHED_INFO_COUNT'. 5575: 5576: The function returns 'KERN_SUCCESS' if the call succeeded and 5577: 'KERN_INVALID_ARGUMENT' if HOST is not a host or FLAVOR is not 5578: recognized. The function returns 'MIG_ARRAY_TOO_LARGE' if the 5579: returned info array is too large for HOST_INFO. In this case, 5580: HOST_INFO is filled as much as possible and HOST_INFO_COUNT is set 5581: to the number of elements that would be returned if there were 5582: enough room. 5583: 5584: -- Data type: struct host_basic_info 5585: A pointer to this structure is returned in HOST_INFO by the 5586: 'host_info' function and provides basic information about the host. 5587: You can cast a variable of type 'host_info_t' to a pointer of this 5588: type if you provided it as the HOST_INFO parameter for the 5589: 'HOST_BASIC_INFO' flavor of 'host_info'. It has the following 5590: members: 5591: 5592: 'int max_cpus' 5593: The maximum number of possible processors for which the kernel 5594: is configured. 5595: 5596: 'int avail_cpus' 5597: The number of cpus currently available. 5598: 5599: 'vm_size_t memory_size' 5600: The size of physical memory in bytes. 5601: 5602: 'cpu_type_t cpu_type' 5603: The type of the master processor. 5604: 5605: 'cpu_subtype_t cpu_subtype' 5606: The subtype of the master processor. 5607: 5608: The type and subtype of the individual processors are also 5609: available by 'processor_info', see *note Processor Interface::. 5610: 5611: -- Data type: host_basic_info_t 5612: This is a pointer to a 'struct host_basic_info'. 5613: 5614: -- Data type: struct host_sched_info 5615: A pointer to this structure is returned in HOST_INFO by the 5616: 'host_info' function and provides information of interest to 5617: schedulers. You can cast a variable of type 'host_info_t' to a 5618: pointer of this type if you provided it as the HOST_INFO parameter 5619: for the 'HOST_SCHED_INFO' flavor of 'host_info'. It has the 5620: following members: 5621: 5622: 'int min_timeout' 5623: The minimum timeout and unit of time in milliseconds. 5624: 5625: 'int min_quantum' 5626: The minimum quantum and unit of quantum in milliseconds. 5627: 5628: -- Data type: host_sched_info_t 5629: This is a pointer to a 'struct host_sched_info'. 5630: 5631: -- Function: kern_return_t host_kernel_version (host_t HOST, 5632: kernel_version_t *VERSION) 5633: The 'host_kernel_version' function returns the version string 5634: compiled into the kernel executing on HOST at the time it was built 5635: in the character string VERSION. This string describes the version 5636: of the kernel. The constant 'KERNEL_VERSION_MAX' should be used to 5637: dimension storage for the returned string if the 'kernel_version_t' 5638: declaration is not used. 5639: 5640: If the version string compiled into the kernel is longer than 5641: 'KERNEL_VERSION_MAX', the result is truncated and not necessarily 5642: null-terminated. 5643: 5644: If HOST is not a valid send right to a host port, the function 5645: returns 'KERN_INVALID_ARGUMENT'. If VERSION points to inaccessible 5646: memory, it returns 'KERN_INVALID_ADDRESS', and 'KERN_SUCCESS' 5647: otherwise. 5648: 5649: -- Function: kern_return_t host_get_boot_info (host_priv_t HOST_PRIV, 5650: kernel_boot_info_t BOOT_INFO) 5651: The 'host_get_boot_info' function returns the boot-time information 5652: string supplied by the operator to the kernel executing on 5653: HOST_PRIV in the character string BOOT_INFO. The constant 5654: 'KERNEL_BOOT_INFO_MAX' should be used to dimension storage for the 5655: returned string if the 'kernel_boot_info_t' declaration is not 5656: used. 5657: 5658: If the boot-time information string supplied by the operator is 5659: longer than 'KERNEL_BOOT_INFO_MAX', the result is truncated and not 5660: necessarily null-terminated. 5661: 5662: 5663: File: mach.info, Node: Host Time, Next: Host Reboot, Prev: Host Information, Up: Host Interface 5664: 5665: 8.3 Host Time 5666: ============= 5667: 5668: -- Data type: time_value_t 5669: This is the representation of a time in Mach. It is a 'struct 5670: time_value' and consists of the following members: 5671: 5672: 'integer_t seconds' 5673: The number of seconds. 5674: 'integer_t microseconds' 5675: The number of microseconds. 5676: 5677: The number of microseconds should always be smaller than 5678: 'TIME_MICROS_MAX' (100000). A time with this property is "normalized". 5679: Normalized time values can be manipulated with the following macros: 5680: 5681: -- Macro: time_value_add_usec (time_value_t *VAL, integer_t *MICROS) 5682: Add MICROS microseconds to VAL. If VAL is normalized and MICROS 5683: smaller than 'TIME_MICROS_MAX', VAL will be normalized afterwards. 5684: 5685: -- Macro: time_value_add (time_value_t *RESULT, time_value_t *ADDEND) 5686: Add the values in ADDEND to RESULT. If both are normalized, RESULT 5687: will be normalized afterwards. 5688: 5689: A variable of type 'time_value_t' can either represent a duration or 5690: a fixed point in time. In the latter case, it shall be interpreted as 5691: the number of seconds and microseconds after the epoch 1. Jan 1970. 5692: 5693: -- Function: kern_return_t host_get_time (host_t HOST, 5694: time_value_t *CURRENT_TIME) 5695: Get the current time as seen by HOST. On success, the time passed 5696: since the epoch is returned in CURRENT_TIME. 5697: 5698: -- Function: kern_return_t host_set_time (host_priv_t HOST_PRIV, 5699: time_value_t NEW_TIME) 5700: Set the time of HOST_PRIV to NEW_TIME. 5701: 5702: -- Function: kern_return_t host_adjust_time (host_priv_t HOST_PRIV, 5703: time_value_t NEW_ADJUSTMENT, time_value_t *OLD_ADJUSTMENT) 5704: Arrange for the current time as seen by HOST_PRIV to be gradually 5705: changed by the adjustment value NEW_ADJUSTMENT, and return the old 5706: adjustment value in OLD_ADJUSTMENT. 5707: 5708: For efficiency, the current time is available through a mapped-time 5709: interface. 5710: 5711: -- Data type: mapped_time_value_t 5712: This structure defines the mapped-time interface. It has the 5713: following members: 5714: 5715: 'integer_t seconds' 5716: The number of seconds. 5717: 5718: 'integer_t microseconds' 5719: The number of microseconds. 5720: 5721: 'integer_t check_seconds' 5722: This is a copy of the seconds value, which must be checked to 5723: protect against a race condition when reading out the two time 5724: values. 5725: 5726: Here is an example how to read out the current time using the 5727: mapped-time interface: 5728: 5729: do 5730: { 5731: secs = mtime->seconds; 5732: usecs = mtime->microseconds; 5733: } 5734: while (secs != mtime->check_seconds); 5735: 5736: 5737: File: mach.info, Node: Host Reboot, Prev: Host Time, Up: Host Interface 5738: 5739: 8.4 Host Reboot 5740: =============== 5741: 5742: -- Function: kern_return_t host_reboot (host_priv_t HOST_PRIV, 5743: int OPTIONS) 5744: Reboot the host specified by HOST_PRIV. The argument OPTIONS 5745: specifies the flags. The available flags are defined in 5746: 'sys/reboot.h': 5747: 5748: 'RB_HALT' 5749: Do not reboot, but halt the machine. 5750: 5751: 'RB_DEBUGGER' 5752: Do not reboot, but enter kernel debugger from user space. 5753: 5754: If successful, the function might not return. 5755: 5756: 5757: File: mach.info, Node: Processors and Processor Sets, Next: Device Interface, Prev: Host Interface, Up: Top 5758: 5759: 9 Processors and Processor Sets 5760: ******************************* 5761: 5762: This section describes the Mach interface to processor sets and 5763: individual processors. The interface allows to group processors into 5764: sets and control the processors and processor sets. 5765: 5766: A processor is not a central part of the interface. It is mostly of 5767: relevance as a part of a processor set. Threads are always assigned to 5768: processor sets, and all processors in a set are equally involved in 5769: executing all threads assigned to that set. 5770: 5771: The processor set is represented by two ports, a name port 5772: PROCESSOR_SET_NAME used to query information about the host accessible 5773: to everyone, and a control port PROCESSOR_SET used to manipulate it. 5774: 5775: * Menu: 5776: 5777: * Processor Set Interface:: How to work with processor sets. 5778: * Processor Interface:: How to work with individual processors. 5779: 5780: 5781: File: mach.info, Node: Processor Set Interface, Next: Processor Interface, Up: Processors and Processor Sets 5782: 5783: 9.1 Processor Set Interface 5784: =========================== 5785: 5786: * Menu: 5787: 5788: * Processor Set Ports:: Ports representing a processor set. 5789: * Processor Set Access:: How the processor sets are accessed. 5790: * Processor Set Creation:: How new processor sets are created. 5791: * Processor Set Destruction:: How processor sets are destroyed. 5792: * Tasks and Threads on Sets:: Assigning tasks, threads to processor sets. 5793: * Processor Set Priority:: Specifying the priority of a processor set. 5794: * Processor Set Policy:: Changing the processor set policies. 5795: * Processor Set Info:: Obtaining information about a processor set. 5796: 5797: 5798: File: mach.info, Node: Processor Set Ports, Next: Processor Set Access, Up: Processor Set Interface 5799: 5800: 9.1.1 Processor Set Ports 5801: ------------------------- 5802: 5803: -- Data type: processor_set_name_t 5804: This is a 'mach_port_t' and used to hold the port name of a 5805: processor set name port that names the processor set. Any task can 5806: get a send right to name port of a processor set. The processor 5807: set name port allows to get information about the processor set. 5808: 5809: -- Data type: processor_set_t 5810: This is a 'mach_port_t' and used to hold the port name of a 5811: privileged processor set control port that represents the processor 5812: set. Operations on the processor set are implemented as remote 5813: procedure calls to the processor set port. The processor set port 5814: allows to manipulate the processor set. 5815: 5816: 5817: File: mach.info, Node: Processor Set Access, Next: Processor Set Creation, Prev: Processor Set Ports, Up: Processor Set Interface 5818: 5819: 9.1.2 Processor Set Access 5820: -------------------------- 5821: 5822: -- Function: kern_return_t host_processor_sets (host_t HOST, 5823: processor_set_name_array_t *PROCESSOR_SETS, 5824: mach_msg_type_number_t *PROCESSOR_SETS_COUNT) 5825: The function 'host_processor_sets' gets send rights to the name 5826: port for each processor set currently assigned to HOST. 5827: 5828: 'host_processor_set_priv' can be used to obtain the control ports 5829: from these if desired. PROCESSOR_SETS is an array that is created 5830: as a result of this call. The caller may wish to 'vm_deallocate' 5831: this array when the data is no longer needed. PROCESSOR_SETS_COUNT 5832: is set to the number of processor sets in the PROCESSOR_SETS. 5833: 5834: This function returns 'KERN_SUCCESS' if the call succeeded and 5835: 'KERN_INVALID_ARGUMENT' if HOST is not a host. 5836: 5837: -- Function: kern_return_t host_processor_set_priv 5838: (host_priv_t HOST_PRIV, processor_set_name_t SET_NAME, 5839: processor_set_t *SET) 5840: The function 'host_processor_set_priv' allows a privileged 5841: application to obtain the control port SET for an existing 5842: processor set from its name port SET_NAME. The privileged host 5843: port HOST_PRIV is required. 5844: 5845: This function returns 'KERN_SUCCESS' if the call succeeded and 5846: 'KERN_INVALID_ARGUMENT' if HOST_PRIV is not a valid host control 5847: port. 5848: 5849: -- Function: kern_return_t processor_set_default (host_t HOST, 5850: processor_set_name_t *DEFAULT_SET) 5851: The function 'processor_set_default' returns the default processor 5852: set of HOST in DEFAULT_SET. The default processor set is used by 5853: all threads, tasks, and processors that are not explicitly assigned 5854: to other sets. processor_set_default returns a port that can be 5855: used to obtain information about this set (e.g. how many threads 5856: are assigned to it). This port cannot be used to perform 5857: operations on that set. 5858: 5859: This function returns 'KERN_SUCCESS' if the call succeeded, 5860: 'KERN_INVALID_ARGUMENT' if HOST is not a host and 5861: 'KERN_INVALID_ADDRESS' if DEFAULT_SET points to inaccessible 5862: memory. 5863: 5864: 5865: File: mach.info, Node: Processor Set Creation, Next: Processor Set Destruction, Prev: Processor Set Access, Up: Processor Set Interface 5866: 5867: 9.1.3 Processor Set Creation 5868: ---------------------------- 5869: 5870: -- Function: kern_return_t processor_set_create (host_t HOST, 5871: processor_set_t *NEW_SET, processor_set_name_t *NEW_NAME) 5872: The function 'processor_set_create' creates a new processor set on 5873: HOST and returns the two ports associated with it. The port 5874: returned in NEW_SET is the actual port representing the set. It is 5875: used to perform operations such as assigning processors, tasks, or 5876: threads. The port returned in NEW_NAME identifies the set, and is 5877: used to obtain information about the set. 5878: 5879: This function returns 'KERN_SUCCESS' if the call succeeded, 5880: 'KERN_INVALID_ARGUMENT' if HOST is not a host, 5881: 'KERN_INVALID_ADDRESS' if NEW_SET or NEW_NAME points to 5882: inaccessible memory and 'KERN_FAILURE' is the operating system does 5883: not support processor allocation. 5884: 5885: 5886: File: mach.info, Node: Processor Set Destruction, Next: Tasks and Threads on Sets, Prev: Processor Set Creation, Up: Processor Set Interface 5887: 5888: 9.1.4 Processor Set Destruction 5889: ------------------------------- 5890: 5891: -- Function: kern_return_t processor_set_destroy 5892: (processor_set_t PROCESSOR_SET) 5893: The function 'processor_set_destroy' destroys the specified 5894: processor set. Any assigned processors, tasks, or threads are 5895: reassigned to the default set. The object port for the processor 5896: set is required (not the name port). The default processor set 5897: cannot be destroyed. 5898: 5899: This function returns 'KERN_SUCCESS' if the set was destroyed, 5900: 'KERN_FAILURE' if an attempt was made to destroy the default 5901: processor set, or the operating system does not support processor 5902: allocation, and 'KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a 5903: valid processor set control port. 5904: 5905: 5906: File: mach.info, Node: Tasks and Threads on Sets, Next: Processor Set Priority, Prev: Processor Set Destruction, Up: Processor Set Interface 5907: 5908: 9.1.5 Tasks and Threads on Sets 5909: ------------------------------- 5910: 5911: -- Function: kern_return_t processor_set_tasks 5912: (processor_set_t PROCESSOR_SET, task_array_t *TASK_LIST, 5913: mach_msg_type_number_t *TASK_COUNT) 5914: The function 'processor_set_tasks' gets send rights to the kernel 5915: port for each task currently assigned to PROCESSOR_SET. 5916: 5917: TASK_LIST is an array that is created as a result of this call. 5918: The caller may wish to 'vm_deallocate' this array when the data is 5919: no longer needed. TASK_COUNT is set to the number of tasks in the 5920: TASK_LIST. 5921: 5922: This function returns 'KERN_SUCCESS' if the call succeeded and 5923: 'KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set. 5924: 5925: -- Function: kern_return_t processor_set_threads 5926: (processor_set_t PROCESSOR_SET, thread_array_t *THREAD_LIST, 5927: mach_msg_type_number_t *THREAD_COUNT) 5928: The function 'processor_set_thread' gets send rights to the kernel 5929: port for each thread currently assigned to PROCESSOR_SET. 5930: 5931: THREAD_LIST is an array that is created as a result of this call. 5932: The caller may wish to 'vm_deallocate' this array when the data is 5933: no longer needed. THREAD_COUNT is set to the number of threads in 5934: the THREAD_LIST. 5935: 5936: This function returns 'KERN_SUCCESS' if the call succeeded and 5937: 'KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set. 5938: 5939: -- Function: kern_return_t task_assign (task_t TASK, 5940: processor_set_t PROCESSOR_SET, boolean_t ASSIGN_THREADS) 5941: The function 'task_assign' assigns TASK the set PROCESSOR_SET. 5942: This assignment is for the purposes of determining the initial 5943: assignment of newly created threads in task. Any previous 5944: assignment of the task is nullified. Existing threads within the 5945: task are also reassigned if ASSIGN_THREADS is 'TRUE'. They are not 5946: affected if it is 'FALSE'. 5947: 5948: This function returns 'KERN_SUCCESS' if the assignment has been 5949: performed and 'KERN_INVALID_ARGUMENT' if TASK is not a task, or 5950: PROCESSOR_SET is not a processor set on the same host as TASK. 5951: 5952: -- Function: kern_return_t task_assign_default (task_t TASK, 5953: boolean_t ASSIGN_THREADS) 5954: The function 'task_assign_default' is a variant of 'task_assign' 5955: that assigns the task to the default processor set on that task's 5956: host. This variant exists because the control port for the default 5957: processor set is privileged and not usually available to users. 5958: 5959: This function returns 'KERN_SUCCESS' if the assignment has been 5960: performed and 'KERN_INVALID_ARGUMENT' if TASK is not a task. 5961: 5962: -- Function: kern_return_t task_get_assignment (task_t TASK, 5963: processor_set_name_t *ASSIGNED_SET) 5964: The function 'task_get_assignment' returns the name of the 5965: processor set to which the thread is currently assigned in 5966: ASSIGNED_SET. This port can only be used to obtain information 5967: about the processor set. 5968: 5969: This function returns 'KERN_SUCCESS' if the assignment has been 5970: performed, 'KERN_INVALID_ADDRESS' if PROCESSOR_SET points to 5971: inaccessible memory, and 'KERN_INVALID_ARGUMENT' if TASK is not a 5972: task. 5973: 5974: -- Function: kern_return_t thread_assign (thread_t THREAD, 5975: processor_set_t PROCESSOR_SET) 5976: The function 'thread_assign' assigns THREAD the set PROCESSOR_SET. 5977: After the assignment is completed, the thread only executes on 5978: processors assigned to the designated processor set. If there are 5979: no such processors, then the thread is unable to execute. Any 5980: previous assignment of the thread is nullified. Unix system call 5981: compatibility code may temporarily force threads to execute on the 5982: master processor. 5983: 5984: This function returns 'KERN_SUCCESS' if the assignment has been 5985: performed and 'KERN_INVALID_ARGUMENT' if THREAD is not a thread, or 5986: PROCESSOR_SET is not a processor set on the same host as THREAD. 5987: 5988: -- Function: kern_return_t thread_assign_default (thread_t THREAD) 5989: The function 'thread_assign_default' is a variant of 5990: 'thread_assign' that assigns the thread to the default processor 5991: set on that thread's host. This variant exists because the control 5992: port for the default processor set is privileged and not usually 5993: available to users. 5994: 5995: This function returns 'KERN_SUCCESS' if the assignment has been 5996: performed and 'KERN_INVALID_ARGUMENT' if THREAD is not a thread. 5997: 5998: -- Function: kern_return_t thread_get_assignment (thread_t THREAD, 5999: processor_set_name_t *ASSIGNED_SET) 6000: The function 'thread_get_assignment' returns the name of the 6001: processor set to which the thread is currently assigned in 6002: ASSIGNED_SET. This port can only be used to obtain information 6003: about the processor set. 6004: 6005: This function returns 'KERN_SUCCESS' if the assignment has been 6006: performed, 'KERN_INVALID_ADDRESS' if PROCESSOR_SET points to 6007: inaccessible memory, and 'KERN_INVALID_ARGUMENT' if THREAD is not a 6008: thread. 6009: 6010: 6011: File: mach.info, Node: Processor Set Priority, Next: Processor Set Policy, Prev: Tasks and Threads on Sets, Up: Processor Set Interface 6012: 6013: 9.1.6 Processor Set Priority 6014: ---------------------------- 6015: 6016: -- Function: kern_return_t processor_set_max_priority 6017: (processor_set_t PROCESSOR_SET, int MAX_PRIORITY, 6018: boolean_t CHANGE_THREADS) 6019: The function 'processor_set_max_priority' is used to set the 6020: maximum priority for a processor set. The priority of a processor 6021: set is used only for newly created threads (thread's maximum 6022: priority is set to processor set's) and the assignment of threads 6023: to the set (thread's maximum priority is reduced if it exceeds the 6024: set's maximum priority, thread's priority is similarly reduced). 6025: 'processor_set_max_priority' changes this priority. It also sets 6026: the maximum priority of all threads assigned to the processor set 6027: to this new priority if CHANGE_THREADS is 'TRUE'. If this maximum 6028: priority is less than the priorities of any of these threads, their 6029: priorities will also be set to this new value. 6030: 6031: This function returns 'KERN_SUCCESS' if the call succeeded and 6032: 'KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set or 6033: PRIORITY is not a valid priority. 6034: 6035: 6036: File: mach.info, Node: Processor Set Policy, Next: Processor Set Info, Prev: Processor Set Priority, Up: Processor Set Interface 6037: 6038: 9.1.7 Processor Set Policy 6039: -------------------------- 6040: 6041: -- Function: kern_return_t processor_set_policy_enable 6042: (processor_set_t PROCESSOR_SET, int POLICY) 6043: -- Function: kern_return_t processor_set_policy_disable 6044: (processor_set_t PROCESSOR_SET, int POLICY, 6045: boolean_t CHANGE_THREADS) 6046: Processor sets may restrict the scheduling policies to be used for 6047: threads assigned to them. These two calls provide the mechanism 6048: for designating permitted and forbidden policies. The current set 6049: of permitted policies can be obtained from 'processor_set_info'. 6050: Timesharing may not be forbidden by any processor set. This is a 6051: compromise to reduce the complexity of the assign operation; any 6052: thread whose policy is forbidden by the target processor set has 6053: its policy reset to timesharing. If the CHANGE_THREADS argument to 6054: 'processor_set_policy_disable' is true, threads currently assigned 6055: to this processor set and using the newly disabled policy will have 6056: their policy reset to timesharing. 6057: 6058: 'mach/policy.h' contains the allowed policies; it is included by 6059: 'mach.h'. Not all policies (e.g. fixed priority) are supported by 6060: all systems. 6061: 6062: This function returns 'KERN_SUCCESS' if the operation was completed 6063: successfully and 'KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a 6064: processor set or POLICY is not a valid policy, or an attempt was 6065: made to disable timesharing. 6066: 6067: 6068: File: mach.info, Node: Processor Set Info, Prev: Processor Set Policy, Up: Processor Set Interface 6069: 6070: 9.1.8 Processor Set Info 6071: ------------------------ 6072: 6073: -- Function: kern_return_t processor_set_info 6074: (processor_set_name_t SET_NAME, int FLAVOR, host_t *HOST, 6075: processor_set_info_t PROCESSOR_SET_INFO, 6076: mach_msg_type_number_t *PROCESSOR_SET_INFO_COUNT) 6077: The function 'processor_set_info' returns the selected information 6078: array for a processor set, as specified by FLAVOR. 6079: 6080: HOST is set to the host on which the processor set resides. This 6081: is the non-privileged host port. 6082: 6083: PROCESSOR_SET_INFO is an array of integers that is supplied by the 6084: caller and returned filled with specified information. 6085: PROCESSOR_SET_INFO_COUNT is supplied as the maximum number of 6086: integers in PROCESSOR_SET_INFO. On return, it contains the actual 6087: number of integers in PROCESSOR_SET_INFO. The maximum number of 6088: integers returned by any flavor is 'PROCESSOR_SET_INFO_MAX'. 6089: 6090: The type of information returned is defined by FLAVOR, which can be 6091: one of the following: 6092: 6093: 'PROCESSOR_SET_BASIC_INFO' 6094: The function returns basic information about the processor 6095: set, as defined by 'processor_set_basic_info_t'. This 6096: includes the number of tasks and threads assigned to the 6097: processor set. The number of integers returned is 6098: 'PROCESSOR_SET_BASIC_INFO_COUNT'. 6099: 6100: 'PROCESSOR_SET_SCHED_INFO' 6101: The function returns information about the scheduling policy 6102: for the processor set as defined by 6103: 'processor_set_sched_info_t'. The number of integers returned 6104: is 'PROCESSOR_SET_SCHED_INFO_COUNT'. 6105: 6106: Some machines may define additional (machine-dependent) flavors. 6107: 6108: The function returns 'KERN_SUCCESS' if the call succeeded and 6109: 'KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set or 6110: FLAVOR is not recognized. The function returns 6111: 'MIG_ARRAY_TOO_LARGE' if the returned info array is too large for 6112: PROCESSOR_SET_INFO. In this case, PROCESSOR_SET_INFO is filled as 6113: much as possible and PROCESSOR_SET_INFO_COUNT is set to the number 6114: of elements that would have been returned if there were enough 6115: room. 6116: 6117: -- Data type: struct processor_set_basic_info 6118: This structure is returned in PROCESSOR_SET_INFO by the 6119: 'processor_set_info' function and provides basic information about 6120: the processor set. You can cast a variable of type 6121: 'processor_set_info_t' to a pointer of this type if you provided it 6122: as the PROCESSOR_SET_INFO parameter for the 6123: 'PROCESSOR_SET_BASIC_INFO' flavor of 'processor_set_info'. It has 6124: the following members: 6125: 6126: 'int processor_count' 6127: number of processors 6128: 6129: 'int task_count' 6130: number of tasks 6131: 6132: 'int thread_count' 6133: number of threads 6134: 6135: 'int load_average' 6136: scaled load average 6137: 6138: 'int mach_factor' 6139: scaled mach factor 6140: 6141: -- Data type: processor_set_basic_info_t 6142: This is a pointer to a 'struct processor_set_basic_info'. 6143: 6144: -- Data type: struct processor_set_sched_info 6145: This structure is returned in PROCESSOR_SET_INFO by the 6146: 'processor_set_info' function and provides schedule information 6147: about the processor set. You can cast a variable of type 6148: 'processor_set_info_t' to a pointer of this type if you provided it 6149: as the PROCESSOR_SET_INFO parameter for the 6150: 'PROCESSOR_SET_SCHED_INFO' flavor of 'processor_set_info'. It has 6151: the following members: 6152: 6153: 'int policies' 6154: allowed policies 6155: 6156: 'int max_priority' 6157: max priority for new threads 6158: 6159: -- Data type: processor_set_sched_info_t 6160: This is a pointer to a 'struct processor_set_sched_info'. 6161: 6162: 6163: File: mach.info, Node: Processor Interface, Prev: Processor Set Interface, Up: Processors and Processor Sets 6164: 6165: 9.2 Processor Interface 6166: ======================= 6167: 6168: -- Data type: processor_t 6169: This is a 'mach_port_t' and used to hold the port name of a 6170: processor port that represents the processor. Operations on the 6171: processor are implemented as remote procedure calls to the 6172: processor port. 6173: 6174: * Menu: 6175: 6176: * Hosted Processors:: Getting a list of all processors on a host. 6177: * Processor Control:: Starting, stopping, controlling processors. 6178: * Processors and Sets:: Combining processors into processor sets. 6179: * Processor Info:: Obtaining information on processors. 6180: 6181: 6182: File: mach.info, Node: Hosted Processors, Next: Processor Control, Up: Processor Interface 6183: 6184: 9.2.1 Hosted Processors 6185: ----------------------- 6186: 6187: -- Function: kern_return_t host_processors (host_priv_t HOST_PRIV, 6188: processor_array_t *PROCESSOR_LIST, 6189: mach_msg_type_number_t *PROCESSOR_COUNT) 6190: The function 'host_processors' gets send rights to the processor 6191: port for each processor existing on HOST_PRIV. This is the 6192: privileged port that allows its holder to control a processor. 6193: 6194: PROCESSOR_LIST is an array that is created as a result of this 6195: call. The caller may wish to 'vm_deallocate' this array when the 6196: data is no longer needed. PROCESSOR_COUNT is set to the number of 6197: processors in the PROCESSOR_LIST. 6198: 6199: This function returns 'KERN_SUCCESS' if the call succeeded, 6200: 'KERN_INVALID_ARGUMENT' if HOST_PRIV is not a privileged host port, 6201: and 'KERN_INVALID_ADDRESS' if PROCESSOR_COUNT points to 6202: inaccessible memory. 6203: 6204: 6205: File: mach.info, Node: Processor Control, Next: Processors and Sets, Prev: Hosted Processors, Up: Processor Interface 6206: 6207: 9.2.2 Processor Control 6208: ----------------------- 6209: 6210: -- Function: kern_return_t processor_start (processor_t PROCESSOR) 6211: -- Function: kern_return_t processor_exit (processor_t PROCESSOR) 6212: -- Function: kern_return_t processor_control (processor_t PROCESSOR, 6213: processor_info_t *CMD, mach_msg_type_number_t COUNT) 6214: Some multiprocessors may allow privileged software to control 6215: processors. The 'processor_start', 'processor_exit', and 6216: 'processor_control' operations implement this. The interpretation 6217: of the command in CMD is machine dependent. A newly started 6218: processor is assigned to the default processor set. An exited 6219: processor is removed from the processor set to which it was 6220: assigned and ceases to be active. 6221: 6222: COUNT contains the length of the command CMD as a number of ints. 6223: 6224: Availability limited. All of these operations are 6225: machine-dependent. They may do nothing. The ability to restart an 6226: exited processor is also machine-dependent. 6227: 6228: This function returns 'KERN_SUCCESS' if the operation was 6229: performed, 'KERN_FAILURE' if the operation was not performed (a 6230: likely reason is that it is not supported on this processor), 6231: 'KERN_INVALID_ARGUMENT' if PROCESSOR is not a processor, and 6232: 'KERN_INVALID_ADDRESS' if CMD points to inaccessible memory. 6233: 6234: 6235: File: mach.info, Node: Processors and Sets, Next: Processor Info, Prev: Processor Control, Up: Processor Interface 6236: 6237: 9.2.3 Processors and Sets 6238: ------------------------- 6239: 6240: -- Function: kern_return_t processor_assign (processor_t PROCESSOR, 6241: processor_set_t PROCESSOR_SET, boolean_t WAIT) 6242: The function 'processor_assign' assigns PROCESSOR to the set 6243: PROCESSOR_SET. After the assignment is completed, the processor 6244: only executes threads that are assigned to that processor set. Any 6245: previous assignment of the processor is nullified. The master 6246: processor cannot be reassigned. All processors take clock 6247: interrupts at all times. The WAIT argument indicates whether the 6248: caller should wait for the assignment to be completed or should 6249: return immediately. Dedicated kernel threads are used to perform 6250: processor assignment, so setting wait to 'FALSE' allows assignment 6251: requests to be queued and performed faster, especially if the 6252: kernel has more than one dedicated internal thread for processor 6253: assignment. Redirection of other device interrupts away from 6254: processors assigned to other than the default processor set is 6255: machine-dependent. Intermediaries that interpose on ports must be 6256: sure to interpose on both ports involved in this call if they 6257: interpose on either. 6258: 6259: This function returns 'KERN_SUCCESS' if the assignment has been 6260: performed, 'KERN_INVALID_ARGUMENT' if PROCESSOR is not a processor, 6261: or PROCESSOR_SET is not a processor set on the same host as 6262: PROCESSOR. 6263: 6264: -- Function: kern_return_t processor_get_assignment 6265: (processor_t PROCESSOR, processor_set_name_t *ASSIGNED_SET) 6266: The function 'processor_get_assignment' obtains the current 6267: assignment of a processor. The name port of the processor set is 6268: returned in ASSIGNED_SET. 6269: 6270: 6271: File: mach.info, Node: Processor Info, Prev: Processors and Sets, Up: Processor Interface 6272: 6273: 9.2.4 Processor Info 6274: -------------------- 6275: 6276: -- Function: kern_return_t processor_info (processor_t PROCESSOR, 6277: int FLAVOR, host_t *HOST, processor_info_t PROCESSOR_INFO, 6278: mach_msg_type_number_t *PROCESSOR_INFO_COUNT) 6279: The function 'processor_info' returns the selected information 6280: array for a processor, as specified by FLAVOR. 6281: 6282: HOST is set to the host on which the processor set resides. This 6283: is the non-privileged host port. 6284: 6285: PROCESSOR_INFO is an array of integers that is supplied by the 6286: caller and returned filled with specified information. 6287: PROCESSOR_INFO_COUNT is supplied as the maximum number of integers 6288: in PROCESSOR_INFO. On return, it contains the actual number of 6289: integers in PROCESSOR_INFO. The maximum number of integers 6290: returned by any flavor is 'PROCESSOR_INFO_MAX'. 6291: 6292: The type of information returned is defined by FLAVOR, which can be 6293: one of the following: 6294: 6295: 'PROCESSOR_BASIC_INFO' 6296: The function returns basic information about the processor, as 6297: defined by 'processor_basic_info_t'. This includes the slot 6298: number of the processor. The number of integers returned is 6299: 'PROCESSOR_BASIC_INFO_COUNT'. 6300: 6301: Machines which require more configuration information beyond the 6302: slot number are expected to define additional (machine-dependent) 6303: flavors. 6304: 6305: The function returns 'KERN_SUCCESS' if the call succeeded and 6306: 'KERN_INVALID_ARGUMENT' if PROCESSOR is not a processor or FLAVOR 6307: is not recognized. The function returns 'MIG_ARRAY_TOO_LARGE' if 6308: the returned info array is too large for PROCESSOR_INFO. In this 6309: case, PROCESSOR_INFO is filled as much as possible and 6310: PROCESSOR_INFOCNT is set to the number of elements that would have 6311: been returned if there were enough room. 6312: 6313: -- Data type: struct processor_basic_info 6314: This structure is returned in PROCESSOR_INFO by the 6315: 'processor_info' function and provides basic information about the 6316: processor. You can cast a variable of type 'processor_info_t' to a 6317: pointer of this type if you provided it as the PROCESSOR_INFO 6318: parameter for the 'PROCESSOR_BASIC_INFO' flavor of 6319: 'processor_info'. It has the following members: 6320: 6321: 'cpu_type_t cpu_type' 6322: cpu type 6323: 6324: 'cpu_subtype_t cpu_subtype' 6325: cpu subtype 6326: 6327: 'boolean_t running' 6328: is processor running? 6329: 6330: 'int slot_num' 6331: slot number 6332: 6333: 'boolean_t is_master' 6334: is this the master processor 6335: 6336: -- Data type: processor_basic_info_t 6337: This is a pointer to a 'struct processor_basic_info'. 6338: 6339: 6340: File: mach.info, Node: Device Interface, Next: Kernel Debugger, Prev: Processors and Processor Sets, Up: Top 6341: 6342: 10 Device Interface 6343: ******************* 6344: 6345: The GNU Mach microkernel provides a simple device interface that allows 6346: the user space programs to access the underlying hardware devices. Each 6347: device has a unique name, which is a string up to 127 characters long. 6348: To open a device, the device master port has to be supplied. The device 6349: master port is only available through the bootstrap port. Anyone who 6350: has control over the device master port can use all hardware devices. 6351: 6352: -- Data type: device_t 6353: This is a 'mach_port_t' and used to hold the port name of a device 6354: port that represents the device. Operations on the device are 6355: implemented as remote procedure calls to the device port. Each 6356: device provides a sequence of records. The length of a record is 6357: specific to the device. Data can be transferred "out-of-line" or 6358: "in-line" (*note Memory::). 6359: 6360: All constants and functions in this chapter are defined in 6361: 'device/device.h'. 6362: 6363: * Menu: 6364: 6365: * Device Reply Server:: Handling device reply messages. 6366: * Device Open:: Opening hardware devices. 6367: * Device Close:: Closing hardware devices. 6368: * Device Read:: Reading data from the device. 6369: * Device Write:: Writing data to the device. 6370: * Device Map:: Mapping devices into virtual memory. 6371: * Device Status:: Querying and manipulating a device. 6372: * Device Filter:: Filtering packets arriving on a device. 6373: 6374: 6375: File: mach.info, Node: Device Reply Server, Next: Device Open, Up: Device Interface 6376: 6377: 10.1 Device Reply Server 6378: ======================== 6379: 6380: Beside the usual synchronous interface, an asynchronous interface is 6381: provided. For this, the caller has to receive and handle the reply 6382: messages separately from the function call. 6383: 6384: -- Function: boolean_t device_reply_server (msg_header_t *IN_MSG, 6385: msg_header_t *OUT_MSG) 6386: The function 'device_reply_server' is produced by the remote 6387: procedure call generator to handle a received message. This 6388: function does all necessary argument handling, and actually calls 6389: one of the following functions: 'ds_device_open_reply', 6390: 'ds_device_read_reply', 'ds_device_read_reply_inband', 6391: 'ds_device_write_reply' and 'ds_device_write_reply_inband'. 6392: 6393: The IN_MSG argument is the message that has been received from the 6394: kernel. The OUT_MSG is a reply message, but this is not used for 6395: this server. 6396: 6397: The function returns 'TRUE' to indicate that the message in 6398: question was applicable to this interface, and that the appropriate 6399: routine was called to interpret the message. It returns 'FALSE' to 6400: indicate that the message did not apply to this interface, and that 6401: no other action was taken. 6402: 6403: 6404: File: mach.info, Node: Device Open, Next: Device Close, Prev: Device Reply Server, Up: Device Interface 6405: 6406: 10.2 Device Open 6407: ================ 6408: 6409: -- Function: kern_return_t device_open (mach_port_t MASTER_PORT, 6410: dev_mode_t MODE, dev_name_t NAME, device_t *DEVICE) 6411: The function 'device_open' opens the device NAME and returns a port 6412: to it in DEVICE. The open count for the device is incremented by 6413: one. If the open count was 0, the open handler for the device is 6414: invoked. 6415: 6416: MASTER_PORT must hold the master device port. NAME specifies the 6417: device to open, and is a string up to 128 characters long. MODE is 6418: the open mode. It is a bitwise-or of the following constants: 6419: 6420: 'D_READ' 6421: Request read access for the device. 6422: 6423: 'D_WRITE' 6424: Request write access for the device. 6425: 6426: 'D_NODELAY' 6427: Do not delay an open. 6428: 6429: The function returns 'D_SUCCESS' if the device was successfully 6430: opened, 'D_INVALID_OPERATION' if MASTER_PORT is not the master 6431: device port, 'D_WOULD_BLOCK' is the device is busy and 'D_NOWAIT' 6432: was specified in mode, 'D_ALREADY_OPEN' if the device is already 6433: open in an incompatible mode and 'D_NO_SUCH_DEVICE' if NAME does 6434: not denote a know device. 6435: 6436: -- Function: kern_return_t device_open_request 6437: (mach_port_t MASTER_PORT, mach_port_t REPLY_PORT, 6438: dev_mode_t MODE, dev_name_t NAME) 6439: -- Function: kern_return_t ds_device_open_reply 6440: (mach_port_t REPLY_PORT, kern_return_t RETURN, 6441: device_t *DEVICE) 6442: This is the asynchronous form of the 'device_open' function. 6443: 'device_open_request' performs the open request. The meaning for 6444: the parameters is as in 'device_open'. Additionally, the caller 6445: has to supply a reply port to which the 'ds_device_open_reply' 6446: message is sent by the kernel when the open has been performed. 6447: The return value of the open operation is stored in RETURN_CODE. 6448: 6449: As neither function receives a reply message, only message 6450: transmission errors apply. If no error occurs, 'KERN_SUCCESS' is 6451: returned. 6452: 6453: 6454: File: mach.info, Node: Device Close, Next: Device Read, Prev: Device Open, Up: Device Interface 6455: 6456: 10.3 Device Close 6457: ================= 6458: 6459: -- Function: kern_return_t device_close (device_t DEVICE) 6460: The function 'device_close' decrements the open count of the device 6461: by one. If the open count drops to zero, the close handler for the 6462: device is called. The device to close is specified by its port 6463: DEVICE. 6464: 6465: The function returns 'D_SUCCESS' if the device was successfully 6466: closed and 'D_NO_SUCH_DEVICE' if DEVICE does not denote a device 6467: port. 6468: 6469: 6470: File: mach.info, Node: Device Read, Next: Device Write, Prev: Device Close, Up: Device Interface 6471: 6472: 10.4 Device Read 6473: ================ 6474: 6475: -- Function: kern_return_t device_read (device_t DEVICE, 6476: dev_mode_t MODE, recnum_t RECNUM, int BYTES_WANTED, 6477: io_buf_ptr_t *DATA, mach_msg_type_number_t *DATA_COUNT) 6478: The function 'device_read' reads BYTES_WANTED bytes from DEVICE, 6479: and stores them in a buffer allocated with 'vm_allocate', which 6480: address is returned in DATA. The caller must deallocated it if it 6481: is no longer needed. The number of bytes actually returned is 6482: stored in DATA_COUNT. 6483: 6484: If MODE is 'D_NOWAIT', the operation does not block. Otherwise 6485: MODE should be 0. RECNUM is the record number to be read, its 6486: meaning is device specific. 6487: 6488: The function returns 'D_SUCCESS' if some data was successfully 6489: read, 'D_WOULD_BLOCK' if no data is currently available and 6490: 'D_NOWAIT' is specified, and 'D_NO_SUCH_DEVICE' if DEVICE does not 6491: denote a device port. 6492: 6493: -- Function: kern_return_t device_read_inband (device_t DEVICE, 6494: dev_mode_t MODE, recnum_t RECNUM, int BYTES_WANTED, 6495: io_buf_ptr_inband_t *DATA, mach_msg_type_number_t *DATA_COUNT) 6496: The 'device_read_inband' function works as the 'device_read' 6497: function, except that the data is returned "in-line" in the reply 6498: IPC message (*note Memory::). 6499: 6500: -- Function: kern_return_t device_read_request (device_t DEVICE, 6501: mach_port_t REPLY_PORT, dev_mode_t MODE, recnum_t RECNUM, 6502: int BYTES_WANTED) 6503: -- Function: kern_return_t ds_device_read_reply 6504: (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE, 6505: io_buf_ptr_t DATA, mach_msg_type_number_t DATA_COUNT) 6506: This is the asynchronous form of the 'device_read' function. 6507: 'device_read_request' performs the read request. The meaning for 6508: the parameters is as in 'device_read'. Additionally, the caller 6509: has to supply a reply port to which the 'ds_device_read_reply' 6510: message is sent by the kernel when the read has been performed. 6511: The return value of the read operation is stored in RETURN_CODE. 6512: 6513: As neither function receives a reply message, only message 6514: transmission errors apply. If no error occurs, 'KERN_SUCCESS' is 6515: returned. 6516: 6517: -- Function: kern_return_t device_read_request_inband (device_t DEVICE, 6518: mach_port_t REPLY_PORT, dev_mode_t MODE, recnum_t RECNUM, 6519: int BYTES_WANTED) 6520: -- Function: kern_return_t ds_device_read_reply_inband 6521: (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE, 6522: io_buf_ptr_t DATA, mach_msg_type_number_t DATA_COUNT) 6523: The 'device_read_request_inband' and 'ds_device_read_reply_inband' 6524: functions work as the 'device_read_request' and 6525: 'ds_device_read_reply' functions, except that the data is returned 6526: "in-line" in the reply IPC message (*note Memory::). 6527: 6528: 6529: File: mach.info, Node: Device Write, Next: Device Map, Prev: Device Read, Up: Device Interface 6530: 6531: 10.5 Device Write 6532: ================= 6533: 6534: -- Function: kern_return_t device_write (device_t DEVICE, 6535: dev_mode_t MODE, recnum_t RECNUM, io_buf_ptr_t DATA, 6536: mach_msg_type_number_t DATA_COUNT, int *BYTES_WRITTEN) 6537: The function 'device_write' writes DATA_COUNT bytes from the buffer 6538: DATA to DEVICE. The number of bytes actually written is returned 6539: in BYTES_WRITTEN. 6540: 6541: If MODE is 'D_NOWAIT', the function returns without waiting for I/O 6542: completion. Otherwise MODE should be 0. RECNUM is the record 6543: number to be written, its meaning is device specific. 6544: 6545: The function returns 'D_SUCCESS' if some data was successfully 6546: written and 'D_NO_SUCH_DEVICE' if DEVICE does not denote a device 6547: port or the device is dead or not completely open. 6548: 6549: -- Function: kern_return_t device_write_inband (device_t DEVICE, 6550: dev_mode_t MODE, recnum_t RECNUM, int BYTES_WANTED, 6551: io_buf_ptr_inband_t *DATA, mach_msg_type_number_t *DATA_COUNT) 6552: The 'device_write_inband' function works as the 'device_write' 6553: function, except that the data is sent "in-line" in the request IPC 6554: message (*note Memory::). 6555: 6556: -- Function: kern_return_t device_write_request (device_t DEVICE, 6557: mach_port_t REPLY_PORT, dev_mode_t MODE, recnum_t RECNUM, 6558: io_buf_ptr_t DATA, mach_msg_type_number_t DATA_COUNT) 6559: -- Function: kern_return_t ds_device_write_reply 6560: (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE, 6561: int BYTES_WRITTEN) 6562: This is the asynchronous form of the 'device_write' function. 6563: 'device_write_request' performs the write request. The meaning for 6564: the parameters is as in 'device_write'. Additionally, the caller 6565: has to supply a reply port to which the 'ds_device_write_reply' 6566: message is sent by the kernel when the write has been performed. 6567: The return value of the write operation is stored in RETURN_CODE. 6568: 6569: As neither function receives a reply message, only message 6570: transmission errors apply. If no error occurs, 'KERN_SUCCESS' is 6571: returned. 6572: 6573: -- Function: kern_return_t device_write_request_inband 6574: (device_t DEVICE, mach_port_t REPLY_PORT, dev_mode_t MODE, 6575: recnum_t RECNUM, io_buf_ptr_t DATA, 6576: mach_msg_type_number_t DATA_COUNT) 6577: -- Function: kern_return_t ds_device_write_reply_inband 6578: (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE, 6579: int BYTES_WRITTEN) 6580: The 'device_write_request_inband' and 6581: 'ds_device_write_reply_inband' functions work as the 6582: 'device_write_request' and 'ds_device_write_reply' functions, 6583: except that the data is sent "in-line" in the request IPC message 6584: (*note Memory::). 6585: 6586: 6587: File: mach.info, Node: Device Map, Next: Device Status, Prev: Device Write, Up: Device Interface 6588: 6589: 10.6 Device Map 6590: =============== 6591: 6592: -- Function: kern_return_t device_map (device_t DEVICE, vm_prot_t PROT, 6593: vm_offset_t OFFSET, vm_size_t SIZE, mach_port_t *PAGER, 6594: int UNMAP) 6595: The function 'device_map' creates a new memory manager for DEVICE 6596: and returns a port to it in PAGER. The memory manager is usable as 6597: a memory object in a 'vm_map' call. The call is device dependent. 6598: 6599: The protection for the memory object is specified by PROT. The 6600: memory object starts at OFFSET within the device and extends SIZE 6601: bytes. UNMAP is currently unused. 6602: 6603: The function returns 'D_SUCCESS' if some data was successfully 6604: written and 'D_NO_SUCH_DEVICE' if DEVICE does not denote a device 6605: port or the device is dead or not completely open. 6606: 6607: 6608: File: mach.info, Node: Device Status, Next: Device Filter, Prev: Device Map, Up: Device Interface 6609: 6610: 10.7 Device Status 6611: ================== 6612: 6613: -- Function: kern_return_t device_set_status (device_t DEVICE, 6614: dev_flavor_t FLAVOR, dev_status_t STATUS, 6615: mach_msg_type_number_t STATUS_COUNT) 6616: The function 'device_set_status' sets the status of a device. The 6617: possible values for FLAVOR and their interpretation is device 6618: specific. 6619: 6620: The function returns 'D_SUCCESS' if some data was successfully 6621: written and 'D_NO_SUCH_DEVICE' if DEVICE does not denote a device 6622: port or the device is dead or not completely open. 6623: 6624: -- Function: kern_return_t device_get_status (device_t DEVICE, 6625: dev_flavor_t FLAVOR, dev_status_t STATUS, 6626: mach_msg_type_number_t *STATUS_COUNT) 6627: The function 'device_get_status' gets the status of a device. The 6628: possible values for FLAVOR and their interpretation is device 6629: specific. 6630: 6631: The function returns 'D_SUCCESS' if some data was successfully 6632: written and 'D_NO_SUCH_DEVICE' if DEVICE does not denote a device 6633: port or the device is dead or not completely open. 6634:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.