summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorThomas Schwinge <tschwinge@gnu.org>2007-01-11 01:05:45 +0000
committerThomas Schwinge <tschwinge@gnu.org>2009-06-18 00:27:01 +0200
commitc03c222abe9958b563a78172dddd84e96ef10051 (patch)
treeeed6b7b2bc87052b104fec48cdeedb87c88d69c4 /doc
parent3527b78c645a5898c7ddbeb3128a49c21514cb1c (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.info175
-rw-r--r--doc/mach.info-16683
-rw-r--r--doc/mach.info-21663
-rw-r--r--doc/stamp-vti4
-rw-r--r--doc/version.texi4
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
- hand­off 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