diff options
| author | Thomas Schwinge <tschwinge@gnu.org> | 2007-01-11 01:05:45 +0000 |
|---|---|---|
| committer | Thomas Schwinge <tschwinge@gnu.org> | 2009-06-18 00:27:01 +0200 |
| commit | c03c222abe9958b563a78172dddd84e96ef10051 (patch) | |
| tree | eed6b7b2bc87052b104fec48cdeedb87c88d69c4 /doc | |
| parent | 3527b78c645a5898c7ddbeb3128a49c21514cb1c (diff) | |
2006-01-11 Thomas Schwinge <tschwinge@gnu.org>
These following files are regenerated by running ``autoreconf -i'' and
``make info''.
* COPYING: Remove file.
* INSTALL: Likewise.
* Makefile.in: Likewise.
* aclocal.m4: Likewise.
* build-aux/compile: Likewise.
* build-aux/config.guess: Likewise.
* build-aux/config.sub: Likewise.
* build-aux/depcomp: Likewise.
* build-aux/install-sh: Likewise.
* build-aux/mdate-sh: Likewise.
* build-aux/missing: Likewise.
* build-aux/texinfo.tex: Likewise.
* config.h.in: Likewise.
* configure: Likewise.
* doc/mach.info: Likewise.
* doc/mach.info-1: Likewise.
* doc/mach.info-2: Likewise.
* doc/stamp-vti: Likewise.
* doc/version.texi: Likewise.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/mach.info | 175 | ||||
| -rw-r--r-- | doc/mach.info-1 | 6683 | ||||
| -rw-r--r-- | doc/mach.info-2 | 1663 | ||||
| -rw-r--r-- | doc/stamp-vti | 4 | ||||
| -rw-r--r-- | doc/version.texi | 4 |
5 files changed, 0 insertions, 8529 deletions
diff --git a/doc/mach.info b/doc/mach.info deleted file mode 100644 index c2100e5..0000000 --- a/doc/mach.info +++ /dev/null @@ -1,175 +0,0 @@ -This is ../doc/mach.info, produced by makeinfo version 4.8 from -../doc/mach.texi. - -INFO-DIR-SECTION Kernel -START-INFO-DIR-ENTRY -* GNUMach: (mach). Using and programming the GNU Mach microkernel. -END-INFO-DIR-ENTRY - - This file documents the GNU Mach microkernel. - - This is Edition 0.4, last updated 2001-09-01, of `The GNU Mach -Reference Manual', for Version 1.3.99. - - Copyright (C) 2001 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "Free Software Needs Free Documentation" and -"GNU Lesser General Public License", the Front-Cover texts being (a) -(see below), and with the Back-Cover Texts being (b) (see below). A -copy of the license is included in the section entitled "GNU Free -Documentation License". - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - - This work is based on manual pages under the following copyright and -license: - -Mach Operating System -Copyright (C) 1991,1990 Carnegie Mellon University -All Rights Reserved. - - Permission to use, copy, modify and distribute this software and its -documentation is hereby granted, provided that both the copyright -notice and this permission notice appear in all copies of the software, -derivative works or modified versions, and any portions thereof, and -that both notices appear in supporting documentation. - - CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" -CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY -DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. - - -Indirect: -mach.info-1: 1914 -mach.info-2: 296589 - -Tag Table: -(Indirect) -Node: Top1914 -Node: Introduction10176 -Node: Audience11007 -Node: Features12042 -Node: Overview13869 -Node: History15062 -Node: Installing15207 -Node: Binary Distributions16431 -Node: Compilation17240 -Node: Configuration18219 -Node: Cross-Compilation31019 -Node: Bootstrap31800 -Ref: Bootstrap-Footnote-132243 -Node: Bootloader32480 -Ref: Bootloader-Footnote-133781 -Node: Modules33863 -Node: Inter Process Communication34668 -Node: Major Concepts35291 -Node: Messaging Interface39096 -Node: Mach Message Call39826 -Node: Message Format43141 -Node: Exchanging Port Rights53602 -Ref: Exchanging Port Rights-Footnote-159168 -Node: Memory59341 -Ref: Memory-Footnote-162435 -Node: Message Send62777 -Ref: Message Send-Footnote-169803 -Node: Message Receive70085 -Ref: Message Receive-Footnote-178722 -Node: Atomicity79003 -Node: Port Manipulation Interface81776 -Node: Port Creation83252 -Node: Port Destruction88038 -Node: Port Names91181 -Node: Port Rights95419 -Node: Ports and other Tasks99216 -Node: Receive Rights103308 -Node: Port Sets108478 -Node: Request Notifications110881 -Node: Virtual Memory Interface115668 -Node: Memory Allocation116921 -Node: Memory Deallocation119446 -Node: Data Transfer120907 -Node: Memory Attributes124432 -Node: Mapping Memory Objects133844 -Node: Memory Statistics137133 -Node: External Memory Management138693 -Node: Memory Object Server139398 -Node: Memory Object Creation142107 -Node: Memory Object Termination146113 -Node: Memory Objects and Data149051 -Node: Memory Object Locking166200 -Node: Memory Object Attributes172093 -Node: Default Memory Manager177933 -Node: Threads and Tasks183654 -Node: Thread Interface183991 -Node: Thread Creation184992 -Node: Thread Termination186109 -Node: Thread Information186580 -Node: Thread Settings192652 -Node: Thread Execution193886 -Node: Scheduling201180 -Node: Thread Priority201535 -Node: Hand-Off Scheduling204174 -Node: Scheduling Policy209166 -Node: Thread Special Ports210499 -Node: Exceptions212945 -Node: Task Interface213824 -Node: Task Creation214836 -Node: Task Termination216171 -Node: Task Information216773 -Node: Task Execution223289 -Node: Task Special Ports227702 -Node: Syscall Emulation231555 -Node: Profiling232782 -Node: Host Interface236540 -Node: Host Ports237525 -Node: Host Information239598 -Node: Host Time244971 -Node: Host Reboot247630 -Node: Processors and Processor Sets248180 -Node: Processor Set Interface249158 -Node: Processor Set Ports249925 -Node: Processor Set Access250760 -Node: Processor Set Creation253023 -Node: Processor Set Destruction254050 -Node: Tasks and Threads on Sets254971 -Node: Processor Set Priority260145 -Node: Processor Set Policy261435 -Node: Processor Set Info263048 -Node: Processor Interface266851 -Node: Hosted Processors267576 -Node: Processor Control268567 -Node: Processors and Sets270033 -Node: Processor Info271914 -Node: Device Interface274650 -Node: Device Reply Server276265 -Node: Device Open277557 -Node: Device Close279677 -Node: Device Read280256 -Node: Device Write283175 -Node: Device Map285980 -Node: Device Status286876 -Node: Device Filter288049 -Node: Kernel Debugger292885 -Node: Operation293612 -Node: Commands296589 -Node: Variables309812 -Node: Expressions311199 -Node: Copying312548 -Node: Documentation License331757 -Node: Free Documentation License332345 -Node: CMU License352244 -Node: Concept Index353475 -Node: Function and Data Index357317 - -End Tag Table diff --git a/doc/mach.info-1 b/doc/mach.info-1 deleted file mode 100644 index a1bb76c..0000000 --- a/doc/mach.info-1 +++ /dev/null @@ -1,6683 +0,0 @@ -This is ../doc/mach.info, produced by makeinfo version 4.8 from -../doc/mach.texi. - -INFO-DIR-SECTION Kernel -START-INFO-DIR-ENTRY -* GNUMach: (mach). Using and programming the GNU Mach microkernel. -END-INFO-DIR-ENTRY - - This file documents the GNU Mach microkernel. - - This is Edition 0.4, last updated 2001-09-01, of `The GNU Mach -Reference Manual', for Version 1.3.99. - - Copyright (C) 2001 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "Free Software Needs Free Documentation" and -"GNU Lesser General Public License", the Front-Cover texts being (a) -(see below), and with the Back-Cover Texts being (b) (see below). A -copy of the license is included in the section entitled "GNU Free -Documentation License". - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - - This work is based on manual pages under the following copyright and -license: - -Mach Operating System -Copyright (C) 1991,1990 Carnegie Mellon University -All Rights Reserved. - - Permission to use, copy, modify and distribute this software and its -documentation is hereby granted, provided that both the copyright -notice and this permission notice appear in all copies of the software, -derivative works or modified versions, and any portions thereof, and -that both notices appear in supporting documentation. - - CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" -CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY -DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. - - -File: mach.info, Node: Top, Next: Introduction, Up: (dir) - -Main Menu -********* - -This is Edition 0.4, last updated 2001-09-01, of `The GNU Mach -Reference Manual', for Version 1.3.99 of the GNU Mach microkernel. - -* Menu: - -* Introduction:: How to use this manual. -* Installing:: Setting up GNU Mach on your computer. -* Bootstrap:: Running GNU Mach on your machine. -* Inter Process Communication:: Communication between process. -* Virtual Memory Interface:: Allocating and deallocating virtual memory. -* External Memory Management:: Handling memory pages in user space. -* Threads and Tasks:: Handling of threads and tasks. -* Host Interface:: Interface to a Mach host. -* Processors and Processor Sets:: Handling processors and sets of processors. -* Device Interface:: Accesing kernel devices. -* Kernel Debugger:: How to use the built-in kernel debugger. - -Appendices - -* Copying:: The GNU General Public License says how you - can copy and share the GNU Mach microkernel. -* Documentation License:: This manual is under the GNU Free - Documentation License. - -Indices - -* Concept Index:: Index of concepts and programs. -* Function and Data Index:: Index of functions, variables and data types. - - - --- The Detailed Node Listing --- - -Introduction - -* Audience:: The people for whom this manual is written. -* Features:: Reasons to install and use GNU Mach. -* Overview:: Basic architecture of the Mach microkernel. -* History:: The story about Mach. - -Installing - -* Binary Distributions:: Obtaining ready-to-run GNU distributions. -* Compilation:: Building GNU Mach from its source code. -* Configuration:: Configuration options at compilation time. -* Cross-Compilation:: Building GNU Mach from another system. - -Bootstrap - -* Bootloader:: Starting the microkernel, or other OSes. -* Modules:: Starting the first task of the OS. - -Inter Process Communication - -* Major Concepts:: The concepts behind the Mach IPC system. -* Messaging Interface:: Composing, sending and receiving messages. -* Port Manipulation Interface:: Manipulating ports, port rights, port sets. - -Messaging Interface - -* Mach Message Call:: Sending and receiving messages. -* Message Format:: The format of Mach messages. -* Exchanging Port Rights:: Sending and receiving port rights. -* Memory:: Passing memory regions in messages. -* Message Send:: Sending messages. -* Message Receive:: Receiving messages. -* Atomicity:: Atomicity of port rights. - -Port Manipulation Interface - -* Port Creation:: How to create new ports and port sets. -* Port Destruction:: How to destroy ports and port sets. -* Port Names:: How to query and manipulate port names. -* Port Rights:: How to work with port rights. -* Ports and other Tasks:: How to move rights between tasks. -* Receive Rights:: How to work with receive rights. -* Port Sets:: How to work with port sets. -* Request Notifications:: How to request notifications for events. - -Virtual Memory Interface - -* Memory Allocation:: Allocation of new virtual memory. -* Memory Deallocation:: Freeing unused virtual memory. -* Data Transfer:: Reading, writing and copying memory. -* Memory Attributes:: Tweaking memory regions. -* Mapping Memory Objects:: How to map memory objects. -* Memory Statistics:: How to get statistics about memory usage. - -External Memory Management - -* Memory Object Server:: The basics of external memory management. -* Memory Object Creation:: How new memory objects are created. -* Memory Object Termination:: How memory objects are terminated. -* Memory Objects and Data:: Data transfer to and from memory objects. -* Memory Object Locking:: How memory objects are locked. -* Memory Object Attributes:: Manipulating attributes of memory objects. -* Default Memory Manager:: Setting and using the default memory manager. - -Threads and Tasks - -* Thread Interface:: Manipulating threads. -* Task Interface:: Manipulating tasks. -* Profiling:: Profiling threads and tasks. - -Thread Interface - -* Thread Creation:: Creating threads. -* Thread Termination:: Terminating threads. -* Thread Information:: How to get informations on threads. -* Thread Settings:: How to set threads related informations. -* Thread Execution:: How to control the thread's machine state. -* Scheduling:: Operations on thread scheduling. -* Thread Special Ports:: How to handle the thread's special ports. -* Exceptions:: Managing exceptions. - -Scheduling - -* Thread Priority:: Changing the priority of a thread. -* Hand-Off Scheduling:: Switch to a new thread. -* Scheduling Policy:: Setting the scheduling policy. - -Task Interface - -* Task Creation:: Creating tasks. -* Task Termination:: Terminating tasks. -* Task Information:: Informations on tasks. -* Task Execution:: Thread scheduling in a task. -* Task Special Ports:: How to get and set the task's special ports. -* Syscall Emulation:: How to emulate system calls. - -Host Interface - -* Host Ports:: Ports representing a host. -* Host Information:: Query information about a host. -* Host Time:: Functions to query manipulate the host time. -* Host Reboot:: Rebooting the system. - -Processors and Processor Sets - -* Processor Set Interface:: How to work with processor sets. -* Processor Interface:: How to work with individual processors. - -Processor Set Interface - -* Processor Set Ports:: Ports representing a processor set. -* Processor Set Access:: How the processor sets are accessed. -* Processor Set Creation:: How new processor sets are created. -* Processor Set Destruction:: How processor sets are destroyed. -* Tasks and Threads on Sets:: Assigning tasks or threads to processor sets. -* Processor Set Priority:: Specifying the priority of a processor set. -* Processor Set Policy:: Changing the processor set policies. -* Processor Set Info:: Obtaining information about a processor set. - -Processor Interface - -* Hosted Processors:: Getting a list of all processors on a host. -* Processor Control:: Starting, stopping, controlling processors. -* Processors and Sets:: Combining processors into processor sets. -* Processor Info:: Obtaining information on processors. - -Device Interface - -* Device Open:: Opening hardware devices. -* Device Close:: Closing hardware devices. -* Device Read:: Reading data from the device. -* Device Write:: Writing data to the device. -* Device Map:: Mapping devices into virtual memory. -* Device Status:: Querying and manipulating a device. -* Device Filter:: Filtering packets arriving on a device. - -Kernel Debugger - -* Operation:: Basic architecture of the kernel debugger. -* Commands:: Available commands in the kernel debugger. -* Variables:: Access of variables from the kernel debugger. -* Expressions:: Usage of expressions in the kernel debugger. - -Documentation License - -* Free Documentation License:: The GNU Free Documentation License. -* CMU License:: The CMU license applies to the original Mach - kernel and its documentation. - - -File: mach.info, Node: Introduction, Next: Installing, Prev: Top, Up: Top - -1 Introduction -************** - -GNU Mach is the microkernel of the GNU Project. It is the base of the -operating system, and provides its functionality to the Hurd servers, -the GNU C Library and all user applications. The microkernel itself -does not provide much functionality of the system, just enough to make -it possible for the Hurd servers and the C library to implement the -missing features you would expect from a POSIX compatible operating -system. - -* Menu: - -* Audience:: The people for whom this manual is written. -* Features:: Reasons to install and use GNU Mach. -* Overview:: Basic architecture of the Mach microkernel. -* History:: The story about Mach. - - -File: mach.info, Node: Audience, Next: Features, Up: Introduction - -1.1 Audience -============ - -This manual is designed to be useful to everybody who is interested in -using, administering, or programming the Mach microkernel. - - If you are an end-user and you are looking for help on running the -Mach kernel, the first few chapters of this manual describe the -essential parts of installing and using the kernel in the GNU operating -system. - - The rest of this manual is a technical discussion of the Mach -programming interface and its implementation, and would not be helpful -until you want to learn how to extend the system or modify the kernel. - - This manual is organized according to the subsystems of Mach, and -each chapter begins with descriptions of conceptual ideas that are -related to that subsystem. If you are a programmer and want to learn -more about, say, the Mach IPC subsystem, you can skip to the IPC chapter -(*note Inter Process Communication::), and read about the related -concepts and interface definitions. - - -File: mach.info, Node: Features, Next: Overview, Prev: Audience, Up: Introduction - -1.2 Features -============ - -GNU Mach is not the most advanced microkernel known to the planet, nor -is it the fastest or smallest, but it has a rich set of interfaces and -some features which make it useful as the base of the Hurd system. - -it's free software - Anybody can use, modify, and redistribute it under the terms of - the GNU General Public License (*note Copying::). GNU Mach is - part of the GNU system, which is a complete operating system - licensed under the GPL. - -it's built to survive - As a microkernel, GNU Mach doesn't implement a lot of the features - commonly found in an operating system, but only the bare minimum - that is required to implement a full operating system on top of it. - This means that a lot of the operating system code is maintained - outside of GNU Mach, and while this code may go through a complete - redesign, the code of the microkernel can remain comparatively - stable. - -it's scalable - Mach is particularly well suited for SMP and network cluster - techniques. Thread support is provided at the kernel level, and - the kernel itself takes advantage of that. Network transparency - at the IPC level makes resources of the system available across - machine boundaries (with NORMA IPC, currently not available in GNU - Mach). - -it exists - The Mach microkernel is real software that works Right Now. It is - not a research or a proposal. You don't have to wait at all - before you can start using and developing it. Mach has been used - in many operating systems in the past, usually as the base for a - single UNIX server. In the GNU system, Mach is the base of a - functional multi-server operating system, the Hurd. - - -File: mach.info, Node: Overview, Next: History, Prev: Features, Up: Introduction - -1.3 Overview -============ - -An operating system kernel provides a framework for programs to share a -computer's hardware resources securely and efficiently. This requires -that the programs are seperated and protected from each other. To make -running multiple programs in parallel useful, there also needs to be a -facility for programs to exchange information by communication. - - The Mach microkernel provides abstractions of the underlying hardware -resources like devices and memory. It organizes the running programs -into tasks and threads (points of execution in the tasks). In addition, -Mach provides a rich interface for inter-process communication. - - What Mach does not provide is a POSIX compatible programming -interface. In fact, it has no understanding of file systems, POSIX -process semantics, network protocols and many more. All this is -implemented in tasks running on top of the microkernel. In the GNU -operating system, the Hurd servers and the C library share the -responsibility to implement the POSIX interface, and the additional -interfaces which are specific to the GNU system. - - -File: mach.info, Node: History, Prev: Overview, Up: Introduction - -1.4 History -=========== - -XXX A few lines about the history of Mach here. - - -File: mach.info, Node: Installing, Next: Bootstrap, Prev: Introduction, Up: Top - -2 Installing -************ - -Before you can use the Mach microkernel in your system you'll need to -install it and all components you want to use with it, e.g. the rest of -the operating system. You also need a bootloader to load the kernel -from the storage medium and run it when the computer is started. - - GNU Mach is only available for Intel i386-compatible architectures -(such as the Pentium) currently. If you have a different architecture -and want to run the GNU Mach microkernel, you will need to port the -kernel and all other software of the system to your machine's -architecture. Porting is an involved process which requires -considerable programming skills, and it is not recommended for the -faint-of-heart. If you have the talent and desire to do a port, contact -<bug-hurd@gnu.org> in order to coordinate the effort. - -* Menu: - -* Binary Distributions:: Obtaining ready-to-run GNU distributions. -* Compilation:: Building GNU Mach from its source code. -* Configuration:: Configuration options at compile time. -* Cross-Compilation:: Building GNU Mach from another system. - - -File: mach.info, Node: Binary Distributions, Next: Compilation, Up: Installing - -2.1 Binary Distributions -======================== - -By far the easiest and best way to install GNU Mach and the operating -system is to obtain a GNU binary distribution. The GNU operating -system consists of GNU Mach, the Hurd, the C library and many -applications. Without the GNU operating system, you will only have a -microkernel, which is not very useful by itself, without the other -programs. - - Building the whole operating system takes a huge effort, and you are -well advised to not do it yourself, but to get a binary distribution of -the GNU operating system. The distribution also includes a binary of -the GNU Mach microkernel. - - Information on how to obtain the GNU system can be found in the Hurd -info manual. - - -File: mach.info, Node: Compilation, Next: Configuration, Prev: Binary Distributions, Up: Installing - -2.2 Compilation -=============== - -If you already have a running GNU system, and only want to recompile -the kernel, for example to select a different set of included hardware -drivers, you can easily do this. You need the GNU C compiler and MiG, -the Mach interface generator, which both come in their own packages. - - Building and installing the kernel is as easy as with any other GNU -software package. The configure script is used to configure the source -and set the compile time options. The compilation is done by running: - - make - - To install the kernel and its header files, just enter the command: - - make install - - This will install the kernel into $(prefix)/boot/gnumach and the -header files into $(prefix)/include. You can also only install the -kernel or the header files. For this, the two targets install-kernel -and install-headers are provided. - - -File: mach.info, Node: Configuration, Next: Cross-Compilation, Prev: Compilation, Up: Installing - -2.3 Configuration -================= - -The following options can be passed to the configure script as command -line arguments and control what components are built into the kernel, or -where it is installed. - - The default for an option is to be disabled, unless otherwise noted. - - This table is out-dated. Please see the file `i386/README-Drivers' -and the output of `[GNU Mach]/configure --help=recursive'. - -`--prefix PREFIX' - Sets the prefix to PREFIX. The default prefix is the empty - string, which is the correct value for the GNU system. The prefix - is prepended to all file names at installation time. - -`--enable-kdb' - Enables the in-kernel debugger. This is only useful if you - actually anticipate debugging the kernel. It is not enabled by - default because it adds considerably to the unpageable memory - footprint of the kernel. *Note Kernel Debugger::. - -`--enable-kmsg' - Enables the kernel message device kmsg. - -`--enable-lpr' - Enables the parallel port devices lpr%d. - -`--enable-floppy' - Enables the PC floppy disk controller devices fd%d. - -`--enable-ide' - Enables the IDE controller devices hd%d, hd%ds%d. - - The following options enable drivers for various SCSI controller. -SCSI devices are named sd%d (disks) or cd%d (CD ROMs). - -`--enable-advansys' - Enables the AdvanSys SCSI controller devices sd%d, cd%d. - -`--enable-buslogic' - Enables the BusLogic SCSI controller devices sd%d, cd%d. - -`--disable-flashpoint' - Only meaningful in conjunction with `--enable-buslogic'. Omits the - FlshPoint support. This option is enabled by default if - `--enable-buslogic' is specified. - -`--enable-u1434f' - Enables the UltraStor 14F/34F SCSI controller devices sd%d, cd%d. - -`--enable-ultrastor' - Enables the UltraStor SCSI controller devices sd%d, cd%d. - -`--enable-aha152x' -`--enable-aha2825' - Enables the Adaptec AHA-152x/2825 SCSI controller devices sd%d, - cd%d. - -`--enable-aha1542' - Enables the Adaptec AHA-1542 SCSI controller devices sd%d, cd%d. - -`--enable-aha1740' - Enables the Adaptec AHA-1740 SCSI controller devices sd%d, cd%d. - -`--enable-aic7xxx' - Enables the Adaptec AIC7xxx SCSI controller devices sd%d, cd%d. - -`--enable-futuredomain' - Enables the Future Domain 16xx SCSI controller devices sd%d, cd%d. - -`--enable-in2000' - Enables the Always IN 2000 SCSI controller devices sd%d, cd%d. - -`--enable-ncr5380' -`--enable-ncr53c400' - Enables the generic NCR5380/53c400 SCSI controller devices sd%d, - cd%d. - -`--enable-ncr53c406a' - Enables the NCR53c406a SCSI controller devices sd%d, cd%d. - -`--enable-pas16' - Enables the PAS16 SCSI controller devices sd%d, cd%d. - -`--enable-seagate' - Enables the Seagate ST02 and Future Domain TMC-8xx SCSI controller - devices sd%d, cd%d. - -`--enable-t128' -`--enable-t128f' -`--enable-t228' - Enables the Trantor T128/T128F/T228 SCSI controller devices sd%d, - cd%d. - -`--enable-ncr53c7xx' - Enables the NCR53C7,8xx SCSI controller devices sd%d, cd%d. - -`--enable-eatadma' - Enables the EATA-DMA (DPT, NEC, AT&T, SNI, AST, Olivetti, - Alphatronix) SCSI controller devices sd%d, cd%d. - -`--enable-eatapio' - Enables the EATA-PIO (old DPT PM2001, PM2012A) SCSI controller - devices sd%d, cd%d. - -`--enable-wd7000' - Enables the WD 7000 SCSI controller devices sd%d, cd%d. - -`--enable-eata' - Enables the EATA ISA/EISA/PCI (DPT and generic EATA/DMA-compliant - boards) SCSI controller devices sd%d, cd%d. - -`--enable-am53c974' -`--enable-am79c974' - Enables the AM53/79C974 SCSI controller devices sd%d, cd%d. - -`--enable-dtc3280' -`--enable-dtc3180' - Enables the DTC3180/3280 SCSI controller devices sd%d, cd%d. - -`--enable-ncr53c8xx' -`--enable-dc390w' -`--enable-dc390u' -`--enable-dc390f' - Enables the NCR53C8XX SCSI controller devices sd%d, cd%d. - -`--enable-dc390t' -`--enable-dc390' - Enables the Tekram DC-390(T) SCSI controller devices sd%d, cd%d. - -`--enable-ppa' - Enables the IOMEGA Parallel Port ZIP drive device sd%d. - -`--enable-qlogicfas' - Enables the Qlogic FAS SCSI controller devices sd%d, cd%d. - -`--enable-qlogicisp' - Enables the Qlogic ISP SCSI controller devices sd%d, cd%d. - -`--enable-gdth' - Enables the GDT SCSI Disk Array controller devices sd%d, cd%d. - - The following options enable drivers for various ethernet cards. -NIC device names are usually eth%d, except for the pocket adaptors. - - GNU Mach does only autodetect one ethernet card. To enable any -further cards, the source code has to be edited. - -`--enable-ne2000' -`--enable-ne1000' - Enables the NE2000/NE1000 ISA netword card devices eth%d. - -`--enable-3c503' -`--enable-el2' - Enables the 3Com 503 (Etherlink II) netword card devices eth%d. - -`--enable-3c509' -`--enable-3c579' -`--enable-el3' - Enables the 3Com 509/579 (Etherlink III) netword card devices - eth%d. - -`--enable-wd80x3' - Enables the WD80X3 netword card devices eth%d. - -`--enable-3c501' -`--enable-el1' - Enables the 3COM 501 netword card devices eth%d. - -`--enable-ul' - Enables the SMC Ultra netword card devices eth%d. - -`--enable-ul32' - Enables the SMC Ultra 32 netword card devices eth%d. - -`--enable-hplanplus' - Enables the HP PCLAN+ (27247B and 27252A) netword card devices - eth%d. - -`--enable-hplan' - Enables the HP PCLAN (27245 and other 27xxx series) netword card - devices eth%d. - -`--enable-3c59x' -`--enable-3c90x' -`--enable-vortex' - Enables the 3Com 590/900 series (592/595/597/900/905) - "Vortex/Boomerang" netword card devices eth%d. - -`--enable-seeq8005' - Enables the Seeq8005 netword card devices eth%d. - -`--enable-hp100' -`--enable-hpj2577' -`--enable-hpj2573' -`--enable-hp27248b' -`--enable-hp2585' - Enables the HP 10/100VG PCLAN (ISA, EISA, PCI) netword card devices - eth%d. - -`--enable-ac3200' - Enables the Ansel Communications EISA 3200 netword card devices - eth%d. - -`--enable-e2100' - Enables the Cabletron E21xx netword card devices eth%d. - -`--enable-at1700' - Enables the AT1700 (Fujitsu 86965) netword card devices eth%d. - -`--enable-eth16i' -`--enable-eth32' - Enables the ICL EtherTeam 16i/32 netword card devices eth%d. - -`--enable-znet' -`--enable-znote' - Enables the Zenith Z-Note netword card devices eth%d. - -`--enable-eexpress' - Enables the EtherExpress 16 netword card devices eth%d. - -`--enable-eexpresspro' - Enables the EtherExpressPro netword card devices eth%d. - -`--enable-eexpresspro100' - Enables the Intel EtherExpressPro PCI 10+/100B/100+ netword card - devices eth%d. - -`--enable-depca' -`--enable-de100' -`--enable-de101' -`--enable-de200' -`--enable-de201' -`--enable-de202' -`--enable-de210' -`--enable-de422' - Enables the DEPCA, DE10x, DE200, DE201, DE202, DE210, DE422 - netword card devices eth%d. - -`--enable-ewrk3' -`--enable-de203' -`--enable-de204' -`--enable-de205' - Enables the EtherWORKS 3 (DE203, DE204, DE205) netword card devices - eth%d. - -`--enable-de4x5' -`--enable-de425' -`--enable-de434' -`--enable-435' -`--enable-de450' -`--enable-500' - Enables the DE425, DE434, DE435, DE450, DE500 netword card devices - eth%d. - -`--enable-apricot' - Enables the Apricot XEN-II on board ethernet netword card devices - eth%d. - -`--enable-wavelan' - Enables the AT&T WaveLAN & DEC RoamAbout DS netword card devices - eth%d. - -`--enable-3c507' -`--enable-el16' - Enables the 3Com 507 netword card devices eth%d. - -`--enable-3c505' -`--enable-elplus' - Enables the 3Com 505 netword card devices eth%d. - -`--enable-de600' - Enables the D-Link DE-600 netword card devices eth%d. - -`--enable-de620' - Enables the D-Link DE-620 netword card devices eth%d. - -`--enable-skg16' - Enables the Schneider & Koch G16 netword card devices eth%d. - -`--enable-ni52' - Enables the NI5210 netword card devices eth%d. - -`--enable-ni65' - Enables the NI6510 netword card devices eth%d. - -`--enable-atp' - Enables the AT-LAN-TEC/RealTek pocket adaptor netword card devices - atp%d. - -`--enable-lance' -`--enable-at1500' -`--enable-ne2100' - Enables the AMD LANCE and PCnet (AT1500 and NE2100) netword card - devices eth%d. - -`--enable-elcp' -`--enable-tulip' - Enables the DECchip Tulip (dc21x4x) PCI netword card devices eth%d. - -`--enable-fmv18x' - Enables the FMV-181/182/183/184 netword card devices eth%d. - -`--enable-3c515' - Enables the 3Com 515 ISA Fast EtherLink netword card devices eth%d. - -`--enable-pcnet32' - Enables the AMD PCI PCnet32 (PCI bus NE2100 cards) netword card - devices eth%d. - -`--enable-ne2kpci' - Enables the PCI NE2000 netword card devices eth%d. - -`--enable-yellowfin' - Enables the Packet Engines Yellowfin Gigabit-NIC netword card - devices eth%d. - -`--enable-rtl8139' -`--enable-rtl8129' - Enables the RealTek 8129/8139 (not 8019/8029!) netword card - devices eth%d. - -`--enable-epic' -`--enable-epic100' - Enables the SMC 83c170/175 EPIC/100 (EtherPower II) netword card - devices eth%d. - -`--enable-tlan' - Enables the TI ThunderLAN netword card devices eth%d. - -`--enable-viarhine' - Enables the VIA Rhine netword card devices eth%d. - -`--enable-hamachi' - Enables the Packet Engines "Hamachi" GNIC-2 Gigabit Ethernet - devices eth%d. - -`--enable-intel-gige' - Enables the Intel PCI Gigabit Ethernet devices eth%d. - -`--enable-myson803' - Enables the Myson MTD803 Ethernet adapter series devices eth%d. - -`--enable-natsemi' - Enables the National Semiconductor DP8381x series PCI Ethernet - devices eth%d. - -`--enable-ns820' - Enables the National Semiconductor DP8382x series PCI Ethernet - devices eth%d. - -`--enable-starfire' - Enables the Adaptec Starfire network adapter devices eth%d. - -`--enable-sundance' - Enables the Sundance ST201 "Alta" PCI Ethernet devices eth%d. - -`--enable-winbond-840' - Enables the Winbond W89c840 PCI Ethernet devices eth%d. - - The following options either enable drivers for supported PCMCIA -bridges or control the overall behaviour of the GNU Mach PCMCIA core. -To make use of GNU Mach PCMCIA support you need to have the -corresponding userland applications (GNU Mach Card Services) installed. - -`--enable-i82365' - Enables the driver for the Intel 82365 and compatible PC Card - controllers, and Yenta-compatible PCI-to-CardBus controllers. - -`--enable-pcmcia-isa' - Enables ISA-bus related bits in the GNU Mach PCMCIA core. This is - generally a good idea, since it does not only have effect if your - PC Card bridge is attached to the ISA bus, but provides more (ISA) - interrupts to the Card Services for it to assign to the cards in - turn. - - The following options enable drivers for supported PCMCIA Ethernet -controllers. NIC device names are usually eth%d. - -`--enable-3c574_cs' - Enables the PCMCIA ethernet driver for the 3Com 3c574 "RoadRunner". - -`--enable-3c589_cs' - Enables the driver for the 3Com 3c589 PCMCIA card. - -`--enable-axnet_cs' - Enables the driver for the Asix AX88190-based PCMCIA cards. - -`--enable-fmvj18x_cs' - Enables the driver for PCMCIA cards with the fmvj18x chipset. - -`--enable-nmclan_cs' - Enables the driver for the New Media Ethernet LAN PCMCIA cards. - -`--enable-pcnet_cs' - Enables the driver for NS8390-based PCMCIA cards. - - This driver supports the D-Link DE-650 and Linksys EthernetCard - cards, the newer D-Link and Linksys combo cards, Accton EN2212 - cards, the RPTI EP400, and the PreMax PE-200 in non-shared-memory - mode, and the IBM Credit Card Adapter, the NE4100, the Thomas - Conrad ethernet card, and the Kingston KNE-PCM/x in shared-memory - mode. It will also handle the Socket EA card in either mode. - -`--enable-smc91c92_cs' - Enables the driver for SMC91c92-based PCMCIA cards. - -`--enable-xirc2ps_cs' - Enables the driver for Xircom CreditCard and Realport PCMCIA - ethernet adapters. - - The following options enable drivers for supported PCMCIA Wireless -LAN network controllers. NIC device names are usually eth%d. - - Please mind, that you need to have some userland applications (the -GNU Mach Wireless Tools) installed, in order to make use of these -devices. - -`--enable-orinoco_cs' - Enables the driver for the Hermes or Prism 2 chipset based PCMCIA - wireless adapters, with Lucent/Agere, Intersil or Symbol firmware. - - This driver is suitable for PCMCIA wireless adapters, such as the - Lucent WavelanIEEE/Orinoco cards and their OEM (Cabletron/EnteraSys - RoamAbout 802.11, ELSA Airlancer, Melco Buffalo and others). It - should also be usable on various Prism II based cards such as the - Linksys, D-Link and Farallon Skyline. It should also work on Symbol - cards such as the 3Com AirConnect and Ericsson WLAN. - - -File: mach.info, Node: Cross-Compilation, Prev: Configuration, Up: Installing - -2.4 Cross-Compilation -===================== - -Another way to install the kernel is to use an existing operating system -in order to compile the kernel binary. This is called -"cross-compiling", because it is done between two different platforms. -If the pre-built kernels are not working for you, and you can't ask -someone to compile a custom kernel for your machine, this is your last -chance to get a kernel that boots on your hardware. - - Luckily, the kernel does have light dependencies. You don't even -need a cross compiler if your build machine has a compiler and is the -same architecture as the system you want to run GNU Mach on. - - You need a cross-mig, though. - - XXX More info needed. - - -File: mach.info, Node: Bootstrap, Next: Inter Process Communication, Prev: Installing, Up: Top - -3 Bootstrap -*********** - -Bootstrapping(1) is the procedure by which your machine loads the -microkernel and transfers control to the operating system. - -* Menu: - -* Bootloader:: Starting the microkernel, or other OSes. -* Modules:: Starting the first task of the OS. - - ---------- Footnotes ---------- - - (1) The term "bootstrapping" refers to a Dutch legend about a boy -who was able to fly by pulling himself up by his bootstraps. In -computers, this term refers to any process where a simple system -activates a more complicated system. - - -File: mach.info, Node: Bootloader, Next: Modules, Up: Bootstrap - -3.1 Bootloader -============== - -The "bootloader" is the first software that runs on your machine. Many -hardware architectures have a very simple startup routine which reads a -very simple bootloader from the beginning of the internal hard disk, -then transfers control to it. Other architectures have startup -routines which are able to understand more of the contents of the hard -disk, and directly start a more advanced bootloader. - - Currently, "GRUB"(1) is the preferred GNU bootloader. GRUB provides -advanced functionality, and is capable of loading several different -kernels (such as Mach, Linux, DOS, and the *BSD family). *Note -Introduction: (grub)Top. - - GNU Mach conforms to the Multiboot specification which defines an -interface between the bootloader and the components that run very early -at startup. GNU Mach can be started by any bootloader which supports -the multiboot standard. After the bootloader loaded the kernel image to -a designated address in the system memory, it jumps into the startup -code of the kernel. This code initializes the kernel and detects the -available hardware devices. Afterwards, the first system task is -started. *Note Overview: (multiboot)Top. - - ---------- Footnotes ---------- - - (1) The GRand Unified Bootloader, available from -`http://www.uruk.org/grub/'. - - -File: mach.info, Node: Modules, Prev: Bootloader, Up: Bootstrap - -3.2 Modules -=========== - -Because the microkernel does not provide filesystem support and other -features necessary to load the first system task from a storage medium, -the first task is loaded by the bootloader as a module to a specified -address. In the GNU system, this first program is the `serverboot' -executable. GNU Mach inserts the host control port and the device -master port into this task and appends the port numbers to the command -line before executing it. - - The `serverboot' program is responsible for loading and executing -the rest of the Hurd servers. Rather than containing specific -instructions for starting the Hurd, it follows general steps given in a -user-supplied boot script. - - XXX More about boot scripts. - - -File: mach.info, Node: Inter Process Communication, Next: Virtual Memory Interface, Prev: Bootstrap, Up: Top - -4 Inter Process Communication -***************************** - -This chapter describes the details of the Mach IPC system. First the -actual calls concerned with sending and receiving messages are -discussed, then the details of the port system are described in detail. - -* Menu: - -* Major Concepts:: The concepts behind the Mach IPC system. -* Messaging Interface:: Composing, sending and receiving messages. -* Port Manipulation Interface:: Manipulating ports, port rights, port sets. - - -File: mach.info, Node: Major Concepts, Next: Messaging Interface, Up: Inter Process Communication - -4.1 Major Concepts -================== - -The Mach kernel provides message-oriented, capability-based interprocess -communication. The interprocess communication (IPC) primitives -efficiently support many different styles of interaction, including -remote procedure calls (RPC), object-oriented distributed programming, -streaming of data, and sending very large amounts of data. - - The IPC primitives operate on three abstractions: messages, ports, -and port sets. User tasks access all other kernel services and -abstractions via the IPC primitives. - - The message primitives let tasks send and receive messages. Tasks -send messages to ports. Messages sent to a port are delivered reliably -(messages may not be lost) and are received in the order in which they -were sent. Messages contain a fixed-size header and a variable amount -of typed data following the header. The header describes the -destination and size of the message. - - The IPC implementation makes use of the VM system to efficiently -transfer large amounts of data. The message body can contain the -address of a region in the sender's address space which should be -transferred as part of the message. When a task receives a message -containing an out-of-line region of data, the data appears in an unused -portion of the receiver's address space. This transmission of -out-of-line data is optimized so that sender and receiver share the -physical pages of data copy-on-write, and no actual data copy occurs -unless the pages are written. Regions of memory up to the size of a -full address space may be sent in this manner. - - Ports hold a queue of messages. Tasks operate on a port to send and -receive messages by exercising capabilities for the port. Multiple -tasks can hold send capabilities, or rights, for a port. Tasks can also -hold send-once rights, which grant the ability to send a single message. -Only one task can hold the receive capability, or receive right, for a -port. Port rights can be transferred between tasks via messages. The -sender of a message can specify in the message body that the message -contains a port right. If a message contains a receive right for a -port, then the receive right is removed from the sender of the message -and the right is transferred to the receiver of the message. While the -receive right is in transit, tasks holding send rights can still send -messages to the port, and they are queued until a task acquires the -receive right and uses it to receive the messages. - - Tasks can receive messages from ports and port sets. The port set -abstraction allows a single thread to wait for a message from any of -several ports. Tasks manipulate port sets with a capability, or -port-set right, which is taken from the same space as the port -capabilities. The port-set right may not be transferred in a message. -A port set holds receive rights, and a receive operation on a port set -blocks waiting for a message sent to any of the constituent ports. A -port may not belong to more than one port set, and if a port is a member -of a port set, the holder of the receive right can't receive directly -from the port. - - Port rights are a secure, location-independent way of naming ports. -The port queue is a protected data structure, only accessible via the -kernel's exported message primitives. Rights are also protected by the -kernel; there is no way for a malicious user task to guess a port name -and send a message to a port to which it shouldn't have access. Port -rights do not carry any location information. When a receive right for -a port moves from task to task, and even between tasks on different -machines, the send rights for the port remain unchanged and continue to -function. - - -File: mach.info, Node: Messaging Interface, Next: Port Manipulation Interface, Prev: Major Concepts, Up: Inter Process Communication - -4.2 Messaging Interface -======================= - -This section describes how messages are composed, sent and received -within the Mach IPC system. - -* Menu: - -* Mach Message Call:: Sending and receiving messages. -* Message Format:: The format of Mach messages. -* Exchanging Port Rights:: Sending and receiving port rights. -* Memory:: Passing memory regions in messages. -* Message Send:: Sending messages. -* Message Receive:: Receiving messages. -* Atomicity:: Atomicity of port rights. - - -File: mach.info, Node: Mach Message Call, Next: Message Format, Up: Messaging Interface - -4.2.1 Mach Message Call ------------------------ - -To use the `mach_msg' call, you can include the header files -`mach/port.h' and `mach/message.h'. - - -- Function: mach_msg_return_t mach_msg (mach_msg_header_t *MSG, - mach_msg_option_t OPTION, mach_msg_size_t SEND_SIZE, - mach_msg_size_t RCV_SIZE, mach_port_t RCV_NAME, - mach_msg_timeout_t TIMEOUT, mach_port_t NOTIFY) - The `mach_msg' function is used to send and receive messages. Mach - messages contain typed data, which can include port rights and - references to large regions of memory. - - MSG is the address of a buffer in the caller's address space. - Message buffers should be aligned on long-word boundaries. The - message options OPTION are bit values, combined with bitwise-or. - One or both of `MACH_SEND_MSG' and `MACH_RCV_MSG' should be used. - Other options act as modifiers. When sending a message, SEND_SIZE - specifies the size of the message buffer. Otherwise zero should be - supplied. When receiving a message, RCV_SIZE specifies the size - of the message buffer. Otherwise zero should be supplied. When - receiving a message, RCV_NAME specifies the port or port set. - Otherwise `MACH_PORT_NULL' should be supplied. When using the - `MACH_SEND_TIMEOUT' and `MACH_RCV_TIMEOUT' options, TIMEOUT - specifies the time in milliseconds to wait before giving up. - Otherwise `MACH_MSG_TIMEOUT_NONE' should be supplied. When using - the `MACH_SEND_NOTIFY', `MACH_SEND_CANCEL', and `MACH_RCV_NOTIFY' - options, NOTIFY specifies the port used for the notification. - Otherwise `MACH_PORT_NULL' should be supplied. - - If the option argument is `MACH_SEND_MSG', it sends a message. The - SEND_SIZE argument specifies the size of the message to send. The - `msgh_remote_port' field of the message header specifies the - destination of the message. - - If the option argument is `MACH_RCV_MSG', it receives a message. - The RCV_SIZE argument specifies the size of the message buffer - that will receive the message; messages larger than RCV_SIZE are - not received. The RCV_NAME argument specifies the port or port - set from which to receive. - - If the option argument is `MACH_SEND_MSG|MACH_RCV_MSG', then - `mach_msg' does both send and receive operations. If the send - operation encounters an error (any return code other than - `MACH_MSG_SUCCESS'), then the call returns immediately without - attempting the receive operation. Semantically the combined call - is equivalent to separate send and receive calls, but it saves a - system call and enables other internal optimizations. - - If the option argument specifies neither `MACH_SEND_MSG' nor - `MACH_RCV_MSG', then `mach_msg' does nothing. - - Some options, like `MACH_SEND_TIMEOUT' and `MACH_RCV_TIMEOUT', - share a supporting argument. If these options are used together, - they make independent use of the supporting argument's value. - - -- Data type: mach_msg_timeout_t - This is a `natural_t' used by the timeout mechanism. The units are - milliseconds. The value to be used when there is no timeout is - `MACH_MSG_TIMEOUT_NONE'. - - -File: mach.info, Node: Message Format, Next: Exchanging Port Rights, Prev: Mach Message Call, Up: Messaging Interface - -4.2.2 Message Format --------------------- - -A Mach message consists of a fixed size message header, a -`mach_msg_header_t', followed by zero or more data items. Data items -are typed. Each item has a type descriptor followed by the actual data -(or the address of the data, for out-of-line memory regions). - - The following data types are related to Mach ports: - - -- Data type: mach_port_t - The `mach_port_t' data type is an unsigned integer type which - represents a port name in the task's port name space. In GNU - Mach, this is an `unsigned int'. - - The following data types are related to Mach messages: - - -- Data type: mach_msg_bits_t - The `mach_msg_bits_t' data type is an `unsigned int' used to store - various flags for a message. - - -- Data type: mach_msg_size_t - The `mach_msg_size_t' data type is an `unsigned int' used to store - the size of a message. - - -- Data type: mach_msg_id_t - The `mach_msg_id_t' data type is an `integer_t' typically used to - convey a function or operation id for the receiver. - - -- Data type: mach_msg_header_t - This structure is the start of every message in the Mach IPC - system. It has the following members: - - `mach_msg_bits_t msgh_bits' - The `msgh_bits' field has the following bits defined, all - other bits should be zero: - - `MACH_MSGH_BITS_REMOTE_MASK' - `MACH_MSGH_BITS_LOCAL_MASK' - The remote and local bits encode `mach_msg_type_name_t' - values that specify the port rights in the - `msgh_remote_port' and `msgh_local_port' fields. The - remote value must specify a send or send-once right for - the destination of the message. If the local value - doesn't specify a send or send-once right for the - message's reply port, it must be zero and - msgh_local_port must be `MACH_PORT_NULL'. - - `MACH_MSGH_BITS_COMPLEX' - The complex bit must be specified if the message body - contains port rights or out-of-line memory regions. If - it is not specified, then the message body carries no - port rights or memory, no matter what the type - descriptors may seem to indicate. - - `MACH_MSGH_BITS_REMOTE' and `MACH_MSGH_BITS_LOCAL' macros - return the appropriate `mach_msg_type_name_t' values, given a - `msgh_bits' value. The `MACH_MSGH_BITS' macro constructs a - value for `msgh_bits', given two `mach_msg_type_name_t' - values. - - `mach_msg_size_t msgh_size' - The `msgh_size' field in the header of a received message - contains the message's size. The message size, a byte - quantity, includes the message header, type descriptors, and - in-line data. For out-of-line memory regions, the message - size includes the size of the in-line address, not the size - of the actual memory region. There are no arbitrary limits - on the size of a Mach message, the number of data items in a - message, or the size of the data items. - - `mach_port_t msgh_remote_port' - The `msgh_remote_port' field specifies the destination port - of the message. The field must carry a legitimate send or - send-once right for a port. - - `mach_port_t msgh_local_port' - The `msgh_local_port' field specifies an auxiliary port right, - which is conventionally used as a reply port by the recipient - of the message. The field must carry a send right, a - send-once right, `MACH_PORT_NULL', or `MACH_PORT_DEAD'. - - `mach_port_seqno_t msgh_seqno' - The `msgh_seqno' field provides a sequence number for the - message. It is only valid in received messages; its value in - sent messages is overwritten. - - `mach_msg_id_t msgh_id' - The `mach_msg' call doesn't use the `msgh_id' field, but it - conventionally conveys an operation or function id. - - -- Macro: mach_msg_bits_t MACH_MSGH_BITS (mach_msg_type_name_t REMOTE, - mach_msg_type_name_t LOCAL) - This macro composes two `mach_msg_type_name_t' values that specify - the port rights in the `msgh_remote_port' and `msgh_local_port' - fields of a `mach_msg' call into an appropriate `mach_msg_bits_t' - value. - - -- Macro: mach_msg_type_name_t MACH_MSGH_BITS_REMOTE - (mach_msg_bits_t BITS) - This macro extracts the `mach_msg_type_name_t' value for the remote - port right in a `mach_msg_bits_t' value. - - -- Macro: mach_msg_type_name_t MACH_MSGH_BITS_LOCAL - (mach_msg_bits_t BITS) - This macro extracts the `mach_msg_type_name_t' value for the local - port right in a `mach_msg_bits_t' value. - - -- Macro: mach_msg_bits_t MACH_MSGH_BITS_PORTS (mach_msg_bits_t BITS) - This macro extracts the `mach_msg_bits_t' component consisting of - the `mach_msg_type_name_t' values for the remote and local port - right in a `mach_msg_bits_t' value. - - -- Macro: mach_msg_bits_t MACH_MSGH_BITS_OTHER (mach_msg_bits_t BITS) - This macro extracts the `mach_msg_bits_t' component consisting of - everything except the `mach_msg_type_name_t' values for the remote - and local port right in a `mach_msg_bits_t' value. - - Each data item has a type descriptor, a `mach_msg_type_t' or a -`mach_msg_type_long_t'. The `mach_msg_type_long_t' type descriptor -allows larger values for some fields. The `msgtl_header' field in the -long descriptor is only used for its inline, longform, and deallocate -bits. - - -- Data type: mach_msg_type_name_t - This is an `unsigned int' and can be used to hold the `msgt_name' - component of the `mach_msg_type_t' and `mach_msg_type_long_t' - structure. - - -- Data type: mach_msg_type_size_t - This is an `unsigned int' and can be used to hold the `msgt_size' - component of the `mach_msg_type_t' and `mach_msg_type_long_t' - structure. - - -- Data type: mach_msg_type_number_t - This is an `natural_t' and can be used to hold the `msgt_number' - component of the `mach_msg_type_t' and `mach_msg_type_long_t' - structure. - - -- Data type: mach_msg_type_t - This structure has the following members: - - `unsigned int msgt_name : 8' - The `msgt_name' field specifies the data's type. The - following types are predefined: - - `MACH_MSG_TYPE_UNSTRUCTURED' - - `MACH_MSG_TYPE_BIT' - - `MACH_MSG_TYPE_BOOLEAN' - - `MACH_MSG_TYPE_INTEGER_16' - - `MACH_MSG_TYPE_INTEGER_32' - - `MACH_MSG_TYPE_CHAR' - - `MACH_MSG_TYPE_BYTE' - - `MACH_MSG_TYPE_INTEGER_8' - - `MACH_MSG_TYPE_REAL' - - `MACH_MSG_TYPE_STRING' - - `MACH_MSG_TYPE_STRING_C' - - `MACH_MSG_TYPE_PORT_NAME' - - The following predefined types specify port rights, and - receive special treatment. The next section discusses these - types in detail. The type `MACH_MSG_TYPE_PORT_NAME' - describes port right names, when no rights are being - transferred, but just names. For this purpose, it should be - used in preference to `MACH_MSG_TYPE_INTEGER_32'. - - `MACH_MSG_TYPE_MOVE_RECEIVE' - - `MACH_MSG_TYPE_MOVE_SEND' - - `MACH_MSG_TYPE_MOVE_SEND_ONCE' - - `MACH_MSG_TYPE_COPY_SEND' - - `MACH_MSG_TYPE_MAKE_SEND' - - `MACH_MSG_TYPE_MAKE_SEND_ONCE' - - `msgt_size : 8' - The `msgt_size' field specifies the size of each datum, in - bits. For example, the msgt_size of - `MACH_MSG_TYPE_INTEGER_32' data is 32. - - `msgt_number : 12' - The `msgt_number' field specifies how many data elements - comprise the data item. Zero is a legitimate number. - - The total length specified by a type descriptor is - `(msgt_size * msgt_number)', rounded up to an integral number - of bytes. In-line data is then padded to an integral number - of long-words. This ensures that type descriptors always - start on long-word boundaries. It implies that message sizes - are always an integral multiple of a long-word's size. - - `msgt_inline : 1' - The `msgt_inline' bit specifies, when `FALSE', that the data - actually resides in an out-of-line region. The address of - the memory region (a `vm_offset_t' or `vm_address_t') follows - the type descriptor in the message body. The `msgt_name', - `msgt_size', and `msgt_number' fields describe the memory - region, not the address. - - `msgt_longform : 1' - The `msgt_longform' bit specifies, when `TRUE', that this type - descriptor is a `mach_msg_type_long_t' instead of a - `mach_msg_type_t'. The `msgt_name', `msgt_size', and - `msgt_number' fields should be zero. Instead, `mach_msg' uses - the following `msgtl_name', `msgtl_size', and `msgtl_number' - fields. - - `msgt_deallocate : 1' - The `msgt_deallocate' bit is used with out-of-line regions. - When `TRUE', it specifies that the memory region should be - deallocated from the sender's address space (as if with - `vm_deallocate') when the message is sent. - - `msgt_unused : 1' - The `msgt_unused' bit should be zero. - - -- Macro: boolean_t MACH_MSG_TYPE_PORT_ANY (mach_msg_type_name_t type) - This macro returns `TRUE' if the given type name specifies a port - type, otherwise it returns `FALSE'. - - -- Macro: boolean_t MACH_MSG_TYPE_PORT_ANY_SEND (mach_msg_type_name_t - type) - This macro returns `TRUE' if the given type name specifies a port - type with a send or send-once right, otherwise it returns `FALSE'. - - -- Macro: boolean_t MACH_MSG_TYPE_PORT_ANY_RIGHT (mach_msg_type_name_t - type) - This macro returns `TRUE' if the given type name specifies a port - right type which is moved, otherwise it returns `FALSE'. - - -- Data type: mach_msg_type_long_t - This structure has the following members: - - `mach_msg_type_t msgtl_header' - Same meaning as `msgt_header'. - - `unsigned short msgtl_name' - Same meaning as `msgt_name'. - - `unsigned short msgtl_size' - Same meaning as `msgt_size'. - - `unsigned int msgtl_number' - Same meaning as `msgt_number'. - - -File: mach.info, Node: Exchanging Port Rights, Next: Memory, Prev: Message Format, Up: Messaging Interface - -4.2.3 Exchanging Port Rights ----------------------------- - -Each task has its own space of port rights. Port rights are named with -positive integers. Except for the reserved values -`MACH_PORT_NULL (0)'(1) and `MACH_PORT_DEAD (~0)', this is a full 32-bit -name space. When the kernel chooses a name for a new right, it is free -to pick any unused name (one which denotes no right) in the space. - - There are five basic kinds of rights: receive rights, send rights, -send-once rights, port-set rights, and dead names. Dead names are not -capabilities. They act as place-holders to prevent a name from being -otherwise used. - - A port is destroyed, or dies, when its receive right is deallocated. -When a port dies, send and send-once rights for the port turn into dead -names. Any messages queued at the port are destroyed, which deallocates -the port rights and out-of-line memory in the messages. - - Tasks may hold multiple user-references for send rights and dead -names. When a task receives a send right which it already holds, the -kernel increments the right's user-reference count. When a task -deallocates a send right, the kernel decrements its user-reference -count, and the task only loses the send right when the count goes to -zero. - - Send-once rights always have a user-reference count of one, although -a port can have multiple send-once rights, because each send-once right -held by a task has a different name. In contrast, when a task holds -send rights or a receive right for a port, the rights share a single -name. - - A message body can carry port rights; the `msgt_name' (`msgtl_name') -field in a type descriptor specifies the type of port right and how the -port right is to be extracted from the caller. The values -`MACH_PORT_NULL' and `MACH_PORT_DEAD' are always valid in place of a -port right in a message body. In a sent message, the following -`msgt_name' values denote port rights: - -`MACH_MSG_TYPE_MAKE_SEND' - The message will carry a send right, but the caller must supply a - receive right. The send right is created from the receive right, - and the receive right's make-send count is incremented. - -`MACH_MSG_TYPE_COPY_SEND' - The message will carry a send right, and the caller should supply - a send right. The user reference count for the supplied send - right is not changed. The caller may also supply a dead name and - the receiving task will get `MACH_PORT_DEAD'. - -`MACH_MSG_TYPE_MOVE_SEND' - The message will carry a send right, and the caller should supply - a send right. The user reference count for the supplied send - right is decremented, and the right is destroyed if the count - becomes zero. Unless a receive right remains, the name becomes - available for recycling. The caller may also supply a dead name, - which loses a user reference, and the receiving task will get - `MACH_PORT_DEAD'. - -`MACH_MSG_TYPE_MAKE_SEND_ONCE' - The message will carry a send-once right, but the caller must - supply a receive right. The send-once right is created from the - receive right. - -`MACH_MSG_TYPE_MOVE_SEND_ONCE' - The message will carry a send-once right, and the caller should - supply a send-once right. The caller loses the supplied send-once - right. The caller may also supply a dead name, which loses a user - reference, and the receiving task will get `MACH_PORT_DEAD'. - -`MACH_MSG_TYPE_MOVE_RECEIVE' - The message will carry a receive right, and the caller should - supply a receive right. The caller loses the supplied receive - right, but retains any send rights with the same name. - - If a message carries a send or send-once right, and the port dies -while the message is in transit, then the receiving task will get -`MACH_PORT_DEAD' instead of a right. The following `msgt_name' values -in a received message indicate that it carries port rights: - -`MACH_MSG_TYPE_PORT_SEND' - This name is an alias for `MACH_MSG_TYPE_MOVE_SEND'. The message - carried a send right. If the receiving task already has send - and/or receive rights for the port, then that name for the port - will be reused. Otherwise, the new right will have a new name. - If the task already has send rights, it gains a user reference for - the right (unless this would cause the user-reference count to - overflow). Otherwise, it acquires the send right, with a - user-reference count of one. - -`MACH_MSG_TYPE_PORT_SEND_ONCE' - This name is an alias for `MACH_MSG_TYPE_MOVE_SEND_ONCE'. The - message carried a send-once right. The right will have a new name. - -`MACH_MSG_TYPE_PORT_RECEIVE' - This name is an alias for `MACH_MSG_TYPE_MOVE_RECEIVE'. The - message carried a receive right. If the receiving task already - has send rights for the port, then that name for the port will be - reused. Otherwise, the right will have a new name. The make-send - count of the receive right is reset to zero, but the port retains - other attributes like queued messages, extant send and send-once - rights, and requests for port-destroyed and no-senders - notifications. - - When the kernel chooses a new name for a port right, it can choose -any name, other than `MACH_PORT_NULL' and `MACH_PORT_DEAD', which is -not currently being used for a port right or dead name. It might -choose a name which at some previous time denoted a port right, but is -currently unused. - - ---------- Footnotes ---------- - - (1) In the Hurd system, we don't make the assumption that -`MACH_PORT_NULL' is zero and evaluates to false, but rather compare -port names to `MACH_PORT_NULL' explicitely - - -File: mach.info, Node: Memory, Next: Message Send, Prev: Exchanging Port Rights, Up: Messaging Interface - -4.2.4 Memory ------------- - -A message body can contain the address of a region in the sender's -address space which should be transferred as part of the message. The -message carries a logical copy of the memory, but the kernel uses VM -techniques to defer any actual page copies. Unless the sender or the -receiver modifies the data, the physical pages remain shared. - - An out-of-line transfer occurs when the data's type descriptor -specifies `msgt_inline' as `FALSE'. The address of the memory region (a -`vm_offset_t' or `vm_address_t') should follow the type descriptor in -the message body. The type descriptor and the address contribute to -the message's size (`send_size', `msgh_size'). The out-of-line data -does not contribute to the message's size. - - The name, size, and number fields in the type descriptor describe the -type and length of the out-of-line data, not the in-line address. -Out-of-line memory frequently requires long type descriptors -(`mach_msg_type_long_t'), because the `msgt_number' field is too small -to describe a page of 4K bytes. - - Out-of-line memory arrives somewhere in the receiver's address space -as new memory. It has the same inheritance and protection attributes as -newly `vm_allocate''d memory. The receiver has the responsibility of -deallocating (with `vm_deallocate') the memory when it is no longer -needed. Security-conscious receivers should exercise caution when -using out-of-line memory from untrustworthy sources, because the memory -may be backed by an unreliable memory manager. - - Null out-of-line memory is legal. If the out-of-line region size is -zero (for example, because `msgtl_number' is zero), then the region's -specified address is ignored. A received null out-of-line memory -region always has a zero address. - - Unaligned addresses and region sizes that are not page multiples are -legal. A received message can also contain memory with unaligned -addresses and funny sizes. In the general case, the first and last -pages in the new memory region in the receiver do not contain only data -from the sender, but are partly zero.(1) The received address points -to the start of the data in the first page. This possibility doesn't -complicate deallocation, because `vm_deallocate' does the right thing, -rounding the start address down and the end address up to deallocate -all arrived pages. - - Out-of-line memory has a deallocate option, controlled by the -`msgt_deallocate' bit. If it is `TRUE' and the out-of-line memory -region is not null, then the region is implicitly deallocated from the -sender, as if by `vm_deallocate'. In particular, the start and end -addresses are rounded so that every page overlapped by the memory -region is deallocated. The use of `msgt_deallocate' effectively -changes the memory copy into a memory movement. In a received message, -`msgt_deallocate' is `TRUE' in type descriptors for out-of-line memory. - - Out-of-line memory can carry port rights. - - ---------- Footnotes ---------- - - (1) Sending out-of-line memory with a non-page-aligned address, or a -size which is not a page multiple, works but with a caveat. The extra -bytes in the first and last page of the received memory are not zeroed, -so the receiver can peek at more data than the sender intended to -transfer. This might be a security problem for the sender. - - -File: mach.info, Node: Message Send, Next: Message Receive, Prev: Memory, Up: Messaging Interface - -4.2.5 Message Send ------------------- - -The send operation queues a message to a port. The message carries a -copy of the caller's data. After the send, the caller can freely modify -the message buffer or the out-of-line memory regions and the message -contents will remain unchanged. - - Message delivery is reliable and sequenced. Messages are not lost, -and messages sent to a port, from a single thread, are received in the -order in which they were sent. - - If the destination port's queue is full, then several things can -happen. If the message is sent to a send-once right (`msgh_remote_port' -carries a send-once right), then the kernel ignores the queue limit and -delivers the message. Otherwise the caller blocks until there is room -in the queue, unless the `MACH_SEND_TIMEOUT' or `MACH_SEND_NOTIFY' -options are used. If a port has several blocked senders, then any of -them may queue the next message when space in the queue becomes -available, with the proviso that a blocked sender will not be -indefinitely starved. - - These options modify `MACH_SEND_MSG'. If `MACH_SEND_MSG' is not -also specified, they are ignored. - -`MACH_SEND_TIMEOUT' - The timeout argument should specify a maximum time (in - milliseconds) for the call to block before giving up.(1) If the - message can't be queued before the timeout interval elapses, then - the call returns `MACH_SEND_TIMED_OUT'. A zero timeout is - legitimate. - -`MACH_SEND_NOTIFY' - The notify argument should specify a receive right for a notify - port. If the send were to block, then instead the message is - queued, `MACH_SEND_WILL_NOTIFY' is returned, and a msg-accepted - notification is requested. If `MACH_SEND_TIMEOUT' is also - specified, then `MACH_SEND_NOTIFY' doesn't take effect until the - timeout interval elapses. - - With `MACH_SEND_NOTIFY', a task can forcibly queue to a send right - one message at a time. A msg-accepted notification is sent to the - the notify port when another message can be forcibly queued. If - an attempt is made to use `MACH_SEND_NOTIFY' before then, the call - returns a `MACH_SEND_NOTIFY_IN_PROGRESS' error. - - The msg-accepted notification carries the name of the send right. - If the send right is deallocated before the msg-accepted - notification is generated, then the msg-accepted notification - carries the value `MACH_PORT_NULL'. If the destination port is - destroyed before the notification is generated, then a send-once - notification is generated instead. - -`MACH_SEND_INTERRUPT' - If specified, the `mach_msg' call will return - `MACH_SEND_INTERRUPTED' if a software interrupt aborts the call. - Otherwise, the send operation will be retried. - -`MACH_SEND_CANCEL' - The notify argument should specify a receive right for a notify - port. If the send operation removes the destination port right - from the caller, and the removed right had a dead-name request - registered for it, and notify is the notify port for the dead-name - request, then the dead-name request may be silently canceled - (instead of resulting in a port-deleted notification). - - This option is typically used to cancel a dead-name request made - with the `MACH_RCV_NOTIFY' option. It should only be used as an - optimization. - - The send operation can generate the following return codes. These -return codes imply that the call did nothing: - -`MACH_SEND_MSG_TOO_SMALL' - The specified send_size was smaller than the minimum size for a - message. - -`MACH_SEND_NO_BUFFER' - A resource shortage prevented the kernel from allocating a message - buffer. - -`MACH_SEND_INVALID_DATA' - The supplied message buffer was not readable. - -`MACH_SEND_INVALID_HEADER' - The `msgh_bits' value was invalid. - -`MACH_SEND_INVALID_DEST' - The `msgh_remote_port' value was invalid. - -`MACH_SEND_INVALID_REPLY' - The `msgh_local_port' value was invalid. - -`MACH_SEND_INVALID_NOTIFY' - When using `MACH_SEND_CANCEL', the notify argument did not denote a - valid receive right. - - These return codes imply that some or all of the message was -destroyed: - -`MACH_SEND_INVALID_MEMORY' - The message body specified out-of-line data that was not readable. - -`MACH_SEND_INVALID_RIGHT' - The message body specified a port right which the caller didn't - possess. - -`MACH_SEND_INVALID_TYPE' - A type descriptor was invalid. - -`MACH_SEND_MSG_TOO_SMALL' - The last data item in the message ran over the end of the message. - - These return codes imply that the message was returned to the caller -with a pseudo-receive operation: - -`MACH_SEND_TIMED_OUT' - The timeout interval expired. - -`MACH_SEND_INTERRUPTED' - A software interrupt occurred. - -`MACH_SEND_INVALID_NOTIFY' - When using `MACH_SEND_NOTIFY', the notify argument did not denote a - valid receive right. - -`MACH_SEND_NO_NOTIFY' - A resource shortage prevented the kernel from setting up a - msg-accepted notification. - -`MACH_SEND_NOTIFY_IN_PROGRESS' - A msg-accepted notification was already requested, and hasn't yet - been generated. - - These return codes imply that the message was queued: - -`MACH_SEND_WILL_NOTIFY' - The message was forcibly queued, and a msg-accepted notification - was requested. - -`MACH_MSG_SUCCESS' - The message was queued. - - Some return codes, like `MACH_SEND_TIMED_OUT', imply that the -message was almost sent, but could not be queued. In these situations, -the kernel tries to return the message contents to the caller with a -pseudo-receive operation. This prevents the loss of port rights or -memory which only exist in the message. For example, a receive right -which was moved into the message, or out-of-line memory sent with the -deallocate bit. - - The pseudo-receive operation is very similar to a normal receive -operation. The pseudo-receive handles the port rights in the message -header as if they were in the message body. They are not reversed. -After the pseudo-receive, the message is ready to be resent. If the -message is not resent, note that out-of-line memory regions may have -moved and some port rights may have changed names. - - The pseudo-receive operation may encounter resource shortages. This -is similar to a `MACH_RCV_BODY_ERROR' return code from a receive -operation. When this happens, the normal send return codes are -augmented with the `MACH_MSG_IPC_SPACE', `MACH_MSG_VM_SPACE', -`MACH_MSG_IPC_KERNEL', and `MACH_MSG_VM_KERNEL' bits to indicate the -nature of the resource shortage. - - The queueing of a message carrying receive rights may create a -circular loop of receive rights and messages, which can never be -received. For example, a message carrying a receive right can be sent -to that receive right. This situation is not an error, but the kernel -will garbage-collect such loops, destroying the messages and ports -involved. - - ---------- Footnotes ---------- - - (1) If MACH_SEND_TIMEOUT is used without MACH_SEND_INTERRUPT, then -the timeout duration might not be accurate. When the call is -interrupted and automatically retried, the original timeout is used. -If interrupts occur frequently enough, the timeout interval might never -expire. - - -File: mach.info, Node: Message Receive, Next: Atomicity, Prev: Message Send, Up: Messaging Interface - -4.2.6 Message Receive ---------------------- - -The receive operation dequeues a message from a port. The receiving -task acquires the port rights and out-of-line memory regions carried in -the message. - - The `rcv_name' argument specifies a port or port set from which to -receive. If a port is specified, the caller must possess the receive -right for the port and the port must not be a member of a port set. If -no message is present, then the call blocks, subject to the -`MACH_RCV_TIMEOUT' option. - - If a port set is specified, the call will receive a message sent to -any of the member ports. It is permissible for the port set to have no -member ports, and ports may be added and removed while a receive from -the port set is in progress. The received message can come from any of -the member ports which have messages, with the proviso that a member -port with messages will not be indefinitely starved. The -`msgh_local_port' field in the received message header specifies from -which port in the port set the message came. - - The `rcv_size' argument specifies the size of the caller's message -buffer. The `mach_msg' call will not receive a message larger than -`rcv_size'. Messages that are too large are destroyed, unless the -`MACH_RCV_LARGE' option is used. - - The destination and reply ports are reversed in a received message -header. The `msgh_local_port' field names the destination port, from -which the message was received, and the `msgh_remote_port' field names -the reply port right. The bits in `msgh_bits' are also reversed. The -`MACH_MSGH_BITS_LOCAL' bits have the value `MACH_MSG_TYPE_PORT_SEND' if -the message was sent to a send right, and the value -`MACH_MSG_TYPE_PORT_SEND_ONCE' if was sent to a send-once right. The -`MACH_MSGH_BITS_REMOTE' bits describe the reply port right. - - A received message can contain port rights and out-of-line memory. -The `msgh_local_port' field does not receive a port right; the act of -receiving the message destroys the send or send-once right for the -destination port. The msgh_remote_port field does name a received port -right, the reply port right, and the message body can carry port rights -and memory if `MACH_MSGH_BITS_COMPLEX' is present in msgh_bits. -Received port rights and memory should be consumed or deallocated in -some fashion. - - In almost all cases, `msgh_local_port' will specify the name of a -receive right, either `rcv_name' or if `rcv_name' is a port set, a -member of `rcv_name'. If other threads are concurrently manipulating -the receive right, the situation is more complicated. If the receive -right is renamed during the call, then `msgh_local_port' specifies the -right's new name. If the caller loses the receive right after the -message was dequeued from it, then `mach_msg' will proceed instead of -returning `MACH_RCV_PORT_DIED'. If the receive right was destroyed, -then `msgh_local_port' specifies `MACH_PORT_DEAD'. If the receive -right still exists, but isn't held by the caller, then -`msgh_local_port' specifies `MACH_PORT_NULL'. - - Received messages are stamped with a sequence number, taken from the -port from which the message was received. (Messages received from a -port set are stamped with a sequence number from the appropriate member -port.) Newly created ports start with a zero sequence number, and the -sequence number is reset to zero whenever the port's receive right moves -between tasks. When a message is dequeued from the port, it is stamped -with the port's sequence number and the port's sequence number is then -incremented. The dequeue and increment operations are atomic, so that -multiple threads receiving messages from a port can use the -`msgh_seqno' field to reconstruct the original order of the messages. - - These options modify `MACH_RCV_MSG'. If `MACH_RCV_MSG' is not also -specified, they are ignored. - -`MACH_RCV_TIMEOUT' - The timeout argument should specify a maximum time (in - milliseconds) for the call to block before giving up.(1) If no - message arrives before the timeout interval elapses, then the call - returns `MACH_RCV_TIMED_OUT'. A zero timeout is legitimate. - -`MACH_RCV_NOTIFY' - The notify argument should specify a receive right for a notify - port. If receiving the reply port creates a new port right in the - caller, then the notify port is used to request a dead-name - notification for the new port right. - -`MACH_RCV_INTERRUPT' - If specified, the `mach_msg' call will return - `MACH_RCV_INTERRUPTED' if a software interrupt aborts the call. - Otherwise, the receive operation will be retried. - -`MACH_RCV_LARGE' - If the message is larger than `rcv_size', then the message remains - queued instead of being destroyed. The call returns - `MACH_RCV_TOO_LARGE' and the actual size of the message is returned - in the `msgh_size' field of the message header. - - The receive operation can generate the following return codes. These -return codes imply that the call did not dequeue a message: - -`MACH_RCV_INVALID_NAME' - The specified `rcv_name' was invalid. - -`MACH_RCV_IN_SET' - The specified port was a member of a port set. - -`MACH_RCV_TIMED_OUT' - The timeout interval expired. - -`MACH_RCV_INTERRUPTED' - A software interrupt occurred. - -`MACH_RCV_PORT_DIED' - The caller lost the rights specified by `rcv_name'. - -`MACH_RCV_PORT_CHANGED' - `rcv_name' specified a receive right which was moved into a port - set during the call. - -`MACH_RCV_TOO_LARGE' - When using `MACH_RCV_LARGE', and the message was larger than - `rcv_size'. The message is left queued, and its actual size is - returned in the `msgh_size' field of the message buffer. - - These return codes imply that a message was dequeued and destroyed: - -`MACH_RCV_HEADER_ERROR' - A resource shortage prevented the reception of the port rights in - the message header. - -`MACH_RCV_INVALID_NOTIFY' - When using `MACH_RCV_NOTIFY', the notify argument did not denote a - valid receive right. - -`MACH_RCV_TOO_LARGE' - When not using `MACH_RCV_LARGE', a message larger than `rcv_size' - was dequeued and destroyed. - - In these situations, when a message is dequeued and then destroyed, -the reply port and all port rights and memory in the message body are -destroyed. However, the caller receives the message's header, with all -fields correct, including the destination port but excepting the reply -port, which is `MACH_PORT_NULL'. - - These return codes imply that a message was received: - -`MACH_RCV_BODY_ERROR' - A resource shortage prevented the reception of a port right or - out-of-line memory region in the message body. The message header, - including the reply port, is correct. The kernel attempts to - transfer all port rights and memory regions in the body, and only - destroys those that can't be transferred. - -`MACH_RCV_INVALID_DATA' - The specified message buffer was not writable. The calling task - did successfully receive the port rights and out-of-line memory - regions in the message. - -`MACH_MSG_SUCCESS' - A message was received. - - Resource shortages can occur after a message is dequeued, while -transferring port rights and out-of-line memory regions to the receiving -task. The `mach_msg' call returns `MACH_RCV_HEADER_ERROR' or -`MACH_RCV_BODY_ERROR' in this situation. These return codes always -carry extra bits (bitwise-ored) that indicate the nature of the resource -shortage: - -`MACH_MSG_IPC_SPACE' - There was no room in the task's IPC name space for another port - name. - -`MACH_MSG_VM_SPACE' - There was no room in the task's VM address space for an out-of-line - memory region. - -`MACH_MSG_IPC_KERNEL' - A kernel resource shortage prevented the reception of a port right. - -`MACH_MSG_VM_KERNEL' - A kernel resource shortage prevented the reception of an - out-of-line memory region. - - If a resource shortage prevents the reception of a port right, the -port right is destroyed and the caller sees the name `MACH_PORT_NULL'. -If a resource shortage prevents the reception of an out-of-line memory -region, the region is destroyed and the caller receives a zero address. -In addition, the `msgt_size' (`msgtl_size') field in the data's type -descriptor is changed to zero. If a resource shortage prevents the -reception of out-of-line memory carrying port rights, then the port -rights are always destroyed if the memory region can not be received. -A task never receives port rights or memory regions that it isn't told -about. - - ---------- Footnotes ---------- - - (1) If MACH_RCV_TIMEOUT is used without MACH_RCV_INTERRUPT, then the -timeout duration might not be accurate. When the call is interrupted -and automatically retried, the original timeout is used. If interrupts -occur frequently enough, the timeout interval might never expire. - - -File: mach.info, Node: Atomicity, Prev: Message Receive, Up: Messaging Interface - -4.2.7 Atomicity ---------------- - -The `mach_msg' call handles port rights in a message header atomically. -Port rights and out-of-line memory in a message body do not enjoy this -atomicity guarantee. The message body may be processed front-to-back, -back-to-front, first out-of-line memory then port rights, in some -random order, or even atomically. - - For example, consider sending a message with the destination port -specified as `MACH_MSG_TYPE_MOVE_SEND' and the reply port specified as -`MACH_MSG_TYPE_COPY_SEND'. The same send right, with one -user-reference, is supplied for both the `msgh_remote_port' and -`msgh_local_port' fields. Because `mach_msg' processes the message -header atomically, this succeeds. If `msgh_remote_port' were processed -before `msgh_local_port', then `mach_msg' would return -`MACH_SEND_INVALID_REPLY' in this situation. - - On the other hand, suppose the destination and reply port are both -specified as `MACH_MSG_TYPE_MOVE_SEND', and again the same send right -with one user-reference is supplied for both. Now the send operation -fails, but because it processes the header atomically, mach_msg can -return either `MACH_SEND_INVALID_DEST' or `MACH_SEND_INVALID_REPLY'. - - For example, consider receiving a message at the same time another -thread is deallocating the destination receive right. Suppose the reply -port field carries a send right for the destination port. If the -deallocation happens before the dequeuing, then the receiver gets -`MACH_RCV_PORT_DIED'. If the deallocation happens after the receive, -then the `msgh_local_port' and the `msgh_remote_port' fields both -specify the same right, which becomes a dead name when the receive -right is deallocated. If the deallocation happens between the dequeue -and the receive, then the `msgh_local_port' and `msgh_remote_port' -fields both specify `MACH_PORT_DEAD'. Because the header is processed -atomically, it is not possible for just one of the two fields to hold -`MACH_PORT_DEAD'. - - The `MACH_RCV_NOTIFY' option provides a more likely example. -Suppose a message carrying a send-once right reply port is received with -`MACH_RCV_NOTIFY' at the same time the reply port is destroyed. If the -reply port is destroyed first, then `msgh_remote_port' specifies -`MACH_PORT_DEAD' and the kernel does not generate a dead-name -notification. If the reply port is destroyed after it is received, -then `msgh_remote_port' specifies a dead name for which the kernel -generates a dead-name notification. It is not possible to receive the -reply port right and have it turn into a dead name before the dead-name -notification is requested; as part of the message header the reply port -is received atomically. - - -File: mach.info, Node: Port Manipulation Interface, Prev: Messaging Interface, Up: Inter Process Communication - -4.3 Port Manipulation Interface -=============================== - -This section describes the interface to create, destroy and manipulate -ports, port rights and port sets. - - -- Data type: ipc_space_t - This is a `task_t' (and as such a `mach_port_t'), which holds a - port name associated with a port that represents an IPC space in - the kernel. An IPC space is used by the kernel to manage the port - names and rights available to a task. The IPC space doesn't get a - port name of its own. Instead the port name of the task - containing the IPC space is used to name the IPC space of the task - (as is indicated by the fact that the type of `ipc_space_t' is - actually `task_t'). - - The IPC spaces of tasks are the only ones accessible outside of - the kernel. - -* Menu: - -* Port Creation:: How to create new ports and port sets. -* Port Destruction:: How to destroy ports and port sets. -* Port Names:: How to query and manipulate port names. -* Port Rights:: How to work with port rights. -* Ports and other Tasks:: How to move rights between tasks. -* Receive Rights:: How to work with receive rights. -* Port Sets:: How to work with port sets. -* Request Notifications:: How to request notifications for events. - - -File: mach.info, Node: Port Creation, Next: Port Destruction, Up: Port Manipulation Interface - -4.3.1 Port Creation -------------------- - - -- Function: kern_return_t mach_port_allocate (ipc_space_t TASK, - mach_port_right_t RIGHT, mach_port_t *NAME) - The `mach_port_allocate' function creates a new right in the - specified task. The new right's name is returned in NAME, which - may be any name that wasn't in use. - - The RIGHT argument takes the following values: - - `MACH_PORT_RIGHT_RECEIVE' - `mach_port_allocate' creates a port. The new port is not a - member of any port set. It doesn't have any extant send or - send-once rights. Its make-send count is zero, its sequence - number is zero, its queue limit is - `MACH_PORT_QLIMIT_DEFAULT', and it has no queued messages. - NAME denotes the receive right for the new port. - - TASK does not hold send rights for the new port, only the - receive right. `mach_port_insert_right' and - `mach_port_extract_right' can be used to convert the receive - right into a combined send/receive right. - - `MACH_PORT_RIGHT_PORT_SET' - `mach_port_allocate' creates a port set. The new port set - has no members. - - `MACH_PORT_RIGHT_DEAD_NAME' - `mach_port_allocate' creates a dead name. The new dead name - has one user reference. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if - RIGHT was invalid, `KERN_NO_SPACE' if there was no room in TASK's - IPC name space for another right and `KERN_RESOURCE_SHORTAGE' if - the kernel ran out of memory. - - The `mach_port_allocate' call is actually an RPC to TASK, normally - a send right for a task port, but potentially any send right. In - addition to the normal diagnostic return codes from the call's - server (normally the kernel), the call may return `mach_msg' - return codes. - - -- Function: mach_port_t mach_reply_port () - The `mach_reply_port' system call creates a reply port in the - calling task. - - `mach_reply_port' creates a port, giving the calling task the - receive right for the port. The call returns the name of the new - receive right. - - This is very much like creating a receive right with the - `mach_port_allocate' call, with two differences. First, - `mach_reply_port' is a system call and not an RPC (which requires a - reply port). Second, the port created by `mach_reply_port' may be - optimized for use as a reply port. - - The function returns `MACH_PORT_NULL' if a resource shortage - prevented the creation of the receive right. - - -- Function: kern_return_t mach_port_allocate_name (ipc_space_t TASK, - mach_port_right_t RIGHT, mach_port_t NAME) - The function `mach_port_allocate_name' creates a new right in the - specified task, with a specified name for the new right. NAME - must not already be in use for some right, and it can't be the - reserved values `MACH_PORT_NULL' and `MACH_PORT_DEAD'. - - The RIGHT argument takes the following values: - - `MACH_PORT_RIGHT_RECEIVE' - `mach_port_allocate_name' creates a port. The new port is - not a member of any port set. It doesn't have any extant - send or send-once rights. Its make-send count is zero, its - sequence number is zero, its queue limit is - `MACH_PORT_QLIMIT_DEFAULT', and it has no queued messages. - NAME denotes the receive right for the new port. - - TASK does not hold send rights for the new port, only the - receive right. `mach_port_insert_right' and - `mach_port_extract_right' can be used to convert the receive - right into a combined send/receive right. - - `MACH_PORT_RIGHT_PORT_SET' - `mach_port_allocate_name' creates a port set. The new port - set has no members. - - `MACH_PORT_RIGHT_DEAD_NAME' - `mach_port_allocate_name' creates a new dead name. The new - dead name has one user reference. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if - RIGHT was invalid or NAME was `MACH_PORT_NULL' or - `MACH_PORT_DEAD', `KERN_NAME_EXISTS' if NAME was already in use - for a port right and `KERN_RESOURCE_SHORTAGE' if the kernel ran - out of memory. - - The `mach_port_allocate_name' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return `mach_msg' - return codes. - - -File: mach.info, Node: Port Destruction, Next: Port Names, Prev: Port Creation, Up: Port Manipulation Interface - -4.3.2 Port Destruction ----------------------- - - -- Function: kern_return_t mach_port_deallocate (ipc_space_t TASK, - mach_port_t NAME) - The function `mach_port_deallocate' releases a user reference for a - right in TASK's IPC name space. It allows a task to release a - user reference for a send or send-once right without failing if - the port has died and the right is now actually a dead name. - - If NAME denotes a dead name, send right, or send-once right, then - the right loses one user reference. If it only had one user - reference, then the right is destroyed. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - NAME did not denote a right and `KERN_INVALID_RIGHT' if NAME - denoted an invalid right. - - The `mach_port_deallocate' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return `mach_msg' - return codes. - - -- Function: kern_return_t mach_port_destroy (ipc_space_t TASK, - mach_port_t NAME) - The function `mach_port_destroy' deallocates all rights denoted by - a name. The name becomes immediately available for reuse. - - For most purposes, `mach_port_mod_refs' and `mach_port_deallocate' - are preferable. - - If NAME denotes a port set, then all members of the port set are - implicitly removed from the port set. - - If NAME denotes a receive right that is a member of a port set, - the receive right is implicitly removed from the port set. If - there is a port-destroyed request registered for the port, then - the receive right is not actually destroyed, but instead is sent - in a port-destroyed notification to the backup port. If there is - no registered port-destroyed request, remaining messages queued to - the port are destroyed and extant send and send-once rights turn - into dead names. If those send and send-once rights have - dead-name requests registered, then dead-name notifications are - generated for them. - - If NAME denotes a send-once right, then the send-once right is - used to produce a send-once notification for the port. - - If NAME denotes a send-once, send, and/or receive right, and it - has a dead-name request registered, then the registered send-once - right is used to produce a port-deleted notification for the name. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - NAME did not denote a right. - - The `mach_port_destroy' call is actually an RPC to TASK, normally - a send right for a task port, but potentially any send right. In - addition to the normal diagnostic return codes from the call's - server (normally the kernel), the call may return `mach_msg' - return codes. - - -File: mach.info, Node: Port Names, Next: Port Rights, Prev: Port Destruction, Up: Port Manipulation Interface - -4.3.3 Port Names ----------------- - - -- Function: kern_return_t mach_port_names (ipc_space_t TASK, - mach_port_array_t *NAMES, mach_msg_type_number_t *NCOUNT, - mach_port_type_array_t *TYPES, mach_msg_type_number_t *TCOUNT) - The function `mach_port_names' returns information about TASK's - port name space. For each name, it also returns what type of - rights TASK holds. (The same information returned by - `mach_port_type'.) NAMES and TYPES are arrays that are - automatically allocated when the reply message is received. The - user should `vm_deallocate' them when the data is no longer needed. - - `mach_port_names' will return in NAMES the names of the ports, - port sets, and dead names in the task's port name space, in no - particular order and in NCOUNT the number of names returned. It - will return in TYPES the type of each corresponding name, which - indicates what kind of rights the task holds with that name. - TCOUNT should be the same as NCOUNT. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_RESOURCE_SHORTAGE' - if the kernel ran out of memory. - - The `mach_port_names' call is actually an RPC to TASK, normally a - send right for a task port, but potentially any send right. In - addition to the normal diagnostic return codes from the call's - server (normally the kernel), the call may return `mach_msg' - return codes. - - -- Function: kern_return_t mach_port_type (ipc_space_t TASK, - mach_port_t NAME, mach_port_type_t *PTYPE) - The function `mach_port_type' returns information about TASK's - rights for a specific name in its port name space. The returned - PTYPE is a bitmask indicating what rights TASK holds for the port, - port set or dead name. The bitmask is composed of the following - bits: - - `MACH_PORT_TYPE_SEND' - The name denotes a send right. - - `MACH_PORT_TYPE_RECEIVE' - The name denotes a receive right. - - `MACH_PORT_TYPE_SEND_ONCE' - The name denotes a send-once right. - - `MACH_PORT_TYPE_PORT_SET' - The name denotes a port set. - - `MACH_PORT_TYPE_DEAD_NAME' - The name is a dead name. - - `MACH_PORT_TYPE_DNREQUEST' - A dead-name request has been registered for the right. - - `MACH_PORT_TYPE_MAREQUEST' - A msg-accepted request for the right is pending. - - `MACH_PORT_TYPE_COMPAT' - The port right was created in the compatibility mode. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid and `KERN_INVALID_NAME' if - NAME did not denote a right. - - The `mach_port_type' call is actually an RPC to TASK, normally a - send right for a task port, but potentially any send right. In - addition to the normal diagnostic return codes from the call's - server (normally the kernel), the call may return `mach_msg' - return codes. - - -- Function: kern_return_t mach_port_rename (ipc_space_t TASK, - mach_port_t OLD_NAME, mach_port_t NEW_NAME) - The function `mach_port_rename' changes the name by which a port, - port set, or dead name is known to TASK. OLD_NAME is the original - name and NEW_NAME the new name for the port right. NEW_NAME must - not already be in use, and it can't be the distinguished values - `MACH_PORT_NULL' and `MACH_PORT_DEAD'. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - OLD_NAME did not denote a right, `KERN_INVALID_VALUE' if NEW_NAME - was `MACH_PORT_NULL' or `MACH_PORT_DEAD', `KERN_NAME_EXISTS' if - `new_name' already denoted a right and `KERN_RESOURCE_SHORTAGE' if - the kernel ran out of memory. - - The `mach_port_rename' call is actually an RPC to TASK, normally a - send right for a task port, but potentially any send right. In - addition to the normal diagnostic return codes from the call's - server (normally the kernel), the call may return `mach_msg' - return codes. - - -File: mach.info, Node: Port Rights, Next: Ports and other Tasks, Prev: Port Names, Up: Port Manipulation Interface - -4.3.4 Port Rights ------------------ - - -- Function: kern_return_t mach_port_get_refs (ipc_space_t TASK, - mach_port_t NAME, mach_port_right_t RIGHT, - mach_port_urefs_t *REFS) - The function `mach_port_get_refs' returns the number of user - references a task has for a right. - - The RIGHT argument takes the following values: - * `MACH_PORT_RIGHT_SEND' - - * `MACH_PORT_RIGHT_RECEIVE' - - * `MACH_PORT_RIGHT_SEND_ONCE' - - * `MACH_PORT_RIGHT_PORT_SET' - - * `MACH_PORT_RIGHT_DEAD_NAME' - - If NAME denotes a right, but not the type of right specified, then - zero is returned. Otherwise a positive number of user references - is returned. Note that a name may simultaneously denote send and - receive rights. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if - RIGHT was invalid and `KERN_INVALID_NAME' if NAME did not denote a - right. - - The `mach_port_get_refs' call is actually an RPC to TASK, normally - a send right for a task port, but potentially any send right. In - addition to the normal diagnostic return codes from the call's - server (normally the kernel), the call may return `mach_msg' - return codes. - - -- Function: kern_return_t mach_port_mod_refs (ipc_space_t TASK, - mach_port_t NAME, mach_port_right_t RIGHT, - mach_port_delta_t DELTA) - The function `mach_port_mod_refs' requests that the number of user - references a task has for a right be changed. This results in the - right being destroyed, if the number of user references is changed - to zero. The task holding the right is TASK, NAME should denote - the specified right. RIGHT denotes the type of right being - modified. DELTA is the signed change to the number of user - references. - - The RIGHT argument takes the following values: - * `MACH_PORT_RIGHT_SEND' - - * `MACH_PORT_RIGHT_RECEIVE' - - * `MACH_PORT_RIGHT_SEND_ONCE' - - * `MACH_PORT_RIGHT_PORT_SET' - - * `MACH_PORT_RIGHT_DEAD_NAME' - - The number of user references for the right is changed by the - amount DELTA, subject to the following restrictions: port sets, - receive rights, and send-once rights may only have one user - reference. The resulting number of user references can't be - negative. If the resulting number of user references is zero, the - effect is to deallocate the right. For dead names and send - rights, there is an implementation-defined maximum number of user - references. - - If the call destroys the right, then the effect is as described for - `mach_port_destroy', with the exception that `mach_port_destroy' - simultaneously destroys all the rights denoted by a name, while - `mach_port_mod_refs' can only destroy one right. The name will be - available for reuse if it only denoted the one right. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if - RIGHT was invalid or the user-reference count would become - negative, `KERN_INVALID_NAME' if NAME did not denote a right, - `KERN_INVALID_RIGHT' if NAME denoted a right, but not the - specified right and `KERN_UREFS_OVERFLOW' if the user-reference - count would overflow. - - The `mach_port_mod_refs' call is actually an RPC to TASK, normally - a send right for a task port, but potentially any send right. In - addition to the normal diagnostic return codes from the call's - server (normally the kernel), the call may return `mach_msg' - return codes. - - -File: mach.info, Node: Ports and other Tasks, Next: Receive Rights, Prev: Port Rights, Up: Port Manipulation Interface - -4.3.5 Ports and other Tasks ---------------------------- - - -- Function: kern_return_t mach_port_insert_right (ipc_space_t TASK, - mach_port_t NAME, mach_port_t RIGHT, - mach_msg_type_name_t RIGHT_TYPE) - The function MACH_PORT_INSERT_RIGHT inserts into TASK the caller's - right for a port, using a specified name for the right in the - target task. - - The specified NAME can't be one of the reserved values - `MACH_PORT_NULL' or `MACH_PORT_DEAD'. The RIGHT can't be - `MACH_PORT_NULL' or `MACH_PORT_DEAD'. - - The argument RIGHT_TYPE specifies a right to be inserted and how - that right should be extracted from the caller. It should be a - value appropriate for MSGT_NAME; see `mach_msg'. If RIGHT_TYPE is - `MACH_MSG_TYPE_MAKE_SEND', `MACH_MSG_TYPE_MOVE_SEND', or - `MACH_MSG_TYPE_COPY_SEND', then a send right is inserted. If the - target already holds send or receive rights for the port, then - NAME should denote those rights in the target. Otherwise, NAME - should be unused in the target. If the target already has send - rights, then those send rights gain an additional user reference. - Otherwise, the target gains a send right, with a user reference - count of one. - - If RIGHT_TYPE is `MACH_MSG_TYPE_MAKE_SEND_ONCE' or - `MACH_MSG_TYPE_MOVE_SEND_ONCE', then a send-once right is inserted. - The name should be unused in the target. The target gains a - send-once right. - - If RIGHT_TYPE is `MACH_MSG_TYPE_MOVE_RECEIVE', then a receive - right is inserted. If the target already holds send rights for the - port, then name should denote those rights in the target. - Otherwise, name should be unused in the target. The receive right - is moved into the target task. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if - RIGHT was not a port right or NAME was `MACH_PORT_NULL' or - `MACH_PORT_DEAD', `KERN_NAME_EXISTS' if NAME already denoted a - right, `KERN_INVALID_CAPABILITY' if RIGHT was `MACH_PORT_NULL' or - `MACH_PORT_DEAD' `KERN_RIGHT_EXISTS' if TASK already had rights - for the port, with a different name, `KERN_UREFS_OVERFLOW' if the - user-reference count would overflow and `KERN_RESOURCE_SHORTAGE' - if the kernel ran out of memory. - - The `mach_port_insert_right' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return - `mach_msg' return codes. - - -- Function: kern_return_t mach_port_extract_right (ipc_space_t TASK, - mach_port_t NAME, mach_msg_type_name_t DESIRED_TYPE, - mach_port_t *RIGHT, mach_msg_type_name_t *ACQUIRED_TYPE) - The function MACH_PORT_EXTRACT_RIGHT extracts a port right from - the target TASK and returns it to the caller as if the task sent - the right voluntarily, using DESIRED_TYPE as the value of - MSGT_NAME. *Note Mach Message Call::. - - The returned value of ACQUIRED_TYPE will be - `MACH_MSG_TYPE_PORT_SEND' if a send right is extracted, - `MACH_MSG_TYPE_PORT_RECEIVE' if a receive right is extracted, and - `MACH_MSG_TYPE_PORT_SEND_ONCE' if a send-once right is extracted. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - NAME did not denote a right, `KERN_INVALID_RIGHT' if NAME denoted - a right, but an invalid one, `KERN_INVALID_VALUE' if DESIRED_TYPE - was invalid. - - The `mach_port_extract_right' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return `mach_msg' - return codes. - - -File: mach.info, Node: Receive Rights, Next: Port Sets, Prev: Ports and other Tasks, Up: Port Manipulation Interface - -4.3.6 Receive Rights --------------------- - - -- Data type: mach_port_seqno_t - The `mach_port_seqno_t' data type is an `unsigned int' which - contains the sequence number of a port. - - -- Data type: mach_port_mscount_t - The `mach_port_mscount_t' data type is an `unsigned int' which - contains the make-send count for a port. - - -- Data type: mach_port_msgcount_t - The `mach_port_msgcount_t' data type is an `unsigned int' which - contains a number of messages. - - -- Data type: mach_port_rights_t - The `mach_port_rights_t' data type is an `unsigned int' which - contains a number of rights for a port. - - -- Data type: mach_port_status_t - This structure contains some status information about a port, - which can be queried with `mach_port_get_receive_status'. It has - the following members: - - `mach_port_t mps_pset' - The containing port set. - - `mach_port_seqno_t mps_seqno' - The sequence number. - - `mach_port_mscount_t mps_mscount' - The make-send count. - - `mach_port_msgcount_t mps_qlimit' - The maximum number of messages in the queue. - - `mach_port_msgcount_t mps_msgcount' - The current number of messages in the queue. - - `mach_port_rights_t mps_sorights' - The number of send-once rights that exist. - - `boolean_t mps_srights' - `TRUE' if send rights exist. - - `boolean_t mps_pdrequest' - `TRUE' if port-deleted notification is requested. - - `boolean_t mps_nsrequest' - `TRUE' if no-senders notification is requested. - - -- Function: kern_return_t mach_port_get_receive_status - (ipc_space_t TASK, mach_port_t NAME, - mach_port_status_t *STATUS) - The function `mach_port_get_receive_status' returns the current - status of the specified receive right. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - NAME did not denote a right and `KERN_INVALID_RIGHT' if NAME - denoted a right, but not a receive right. - - The `mach_port_get_receive_status' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return - `mach_msg' return codes. - - -- Function: kern_return_t mach_port_set_mscount (ipc_space_t TASK, - mach_port_t NAME, mach_port_mscount_t MSCOUNT) - The function `mach_port_set_mscount' changes the make-send count of - TASK's receive right named NAME to MSCOUNT. All values for - MSCOUNT are valid. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - NAME did not denote a right and `KERN_INVALID_RIGHT' if NAME - denoted a right, but not a receive right. - - The `mach_port_set_mscount' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return - `mach_msg' return codes. - - -- Function: kern_return_t mach_port_set_qlimit (ipc_space_t TASK, - mach_port_t NAME, mach_port_msgcount_t QLIMIT) - The function `mach_port_set_qlimit' changes the queue limit TASK's - receive right named NAME to QLIMIT. Valid values for QLIMIT are - between zero and `MACH_PORT_QLIMIT_MAX', inclusive. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - NAME did not denote a right, `KERN_INVALID_RIGHT' if NAME denoted - a right, but not a receive right and `KERN_INVALID_VALUE' if - QLIMIT was invalid. - - The `mach_port_set_qlimit' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return - `mach_msg' return codes. - - -- Function: kern_return_t mach_port_set_seqno (ipc_space_t TASK, - mach_port_t NAME, mach_port_seqno_t SEQNO) - The function `mach_port_set_seqno' changes the sequence number - TASK's receive right named NAME to SEQNO. All sequence number - values are valid. The next message received from the port will be - stamped with the specified sequence number. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - NAME did not denote a right and `KERN_INVALID_RIGHT' if NAME - denoted a right, but not a receive right. - - The `mach_port_set_seqno' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return - `mach_msg' return codes. - - -File: mach.info, Node: Port Sets, Next: Request Notifications, Prev: Receive Rights, Up: Port Manipulation Interface - -4.3.7 Port Sets ---------------- - - -- Function: kern_return_t mach_port_get_set_status (ipc_space_t TASK, - mach_port_t NAME, mach_port_array_t *MEMBERS, - mach_msg_type_number_t *COUNT) - The function `mach_port_get_set_status' returns the members of a - port set. MEMBERS is an array that is automatically allocated - when the reply message is received. The user should - `vm_deallocate' it when the data is no longer needed. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - NAME did not denote a right, `KERN_INVALID_RIGHT' if NAME denoted - a right, but not a receive right and `KERN_RESOURCE_SHORTAGE' if - the kernel ran out of memory. - - The `mach_port_get_set_status' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return `mach_msg' - return codes. - - -- Function: kern_return_t mach_port_move_member (ipc_space_t TASK, - mach_port_t MEMBER, mach_port_t AFTER) - The function MACH_PORT_MOVE_MEMBER moves the receive right MEMBER - into the port set AFTER. If the receive right is already a member - of another port set, it is removed from that set first (the whole - operation is atomic). If the port set is `MACH_PORT_NULL', then - the receive right is not put into a port set, but removed from its - current port set. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if - MEMBER or AFTER did not denote a right, `KERN_INVALID_RIGHT' if - MEMBER denoted a right, but not a receive right or AFTER denoted a - right, but not a port set, and `KERN_NOT_IN_SET' if AFTER was - `MACH_PORT_NULL', but `member' wasn't currently in a port set. - - The `mach_port_move_member' call is actually an RPC to TASK, - normally a send right for a task port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return - `mach_msg' return codes. - - -File: mach.info, Node: Request Notifications, Prev: Port Sets, Up: Port Manipulation Interface - -4.3.8 Request Notifications ---------------------------- - - -- Function: kern_return_t mach_port_request_notification - (ipc_space_t TASK, mach_port_t NAME, mach_msg_id_t VARIANT, - mach_port_mscount_t SYNC, mach_port_t NOTIFY, - mach_msg_type_name_t NOTIFY_TYPE, mach_port_t *PREVIOUS) - The function `mach_port_request_notification' registers a request - for a notification and supplies the send-once right NOTIFY to - which the notification will be sent. The NOTIFY_TYPE denotes the - IPC type for the send-once right, which can be - `MACH_MSG_TYPE_MAKE_SEND_ONCE' or `MACH_MSG_TYPE_MOVE_SEND_ONCE'. - It is an atomic swap, returning the previously registered - send-once right (or `MACH_PORT_NULL' for none) in PREVIOUS. A - previous notification request may be cancelled by providing - `MACH_PORT_NULL' for NOTIFY. - - The VARIANT argument takes the following values: - - `MACH_NOTIFY_PORT_DESTROYED' - SYNC must be zero. The NAME must specify a receive right, - and the call requests a port-destroyed notification for the - receive right. If the receive right were to have been - destroyed, say by `mach_port_destroy', then instead the - receive right will be sent in a port-destroyed notification - to the registered send-once right. - - `MACH_NOTIFY_DEAD_NAME' - The call requests a dead-name notification. NAME specifies - send, receive, or send-once rights for a port. If the port - is destroyed (and the right remains, becoming a dead name), - then a dead-name notification which carries the name of the - right will be sent to the registered send-once right. If - NOTIFY is not null and sync is non-zero, the name may specify - a dead name, and a dead-name notification is immediately - generated. - - Whenever a dead-name notification is generated, the user - reference count of the dead name is incremented. For - example, a send right with two user refs has a registered - dead-name request. If the port is destroyed, the send right - turns into a dead name with three user refs (instead of two), - and a dead-name notification is generated. - - If the name is made available for reuse, perhaps because of - `mach_port_destroy' or `mach_port_mod_refs', or the name - denotes a send-once right which has a message sent to it, - then the registered send-once right is used to generate a - port-deleted notification. - - `MACH_NOTIFY_NO_SENDERS' - The call requests a no-senders notification. NAME must - specify a receive right. If NOTIFY is not null, and the - receive right's make-send count is greater than or equal to - the sync value, and it has no extant send rights, than an - immediate no-senders notification is generated. Otherwise - the notification is generated when the receive right next - loses its last extant send right. In either case, any - previously registered send-once right is returned. - - The no-senders notification carries the value the port's - make-send count had when it was generated. The make-send - count is incremented whenever `MACH_MSG_TYPE_MAKE_SEND' is - used to create a new send right from the receive right. The - make-send count is reset to zero when the receive right is - carried in a message. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if - VARIANT was invalid, `KERN_INVALID_NAME' if NAME did not denote a - right, `KERN_INVALID_RIGHT' if NAME denoted an invalid right and - `KERN_INVALID_CAPABILITY' if NOTIFY was invalid. - - When using `MACH_NOTIFY_PORT_DESTROYED', the function returns - `KERN_INVALID_VALUE' if SYNC wasn't zero. - - When using `MACH_NOTIFY_DEAD_NAME', the function returns - `KERN_RESOURCE_SHORTAGE' if the kernel ran out of memory, - `KERN_INVALID_ARGUMENT' if NAME denotes a dead name, but SYNC is - zero or NOTIFY is `MACH_PORT_NULL', and `KERN_UREFS_OVERFLOW' if - NAME denotes a dead name, but generating an immediate dead-name - notification would overflow the name's user-reference count. - - The `mach_port_request_notification' call is actually an RPC to - TASK, normally a send right for a task port, but potentially any - send right. In addition to the normal diagnostic return codes - from the call's server (normally the kernel), the call may return - `mach_msg' return codes. - - -File: mach.info, Node: Virtual Memory Interface, Next: External Memory Management, Prev: Inter Process Communication, Up: Top - -5 Virtual Memory Interface -************************** - - -- Data type: vm_task_t - This is a `task_t' (and as such a `mach_port_t'), which holds a - port name associated with a port that represents a virtual memory - map in the kernel. An virtual memory map is used by the kernel to - manage the address space of a task. The virtual memory map - doesn't get a port name of its own. Instead the port name of the - task provided with the virtual memory is used to name the virtual - memory map of the task (as is indicated by the fact that the type - of `vm_task_t' is actually `task_t'). - - The virtual memory maps of tasks are the only ones accessible - outside of the kernel. - -* Menu: - -* Memory Allocation:: Allocation of new virtual memory. -* Memory Deallocation:: Freeing unused virtual memory. -* Data Transfer:: Reading, writing and copying memory. -* Memory Attributes:: Tweaking memory regions. -* Mapping Memory Objects:: How to map memory objects. -* Memory Statistics:: How to get statistics about memory usage. - - -File: mach.info, Node: Memory Allocation, Next: Memory Deallocation, Up: Virtual Memory Interface - -5.1 Memory Allocation -===================== - - -- Function: kern_return_t vm_allocate (vm_task_t TARGET_TASK, - vm_address_t *ADDRESS, vm_size_t SIZE, boolean_t ANYWHERE) - The function `vm_allocate' allocates a region of virtual memory, - placing it in the specified TASK's address space. - - The starting address is ADDRESS. If the ANYWHERE option is false, - an attempt is made to allocate virtual memory starting at this - virtual address. If this address is not at the beginning of a - virtual page, it will be rounded down to one. If there is not - enough space at this address, no memory will be allocated. If the - ANYWHERE option is true, the input value of this address will be - ignored, and the space will be allocated wherever it is available. - In either case, the address at which memory was actually - allocated will be returned in ADDRESS. - - SIZE is the number of bytes to allocate (rounded by the system in - a machine dependent way to an integral number of virtual pages). - - If ANYWHERE is true, the kernel should find and allocate any - region of the specified size, and return the address of the - resulting region in address address, rounded to a virtual page - boundary if there is sufficient space. - - The physical memory is not actually allocated until the new virtual - memory is referenced. By default, the kernel rounds all addresses - down to the nearest page boundary and all memory sizes up to the - nearest page size. The global variable `vm_page_size' contains - the page size. `mach_task_self' returns the value of the current - task port which should be used as the TARGET_TASK argument in - order to allocate memory in the caller's address space. For - languages other than C, these values can be obtained by the calls - `vm_statistics' and `mach_task_self'. Initially, the pages of - allocated memory will be protected to allow all forms of access, - and will be inherited in child tasks as a copy. Subsequent calls - to `vm_protect' and `vm_inherit' may be used to change these - properties. The allocated region is always zero-filled. - - The function returns `KERN_SUCCESS' if the memory was successfully - allocated, `KERN_INVALID_ADDRESS' if an invalid address was - specified and `KERN_NO_SPACE' if there was not enough space left to - satisfy the request. - - -File: mach.info, Node: Memory Deallocation, Next: Data Transfer, Prev: Memory Allocation, Up: Virtual Memory Interface - -5.2 Memory Deallocation -======================= - - -- Function: kern_return_t vm_deallocate (vm_task_t TARGET_TASK, - vm_address_t ADDRESS, vm_size_t SIZE) - `vm_deallocate' relinquishes access to a region of a TASK's - address space, causing further access to that memory to fail. This - address range will be available for reallocation. ADDRESS is the - starting address, which will be rounded down to a page boundary. - SIZE is the number of bytes to deallocate, which will be rounded - up to give a page boundary. Note, that because of the rounding to - virtual page boundaries, more than SIZE bytes may be deallocated. - Use `vm_page_size' or `vm_statistics' to find out the current - virtual page size. - - This call may be used to deallocte memory that was passed to a - task in a message (via out of line data). In that case, the - rounding should cause no trouble, since the region of memory was - allocated as a set of pages. - - The `vm_deallocate' call affects only the task specified by the - TARGET_TASK. Other tasks which may have access to this memory may - continue to reference it. - - The function returns `KERN_SUCCESS' if the memory was successfully - deallocated and `KERN_INVALID_ADDRESS' if an invalid or - non-allocated address was specified. - - -File: mach.info, Node: Data Transfer, Next: Memory Attributes, Prev: Memory Deallocation, Up: Virtual Memory Interface - -5.3 Data Transfer -================= - - -- Function: kern_return_t vm_read (vm_task_t TARGET_TASK, - vm_address_t ADDRESS, vm_size_t SIZE, vm_offset_t *DATA, - mach_msg_type_number_t *DATA_COUNT) - The function `vm_read' allows one task's virtual memory to be read - by another task. The TARGET_TASK is the task whose memory is to - be read. ADDRESS is the first address to be read and must be on a - page boundary. SIZE is the number of bytes of data to be read and - must be an integral number of pages. DATA is the array of data - copied from the given task, and DATA_COUNT is the size of the data - array in bytes (will be an integral number of pages). - - Note that the data array is returned in a newly allocated region; - the task reading the data should `vm_deallocate' this region when - it is done with the data. - - The function returns `KERN_SUCCESS' if the memory was successfully - read, `KERN_INVALID_ADDRESS' if an invalid or non-allocated address - was specified or there was not SIZE bytes of data following the - address, `KERN_INVALID_ARGUMENT' if the address does not start on a - page boundary or the size is not an integral number of pages, - `KERN_PROTECTION_FAILURE' if the address region in the target task - is protected against reading and `KERN_NO_SPACE' if there was not - enough room in the callers virtual memory to allocate space for - the data to be returned. - - -- Function: kern_return_t vm_write (vm_task_t TARGET_TASK, - vm_address_t ADDRESS, vm_offset_t DATA, - mach_msg_type_number_t DATA_COUNT) - The function `vm_write' allows a task to write to the vrtual memory - of TARGET_TASK. ADDRESS is the starting address in task to be - affected. DATA is an array of bytes to be written, and DATA_COUNT - the size of the DATA array. - - The current implementation requires that ADDRESS, DATA and - DATA_COUNT all be page-aligned. Otherwise, - `KERN_INVALID_ARGUMENT' is returned. - - The function returns `KERN_SUCCESS' if the memory was successfully - written, `KERN_INVALID_ADDRESS' if an invalid or non-allocated - address was specified or there was not DATA_COUNT bytes of - allocated memory starting at ADDRESS and `KERN_PROTECTION_FAILURE' - if the address region in the target task is protected against - writing. - - -- Function: kern_return_t vm_copy (vm_task_t TARGET_TASK, - vm_address_t SOURCE_ADDRESS, vm_size_t COUNT, - vm_offset_t DEST_ADDRESS) - The function `vm_copy' causes the source memory range to be copied - to the destination address. The source and destination memory - ranges may overlap. The destination address range must already be - allocated and writable; the source range must be readable. - - `vm_copy' is equivalent to `vm_read' followed by `vm_write'. - - The current implementation requires that ADDRESS, DATA and - DATA_COUNT all be page-aligned. Otherwise, - `KERN_INVALID_ARGUMENT' is returned. - - The function returns `KERN_SUCCESS' if the memory was successfully - written, `KERN_INVALID_ADDRESS' if an invalid or non-allocated - address was specified or there was insufficient memory allocated - at one of the addresses and `KERN_PROTECTION_FAILURE' if the - destination region was not writable or the source region was not - readable. - - -File: mach.info, Node: Memory Attributes, Next: Mapping Memory Objects, Prev: Data Transfer, Up: Virtual Memory Interface - -5.4 Memory Attributes -===================== - - -- Function: kern_return_t vm_region (vm_task_t TARGET_TASK, - vm_address_t *ADDRESS, vm_size_t *SIZE, - vm_prot_t *PROTECTION, vm_prot_t *MAX_PROTECTION, - vm_inherit_t *INHERITANCE, boolean_t *SHARED, - memory_object_name_t *OBJECT_NAME, vm_offset_t *OFFSET) - The function `vm_region' returns a description of the specified - region of TARGET_TASK's virtual address space. `vm_region' begins - at ADDRESS and looks forward through memory until it comes to an - allocated region. If address is within a region, then that region - is used. Various bits of information about the region are - returned. If ADDRESS was not within a region, then ADDRESS is set - to the start of the first region which follows the incoming value. - In this way an entire address space can be scanned. - - The SIZE returned is the size of the located region in bytes. - PROTECTION is the current protection of the region, MAX_PROTECTION - is the maximum allowable protection for this region. INHERITANCE - is the inheritance attribute for this region. SHARED tells if the - region is shared or not. The port OBJECT_NAME identifies the - memory object associated with this region, and OFFSET is the - offset into the pager object that this region begins at. - - The function returns `KERN_SUCCESS' if the memory region was - successfully located and the information returned and - `KERN_NO_SPACE' if there is no region at or above ADDRESS in the - specified task. - - -- Function: kern_return_t vm_protect (vm_task_t TARGET_TASK, - vm_address_t ADDRESS, vm_size_t SIZE, boolean_t SET_MAXIMUM, - vm_prot_t NEW_PROTECTION) - The function `vm_protect' sets the virtual memory access privileges - for a range of allocated addresses in TARGET_TASK's virtual - address space. The protection argument describes a combination of - read, write, and execute accesses that should be _permitted_. - - ADDRESS is the starting address, which will be rounded down to a - page boundary. SIZE is the size in bytes of the region for which - protection is to change, and will be rounded up to give a page - boundary. If SET_MAXIMUM is set, make the protection change apply - to the maximum protection associated with this address range; - otherwise, the current protection on this range is changed. If - the maximum protection is reduced below the current protection, - both will be changed to reflect the new maximum. NEW_PROTECTION - is the new protection value for this region; a set of: - `VM_PROT_READ', `VM_PROT_WRITE', `VM_PROT_EXECUTE'. - - The enforcement of virtual memory protection is machine-dependent. - Nominally read access requires `VM_PROT_READ' permission, write - access requires `VM_PROT_WRITE' permission, and execute access - requires `VM_PROT_EXECUTE' permission. However, some combinations - of access rights may not be supported. In particular, the kernel - interface allows write access to require `VM_PROT_READ' and - `VM_PROT_WRITE' permission and execute access to require - `VM_PROT_READ' permission. - - The function returns `KERN_SUCCESS' if the memory was successfully - protected, `KERN_INVALID_ADDRESS' if an invalid or non-allocated - address was specified and `KERN_PROTECTION_FAILURE' if an attempt - was made to increase the current or maximum protection beyond the - existing maximum protection value. - - -- Function: kern_return_t vm_inherit (vm_task_t TARGET_TASK, - vm_address_t ADDRESS, vm_size_t SIZE, - vm_inherit_t NEW_INHERITANCE) - The function `vm_inherit' specifies how a region of TARGET_TASK's - address space is to be passed to child tasks at the time of task - creation. Inheritance is an attribute of virtual pages, so - ADDRESS to start from will be rounded down to a page boundary and - SIZE, the size in bytes of the region for wihch inheritance is to - change, will be rounded up to give a page boundary. How this - memory is to be inherited in child tasks is specified by - NEW_INHERITANCE. Inheritance is specified by using one of these - following three values: - - `VM_INHERIT_SHARE' - Child tasks will share this memory with this task. - - `VM_INHERIT_COPY' - Child tasks will receive a copy of this region. - - `VM_INHERIT_NONE' - This region will be absent from child tasks. - - Setting `vm_inherit' to `VM_INHERIT_SHARE' and forking a child - task is the only way two Mach tasks can share physical memory. - Remember that all the theads of a given task share all the same - memory. - - The function returns `KERN_SUCCESS' if the memory inheritance was - successfully set and `KERN_INVALID_ADDRESS' if an invalid or - non-allocated address was specified. - - -- Function: kern_return_t vm_wire (host_priv_t HOST_PRIV, - vm_task_t TARGET_TASK, vm_address_t ADDRESS, vm_size_t SIZE, - vm_prot_t ACCESS) - The function `vm_wire' allows privileged applications to control - memory pageability. HOST_PRIV is the privileged host port for the - host on which TARGET_TASK resides. ADDRESS is the starting - address, which will be rounded down to a page boundary. SIZE is - the size in bytes of the region for which protection is to change, - and will be rounded up to give a page boundary. ACCESS specifies - the types of accesses that must not cause page faults. - - The semantics of a successful `vm_wire' operation are that memory - in the specified range will not cause page faults for any accesses - included in access. Data memory can be made non-pageable (wired) - with a access argument of `VM_PROT_READ | VM_PROT_WRITE'. A - special case is that `VM_PROT_NONE' makes the memory pageable. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_HOST' if HOST_PRIV was not the privileged host port, - `KERN_INVALID_TASK' if TASK was not a valid task, - `KERN_INVALID_VALUE' if ACCESS specified an invalid access mode, - `KERN_FAILURE' if some memory in the specified range is not - present or has an inappropriate protection value, and - `KERN_INVALID_ARGUMENT' if unwiring (ACCESS is `VM_PROT_NONE') and - the memory is not already wired. - - The `vm_wire' call is actually an RPC to HOST_PRIV, normally a - send right for a privileged host port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return - `mach_msg' return codes. - - -- Function: kern_return_t vm_machine_attribute (vm_task_t TASK, - vm_address_t ADDRESS, vm_size_t SIZE, vm_prot_t ACCESS, - vm_machine_attribute_t ATTRIBUTE, - vm_machine_attribute_val_t VALUE) - The function `vm_machine_attribute' specifies machine-specific - attributes for a VM mapping, such as cachability, migrability, - replicability. This is used on machines that allow the user - control over the cache (this is the case for MIPS architectures) - or placement of memory pages as in NUMA architectures (Non-Uniform - Memory Access time) such as the IBM ACE multiprocessor. - - Machine-specific attributes can be consider additions to the - machine-independent ones such as protection and inheritance, but - they are not guaranteed to be supported by any given machine. - Moreover, implementations of Mach on new architectures might find - the need for new attribute types and or values besides the ones - defined in the initial implementation. - - The types currently defined are - `MATTR_CACHE' - Controls caching of memory pages - - `MATTR_MIGRATE' - Controls migrability of memory pages - - `MATTR_REPLICATE' - Controls replication of memory pages - - Corresponding values, and meaning of a specific call to - `vm_machine_attribute' - `MATTR_VAL_ON' - Enables the attribute. Being enabled is the default value - for any applicable attribute. - - `MATTR_VAL_OFF' - Disables the attribute, making memory non-cached, or - non-migratable, or non-replicatable. - - `MATTR_VAL_GET' - Returns the current value of the attribute for the memory - segment. If the attribute does not apply uniformly to the - given range the value returned applies to the initial portion - of the segment only. - - `MATTR_VAL_CACHE_FLUSH' - Flush the memory pages from the Cache. The size value in - this case might be meaningful even if not a multiple of the - page size, depending on the implementation. - - `MATTR_VAL_ICACHE_FLUSH' - Same as above, applied to the Instruction Cache alone. - - `MATTR_VAL_DCACHE_FLUSH' - Same as above, applied to the Data Cache alone. - - The function returns `KERN_SUCCESS' if call succeeded, and - `KERN_INVALID_ARGUMENT' if TASK is not a task, or ADDRESS and SIZE - do not define a valid address range in task, or ATTRIBUTE is not a - valid attribute type, or it is not implemented, or VALUE is not a - permissible value for attribute. - - -File: mach.info, Node: Mapping Memory Objects, Next: Memory Statistics, Prev: Memory Attributes, Up: Virtual Memory Interface - -5.5 Mapping Memory Objects -========================== - - -- Function: kern_return_t vm_map (vm_task_t TARGET_TASK, - vm_address_t *ADDRESS, vm_size_t SIZE, vm_address_t MASK, - boolean_t ANYWHERE, memory_object_t MEMORY_OBJECT, - vm_offset_t OFFSET, boolean_t COPY, vm_prot_t CUR_PROTECTION, - vm_prot_t MAX_PROTECTION, vm_inherit_t INHERITANCE) - The function `vm_map' maps a region of virtual memory at the - specified address, for which data is to be supplied by the given - memory object, starting at the given offset within that object. - In addition to the arguments used in `vm_allocate', the `vm_map' - call allows the specification of an address alignment parameter, - and of the initial protection and inheritance values. - - If the memory object in question is not currently in use, the - kernel will perform a `memory_object_init' call at this time. If - the copy parameter is asserted, the specified region of the memory - object will be copied to this address space; changes made to this - object by other tasks will not be visible in this mapping, and - changes made in this mapping will not be visible to others (or - returned to the memory object). - - The `vm_map' call returns once the mapping is established. - Completion of the call does not require any action on the part of - the memory manager. - - Warning: Only memory objects that are provided by bona fide memory - managers should be used in the `vm_map' call. A memory manager - must implement the memory object interface described elsewhere in - this manual. If other ports are used, a thread that accesses the - mapped virtual memory may become permanently hung or may receive a - memory exception. - - TARGET_TASK is the task to be affected. The starting address is - ADDRESS. If the ANYWHERE option is used, this address is ignored. - The address actually allocated will be returned in ADDRESS. SIZE - is the number of bytes to allocate (rounded by the system in a - machine dependent way). The alignment restriction is specified by - MASK. Bits asserted in this mask must not be asserted in the - address returned. If ANYWHERE is set, the kernel should find and - allocate any region of the specified size, and return the address - of the resulting region in ADDRESS. - - MEMORY_OBJECT is the port that represents the memory object: used - by user tasks in `vm_map'; used by the make requests for data or - other management actions. If this port is `MEMORY_OBJECT_NULL', - then zero-filled memory is allocated instead. Within a memory - object, OFFSET specifes an offset in bytes. This must be page - aligned. If COPY is set, the range of the memory object should be - copied to the target task, rather than mapped read-write. - - The function returns `KERN_SUCCESS' if the object is mapped, - `KERN_NO_SPACE' if no unused region of the task's virtual address - space that meets the address, size, and alignment criteria could be - found, and `KERN_INVALID_ARGUMENT' if an invalid argument was - provided. - - -File: mach.info, Node: Memory Statistics, Prev: Mapping Memory Objects, Up: Virtual Memory Interface - -5.6 Memory Statistics -===================== - - -- Data type: vm_statistics_data_t - This structure is returned in VM_STATS by the `vm_statistics' - function and provides virtual memory statistics for the system. - It has the following members: - - `long pagesize' - The page size in bytes. - - `long free_count' - The number of free pages. - - `long active_count' - The umber of active pages. - - `long inactive_count' - The number of inactive pages. - - `long wire_count' - The number of pages wired down. - - `long zero_fill_count' - The number of zero filled pages. - - `long reactivations' - The number of reactivated pages. - - `long pageins' - The number of pageins. - - `long pageouts' - The number of pageouts. - - `long faults' - The number of faults. - - `long cow_faults' - The number of copy-on-writes. - - `long lookups' - The number of object cache lookups. - - `long hits' - The number of object cache hits. - - -- Function: kern_return_t vm_statistics (vm_task_t TARGET_TASK, - vm_statistics_data_t *VM_STATS) - The function `vm_statistics' returns the statistics about the - kernel's use of virtual memory since the kernel was booted. - `pagesize' can also be found as a global variable `vm_page_size' - which is set at task initialization and remains constant for the - life of the task. - - -File: mach.info, Node: External Memory Management, Next: Threads and Tasks, Prev: Virtual Memory Interface, Up: Top - -6 External Memory Management -**************************** - -* Menu: - -* Memory Object Server:: The basics of external memory management. -* Memory Object Creation:: How new memory objects are created. -* Memory Object Termination:: How memory objects are terminated. -* Memory Objects and Data:: Data transfer to and from memory objects. -* Memory Object Locking:: How memory objects are locked. -* Memory Object Attributes:: Manipulating attributes of memory objects. -* Default Memory Manager:: Setting and using the default memory manager. - - -File: mach.info, Node: Memory Object Server, Next: Memory Object Creation, Up: External Memory Management - -6.1 Memory Object Server -======================== - - -- Function: boolean_t memory_object_server (msg_header_t *IN_MSG, - msg_header_t *OUT_MSG) - -- Function: boolean_t memory_object_default_server - (msg_header_t *IN_MSG, msg_header_t *OUT_MSG) - -- Function: boolean_t seqnos_memory_object_server - (msg_header_t *IN_MSG, msg_header_t *OUT_MSG) - -- Function: boolean_t seqnos_memory_object_default_server - (msg_header_t *IN_MSG, msg_header_t *OUT_MSG) - A memory manager is a server task that responds to specific - messages from the kernel in order to handle memory management - functions for the kernel. - - In order to isolate the memory manager from the specifics of - message formatting, the remote procedure call generator produces a - procedure, `memory_object_server', to handle a received message. - This function does all necessary argument handling, and actually - calls one of the following functions: `memory_object_init', - `memory_object_data_write', `memory_object_data_return', - `memory_object_data_request', `memory_object_data_unlock', - `memory_object_lock_completed', `memory_object_copy', - `memory_object_terminate'. The *default memory manager* may get - two additional requests from the kernel: `memory_object_create' - and `memory_object_data_initialize'. The remote procedure call - generator produces a procedure `memory_object_default_server' to - handle those functions specific to the default memory manager. - - The `seqnos_memory_object_server' and - `seqnos_memory_object_default_server' differ from - `memory_object_server' and `memory_object_default_server' in that - they supply message sequence numbers to the server interfaces. - They call the `seqnos_memory_object_*' functions, which complement - the `memory_object_*' set of functions. - - The return value from the `memory_object_server' function indicates - that the message was appropriate to the memory management interface - (returning `TRUE'), or that it could not handle this message - (returning `FALSE'). - - The IN_MSG argument is the message that has been received from the - kernel. The OUT_MSG is a reply message, but this is not used for - this server. - - The function returns `TRUE' to indicate that the message in - question was applicable to this interface, and that the appropriate - routine was called to interpret the message. It returns `FALSE' to - indicate that the message did not apply to this interface, and - that no other action was taken. - - -File: mach.info, Node: Memory Object Creation, Next: Memory Object Termination, Prev: Memory Object Server, Up: External Memory Management - -6.2 Memory Object Creation -========================== - - -- Function: kern_return_t memory_object_init - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, - memory_object_name_t MEMORY_OBJECT_NAME, - vm_size_t MEMORY_OBJECT_PAGE_SIZE) - -- Function: kern_return_t seqnos_memory_object_init - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, - memory_object_name_t MEMORY_OBJECT_NAME, - vm_size_t MEMORY_OBJECT_PAGE_SIZE) - The function `memory_object_init' serves as a notification that the - kernel has been asked to map the given memory object into a task's - virtual address space. Additionally, it provides a port on which - the memory manager may issue cache management requests, and a port - which the kernel will use to name this data region. In the event - that different each will perform a `memory_object_init' call with - new request and name ports. The virtual page size that is used by - the calling kernel is included for planning purposes. - - When the memory manager is prepared to accept requests for data - for this object, it must call `memory_object_ready' with the - attribute. Otherwise the kernel will not process requests on this - object. To reject all mappings of this object, the memory manager - may use `memory_object_destroy'. - - The argument MEMORY_OBJECT is the port that represents the memory - object data, as supplied to the kernel in a `vm_map' call. - MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied - to more than one the kernel that has made the request.) - MEMORY_OBJECT_NAME is a port used by the kernel to refer to the - memory object data in reponse to `vm_region' calls. - `memory_object_page_size' is the page size to be used by this - kernel. All data sizes in calls involving this kernel must be an - integral multiple of the page size. Note that different kernels, - indicated by a different `memory_control', may have different page - sizes. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -- Function: kern_return_t memory_object_ready - (memory_object_control_t MEMORY_CONTROL, - boolean_t MAY_CACHE_OBJECT, - memory_object_copy_strategy_t COPY_STRATEGY) - The function `memory_object_ready' informs the kernel that the - memory manager is ready to receive data or unlock requests on - behalf of the clients. The argument MEMORY_CONTROL is the port, - provided by the kernel in a `memory_object_init' call, to which - cache management requests may be issued. If MAY_CACHE_OBJECT is - set, the kernel may keep data associated with this memory object, - even after virtual memory references to it are gone. - - COPY_STRATEGY tells how the kernel should copy regions of the - associated memory object. There are three possible caching - strategies: `MEMORY_OBJECT_COPY_NONE' which specifies that nothing - special should be done when data in the object is copied; - `MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager - should be notified via a `memory_object_copy' call before any part - of the object is copied; and `MEMORY_OBJECT_COPY_DELAY' which - guarantees that the memory manager does not externally modify the - data so that the kernel can use its normal copy-on-write - algorithms. `MEMORY_OBJECT_COPY_DELAY' is the strategy most - commonly used. - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -File: mach.info, Node: Memory Object Termination, Next: Memory Objects and Data, Prev: Memory Object Creation, Up: External Memory Management - -6.3 Memory Object Termination -============================= - - -- Function: kern_return_t memory_object_terminate - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, - memory_object_name_t MEMORY_OBJECT_NAME) - -- Function: kern_return_t seqnos_memory_object_terminate - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, - memory_object_name_t MEMORY_OBJECT_NAME) - The function `memory_object_terminate' indicates that the kernel - has completed its use of the given memory object. All rights to - the memory object control and name ports are included, so that the - memory manager can destroy them (using `mach_port_deallocate') - after doing appropriate bookkeeping. The kernel will terminate a - memory object only after all address space mappings of that memory - object have been deallocated, or upon explicit request by the - memory manager. - - The argument MEMORY_OBJECT is the port that represents the memory - object data, as supplied to the kernel in a `vm_map' call. - MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied - to more than one the kernel that has made the request.) - MEMORY_OBJECT_NAME is a port used by the kernel to refer to the - memory object data in reponse to `vm_region' calls. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -- Function: kern_return_t memory_object_destroy - (memory_object_control_t MEMORY_CONTROL, kern_return_t REASON) - The function `memory_object_destroy' tells the kernel to shut down - the memory object. As a result of this call the kernel will no - longer support paging activity or any `memory_object' calls on this - object, and all rights to the memory object port, the memory - control port and the memory name port will be returned to the - memory manager in a memory_object_terminate call. If the memory - manager is concerned that any modified cached data be returned to - it before the object is terminated, it should call - `memory_object_lock_request' with SHOULD_FLUSH set and a lock - value of `VM_PROT_WRITE' before making this call. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a `memory_object_init' call, to which cache management requests may - be issued. REASON is an error code indicating why the object must - be destroyed. - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -File: mach.info, Node: Memory Objects and Data, Next: Memory Object Locking, Prev: Memory Object Termination, Up: External Memory Management - -6.4 Memory Objects and Data -=========================== - - -- Function: kern_return_t memory_object_data_return - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT, boolean_t DIRTY, - boolean_t KERNEL_COPY) - -- Function: kern_return_t seqnos_memory_object_data_return - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT, boolean_t DIRTY, - boolean_t KERNEL_COPY) - The function `memory_object_data_return' provides the memory - manager with data that has been modified while cached in physical - memory. Once the memory manager no longer needs this data (e.g., - it has been written to another storage medium), it should be - deallocated using `vm_deallocate'. - - The argument MEMORY_OBJECT is the port that represents the memory - object data, as supplied to the kernel in a `vm_map' call. - MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied - to more than one the kernel that has made the request.) OFFSET is - the offset within a memory object to which this call refers. This - will be page aligned. DATA is the data which has been modified - while cached in physical memory. DATA_COUNT is the amount of data - to be written, in bytes. This will be an integral number of - memory object pages. - - The kernel will also use this call to return precious pages. If an - unmodified precious age is returned, DIRTY is set to `FALSE', - otherwise it is `TRUE'. If KERNEL_COPY is `TRUE', the kernel kept - a copy of the page. Precious data remains precious if the kernel - keeps a copy. The indication that the kernel kept a copy is only - a hint if the data is not precious; the cleaned copy may be - discarded without further notifying the manager. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -- Function: kern_return_t memory_object_data_request - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t LENGTH, vm_prot_t DESIRED_ACCESS) - -- Function: kern_return_t seqnos_memory_object_data_request - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t LENGTH, vm_prot_t DESIRED_ACCESS) - The function `memory_object_data_request' is a request for data - from the specified memory object, for at least the access - specified. The memory manager is expected to return at least the - specified data, with as much access as it can allow, using - `memory_object_data_supply'. If the memory manager is unable to - provide the data (for example, because of a hardware error), it - may use the `memory_object_data_error' call. The - `memory_object_data_unavailable' call may be used to tell the - kernel to supply zero-filled memory for this region. - - The argument MEMORY_OBJECT is the port that represents the memory - object data, as supplied to the kernel in a `vm_map' call. - MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied - to more than one the kernel that has made the request.) OFFSET is - the offset within a memory object to which this call refers. This - will be page aligned. LENGTH is the number of bytes of data, - starting at OFFSET, to which this call refers. This will be an - integral number of memory object pages. DESIRED_ACCESS is a - protection value describing the memory access modes which must be - permitted on the specified cached data. One or more of: - `VM_PROT_READ', `VM_PROT_WRITE' or `VM_PROT_EXECUTE'. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -- Function: kern_return_t memory_object_data_supply - (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT, vm_prot_t LOCK_VALUE, - boolean_t PRECIOUS, mach_port_t REPLY) - The function `memory_object_data_supply' supplies the kernel with - data for the specified memory object. Ordinarily, memory managers - should only provide data in reponse to `memory_object_data_request' - calls from the kernel (but they may provide data in advance as - desired). When data already held by this kernel is provided - again, the new data is ignored. The kernel may not provide any - data (or protection) consistency among pages with different - virtual page alignments within the same object. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a `memory_object_init' call, to which cache management requests may - be issued. OFFSET is an offset within a memory object in bytes. - This must be page aligned. DATA is the data that is being - provided to the kernel. This is a pointer to the data. - DATA_COUNT is the amount of data to be provided. Only whole - virtual pages of data can be accepted; partial pages will be - discarded. - - LOCK_VALUE is a protection value indicating those forms of access - that should *not* be permitted to the specified cached data. The - lock values must be one or more of the set: `VM_PROT_NONE', - `VM_PROT_READ', `VM_PROT_WRITE', `VM_PROT_EXECUTE' and - `VM_PROT_ALL' as defined in `mach/vm_prot.h'. - - If PRECIOUS is `FALSE', the kernel treats the data as a temporary - and may throw it away if it hasn't been changed. If the PRECIOUS - value is `TRUE', the kernel treats its copy as a data repository - and promises to return it to the manager; the manager may tell the - kernel to throw it away instead by flushing and not cleaning the - data (see `memory_object_lock_request'). - - If REPLY_TO is not `MACH_PORT_NULL', the kernel will send a - completion message to the provided port (see - `memory_object_supply_completed'). - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -- Function: kern_return_t memory_object_supply_completed - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_size_t LENGTH, kern_return_t RESULT, - vm_offset_t ERROR_OFFSET) - -- Function: kern_return_t seqnos_memory_object_supply_completed - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_size_t LENGTH, kern_return_t RESULT, - vm_offset_t ERROR_OFFSET) - The function `memory_object_supply_completed' indicates that a - previous `memory_object_data_supply' has been completed. Note that - this call is made on whatever port was specified in the - `memory_object_data_supply' call; that port need not be the memory - object port itself. No reply is expected after this call. - - The argument MEMORY_OBJECT is the port that represents the memory - object data, as supplied to the kernel in a `vm_map' call. - MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied - to more than one the kernel that has made the request.) OFFSET is - the offset within a memory object to which this call refers. - LENGTH is the length of the data covered by the lock request. The - RESULT parameter indicates what happened during the supply. If it - is not `KERN_SUCCESS', then ERROR_OFFSET identifies the first - offset at which a problem occurred. The pagein operation stopped - at this point. Note that the only failures reported by this - mechanism are `KERN_MEMORY_PRESENT'. All other failures (invalid - argument, error on pagein of supplied data in manager's address - space) cause the entire operation to fail. - - - -- Function: kern_return_t memory_object_data_error - (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_size_t SIZE, kern_return_t REASON) - The function `memory_object_data_error' indicates that the memory - manager cannot return the data requested for the given region, - specifying a reason for the error. This is typically used when a - hardware error is encountered. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a `memory_object_init' call, to which cache management requests may - be issued. OFFSET is an offset within a memory object in bytes. - This must be page aligned. DATA is the data that is being - provided to the kernel. This is a pointer to the data. SIZE is - the amount of cached data (starting at OFFSET) to be handled. - This must be an integral number of the memory object page size. - REASON is an error code indicating what type of error occured. - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -- Function: kern_return_t memory_object_data_unavailable - (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_size_t SIZE, kern_return_t REASON) - The function `memory_object_data_unavailable' indicates that the - memory object does not have data for the given region and that the - kernel should provide the data for this range. The memory manager - may use this call in three different situations. - - 1. The object was created by `memory_object_create' and the - kernel has not yet provided data for this range (either via a - `memory_object_data_initialize', `memory_object_data_write' or - a `memory_object_data_return' for the object. - - 2. The object was created by an `memory_object_data_copy' and the - kernel should copy this region from the original memory - object. - - 3. The object is a normal user-created memory object and the - kernel should supply unlocked zero-filled pages for the range. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a `memory_object_init' call, to which cache management requests may - be issued. OFFSET is an offset within a memory object, in bytes. - This must be page aligned. SIZE is the amount of cached data - (starting at OFFSET) to be handled. This must be an integral - number of the memory object page size. - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -- Function: kern_return_t memory_object_copy - (memory_object_t OLD_MEMORY_OBJECT, - memory_object_control_t OLD_MEMORY_CONTROL, - vm_offset_t OFFSET, vm_size_t LENGTH, - memory_object_t NEW_MEMORY_OBJECT) - -- Function: kern_return_t seqnos_memory_object_copy - (memory_object_t OLD_MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t OLD_MEMORY_CONTROL, - vm_offset_t OFFSET, vm_size_t LENGTH, - memory_object_t NEW_MEMORY_OBJECT) - The function `memory_object_copy' indicates that a copy has been - made of the specified range of the given original memory object. - This call includes only the new memory object itself; a - `memory_object_init' call will be made on the new memory object - after the currently cached pages of the original object are - prepared. After the memory manager receives the init call, it - must reply with the `memory_object_ready' call to assert the - "ready" attribute. The kernel will use the new memory object, - control and name ports to refer to the new copy. - - This call is made when the original memory object had the caching - parameter set to `MEMORY_OBJECT_COPY_CALL' and a user of the object - has asked the kernel to copy it. - - Cached pages from the original memory object at the time of the - copy operation are handled as follows: Readable pages may be - silently copied to the new memory object (with all access - permissions). Pages not copied are locked to prevent write access. - - The new memory object is *temporary*, meaning that the memory - manager should not change its contents or allow the memory object - to be mapped in another client. The memory manager may use the - `memory_object_data_unavailable' call to indicate that the - appropriate pages of the original memory object may be used to - fulfill the data request. - - The argument OLD_MEMORY_OBJECT is the port that represents the old - memory object data. OLD_MEMORY_CONTROL is the kernel port for the - old object. OFFSET is the offset within a memory object to which - this call refers. This will be page aligned. LENGTH is the - number of bytes of data, starting at OFFSET, to which this call - refers. This will be an integral number of memory object pages. - NEW_MEMORY_OBJECT is a new memory object created by the kernel; - see synopsis for further description. Note that all port rights - (including receive rights) are included for the new memory object. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - The remaining interfaces in this section are obsolet. - - -- Function: kern_return_t memory_object_data_write - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT) - -- Function: kern_return_t seqnos_memory_object_data_write - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT) - The function `memory_object_data_write' provides the memory manager - with data that has been modified while cached in physical memory. - It is the old form of `memory_object_data_return'. Once the - memory manager no longer needs this data (e.g., it has been written - to another storage medium), it should be deallocated using - `vm_deallocate'. - - The argument MEMORY_OBJECT is the port that represents the memory - object data, as supplied to the kernel in a `vm_map' call. - MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied - to more than one the kernel that has made the request.) OFFSET is - the offset within a memory object to which this call refers. This - will be page aligned. DATA is the data which has been modified - while cached in physical memory. DATA_COUNT is the amount of data - to be written, in bytes. This will be an integral number of - memory object pages. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -- Function: kern_return_t memory_object_data_provided - (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT, vm_prot_t LOCK_VALUE) - The function `memory_object_data_provided' supplies the kernel with - data for the specified memory object. It is the old form of - `memory_object_data_supply'. Ordinarily, memory managers should - only provide data in reponse to `memory_object_data_request' calls - from the kernel. The LOCK_VALUE specifies what type of access - will not be allowed to the data range. The lock values must be - one or more of the set: `VM_PROT_NONE', `VM_PROT_READ', - `VM_PROT_WRITE', `VM_PROT_EXECUTE' and `VM_PROT_ALL' as defined in - `mach/vm_prot.h'. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a `memory_object_init' call, to which cache management requests may - be issued. OFFSET is an offset within a memory object in bytes. - This must be page aligned. DATA is the data that is being - provided to the kernel. This is a pointer to the data. - DATA_COUNT is the amount of data to be provided. This must be an - integral number of memory object pages. LOCK_VALUE is a - protection value indicating those forms of access that should - *not* be permitted to the specified cached data. - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -File: mach.info, Node: Memory Object Locking, Next: Memory Object Attributes, Prev: Memory Objects and Data, Up: External Memory Management - -6.5 Memory Object Locking -========================= - - -- Function: kern_return_t memory_object_lock_request - (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_size_t SIZE, memory_object_return_t SHOULD_CLEAN, - boolean_t SHOULD_FLUSH, vm_prot_t LOCK_VALUE, - mach_port_t REPLY_TO) - The function `memory_object_lock_request' allows a memory manager - to make cache management requests. As specified in arguments to - the call, the kernel will: - * clean (i.e., write back using `memory_object_data_supply' or - `memory_object_data_write') any cached data which has been - modified since the last time it was written - - * flush (i.e., remove any uses of) that data from memory - - * lock (i.e., prohibit the specified uses of) the cached data - - Locks applied to cached data are not cumulative; new lock values - override previous ones. Thus, data may also be unlocked using this - primitive. The lock values must be one or more of the following - values: `VM_PROT_NONE', `VM_PROT_READ', `VM_PROT_WRITE', - `VM_PROT_EXECUTE' and `VM_PROT_ALL' as defined in `mach/vm_prot.h'. - - Only data which is cached at the time of this call is affected. - When a running thread requires a prohibited access to cached data, - the kernel will issue a `memory_object_data_unlock' call - specifying the forms of access required. - - Once all of the actions requested by this call have been - completed, the kernel issues a `memory_object_lock_completed' call - on the specified reply port. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a `memory_object_init' call, to which cache management requests may - be issued. OFFSET is an offset within a memory object, in bytes. - This must be page aligned. SIZE is the amount of cached data - (starting at OFFSET) to be handled. This must be an integral - number of the memory object page size. If SHOULD_CLEAN is set, - modified data should be written back to the memory manager. If - SHOULD_FLUSH is set, the specified cached data should be - invalidated, and all uses of that data should be revoked. - LOCK_VALUE is a protection value indicating those forms of access - that should *not* be permitted to the specified cached data. - REPLY_TO is a port on which a `memory_object_lock_comleted' call - should be issued, or `MACH_PORT_NULL' if no acknowledgement is - desired. - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -- Function: kern_return_t memory_object_lock_completed - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_size_t LENGTH) - -- Function: kern_return_t seqnos_memory_object_lock_completed - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_size_t LENGTH) - The function `memory_object_lock_completed' indicates that a - previous `memory_object_lock_request' has been completed. Note - that this call is made on whatever port was specified in the - `memory_object_lock_request' call; that port need not be the memory - object port itself. No reply is expected after this call. - - The argument MEMORY_OBJECT is the port that represents the memory - object data, as supplied to the kernel in a `vm_map' call. - MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied - to more than one the kernel that has made the request.) OFFSET is - the offset within a memory object to which this call refers. - LENGTH is the length of the data covered by the lock request. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -- Function: kern_return_t memory_object_data_unlock - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_size_t LENGTH, vm_prot_t DESIRED_ACCESS) - -- Function: kern_return_t seqnos_memory_object_data_unlock - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_size_t LENGTH, vm_prot_t DESIRED_ACCESS) - The function `memory_object_data_unlock' is a request that the - memory manager permit at least the desired access to the specified - data cached by the kernel. A call to `memory_object_lock_request' - is expected in response. - - The argument MEMORY_OBJECT is the port that represents the memory - object data, as supplied to the kernel in a `vm_map' call. - MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied - to more than one the kernel that has made the request.) OFFSET is - the offset within a memory object to which this call refers. This - will be page aligned. LENGTH is the number of bytes of data, - starting at OFFSET, to which this call refers. This will be an - integral number of memory object pages. DESIRED_ACCESS a - protection value describing the memory access modes which must be - permitted on the specified cached data. One or more of: - `VM_PROT_READ', `VM_PROT_WRITE' or `VM_PROT_EXECUTE'. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -File: mach.info, Node: Memory Object Attributes, Next: Default Memory Manager, Prev: Memory Object Locking, Up: External Memory Management - -6.6 Memory Object Attributes -============================ - - -- Function: kern_return_t memory_object_get_attributes - (memory_object_control_t MEMORY_CONTROL, - boolean_t *OBJECT_READY, boolean_t *MAY_CACHE_OBJECT, - memory_object_copy_strategy_t *COPY_STRATEGY) - The function `memory_object_get_attribute' retrieves the current - attributes associated with the memory object. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a `memory_object_init' call, to which cache management requests may - be issued. If OBJECT_READY is set, the kernel may issue new data - and unlock requests on the associated memory object. If - MAY_CACHE_OBJECT is set, the kernel may keep data associated with - this memory object, even after virtual memory references to it are - gone. COPY_STRATEGY tells how the kernel should copy regions of - the associated memory object. - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -- Function: kern_return_t memory_object_change_attributes - (memory_object_control_t MEMORY_CONTROL, - boolean_t MAY_CACHE_OBJECT, - memory_object_copy_strategy_t COPY_STRATEGY, - mach_port_t REPLY_TO) - The function `memory_object_change_attribute' sets - performance-related attributes for the specified memory object. - If the caching attribute is asserted, the kernel is permitted (and - encouraged) to maintain cached data for this memory object even - after no virtual address space contains this data. - - There are three possible caching strategies: - `MEMORY_OBJECT_COPY_NONE' which specifies that nothing special - should be done when data in the object is copied; - `MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager - should be notified via a `memory_object_copy' call before any part - of the object is copied; and `MEMORY_OBJECT_COPY_DELAY' which - guarantees that the memory manager does not externally modify the - data so that the kernel can use its normal copy-on-write - algorithms. `MEMORY_OBJECT_COPY_DELAY' is the strategy most - commonly used. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a `memory_object_init' call, to which cache management requests may - be issued. If MAY_CACHE_OBJECT is set, the kernel may keep data - associated with this memory object, even after virtual memory - references to it are gone. COPY_STRATEGY tells how the kernel - should copy regions of the associated memory object. REPLY_TO is - a port on which a `memory_object_change_comleted' call will be - issued upon completion of the attribute change, or - `MACH_PORT_NULL' if no acknowledgement is desired. - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -- Function: kern_return_t memory_object_change_completed - (memory_object_t MEMORY_OBJECT, boolean_t MAY_CACHE_OBJECT, - memory_object_copy_strategy_t COPY_STRATEGY) - -- Function: kern_return_t seqnos_memory_object_change_completed - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - boolean_t MAY_CACHE_OBJECT, - memory_object_copy_strategy_t COPY_STRATEGY) - The function `memory_object_change_completed' indicates the - completion of an attribute change call. - - - The following interface is obsoleted by `memory_object_ready' and -`memory_object_change_attributes'. If the old form -`memory_object_set_attributes' is used to make a memory object ready, -the kernel will write back data using the old -`memory_object_data_write' interface rather than -`memory_object_data_return'.. - - -- Function: kern_return_t memory_object_set_attributes - (memory_object_control_t MEMORY_CONTROL, - boolean OBJECT_READY, boolean_t MAY_CACHE_OBJECT, - memory_object_copy_strategy_t COPY_STRATEGY) - The function `memory_object_set_attribute' controls how the the - memory object. The kernel will only make data or unlock requests - when the ready attribute is asserted. If the caching attribute is - asserted, the kernel is permitted (and encouraged) to maintain - cached data for this memory object even after no virtual address - space contains this data. - - There are three possible caching strategies: - `MEMORY_OBJECT_COPY_NONE' which specifies that nothing special - should be done when data in the object is copied; - `MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager - should be notified via a `memory_object_copy' call before any part - of the object is copied; and `MEMORY_OBJECT_COPY_DELAY' which - guarantees that the memory manager does not externally modify the - data so that the kernel can use its normal copy-on-write - algorithms. `MEMORY_OBJECT_COPY_DELAY' is the strategy most - commonly used. - - The argument MEMORY_CONTROL is the port, provided by the kernel in - a `memory_object_init' call, to which cache management requests may - be issued. If OBJECT_READY is set, the kernel may issue new data - and unlock requests on the associated memory object. If - MAY_CACHE_OBJECT is set, the kernel may keep data associated with - this memory object, even after virtual memory references to it are - gone. COPY_STRATEGY tells how the kernel should copy regions of - the associated memory object. - - This routine does not receive a reply message (and consequently - has no return value), so only message transmission errors apply. - - -File: mach.info, Node: Default Memory Manager, Prev: Memory Object Attributes, Up: External Memory Management - -6.7 Default Memory Manager -========================== - - -- Function: kern_return_t vm_set_default_memory_manager (host_t HOST, - mach_port_t *DEFAULT_MANAGER) - The function `vm_set_default_memory_manager' sets the kernel's - default memory manager. It sets the port to which newly-created - temporary memory objects are delivered by `memory_object_create' to - the host. The old memory manager port is returned. If - DEFAULT_MANAGER is `MACH_PORT_NULL' then this routine just returns - the current default manager port without changing it. - - The argument HOST is a task port to the kernel whose default - memory manager is to be changed. DEFAULT_MANAGER is an in/out - parameter. As input, DEFAULT_MANAGER is the port that the new - memory manager is listening on for `memory_object_create' calls. - As output, it is the old default memory manager's port. - - The function returns `KERN_SUCCESS' if the new memory manager is - installed, and `KERN_INVALID_ARGUMENT' if this task does not have - the privileges required for this call. - - -- Function: kern_return_t memory_object_create - (memory_object_t OLD_MEMORY_OBJECT, - memory_object_t NEW_MEMORY_OBJECT, vm_size_t NEW_OBJECT_SIZE, - memory_object_control_t NEW_CONTROL, - memory_object_name_t NEW_NAME, vm_size_t NEW_PAGE_SIZE) - -- Function: kern_return_t seqnos_memory_object_create - (memory_object_t OLD_MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_t NEW_MEMORY_OBJECT, vm_size_t NEW_OBJECT_SIZE, - memory_object_control_t NEW_CONTROL, - memory_object_name_t NEW_NAME, vm_size_t NEW_PAGE_SIZE) - The function `memory_object_create' is a request that the given - memory manager accept responsibility for the given memory object - created by the kernel. This call will only be made to the system - *default memory manager*. The memory object in question initially - consists of zero-filled memory; only memory pages that are - actually written will ever be provided to - `memory_object_data_request' calls, the default memory manager must - use `memory_object_data_unavailable' for any pages that have not - previously been written. - - No reply is expected after this call. Since this call is directed - to the default memory manager, the kernel assumes that it will be - ready to handle data requests to this object and does not need the - confirmation of a `memory_object_set_attributes' call. - - The argument OLD_MEMORY_OBJECT is a memory object provided by the - default memory manager on which the kernel can make - `memory_object_create' calls. NEW_MEMORY_OBJECT is a new memory - object created by the kernel; see synopsis for further - description. Note that all port rights (including receive rights) - are included for the new memory object. NEW_OBJECT_SIZE is the - maximum size of the new object. NEW_CONTROL is a port, created by - the kernel, on which a memory manager may issue cache management - requests for the new object. NEW_NAME a port used by the kernel - to refer to the new memory object data in response to `vm_region' - calls. NEW_PAGE_SIZE is the page size to be used by this kernel. - All data sizes in calls involving this kernel must be an integral - multiple of the page size. Note that different kernels, indicated - by different a `memory_control', may have different page sizes. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -- Function: kern_return_t memory_object_data_initialize - (memory_object_t MEMORY_OBJECT, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT) - -- Function: kern_return_t seqnos_memory_object_data_initialize - (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO, - memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET, - vm_offset_t DATA, vm_size_t DATA_COUNT) - The function `memory_object_data_initialize' provides the memory - manager with initial data for a kernel-created memory object. If - the memory manager already has been supplied data (by a previous - `memory_object_data_initialize', `memory_object_data_write' or - `memory_object_data_return'), then this data should be ignored. - Otherwise, this call behaves exactly as does - `memory_object_data_return' on memory objects created by the kernel - via `memory_object_create' and thus will only be made to default - memory managers. This call will not be made on objects created via - `memory_object_copy'. - - The argument MEMORY_OBJECT the port that represents the memory - object data, as supplied by the kernel in a `memory_object_create' - call. MEMORY_CONTROL is the request port to which a response is - requested. (In the event that a memory object has been supplied - to more than one the kernel that has made the request.) OFFSET is - the offset within a memory object to which this call refers. This - will be page aligned. DATA os the data which has been modified - while cached in physical memory. DATA_COUNT is the amount of data - to be written, in bytes. This will be an integral number of - memory object pages. - - The function should return `KERN_SUCCESS', but since this routine - is called by the kernel, which does not wait for a reply message, - this value is ignored. - - -File: mach.info, Node: Threads and Tasks, Next: Host Interface, Prev: External Memory Management, Up: Top - -7 Threads and Tasks -******************* - -* Menu: - -* Thread Interface:: Manipulating threads. -* Task Interface:: Manipulating tasks. -* Profiling:: Profiling threads and tasks. - - -File: mach.info, Node: Thread Interface, Next: Task Interface, Up: Threads and Tasks - -7.1 Thread Interface -==================== - - -- Data type: thread_t - This is a `mach_port_t' and used to hold the port name of a thread - port that represents the thread. Manipulations of the thread are - implemented as remote procedure calls to the thread port. A - thread can get a port to itself with the `mach_thread_self' system - call. - -* Menu: - -* Thread Creation:: Creating new threads. -* Thread Termination:: Terminating existing threads. -* Thread Information:: How to get informations on threads. -* Thread Settings:: How to set threads related informations. -* Thread Execution:: How to control the thread's machine state. -* Scheduling:: Operations on thread scheduling. -* Thread Special Ports:: How to handle the thread's special ports. -* Exceptions:: Managing exceptions. - - -File: mach.info, Node: Thread Creation, Next: Thread Termination, Up: Thread Interface - -7.1.1 Thread Creation ---------------------- - - -- Function: kern_return_t thread_create (task_t PARENT_TASK, - thread_t *CHILD_THREAD) - The function `thread_create' creates a new thread within the task - specified by PARENT_TASK. The new thread has no processor state, - and has a suspend count of 1. To get a new thread to run, first - `thread_create' is called to get the new thread's identifier, - (CHILD_THREAD). Then `thread_set_state' is called to set a - processor state, and finally `thread_resume' is called to get the - thread scheduled to execute. - - When the thread is created send rights to its thread kernel port - are given to it and returned to the caller in CHILD_THREAD. The - new thread's exception port is set to `MACH_PORT_NULL'. - - The function returns `KERN_SUCCESS' if a new thread has been - created, `KERN_INVALID_ARGUMENT' if PARENT_TASK is not a valid - task and `KERN_RESOURCE_SHORTAGE' if some critical kernel resource - is not available. - - -File: mach.info, Node: Thread Termination, Next: Thread Information, Prev: Thread Creation, Up: Thread Interface - -7.1.2 Thread Termination ------------------------- - - -- Function: kern_return_t thread_terminate (thread_t TARGET_THREAD) - The function `thread_terminate' destroys the thread specified by - TARGET_THREAD. - - The function returns `KERN_SUCCESS' if the thread has been killed - and `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread. - - -File: mach.info, Node: Thread Information, Next: Thread Settings, Prev: Thread Termination, Up: Thread Interface - -7.1.3 Thread Information ------------------------- - - -- Function: thread_t mach_thread_self () - The `mach_thread_self' system call returns the calling thread's - thread port. - - `mach_thread_self' has an effect equivalent to receiving a send - right for the thread port. `mach_thread_self' returns the name of - the send right. In particular, successive calls will increase the - calling task's user-reference count for the send right. - - As a special exception, the kernel will overrun the user reference - count of the thread name port, so that this function can not fail - for that reason. Because of this, the user should not deallocate - the port right if an overrun might have happened. Otherwise the - reference count could drop to zero and the send right be destroyed - while the user still expects to be able to use it. As the kernel - does not make use of the number of extant send rights anyway, this - is safe to do (the thread port itself is not destroyed, even when - there are no send rights anymore). - - The function returns `MACH_PORT_NULL' if a resource shortage - prevented the reception of the send right or if the thread port is - currently null and `MACH_PORT_DEAD' if the thread port is currently - dead. - - -- Function: kern_return_t thread_info (thread_t TARGET_THREAD, - int FLAVOR, thread_info_t THREAD_INFO, - mach_msg_type_number_t *THREAD_INFOCNT) - The function `thread_info' returns the selected information array - for a thread, as specified by FLAVOR. - - THREAD_INFO is an array of integers that is supplied by the caller - and returned filled with specified information. THREAD_INFOCNT is - supplied as the maximum number of integers in THREAD_INFO. On - return, it contains the actual number of integers in THREAD_INFO. - The maximum number of integers returned by any flavor is - `THREAD_INFO_MAX'. - - The type of information returned is defined by FLAVOR, which can - be one of the following: - - `THREAD_BASIC_INFO' - The function returns basic information about the thread, as - defined by `thread_basic_info_t'. This includes the user and - system time, the run state, and scheduling priority. The - number of integers returned is `THREAD_BASIC_INFO_COUNT'. - - `THREAD_SCHED_INFO' - The function returns information about the schduling policy - for the thread as defined by `thread_sched_info_t'. The - number of integers returned is `THREAD_SCHED_INFO_COUNT'. - - The function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread or FLAVOR - is not recognized. The function returns `MIG_ARRAY_TOO_LARGE' if - the returned info array is too large for THREAD_INFO. In this - case, THREAD_INFO is filled as much as possible and THREAD_INFOCNT - is set to the number of elements that would have been returned if - there were enough room. - - -- Data type: struct thread_basic_info - This structure is returned in THREAD_INFO by the `thread_info' - function and provides basic information about the thread. You can - cast a variable of type `thread_info_t' to a pointer of this type - if you provided it as the THREAD_INFO parameter for the - `THREAD_BASIC_INFO' flavor of `thread_info'. It has the following - members: - - `time_value_t user_time' - user run time - - `time_value_t system_time' - system run time - - `int cpu_usage' - Scaled cpu usage percentage. The scale factor is - `TH_USAGE_SCALE'. - - `int base_priority' - The base scheduling priority of the thread. - - `int cur_priority' - The current scheduling priority of the thread. - - `integer_t run_state' - The run state of the thread. The possible vlues of this - field are: - `TH_STATE_RUNNING' - The thread is running normally. - - `TH_STATE_STOPPED' - The thread is suspended. - - `TH_STATE_WAITING' - The thread is waiting normally. - - `TH_STATE_UNINTERRUPTIBLE' - The thread is in an uninterruptible wait. - - `TH_STATE_HALTED' - The thread is halted at a clean point. - - `flags' - Various flags. The possible values of this field are: - `TH_FLAGS_SWAPPED' - The thread is swapped out. - - `TH_FLAGS_IDLE' - The thread is an idle thread. - - `int suspend_count' - The suspend count for the thread. - - `int sleep_time' - The number of seconds that the thread has been sleeping. - - `time_value_t creation_time' - The time stamp of creation. - - -- Data type: thread_basic_info_t - This is a pointer to a `struct thread_basic_info'. - - -- Data type: struct thread_sched_info - This structure is returned in THREAD_INFO by the `thread_info' - function and provides schedule information about the thread. You - can cast a variable of type `thread_info_t' to a pointer of this - type if you provided it as the THREAD_INFO parameter for the - `THREAD_SCHED_INFO' flavor of `thread_info'. It has the following - members: - - `int policy' - The scheduling policy of the thread, *Note Scheduling - Policy::. - - `integer_t data' - Policy-dependent scheduling information, *Note Scheduling - Policy::. - - `int base_priority' - The base scheduling priority of the thread. - - `int max_priority' - The maximum scheduling priority of the thread. - - `int cur_priority' - The current scheduling priority of the thread. - - `int depressed' - `TRUE' if the thread is depressed. - - `int depress_priority' - The priority the thread was depressed from. - - -- Data type: thread_sched_info_t - This is a pointer to a `struct thread_sched_info'. - - -File: mach.info, Node: Thread Settings, Next: Thread Execution, Prev: Thread Information, Up: Thread Interface - -7.1.4 Thread Settings ---------------------- - - -- Function: kern_return_t thread_wire (host_priv_t HOST_PRIV, - thread_t THREAD, boolean_t WIRED) - The function `thread_wire' controls the VM privilege level of the - thread THREAD. A VM-privileged thread never waits inside the - kernel for memory allocation from the kernel's free list of pages - or for allocation of a kernel stack. - - Threads that are part of the default pageout path should be - VM-privileged, to prevent system deadlocks. Threads that are not - part of the default pageout path should not be VM-privileged, to - prevent the kernel's free list of pages from being exhausted. - - The functions returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_ARGUMENT' if HOST_PRIV or THREAD was invalid. - - The `thread_wire' call is actually an RPC to HOST_PRIV, normally a - send right for a privileged host port, but potentially any send - right. In addition to the normal diagnostic return codes from the - call's server (normally the kernel), the call may return `mach_msg' - return codes. - - -File: mach.info, Node: Thread Execution, Next: Scheduling, Prev: Thread Settings, Up: Thread Interface - -7.1.5 Thread Execution ----------------------- - - -- Function: kern_return_t thread_suspend (thread_t TARGET_THREAD) - Increments the thread's suspend count and prevents the thread from - executing any more user level instructions. In this context a user - level instruction is either a machine instruction executed in user - mode or a system trap instruction including page faults. Thus if - a thread is currently executing within a system trap the kernel - code may continue to execute until it reaches the system return - code or it may supend within the kernel code. In either case, - when the thread is resumed the system trap will return. This - could cause unpredictible results if the user did a suspend and - then altered the user state of the thread in order to change its - direction upon a resume. The call `thread_abort' is provided to - allow the user to abort any system call that is in progress in a - predictable way. - - The suspend count may become greater than one with the effect that - it will take more than one resume call to restart the thread. - - The function returns `KERN_SUCCESS' if the thread has been - suspended and `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a - thread. - - -- Function: kern_return_t thread_resume (thread_t TARGET_THREAD) - Decrements the threads's suspend count. If the count becomes zero - the thread is resumed. If it is still positive, the thread is left - suspended. The suspend count may not become negative. - - The function returns `KERN_SUCCESS' if the thread has been resumed, - `KERN_FAILURE' if the suspend count is already zero and - `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread. - - -- Function: kern_return_t thread_abort (thread_t TARGET_THREAD) - The function `thread_abort' aborts the kernel primitives: - `mach_msg', `msg_send', `msg_receive' and `msg_rpc' and - page-faults, making the call return a code indicating that it was - interrupted. The call is interrupted whether or not the thread - (or task containing it) is currently suspended. If it is - supsended, the thread receives the interupt when it is resumed. - - A thread will retry an aborted page-fault if its state is not - modified before it is resumed. `msg_send' returns - `SEND_INTERRUPTED'; `msg_receive' returns `RCV_INTERRUPTED'; - `msg_rpc' returns either `SEND_INTERRUPTED' or `RCV_INTERRUPTED', - depending on which half of the RPC was interrupted. - - The main reason for this primitive is to allow one thread to - cleanly stop another thread in a manner that will allow the future - execution of the target thread to be controlled in a predictable - way. `thread_suspend' keeps the target thread from executing any - further instructions at the user level, including the return from - a system call. `thread_get_state'/`thread_set_state' allows the - examination or modification of the user state of a target thread. - However, if a suspended thread was executing within a system call, - it also has associated with it a kernel state. This kernel state - can not be modified by `thread_set_state' with the result that - when the thread is resumed the system call may return changing the - user state and possibly user memory. `thread_abort' aborts the - kernel call from the target thread's point of view by resetting - the kernel state so that the thread will resume execution at the - system call return with the return code value set to one of the - interrupted codes. The system call itself will either be entirely - completed or entirely aborted, depending on the precise moment at - which the abort was received. Thus if the thread's user state has - been changed by `thread_set_state', it will not be modified by any - unexpected system call side effects. - - For example to simulate a Unix signal, the following sequence of - calls may be used: - - 1. `thread_suspend': Stops the thread. - - 2. `thread_abort': Interrupts any system call in progress, - setting the return value to `interrupted'. Since the thread - is stopped, it will not return to user code. - - 3. `thread_set_state': Alters thread's state to simulate a - procedure call to the signal handler - - 4. `thread_resume': Resumes execution at the signal handler. If - the thread's stack has been correctly set up, the thread may - return to the interrupted system call. (Of course, the code - to push an extra stack frame and change the registers is VERY - machine-dependent.) - - Calling `thread_abort' on a non-suspended thread is pretty risky, - since it is very difficult to know exactly what system trap, if - any, the thread might be executing and whether an interrupt return - would cause the thread to do something useful. - - The function returns `KERN_SUCCESS' if the thread received an - interrupt and `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a - thread. - - -- Function: kern_return_t thread_get_state (thread_t TARGET_THREAD, - int FLAVOR, thread_state_t OLD_STATE, - mach_msg_type_number_t *OLD_STATECNT) - The function `thread_get_state' returns the execution state (e.g. - the machine registers) of TARGET_THREAD as specified by FLAVOR. - The OLD_STATE is an array of integers that is provided by the - caller and returned filled with the specified information. - OLD_STATECNT is input set to the maximum number of integers in - OLD_STATE and returned equal to the actual number of integers in - OLD_STATE. - - TARGET_THREAD may not be `mach_thread_self()'. - - The definition of the state structures can be found in - `machine/thread_status.h'. - - The function returns `KERN_SUCCESS' if the state has been returned, - `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread or is - `mach_thread_self' or FLAVOR is unrecogized for this machine. The - function returns `MIG_ARRAY_TOO_LARGE' if the returned state is - too large for OLD_STATE. In this case, OLD_STATE is filled as - much as possible and OLD_STATECNT is set to the number of elements - that would have been returned if there were enough room. - - -- Function: kern_return_t thread_set_state (thread_t TARGET_THREAD, - int FLAVOR, thread_state_t NEW_STATE, - mach_msg_type_number_t NEW_STATE_COUNT) - The function `thread_set_state' sets the execution state (e.g. the - machine registers) of TARGET_THREAD as specified by FLAVOR. The - NEW_STATE is an array of integers. NEW_STATE_COUNT is the number - of elements in NEW_STATE. The entire set of registers is reset. - This will do unpredictable things if TARGET_THREAD is not - suspended. - - TARGET_THREAD may not be `mach_thread_self'. - - The definition of the state structures can be found in - `machine/thread_status.h'. - - The function returns `KERN_SUCCESS' if the state has been set and - `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread or is - `mach_thread_self' or FLAVOR is unrecogized for this machine. - - -File: mach.info, Node: Scheduling, Next: Thread Special Ports, Prev: Thread Execution, Up: Thread Interface - -7.1.6 Scheduling ----------------- - -* Menu: - -* Thread Priority:: Changing the priority of a thread. -* Hand-Off Scheduling:: Switching to a new thread. -* Scheduling Policy:: Setting the scheduling policy. - - -File: mach.info, Node: Thread Priority, Next: Hand-Off Scheduling, Up: Scheduling - -7.1.6.1 Thread Priority -....................... - -Threads have three priorities associated with them by the system, a -priority, a maximum priority, and a scheduled priority. The scheduled -priority is used to make scheduling decisions about the thread. It is -determined from the priority by the policy (for timesharing, this means -adding an increment derived from cpu usage). The priority can be set -under user control, but may never exceed the maximum priority. Changing -the maximum priority requires presentation of the control port for the -thread's processor set; since the control port for the default processor -set is privileged, users cannot raise their maximum priority to unfairly -compete with other users on that set. Newly created threads obtain -their priority from their task and their max priority from the thread. - - -- Function: kern_return_t thread_priority (thread_t THREAD, - int PRORITY, boolean_t SET_MAX) - The function `thread_priority' changes the priority and optionally - the maximum priority of THREAD. Priorities range from 0 to 31, - where lower numbers denote higher priorities. If the new priority - is higher than the priority of the current thread, preemption may - occur as a result of this call. The maximum priority of the - thread is also set if SET_MAX is `TRUE'. This call will fail if - PRIORITY is greater than the current maximum priority of the - thread. As a result, this call can only lower the value of a - thread's maximum priority. - - The functions returns `KERN_SUCCESS' if the operation completed - successfully, `KERN_INVALID_ARGUMENT' if THREAD is not a thread or - PRIORITY is out of range (not in 0..31), and `KERN_FAILURE' if the - requested operation would violate the thread's maximum priority - (thread_priority). - - -- Function: kern_return_t thread_max_priority (thread_t THREAD, - processor_set_t PROCESSOR_SET, int PRIORITY) - The function `thread_max_priority' changes the maximum priority of - the thread. Because it requires presentation of the corresponding - processor set port, this call can reset the maximum priority to any - legal value. - - The functions returns `KERN_SUCCESS' if the operation completed - successfully, `KERN_INVALID_ARGUMENT' if THREAD is not a thread or - PROCESSOR_SET is not a control port for a processor set or - PRIORITY is out of range (not in 0..31), and `KERN_FAILURE' if the - thread is not assigned to the processor set whose control port was - presented. - - -File: mach.info, Node: Hand-Off Scheduling, Next: Scheduling Policy, Prev: Thread Priority, Up: Scheduling - -7.1.6.2 Hand-Off Scheduling -........................... - - -- Function: kern_return_t thread_switch (thread_t NEW_THREAD, - int OPTION, int TIME) - The function `thread_switch' provides low-level access to the - scheduler's context switching code. NEW_THREAD is a hint that - implements hand-off scheduling. The operating system will attempt - to switch directly to the new thread (by passing the normal logic - that selects the next thread to run) if possible. Since this is a - hint, it may be incorrect; it is ignored if it doesn't specify a - thread on the same host as the current thread or if that thread - can't be switched to (i.e., not runnable or already running on - another processor). In this case, the normal logic to select the - next thread to run is used; the current thread may continue - running if there is no other appropriate thread to run. - - Options for OPTION are defined in `mach/thread_switch.h' and - specify the interpretation of TIME. The possible values for - OPTION are: - - `SWITCH_OPTION_NONE' - No options, the time argument is ignored. - - `SWITCH_OPTION_WAIT' - The thread is blocked for the specified time. This can be - aborted by `thread_abort'. - - `SWITCH_OPTION_DEPRESS' - The thread's priority is depressed to the lowest possible - value for the specified time. This can be aborted by - `thread_depress_abort'. This depression is independent of - operations that change the thread's priority (e.g. - `thread_priority' will not abort the depression). The - minimum time and units of time can be obtained as the - `min_timeout' value from `host_info'. The depression is also - aborted when the current thread is next run (either via - handoff scheduling or because the processor set has nothing - better to do). - - `thread_switch' is often called when the current thread can proceed - no further for some reason; the various options and arguments allow - information about this reason to be transmitted to the kernel. The - NEW_THREAD argument (handoff scheduling) is useful when the - identity of the thread that must make progress before the current - thread runs again is known. The `WAIT' option is used when the - amount of time that the current thread must wait before it can do - anything useful can be estimated and is fairly long. The - `DEPRESS' option is used when the amount of time that must be - waited is fairly short, especially when the identity of the thread - that is being waited for is not known. - - Users should beware of calling `thread_switch' with an invalid hint - (e.g. `MACH_PORT_NULL') and no option. Because the time-sharing - scheduler varies the priority of threads based on usage, this may - result in a waste of cpu time if the thread that must be run is of - lower priority. The use of the `DEPRESS' option in this situation - is highly recommended. - - `thread_switch' ignores policies. Users relying on the preemption - semantics of a fixed time policy should be aware that - `thread_switch' ignores these semantics; it will run the specified - NEW_THREAD indepent of its priority and the priority of any other - threads that could be run instead. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_ARGUMENT' if THREAD is not a thread or OPTION is not - a recognized option, and `KERN_FAILURE' if `kern_depress_abort' - failed because the thread was not depressed. - - -- Function: kern_return_t thread_depress_abort (thread_t THREAD) - The function `thread_depress_abort' cancels any priority depression - for THREAD caused by a `swtch_pri' or `thread_switch' call. - - The function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if THREAD is not a valid thread. - - -- Function: boolean_t swtch () - The system trap `swtch' attempts to switch the current thread off - the processor. The return value indicates if more than the current - thread is running in the processor set. This is useful for lock - management routines. - - The call returns `FALSE' if the thread is justified in becoming a - resource hog by continuing to spin because there's nothing else - useful that the processor could do. `TRUE' is returned if the - thread should make one more check on the lock and then be a good - citizen and really suspend. - - -- Function: boolean_t swtch_pri (int PRIORITY) - The system trap `swtch_pri' attempts to switch the current thread - off the processor as `swtch' does, but depressing the priority of - the thread to the minimum possible value during the time. - PRIORITY is not used currently. - - The return value is as for `swtch'. - - -File: mach.info, Node: Scheduling Policy, Prev: Hand-Off Scheduling, Up: Scheduling - -7.1.6.3 Scheduling Policy -......................... - - -- Function: kern_return_t thread_policy (thread_t THREAD, int POLICY, - int DATA) - The function `thread_policy' changes the scheduling policy for - THREAD to POLICY. - - DATA is policy-dependent scheduling information. There are - currently two supported policies: `POLICY_TIMESHARE' and - `POLICY_FIXEDPRI' defined in `mach/policy.h'; this file is - included by `mach.h'. DATA is meaningless for timesharing, but is - the quantum to be used (in milliseconds) for the fixed priority - policy. To be meaningful, this quantum must be a multiple of the - basic system quantum (min_quantum) which can be obtained from - `host_info'. The system will always round up to the next multiple - of the quantum. - - Processor sets may restrict the allowed policies, so this call - will fail if the processor set to which THREAD is currently - assigned does not permit POLICY. - - The function returns `KERN_SUCCESS' if the call succeeded. - `KERN_INVALID_ARGUMENT' if THREAD is not a thread or POLICY is not - a recognized policy, and `KERN_FAILURE' if the processor set to - which THREAD is currently assigned does not permit POLICY. - - -File: mach.info, Node: Thread Special Ports, Next: Exceptions, Prev: Scheduling, Up: Thread Interface - -7.1.7 Thread Special Ports --------------------------- - - -- Function: kern_return_t thread_get_special_port (thread_t THREAD, - int WHICH_PORT, mach_port_t *SPECIAL_PORT) - The function `thread_get_special_port' returns send rights to one - of a set of special ports for the thread specified by THREAD. - - The possible values for WHICH_PORT are `THREAD_KERNEL_PORT' and - `THREAD_EXCEPTION_PORT'. A thread also has access to its task's - special ports. - - The function returns `KERN_SUCCESS' if the port was returned and - `KERN_INVALID_ARGUMENT' if THREAD is not a thread or WHICH_PORT is - an invalid port selector. - - -- Function: kern_return_t thread_get_kernel_port (thread_t THREAD, - mach_port_t *KERNEL_PORT) - The function `thread_get_kernel_port' is equivalent to the function - `thread_get_special_port' with the WHICH_PORT argument set to - `THREAD_KERNEL_PORT'. - - -- Function: kern_return_t thread_get_exception_port (thread_t THREAD, - mach_port_t *EXCEPTION_PORT) - The function `thread_get_exception_port' is equivalent to the - function `thread_get_special_port' with the WHICH_PORT argument - set to `THREAD_EXCEPTION_PORT'. - - -- Function: kern_return_t thread_set_special_port (thread_t THREAD, - int WHICH_PORT, mach_port_t SPECIAL_PORT) - The function `thread_set_special_port' sets one of a set of special - ports for the thread specified by THREAD. - - The possible values for WHICH_PORT are `THREAD_KERNEL_PORT' and - `THREAD_EXCEPTION_PORT'. A thread also has access to its task's - special ports. - - The function returns `KERN_SUCCESS' if the port was set and - `KERN_INVALID_ARGUMENT' if THREAD is not a thread or WHICH_PORT is - an invalid port selector. - - -- Function: kern_return_t thread_set_kernel_port (thread_t THREAD, - mach_port_t KERNEL_PORT) - The function `thread_set_kernel_port' is equivalent to the function - `thread_set_special_port' with the WHICH_PORT argument set to - `THREAD_KERNEL_PORT'. - - -- Function: kern_return_t thread_set_exception_port (thread_t THREAD, - mach_port_t EXCEPTION_PORT) - The function `thread_set_exception_port' is equivalent to the - function `thread_set_special_port' with the WHICH_PORT argument - set to `THREAD_EXCEPTION_PORT'. - - -File: mach.info, Node: Exceptions, Prev: Thread Special Ports, Up: Thread Interface - -7.1.8 Exceptions ----------------- - - -- Function: kern_return_t catch_exception_raise - (mach_port_t EXCEPTION_PORT, thread_t THREAD, task_t TASK, - int EXCEPTION, int CODE, int SUBCODE) - XXX Fixme - - -- Function: kern_return_t exception_raise - (mach_port_t EXCEPTION_PORT, mach_port_t THREAD, - mach_port_t TASK, integer_t EXCEPTION, integer_t CODE, - integer_t SUBCODE) - XXX Fixme - - -- Function: kern_return_t evc_wait (unsigned int EVENT) - The system trap `evc_wait' makes the calling thread wait for the - event specified by EVENT. - - The call returns `KERN_SUCCESS' if the event has occured, - `KERN_NO_SPACE' if another thread is waiting for the same event and - `KERN_INVALID_ARGUMENT' if the event object is invalid. - - -File: mach.info, Node: Task Interface, Next: Profiling, Prev: Thread Interface, Up: Threads and Tasks - -7.2 Task Interface -================== - - -- Data type: task_t - This is a `mach_port_t' and used to hold the port name of a task - port that represents the thread. Manipulations of the task are - implemented as remote procedure calls to the task port. A task - can get a port to itself with the `mach_task_self' system call. - - The task port name is also used to identify the task's IPC space - (*note Port Manipulation Interface::) and the task's virtual - memory map (*note Virtual Memory Interface::). - -* Menu: - -* Task Creation:: Creating tasks. -* Task Termination:: Terminating tasks. -* Task Information:: Informations on tasks. -* Task Execution:: Thread scheduling in a task. -* Task Special Ports:: How to get and set the task's special ports. -* Syscall Emulation:: How to emulate system calls. - - -File: mach.info, Node: Task Creation, Next: Task Termination, Up: Task Interface - -7.2.1 Task Creation -------------------- - - -- Function: kern_return_t task_create (task_t PARENT_TASK, - boolean_t INHERIT_MEMORY, task_t *CHILD_TASK) - The function `task_create' creates a new task from PARENT_TASK; - the resulting task (CHILD_TASK) acquires shared or copied parts of - the parent's address space (see `vm_inherit'). The child task - initially contains no threads. - - If INHERIT_MEMORY is set, the child task's address space is built - from the parent task according to its memory inheritance values; - otherwise, the child task is given an empty address space. - - The child task gets the three special ports created or copied for - it at task creation. The `TASK_KERNEL_PORT' is created and send - rights for it are given to the child and returned to the caller. - The `TASK_BOOTSTRAP_PORT' and the `TASK_EXCEPTION_PORT' are - inherited from the parent task. The new task can get send rights - to these ports with the call `task_get_special_port'. - - The function returns `KERN_SUCCESS' if a new task has been created, - `KERN_INVALID_ARGUMENT' if PARENT_TASK is not a valid task port - and `KERN_RESOURCE_SHORTAGE' if some critical kernel resource is - unavailable. - - -File: mach.info, Node: Task Termination, Next: Task Information, Prev: Task Creation, Up: Task Interface - -7.2.2 Task Termination ----------------------- - - -- Function: kern_return_t task_terminate (task_t TARGET_TASK) - The function `task_terminate' destroys the task specified by - TARGET_TASK and all its threads. All resources that are used only - by this task are freed. Any port to which this task has receive - and ownership rights is destroyed. - - The function returns `KERN_SUCCESS' if the task has been killed, - `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task. - - -File: mach.info, Node: Task Information, Next: Task Execution, Prev: Task Termination, Up: Task Interface - -7.2.3 Task Information ----------------------- - - -- Function: task_t mach_task_self () - The `mach_task_self' system call returns the calling thread's task - port. - - `mach_task_self' has an effect equivalent to receiving a send right - for the task port. `mach_task_self' returns the name of the send - right. In particular, successive calls will increase the calling - task's user-reference count for the send right. - - As a special exception, the kernel will overrun the user reference - count of the task name port, so that this function can not fail - for that reason. Because of this, the user should not deallocate - the port right if an overrun might have happened. Otherwise the - reference count could drop to zero and the send right be destroyed - while the user still expects to be able to use it. As the kernel - does not make use of the number of extant send rights anyway, this - is safe to do (the task port itself is not destroyed, even when - there are no send rights anymore). - - The funcion returns `MACH_PORT_NULL' if a resource shortage - prevented the reception of the send right, `MACH_PORT_NULL' if the - task port is currently null, `MACH_PORT_DEAD' if the task port is - currently dead. - - -- Function: kern_return_t task_threads (task_t TARGET_TASK, - thread_array_t *THREAD_LIST, - mach_msg_type_number_t *THREAD_COUNT) - The function `task_threads' gets send rights to the kernel port for - each thread contained in TARGET_TASK. THREAD_LIST is an array - that is created as a result of this call. The caller may wish to - `vm_deallocate' this array when the data is no longer needed. - - The function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task. - - -- Function: kern_return_t task_info (task_t TARGET_TASK, int FLAVOR, - task_info_t TASK_INFO, - mach_msg_type_number_t *TASK_INFO_COUNT) - The function `task_info' returns the selected information array for - a task, as specified by FLAVOR. TASK_INFO is an array of integers - that is supplied by the caller, and filled with specified - information. TASK_INFO_COUNT is supplied as the maximum number of - integers in TASK_INFO. On return, it contains the actual number - of integers in TASK_INFO. The maximum number of integers returned - by any flavor is `TASK_INFO_MAX'. - - The type of information returned is defined by FLAVOR, which can - be one of the following: - - `TASK_BASIC_INFO' - The function returns basic information about the task, as - defined by `task_basic_info_t'. This includes the user and - system time and memory consumption. The number of integers - returned is `TASK_BASIC_INFO_COUNT'. - - `TASK_EVENTS_INFO' - The function returns information about events for the task as - defined by `thread_sched_info_t'. This includes statistics - about virtual memory and IPC events like pageouts, pageins - and messages sent and received. The number of integers - returned is `TASK_EVENTS_INFO_COUNT'. - - `TASK_THREAD_TIMES_INFO' - The function returns information about the total time for - live threads as defined by `task_thread_times_info_t'. The - number of integers returned is `TASK_THREAD_TIMES_INFO_COUNT'. - - The function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a thread or FLAVOR - is not recognized. The function returns `MIG_ARRAY_TOO_LARGE' if - the returned info array is too large for TASK_INFO. In this case, - TASK_INFO is filled as much as possible and TASK_INFOCNT is set to - the number of elements that would have been returned if there were - enough room. - - -- Data type: struct task_basic_info - This structure is returned in TASK_INFO by the `task_info' - function and provides basic information about the task. You can - cast a variable of type `task_info_t' to a pointer of this type if - you provided it as the TASK_INFO parameter for the - `TASK_BASIC_INFO' flavor of `task_info'. It has the following - members: - - `integer_t suspend_count' - suspend count for task - - `integer_t base_priority' - base scheduling priority - - `vm_size_t virtual_size' - number of virtual pages - - `vm_size_t resident_size' - number of resident pages - - `time_value_t user_time' - total user run time for terminated threads - - `time_value_t system_time' - total system run time for terminated threads - - `time_value_t creation_time' - creation time stamp - - -- Data type: task_basic_info_t - This is a pointer to a `struct task_basic_info'. - - -- Data type: struct task_events_info - This structure is returned in TASK_INFO by the `task_info' - function and provides event statistics for the task. You can cast - a variable of type `task_info_t' to a pointer of this type if you - provided it as the TASK_INFO parameter for the `TASK_EVENTS_INFO' - flavor of `task_info'. It has the following members: - - `natural_t faults' - number of page faults - - `natural_t zero_fills' - number of zero fill pages - - `natural_t reactivations' - number of reactivated pages - - `natural_t pageins' - number of actual pageins - - `natural_t cow_faults' - number of copy-on-write faults - - `natural_t messages_sent' - number of messages sent - - `natural_t messages_received' - number of messages received - - -- Data type: task_events_info_t - This is a pointer to a `struct task_events_info'. - - -- Data type: struct task_thread_times_info - This structure is returned in TASK_INFO by the `task_info' - function and provides event statistics for the task. You can cast - a variable of type `task_info_t' to a pointer of this type if you - provided it as the TASK_INFO parameter for the - `TASK_THREAD_TIMES_INFO' flavor of `task_info'. It has the - following members: - - `time_value_t user_time' - total user run time for live threads - - `time_value_t system_time' - total system run time for live threads - - -- Data type: task_thread_times_info_t - This is a pointer to a `struct task_thread_times_info'. - - -File: mach.info, Node: Task Execution, Next: Task Special Ports, Prev: Task Information, Up: Task Interface - -7.2.4 Task Execution --------------------- - - -- Function: kern_return_t task_suspend (task_t TARGET_TASK) - The function `task_suspend' increments the task's suspend count and - stops all threads in the task. As long as the suspend count is - positive newly created threads will not run. This call does not - return until all threads are suspended. - - The count may become greater than one, with the effect that it - will take more than one resume call to restart the task. - - The function returns `KERN_SUCCESS' if the task has been suspended - and `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task. - - -- Function: kern_return_t task_resume (task_t TARGET_TASK) - The function `task_resume' decrements the task's suspend count. If - it becomes zero, all threads with zero suspend counts in the task - are resumed. The count may not become negative. - - The function returns `KERN_SUCCESS' if the task has been resumed, - `KERN_FAILURE' if the suspend count is already at zero and - `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task. - - -- Function: kern_return_t task_priority (task_t TASK, int PRIORITY, - boolean_t CHANGE_THREADS) - The priority of a task is used only for creation of new threads; a - new thread's priority is set to the enclosing task's priority. - `task_priority' changes this task priority. It also sets the - priorities of all threads in the task to this new priority if - CHANGE_THREADS is `TRUE'. Existing threads are not affected - otherwise. If this priority change violates the maximum priority - of some threads, as many threads as possible will be changed and - an error code will be returned. - - The function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_ARGUMENT' if TASK is not a task, or PRIORITY is not - a valid priority and `KERN_FAILURE' if CHANGE_THREADS was `TRUE' - and the attempt to change the priority of at least one existing - thread failed because the new priority would have exceeded that - thread's maximum priority. - - -- Function: kern_return_t task_ras_control (task_t TARGET_TASK, - vm_address_t START_PC, vm_address_t END_PC, int FLAVOR) - The function `task_ras_control' manipulates a task's set of - restartable atomic sequences. If a sequence is installed, and any - thread in the task is preempted within the range - [START_PC,END_PC], then the thread is resumed at START_PC. This - enables applications to build atomic sequences which, when - executed to completion, will have executed atomically. - Restartable atomic sequences are intended to be used on systems - that do not have hardware support for low-overhead atomic - primitives. - - As a thread can be rolled-back, the code in the sequence should - have no side effects other than a final store at END_PC. The - kernel does not guarantee that the sequence is restartable. It - assumes the application knows what it's doing. - - A task may have a finite number of atomic sequences that is - defined at compile time. - - The flavor specifices the particular operation that should be - applied to this restartable atomic sequence. Possible values for - flavor can be: - - `TASK_RAS_CONTROL_PURGE_ALL' - Remove all registered sequences for this task. - - `TASK_RAS_CONTROL_PURGE_ONE' - Remove the named registered sequence for this task. - - `TASK_RAS_CONTROL_PURGE_ALL_AND_INSTALL_ONE' - Atomically remove all registered sequences and install the - named sequence. - - `TASK_RAS_CONTROL_INSTALL_ONE' - Install this sequence. - - The function returns `KERN_SUCCESS' if the operation has been - performed, `KERN_INVALID_ADDRESS' if the START_PC or END_PC values - are not a valid address for the requested operation (for example, - it is invalid to purge a sequence that has not been registered), - `KERN_RESOURCE_SHORTAGE' if an attempt was made to install more - restartable atomic sequences for a task than can be supported by - the kernel, `KERN_INVALID_VALUE' if a bad flavor was specified, - `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task and - `KERN_FAILURE' if the call is not not supported on this - configuration. - - -File: mach.info, Node: Task Special Ports, Next: Syscall Emulation, Prev: Task Execution, Up: Task Interface - -7.2.5 Task Special Ports ------------------------- - - -- Function: kern_return_t task_get_special_port (task_t TASK, - int WHICH_PORT, mach_port_t *SPECIAL_PORT) - The function `task_get_special_port' returns send rights to one of - a set of special ports for the task specified by TASK. - - The special ports associated with a task are the kernel port - (`TASK_KERNEL_PORT'), the bootstrap port (`TASK_BOOTSTRAP_PORT') - and the exception port (`TASK_EXCEPTION_PORT'). The bootstrap - port is a port to which a task may send a message requesting other - system service ports. This port is not used by the kernel. The - task's exception port is the port to which messages are sent by - the kernel when an exception occurs and the thread causing the - exception has no exception port of its own. - - The following macros to call `task_get_special_port' for a specific - port are defined in `mach/task_special_ports.h': - `task_get_exception_port' and `task_get_bootstrap_port'. - - The function returns `KERN_SUCCESS' if the port was returned and - `KERN_INVALID_ARGUMENT' if TASK is not a task or WHICH_PORT is an - invalid port selector. - - -- Function: kern_return_t task_get_kernel_port (task_t TASK, - mach_port_t *KERNEL_PORT) - The function `task_get_kernel_port' is equivalent to the function - `task_get_special_port' with the WHICH_PORT argument set to - `TASK_KERNEL_PORT'. - - -- Function: kern_return_t task_get_exception_port (task_t TASK, - mach_port_t *EXCEPTION_PORT) - The function `task_get_exception_port' is equivalent to the - function `task_get_special_port' with the WHICH_PORT argument set - to `TASK_EXCEPTION_PORT'. - - -- Function: kern_return_t task_get_bootstrap_port (task_t TASK, - mach_port_t *BOOTSTRAP_PORT) - The function `task_get_bootstrap_port' is equivalent to the - function `task_get_special_port' with the WHICH_PORT argument set - to `TASK_BOOTSTRAP_PORT'. - - -- Function: kern_return_t task_set_special_port (task_t TASK, - int WHICH_PORT, mach_port_t SPECIAL_PORT) - The function `thread_set_special_port' sets one of a set of special - ports for the task specified by TASK. - - The special ports associated with a task are the kernel port - (`TASK_KERNEL_PORT'), the bootstrap port (`TASK_BOOTSTRAP_PORT') - and the exception port (`TASK_EXCEPTION_PORT'). The bootstrap - port is a port to which a thread may send a message requesting - other system service ports. This port is not used by the kernel. - The task's exception port is the port to which messages are sent - by the kernel when an exception occurs and the thread causing the - exception has no exception port of its own. - - The function returns `KERN_SUCCESS' if the port was set and - `KERN_INVALID_ARGUMENT' if TASK is not a task or WHICH_PORT is an - invalid port selector. - - -- Function: kern_return_t task_set_kernel_port (task_t TASK, - mach_port_t KERNEL_PORT) - The function `task_set_kernel_port' is equivalent to the function - `task_set_special_port' with the WHICH_PORT argument set to - `TASK_KERNEL_PORT'. - - -- Function: kern_return_t task_set_exception_port (task_t TASK, - mach_port_t EXCEPTION_PORT) - The function `task_set_exception_port' is equivalent to the - function `task_set_special_port' with the WHICH_PORT argument set - to `TASK_EXCEPTION_PORT'. - - -- Function: kern_return_t task_set_bootstrap_port (task_t TASK, - mach_port_t BOOTSTRAP_PORT) - The function `task_set_bootstrap_port' is equivalent to the - function `task_set_special_port' with the WHICH_PORT argument set - to `TASK_BOOTSTRAP_PORT'. - - -File: mach.info, Node: Syscall Emulation, Prev: Task Special Ports, Up: Task Interface - -7.2.6 Syscall Emulation ------------------------ - - -- Function: kern_return_t task_get_emulation_vector (task_t TASK, - int *VECTOR_START, emulation_vector_t *EMULATION_VECTOR, - mach_msg_type_number_t *EMULATION_VECTOR_COUNT) - The function `task_get_emulation_vector' gets the user-level - handler entry points for all emulated system calls. - - -- Function: kern_return_t task_set_emulation_vector (task_t TASK, - int VECTOR_START, emulation_vector_t EMULATION_VECTOR, - mach_msg_type_number_t EMULATION_VECTOR_COUNT) - The function `task_set_emulation_vector' establishes user-level - handlers for the specified system calls. Non-emulated system - calls are specified with an entry of `EML_ROUTINE_NULL'. System - call emulation handlers are inherited by the childs of TASK. - - -- Function: kern_return_t task_set_emulation (task_t TASK, - vm_address_t ROUTINE_ENTRY_PT, int ROUTINE_NUMBER) - The function `task_set_emulation' establishes a user-level handler - for the specified system call. System call emulation handlers are - inherited by the childs of TASK. - - -File: mach.info, Node: Profiling, Prev: Task Interface, Up: Threads and Tasks - -7.3 Profiling -============= - - -- Function: kern_return_t task_enable_pc_sampling (task_t TASK, - int *TICKS, sampled_pc_flavor_t FLAVOR) - -- Function: kern_return_t thread_enable_pc_sampling (thread_t THREAD, - int *TICKS, sampled_pc_flavor_t FLAVOR) - The function `task_enable_pc_sampling' enables PC sampling for - TASK, the function `thread_enable_pc_sampling' enables PC sampling - for THREAD. The kernel's idea of clock granularity is returned in - TICKS in usecs. (this value should not be trusted). The sampling - flavor is specified by FLAVOR. - - The function returns `KERN_SUCCESS' if the operation is completed - successfully and `KERN_INVALID_ARGUMENT' if THREAD is not a valid - thread. - - -- Function: kern_return_t task_disable_pc_sampling (task_t TASK, - int *SAMPLE_COUNT) - -- Function: kern_return_t thread_disable_pc_sampling - (thread_t THREAD, int *SAMPLE_COUNT) - The function `task_disable_pc_sampling' disables PC sampling for - TASK, the function `thread_disable_pc_sampling' disables PC - sampling for THREAD. The number of sample elements in the kernel - for the thread is returned in SAMPLE_COUNT. - - The function returns `KERN_SUCCESS' if the operation is completed - successfully and `KERN_INVALID_ARGUMENT' if THREAD is not a valid - thread. - - -- Function: kern_return_t task_get_sampled_pcs (task_t TASK, - sampled_pc_seqno_t *SEQNO, sampled_pc_array_t SAMPLED_PCS, - mach_msg_type_number_t *SAMPLE_COUNT) - -- Function: kern_return_t thread_get_sampled_pcs (thread_t THREAD, - sampled_pc_seqno_t *SEQNO, sampled_pc_array_t SAMPLED_PCS, - int *SAMPLE_COUNT) - The function `task_get_sampled_pcs' extracts the PC samples for - TASK, the function `thread_get_sampled_pcs' extracts the PC - samples for THREAD. SEQNO is the sequence number of the sampled - PCs. This is useful for determining when a collector thread has - missed a sample. The sampled PCs for the thread are returned in - SAMPLED_PCS. SAMPLE_COUNT contains the number of sample elements - returned. - - The function returns `KERN_SUCCESS' if the operation is completed - successfully, `KERN_INVALID_ARGUMENT' if THREAD is not a valid - thread and `KERN_FAILURE' if THREAD is not sampled. - - -- Data type: sampled_pc_t - This structure is returned in SAMPLED_PCS by the - `thread_get_sampled_pcs' and `task_get_sampled_pcs' functions and - provides pc samples for threads or tasks. It has the following - members: - - `natural_t id' - A thread-specific unique identifier. - - `vm_offset_t pc' - A pc value. - - `sampled_pc_flavor_t sampletype' - The type of the sample as per flavor. - - -- Data type: sampled_pc_flavor_t - This data type specifies a pc sample flavor, either as argument - passed in FLAVOR to the `thread_enable_pc_sample' and - `thread_disable_pc_sample' functions, or as member `sampletype' in - the `sample_pc_t' data type. The flavor is a bitwise-or of the - possible flavors defined in `mach/pc_sample.h': - - `SAMPLED_PC_PERIODIC' - default - - `SAMPLED_PC_VM_ZFILL_FAULTS' - zero filled fault - - `SAMPLED_PC_VM_REACTIVATION_FAULTS' - reactivation fault - - `SAMPLED_PC_VM_PAGEIN_FAULTS' - pagein fault - - `SAMPLED_PC_VM_COW_FAULTS' - copy-on-write fault - - `SAMPLED_PC_VM_FAULTS_ANY' - any fault - - `SAMPLED_PC_VM_FAULTS' - the bitwise-or of `SAMPLED_PC_VM_ZFILL_FAULTS', - `SAMPLED_PC_VM_REACTIVATION_FAULTS', - `SAMPLED_PC_VM_PAGEIN_FAULTS' and `SAMPLED_PC_VM_COW_FAULTS'. - - -File: mach.info, Node: Host Interface, Next: Processors and Processor Sets, Prev: Threads and Tasks, Up: Top - -8 Host Interface -**************** - -This section describes the Mach interface to a host executing a Mach -kernel. The interface allows to query statistics about a host and -control its behaviour. - - A host is represented by two ports, a name port HOST used to query -information about the host accessible to everyone, and a control port -HOST_PRIV used to manipulate it. For example, you can query the -current time using the name port, but to change the time you need to -send a message to the host control port. - - Everything described in this section is declared in the header file -`mach.h'. - -* Menu: - -* Host Ports:: Ports representing a host. -* Host Information:: Retrieval of information about a host. -* Host Time:: Operations on the time as seen by a host. -* Host Reboot:: Rebooting the system. - - -File: mach.info, Node: Host Ports, Next: Host Information, Up: Host Interface - -8.1 Host Ports -============== - - -- Data type: host_t - This is a `mach_port_t' and used to hold the port name of a host - name port (or short: host port). Any task can get a send right to - the name port of the host running the task using the - `mach_host_self' system call. The name port can be used query - information about the host, for example the current time. - - -- Function: host_t mach_host_self () - The `mach_host_self' system call returns the calling thread's host - name port. It has an effect equivalent to receiving a send right - for the host port. `mach_host_self' returns the name of the send - right. In particular, successive calls will increase the calling - task's user-reference count for the send right. - - As a special exception, the kernel will overrun the user reference - count of the host name port, so that this function can not fail - for that reason. Because of this, the user should not deallocate - the port right if an overrun might have happened. Otherwise the - reference count could drop to zero and the send right be destroyed - while the user still expects to be able to use it. As the kernel - does not make use of the number of extant send rights anyway, this - is safe to do (the host port itself is never destroyed). - - The function returns `MACH_PORT_NULL' if a resource shortage - prevented the reception of the send right. - - This function is also available in `mach/mach_traps.h'. - - -- Data type: host_priv_t - This is a `mach_port_t' and used to hold the port name of a - privileged host control port. A send right to the host control - port is inserted into the first task at bootstrap (*note - Modules::). This is the only way to get access to the host - control port in Mach, so the initial task has to preserve the send - right carefully, moving a copy of it to other privileged tasks if - necessary and denying access to unprivileged tasks. - - -File: mach.info, Node: Host Information, Next: Host Time, Prev: Host Ports, Up: Host Interface - -8.2 Host Information -==================== - - -- Function: kern_return_t host_info (host_t HOST, int FLAVOR, - host_info_t HOST_INFO, - mach_msg_type_number_t *HOST_INFO_COUNT) - The `host_info' function returns various information about HOST. - HOST_INFO is an array of integers that is supplied by the caller. - It will be filled with the requested information. HOST_INFO_COUNT - is supplied as the maximum number of integers in HOST_INFO. On - return, it contains the actual number of integers in HOST_INFO. - The maximum number of integers returned by any flavor is - `HOST_INFO_MAX'. - - The type of information returned is defined by FLAVOR, which can - be one of the following: - - `HOST_BASIC_INFO' - The function returns basic information about the host, as - defined by `host_basic_info_t'. This includes the number of - processors, their type, and the amount of memory installed in - the system. The number of integers returned is - `HOST_BASIC_INFO_COUNT'. For how to get more information - about the processor, see *Note Processor Interface::. - - `HOST_PROCESSOR_SLOTS' - The function returns the numbers of the slots with active - processors in them. The number of integers returned can be - up to `max_cpus', as returned by the `HOST_BASIC_INFO' flavor - of `host_info'. - - `HOST_SCHED_INFO' - The function returns information of interest to schedulers as - defined by `host_sched_info_t'. The number of integers - returned is `HOST_SCHED_INFO_COUNT'. - - The function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if HOST is not a host or FLAVOR is not - recognized. The function returns `MIG_ARRAY_TOO_LARGE' if the - returned info array is too large for HOST_INFO. In this case, - HOST_INFO is filled as much as possible and HOST_INFO_COUNT is set - to the number of elements that would be returned if there were - enough room. - - -- Data type: struct host_basic_info - A pointer to this structure is returned in HOST_INFO by the - `host_info' function and provides basic information about the host. - You can cast a variable of type `host_info_t' to a pointer of this - type if you provided it as the HOST_INFO parameter for the - `HOST_BASIC_INFO' flavor of `host_info'. It has the following - members: - - `int max_cpus' - The maximum number of possible processors for which the - kernel is configured. - - `int avail_cpus' - The number of cpus currently available. - - `vm_size_t memory_size' - The size of physical memory in bytes. - - `cpu_type_t cpu_type' - The type of the master processor. - - `cpu_subtype_t cpu_subtype' - The subtype of the master processor. - - The type and subtype of the individual processors are also - available by `processor_info', see *Note Processor Interface::. - - -- Data type: host_basic_info_t - This is a pointer to a `struct host_basic_info'. - - -- Data type: struct host_sched_info - A pointer to this structure is returned in HOST_INFO by the - `host_info' function and provides information of interest to - schedulers. You can cast a variable of type `host_info_t' to a - pointer of this type if you provided it as the HOST_INFO parameter - for the `HOST_SCHED_INFO' flavor of `host_info'. It has the - following members: - - `int min_timeout' - The minimum timeout and unit of time in milliseconds. - - `int min_quantum' - The minimum quantum and unit of quantum in milliseconds. - - -- Data type: host_sched_info_t - This is a pointer to a `struct host_sched_info'. - - -- Function: kern_return_t host_kernel_version (host_t HOST, - kernel_version_t *VERSION) - The `host_kernel_version' function returns the version string - compiled into the kernel executing on HOST at the time it was - built in the character string VERSION. This string describes the - version of the kernel. The constant `KERNEL_VERSION_MAX' should be - used to dimension storage for the returned string if the - `kernel_version_t' declaration is not used. - - If the version string compiled into the kernel is longer than - `KERNEL_VERSION_MAX', the result is truncated and not necessarily - null-terminated. - - If HOST is not a valid send right to a host port, the function - returns `KERN_INVALID_ARGUMENT'. If VERSION points to - inaccessible memory, it returns `KERN_INVALID_ADDRESS', and - `KERN_SUCCESS' otherwise. - - -- Function: kern_return_t host_get_boot_info (host_priv_t HOST_PRIV, - kernel_boot_info_t BOOT_INFO) - The `host_get_boot_info' function returns the boot-time information - string supplied by the operator to the kernel executing on - HOST_PRIV in the character string BOOT_INFO. The constant - `KERNEL_BOOT_INFO_MAX' should be used to dimension storage for the - returned string if the `kernel_boot_info_t' declaration is not - used. - - If the boot-time information string supplied by the operator is - longer than `KERNEL_BOOT_INFO_MAX', the result is truncated and not - necessarily null-terminated. - - -File: mach.info, Node: Host Time, Next: Host Reboot, Prev: Host Information, Up: Host Interface - -8.3 Host Time -============= - - -- Data type: time_value_t - This is the representation of a time in Mach. It is a `struct - time_value' and consists of the following members: - - `integer_t seconds' - The number of seconds. - - `integer_t microseconds' - The number of microseconds. - -The number of microseconds should always be smaller than -`TIME_MICROS_MAX' (100000). A time with this property is "normalized". -Normalized time values can be manipulated with the following macros: - - -- Macro: time_value_add_usec (time_value_t *VAL, integer_t *MICROS) - Add MICROS microseconds to VAL. If VAL is normalized and MICROS - smaller than `TIME_MICROS_MAX', VAL will be normalized afterwards. - - -- Macro: time_value_add (time_value_t *RESULT, time_value_t *ADDEND) - Add the values in ADDEND to RESULT. If both are normalized, - RESULT will be normalized afterwards. - - A variable of type `time_value_t' can either represent a duration or -a fixed point in time. In the latter case, it shall be interpreted as -the number of seconds and microseconds after the epoch 1. Jan 1970. - - -- Function: kern_return_t host_get_time (host_t HOST, - time_value_t *CURRENT_TIME) - Get the current time as seen by HOST. On success, the time passed - since the epoch is returned in CURRENT_TIME. - - -- Function: kern_return_t host_set_time (host_priv_t HOST_PRIV, - time_value_t NEW_TIME) - Set the time of HOST_PRIV to NEW_TIME. - - -- Function: kern_return_t host_adjust_time (host_priv_t HOST_PRIV, - time_value_t NEW_ADJUSTMENT, time_value_t *OLD_ADJUSTMENT) - Arrange for the current time as seen by HOST_PRIV to be gradually - changed by the adjustment value NEW_ADJUSTMENT, and return the old - adjustment value in OLD_ADJUSTMENT. - - For efficiency, the current time is available through a mapped-time -interface. - - -- Data type: mapped_time_value_t - This structure defines the mapped-time interface. It has the - following members: - - `integer_t seconds' - The number of seconds. - - `integer_t microseconds' - The number of microseconds. - - `integer_t check_seconds' - This is a copy of the seconds value, which must be checked to - protect against a race condition when reading out the two - time values. - - Here is an example how to read out the current time using the -mapped-time interface: - - do - { - secs = mtime->seconds; - usecs = mtime->microseconds; - } - while (secs != mtime->check_seconds); - - -File: mach.info, Node: Host Reboot, Prev: Host Time, Up: Host Interface - -8.4 Host Reboot -=============== - - -- Function: kern_return_t host_reboot (host_priv_t HOST_PRIV, - int OPTIONS) - Reboot the host specified by HOST_PRIV. The argument OPTIONS - specifies the flags. The available flags are defined in - `sys/reboot.h': - - `RB_HALT' - Do not reboot, but halt the machine. - - `RB_DEBUGGER' - Do not reboot, but enter kernel debugger from user space. - - If successful, the function might not return. - - -File: mach.info, Node: Processors and Processor Sets, Next: Device Interface, Prev: Host Interface, Up: Top - -9 Processors and Processor Sets -******************************* - -This section describes the Mach interface to processor sets and -individual processors. The interface allows to group processors into -sets and control the processors and processor sets. - - A processor is not a central part of the interface. It is mostly of -relevance as a part of a processor set. Threads are always assigned to -processor sets, and all processors in a set are equally involved in -executing all threads assigned to that set. - - The processor set is represented by two ports, a name port -PROCESSOR_SET_NAME used to query information about the host accessible -to everyone, and a control port PROCESSOR_SET used to manipulate it. - -* Menu: - -* Processor Set Interface:: How to work with processor sets. -* Processor Interface:: How to work with individual processors. - - -File: mach.info, Node: Processor Set Interface, Next: Processor Interface, Up: Processors and Processor Sets - -9.1 Processor Set Interface -=========================== - -* Menu: - -* Processor Set Ports:: Ports representing a processor set. -* Processor Set Access:: How the processor sets are accessed. -* Processor Set Creation:: How new processor sets are created. -* Processor Set Destruction:: How processor sets are destroyed. -* Tasks and Threads on Sets:: Assigning tasks, threads to processor sets. -* Processor Set Priority:: Specifying the priority of a processor set. -* Processor Set Policy:: Changing the processor set policies. -* Processor Set Info:: Obtaining information about a processor set. - - -File: mach.info, Node: Processor Set Ports, Next: Processor Set Access, Up: Processor Set Interface - -9.1.1 Processor Set Ports -------------------------- - - -- Data type: processor_set_name_t - This is a `mach_port_t' and used to hold the port name of a - processor set name port that names the processor set. Any task - can get a send right to name port of a processor set. The - processor set name port allows to get information about the - processor set. - - -- Data type: processor_set_t - This is a `mach_port_t' and used to hold the port name of a - privileged processor set control port that represents the - processor set. Operations on the processor set are implemented as - remote procedure calls to the processor set port. The processor - set port allows to manipulate the processor set. - - -File: mach.info, Node: Processor Set Access, Next: Processor Set Creation, Prev: Processor Set Ports, Up: Processor Set Interface - -9.1.2 Processor Set Access --------------------------- - - -- Function: kern_return_t host_processor_sets (host_t HOST, - processor_set_name_array_t *PROCESSOR_SETS, - mach_msg_type_number_t *PROCESSOR_SETS_COUNT) - The function `host_processor_sets' gets send rights to the name - port for each processor set currently assigned to HOST. - - `host_processor_set_priv' can be used to obtain the control ports - from these if desired. PROCESSOR_SETS is an array that is created - as a result of this call. The caller may wish to `vm_deallocate' - this array when the data is no longer needed. - PROCESSOR_SETS_COUNT is set to the number of processor sets in the - PROCESSOR_SETS. - - This function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if HOST is not a host. - - -- Function: kern_return_t host_processor_set_priv - (host_priv_t HOST_PRIV, processor_set_name_t SET_NAME, - processor_set_t *SET) - The function `host_processor_set_priv' allows a privileged - application to obtain the control port SET for an existing - processor set from its name port SET_NAME. The privileged host - port HOST_PRIV is required. - - This function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if HOST_PRIV is not a valid host control - port. - - -- Function: kern_return_t processor_set_default (host_t HOST, - processor_set_name_t *DEFAULT_SET) - The function `processor_set_default' returns the default processor - set of HOST in DEFAULT_SET. The default processor set is used by - all threads, tasks, and processors that are not explicitly - assigned to other sets. processor_set_default returns a port that - can be used to obtain information about this set (e.g. how many - threads are assigned to it). This port cannot be used to perform - operations on that set. - - This function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_ARGUMENT' if HOST is not a host and - `KERN_INVALID_ADDRESS' if DEFAULT_SET points to inaccessible - memory. - - -File: mach.info, Node: Processor Set Creation, Next: Processor Set Destruction, Prev: Processor Set Access, Up: Processor Set Interface - -9.1.3 Processor Set Creation ----------------------------- - - -- Function: kern_return_t processor_set_create (host_t HOST, - processor_set_t *NEW_SET, processor_set_name_t *NEW_NAME) - The function `processor_set_create' creates a new processor set on - HOST and returns the two ports associated with it. The port - returned in NEW_SET is the actual port representing the set. It - is used to perform operations such as assigning processors, tasks, - or threads. The port returned in NEW_NAME identifies the set, and - is used to obtain information about the set. - - This function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_ARGUMENT' if HOST is not a host, - `KERN_INVALID_ADDRESS' if NEW_SET or NEW_NAME points to - inaccessible memory and `KERN_FAILURE' is the operating system does - not support processor allocation. - - -File: mach.info, Node: Processor Set Destruction, Next: Tasks and Threads on Sets, Prev: Processor Set Creation, Up: Processor Set Interface - -9.1.4 Processor Set Destruction -------------------------------- - - -- Function: kern_return_t processor_set_destroy - (processor_set_t PROCESSOR_SET) - The function `processor_set_destroy' destroys the specified - processor set. Any assigned processors, tasks, or threads are - reassigned to the default set. The object port for the processor - set is required (not the name port). The default processor set - cannot be destroyed. - - This function returns `KERN_SUCCESS' if the set was destroyed, - `KERN_FAILURE' if an attempt was made to destroy the default - processor set, or the operating system does not support processor - allocation, and `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a - valid processor set control port. - - -File: mach.info, Node: Tasks and Threads on Sets, Next: Processor Set Priority, Prev: Processor Set Destruction, Up: Processor Set Interface - -9.1.5 Tasks and Threads on Sets -------------------------------- - - -- Function: kern_return_t processor_set_tasks - (processor_set_t PROCESSOR_SET, task_array_t *TASK_LIST, - mach_msg_type_number_t *TASK_COUNT) - The function `processor_set_tasks' gets send rights to the kernel - port for each task currently assigned to PROCESSOR_SET. - - TASK_LIST is an array that is created as a result of this call. - The caller may wish to `vm_deallocate' this array when the data is - no longer needed. TASK_COUNT is set to the number of tasks in the - TASK_LIST. - - This function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set. - - -- Function: kern_return_t processor_set_threads - (processor_set_t PROCESSOR_SET, thread_array_t *THREAD_LIST, - mach_msg_type_number_t *THREAD_COUNT) - The function `processor_set_thread' gets send rights to the kernel - port for each thread currently assigned to PROCESSOR_SET. - - THREAD_LIST is an array that is created as a result of this call. - The caller may wish to `vm_deallocate' this array when the data is - no longer needed. THREAD_COUNT is set to the number of threads in - the THREAD_LIST. - - This function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set. - - -- Function: kern_return_t task_assign (task_t TASK, - processor_set_t PROCESSOR_SET, boolean_t ASSIGN_THREADS) - The function `task_assign' assigns TASK the set PROCESSOR_SET. - This assignment is for the purposes of determining the initial - assignment of newly created threads in task. Any previous - assignment of the task is nullified. Existing threads within the - task are also reassigned if ASSIGN_THREADS is `TRUE'. They are - not affected if it is `FALSE'. - - This function returns `KERN_SUCCESS' if the assignment has been - performed and `KERN_INVALID_ARGUMENT' if TASK is not a task, or - PROCESSOR_SET is not a processor set on the same host as TASK. - - -- Function: kern_return_t task_assign_default (task_t TASK, - boolean_t ASSIGN_THREADS) - The function `task_assign_default' is a variant of `task_assign' - that assigns the task to the default processor set on that task's - host. This variant exists because the control port for the - default processor set is privileged and not ususally available to - users. - - This function returns `KERN_SUCCESS' if the assignment has been - performed and `KERN_INVALID_ARGUMENT' if TASK is not a task. - - -- Function: kern_return_t task_get_assignment (task_t TASK, - processor_set_name_t *ASSIGNED_SET) - The function `task_get_assignment' returns the name of the - processor set to which the thread is currently assigned in - ASSIGNED_SET. This port can only be used to obtain information - about the processor set. - - This function returns `KERN_SUCCESS' if the assignment has been - performed, `KERN_INVALID_ADDRESS' if PROCESSOR_SET points to - inaccessible memory, and `KERN_INVALID_ARGUMENT' if TASK is not a - task. - - -- Function: kern_return_t thread_assign (thread_t THREAD, - processor_set_t PROCESSOR_SET) - The function `thread_assign' assigns THREAD the set PROCESSOR_SET. - After the assignment is completed, the thread only executes on - processors assigned to the designated processor set. If there are - no such processors, then the thread is unable to execute. Any - previous assignment of the thread is nullified. Unix system call - compatibility code may temporarily force threads to execute on the - master processor. - - This function returns `KERN_SUCCESS' if the assignment has been - performed and `KERN_INVALID_ARGUMENT' if THREAD is not a thread, - or PROCESSOR_SET is not a processor set on the same host as THREAD. - - -- Function: kern_return_t thread_assign_default (thread_t THREAD) - The function `thread_assign_default' is a variant of - `thread_assign' that assigns the thread to the default processor - set on that thread's host. This variant exists because the - control port for the default processor set is privileged and not - ususally available to users. - - This function returns `KERN_SUCCESS' if the assignment has been - performed and `KERN_INVALID_ARGUMENT' if THREAD is not a thread. - - -- Function: kern_return_t thread_get_assignment (thread_t THREAD, - processor_set_name_t *ASSIGNED_SET) - The function `thread_get_assignment' returns the name of the - processor set to which the thread is currently assigned in - ASSIGNED_SET. This port can only be used to obtain information - about the processor set. - - This function returns `KERN_SUCCESS' if the assignment has been - performed, `KERN_INVALID_ADDRESS' if PROCESSOR_SET points to - inaccessible memory, and `KERN_INVALID_ARGUMENT' if THREAD is not - a thread. - - -File: mach.info, Node: Processor Set Priority, Next: Processor Set Policy, Prev: Tasks and Threads on Sets, Up: Processor Set Interface - -9.1.6 Processor Set Priority ----------------------------- - - -- Function: kern_return_t processor_set_max_priority - (processor_set_t PROCESSOR_SET, int MAX_PRIORITY, - boolean_t CHANGE_THREADS) - The function `processor_set_max_priority' is used to set the - maximum priority for a processor set. The priority of a processor - set is used only for newly created threads (thread's maximum - priority is set to processor set's) and the assignment of threads - to the set (thread's maximum priority is reduced if it exceeds the - set's maximum priority, thread's priority is similarly reduced). - `processor_set_max_priority' changes this priority. It also sets - the maximum priority of all threads assigned to the processor set - to this new priority if CHANGE_THREADS is `TRUE'. If this maximum - priority is less than the priorities of any of these threads, - their priorities will also be set to this new value. - - This function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set or - PRIORITY is not a valid priority. - - -File: mach.info, Node: Processor Set Policy, Next: Processor Set Info, Prev: Processor Set Priority, Up: Processor Set Interface - -9.1.7 Processor Set Policy --------------------------- - - -- Function: kern_return_t processor_set_policy_enable - (processor_set_t PROCESSOR_SET, int POLICY) - -- Function: kern_return_t processor_set_policy_disable - (processor_set_t PROCESSOR_SET, int POLICY, - boolean_t CHANGE_THREADS) - Processor sets may restrict the scheduling policies to be used for - threads assigned to them. These two calls provide the mechanism - for designating permitted and forbidden policies. The current set - of permitted policies can be obtained from `processor_set_info'. - Timesharing may not be forbidden by any processor set. This is a - compromise to reduce the complexity of the assign operation; any - thread whose policy is forbidden by the target processor set has - its policy reset to timesharing. If the CHANGE_THREADS argument to - `processor_set_policy_disable' is true, threads currently assigned - to this processor set and using the newly disabled policy will have - their policy reset to timesharing. - - `mach/policy.h' contains the allowed policies; it is included by - `mach.h'. Not all policies (e.g. fixed priority) are supported by - all systems. - - This function returns `KERN_SUCCESS' if the operation was completed - successfully and `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a - processor set or POLICY is not a valid policy, or an attempt was - made to disable timesharing. - - -File: mach.info, Node: Processor Set Info, Prev: Processor Set Policy, Up: Processor Set Interface - -9.1.8 Processor Set Info ------------------------- - - -- Function: kern_return_t processor_set_info - (processor_set_name_t SET_NAME, int FLAVOR, host_t *HOST, - processor_set_info_t PROCESSOR_SET_INFO, - mach_msg_type_number_t *PROCESSOR_SET_INFO_COUNT) - The function `processor_set_info' returns the selected information - array for a processor set, as specified by FLAVOR. - - HOST is set to the host on which the processor set resides. This - is the non-privileged host port. - - PROCESSOR_SET_INFO is an array of integers that is supplied by the - caller and returned filled with specified information. - PROCESSOR_SET_INFO_COUNT is supplied as the maximum number of - integers in PROCESSOR_SET_INFO. On return, it contains the actual - number of integers in PROCESSOR_SET_INFO. The maximum number of - integers returned by any flavor is `PROCESSOR_SET_INFO_MAX'. - - The type of information returned is defined by FLAVOR, which can - be one of the following: - - `PROCESSOR_SET_BASIC_INFO' - The function returns basic information about the processor - set, as defined by `processor_set_basic_info_t'. This - includes the number of tasks and threads assigned to the - processor set. The number of integers returned is - `PROCESSOR_SET_BASIC_INFO_COUNT'. - - `PROCESSOR_SET_SCHED_INFO' - The function returns information about the schduling policy - for the processor set as defined by - `processor_set_sched_info_t'. The number of integers - returned is `PROCESSOR_SET_SCHED_INFO_COUNT'. - - Some machines may define additional (machine-dependent) flavors. - - The function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set or - FLAVOR is not recognized. The function returns - `MIG_ARRAY_TOO_LARGE' if the returned info array is too large for - PROCESSOR_SET_INFO. In this case, PROCESSOR_SET_INFO is filled as - much as possible and PROCESSOR_SET_INFO_COUNT is set to the number - of elements that would have been returned if there were enough - room. - - -- Data type: struct processor_set_basic_info - This structure is returned in PROCESSOR_SET_INFO by the - `processor_set_info' function and provides basic information about - the processor set. You can cast a variable of type - `processor_set_info_t' to a pointer of this type if you provided it - as the PROCESSOR_SET_INFO parameter for the - `PROCESSOR_SET_BASIC_INFO' flavor of `processor_set_info'. It has - the following members: - - `int processor_count' - number of processors - - `int task_count' - number of tasks - - `int thread_count' - number of threads - - `int load_average' - scaled load average - - `int mach_factor' - scaled mach factor - - -- Data type: processor_set_basic_info_t - This is a pointer to a `struct processor_set_basic_info'. - - -- Data type: struct processor_set_sched_info - This structure is returned in PROCESSOR_SET_INFO by the - `processor_set_info' function and provides schedule information - about the processor set. You can cast a variable of type - `processor_set_info_t' to a pointer of this type if you provided it - as the PROCESSOR_SET_INFO parameter for the - `PROCESSOR_SET_SCHED_INFO' flavor of `processor_set_info'. It has - the following members: - - `int policies' - allowed policies - - `int max_priority' - max priority for new threads - - -- Data type: processor_set_sched_info_t - This is a pointer to a `struct processor_set_sched_info'. - - -File: mach.info, Node: Processor Interface, Prev: Processor Set Interface, Up: Processors and Processor Sets - -9.2 Processor Interface -======================= - - -- Data type: processor_t - This is a `mach_port_t' and used to hold the port name of a - processor port that represents the processor. Operations on the - processor are implemented as remote procedure calls to the - processor port. - -* Menu: - -* Hosted Processors:: Getting a list of all processors on a host. -* Processor Control:: Starting, stopping, controlling processors. -* Processors and Sets:: Combining processors into processor sets. -* Processor Info:: Obtaining information on processors. - - -File: mach.info, Node: Hosted Processors, Next: Processor Control, Up: Processor Interface - -9.2.1 Hosted Processors ------------------------ - - -- Function: kern_return_t host_processors (host_priv_t HOST_PRIV, - processor_array_t *PROCESSOR_LIST, - mach_msg_type_number_t *PROCESSOR_COUNT) - The function `host_processors' gets send rights to the processor - port for each processor existing on HOST_PRIV. This is the - privileged port that allows its holder to control a processor. - - PROCESSOR_LIST is an array that is created as a result of this - call. The caller may wish to `vm_deallocate' this array when the - data is no longer needed. PROCESSOR_COUNT is set to the number of - processors in the PROCESSOR_LIST. - - This function returns `KERN_SUCCESS' if the call succeeded, - `KERN_INVALID_ARGUMENT' if HOST_PRIV is not a privileged host - port, and `KERN_INVALID_ADDRESS' if PROCESSOR_COUNT points to - inaccessible memory. - - -File: mach.info, Node: Processor Control, Next: Processors and Sets, Prev: Hosted Processors, Up: Processor Interface - -9.2.2 Processor Control ------------------------ - - -- Function: kern_return_t processor_start (processor_t PROCESSOR) - -- Function: kern_return_t processor_exit (processor_t PROCESSOR) - -- Function: kern_return_t processor_control (processor_t PROCESSOR, - processor_info_t *CMD, mach_msg_type_number_t COUNT) - Some multiprocessors may allow privileged software to control - processors. The `processor_start', `processor_exit', and - `processor_control' operations implement this. The interpretation - of the command in CMD is machine dependent. A newly started - processor is assigned to the default processor set. An exited - processor is removed from the processor set to which it was - assigned and ceases to be active. - - COUNT contains the length of the command CMD as a number of ints. - - Availability limited. All of these operations are - machine-dependent. They may do nothing. The ability to restart - an exited processor is also machine-dependent. - - This function returns `KERN_SUCCESS' if the operation was - performed, `KERN_FAILURE' if the operation was not performed (a - likely reason is that it is not supported on this processor), - `KERN_INVALID_ARGUMENT' if PROCESSOR is not a processor, and - `KERN_INVALID_ADDRESS' if CMD points to inaccessible memory. - - -File: mach.info, Node: Processors and Sets, Next: Processor Info, Prev: Processor Control, Up: Processor Interface - -9.2.3 Processors and Sets -------------------------- - - -- Function: kern_return_t processor_assign (processor_t PROCESSOR, - processor_set_t PROCESSOR_SET, boolean_t WAIT) - The function `processor_assign' assigns PROCESSOR to the the set - PROCESSOR_SET. After the assignment is completed, the processor - only executes threads that are assigned to that processor set. - Any previous assignment of the processor is nullified. The master - processor cannot be reassigned. All processors take clock - interrupts at all times. The WAIT argument indicates whether the - caller should wait for the assignment to be completed or should - return immediately. Dedicated kernel threads are used to perform - processor assignment, so setting wait to `FALSE' allows assignment - requests to be queued and performed faster, especially if the - kernel has more than one dedicated internal thread for processor - assignment. Redirection of other device interrupts away from - processors assigned to other than the default processor set is - machine-dependent. Intermediaries that interpose on ports must be - sure to interpose on both ports involved in this call if they - interpose on either. - - This function returns `KERN_SUCCESS' if the assignment has been - performed, `KERN_INVALID_ARGUMENT' if PROCESSOR is not a - processor, or PROCESSOR_SET is not a processor set on the same - host as PROCESSOR. - - -- Function: kern_return_t processor_get_assignment - (processor_t PROCESSOR, processor_set_name_t *ASSIGNED_SET) - The function `processor_get_assignment' obtains the current - assignment of a processor. The name port of the processor set is - returned in ASSIGNED_SET. - - -File: mach.info, Node: Processor Info, Prev: Processors and Sets, Up: Processor Interface - -9.2.4 Processor Info --------------------- - - -- Function: kern_return_t processor_info (processor_t PROCESSOR, - int FLAVOR, host_t *HOST, processor_info_t PROCESSOR_INFO, - mach_msg_type_number_t *PROCESSOR_INFO_COUNT) - The function `processor_info' returns the selected information - array for a processor, as specified by FLAVOR. - - HOST is set to the host on which the processor set resides. This - is the non-privileged host port. - - PROCESSOR_INFO is an array of integers that is supplied by the - caller and returned filled with specified information. - PROCESSOR_INFO_COUNT is supplied as the maximum number of integers - in PROCESSOR_INFO. On return, it contains the actual number of - integers in PROCESSOR_INFO. The maximum number of integers - returned by any flavor is `PROCESSOR_INFO_MAX'. - - The type of information returned is defined by FLAVOR, which can - be one of the following: - - `PROCESSOR_BASIC_INFO' - The function returns basic information about the processor, - as defined by `processor_basic_info_t'. This includes the - slot number of the processor. The number of integers - returned is `PROCESSOR_BASIC_INFO_COUNT'. - - Machines which require more configuration information beyond the - slot number are expected to define additional (machine-dependent) - flavors. - - The function returns `KERN_SUCCESS' if the call succeeded and - `KERN_INVALID_ARGUMENT' if PROCESSOR is not a processor or FLAVOR - is not recognized. The function returns `MIG_ARRAY_TOO_LARGE' if - the returned info array is too large for PROCESSOR_INFO. In this - case, PROCESSOR_INFO is filled as much as possible and - PROCESSOR_INFOCNT is set to the number of elements that would have - been returned if there were enough room. - - -- Data type: struct processor_basic_info - This structure is returned in PROCESSOR_INFO by the - `processor_info' function and provides basic information about the - processor. You can cast a variable of type `processor_info_t' to a - pointer of this type if you provided it as the PROCESSOR_INFO - parameter for the `PROCESSOR_BASIC_INFO' flavor of - `processor_info'. It has the following members: - - `cpu_type_t cpu_type' - cpu type - - `cpu_subtype_t cpu_subtype' - cpu subtype - - `boolean_t running' - is processor running? - - `int slot_num' - slot number - - `boolean_t is_master' - is this the master processor - - -- Data type: processor_basic_info_t - This is a pointer to a `struct processor_basic_info'. - - -File: mach.info, Node: Device Interface, Next: Kernel Debugger, Prev: Processors and Processor Sets, Up: Top - -10 Device Interface -******************* - -The GNU Mach microkernel provides a simple device interface that allows -the user space programs to access the underlying hardware devices. Each -device has a unique name, which is a string up to 127 characters long. -To open a device, the device master port has to be supplied. The device -master port is only available through the bootstrap port. Anyone who -has control over the device master port can use all hardware devices. - - -- Data type: device_t - This is a `mach_port_t' and used to hold the port name of a device - port that represents the device. Operations on the device are - implemented as remote procedure calls to the device port. Each - device provides a sequence of records. The length of a record is - specific to the device. Data can be transferred "out-of-line" or - "in-line" (*note Memory::). - - All constants and functions in this chapter are defined in -`device/device.h'. - -* Menu: - -* Device Reply Server:: Handling device reply messages. -* Device Open:: Opening hardware devices. -* Device Close:: Closing hardware devices. -* Device Read:: Reading data from the device. -* Device Write:: Writing data to the device. -* Device Map:: Mapping devices into virtual memory. -* Device Status:: Querying and manipulating a device. -* Device Filter:: Filtering packets arriving on a device. - - -File: mach.info, Node: Device Reply Server, Next: Device Open, Up: Device Interface - -10.1 Device Reply Server -======================== - -Beside the usual synchronous interface, an asynchronous interface is -provided. For this, the caller has to receive and handle the reply -messages seperately from the function call. - - -- Function: boolean_t device_reply_server (msg_header_t *IN_MSG, - msg_header_t *OUT_MSG) - The function `device_reply_server' is produced by the remote - procedure call generator to handle a received message. This - function does all necessary argument handling, and actually calls - one of the following functions: `ds_device_open_reply', - `ds_device_read_reply', `ds_device_read_reply_inband', - `ds_device_write_reply' and `ds_device_write_reply_inband'. - - The IN_MSG argument is the message that has been received from the - kernel. The OUT_MSG is a reply message, but this is not used for - this server. - - The function returns `TRUE' to indicate that the message in - question was applicable to this interface, and that the appropriate - routine was called to interpret the message. It returns `FALSE' to - indicate that the message did not apply to this interface, and - that no other action was taken. - - -File: mach.info, Node: Device Open, Next: Device Close, Prev: Device Reply Server, Up: Device Interface - -10.2 Device Open -================ - - -- Function: kern_return_t device_open (mach_port_t MASTER_PORT, - dev_mode_t MODE, dev_name_t NAME, device_t *DEVICE) - The function `device_open' opens the device NAME and returns a - port to it in DEVICE. The open count for the device is - incremented by one. If the open count was 0, the open handler for - the device is invoked. - - MASTER_PORT must hold the master device port. NAME specifies the - device to open, and is a string up to 128 characters long. MODE - is the open mode. It is a bitwise-or of the following constants: - - `D_READ' - Request read access for the device. - - `D_WRITE' - Request write access for the device. - - `D_NODELAY' - Do not delay an open. - - The function returns `D_SUCCESS' if the device was successfully - opened, `D_INVALID_OPERATION' if MASTER_PORT is not the master - device port, `D_WOULD_BLOCK' is the device is busy and `D_NOWAIT' - was specified in mode, `D_ALREADY_OPEN' if the device is already - open in an incompatible mode and `D_NO_SUCH_DEVICE' if NAME does - not denote a know device. - - -- Function: kern_return_t device_open_request - (mach_port_t MASTER_PORT, mach_port_t REPLY_PORT, - dev_mode_t MODE, dev_name_t NAME) - -- Function: kern_return_t ds_device_open_reply - (mach_port_t REPLY_PORT, kern_return_t RETURN, - device_t *DEVICE) - This is the asynchronous form of the `device_open' function. - `device_open_request' performs the open request. The meaning for - the parameters is as in `device_open'. Additionally, the caller - has to supply a reply port to which the `ds_device_open_reply' - message is sent by the kernel when the open has been performed. - The return value of the open operation is stored in RETURN_CODE. - - As neither function receives a reply message, only message - transmission errors apply. If no error occurs, `KERN_SUCCESS' is - returned. - - -File: mach.info, Node: Device Close, Next: Device Read, Prev: Device Open, Up: Device Interface - -10.3 Device Close -================= - - -- Function: kern_return_t device_close (device_t DEVICE) - The function `device_close' decrements the open count of the device - by one. If the open count drops to zero, the close handler for the - device is called. The device to close is specified by its port - DEVICE. - - The function returns `D_SUCCESS' if the device was successfully - closed and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device - port. - - -File: mach.info, Node: Device Read, Next: Device Write, Prev: Device Close, Up: Device Interface - -10.4 Device Read -================ - - -- Function: kern_return_t device_read (device_t DEVICE, - dev_mode_t MODE, recnum_t RECNUM, int BYTES_WANTED, - io_buf_ptr_t *DATA, mach_msg_type_number_t *DATA_COUNT) - The function `device_read' reads BYTES_WANTED bytes from DEVICE, - and stores them in a buffer allocated with `vm_allocate', which - address is returned in DATA. The caller must deallocated it if it - is no longer needed. The number of bytes actually returned is - stored in DATA_COUNT. - - If MODE is `D_NOWAIT', the operation does not block. Otherwise - MODE should be 0. RECNUM is the record number to be read, its - meaning is device specific. - - The function returns `D_SUCCESS' if some data was successfully - read, `D_WOULD_BLOCK' if no data is currently available and - `D_NOWAIT' is specified, and `D_NO_SUCH_DEVICE' if DEVICE does not - denote a device port. - - -- Function: kern_return_t device_read_inband (device_t DEVICE, - dev_mode_t MODE, recnum_t RECNUM, int BYTES_WANTED, - io_buf_ptr_inband_t *DATA, mach_msg_type_number_t *DATA_COUNT) - The `device_read_inband' function works as the `device_read' - function, except that the data is returned "in-line" in the reply - IPC message (*note Memory::). - - -- Function: kern_return_t device_read_request (device_t DEVICE, - mach_port_t REPLY_PORT, dev_mode_t MODE, recnum_t RECNUM, - int BYTES_WANTED) - -- Function: kern_return_t ds_device_read_reply - (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE, - io_buf_ptr_t DATA, mach_msg_type_number_t DATA_COUNT) - This is the asynchronous form of the `device_read' function. - `device_read_request' performs the read request. The meaning for - the parameters is as in `device_read'. Additionally, the caller - has to supply a reply port to which the `ds_device_read_reply' - message is sent by the kernel when the read has been performed. - The return value of the read operation is stored in RETURN_CODE. - - As neither function receives a reply message, only message - transmission errors apply. If no error occurs, `KERN_SUCCESS' is - returned. - - -- Function: kern_return_t device_read_request_inband - (device_t DEVICE, mach_port_t REPLY_PORT, dev_mode_t MODE, - recnum_t RECNUM, int BYTES_WANTED) - -- Function: kern_return_t ds_device_read_reply_inband - (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE, - io_buf_ptr_t DATA, mach_msg_type_number_t DATA_COUNT) - The `device_read_request_inband' and `ds_device_read_reply_inband' - functions work as the `device_read_request' and - `ds_device_read_reply' functions, except that the data is returned - "in-line" in the reply IPC message (*note Memory::). - - -File: mach.info, Node: Device Write, Next: Device Map, Prev: Device Read, Up: Device Interface - -10.5 Device Write -================= - - -- Function: kern_return_t device_write (device_t DEVICE, - dev_mode_t MODE, recnum_t RECNUM, io_buf_ptr_t DATA, - mach_msg_type_number_t DATA_COUNT, int *BYTES_WRITTEN) - The function `device_write' writes DATA_COUNT bytes from the - buffer DATA to DEVICE. The number of bytes actually written is - returned in BYTES_WRITTEN. - - If MODE is `D_NOWAIT', the function returns without waiting for - I/O completion. Otherwise MODE should be 0. RECNUM is the record - number to be written, its meaning is device specific. - - The function returns `D_SUCCESS' if some data was successfully - written and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device - port or the device is dead or not completely open. - - -- Function: kern_return_t device_write_inband (device_t DEVICE, - dev_mode_t MODE, recnum_t RECNUM, int BYTES_WANTED, - io_buf_ptr_inband_t *DATA, mach_msg_type_number_t *DATA_COUNT) - The `device_write_inband' function works as the `device_write' - function, except that the data is sent "in-line" in the request IPC - message (*note Memory::). - - -- Function: kern_return_t device_write_request (device_t DEVICE, - mach_port_t REPLY_PORT, dev_mode_t MODE, recnum_t RECNUM, - io_buf_ptr_t DATA, mach_msg_type_number_t DATA_COUNT) - -- Function: kern_return_t ds_device_write_reply - (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE, - int BYTES_WRITTEN) - This is the asynchronous form of the `device_write' function. - `device_write_request' performs the write request. The meaning for - the parameters is as in `device_write'. Additionally, the caller - has to supply a reply port to which the `ds_device_write_reply' - message is sent by the kernel when the write has been performed. - The return value of the write operation is stored in RETURN_CODE. - - As neither function receives a reply message, only message - transmission errors apply. If no error occurs, `KERN_SUCCESS' is - returned. - - -- Function: kern_return_t device_write_request_inband - (device_t DEVICE, mach_port_t REPLY_PORT, dev_mode_t MODE, - recnum_t RECNUM, io_buf_ptr_t DATA, - mach_msg_type_number_t DATA_COUNT) - -- Function: kern_return_t ds_device_write_reply_inband - (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE, - int BYTES_WRITTEN) - The `device_write_request_inband' and - `ds_device_write_reply_inband' functions work as the - `device_write_request' and `ds_device_write_reply' functions, - except that the data is sent "in-line" in the request IPC message - (*note Memory::). - - -File: mach.info, Node: Device Map, Next: Device Status, Prev: Device Write, Up: Device Interface - -10.6 Device Map -=============== - - -- Function: kern_return_t device_map (device_t DEVICE, - vm_prot_t PROT, vm_offset_t OFFSET, vm_size_t SIZE, - mach_port_t *PAGER, int UNMAP) - The function `device_map' creates a new memory manager for DEVICE - and returns a port to it in PAGER. The memory manager is usable - as a memory object in a `vm_map' call. The call is device - dependant. - - The protection for the memory object is specified by PROT. The - memory object starts at OFFSET within the device and extends SIZE - bytes. UNMAP is currently unused. - - The function returns `D_SUCCESS' if some data was successfully - written and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device - port or the device is dead or not completely open. - - -File: mach.info, Node: Device Status, Next: Device Filter, Prev: Device Map, Up: Device Interface - -10.7 Device Status -================== - - -- Function: kern_return_t device_set_status (device_t DEVICE, - dev_flavor_t FLAVOR, dev_status_t STATUS, - mach_msg_type_number_t STATUS_COUNT) - The function `device_set_status' sets the status of a device. The - possible values for FLAVOR and their interpretation is device - specific. - - The function returns `D_SUCCESS' if some data was successfully - written and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device - port or the device is dead or not completely open. - - -- Function: kern_return_t device_get_status (device_t DEVICE, - dev_flavor_t FLAVOR, dev_status_t STATUS, - mach_msg_type_number_t *STATUS_COUNT) - The function `device_get_status' gets the status of a device. The - possible values for FLAVOR and their interpretation is device - specific. - - The function returns `D_SUCCESS' if some data was successfully - written and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device - port or the device is dead or not completely open. - - -File: mach.info, Node: Device Filter, Prev: Device Status, Up: Device Interface - -10.8 Device Filter -================== - - -- Function: kern_return_t device_set_filter (device_t DEVICE, - mach_port_t RECEIVE_PORT, - mach_msg_type_name_t RECEIVE_PORT_TYPE, int PRIORITY, - filter_array_t FILTER, mach_msg_type_number_t FILTER_COUNT) - The function `device_set_filter' makes it possible to filter out - selected data arriving at the device and forward it to a port. - FILTER is a list of filter commands, which are applied to incoming - data to determine if the data should be sent to RECEIVE_PORT. The - IPC type of the send right is specified by RECEIVE_PORT_RIGHT, it - is either `MACH_MSG_TYPE_MAKE_SEND' or `MACH_MSG_TYPE_MOVE_SEND'. - The PRIORITY value is used to order multiple filters. - - There can be up to `NET_MAX_FILTER' commands in FILTER. The - actual number of commands is passed in FILTER_COUNT. For the - purpose of the filter test, an internal stack is provided. After - all commands have been processed, the value on the top of the stack - determines if the data is forwarded or the next filter is tried. - - Each word of the command list specifies a data (push) operation - (high order NETF_NBPO bits) as well as a binary operator (low - order NETF_NBPA bits). The value to be pushed onto the stack is - chosen as follows. - - `NETF_PUSHLIT' - Use the next short word of the filter as the value. - - `NETF_PUSHZERO' - Use 0 as the value. - - `NETF_PUSHWORD+N' - Use short word N of the "data" portion of the message as the - value. - - `NETF_PUSHHDR+N' - Use short word N of the "header" portion of the message as - the value. - - `NETF_PUSHIND+N' - Pops the top long word from the stack and then uses short - word N of the "data" portion of the message as the value. - - `NETF_PUSHHDRIND+N' - Pops the top long word from the stack and then uses short - word N of the "header" portion of the message as the value. - - `NETF_PUSHSTK+N' - Use long word N of the stack (where the top of stack is long - word 0) as the value. - - `NETF_NOPUSH' - Don't push a value. - - The unsigned value so chosen is promoted to a long word before - being pushed. Once a value is pushed (except for the case of - `NETF_NOPUSH'), the top two long words of the stack are popped and - a binary operator applied to them (with the old top of stack as the - second operand). The result of the operator is pushed on the - stack. These operators are: - - `NETF_NOP' - Don't pop off any values and do no operation. - - `NETF_EQ' - Perform an equal comparison. - - `NETF_LT' - Perform a less than comparison. - - `NETF_LE' - Perform a less than or equal comparison. - - `NETF_GT' - Perform a greater than comparison. - - `NETF_GE' - Perform a greater than or equal comparison. - - `NETF_AND' - Perform a bitise boolean AND operation. - - `NETF_OR' - Perform a bitise boolean inclusive OR operation. - - `NETF_XOR' - Perform a bitise boolean exclusive OR operation. - - `NETF_NEQ' - Perform a not equal comparison. - - `NETF_LSH' - Perform a left shift operation. - - `NETF_RSH' - Perform a right shift operation. - - `NETF_ADD' - Perform an addition. - - `NETF_SUB' - Perform a subtraction. - - `NETF_COR' - Perform an equal comparison. If the comparison is `TRUE', - terminate the filter list. Otherwise, pop the result of the - comparison off the stack. - - `NETF_CAND' - Perform an equal comparison. If the comparison is `FALSE', - terminate the filter list. Otherwise, pop the result of the - comparison off the stack. - - `NETF_CNOR' - Perform a not equal comparison. If the comparison is `FALSE', - terminate the filter list. Otherwise, pop the result of the - comparison off the stack. - - `NETF_CNAND' - Perform a not equal comparison. If the comparison is `TRUE', - terminate the filter list. Otherwise, pop the result of the - comparison off the stack. The scan of the filter list - terminates when the filter list is emptied, or a `NETF_C...' - operation terminates the list. At this time, if the final - value of the top of the stack is `TRUE', then the message is - accepted for the filter. - - The function returns `D_SUCCESS' if some data was successfully - written, `D_INVALID_OPERATION' if RECEIVE_PORT is not a valid send - right, and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device - port or the device is dead or not completely open. - - -File: mach.info, Node: Kernel Debugger, Next: Copying, Prev: Device Interface, Up: Top - -11 Kernel Debugger -****************** - -The GNU Mach kernel debugger `ddb' is a powerful built-in debugger with -a gdb like syntax. It is enabled at compile time using the -`--enable-kdb' option. Whenever you want to enter the debugger while -running the kernel, you can press the key combination <Ctrl-Alt-D>. - -* Menu: - -* Operation:: Basic architecture of the kernel debugger. -* Commands:: Available commands in the kernel debugger. -* Variables:: Access of variables from the kernel debugger. -* Expressions:: Usage of expressions in the kernel debugger. - - -File: mach.info, Node: Operation, Next: Commands, Up: Kernel Debugger - -11.1 Operation -============== - -The current location is called "dot". The dot is displayed with a -hexadecimal format at a prompt. Examine and write commands update dot -to the address of the last line examined or the last location modified, -and set "next" to the address of the next location to be examined or -changed. Other commands don't change dot, and set next to be the same -as dot. - - The general command syntax is: - - COMMAND[/MODIFIER] ADDRESS [,COUNT] - - `!!' repeats the previous command, and a blank line repeats from the -address next with count 1 and no modifiers. Specifying ADDRESS sets -dot to the address. Omitting ADDRESS uses dot. A missing COUNT is -taken to be 1 for printing commands or infinity for stack traces. - - Current `ddb' is enhanced to support multi-thread debugging. A -break point can be set only for a specific thread, and the address space -or registers of non current thread can be examined or modified if -supported by machine dependent routines. For example, - - break/t mach_msg_trap $task11.0 - - sets a break point at `mach_msg_trap' for the first thread of task -11 listed by a `show all threads' command. - - In the above example, `$task11.0' is translated to the corresponding -thread structure's address by variable translation mechanism described -later. If a default target thread is set in a variable `$thread', the -`$task11.0' can be omitted. In general, if `t' is specified in a -modifier of a command line, a specified thread or a default target -thread is used as a target thread instead of the current one. The `t' -modifier in a command line is not valid in evaluating expressions in a -command line. If you want to get a value indirectly from a specific -thread's address space or access to its registers within an expression, -you have to specify a default target thread in advance, and to use `:t' -modifier immediately after the indirect access or the register -reference like as follows: - - set $thread $task11.0 - print $eax:t *(0x100):tuh - - No sign extension and indirection `size(long, half word, byte)' can -be specified with `u', `l', `h' and `b' respectively for the indirect -access. - - Note: Support of non current space/register access and user space -break point depend on the machines. If not supported, attempts of such -operation may provide incorrect information or may cause strange -behavior. Even if supported, the user space access is limited to the -pages resident in the main memory at that time. If a target page is not -in the main memory, an error will be reported. - - `ddb' has a feature like a command `more' for the output. If an -output line exceeds the number set in the `$lines' variable, it -displays `--db_more--' and waits for a response. The valid responses -for it are: - -`<SPC>' - one more page - -`<RET>' - one more line - -`q' - abort the current command, and return to the command input mode - diff --git a/doc/mach.info-2 b/doc/mach.info-2 deleted file mode 100644 index 806539f..0000000 --- a/doc/mach.info-2 +++ /dev/null @@ -1,1663 +0,0 @@ -This is ../doc/mach.info, produced by makeinfo version 4.8 from -../doc/mach.texi. - -INFO-DIR-SECTION Kernel -START-INFO-DIR-ENTRY -* GNUMach: (mach). Using and programming the GNU Mach microkernel. -END-INFO-DIR-ENTRY - - This file documents the GNU Mach microkernel. - - This is Edition 0.4, last updated 2001-09-01, of `The GNU Mach -Reference Manual', for Version 1.3.99. - - Copyright (C) 2001 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being "Free Software Needs Free Documentation" and -"GNU Lesser General Public License", the Front-Cover texts being (a) -(see below), and with the Back-Cover Texts being (b) (see below). A -copy of the license is included in the section entitled "GNU Free -Documentation License". - - (a) The FSF's Front-Cover Text is: - - A GNU Manual - - (b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU -software. Copies published by the Free Software Foundation raise -funds for GNU development. - - This work is based on manual pages under the following copyright and -license: - -Mach Operating System -Copyright (C) 1991,1990 Carnegie Mellon University -All Rights Reserved. - - Permission to use, copy, modify and distribute this software and its -documentation is hereby granted, provided that both the copyright -notice and this permission notice appear in all copies of the software, -derivative works or modified versions, and any portions thereof, and -that both notices appear in supporting documentation. - - CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" -CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY -DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. - - -File: mach.info, Node: Commands, Next: Variables, Prev: Operation, Up: Kernel Debugger - -11.2 Commands -============= - -`examine(x) [/MODIFIER] ADDR[,COUNT] [ THREAD ]' - Display the addressed locations according to the formats in the - modifier. Multiple modifier formats display multiple locations. - If no format is specified, the last formats specified for this - command is used. Address space other than that of the current - thread can be specified with `t' option in the modifier and THREAD - parameter. The format characters are - - `b' - look at by bytes(8 bits) - - `h' - look at by half words(16 bits) - - `l' - look at by long words(32 bits) - - `a' - print the location being displayed - - `,' - skip one unit producing no output - - `A' - print the location with a line number if possible - - `x' - display in unsigned hex - - `z' - display in signed hex - - `o' - display in unsigned octal - - `d' - display in signed decimal - - `u' - display in unsigned decimal - - `r' - display in current radix, signed - - `c' - display low 8 bits as a character. Non-printing characters - are displayed as an octal escape code (e.g. '\000'). - - `s' - display the null-terminated string at the location. - Non-printing characters are displayed as octal escapes. - - `m' - display in unsigned hex with character dump at the end of - each line. The location is also displayed in hex at the - beginning of each line. - - `i' - display as an instruction - - `I' - display as an instruction with possible alternate formats - depending on the machine: - - `vax' - don't assume that each external label is a procedure - entry mask - - `i386' - don't round to the next long word boundary - - `mips' - print register contents - -`xf' - Examine forward. It executes an examine command with the last - specified parameters to it except that the next address displayed - by it is used as the start address. - -`xb' - Examine backward. It executes an examine command with the last - specified parameters to it except that the last start address - subtracted by the size displayed by it is used as the start - address. - -`print[/axzodurc] ADDR1 [ ADDR2 ... ]' - Print ADDR's according to the modifier character. Valid formats - are: `a' `x' `z' `o' `d' `u' `r' `c'. If no modifier is - specified, the last one specified to it is used. ADDR can be a - string, and it is printed as it is. For example, - - print/x "eax = " $eax "\necx = " $ecx "\n" - - will print like - - eax = xxxxxx - ecx = yyyyyy - -`write[/bhlt] ADDR [ THREAD ] EXPR1 [ EXPR2 ... ]' - Write the expressions at succeeding locations. The write unit - size can be specified in the modifier with a letter b (byte), h - (half word) or l(long word) respectively. If omitted, long word - is assumed. Target address space can also be specified with `t' - option in the modifier and THREAD parameter. Warning: since there - is no delimiter between expressions, strange things may happen. - It's best to enclose each expression in parentheses. - -`set $VARIABLE [=] EXPR' - Set the named variable or register with the value of EXPR. Valid - variable names are described below. - -`break[/tuTU] ADDR[,COUNT] [ THREAD1 ... ]' - Set a break point at ADDR. If count is supplied, continues - (COUNT-1) times before stopping at the break point. If the break - point is set, a break point number is printed with `#'. This - number can be used in deleting the break point or adding - conditions to it. - - `t' - Set a break point only for a specific thread. The thread is - specified by THREAD parameter, or default one is used if the - parameter is omitted. - - `u' - Set a break point in user space address. It may be combined - with `t' or `T' option to specify the non-current target user - space. Without `u' option, the address is considered in the - kernel space, and wrong space address is rejected with an - error message. This option can be used only if it is - supported by machine dependent routines. - - `T' - Set a break point only for threads in a specific task. It is - like `t' option except that the break point is valid for all - threads which belong to the same task as the specified target - thread. - - `U' - Set a break point in shared user space address. It is like - `u' option, except that the break point is valid for all - threads which share the same address space even if `t' option - is specified. `t' option is used only to specify the target - shared space. Without `t' option, `u' and `U' have the same - meanings. `U' is useful for setting a user space break point - in non-current address space with `t' option such as in an - emulation library space. This option can be used only if it - is supported by machine dependent routines. - - Warning: if a user text is shadowed by a normal user space - debugger, user space break points may not work correctly. Setting - a break point at the low-level code paths may also cause strange - behavior. - -`delete[/tuTU] ADDR|#NUMBER [ THREAD1 ... ]' - Delete the break point. The target break point can be specified - by a break point number with `#', or by ADDR like specified in - `break' command. - -`cond #NUMBER [ CONDITION COMMANDS ]' - Set or delete a condition for the break point specified by the - NUMBER. If the CONDITION and COMMANDS are null, the condition is - deleted. Otherwise the condition is set for it. When the break - point is hit, the CONDITION is evaluated. The COMMANDS will be - executed if the condition is true and the break point count set by - a break point command becomes zero. COMMANDS is a list of - commands separated by semicolons. Each command in the list is - executed in that order, but if a `continue' command is executed, - the command execution stops there, and the stopped thread resumes - execution. If the command execution reaches the end of the list, - and it enters into a command input mode. For example, - - set $work0 0 - break/Tu xxx_start $task7.0 - cond #1 (1) set $work0 1; set $work1 0; cont - break/T vm_fault $task7.0 - cond #2 ($work0) set $work1 ($work1+1); cont - break/Tu xxx_end $task7.0 - cond #3 ($work0) print $work1 " faults\n"; set $work0 0 - cont - - will print page fault counts from `xxx_start' to `xxx_end' in - `task7'. - -`step[/p] [,COUNT]' - Single step COUNT times. If `p' option is specified, print each - instruction at each step. Otherwise, only print the last - instruction. - - Warning: depending on machine type, it may not be possible to - single-step through some low-level code paths or user space code. - On machines with software-emulated single-stepping (e.g., pmax), - stepping through code executed by interrupt handlers will probably - do the wrong thing. - -`continue[/c]' - Continue execution until a breakpoint or watchpoint. If `/c', - count instructions while executing. Some machines (e.g., pmax) - also count loads and stores. - - Warning: when counting, the debugger is really silently - single-stepping. This means that single-stepping on low-level - code may cause strange behavior. - -`until' - Stop at the next call or return instruction. - -`next[/p]' - Stop at the matching return instruction. If `p' option is - specified, print the call nesting depth and the cumulative - instruction count at each call or return. Otherwise, only print - when the matching return is hit. - -`match[/p]' - A synonym for `next'. - -`trace[/tu] [ FRAME_ADDR|THREAD ][,COUNT]' - Stack trace. `u' option traces user space; if omitted, only traces - kernel space. If `t' option is specified, it shows the stack trace - of the specified thread or a default target thread. Otherwise, it - shows the stack trace of the current thread from the frame address - specified by a parameter or from the current frame. COUNT is the - number of frames to be traced. If the COUNT is omitted, all - frames are printed. - - Warning: If the target thread's stack is not in the main memory at - that time, the stack trace will fail. User space stack trace is - valid only if the machine dependent code supports it. - -`search[/bhl] ADDR VALUE [MASK] [,COUNT]' - Search memory for a value. This command might fail in interesting - ways if it doesn't find the searched-for value. This is because - `ddb' doesn't always recover from touching bad memory. The - optional count argument limits the search. - -`macro NAME COMMANDS' - Define a debugger macro as NAME. COMMANDS is a list of commands - to be associated with the macro. In the expressions of the - command list, a variable `$argxx' can be used to get a parameter - passed to the macro. When a macro is called, each argument is - evaluated as an expression, and the value is assigned to each - parameter, `$arg1', `$arg2', ... respectively. 10 `$arg' - variables are reserved to each level of macros, and they can be - used as local variables. The nesting of macro can be allowed up - to 5 levels. For example, - - macro xinit set $work0 $arg1 - macro xlist examine/m $work0,4; set $work0 *($work0) - xinit *(xxx_list) - xlist - .... - - will print the contents of a list starting from `xxx_list' by each - `xlist' command. - -`dmacro NAME' - Delete the macro named NAME. - -`show all threads[/ul]' - Display all tasks and threads information. This version of `ddb' - prints more information than previous one. It shows UNIX process - information like `ps' for each task. The UNIX process information - may not be shown if it is not supported in the machine, or the - bottom of the stack of the target task is not in the main memory at - that time. It also shows task and thread identification numbers. - These numbers can be used to specify a task or a thread - symbolically in various commands. The numbers are valid only in - the same debugger session. If the execution is resumed again, the - numbers may change. The current thread can be distinguished from - others by a `#' after the thread id instead of `:'. Without `l' - option, it only shows thread id, thread structure address and the - status for each thread. The status consists of 5 letters, R(run), - W(wait), S(sus pended), O(swapped out) and N(interruptible), and - if corresponding status bit is off, `.' is printed instead. If - `l' option is specified, more detail information is printed for - each thread. - -`show task [ ADDR ]' - Display the information of a task specified by ADDR. If ADDR is - omitted, current task information is displayed. - -`show thread [ ADDR ]' - Display the information of a thread specified by ADDR. If ADDR is - omitted, current thread information is displayed. - -`show registers[/tu [ THREAD ]]' - Display the register set. Target thread can be specified with `t' - option and THREAD parameter. If `u' option is specified, it - displays user registers instead of kernel or currently saved one. - - Warning: The support of `t' and `u' option depends on the machine. - If not supported, incorrect information will be displayed. - -`show map ADDR' - Prints the `vm_map' at ADDR. - -`show object ADDR' - Prints the `vm_object' at ADDR. - -`show page ADDR' - Prints the `vm_page' structure at ADDR. - -`show port ADDR' - Prints the `ipc_port' structure at ADDR. - -`show ipc_port[/t [ THREAD ]]' - Prints all `ipc_port' structure's addresses the target thread has. - The target thread is a current thread or that specified by a - parameter. - -`show macro [ NAME ]' - Show the definitions of macros. If NAME is specified, only the - definition of it is displayed. Otherwise, definitions of all - macros are displayed. - -`show watches' - Displays all watchpoints. - -`watch[/T] ADDR,SIZE [ TASK ]' - Set a watchpoint for a region. Execution stops when an attempt to - modify the region occurs. The SIZE argument defaults to 4. - Without `T' option, ADDR is assumed to be a kernel address. If - you want to set a watch point in user space, specify `T' and TASK - parameter where the address belongs to. If the TASK parameter is - omitted, a task of the default target thread or a current task is - assumed. If you specify a wrong space address, the request is - rejected with an error message. - - Warning: Attempts to watch wired kernel memory may cause - unrecoverable error in some systems such as i386. Watchpoints on - user addresses work best. - - -File: mach.info, Node: Variables, Next: Expressions, Prev: Commands, Up: Kernel Debugger - -11.3 Variables -============== - -The debugger accesses registers and variables as $NAME. Register names -are as in the `show registers' command. Some variables are suffixed -with numbers, and may have some modifier following a colon immediately -after the variable name. For example, register variables can have `u' -and `t' modifier to indicate user register and that of a default target -thread instead of that of the current thread (e.g. `$eax:tu'). - - Built-in variables currently supported are: - -`taskXX[.YY]' - Task or thread structure address. XX and YY are task and thread - identification numbers printed by a `show all threads' command - respectively. This variable is read only. - -`thread' - The default target thread. The value is used when `t' option is - specified without explicit thread structure address parameter in - command lines or expression evaluation. - -`radix' - Input and output radix - -`maxoff' - Addresses are printed as SYMBOL+OFFSET unless offset is greater - than maxoff. - -`maxwidth' - The width of the displayed line. - -`lines' - The number of lines. It is used by `more' feature. - -`tabstops' - Tab stop width. - -`argXX' - Parameters passed to a macro. XX can be 1 to 10. - -`workXX' - Work variable. XX can be 0 to 31. - - -File: mach.info, Node: Expressions, Prev: Variables, Up: Kernel Debugger - -11.4 Expressions -================ - -Almost all expression operators in C are supported except `~', `^', and -unary `&'. Special rules in `ddb' are: - -`IDENTIFIER' - name of a symbol. It is translated to the address(or value) of it. - `.' and `:' can be used in the identifier. If supported by an - object format dependent routine, [FILE_NAME:]FUNC[:LINE_NUMBER] - [FILE_NAME:]VARIABLE, and FILE_NAME[:LINE_NUMBER] can be accepted - as a symbol. The symbol may be prefixed with - `SYMBOL_TABLE_NAME::' like `emulator::mach_msg_trap' to specify - other than kernel symbols. - -`NUMBER' - radix is determined by the first two letters: - `0x' - hex - - `0o' - octal - - `0t' - decimal - - otherwise, follow current radix. - -`.' - dot - -`+' - next - -`..' - address of the start of the last line examined. Unlike dot or - next, this is only changed by `examine' or `write' command. - -`´' - last address explicitly specified. - -`$VARIABLE' - register name or variable. It is translated to the value of it. - It may be followed by a `:' and modifiers as described above. - -`a' - multiple of right hand side. - -`*EXPR' - indirection. It may be followed by a `:' and modifiers as - described above. - - -File: mach.info, Node: Copying, Next: Documentation License, Prev: Kernel Debugger, Up: Top - -Appendix A GNU GENERAL PUBLIC LICENSE -************************************* - - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - -A.0.1 Preamble --------------- - -The licenses for most software are designed to take away your freedom -to share and change it. By contrast, the GNU General Public License is -intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it in -new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, -and (2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - 1. This License applies to any program or other work which contains a - notice placed by the copyright holder saying it may be distributed - under the terms of this General Public License. The "Program", - below, refers to any such program or work, and a "work based on - the Program" means either the Program or any derivative work under - copyright law: that is to say, a work containing the Program or a - portion of it, either verbatim or with modifications and/or - translated into another language. (Hereinafter, translation is - included without limitation in the term "modification".) Each - licensee is addressed as "you". - - Activities other than copying, distribution and modification are - not covered by this License; they are outside its scope. The act - of running the Program is not restricted, and the output from the - Program is covered only if its contents constitute a work based on - the Program (independent of having been made by running the - Program). Whether that is true depends on what the Program does. - - 2. You may copy and distribute verbatim copies of the Program's - source code as you receive it, in any medium, provided that you - conspicuously and appropriately publish on each copy an appropriate - copyright notice and disclaimer of warranty; keep intact all the - notices that refer to this License and to the absence of any - warranty; and give any other recipients of the Program a copy of - this License along with the Program. - - You may charge a fee for the physical act of transferring a copy, - and you may at your option offer warranty protection in exchange - for a fee. - - 3. You may modify your copy or copies of the Program or any portion - of it, thus forming a work based on the Program, and copy and - distribute such modifications or work under the terms of Section 1 - above, provided that you also meet all of these conditions: - - a. You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b. You must cause any work that you distribute or publish, that - in whole or in part contains or is derived from the Program - or any part thereof, to be licensed as a whole at no charge - to all third parties under the terms of this License. - - c. If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display - an announcement including an appropriate copyright notice and - a notice that there is no warranty (or else, saying that you - provide a warranty) and that users may redistribute the - program under these conditions, and telling the user how to - view a copy of this License. (Exception: if the Program - itself is interactive but does not normally print such an - announcement, your work based on the Program is not required - to print an announcement.) - - These requirements apply to the modified work as a whole. If - identifiable sections of that work are not derived from the - Program, and can be reasonably considered independent and separate - works in themselves, then this License, and its terms, do not - apply to those sections when you distribute them as separate - works. But when you distribute the same sections as part of a - whole which is a work based on the Program, the distribution of - the whole must be on the terms of this License, whose permissions - for other licensees extend to the entire whole, and thus to each - and every part regardless of who wrote it. - - Thus, it is not the intent of this section to claim rights or - contest your rights to work written entirely by you; rather, the - intent is to exercise the right to control the distribution of - derivative or collective works based on the Program. - - In addition, mere aggregation of another work not based on the - Program with the Program (or with a work based on the Program) on - a volume of a storage or distribution medium does not bring the - other work under the scope of this License. - - 4. You may copy and distribute the Program (or a work based on it, - under Section 2) in object code or executable form under the terms - of Sections 1 and 2 above provided that you also do one of the - following: - - a. Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of - Sections 1 and 2 above on a medium customarily used for - software interchange; or, - - b. Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a - medium customarily used for software interchange; or, - - c. Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with - such an offer, in accord with Subsection b above.) - - The source code for a work means the preferred form of the work for - making modifications to it. For an executable work, complete - source code means all the source code for all modules it contains, - plus any associated interface definition files, plus the scripts - used to control compilation and installation of the executable. - However, as a special exception, the source code distributed need - not include anything that is normally distributed (in either - source or binary form) with the major components (compiler, - kernel, and so on) of the operating system on which the executable - runs, unless that component itself accompanies the executable. - - If distribution of executable or object code is made by offering - access to copy from a designated place, then offering equivalent - access to copy the source code from the same place counts as - distribution of the source code, even though third parties are not - compelled to copy the source along with the object code. - - 5. You may not copy, modify, sublicense, or distribute the Program - except as expressly provided under this License. Any attempt - otherwise to copy, modify, sublicense or distribute the Program is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 6. You are not required to accept this License, since you have not - signed it. However, nothing else grants you permission to modify - or distribute the Program or its derivative works. These actions - are prohibited by law if you do not accept this License. - Therefore, by modifying or distributing the Program (or any work - based on the Program), you indicate your acceptance of this - License to do so, and all its terms and conditions for copying, - distributing or modifying the Program or works based on it. - - 7. Each time you redistribute the Program (or any work based on the - Program), the recipient automatically receives a license from the - original licensor to copy, distribute or modify the Program - subject to these terms and conditions. You may not impose any - further restrictions on the recipients' exercise of the rights - granted herein. You are not responsible for enforcing compliance - by third parties to this License. - - 8. If, as a consequence of a court judgment or allegation of patent - infringement or for any other reason (not limited to patent - issues), conditions are imposed on you (whether by court order, - agreement or otherwise) that contradict the conditions of this - License, they do not excuse you from the conditions of this - License. If you cannot distribute so as to satisfy simultaneously - your obligations under this License and any other pertinent - obligations, then as a consequence you may not distribute the - Program at all. For example, if a patent license would not permit - royalty-free redistribution of the Program by all those who - receive copies directly or indirectly through you, then the only - way you could satisfy both it and this License would be to refrain - entirely from distribution of the Program. - - If any portion of this section is held invalid or unenforceable - under any particular circumstance, the balance of the section is - intended to apply and the section as a whole is intended to apply - in other circumstances. - - It is not the purpose of this section to induce you to infringe any - patents or other property right claims or to contest validity of - any such claims; this section has the sole purpose of protecting - the integrity of the free software distribution system, which is - implemented by public license practices. Many people have made - generous contributions to the wide range of software distributed - through that system in reliance on consistent application of that - system; it is up to the author/donor to decide if he or she is - willing to distribute software through any other system and a - licensee cannot impose that choice. - - This section is intended to make thoroughly clear what is believed - to be a consequence of the rest of this License. - - 9. If the distribution and/or use of the Program is restricted in - certain countries either by patents or by copyrighted interfaces, - the original copyright holder who places the Program under this - License may add an explicit geographical distribution limitation - excluding those countries, so that distribution is permitted only - in or among countries not thus excluded. In such case, this - License incorporates the limitation as if written in the body of - this License. - - 10. The Free Software Foundation may publish revised and/or new - versions of the General Public License from time to time. Such - new versions will be similar in spirit to the present version, but - may differ in detail to address new problems or concerns. - - Each version is given a distinguishing version number. If the - Program specifies a version number of this License which applies - to it and "any later version", you have the option of following - the terms and conditions either of that version or of any later - version published by the Free Software Foundation. If the Program - does not specify a version number of this License, you may choose - any version ever published by the Free Software Foundation. - - 11. If you wish to incorporate parts of the Program into other free - programs whose distribution conditions are different, write to the - author to ask for permission. For software which is copyrighted - by the Free Software Foundation, write to the Free Software - Foundation; we sometimes make exceptions for this. Our decision - will be guided by the two goals of preserving the free status of - all derivatives of our free software and of promoting the sharing - and reuse of software generally. - - NO WARRANTY - 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO - WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE - LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT - HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT - WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT - NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE - QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE - PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY - SERVICING, REPAIR OR CORRECTION. - - 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN - WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY - MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE - LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, - INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR - INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF - DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU - OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY - OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN - ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS -How to Apply These Terms to Your New Programs -============================================= - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES. - Copyright (C) 19YY NAME OF AUTHOR - - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. - - Also add information on how to contact you by electronic and paper -mail. - - If the program is interactive, make it output a short notice like -this when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details - type `show w'. This is free software, and you are welcome - to redistribute it under certain conditions; type `show c' - for details. - - The hypothetical commands `show w' and `show c' should show the -appropriate parts of the General Public License. Of course, the -commands you use may be called something other than `show w' and `show -c'; they could even be mouse-clicks or menu items--whatever suits your -program. - - You should also get your employer (if you work as a programmer) or -your school, if any, to sign a "copyright disclaimer" for the program, -if necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright - interest in the program `Gnomovision' - (which makes passes at compilers) written - by James Hacker. - - SIGNATURE OF TY COON, 1 April 1989 - Ty Coon, President of Vice - - This General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use the -GNU Library General Public License instead of this License. - - -File: mach.info, Node: Documentation License, Next: Concept Index, Prev: Copying, Up: Top - -Appendix B Documentation License -******************************** - -This manual is copyrighted and licensed under the GNU Free Documentation -license. - - Parts of this manual are derived from the Mach manual packages -originally provided by Carnegie Mellon University. - -* Menu: - -* Free Documentation License:: The GNU Free Documentation License. -* CMU License:: The CMU license applies to the original Mach - kernel and its documentation. - - -File: mach.info, Node: Free Documentation License, Next: CMU License, Up: Documentation License - -B.1 GNU Free Documentation License -================================== - - Version 1.1, March 2000 - - Copyright (C) 2000 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you". - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter - section of the Document that deals exclusively with the - relationship of the publishers or authors of the Document to the - Document's overall subject (or to related matters) and contains - nothing that could fall directly within that overall subject. - (For example, if the Document is in part a textbook of - mathematics, a Secondary Section may not explain any mathematics.) - The relationship could be a matter of historical connection with - the subject or with related matters, or of legal, commercial, - philosophical, ethical or political position regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup has been designed - to thwart or discourage subsequent modification by readers is not - Transparent. A copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML designed for human modification. - Opaque formats include PostScript, PDF, proprietary formats that - can be read and edited only by proprietary word processors, SGML - or XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML produced by some word - processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies of the Document numbering more than - 100, and the Document's license notice requires Cover Texts, you - must enclose the copies in covers that carry, clearly and legibly, - all these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a publicly-accessible - computer-network location containing a complete Transparent copy - of the Document, free of added material, which the general - network-using public has access to download anonymously at no - charge using public-standard network protocols. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has less than five). - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section entitled "History", and its title, and - add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. In any section entitled "Acknowledgments" or "Dedications", - preserve the section's title, and preserve in the section all - the substance and tone of each of the contributor - acknowledgments and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections entitled - "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgments", and any sections entitled "Dedications". You - must delete all sections entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation - copyright is claimed for the compilation. Such a compilation is - called an "aggregate", and this License does not apply to the - other self-contained works thus compiled with the Document, on - account of their being thus compiled, if they are not themselves - derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one - quarter of the entire aggregate, the Document's Cover Texts may be - placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License provided that you also include the - original English version of this License. In case of a - disagreement between the translation and the original English - version of this License, the original English version will prevail. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - -B.1.0.1 ADDENDUM: How to use this License for your documents -............................................................ - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no Front-Cover -Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being -LIST"; likewise for Back-Cover Texts. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, to -permit their use in free software. - - -File: mach.info, Node: CMU License, Prev: Free Documentation License, Up: Documentation License - -B.2 CMU License -=============== - - Mach Operating System - Copyright (C) 1991,1990,1989 Carnegie Mellon University - All Rights Reserved. - - Permission to use, copy, modify and distribute this software and - its documentation is hereby granted, provided that both the - copyright notice and this permission notice appear in all copies - of the software, derivative works or modified versions, and any - portions thereof, and that both notices appear in supporting - documentation. - - CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" - CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR - ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. - - Carnegie Mellon requests users of this software to return to - - Software Distribution Coordinator - School of Computer Science - Carnegie Mellon University - Pittsburgh PA 15213-3890 - - or <Software.Distribution@CS.CMU.EDU> any improvements or - extensions that they make and grant Carnegie Mellon the rights to - redistribute these changes. - - -File: mach.info, Node: Concept Index, Next: Function and Data Index, Prev: Documentation License, Up: Top - -Concept Index -************* - - -* Menu: - -* communication between tasks: Major Concepts. (line 6) -* composing messages: Message Format. (line 6) -* device port: Device Interface. (line 13) -* FDL, GNU Free Documentation License: Free Documentation License. - (line 6) -* format of a message: Message Format. (line 6) -* GPL, GNU General Public License: Copying. (line 6) -* GRand Unified Bootloader: Bootloader. (line 13) -* GRUB: Bootloader. (line 13) -* host control port: Host Ports. (line 34) -* host interface: Host Interface. (line 6) -* host name port: Host Ports. (line 6) -* host ports: Host Ports. (line 6) -* interprocess communication (IPC): Major Concepts. (line 6) -* IPC (interprocess communication): Major Concepts. (line 6) -* IPC space port: Port Manipulation Interface. - (line 9) -* message composition: Message Format. (line 6) -* message format: Message Format. (line 6) -* messages: Major Concepts. (line 6) -* moving port rights: Exchanging Port Rights. - (line 6) -* port representing a device: Device Interface. (line 13) -* port representing a processor: Processor Interface. (line 6) -* port representing a processor set name: Processor Set Ports. (line 6) -* port representing a task: Task Interface. (line 6) -* port representing a thread: Thread Interface. (line 6) -* port representing a virtual memory map: Virtual Memory Interface. - (line 6) -* port representing an IPC space: Port Manipulation Interface. - (line 9) -* ports representing a host: Host Ports. (line 6) -* ports representing a processor set: Processor Set Ports. (line 6) -* processor port: Processor Interface. (line 6) -* processor set name port: Processor Set Ports. (line 6) -* processor set port: Processor Set Ports. (line 13) -* processor set ports: Processor Set Ports. (line 6) -* receiving memory: Memory. (line 6) -* receiving port rights: Exchanging Port Rights. - (line 6) -* remote procedure calls (RPC): Major Concepts. (line 6) -* RPC (remote procedure calls): Major Concepts. (line 6) -* sending memory: Memory. (line 6) -* sending messages: Message Send. (line 6) -* sending port rights: Exchanging Port Rights. - (line 6) -* serverboot: Modules. (line 6) -* task port: Task Interface. (line 6) -* thread port: Thread Interface. (line 6) -* virtual memory map port: Virtual Memory Interface. - (line 6) - - -File: mach.info, Node: Function and Data Index, Prev: Concept Index, Up: Top - -Function and Data Index -*********************** - - -* Menu: - -* catch_exception_raise: Exceptions. (line 9) -* device_close: Device Close. (line 7) -* device_get_status: Device Status. (line 20) -* device_map: Device Map. (line 9) -* device_open: Device Open. (line 8) -* device_open_request: Device Open. (line 36) -* device_read: Device Read. (line 9) -* device_read_inband: Device Read. (line 27) -* device_read_request: Device Read. (line 34) -* device_read_request_inband: Device Read. (line 51) -* device_reply_server: Device Reply Server. (line 12) -* device_set_filter: Device Filter. (line 10) -* device_set_status: Device Status. (line 9) -* device_t: Device Interface. (line 14) -* device_write: Device Write. (line 9) -* device_write_inband: Device Write. (line 24) -* device_write_request: Device Write. (line 31) -* device_write_request_inband: Device Write. (line 49) -* ds_device_open_reply: Device Open. (line 39) -* ds_device_read_reply: Device Read. (line 37) -* ds_device_read_reply_inband: Device Read. (line 54) -* ds_device_write_reply: Device Write. (line 34) -* ds_device_write_reply_inband: Device Write. (line 52) -* evc_wait: Exceptions. (line 18) -* exception_raise: Exceptions. (line 15) -* host_adjust_time: Host Time. (line 43) -* host_basic_info_t: Host Information. (line 75) -* host_get_boot_info: Host Information. (line 114) -* host_get_time: Host Time. (line 34) -* host_info: Host Information. (line 9) -* host_kernel_version: Host Information. (line 96) -* host_priv_t: Host Ports. (line 35) -* host_processor_set_priv: Processor Set Access. - (line 25) -* host_processor_sets: Processor Set Access. - (line 9) -* host_processors: Hosted Processors. (line 9) -* host_reboot: Host Reboot. (line 8) -* host_sched_info_t: Host Information. (line 92) -* host_set_time: Host Time. (line 39) -* host_t: Host Ports. (line 7) -* ipc_space_t: Port Manipulation Interface. - (line 10) -* mach_host_self: Host Ports. (line 14) -* mach_msg: Mach Message Call. (line 13) -* mach_msg_bits_t: Message Format. (line 21) -* mach_msg_header_t: Message Format. (line 33) -* mach_msg_id_t: Message Format. (line 29) -* mach_msg_size_t: Message Format. (line 25) -* mach_msg_timeout_t: Mach Message Call. (line 61) -* mach_msg_type_long_t: Message Format. (line 248) -* mach_msg_type_name_t: Message Format. (line 128) -* mach_msg_type_number_t: Message Format. (line 138) -* MACH_MSG_TYPE_PORT_ANY: Message Format. (line 234) -* MACH_MSG_TYPE_PORT_ANY_RIGHT: Message Format. (line 244) -* MACH_MSG_TYPE_PORT_ANY_SEND: Message Format. (line 239) -* mach_msg_type_size_t: Message Format. (line 133) -* mach_msg_type_t: Message Format. (line 143) -* MACH_MSGH_BITS: Message Format. (line 96) -* MACH_MSGH_BITS_LOCAL: Message Format. (line 108) -* MACH_MSGH_BITS_OTHER: Message Format. (line 117) -* MACH_MSGH_BITS_PORTS: Message Format. (line 112) -* MACH_MSGH_BITS_REMOTE: Message Format. (line 103) -* mach_port_allocate: Port Creation. (line 8) -* mach_port_allocate_name: Port Creation. (line 66) -* mach_port_deallocate: Port Destruction. (line 8) -* mach_port_destroy: Port Destruction. (line 30) -* mach_port_extract_right: Ports and other Tasks. - (line 59) -* mach_port_get_receive_status: Receive Rights. (line 57) -* mach_port_get_refs: Port Rights. (line 9) -* mach_port_get_set_status: Port Sets. (line 9) -* mach_port_insert_right: Ports and other Tasks. - (line 9) -* mach_port_mod_refs: Port Rights. (line 42) -* mach_port_move_member: Port Sets. (line 28) -* mach_port_mscount_t: Receive Rights. (line 11) -* mach_port_msgcount_t: Receive Rights. (line 15) -* mach_port_names: Port Names. (line 9) -* mach_port_rename: Port Names. (line 77) -* mach_port_request_notification: Request Notifications. - (line 10) -* mach_port_rights_t: Receive Rights. (line 19) -* mach_port_seqno_t: Receive Rights. (line 7) -* mach_port_set_mscount: Receive Rights. (line 73) -* mach_port_set_qlimit: Receive Rights. (line 90) -* mach_port_set_seqno: Receive Rights. (line 108) -* mach_port_status_t: Receive Rights. (line 23) -* mach_port_t: Message Format. (line 14) -* mach_port_type: Port Names. (line 35) -* mach_reply_port: Port Creation. (line 48) -* mach_task_self: Task Information. (line 7) -* mach_thread_self: Thread Information. (line 7) -* mapped_time_value_t: Host Time. (line 51) -* memory_object_change_attributes: Memory Object Attributes. - (line 30) -* memory_object_change_completed: Memory Object Attributes. - (line 63) -* memory_object_copy: Memory Objects and Data. - (line 209) -* memory_object_create: Default Memory Manager. - (line 30) -* memory_object_data_error: Memory Objects and Data. - (line 157) -* memory_object_data_initialize: Default Memory Manager. - (line 73) -* memory_object_data_provided: Memory Objects and Data. - (line 289) -* memory_object_data_request: Memory Objects and Data. - (line 49) -* memory_object_data_return: Memory Objects and Data. - (line 11) -* memory_object_data_supply: Memory Objects and Data. - (line 84) -* memory_object_data_unavailable: Memory Objects and Data. - (line 177) -* memory_object_data_unlock: Memory Object Locking. - (line 85) -* memory_object_data_write: Memory Objects and Data. - (line 260) -* memory_object_default_server: Memory Object Server. - (line 10) -* memory_object_destroy: Memory Object Termination. - (line 37) -* memory_object_get_attributes: Memory Object Attributes. - (line 10) -* memory_object_init: Memory Object Creation. - (line 11) -* memory_object_lock_completed: Memory Object Locking. - (line 59) -* memory_object_lock_request: Memory Object Locking. - (line 11) -* memory_object_ready: Memory Object Creation. - (line 52) -* memory_object_server: Memory Object Server. - (line 8) -* memory_object_set_attributes: Memory Object Attributes. - (line 82) -* memory_object_supply_completed: Memory Objects and Data. - (line 127) -* memory_object_terminate: Memory Object Termination. - (line 10) -* processor_assign: Processors and Sets. (line 8) -* processor_basic_info_t: Processor Info. (line 67) -* processor_control: Processor Control. (line 10) -* processor_exit: Processor Control. (line 8) -* processor_get_assignment: Processors and Sets. (line 32) -* processor_info: Processor Info. (line 9) -* processor_set_basic_info_t: Processor Set Info. (line 75) -* processor_set_create: Processor Set Creation. - (line 8) -* processor_set_default: Processor Set Access. - (line 36) -* processor_set_destroy: Processor Set Destruction. - (line 8) -* processor_set_info: Processor Set Info. (line 10) -* processor_set_max_priority: Processor Set Priority. - (line 9) -* processor_set_name_t: Processor Set Ports. (line 7) -* processor_set_policy_disable: Processor Set Policy. - (line 11) -* processor_set_policy_enable: Processor Set Policy. - (line 8) -* processor_set_sched_info_t: Processor Set Info. (line 93) -* processor_set_t: Processor Set Ports. (line 14) -* processor_set_tasks: Tasks and Threads on Sets. - (line 9) -* processor_set_threads: Tasks and Threads on Sets. - (line 23) -* processor_start: Processor Control. (line 7) -* processor_t: Processor Interface. (line 7) -* sampled_pc_flavor_t: Profiling. (line 67) -* sampled_pc_t: Profiling. (line 52) -* seqnos_memory_object_change_completed: Memory Object Attributes. - (line 67) -* seqnos_memory_object_copy: Memory Objects and Data. - (line 214) -* seqnos_memory_object_create: Default Memory Manager. - (line 35) -* seqnos_memory_object_data_initialize: Default Memory Manager. - (line 77) -* seqnos_memory_object_data_request: Memory Objects and Data. - (line 53) -* seqnos_memory_object_data_return: Memory Objects and Data. - (line 16) -* seqnos_memory_object_data_unlock: Memory Object Locking. - (line 89) -* seqnos_memory_object_data_write: Memory Objects and Data. - (line 264) -* seqnos_memory_object_default_server: Memory Object Server. - (line 14) -* seqnos_memory_object_init: Memory Object Creation. - (line 16) -* seqnos_memory_object_lock_completed: Memory Object Locking. - (line 63) -* seqnos_memory_object_server: Memory Object Server. - (line 12) -* seqnos_memory_object_supply_completed: Memory Objects and Data. - (line 132) -* seqnos_memory_object_terminate: Memory Object Termination. - (line 14) -* struct host_basic_info: Host Information. (line 48) -* struct host_sched_info: Host Information. (line 78) -* struct processor_basic_info: Processor Info. (line 44) -* struct processor_set_basic_info: Processor Set Info. (line 51) -* struct processor_set_sched_info: Processor Set Info. (line 78) -* struct task_basic_info: Task Information. (line 82) -* struct task_events_info: Task Information. (line 114) -* struct task_thread_times_info: Task Information. (line 145) -* struct thread_basic_info: Thread Information. (line 66) -* struct thread_sched_info: Thread Information. (line 128) -* swtch: Hand-Off Scheduling. (line 81) -* swtch_pri: Hand-Off Scheduling. (line 93) -* task_assign: Tasks and Threads on Sets. - (line 36) -* task_assign_default: Tasks and Threads on Sets. - (line 49) -* task_basic_info_t: Task Information. (line 111) -* task_create: Task Creation. (line 8) -* task_disable_pc_sampling: Profiling. (line 22) -* task_enable_pc_sampling: Profiling. (line 8) -* task_events_info_t: Task Information. (line 142) -* task_get_assignment: Tasks and Threads on Sets. - (line 60) -* task_get_bootstrap_port: Task Special Ports. (line 42) -* task_get_emulation_vector: Syscall Emulation. (line 9) -* task_get_exception_port: Task Special Ports. (line 36) -* task_get_kernel_port: Task Special Ports. (line 30) -* task_get_sampled_pcs: Profiling. (line 36) -* task_get_special_port: Task Special Ports. (line 8) -* task_info: Task Information. (line 44) -* task_priority: Task Execution. (line 29) -* task_ras_control: Task Execution. (line 47) -* task_resume: Task Execution. (line 19) -* task_set_bootstrap_port: Task Special Ports. (line 78) -* task_set_emulation: Syscall Emulation. (line 22) -* task_set_emulation_vector: Syscall Emulation. (line 15) -* task_set_exception_port: Task Special Ports. (line 72) -* task_set_kernel_port: Task Special Ports. (line 66) -* task_set_special_port: Task Special Ports. (line 48) -* task_suspend: Task Execution. (line 7) -* task_t: Task Interface. (line 7) -* task_terminate: Task Termination. (line 7) -* task_thread_times_info_t: Task Information. (line 159) -* task_threads: Task Information. (line 33) -* thread_abort: Thread Execution. (line 38) -* thread_assign: Tasks and Threads on Sets. - (line 72) -* thread_assign_default: Tasks and Threads on Sets. - (line 85) -* thread_basic_info_t: Thread Information. (line 125) -* thread_create: Thread Creation. (line 8) -* thread_depress_abort: Hand-Off Scheduling. (line 74) -* thread_disable_pc_sampling: Profiling. (line 24) -* thread_enable_pc_sampling: Profiling. (line 10) -* thread_get_assignment: Tasks and Threads on Sets. - (line 96) -* thread_get_exception_port: Thread Special Ports. - (line 27) -* thread_get_kernel_port: Thread Special Ports. - (line 21) -* thread_get_sampled_pcs: Profiling. (line 39) -* thread_get_special_port: Thread Special Ports. - (line 8) -* thread_get_state: Thread Execution. (line 102) -* thread_info: Thread Information. (line 33) -* thread_max_priority: Thread Priority. (line 38) -* thread_policy: Scheduling Policy. (line 8) -* thread_priority: Thread Priority. (line 20) -* thread_resume: Thread Execution. (line 29) -* thread_sched_info_t: Thread Information. (line 159) -* thread_set_exception_port: Thread Special Ports. - (line 52) -* thread_set_kernel_port: Thread Special Ports. - (line 46) -* thread_set_special_port: Thread Special Ports. - (line 33) -* thread_set_state: Thread Execution. (line 126) -* thread_suspend: Thread Execution. (line 7) -* thread_switch: Hand-Off Scheduling. (line 8) -* thread_t: Thread Interface. (line 7) -* thread_terminate: Thread Termination. (line 7) -* thread_wire: Thread Settings. (line 8) -* time_value_add: Host Time. (line 25) -* time_value_add_usec: Host Time. (line 21) -* time_value_t: Host Time. (line 7) -* vm_allocate: Memory Allocation. (line 8) -* vm_copy: Data Transfer. (line 53) -* vm_deallocate: Memory Deallocation. (line 8) -* vm_inherit: Memory Attributes. (line 70) -* vm_machine_attribute: Memory Attributes. (line 134) -* vm_map: Mapping Memory Objects. - (line 11) -* vm_protect: Memory Attributes. (line 36) -* vm_read: Data Transfer. (line 9) -* vm_region: Memory Attributes. (line 11) -* vm_set_default_memory_manager: Default Memory Manager. - (line 8) -* vm_statistics: Memory Statistics. (line 52) -* vm_statistics_data_t: Memory Statistics. (line 7) -* vm_task_t: Virtual Memory Interface. - (line 7) -* vm_wire: Memory Attributes. (line 101) -* vm_write: Data Transfer. (line 34) - - diff --git a/doc/stamp-vti b/doc/stamp-vti deleted file mode 100644 index cab3d80..0000000 --- a/doc/stamp-vti +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 7 October 2006 -@set UPDATED-MONTH October 2006 -@set EDITION 1.3.99 -@set VERSION 1.3.99 diff --git a/doc/version.texi b/doc/version.texi deleted file mode 100644 index cab3d80..0000000 --- a/doc/version.texi +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 7 October 2006 -@set UPDATED-MONTH October 2006 -@set EDITION 1.3.99 -@set VERSION 1.3.99 |