WHATIS: Mach Ports

[Marcus Brinkmann]

Hi,

I wrote this for inclusion in the What Is area of the web page.  It is only
a first draft, and not complete yet, but after the horrible confusion
yesterday, it would be nice if someone could skim over it.  Any comments
appreciated!

Thanks,
Marcus

2001-05-07  Marcus Brinkmann  <marcus@gnu.org>

        * Initial release.


What Is?

Mach Ports
by Marcus Brinkmann


Mach ports are a basic component of the Mach interprocess
communication (IPC) facilities.  They are used to provide a one-way
channel of communication for message passing.  Only one entity (the
kernel or a user task) can receive messages from a port, but anyone
with permission may sent to it.  This document describes Mach ports,
port names, port rights, how they are used and implemented.

The basic object is a Mach port.  All ports are protected kernel
objects, and are not manipulated directly by the user.  To the kernel,
a port is an object of the struct ipc_port type
(mach:/ipc/ipc_port.h), which includes information about the port
properties as well as internal data structures like locks, a message
queue, pointers to related objects etc.  This interface is completely
hidden from the user by the port name abstraction.

The standard way to refer to a port is by using a port name in a port
name space.  Every task has a port name space, and the kernel has one,
too.  The name space doesn't contain the ports.  Rather, it contains a
list of port names.  Any port name is a mach_port_t (unsigned
integer), and refers to a port.  The port name spaces are also
protected by the kernel.  A user can't simply add and remove entries
in the port name space, he has to rely on the kernel to do it on
request.  This way, any task can only access and manipulate ports for
which he has the permission.  You can think of the port name space as
a table, although it is implemented as a comination of a table and a
tree structure for efficiency (sparse, high port names are stored in
the tree, low, dense port names in the table, see
mach:/ipc/ipc_space.h, struct ipc_space).  Note that a port name only
is meaningful in the context of a port name space.

[Actually, the truth is a bit more complicated.  The ipc space
 contains ipc entries, which describe capabilities for generic ipc
 objects.  Such an object can be a port, but also a port set.
 See mach:/ipc/ipc_entry.h, struct ipc_entry]

Associated with a port name is one or several port rights.  Port
rights describe capabilities for this user of a port.  For example, if
a task has the right to recieve a message from a port, the port name
for this port in the task's port name space has the flag
MACH_PORT_RIGHT_RECEIVE set.  The basic rights are

MACH_PORT_RIGHT_RECEIVE
  User has permission to receive the messages to the port described by
  the port name.

MACH_PORT_RIGHT_SEND
  User has permission to send messages to the port described by the
  port name.

MACH_PORT_RIGHT_SEND_ONCE
  User has permission to send exactly one message to the port
  described by the port name (and if he doesn't, the kernel will send
  a notification message instead).

In the port name space, all receive and send rights for the same port
are collected in a single port name entry.  Only one receive right is
permittible for any port, so the reference count of the receive rights
for any given port name is either 0 or 1.  If it is 1, no other port
name referring to the same port in this or other port name spaces has
a receive right for this port.  In contrast to that, the number of
possible send rights is arbitrary, and other port name spaces might
also contain a port name denoting send rights to the same port.

However, send-once rights are special as every send-once right gets
its own port name.  So, you can either have 0 or 1 receive right and
an arbitrary number of send rights in one port name, or no receive and
send rights and exactly one send-once right.

You can use a port name denoting a send or send-once right as the
port argument to a mach_msg_send call to send a message to the port.
You can use a port name denoting a receive right as the port argument
to a mach_msg_receive call to receive a message from the port.  The
message is taken from the message queue of the port.  If you have a
port name with a receive right for a port in your name space, you know
that no other port name (neither in this nor in other port name
spaces) exist, so you are the only one who can receive messages to
this port (and exclusively with this port name).

Ports are created with mach_port_allocate, mach_port_allocate_name or
mach_reply_port.  Any of these can create a new port, and a port name
for this port is creating in the tasks port name space.  The port name
will hold the receive right for this port, but no other rights are
created.  The mach_port_insert_right call can be used to acquire new
send and send-once rights.  Port rights can also be transferred in
messages.

After a send right is not used any longer, or if there is no need to
make use of the send-once right, the port right can be removed with
mach_port_deallocate.  The respective reference count is decremented
by 1 (there is no confusion possible about which type is meant, send
or send-once, as any port name only denotes either right).
Alternatively, arbitrary changes to the reference count can be made
with mach_port_mod_refs.  If a port names reference counters are all
zero, the port name is removed from the port name space.  This can
also be requested explicitely with mach_port_destroy.  The port itself
is not affected, unless the receive right was removed.  In this case,
the port itself is destroyed and all dangling send and send-once
rights to this port are turned into MACH_PORT_RIGHT_DEAD_NAME, as the
port name now refers to a non-existing port.

TODO
----
port sets
notification messages
more references to source
more details about the interfaces
more interfaces
messages, mach ipc

-- 
`Rhubarb is no Egyptian god.' Debian http://www.debian.org brinkmd@debian.org
Marcus Brinkmann              GNU    http://www.gnu.org    marcus@gnu.org
Marcus.Brinkmann@ruhr-uni-bochum.de
http://www.marcus-brinkmann.de