merge
This commit is contained in:
commit
b6eee91029
829
sys/doc/8½/8½.ms
Normal file
829
sys/doc/8½/8½.ms
Normal file
|
@ -0,0 +1,829 @@
|
||||||
|
.HTML "8½, the Plan 9 Window System
|
||||||
|
.TL
|
||||||
|
8½, the Plan 9 Window System
|
||||||
|
.AU
|
||||||
|
Rob Pike
|
||||||
|
rob@plan9.bell-labs.com
|
||||||
|
.AB
|
||||||
|
.FS
|
||||||
|
Originally appeared, in a slightly different form, in
|
||||||
|
.I
|
||||||
|
Proc. of the Summer 1991 USENIX Conf.,
|
||||||
|
.R
|
||||||
|
pp. 257-265,
|
||||||
|
Nashville.
|
||||||
|
Note that
|
||||||
|
.CW 8½
|
||||||
|
has been replaced by
|
||||||
|
.CW rio
|
||||||
|
(see
|
||||||
|
.I rio (1)).
|
||||||
|
.FE
|
||||||
|
The Plan 9 window system, 8½, is a modest-sized program of novel design.
|
||||||
|
It provides textual I/O and bitmap graphic services to both
|
||||||
|
local and remote client programs by offering a multiplexed file service to those clients.
|
||||||
|
It serves traditional UNIX files like
|
||||||
|
.CW /dev/tty
|
||||||
|
as well as more unusual ones that provide access to the mouse
|
||||||
|
and the raw screen.
|
||||||
|
Bitmap graphics operations are provided by serving a file called
|
||||||
|
.CW /dev/bitblt
|
||||||
|
that interprets client messages to perform raster operations.
|
||||||
|
The file service that 8½ offers its clients is identical to that it uses for
|
||||||
|
its own implementation, so it is fundamentally no more than
|
||||||
|
a multiplexer.
|
||||||
|
This architecture has some rewarding symmetries and can be implemented
|
||||||
|
compactly.
|
||||||
|
.AE
|
||||||
|
.SH
|
||||||
|
Introduction
|
||||||
|
.PP
|
||||||
|
In 1989 I constructed a toy window system from only a few hundred
|
||||||
|
lines of source code using a custom language and an unusual architecture
|
||||||
|
involving concurrent processes [Pike89].
|
||||||
|
Although that system was rudimentary at best, it demonstrated that
|
||||||
|
window systems are not inherently complicated.
|
||||||
|
The following year, for the new Plan 9 distributed system [Pike92], I applied some of
|
||||||
|
the lessons from that toy project to write, in C,
|
||||||
|
a production-quality window system
|
||||||
|
called 8½.
|
||||||
|
8½ provides, on black-and-white, grey-scale, or color displays,
|
||||||
|
the services required of a modern window system, including
|
||||||
|
programmability and support for remote graphics.
|
||||||
|
The entire system, including the default program that runs in the
|
||||||
|
window \(em the equivalent of
|
||||||
|
.CW xterm
|
||||||
|
[Far89] with `cutting and pasting' between windows \(em
|
||||||
|
is well under 90 kilobytes of text on a Motorola 68020 processor, about
|
||||||
|
half the size of the
|
||||||
|
operating system
|
||||||
|
kernel that supports it and a tenth the size of the X server
|
||||||
|
[Sche86]
|
||||||
|
.I without
|
||||||
|
.CW xterm .
|
||||||
|
.PP
|
||||||
|
What makes 8½ so compact? Much of the saving comes from overall simplicity:
|
||||||
|
8½ has little graphical fanciness, a concise programming interface, and
|
||||||
|
a simple, fixed user interface.
|
||||||
|
8½ also makes some decisions by fiat
|
||||||
|
\(em three-button mouse, overlapping windows, built-in terminal program and
|
||||||
|
window manager, etc. \(em
|
||||||
|
rather than trying to appeal to all tastes.
|
||||||
|
Although compact, 8½ is not ascetic.
|
||||||
|
It provides the fundamentals and
|
||||||
|
enough extras to make them comfortable to use.
|
||||||
|
The most important contributor to its small size, though, is its
|
||||||
|
overall design as a file server.
|
||||||
|
This structure may be applicable to window systems
|
||||||
|
on traditional UNIX-like operating systems.
|
||||||
|
.PP
|
||||||
|
The small size of 8½ does not reflect reduced functionality:
|
||||||
|
8½ provides service roughly equivalent to the X window system.
|
||||||
|
8½'s clients may of course be as complex as they choose,
|
||||||
|
although the tendency to mimic 8½'s design
|
||||||
|
and the clean programming interface means they
|
||||||
|
are not nearly as bloated as X applications.
|
||||||
|
.SH
|
||||||
|
User's Model
|
||||||
|
.PP
|
||||||
|
8½ turns the single screen, mouse, and keyboard of the terminal
|
||||||
|
(in Plan 9 terminology) or workstation (in commercial terminology) into an array
|
||||||
|
of independent virtual terminals that may be textual terminals supporting a shell and
|
||||||
|
the usual suite of tools
|
||||||
|
or graphical applications using the full power of the bitmap screen and mouse.
|
||||||
|
Text is represented in UTF, an encoding of the Unicode Standard [Pike93].
|
||||||
|
The entire programming interface is provided through
|
||||||
|
reading and writing files in
|
||||||
|
.CW /dev .
|
||||||
|
.PP
|
||||||
|
Primarily for reasons of history and familiarity,
|
||||||
|
the general model and appearance of 8½ are similar to those of
|
||||||
|
.CW mux
|
||||||
|
[Pike88].
|
||||||
|
The right button has a short menu for controlling window creation, destruction,
|
||||||
|
and placement.
|
||||||
|
When a window is created, it runs the default shell,
|
||||||
|
.CW rc
|
||||||
|
[Duff90], with standard input
|
||||||
|
and output directed to the window and accessible through the file
|
||||||
|
.CW /dev/cons
|
||||||
|
(`console'),
|
||||||
|
analogous to the
|
||||||
|
.CW /dev/tty
|
||||||
|
of UNIX.
|
||||||
|
The name change represents a break with the past: Plan 9 does not provide a
|
||||||
|
Teletype-style model of terminals. 8½ provides the only way
|
||||||
|
most users ever access Plan 9.
|
||||||
|
.PP
|
||||||
|
Graphical applications,
|
||||||
|
like ordinary programs,
|
||||||
|
may be run by typing their names
|
||||||
|
to the shell running in a window.
|
||||||
|
This runs the application in the same window;
|
||||||
|
to run the application in a new window one may use an external program,
|
||||||
|
.CW window ,
|
||||||
|
described below.
|
||||||
|
For graphical applications, the virtual terminal model
|
||||||
|
is extended somewhat to allow programs to perform graphical operations,
|
||||||
|
access the
|
||||||
|
mouse, and perform related functions by reading and writing files with
|
||||||
|
suggestive names such as
|
||||||
|
.CW /dev/mouse
|
||||||
|
and
|
||||||
|
.CW /dev/window
|
||||||
|
multiplexed per-window
|
||||||
|
much like
|
||||||
|
.CW /dev/cons .
|
||||||
|
The implementation and semantics of these files,
|
||||||
|
described below, is central to the structure of 8½.
|
||||||
|
.PP
|
||||||
|
The default program that runs in a window is familiar to users of Blit terminals [Pike83].
|
||||||
|
It is very similar to that of
|
||||||
|
.CW mux
|
||||||
|
[Pike88], providing mouse-based editing of input and output text,
|
||||||
|
the ability to scroll back to see earlier output, and so on.
|
||||||
|
It also has a new feature, toggled by typing ESC,
|
||||||
|
that enables the user to control when
|
||||||
|
typed characters may be read by the shell or application,
|
||||||
|
instead of (for example) after each newline.
|
||||||
|
This feature makes the window program directly useful for many text-editing
|
||||||
|
tasks such as composing mail messages before sending them.
|
||||||
|
.SH
|
||||||
|
Plan 9 and 8½
|
||||||
|
.PP
|
||||||
|
Plan 9 is a distributed system that provides support for UNIX-like applications
|
||||||
|
in an environment built from distinct CPU servers, file servers, and terminals
|
||||||
|
connected by a variety of networks [Pike90].
|
||||||
|
The terminals are comparable to modest workstations that, once connected to a file
|
||||||
|
server over a medium-bandwidth network such as Ethernet, are self-sufficient computers
|
||||||
|
running a full operating system.
|
||||||
|
Unlike workstations, however, their role is just to
|
||||||
|
provide an affordable multiplexed user interface to the rest of the system:
|
||||||
|
they run the window system and support simple interactive
|
||||||
|
tasks such as text editing.
|
||||||
|
Thus they lie somewhere between workstations and X terminals in design,
|
||||||
|
cost, performance, and function.
|
||||||
|
(The terminals can be used
|
||||||
|
for general computing, but in practice Plan 9 users do their
|
||||||
|
computing on the CPU servers.)
|
||||||
|
The Plan 9 terminal software, including 8½,
|
||||||
|
was developed on a 68020-based
|
||||||
|
machine called a Gnot
|
||||||
|
and has been ported to
|
||||||
|
the NeXTstation,
|
||||||
|
the MIPS Magnum 3000,
|
||||||
|
SGI Indigos,
|
||||||
|
and Sun SPARCstations\(emall small workstations that we use as terminals\(emas
|
||||||
|
well as PCs.
|
||||||
|
.PP
|
||||||
|
Heavy computations such as compilation, text processing,
|
||||||
|
or scientific calculation are done on the CPU servers, which are connected
|
||||||
|
to the file servers by high-bandwidth networks.
|
||||||
|
For interactive work,
|
||||||
|
these computations can access the terminal that instantiated them.
|
||||||
|
The terminal and CPU server being used by a particular user are connected to the
|
||||||
|
same file server, although over different networks; Plan 9 provides a view of the
|
||||||
|
file server that is independent of location in the network.
|
||||||
|
.PP
|
||||||
|
The components of Plan 9 are connected by a common protocol based on the sharing of files.
|
||||||
|
All resources in the network are implemented as file servers; programs that wish to
|
||||||
|
access them connect to them over the network and communicate using ordinary file
|
||||||
|
operations.
|
||||||
|
An unusual aspect of Plan 9 is that the
|
||||||
|
.I
|
||||||
|
name space
|
||||||
|
.R
|
||||||
|
of a process, the set of files that can be accessed by name
|
||||||
|
(for example by an
|
||||||
|
.CW open
|
||||||
|
system call) is not global to all processes on a machine; distinct processes
|
||||||
|
may have distinct name spaces. The system provides methods by which processes
|
||||||
|
may change their name spaces, such as the ability to
|
||||||
|
.I mount
|
||||||
|
a service upon an existing directory, making the files of the service
|
||||||
|
visible in the directory.
|
||||||
|
(This is a different operation from its
|
||||||
|
UNIX
|
||||||
|
namesake.)
|
||||||
|
Multiple services may be mounted upon the same directory,
|
||||||
|
allowing the files from multiple services to be accessed in the same directory.
|
||||||
|
Options to the
|
||||||
|
.CW mount
|
||||||
|
system call control the order of searching for files in such a
|
||||||
|
.I
|
||||||
|
union directory.
|
||||||
|
.R
|
||||||
|
.PP
|
||||||
|
The most obvious example of a network resource is a file server, where permanent
|
||||||
|
files reside. There are a number of unusual services, however, whose design in
|
||||||
|
a different environment would likely not be file-based. Many are described
|
||||||
|
elsewhere [Pike92]; some examples are the representation
|
||||||
|
of processes for debugging,
|
||||||
|
much like Killian's process files for the 8th edition [Kill84],
|
||||||
|
and the implementation of the name/value pairs of the
|
||||||
|
UNIX
|
||||||
|
.CW exec
|
||||||
|
environment as files.
|
||||||
|
User processes may also implement a file service and make it available to clients
|
||||||
|
in the network, much like the `mounted streams' in the 9th Edition
|
||||||
|
[Pres90].
|
||||||
|
A typical example is a program that interprets an externally-defined file system
|
||||||
|
such as that on a CD-ROM or a standard
|
||||||
|
UNIX
|
||||||
|
system and makes the contents available to Plan 9 programs.
|
||||||
|
This design is used by all distributed applications in Plan 9, including 8½.
|
||||||
|
.PP
|
||||||
|
8½ serves a set of files in the conventional directory
|
||||||
|
.CW /dev
|
||||||
|
with names like
|
||||||
|
.CW cons ,
|
||||||
|
.CW mouse ,
|
||||||
|
and
|
||||||
|
.CW screen .
|
||||||
|
Clients of 8½ communicate with the window system by reading and writing
|
||||||
|
these files.
|
||||||
|
For example, a client program, such as a shell,
|
||||||
|
can print text by writing its standard output, which is automatically
|
||||||
|
connected to
|
||||||
|
.CW /dev/cons ,
|
||||||
|
or it may open and write that file explicitly.
|
||||||
|
Unlike files served by a traditional file server, however, the instance of
|
||||||
|
.CW /dev/cons
|
||||||
|
served in each window by 8½ is a distinct file;
|
||||||
|
the per-process name spaces of Plan 9 allow 8½ to provide a unique
|
||||||
|
.CW /dev/cons
|
||||||
|
to each client.
|
||||||
|
This mechanism is best illustrated by the creation of a new 8½ client.
|
||||||
|
.PP
|
||||||
|
When 8½ starts, it creates a full-duplex pipe to be the communication
|
||||||
|
medium for the messages that implement the file service it will provide.
|
||||||
|
One end will be shared by all the clients; the other end is held by
|
||||||
|
8½ to accept requests for I/O.
|
||||||
|
When a user makes a new window using the mouse,
|
||||||
|
8½ allocates the window data structures and forks a child process.
|
||||||
|
The child's name space,
|
||||||
|
initially shared with the parent,
|
||||||
|
is then duplicated
|
||||||
|
so that changes the child makes to its name space will not affect the parent.
|
||||||
|
The child then attaches its end of the communication pipe,
|
||||||
|
.CW cfd ,
|
||||||
|
to the directory
|
||||||
|
.CW /dev
|
||||||
|
by doing a
|
||||||
|
.CW mount
|
||||||
|
system call:
|
||||||
|
.P1
|
||||||
|
mount(cfd, "/dev", MBEFORE, buf)
|
||||||
|
.P2
|
||||||
|
This call attaches the service associated with the file descriptor
|
||||||
|
.CW cfd
|
||||||
|
\(em the client end of the pipe \(em to the beginning of
|
||||||
|
.CW /dev
|
||||||
|
so that the files in the new service take priority over existing files
|
||||||
|
in the directory.
|
||||||
|
This makes the new files
|
||||||
|
.CW cons ,
|
||||||
|
.CW mouse ,
|
||||||
|
and so on,
|
||||||
|
available in
|
||||||
|
.CW /dev
|
||||||
|
in a way that hides any files with the same names already in place.
|
||||||
|
The argument
|
||||||
|
.CW buf
|
||||||
|
is a character string (null in this case),
|
||||||
|
described below.
|
||||||
|
.PP
|
||||||
|
The client process then closes file descriptors 0, 1, and 2 and opens
|
||||||
|
.CW /dev/cons
|
||||||
|
repeatedly to connect the standard
|
||||||
|
input, output, and error files to the window's
|
||||||
|
.CW /dev/cons .
|
||||||
|
It then does an
|
||||||
|
.CW exec
|
||||||
|
system call to begin executing the shell in the window.
|
||||||
|
This entire sequence, complete with error handling, is 33 lines of C.
|
||||||
|
.PP
|
||||||
|
The view of these events from 8½'s end of the pipe is a sequence
|
||||||
|
of file protocol messages from the new client generated by the
|
||||||
|
intervening operating
|
||||||
|
system in response to the
|
||||||
|
.CW mount
|
||||||
|
and
|
||||||
|
.CW open
|
||||||
|
system calls executed by the client.
|
||||||
|
The message generated by the
|
||||||
|
.CW mount
|
||||||
|
informs 8½ that a new client has attached to the file service it provides;
|
||||||
|
8½'s response is a unique identifier kept by the operating system and
|
||||||
|
passed in all messages generated by I/O on the files derived from that
|
||||||
|
.CW mount .
|
||||||
|
This identifier is used by 8½ to distinguish the various clients so
|
||||||
|
each sees a unique
|
||||||
|
.CW /dev/cons ;
|
||||||
|
most servers do not need to make this distinction.
|
||||||
|
.PP
|
||||||
|
A process unrelated to 8½ may create windows by a variant of this mechanism.
|
||||||
|
When 8½ begins, it uses a Plan 9 service to `post' the client end of the
|
||||||
|
communication pipe in a public place.
|
||||||
|
A process may open that pipe and
|
||||||
|
.CW mount
|
||||||
|
it to attach to the window system,
|
||||||
|
much in the way an X client may connect to a
|
||||||
|
UNIX
|
||||||
|
domain socket to the server bound to the file system.
|
||||||
|
The final argument to
|
||||||
|
.CW mount
|
||||||
|
is passed through uninterpreted by the operating
|
||||||
|
system.
|
||||||
|
It provides a way for the client and server to
|
||||||
|
exchange information at the time of the
|
||||||
|
.CW mount .
|
||||||
|
8½ interprets it as the dimensions of the window to be
|
||||||
|
created for the new client. (In the case above, the window has been
|
||||||
|
created by the time the mount occurs, and
|
||||||
|
.CW buf
|
||||||
|
carries no information.)
|
||||||
|
When the
|
||||||
|
.CW mount
|
||||||
|
returns, the process can open the files of the new window and begin I/O to
|
||||||
|
use it.
|
||||||
|
.PP
|
||||||
|
Because 8½'s interface is based on files,
|
||||||
|
standard system utilities can be used to control its services.
|
||||||
|
For example,
|
||||||
|
its method of creating windows externally is packaged in a
|
||||||
|
16-line shell script, called
|
||||||
|
.CW window ,
|
||||||
|
the core of which is just a
|
||||||
|
.CW mount
|
||||||
|
operation that prefixes 8½'s directory to
|
||||||
|
.CW /dev
|
||||||
|
and runs a command passed on the argument line:
|
||||||
|
.P1
|
||||||
|
mount -b $'8½serv' /dev
|
||||||
|
$* < /dev/cons > /dev/cons >[2] /dev/cons &
|
||||||
|
.P2
|
||||||
|
The
|
||||||
|
.CW window
|
||||||
|
program is typically employed by users to create their
|
||||||
|
initial working environment when they boot the system, although
|
||||||
|
it has more general possibilities.
|
||||||
|
.PP
|
||||||
|
Other basic features of the system fall out naturally from the
|
||||||
|
file-based model.
|
||||||
|
When the user deletes a window, 8½ sends the equivalent of a
|
||||||
|
UNIX
|
||||||
|
signal to the process group \(em the clients \(em in the window,
|
||||||
|
removes the window from the screen, and poisons the incoming connections
|
||||||
|
to the files that drive it. If a client ignores the signal and
|
||||||
|
continues to write to the window, it will get I/O errors.
|
||||||
|
If, on the other hand, all the processes in a window exit spontaneously,
|
||||||
|
they will automatically close all connections to the window.
|
||||||
|
8½ counts references to the window's files; when none are left,
|
||||||
|
it shuts down the window and removes it from the screen.
|
||||||
|
As a different example, when the user hits the DEL key to generate an
|
||||||
|
interrupt,
|
||||||
|
8½ writes a message to a special file, provided by Plan 9's
|
||||||
|
process control interface, that interrupts all the processes
|
||||||
|
in the window.
|
||||||
|
In all these examples, the implementation works seamlessly
|
||||||
|
across a network.
|
||||||
|
.PP
|
||||||
|
There are two valuable side effects of implementing
|
||||||
|
a window system by multiplexing
|
||||||
|
.CW /dev/cons
|
||||||
|
and other such files.
|
||||||
|
First, the problem of giving a meaningful
|
||||||
|
interpretation to the file
|
||||||
|
.CW /dev/cons
|
||||||
|
.CW /dev/tty ) (
|
||||||
|
in each window is solved automatically.
|
||||||
|
To provide
|
||||||
|
.CW /dev/cons
|
||||||
|
is the fundamental job of the window system, rather than just an awkward burden;
|
||||||
|
other systems must often make special and otherwise irrelevant arrangements for
|
||||||
|
.CW /dev/tty
|
||||||
|
to behave as expected in a window.
|
||||||
|
Second, any program that can access the server, including a
|
||||||
|
process on a remote machine, can access the files using standard
|
||||||
|
read and write system calls to communicate with the window system,
|
||||||
|
and standard open and close calls to connect to it.
|
||||||
|
Again, no special arrangements need to be made for remote processes to
|
||||||
|
use all the graphics facilities of 8½.
|
||||||
|
.SH
|
||||||
|
Graphical input
|
||||||
|
.PP
|
||||||
|
Of course 8½ offers more than ASCII I/O to its clients.
|
||||||
|
The state of the mouse may be discovered by reading the file
|
||||||
|
.CW /dev/mouse ,
|
||||||
|
which returns a ten-byte message encoding the state
|
||||||
|
of the buttons and the position of the cursor.
|
||||||
|
If the mouse has not moved since the last read of
|
||||||
|
.CW /dev/mouse ,
|
||||||
|
or if the window associated with the instance of
|
||||||
|
.CW /dev/mouse
|
||||||
|
is not the `input focus', the read blocks.
|
||||||
|
.PP
|
||||||
|
The format of the message is:
|
||||||
|
.DS
|
||||||
|
.CW 'm'
|
||||||
|
1 byte of button state
|
||||||
|
4 bytes of x, low byte first
|
||||||
|
4 bytes of y, low byte first
|
||||||
|
.DE
|
||||||
|
As in all shared data structures in Plan 9,
|
||||||
|
the order of every byte in the message is defined
|
||||||
|
so all clients can execute the same code to unpack the message
|
||||||
|
into a local data structure.
|
||||||
|
.PP
|
||||||
|
For keyboard input, clients can read
|
||||||
|
.CW /dev/cons
|
||||||
|
or, if they need character-at-a-time input,
|
||||||
|
.CW /dev/rcons
|
||||||
|
(`raw console').
|
||||||
|
There is no explicit event mechanism to help clients that need to read
|
||||||
|
from multiple sources.
|
||||||
|
Instead, a small (365 line) external
|
||||||
|
support library can be used.
|
||||||
|
It attaches a process
|
||||||
|
to the various blocking input sources \(em mouse, keyboard, and perhaps
|
||||||
|
a third user-provided file descriptor \(em
|
||||||
|
and funnels their input into a single pipe from which may be read
|
||||||
|
the various types of
|
||||||
|
events in the traditional style.
|
||||||
|
This package is a compromise. As discussed in a previous paper
|
||||||
|
[Pike89] I prefer
|
||||||
|
to free applications from event-based programming. Unfortunately, though, I see
|
||||||
|
no easy way to achieve this in single-threaded C programs, and am unwilling
|
||||||
|
to require all programmers to master concurrent programming.
|
||||||
|
It should be noted, though, that even this compromise results in a small
|
||||||
|
and easily understood interface. An example program that uses it is
|
||||||
|
given near the end of the paper.
|
||||||
|
.SH
|
||||||
|
Graphical output
|
||||||
|
.PP
|
||||||
|
The file
|
||||||
|
.CW /dev/screen
|
||||||
|
may be read by any client to recover the contents of the entire screen,
|
||||||
|
such as for printing (see Figure 1).
|
||||||
|
Similarly,
|
||||||
|
.CW /dev/window
|
||||||
|
holds the contents of the current window.
|
||||||
|
These are read-only files.
|
||||||
|
.PP
|
||||||
|
To perform graphics operations in their windows, client programs access
|
||||||
|
.CW /dev/bitblt .
|
||||||
|
It implements a protocol that encodes bitmap graphics operations.
|
||||||
|
Most of the messages in the protocol (there are 23 messages in all, about
|
||||||
|
half to manage the multi-level fonts necessary for efficient handling
|
||||||
|
of Unicode characters)
|
||||||
|
are transmissions (via a write)
|
||||||
|
from the client to the window system to perform a graphical
|
||||||
|
operation such as a
|
||||||
|
.CW bitblt
|
||||||
|
[PLR85] or character-drawing operation; a few include return information
|
||||||
|
(recovered via a read) to the client.
|
||||||
|
As with
|
||||||
|
.CW /dev/mouse ,
|
||||||
|
the
|
||||||
|
.CW /dev/bitblt
|
||||||
|
protocol is in a defined byte order.
|
||||||
|
Here, for example, is the layout of the
|
||||||
|
.CW bitblt
|
||||||
|
message:
|
||||||
|
.DS
|
||||||
|
.CW 'b'
|
||||||
|
2 bytes of destination id
|
||||||
|
2x4 bytes of destination point
|
||||||
|
2 bytes of source id
|
||||||
|
4x4 bytes of source rectangle
|
||||||
|
2 bytes of boolean function code
|
||||||
|
.DE
|
||||||
|
.KF
|
||||||
|
.ie h .html - <center><a href="8½.fig1.png"><img src="8½.fig1s.png"></a></center>
|
||||||
|
.el .BP fig1.ps 4.16 5.6 r 0 0
|
||||||
|
.EP
|
||||||
|
.IP
|
||||||
|
Figure 1.
|
||||||
|
A representative 8½ screen, running on a NeXTstation under Plan 9
|
||||||
|
(with no NeXT software). In the upper right, a program announces the
|
||||||
|
arrival of mail. In the top and left are a broswer for astronomical
|
||||||
|
databases and an image of a galaxy produced by the browser.
|
||||||
|
In the lower left there is a screen editor,
|
||||||
|
.CW sam
|
||||||
|
[Pike87],
|
||||||
|
editing Japanese text encoded in UTF,
|
||||||
|
and in the lower right an 8½ running recursively and, inside that instantiation,
|
||||||
|
a previewer for
|
||||||
|
.CW troff
|
||||||
|
output.
|
||||||
|
Underneath the faces is a small window running the command that
|
||||||
|
prints the screen by passing
|
||||||
|
.CW /dev/screen
|
||||||
|
to the bitmap printing utility.
|
||||||
|
.sp
|
||||||
|
.KE
|
||||||
|
.PP
|
||||||
|
The message is trivially constructed from the
|
||||||
|
.CW bitblt
|
||||||
|
subroutine in the library, defined as
|
||||||
|
.P1
|
||||||
|
void bitblt(Bitmap *dst, Point dp,
|
||||||
|
Bitmap *src, Rectangle sr, Fcode c).
|
||||||
|
.P2
|
||||||
|
.PP
|
||||||
|
The `id'
|
||||||
|
fields in the message indicate another property of 8½:
|
||||||
|
the clients do not store the actual data for any of their bitmaps locally.
|
||||||
|
Instead, the protocol provides a message to allocate a bitmap, to be
|
||||||
|
stored in the server, and returns to the client an integer identifier,
|
||||||
|
much like a
|
||||||
|
UNIX
|
||||||
|
file descriptor, to be used in operations on that bitmap.
|
||||||
|
Bitmap number 0 is conventionally the client's window,
|
||||||
|
analogous to standard input for file I/O.
|
||||||
|
In fact, no bitmap graphics operations are executed in the client at all;
|
||||||
|
they are all performed on its behalf by the server.
|
||||||
|
Again, using the standard remote file operations in Plan 9,
|
||||||
|
this permits remote machines having no graphics capability, such
|
||||||
|
as the CPU server,
|
||||||
|
to run graphics applications.
|
||||||
|
Analogous features of the original Andrew window system [Gos86]
|
||||||
|
and of X [Sche86] require more complex mechanisms.
|
||||||
|
.PP
|
||||||
|
Nor does 8½ itself operate directly on bitmaps.
|
||||||
|
Instead, it calls another server to do its graphics operations for it,
|
||||||
|
using an identical protocol.
|
||||||
|
The operating system for the Plan 9 terminals contains an internal
|
||||||
|
server that implements that protocol, exactly as does 8½, but for a single
|
||||||
|
client. That server stores the actual bytes for the bitmaps
|
||||||
|
and implements the fundamental bitmap graphics operations.
|
||||||
|
Thus the environment in which 8½ runs
|
||||||
|
has exactly the structure it provides for its clients;
|
||||||
|
8½ reproduces the environment for its clients,
|
||||||
|
multiplexing the interface to keep the clients separate.
|
||||||
|
.PP
|
||||||
|
This idea of multiplexing by simulation is applicable to more
|
||||||
|
than window systems, of course, and has some side effects.
|
||||||
|
Since 8½ simulates its own environment for its clients, it may run
|
||||||
|
in one of its own windows (see Figure 1).
|
||||||
|
A useful and common application of this
|
||||||
|
technique is to connect a window to a remote machine, such as a CPU
|
||||||
|
server, and run the window system there so that each subwindow is automatically
|
||||||
|
on the remote machine.
|
||||||
|
It is also a handy way to debug a new version of the window system
|
||||||
|
or to create an environment with, for example, a different default font.
|
||||||
|
.SH
|
||||||
|
Implementation
|
||||||
|
.PP
|
||||||
|
To provide graphics to its clients, 8½ mostly just multiplexes and passes
|
||||||
|
through to its own server the clients' requests, occasionally rearranging
|
||||||
|
the messages to maintain the fiction that the clients have unique screens
|
||||||
|
(windows).
|
||||||
|
To manage the overlapping windows it uses the layers model,
|
||||||
|
which is handled by a separate library [Pike83a].
|
||||||
|
Thus it has little work to do and is a fairly simple program;
|
||||||
|
it is dominated by a couple of switch statements to interpret
|
||||||
|
the bitmap and file server protocols.
|
||||||
|
The built-in window program and its associated menus and text-management
|
||||||
|
support are responsible for most of the code.
|
||||||
|
.PP
|
||||||
|
The operating system's server is also compact:
|
||||||
|
the version for the 68020 processor, excluding the implementation
|
||||||
|
of a half dozen bitmap graphics operations, is 2295 lines of C
|
||||||
|
(again, about half dealing with fonts);
|
||||||
|
the graphics operations are another 2214 lines.
|
||||||
|
.PP
|
||||||
|
8½ is structured as a set of communicating coroutines,
|
||||||
|
much as discussed in a 1989 paper [Pike89].
|
||||||
|
One coroutine manages the mouse, another the keyboard, and another
|
||||||
|
is instantiated to manage the state of each window and associated client.
|
||||||
|
When no coroutine wishes to run, 8½ reads the next file I/O request from
|
||||||
|
its clients, which arrive serially on the full-duplex communication pipe.
|
||||||
|
Thus 8½ is entirely synchronous.
|
||||||
|
.PP
|
||||||
|
The program source is small and compiles in about 10 seconds
|
||||||
|
in our Plan 9 environment. There are ten source files and
|
||||||
|
one
|
||||||
|
.CW makefile
|
||||||
|
totaling 5100 lines.
|
||||||
|
This includes the source for the window management process,
|
||||||
|
the cut-and-paste terminal program,
|
||||||
|
the window/file server itself,
|
||||||
|
and a small coroutine library
|
||||||
|
.CW proc.c ). (
|
||||||
|
It does not include the layer library
|
||||||
|
(another 1031 lines)
|
||||||
|
or the library to handle the cutting and pasting of text
|
||||||
|
displayed in a window (960 lines),
|
||||||
|
or the general graphics support library that manages all the
|
||||||
|
non-drawing aspects of graphics \(em arithmetic on points and rectangles,
|
||||||
|
memory management, error handling, clipping, \(em plus fonts,
|
||||||
|
events, and non-primitive drawing operations such as circles and ellipses
|
||||||
|
(a final 3051 lines).
|
||||||
|
Not all the pieces of these libraries are used by 8½ itself;
|
||||||
|
a large part of the graphics library in particular is used only by clients.
|
||||||
|
Thus it is somewhat unfair to 8½ just to sum these numbers, including
|
||||||
|
the 4509 lines of support in the kernel, and arrive
|
||||||
|
at a total implementation size of 14651 lines of source to implement
|
||||||
|
all of 8½ from the lowest levels to the highest.
|
||||||
|
But that number gives a fair measure of the complexity of the overall system.
|
||||||
|
.PP
|
||||||
|
The implementation is also efficient.
|
||||||
|
8½'s performance is competitive to X windows'.
|
||||||
|
Compared using Dunwoody's and Linton's
|
||||||
|
.CW gbench
|
||||||
|
benchmarks on the 68020,
|
||||||
|
distributed with the ``X Test Suite'',
|
||||||
|
circles and arcs are drawn about half as fast in 8½ as in
|
||||||
|
X11 release 4 compiled with
|
||||||
|
.CW gcc
|
||||||
|
for equivalent hardware,
|
||||||
|
probably because they are currently implemented in a user library
|
||||||
|
by calls to the
|
||||||
|
.CW point
|
||||||
|
primitive.
|
||||||
|
Line drawing speed is about equal between the two systems.
|
||||||
|
Unicode text is drawn about the same speed by 8½ as ASCII text by
|
||||||
|
X, and
|
||||||
|
the
|
||||||
|
.CW bitblt
|
||||||
|
test is runs four times faster for 8½.
|
||||||
|
These numbers vary enough to caution against drawing sweeping
|
||||||
|
conclusions, but they
|
||||||
|
suggest that 8½'s architecture does not penalize its performance.
|
||||||
|
Finally, 8½ boots in under a second and creates a new window
|
||||||
|
apparently instantaneously.
|
||||||
|
.SH
|
||||||
|
An example
|
||||||
|
.PP
|
||||||
|
Here is a complete program that runs under 8½.
|
||||||
|
It prints the string
|
||||||
|
.CW \&"hello
|
||||||
|
.CW world"
|
||||||
|
wherever the left mouse button is depressed, and exits when the
|
||||||
|
right mouse button is depressed.
|
||||||
|
It also prints the string in the center of its window, and maintains
|
||||||
|
that string when the window is resized.
|
||||||
|
.P1
|
||||||
|
#include <u.h>
|
||||||
|
#include <libc.h>
|
||||||
|
#include <libg.h>
|
||||||
|
|
||||||
|
void
|
||||||
|
ereshaped(Rectangle r)
|
||||||
|
{
|
||||||
|
Point p;
|
||||||
|
|
||||||
|
screen.r = r;
|
||||||
|
bitblt(&screen, screen.r.min, &screen, r, Zero); /* clear */
|
||||||
|
p.x = screen.r.min.x + Dx(screen.r)/2;
|
||||||
|
p.y = screen.r.min.y + Dy(screen.r)/2;
|
||||||
|
p = sub(p, div(strsize(font, "hello world"), 2));
|
||||||
|
string(&screen, p, font, "hello world", S);
|
||||||
|
}
|
||||||
|
|
||||||
|
main(void)
|
||||||
|
{
|
||||||
|
Mouse m;
|
||||||
|
|
||||||
|
binit(0, 0, 0); /* initialize graphics library */
|
||||||
|
einit(Emouse); /* initialize event library */
|
||||||
|
ereshaped(screen.r);
|
||||||
|
for(;;){
|
||||||
|
m = emouse();
|
||||||
|
if(m.buttons & RIGHTB)
|
||||||
|
break;
|
||||||
|
if(m.buttons & LEFTB){
|
||||||
|
string(&screen, m.xy, font, "hello world", S);
|
||||||
|
/* wait for release of button */
|
||||||
|
do; while(emouse().buttons & LEFTB);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
.P2
|
||||||
|
The complete loaded binary is a little over 26K bytes on a 68020.
|
||||||
|
This program should be compared to the similar ones in the excellent paper
|
||||||
|
by Rosenthal [Rose88].
|
||||||
|
(The current program does more: it also employs the mouse.)
|
||||||
|
The clumsiest part is
|
||||||
|
.CW ereshaped ,
|
||||||
|
a function with a known name that is called from the event library
|
||||||
|
whenever the window is
|
||||||
|
reshaped or moved, as is discovered inelegantly but adequately
|
||||||
|
by a special case of a mouse message.
|
||||||
|
(Simple so-called expose events are not events
|
||||||
|
at all in 8½; the layer library takes care of them transparently.)
|
||||||
|
The lesson of this program, with deference to Rosenthal, is that if
|
||||||
|
the window system is cleanly designed a toolkit should be unnecessary
|
||||||
|
for simple tasks.
|
||||||
|
.SH
|
||||||
|
Status
|
||||||
|
.PP
|
||||||
|
As of 1992, 8½ is in regular daily use by almost all the 60 people in our
|
||||||
|
research center. Some of those people use it to access Plan 9 itself; others
|
||||||
|
use it as a front end to remote
|
||||||
|
UNIX
|
||||||
|
systems, much as one would use an X terminal.
|
||||||
|
.PP
|
||||||
|
Some things about 8½ may change.
|
||||||
|
It would be nice if its capabilities were more easily accessible
|
||||||
|
from the shell.
|
||||||
|
A companion to this paper [Pike91] proposes one way to do this,
|
||||||
|
but that does not include any graphics functionality.
|
||||||
|
Perhaps a textual version of the
|
||||||
|
.CW /dev/bitblt
|
||||||
|
file is a way to proceed; that would allow, for example,
|
||||||
|
.CW awk
|
||||||
|
programs to draw graphs directly.
|
||||||
|
.PP
|
||||||
|
Can this style of window system be built on other operating systems?
|
||||||
|
A major part of the design of 8½ depends on its structure as a file server.
|
||||||
|
In principle this could be done for any system that supports user processes
|
||||||
|
that serve files, such as any system running NFS or AFS [Sun89, Kaza87].
|
||||||
|
One requirement, however, is 8½'s need
|
||||||
|
to respond to its clients' requests out of order:
|
||||||
|
if one client reads
|
||||||
|
.CW /dev/cons
|
||||||
|
in a window with no characters to be read,
|
||||||
|
other clients should be able to perform I/O in their windows, or even
|
||||||
|
the same window.
|
||||||
|
Another constraint is that the 8½ files are like devices,
|
||||||
|
and must not be cached by the client.
|
||||||
|
NFS cannot honor these requirements; AFS may be able to.
|
||||||
|
Of course, other interprocess communication mechanisms such as sockets
|
||||||
|
could be used as a basis for a window system. One may even argue that
|
||||||
|
X's model fits into this overall scheme. It may prove easy and worthwhile
|
||||||
|
to write a small 8½-like system for commercial
|
||||||
|
UNIX
|
||||||
|
systems to demonstrate that its merits can be won in systems other than
|
||||||
|
Plan 9.
|
||||||
|
.SH
|
||||||
|
Conclusion
|
||||||
|
.PP
|
||||||
|
In conclusion, 8½ uses an unusual architecture in
|
||||||
|
concert with the file-oriented interprocess communication of Plan 9
|
||||||
|
to provide network-based interactive graphics to client programs.
|
||||||
|
It demonstrates that even production-quality window systems are not
|
||||||
|
inherently large or complicated
|
||||||
|
and may be simple to use and to program.
|
||||||
|
.SH
|
||||||
|
Acknowledgements
|
||||||
|
.PP
|
||||||
|
Helpful comments on early drafts of this paper were made by
|
||||||
|
Doug Blewett,
|
||||||
|
Stu Feldman,
|
||||||
|
Chris Fraser,
|
||||||
|
Brian Kernighan,
|
||||||
|
Dennis Ritchie,
|
||||||
|
and Phil Winterbottom.
|
||||||
|
8½'s support for color was added by Howard Trickey.
|
||||||
|
Many of the ideas leading to 8½ were tried out in earlier, sometimes less
|
||||||
|
successful, programs. I would like to thank those users who suffered
|
||||||
|
through some of my previous 7½ window systems.
|
||||||
|
.SH
|
||||||
|
References
|
||||||
|
.LP
|
||||||
|
[Duff90] Tom Duff, ``Rc - A Shell for Plan 9 and UNIX systems'', Proc. of the Summer 1990 UKUUG Conf., London, July, 1990, pp. 21-33, reprinted, in a different form, in this volume.
|
||||||
|
.LP
|
||||||
|
[Far89] Far too many people, XTERM(1), Massachusetts Institute of Technology, 1989.
|
||||||
|
.LP
|
||||||
|
[Gos86] James Gosling and David Rosenthal,
|
||||||
|
``A window manager for bitmapped displays and UNIX'', in Methodology of Window Management, edited by F.R.A. Hopgood et al., Springer, 1986.
|
||||||
|
.LP
|
||||||
|
[Kaza87] Mike Kazar, ``Synchronization and Caching issues in the Andrew File System'', Tech. Rept. CMU-ITC-058, Information Technology Center, Carnegie Mellon University, June, 1987.
|
||||||
|
.LP
|
||||||
|
[Kill84] Tom Killian, ``Processes as Files'', USENIX Summer Conf. Proc., Salt Lake City June, 1984.
|
||||||
|
.LP
|
||||||
|
[Pike83] Rob Pike, ``The Blit: A Multiplexed Graphics Terminal'', Bell Labs Tech. J., V63, #8, part 2, pp. 1607-1631.
|
||||||
|
.LP
|
||||||
|
[Pike83a] Rob Pike, ``Graphics in Overlapping Bitmap Layers'', Trans. on Graph., Vol 2, #2, 135-160, reprinted in Proc. SIGGRAPH '83, pp. 331-356.
|
||||||
|
.LP
|
||||||
|
[Pike87] Rob Pike, ``The Text Editor \f(CWsam\fP'', Softw. - Prac. and Exp., Nov 1987, Vol 17 #11, pp. 813-845, reprinted in this volume.
|
||||||
|
.LP
|
||||||
|
[Pike88] Rob Pike, ``Window Systems Should Be Transparent'', Comp. Sys., Summer 1988, Vol 1 #3, pp. 279-296.
|
||||||
|
.LP
|
||||||
|
[Pike89] Rob Pike, ``A Concurrent Window System'', Comp. Sys., Spring 1989, Vol 2 #2, pp. 133-153.
|
||||||
|
.LP
|
||||||
|
[Pike91] Rob Pike, ``A Minimalist Global User Interface'', USENIX Summer Conf. Proc., Nashville, June, 1991.
|
||||||
|
.LP
|
||||||
|
[Pike92] Rob Pike, Dave Presotto, Ken Thompson, Howard Trickey, and Phil Winterbottom,
|
||||||
|
Operating Systems Review
|
||||||
|
Vol 27, #2, Apr 1993, pp. 72-76
|
||||||
|
(reprinted from Proceedings of the 5th ACM SIGOPS European Workshop, Mont Saint-Michel, 1992, Paper nº 34, and reprinted in this volume).
|
||||||
|
.LP
|
||||||
|
[Pike94] Rob Pike and Ken Thompson, ``Hello World or Καλημέρα κόσμε or \f(Jpこんにちは 世界\fP'', USENIX Winter Conf. Proc., San Diego, Jan, 1993, reprinted in this volume.
|
||||||
|
.LP
|
||||||
|
[PLR85] Rob Pike, Bart Locanthi and John Reiser, ``Hardware/Software Tradeoffs for Bitmap Graphics on the Blit'', Softw. - Prac. and Exp., Feb 1985, Vol 15 #2, pp. 131-152.
|
||||||
|
.LP
|
||||||
|
[Pres90] David L. Presotto and Dennis M. Ritchie, ``Interprocess Communication in the Ninth Edition Unix System'', Softw. - Prac. and Exp., June 1990, Vol 20 #S1, pp. S1/3-S1/17.
|
||||||
|
.LP
|
||||||
|
[Rose88] David Rosenthal, ``A Simple X11 Client Program -or- How hard can it really be to write ``Hello, World''?'', USENIX Winter Conf. Proc., Dallas, Jan, 1988, pp. 229-242.
|
||||||
|
.LP
|
||||||
|
[Sche86] Robert W. Scheifler and Jim Gettys,
|
||||||
|
``The X Window System'',
|
||||||
|
ACM Trans. on Graph., Vol 5 #2, pp. 79-109.
|
||||||
|
.LP
|
||||||
|
[Sun89] Sun Microsystems, NFS: Network file system protocol specification,
|
||||||
|
RFC 1094, Network Information Center, SRI International, March, 1989.
|
||||||
|
.br
|
16397
sys/doc/8½/8½.ps
Normal file
16397
sys/doc/8½/8½.ps
Normal file
File diff suppressed because it is too large
Load diff
7508
sys/doc/8½/fig1.ps
Normal file
7508
sys/doc/8½/fig1.ps
Normal file
File diff suppressed because it is too large
Load diff
9
sys/doc/8½/mkfile
Normal file
9
sys/doc/8½/mkfile
Normal file
|
@ -0,0 +1,9 @@
|
||||||
|
</sys/doc/fonts
|
||||||
|
|
||||||
|
8½.ps:D: 8½.ms fig1.ps
|
||||||
|
{echo $FONTS; cat 8½.ms} | tbl | troff -ms -mpictures -mnihongo | lp -dstdout >8½.ps
|
||||||
|
../cleanps 8½.ps
|
||||||
|
|
||||||
|
8½.html:D: 8½.ms
|
||||||
|
tbl 8½.ms | htmlroff -ms -mhtml >8½.html
|
||||||
|
|
2330
sys/doc/9.ms
Normal file
2330
sys/doc/9.ms
Normal file
File diff suppressed because it is too large
Load diff
17914
sys/doc/9.ps
Normal file
17914
sys/doc/9.ps
Normal file
File diff suppressed because it is too large
Load diff
2550
sys/doc/acid.ms
Normal file
2550
sys/doc/acid.ms
Normal file
File diff suppressed because it is too large
Load diff
13619
sys/doc/acid.ps
Normal file
13619
sys/doc/acid.ps
Normal file
File diff suppressed because it is too large
Load diff
1324
sys/doc/acidpaper.ms
Normal file
1324
sys/doc/acidpaper.ms
Normal file
File diff suppressed because it is too large
Load diff
10721
sys/doc/acidpaper.ps
Normal file
10721
sys/doc/acidpaper.ps
Normal file
File diff suppressed because it is too large
Load diff
2801
sys/doc/acme/acme.fig1
Normal file
2801
sys/doc/acme/acme.fig1
Normal file
File diff suppressed because it is too large
Load diff
BIN
sys/doc/acme/acme.fig1.gif
Normal file
BIN
sys/doc/acme/acme.fig1.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 24 KiB |
1139
sys/doc/acme/acme.fig2
Normal file
1139
sys/doc/acme/acme.fig2
Normal file
File diff suppressed because it is too large
Load diff
BIN
sys/doc/acme/acme.fig2.gif
Normal file
BIN
sys/doc/acme/acme.fig2.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 7.6 KiB |
1466
sys/doc/acme/acme.html
Normal file
1466
sys/doc/acme/acme.html
Normal file
File diff suppressed because it is too large
Load diff
1303
sys/doc/acme/acme.ms
Normal file
1303
sys/doc/acme/acme.ms
Normal file
File diff suppressed because it is too large
Load diff
BIN
sys/doc/acme/acme.pdf
Normal file
BIN
sys/doc/acme/acme.pdf
Normal file
Binary file not shown.
16115
sys/doc/acme/acme.ps
Normal file
16115
sys/doc/acme/acme.ps
Normal file
File diff suppressed because it is too large
Load diff
24
sys/doc/acme/bs
Normal file
24
sys/doc/acme/bs
Normal file
|
@ -0,0 +1,24 @@
|
||||||
|
.pn 267
|
||||||
|
.nr %# 267
|
||||||
|
.ds Tl "Acme: A User Interface for Programmers
|
||||||
|
.ds Au "USER INTERFACES
|
||||||
|
.de PT
|
||||||
|
.nr PN \\n(%#
|
||||||
|
.X "PT \\n(%#
|
||||||
|
.sp \\n(HMu/2u
|
||||||
|
.nr Ps \\n(PS-1
|
||||||
|
.if \\n(OL .lt \\n(OLu \" why isn't this reset???
|
||||||
|
.if \\n(BT>0 .if e .tl @\\n(PN \s\\n(Ps\\*(Au\s0@@@
|
||||||
|
.if \\n(BT>0 .if o .tl @@@\f2\\*(Tl\\f1 \\n(PN@
|
||||||
|
.if \\n(BT=0 .tl '\0''' \" put out something or spacing is curdled
|
||||||
|
.X "END PT \\n(%#
|
||||||
|
..
|
||||||
|
. \" BT - bottom title
|
||||||
|
.de BT
|
||||||
|
.X "BT \\n(%#
|
||||||
|
.sp |\\n(FMu/2u+\\n(FOu-1v
|
||||||
|
.if \\n(%#%2 \\*(%O
|
||||||
|
.if !\\n(%#%2 \\*(%E
|
||||||
|
.nr BT \\n(BT+1
|
||||||
|
.X "END BT \\n(%#
|
||||||
|
..
|
14
sys/doc/acme/mkfile
Normal file
14
sys/doc/acme/mkfile
Normal file
|
@ -0,0 +1,14 @@
|
||||||
|
</sys/doc/fonts
|
||||||
|
|
||||||
|
ALL:V:
|
||||||
|
echo 'for technical reasons, -mpm is gone and acme.ps cannot be regenerated'
|
||||||
|
|
||||||
|
acme.ps:D: acme.ms
|
||||||
|
{echo $FONTS; cat acme.ms} | troff -mpm -mpictures -mnihongo | lp -m.9 -dstdout >acme.ps
|
||||||
|
../cleanps acme.ps
|
||||||
|
|
||||||
|
acme.html:D: acme.ms
|
||||||
|
htmlroff -ms -mhtml acme.ms >acme.html
|
||||||
|
|
||||||
|
clean:V:
|
||||||
|
# nothing
|
537
sys/doc/ape.ms
Normal file
537
sys/doc/ape.ms
Normal file
|
@ -0,0 +1,537 @@
|
||||||
|
.HTML "APE — The ANSI/POSIX Environment
|
||||||
|
.de XX
|
||||||
|
.IP \ \ \ \-
|
||||||
|
..
|
||||||
|
.TL
|
||||||
|
APE \(em The ANSI/POSIX Environment
|
||||||
|
.AU
|
||||||
|
Howard Trickey
|
||||||
|
howard@plan9.bell-labs.com
|
||||||
|
.SH
|
||||||
|
Introduction
|
||||||
|
.PP
|
||||||
|
When a large or frequently-updated program must be ported
|
||||||
|
to or from Plan 9, the ANSI/POSIX environment known as APE can be useful.
|
||||||
|
APE combines the set of headers and object code libraries specified by
|
||||||
|
the ANSI C standard (ANSI X3.159-1989) with the POSIX operating system
|
||||||
|
interface standard (IEEE 1003.1-1990, ISO 9945-1), the part of POSIX
|
||||||
|
defining the basic operating system functions.
|
||||||
|
Using APE will cause slower compilation and marginally slower execution speeds,
|
||||||
|
so if the importing or exporting happens only infrequently, due consideration
|
||||||
|
should be given to using the usual Plan 9 compilation environment instead.
|
||||||
|
Another factor to consider is that the Plan 9 header organization is
|
||||||
|
much simpler to remember and use.
|
||||||
|
.PP
|
||||||
|
There are some aspects of required POSIX behavior that are impossible or
|
||||||
|
very hard to simulate in Plan 9. They are described below.
|
||||||
|
Experience has shown, however, that the simulation is adequate for the
|
||||||
|
vast majority of programs. A much more common problem is that
|
||||||
|
many programs use functions or headers not defined by POSIX.
|
||||||
|
APE has some extensions to POSIX to help in this regard.
|
||||||
|
Extensions must be explicitly enabled with an appropriate
|
||||||
|
.CW #define ,
|
||||||
|
in order that the APE environment be a good aid for testing
|
||||||
|
ANSI/POSIX compliance of programs.
|
||||||
|
.SH
|
||||||
|
Pcc
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW pcc
|
||||||
|
command acts as a front end to the Plan 9 C compilers and loaders.
|
||||||
|
It runs an ANSI C preprocessor over source files, using the APE
|
||||||
|
headers to satisfy
|
||||||
|
.CW "#include <\fIfile\fP>"
|
||||||
|
directives; then it runs a Plan 9 C compiler; finally, it may load
|
||||||
|
with APE libraries to produce an executable program.
|
||||||
|
The document
|
||||||
|
.I "How to Use the Plan 9 C Compiler"
|
||||||
|
explains how environment variables are used by convention to
|
||||||
|
handle compilation for differing architectures.
|
||||||
|
The environment variable
|
||||||
|
.CW $objtype
|
||||||
|
controls which Plan 9 compiler and loader are used by
|
||||||
|
.CW pcc ,
|
||||||
|
as well as the location of header and library files.
|
||||||
|
For example, if
|
||||||
|
.CW $objtype
|
||||||
|
is
|
||||||
|
.CW mips ,
|
||||||
|
then
|
||||||
|
.CW pcc
|
||||||
|
has
|
||||||
|
.CW cpp
|
||||||
|
look for headers in
|
||||||
|
.CW /mips/include/ape
|
||||||
|
followed by
|
||||||
|
.CW /sys/include/ape ;
|
||||||
|
then
|
||||||
|
.CW pcc
|
||||||
|
uses
|
||||||
|
.CW vc
|
||||||
|
to create
|
||||||
|
.CW .v
|
||||||
|
object files;
|
||||||
|
finally,
|
||||||
|
.CW vl
|
||||||
|
is used to create an executable using libraries in
|
||||||
|
.CW /mips/lib/ape .
|
||||||
|
.SH
|
||||||
|
Psh and Cc
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW pcc
|
||||||
|
command is intended for uses where the source code is
|
||||||
|
ANSI/POSIX, but the programs are built in the usual Plan 9
|
||||||
|
manner \(em with
|
||||||
|
.CW mk
|
||||||
|
and producing object files with names ending in
|
||||||
|
.CW .v ,
|
||||||
|
etc.
|
||||||
|
Sometimes it is best to use the standard POSIX
|
||||||
|
.CW make
|
||||||
|
and
|
||||||
|
.CW cc
|
||||||
|
(which produces object files with names ending in
|
||||||
|
.CW .o ,
|
||||||
|
and automatically calls the loader unless
|
||||||
|
.CW -c
|
||||||
|
is specified).
|
||||||
|
Under these circumstances, execute the command:
|
||||||
|
.DS
|
||||||
|
.CW "ape/psh"
|
||||||
|
.DE
|
||||||
|
This starts a POSIX shell, with an environment that
|
||||||
|
includes the POSIX commands
|
||||||
|
.CW ar89 ,
|
||||||
|
.CW c89 ,
|
||||||
|
.CW cc ,
|
||||||
|
.CW basename ,
|
||||||
|
.CW dirname ,
|
||||||
|
.CW expr ,
|
||||||
|
.CW false ,
|
||||||
|
.CW grep ,
|
||||||
|
.CW kill ,
|
||||||
|
.CW make ,
|
||||||
|
.CW rmdir ,
|
||||||
|
.CW sed ,
|
||||||
|
.CW sh ,
|
||||||
|
.CW stty ,
|
||||||
|
.CW true ,
|
||||||
|
.CW uname ,
|
||||||
|
and
|
||||||
|
.CW yacc .
|
||||||
|
There are also a few placeholders for commands that cannot be
|
||||||
|
implemented in Plan 9:
|
||||||
|
.CW chown ,
|
||||||
|
.CW ln ,
|
||||||
|
and
|
||||||
|
.CW umask .
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW cc
|
||||||
|
command accepts the options mandated for
|
||||||
|
the POSIX command
|
||||||
|
.CW c89 ,
|
||||||
|
as specified in the C-Language Development Utilities Option
|
||||||
|
annex of the POSIX Shell and Utilities standard.
|
||||||
|
It also accepts the following nonstandard options:
|
||||||
|
.CW -v
|
||||||
|
for echoing the commands for each pass to stdout;
|
||||||
|
.CW -A
|
||||||
|
to turn on ANSI prototype warnings;
|
||||||
|
.CW -S
|
||||||
|
to leave assembly language in
|
||||||
|
.I file .s;
|
||||||
|
.CW -Wp,\fIargs\fP
|
||||||
|
to pass
|
||||||
|
.I args
|
||||||
|
to the
|
||||||
|
.CW cpp ;
|
||||||
|
.CW -W0,\fIargs\fP
|
||||||
|
to pass
|
||||||
|
.I args
|
||||||
|
to 2c, etc.;
|
||||||
|
and
|
||||||
|
.CW -Wl,\fIargs\fP
|
||||||
|
to pass
|
||||||
|
.I args
|
||||||
|
to 2l, etc.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW sh
|
||||||
|
command is pdksh, a mostly POSIX-compliant public domain Korn Shell.
|
||||||
|
The Plan 9 implementation does not include
|
||||||
|
the emacs and vi editing modes.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW stty
|
||||||
|
command only has effect if the
|
||||||
|
.CW ape/ptyfs
|
||||||
|
command has been started to interpose a pseudo-tty interface
|
||||||
|
between
|
||||||
|
.CW /dev/cons
|
||||||
|
and the running command.
|
||||||
|
None of the distributed commands do this automatically.
|
||||||
|
.SH
|
||||||
|
Symbols
|
||||||
|
.PP
|
||||||
|
The C and POSIX standards require that certain symbols be
|
||||||
|
defined in headers.
|
||||||
|
They also require that certain other classes of symbols not
|
||||||
|
be defined in the headers, and specify certain other
|
||||||
|
symbols that may be defined in headers at the discretion
|
||||||
|
of the implementation.
|
||||||
|
POSIX defines
|
||||||
|
.I "feature test macros" ,
|
||||||
|
which are preprocessor symbols beginning with an underscore
|
||||||
|
and then a capital letter; if the program
|
||||||
|
.CW #defines
|
||||||
|
a feature test macro before the inclusion of any headers,
|
||||||
|
then it is requesting that certain symbols be visible in the headers.
|
||||||
|
The most important feature test macro is
|
||||||
|
.CW _POSIX_SOURCE :
|
||||||
|
when it is defined, exactly the symbols required by POSIX are
|
||||||
|
visible in the appropriate headers.
|
||||||
|
Consider
|
||||||
|
.CW <signal.h>
|
||||||
|
for example:
|
||||||
|
ANSI defines some names that must be defined in
|
||||||
|
.CW <signal.h> ,
|
||||||
|
but POSIX defines others, such as
|
||||||
|
.CW sigset_t ,
|
||||||
|
which are not allowed according to ANSI.
|
||||||
|
The solution is to make the additional symbols visible only when
|
||||||
|
.CW _POSIX_SOURCE
|
||||||
|
is defined.
|
||||||
|
.PP
|
||||||
|
To export a program, it helps to know whether it fits
|
||||||
|
in one of the following categories:
|
||||||
|
.IP 1.
|
||||||
|
Strictly conforming ANSI C program. It only uses features of the language,
|
||||||
|
libraries, and headers explicitly required by the C standard. It does not
|
||||||
|
depend on unspecified, undefined, or implementation-dependent behavior,
|
||||||
|
and does not exceed any minimum implementation limit.
|
||||||
|
.IP 2.
|
||||||
|
Strictly conforming POSIX program. Similar, but for the POSIX standard as well.
|
||||||
|
.IP 3.
|
||||||
|
Some superset of POSIX, with extensions. Each extension
|
||||||
|
is selected by a feature test macro, so it is clear which extensions
|
||||||
|
are being used.
|
||||||
|
.PP
|
||||||
|
With APE, if headers are always included to declare any library functions
|
||||||
|
used, then the set of feature test macros defined by a program will
|
||||||
|
show which of the above categories the program is in.
|
||||||
|
To accomplish this, no symbol is defined in a header if it is not required
|
||||||
|
by the C or POSIX standard, and those required by the POSIX standard
|
||||||
|
are protected by
|
||||||
|
.CW "#ifdef _POSIX_SOURCE" .
|
||||||
|
For example,
|
||||||
|
.CW <errno.h>
|
||||||
|
defines
|
||||||
|
.CW EDOM ,
|
||||||
|
.CW ERANGE ,
|
||||||
|
and
|
||||||
|
.CW errno ,
|
||||||
|
as required by the C standard.
|
||||||
|
The C standard allows more names beginning with
|
||||||
|
.CW E ,
|
||||||
|
but our header defines only those unless
|
||||||
|
.CW _POSIX_SOURCE
|
||||||
|
is defined, in which case the symbols required by POSIX are also defined.
|
||||||
|
This means that a program that uses
|
||||||
|
.CW ENAMETOOLONG
|
||||||
|
cannot masquerade as a strictly conforming ANSI C program.
|
||||||
|
.PP
|
||||||
|
.CW Pcc
|
||||||
|
and
|
||||||
|
.CW cc
|
||||||
|
do not predefine any preprocessor symbols except those required by
|
||||||
|
the ANSI C standard:
|
||||||
|
.CW __STDC__ ,
|
||||||
|
.CW __LINE__ ,
|
||||||
|
.CW __FILE__ ,
|
||||||
|
.CW __DATE__ ,
|
||||||
|
and
|
||||||
|
.CW __TIME__ .
|
||||||
|
Any others must be defined in the program itself or by using
|
||||||
|
.CW -D
|
||||||
|
on the command line.
|
||||||
|
.SH
|
||||||
|
Extensions
|
||||||
|
.PP
|
||||||
|
The discipline enforced by putting only required
|
||||||
|
names in the headers is useful for exporting programs,
|
||||||
|
but it gets in the way when importing programs.
|
||||||
|
The compromise is to allow additional symbols in headers,
|
||||||
|
additional headers, and additional library functions,
|
||||||
|
but only under control of extension feature test macros.
|
||||||
|
The following extensions are provided; unless otherwise
|
||||||
|
specified, the additional library functions are in the
|
||||||
|
default APE library.
|
||||||
|
.XX
|
||||||
|
.CW _LIBG_EXTENSION .
|
||||||
|
This allows the use of the Plan 9 graphics library.
|
||||||
|
The functions are as described in the Plan 9 manual (see
|
||||||
|
.I graphics (2))
|
||||||
|
except that
|
||||||
|
.CW div
|
||||||
|
had to be renamed
|
||||||
|
.CW ptdiv .
|
||||||
|
Include the
|
||||||
|
.CW <libg.h>
|
||||||
|
header to declare the needed types and functions.
|
||||||
|
.XX
|
||||||
|
.CW _LIMITS_EXTENSION .
|
||||||
|
POSIX does not require that names such as
|
||||||
|
.CW PATH_MAX
|
||||||
|
and
|
||||||
|
.CW OPEN_MAX
|
||||||
|
be defined in
|
||||||
|
.CW <limits.h> ,
|
||||||
|
but many programs assume they are defined there.
|
||||||
|
If
|
||||||
|
.CW _LIMITS_EXTENSION
|
||||||
|
is defined, those names will all be defined when
|
||||||
|
.CW <limits.h>
|
||||||
|
is included.
|
||||||
|
.XX
|
||||||
|
.CW _BSD_EXTENSION .
|
||||||
|
This extension includes not only Berkeley Unix routines,
|
||||||
|
but also a grab bag of other miscellaneous routines often
|
||||||
|
found in Unix implementations.
|
||||||
|
The extension allows the inclusion of any of:
|
||||||
|
.CW <bsd.h>
|
||||||
|
for
|
||||||
|
.CW bcopy() ,
|
||||||
|
.CW bcmp() ,
|
||||||
|
and similar Berkeley functions;
|
||||||
|
.CW <netdb.h>
|
||||||
|
for
|
||||||
|
.CW gethostbyname() ,
|
||||||
|
etc.,
|
||||||
|
and associated structures;
|
||||||
|
.CW <select.h>
|
||||||
|
for the Berkeley
|
||||||
|
.CW select
|
||||||
|
function and associated types and macros
|
||||||
|
for dealing with multiple input sources;
|
||||||
|
.CW <sys/ioctl.h>
|
||||||
|
for the
|
||||||
|
.CW ioctl
|
||||||
|
function (minimally implemented);
|
||||||
|
.CW <sys/param.h>
|
||||||
|
for
|
||||||
|
.CW NOFILES_MAX ;
|
||||||
|
.CW <sys/pty.h>
|
||||||
|
for pseudo-tty support via the
|
||||||
|
.CW ptsname(int)
|
||||||
|
and
|
||||||
|
.CW ptmname(int)
|
||||||
|
functions;
|
||||||
|
.CW <sys/resource.h> ;
|
||||||
|
.CW <sys/socket.h>
|
||||||
|
for socket structures, constants, and functions;
|
||||||
|
.CW <sys/time.h>
|
||||||
|
for definitions of the
|
||||||
|
.CW timeval
|
||||||
|
and
|
||||||
|
.CW timezone
|
||||||
|
structures;
|
||||||
|
and
|
||||||
|
.CW <sys/uio.h>
|
||||||
|
for the
|
||||||
|
.CW iovec
|
||||||
|
structure and the
|
||||||
|
.CW writev
|
||||||
|
and
|
||||||
|
.CW readv
|
||||||
|
functions used for scatter/gather I/O.
|
||||||
|
Defining
|
||||||
|
.CW _BSD_EXTENSION
|
||||||
|
also enables various extra definitions in
|
||||||
|
.CW <ctype.h> ,
|
||||||
|
.CW <signal.h> ,
|
||||||
|
.CW <stdio.h> ,
|
||||||
|
.CW <unistd.h> ,
|
||||||
|
.CW <sys/stat.h> ,
|
||||||
|
and
|
||||||
|
.CW <sys/times.h> .
|
||||||
|
.XX
|
||||||
|
.CW _NET_EXTENSION .
|
||||||
|
This extension allows inclusion of
|
||||||
|
.CW <libnet.h> ,
|
||||||
|
which defines the networking functions described in the Plan 9 manual page
|
||||||
|
.I dial (2).
|
||||||
|
.XX
|
||||||
|
.CW _PLAN9_EXTENSION .
|
||||||
|
This extension allows inclusion of
|
||||||
|
.CW <u.h> ,
|
||||||
|
.CW <lock.h> ,
|
||||||
|
.CW <qlock.h> ,
|
||||||
|
.CW <utf.h> ,
|
||||||
|
.CW <fmt.h> ,
|
||||||
|
and
|
||||||
|
.CW <draw.h> .
|
||||||
|
These are pieces of Plan 9 source code ported into APE,
|
||||||
|
mostly from
|
||||||
|
.CW <libc.h> .
|
||||||
|
.XX
|
||||||
|
.CW _REGEXP_EXTENSION .
|
||||||
|
This extension allows inclusion of
|
||||||
|
.CW <regexp.h> ,
|
||||||
|
which defines the regular expression matching functions described
|
||||||
|
in the Plan 9 manual page
|
||||||
|
.I regexp (2).
|
||||||
|
.XX
|
||||||
|
.CW _RESEARCH_SOURCE .
|
||||||
|
This extension enables a small library of functions from the Tenth Edition Unix
|
||||||
|
Research System (V10).
|
||||||
|
These functions and the types needed to use them are all defined in the
|
||||||
|
.CW <libv.h>
|
||||||
|
header.
|
||||||
|
The provided functions are:
|
||||||
|
.CW srand ,
|
||||||
|
.CW rand ,
|
||||||
|
.CW nrand ,
|
||||||
|
.CW lrand ,
|
||||||
|
and
|
||||||
|
.CW frand
|
||||||
|
(better random number generators);
|
||||||
|
.CW getpass ,
|
||||||
|
.CW tty_echoon ,
|
||||||
|
.CW tty_echooff
|
||||||
|
(for dealing with the common needs for mucking with terminal
|
||||||
|
characteristics);
|
||||||
|
.CW min
|
||||||
|
and
|
||||||
|
.CW max ;
|
||||||
|
.CW nap ;
|
||||||
|
and
|
||||||
|
.CW setfields ,
|
||||||
|
.CW getfields ,
|
||||||
|
and
|
||||||
|
.CW getmfields
|
||||||
|
(for parsing a line into fields).
|
||||||
|
See the Research Unix System Programmer's Manual, Tenth Edition, for a description
|
||||||
|
of these functions.
|
||||||
|
.XX
|
||||||
|
.CW _C99_SNPRINTF_EXTENSION .
|
||||||
|
This extension permits the use of the return values of
|
||||||
|
.I snprintf
|
||||||
|
and
|
||||||
|
.I vsnprintf .
|
||||||
|
Before C99, the 1999 C standard,
|
||||||
|
these functions usually returned the number of bytes,
|
||||||
|
excluding terminating NUL,
|
||||||
|
actually stored in the target string.
|
||||||
|
(GNU, as usual, had to be different and returned -1 if the target
|
||||||
|
string was too small.)
|
||||||
|
C99 requires them to instead return the number of bytes,
|
||||||
|
excluding terminating NUL,
|
||||||
|
that would have been written into the target string if it were infinitely large
|
||||||
|
or a negative value if an `encoding error' occurs,
|
||||||
|
so old programs compiled under C99 rules will be prone to overrunning
|
||||||
|
their buffers.
|
||||||
|
This extension is a way for the programmer to declare that he or she understands
|
||||||
|
the situation and has adjusted the code being compiled to compensate.
|
||||||
|
.SH
|
||||||
|
Common Problems
|
||||||
|
.PP
|
||||||
|
Some large systems, including X11, have been ported successfully
|
||||||
|
to Plan 9 using APE
|
||||||
|
(the X11 port is not included in the distribution, however,
|
||||||
|
because supporting it properly is too big a job).
|
||||||
|
The problems encountered fall into three categories:
|
||||||
|
(1) non-ANSI C/POSIX features used; (2) inadequate simulation of POSIX functions;
|
||||||
|
and (3) compiler/loader bugs.
|
||||||
|
By far the majority of problems are in the first category.
|
||||||
|
.PP
|
||||||
|
POSIX is just starting to be a target for programmers.
|
||||||
|
Most existing code is written to work with one or both of a BSD or a System V Unix.
|
||||||
|
System V is fairly close to POSIX, but there are some differences.
|
||||||
|
Also, many System V systems have imported some BSD features that are
|
||||||
|
not part of POSIX.
|
||||||
|
A good strategy for porting external programs is to first try using
|
||||||
|
.CW CFLAGS=-D_POSIX_SOURCE ;
|
||||||
|
if that doesn't work, try adding
|
||||||
|
.CW _D_BSD_EXTENSION
|
||||||
|
and perhaps include
|
||||||
|
.CW <bsd.h>
|
||||||
|
in source files.
|
||||||
|
Here are some solutions to problems that might remain:
|
||||||
|
.XX
|
||||||
|
Third (environment) argument to
|
||||||
|
.CW main .
|
||||||
|
Use the
|
||||||
|
.CW environ
|
||||||
|
global instead.
|
||||||
|
.XX
|
||||||
|
.CW OPEN_MAX ,
|
||||||
|
.CW PATH_MAX ,
|
||||||
|
etc., assumed in
|
||||||
|
.CW <limits.h> .
|
||||||
|
Rewrite to call
|
||||||
|
.CW sysconf
|
||||||
|
or define
|
||||||
|
.CW _LIMITS_EXTENSION .
|
||||||
|
.XX
|
||||||
|
.CW <varargs.h> .
|
||||||
|
Rewrite to use
|
||||||
|
.CW <stdarg.h> .
|
||||||
|
.PP
|
||||||
|
The second class of problems has to do with inadequacies in the Plan 9
|
||||||
|
simulation of POSIX functions.
|
||||||
|
These shortcomings have rarely gotten in the way
|
||||||
|
(except, perhaps, for the
|
||||||
|
.CW link
|
||||||
|
problem).
|
||||||
|
.XX
|
||||||
|
Functions for setting the userid, groupid, effective userid and effective groupid
|
||||||
|
do not do anything useful. The concept is impossible to simulate in Plan 9.
|
||||||
|
.CW Chown
|
||||||
|
also does nothing.
|
||||||
|
.XX
|
||||||
|
.CW execlp
|
||||||
|
and the related functions do not look at the
|
||||||
|
.CW PATH
|
||||||
|
environment variable. They just try the current directory and
|
||||||
|
.CW /bin
|
||||||
|
if the pathname is not absolute.
|
||||||
|
.XX
|
||||||
|
Advisory locking via
|
||||||
|
.CW fcntl
|
||||||
|
is not implemented.
|
||||||
|
.XX
|
||||||
|
.CW isatty
|
||||||
|
is hard to do correctly.
|
||||||
|
The approximation used is only sometimes correct.
|
||||||
|
.XX
|
||||||
|
.CW link
|
||||||
|
always fails.
|
||||||
|
.XX
|
||||||
|
With
|
||||||
|
.CW open ,
|
||||||
|
the
|
||||||
|
.CW O_NOCTTY
|
||||||
|
option has no effect.
|
||||||
|
The concept of a controlling tty is foreign to Plan 9.
|
||||||
|
.XX
|
||||||
|
.CW setsid
|
||||||
|
forks the name space and note group,
|
||||||
|
which is only approximately the right behavior.
|
||||||
|
.XX
|
||||||
|
The functions dealing with stacking signals,
|
||||||
|
.CW sigpending ,
|
||||||
|
.CW sigprocmask
|
||||||
|
and
|
||||||
|
.CW sigsuspend ,
|
||||||
|
do not work.
|
||||||
|
.XX
|
||||||
|
.CW umask
|
||||||
|
has no effect, as there is no such concept in Plan 9.
|
||||||
|
.XX
|
||||||
|
code that does
|
||||||
|
.CW getenv("HOME")
|
||||||
|
should be changed to
|
||||||
|
.CW getenv("home")
|
||||||
|
on Plan 9.
|
6017
sys/doc/ape.ps
Normal file
6017
sys/doc/ape.ps
Normal file
File diff suppressed because it is too large
Load diff
1431
sys/doc/asm.ms
Normal file
1431
sys/doc/asm.ms
Normal file
File diff suppressed because it is too large
Load diff
9383
sys/doc/asm.ps
Normal file
9383
sys/doc/asm.ps
Normal file
File diff suppressed because it is too large
Load diff
2147
sys/doc/auth.ms
Normal file
2147
sys/doc/auth.ms
Normal file
File diff suppressed because it is too large
Load diff
15060
sys/doc/auth.ps
Normal file
15060
sys/doc/auth.ps
Normal file
File diff suppressed because it is too large
Load diff
178
sys/doc/backup.ms
Normal file
178
sys/doc/backup.ms
Normal file
|
@ -0,0 +1,178 @@
|
||||||
|
.FP lucidasans
|
||||||
|
.HTML "Venti Backups to Blu-Ray Discs"
|
||||||
|
.EQ
|
||||||
|
delim $$
|
||||||
|
.EN
|
||||||
|
.
|
||||||
|
.TL
|
||||||
|
Venti Backups to Blu-Ray Discs
|
||||||
|
.AU
|
||||||
|
Geoff Collyer
|
||||||
|
.AI
|
||||||
|
.MH
|
||||||
|
.SH
|
||||||
|
Overview
|
||||||
|
.PP
|
||||||
|
As a precaution against multiple disks in our
|
||||||
|
Plan 9
|
||||||
|
.I venti
|
||||||
|
server's RAID array failing at about the same time,
|
||||||
|
or other catastrophic failure, we record
|
||||||
|
.I venti
|
||||||
|
arenas,
|
||||||
|
after they are sealed,
|
||||||
|
onto dual-layer Blu-Ray discs (BDs).
|
||||||
|
One could use other large optical discs instead.
|
||||||
|
.PP
|
||||||
|
The advertised capacity of a dual-layer BD is 50GB,
|
||||||
|
but those aren't even disk-manufacturer's (decimal) gigabytes,
|
||||||
|
which would give a capacity of
|
||||||
|
$50 times 10 sup 9$ bytes,
|
||||||
|
which is roughly equivalent to 46.6 gigabytes,
|
||||||
|
as the term is used by everyone but disk manufacturers.
|
||||||
|
In the case of BDs,
|
||||||
|
even that is an exaggeration, with the actual capacity being
|
||||||
|
closer to $48.44 times 10 sup 9$ bytes,
|
||||||
|
so the claimed capacity should be read as `50 VAX-gigabytes',
|
||||||
|
where a
|
||||||
|
.I VAX-gigabyte
|
||||||
|
is 968,800,338 bytes.
|
||||||
|
The default
|
||||||
|
.I venti
|
||||||
|
arena size is 512MB, but for some reason our server is configured
|
||||||
|
with 1GB arenas, so we could fit 46 of them on a BD.
|
||||||
|
To leave a little extra room for lead-in, lead-out, inter-track gaps,
|
||||||
|
lossless-linking and the like,
|
||||||
|
we record 45 arenas per BD.
|
||||||
|
.PP
|
||||||
|
The scripts used and records kept are in
|
||||||
|
.CW /sys/lib/backup
|
||||||
|
and pertain to the file server on which they are stored.
|
||||||
|
You will probably want to edit
|
||||||
|
.CW funcs
|
||||||
|
to set default file server and Blu-ray device, at minimum.
|
||||||
|
.SH
|
||||||
|
Creating and Updating Backups
|
||||||
|
.PP
|
||||||
|
We start
|
||||||
|
.I cdfs
|
||||||
|
after inserting a disc (virgin or partially-written),
|
||||||
|
then use
|
||||||
|
.I venti/rdarena
|
||||||
|
to copy the next sealed but not backed-up arena
|
||||||
|
to the start of the unwritten portion of the BD by writing to
|
||||||
|
.CW /mnt/cd/wd/x .
|
||||||
|
We don't fixate data BDs, as that seems to tickle a bug,
|
||||||
|
perhaps in our Sony Blu-Ray burners, that only records the first track
|
||||||
|
in the disc index upon fixation.
|
||||||
|
.PP
|
||||||
|
One can find out which arenas are sealed and which are open by viewing
|
||||||
|
.CW http://\fIventi-server\fP/index .
|
||||||
|
We also periodically print the most recent
|
||||||
|
.I fossil
|
||||||
|
dump scores and save the paper with the discs.
|
||||||
|
.PP
|
||||||
|
All of this is packaged up as scripts in
|
||||||
|
.CW /sys/lib/backup ,
|
||||||
|
notably
|
||||||
|
.CW backup .
|
||||||
|
A typical invocation would be just
|
||||||
|
.DS
|
||||||
|
.ft CW
|
||||||
|
cd /sys/lib/backup
|
||||||
|
backup
|
||||||
|
.ft
|
||||||
|
.DE
|
||||||
|
which will guide its invoker as to which discs to insert into a Blu-ray
|
||||||
|
burner and when.
|
||||||
|
This works for a first full backup and for subsequent incremental backups
|
||||||
|
of just the newly-sealed arenas.
|
||||||
|
There is provision for burning multiple backup sets, the default being
|
||||||
|
.CW set1 .
|
||||||
|
To burn a second set, we would
|
||||||
|
.DS
|
||||||
|
.ft CW
|
||||||
|
mkdir /sys/lib/backup/set2
|
||||||
|
backup -s set2
|
||||||
|
.ft
|
||||||
|
.DE
|
||||||
|
.CW backup
|
||||||
|
and related scripts keep track of which BD is current and how many
|
||||||
|
tracks are recorded, and which arenas have been dumped to BD.
|
||||||
|
.PP
|
||||||
|
We have recorded two sets of BD backups, one of which will go to
|
||||||
|
Antwerp to seed their
|
||||||
|
.I venti
|
||||||
|
server and also serve as off-site backup for Murray Hill.
|
||||||
|
.SH
|
||||||
|
Restoring from Backups
|
||||||
|
.PP
|
||||||
|
After a disaster, or when setting up a new
|
||||||
|
.I venti
|
||||||
|
server from BD backups,
|
||||||
|
the first step is to get Plan 9 running on the new
|
||||||
|
.I venti
|
||||||
|
server.
|
||||||
|
This could be done by installing into a smallish (2GB)
|
||||||
|
.I fossil
|
||||||
|
partition from a Plan 9 installation CD, if necessary.
|
||||||
|
One would then initialise the new disk partitions per
|
||||||
|
.I venti-fmt (8)
|
||||||
|
and read all the arenas on all the BDs into the new
|
||||||
|
.I venti
|
||||||
|
by running
|
||||||
|
.I venti/wrarena
|
||||||
|
once per BD track (arena).
|
||||||
|
.br
|
||||||
|
.ne 3
|
||||||
|
.PP
|
||||||
|
To add the contents of a backup BD to a (possibly fresh)
|
||||||
|
.I venti
|
||||||
|
store,
|
||||||
|
shut down the
|
||||||
|
.I venti
|
||||||
|
server,
|
||||||
|
format the arenas partition, then
|
||||||
|
run
|
||||||
|
.DS
|
||||||
|
.ft CW
|
||||||
|
restore \fIfirst-arena-number\fP
|
||||||
|
.ft
|
||||||
|
.DE
|
||||||
|
after inserting a BD into the Blu-ray drive.
|
||||||
|
Repeat this for each BD in the backup set.
|
||||||
|
When all the arenas have been restored,
|
||||||
|
it will be necessary to build a new
|
||||||
|
.I venti
|
||||||
|
index,
|
||||||
|
the usual steps being to run
|
||||||
|
.I checkarenas ,
|
||||||
|
.I fmtisect ,
|
||||||
|
.I fmtbloom ,
|
||||||
|
.I fmtindex ,
|
||||||
|
and
|
||||||
|
.I "buildindex -b" ,
|
||||||
|
all from
|
||||||
|
.I venti-fmt (8).
|
||||||
|
Then the
|
||||||
|
.I venti
|
||||||
|
server may be restarted.
|
||||||
|
.PP
|
||||||
|
Once the
|
||||||
|
.I venti
|
||||||
|
storage has been restored,
|
||||||
|
a new
|
||||||
|
.I fossil
|
||||||
|
partition (perhaps the existing one or another one)
|
||||||
|
can be initialised from the last
|
||||||
|
.I fossil
|
||||||
|
dump score corresponding to the last arena on BD
|
||||||
|
(see
|
||||||
|
.I fossil/flfmt
|
||||||
|
in
|
||||||
|
.I fossil (4)):
|
||||||
|
.DS
|
||||||
|
.ft CW
|
||||||
|
fossil/flfmt -v c388...32b5 /dev/sdC0/fossil
|
||||||
|
.ft
|
||||||
|
.DE
|
4366
sys/doc/backup.ps
Normal file
4366
sys/doc/backup.ps
Normal file
File diff suppressed because it is too large
Load diff
13
sys/doc/cleanps
Normal file
13
sys/doc/cleanps
Normal file
|
@ -0,0 +1,13 @@
|
||||||
|
#!/bin/rc
|
||||||
|
|
||||||
|
if(! ~ $#* 1){
|
||||||
|
echo usage: cleanps infile >[1=2]
|
||||||
|
exit usage
|
||||||
|
}
|
||||||
|
|
||||||
|
{
|
||||||
|
echo %!PS-Adobe-2.0
|
||||||
|
cat /sys/doc/preamble
|
||||||
|
grep -v '^%%DocumentFonts' $1
|
||||||
|
} > cleanps.tmp
|
||||||
|
mv cleanps.tmp $1
|
3752
sys/doc/colophon.ps
Normal file
3752
sys/doc/colophon.ps
Normal file
File diff suppressed because it is too large
Load diff
1449
sys/doc/comp.ms
Normal file
1449
sys/doc/comp.ms
Normal file
File diff suppressed because it is too large
Load diff
9932
sys/doc/comp.ps
Normal file
9932
sys/doc/comp.ps
Normal file
File diff suppressed because it is too large
Load diff
1157
sys/doc/compiler.ms
Normal file
1157
sys/doc/compiler.ms
Normal file
File diff suppressed because it is too large
Load diff
8239
sys/doc/compiler.ps
Normal file
8239
sys/doc/compiler.ps
Normal file
File diff suppressed because it is too large
Load diff
332
sys/doc/contents.html
Normal file
332
sys/doc/contents.html
Normal file
|
@ -0,0 +1,332 @@
|
||||||
|
<?xml version="1.0" encoding="utf-8"?>
|
||||||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
|
||||||
|
"http://www.w3.org/TR/html4/loose.dtd">
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta http-equiv=Content-Type content="text/html; charset=utf8">
|
||||||
|
<title>Plan 9 — The Documents (Volume 2)</title>
|
||||||
|
</meta>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.05in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.50in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: center;">
|
||||||
|
<span style="font-size: 12pt"></span><span style="font-size: 12pt"><b>Plan 9 — The Documents (Volume 2)</b></span><span style="font-size: 12pt"></span></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.50in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Introduction
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Plan 9 From Bell Labs
|
||||||
|
(<a href="9.html">html</a> |
|
||||||
|
<a href="9.ps">ps</a> |
|
||||||
|
<a href="9.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike, Dave Presotto, Sean Dorward, Bob Flandrena, Ken Thompson, Howard Trickey, and Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An overview of the system; read at least this paper before you install.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Use of Name Spaces in Plan 9
|
||||||
|
(<a href="names.html">html</a> |
|
||||||
|
<a href="names.ps">ps</a> |
|
||||||
|
<a href="names.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike, Dave Presotto, Ken Thompson, Howard Trickey, and Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">What’s in a name?
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Organization of Networks in Plan 9
|
||||||
|
(<a href="net/net.html">html</a> |
|
||||||
|
<a href="net/net.ps">ps</a> |
|
||||||
|
<a href="net/net.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Dave Presotto and Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Connecting the pieces. The details in the paper are outdated but the ideas still apply.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Security in Plan 9
|
||||||
|
(<a href="auth.html">html</a> |
|
||||||
|
<a href="auth.ps">ps</a> |
|
||||||
|
<a href="auth.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Russ Cox, Eric Grosse, Rob Pike, Dave Presotto, and Sean Quinlan
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An overview of the security architecture.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Programming
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">How to Use the Plan 9 C Compiler
|
||||||
|
(<a href="comp.html">html</a> |
|
||||||
|
<a href="comp.ps">ps</a> |
|
||||||
|
<a href="comp.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The starting point for C programming under Plan 9.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Changes to the Programming Environment in the Fourth Release of Plan 9
|
||||||
|
(<a href="prog4.html">html</a> |
|
||||||
|
<a href="prog4.ps">ps</a> |
|
||||||
|
<a href="prog4.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An overview of the changes to the C library since the Third Release.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">APE — The ANSI/POSIX Environment
|
||||||
|
(<a href="ape.html">html</a> |
|
||||||
|
<a href="ape.ps">ps</a> |
|
||||||
|
<a href="ape.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Howard Trickey
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Moving C code between UNIX and Plan 9.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Acid: A Debugger Built From A Language
|
||||||
|
(<a href="acidpaper.html">html</a> |
|
||||||
|
<a href="acidpaper.ps">ps</a> |
|
||||||
|
<a href="acidpaper.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An overview paper about the Acid debugger.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Acid Manual
|
||||||
|
(<a href="acid.html">html</a> |
|
||||||
|
<a href="acid.ps">ps</a> |
|
||||||
|
<a href="acid.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The reference manual for the language and its libraries.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Maintaining Files on Plan 9 with Mk
|
||||||
|
(<a href="mk.html">html</a> |
|
||||||
|
<a href="mk.ps">ps</a> |
|
||||||
|
<a href="mk.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Andrew G. Hume and Bob Flandrena
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An introduction to Plan 9’s replacement for </span><span style="font-size: 10pt"><tt>make</tt></span><span style="font-size: 10pt">.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Plan 9 Mkfiles
|
||||||
|
(<a href="mkfiles.html">html</a> |
|
||||||
|
<a href="mkfiles.ps">ps</a> |
|
||||||
|
<a href="mkfiles.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Bob Flandrena
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The conventions for using </span><span style="font-size: 10pt"><tt>mk</tt></span><span style="font-size: 10pt"> in Plan 9.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A Manual for the Plan 9 assembler
|
||||||
|
(<a href="asm.html">html</a> |
|
||||||
|
<a href="asm.ps">ps</a> |
|
||||||
|
<a href="asm.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Things you’d rather not know.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>User Interfaces
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">8½, the Plan 9 Window System
|
||||||
|
(<a href="8½/8½.html">html</a> |
|
||||||
|
<a href="8½/8½.ps">ps</a> |
|
||||||
|
<a href="8½/8½.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An introduction to the (previous) window system and its unusual implementation.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Rc — The Plan 9 Shell
|
||||||
|
(<a href="rc.html">html</a> |
|
||||||
|
<a href="rc.ps">ps</a> |
|
||||||
|
<a href="rc.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Tom Duff
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An introduction to the new shell, complete with examples.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Text Editor </span><span style="font-size: 10pt"><tt>sam</tt></span><span style="font-size: 10pt">
|
||||||
|
(<a href="sam/sam.html">html</a> |
|
||||||
|
<a href="sam/sam.ps">ps</a> |
|
||||||
|
<a href="sam/sam.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><tt>Sam</tt></span><span style="font-size: 10pt"> is the standard editor on Plan 9.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Acme: A User Interface for Programmers
|
||||||
|
(<a href="acme/acme.html">html</a> |
|
||||||
|
<a href="acme/acme.ps">ps</a> |
|
||||||
|
<a href="acme/acme.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A system with a more radical approach to programming and editing.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Plumbing and Other Utilities
|
||||||
|
(<a href="plumb.html">html</a> |
|
||||||
|
<a href="plumb.ps">ps</a> |
|
||||||
|
<a href="plumb.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Inter-process communication that enlivens the interactive user interface.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Implementation
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Hello World, or Καλημέρα κόσμε, or </span><span style="font-size: 10pt">こんにちは 世界</span><span style="font-size: 10pt">
|
||||||
|
(<a href="utf.html">html</a> |
|
||||||
|
<a href="utf.ps">ps</a> |
|
||||||
|
<a href="utf.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike and Ken Thompson
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The details about Plan 9’s character set: the Unicode Standard plus an ASCII-compatible encoding.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Plan 9 C Compilers
|
||||||
|
(<a href="compiler.html">html</a> |
|
||||||
|
<a href="compiler.ps">ps</a> |
|
||||||
|
<a href="compiler.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Ken Thompson
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The design and some internals of the compiler suite.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Adding Application Support for a New Architecture in Plan 9
|
||||||
|
(<a href="libmach.html">html</a> |
|
||||||
|
<a href="libmach.ps">ps</a> |
|
||||||
|
<a href="libmach.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Bob Flandrena
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The procedures necessary to add a new instruction set to Plan 9’s programming environment.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Plan 9 File Server
|
||||||
|
(<a href="fs/fs.html">html</a> |
|
||||||
|
<a href="fs/fs.ps">ps</a> |
|
||||||
|
<a href="fs/fs.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Ken Thompson
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The design of the central file server and its novel backup system.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Venti: A new approach to archival storage
|
||||||
|
(<a href="venti/venti.html">html</a> |
|
||||||
|
<a href="venti/venti.ps">ps</a> |
|
||||||
|
<a href="venti/venti.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Sean Quinlan and Sean Dorward
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Archival block-level storage using secure hashes as block identifiers.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The IL protocol
|
||||||
|
(<a href="il/il.html">html</a> |
|
||||||
|
<a href="il/il.ps">ps</a> |
|
||||||
|
<a href="il/il.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Dave Presotto and Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A description of the Internet protocol Plan 9 uses for internal communication.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Lexical File Names in Plan 9, or, Getting Dot-Dot Right
|
||||||
|
(<a href="lexnames.html">html</a> |
|
||||||
|
<a href="lexnames.ps">ps</a> |
|
||||||
|
<a href="lexnames.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A vexing old problem solved: how to make </span><span style="font-size: 10pt"><tt>pwd</tt></span><span style="font-size: 10pt"> get the right answer in the face of multiply-bound directories.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Process Sleep and Wakeup on a Shared-memory Multiprocessor
|
||||||
|
(<a href="sleep.html">html</a> |
|
||||||
|
<a href="sleep.ps">ps</a> |
|
||||||
|
<a href="sleep.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike, Dave Presotto, Ken Thompson, and Gerard Holzmann
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A detailed study of a central issue in the Plan 9 kernel.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Miscellany
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A Guide to the Lp Printer Spooler
|
||||||
|
(<a href="lp.html">html</a> |
|
||||||
|
<a href="lp.ps">ps</a> |
|
||||||
|
<a href="lp.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Paul Glick
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Adminstering the suite of tools to drive PostScript printers.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Troff User’s Manual
|
||||||
|
(<a href="troff.ps">ps</a> |
|
||||||
|
<a href="troff.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Joseph F. Ossanna and Brian W. Kernighan
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The old warhorse, updated for Unicode characters.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Using SPIN
|
||||||
|
(<a href="spin.html">html</a> |
|
||||||
|
<a href="spin.ps">ps</a> |
|
||||||
|
<a href="spin.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Gerard Holzmann
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An introduction to a tool for analyzing parallel and distributed programs.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Installation
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Various Ports
|
||||||
|
(<a href="port.html">html</a> |
|
||||||
|
<a href="port.ps">ps</a> |
|
||||||
|
<a href="port.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The hardware requirements for the Plan 9 compilers and kernels.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<center><a href="/plan9/">Plan 9 Home Page</a></center>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.50in"></p>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
|
185
sys/doc/contents.ms
Normal file
185
sys/doc/contents.ms
Normal file
|
@ -0,0 +1,185 @@
|
||||||
|
.HTML "Plan 9 — The Documents (Volume 2)
|
||||||
|
.FP lucidasans
|
||||||
|
.na
|
||||||
|
.ds CH
|
||||||
|
.
|
||||||
|
.de He
|
||||||
|
.sp
|
||||||
|
.ft B
|
||||||
|
.in 0
|
||||||
|
\\$1
|
||||||
|
.sp .5
|
||||||
|
.ft
|
||||||
|
.br
|
||||||
|
..
|
||||||
|
.
|
||||||
|
.\" BUG: \! transparency always emits the rest of the line, even in
|
||||||
|
.\" an `unexecuted' if-else branch, so this doesn't work as desired.
|
||||||
|
.\" .de Ti
|
||||||
|
.\" .ft R
|
||||||
|
.\" .ie h \{\
|
||||||
|
.\" \\$3
|
||||||
|
.\" (\c
|
||||||
|
.\" .if !'\\$2'troff' \! \<a href="\\$2.html"\>html\</a\> |
|
||||||
|
.\" \! \<a href="\\$2.ps"\>ps\</a\>
|
||||||
|
.\" |
|
||||||
|
.\" \! \<a href="\\$2.pdf"\>pdf\</a\>)
|
||||||
|
.\" ...\}
|
||||||
|
.\" .el \{\
|
||||||
|
.\" .ta \\n(LLuR
|
||||||
|
.\" \\$3 \a\|\|\\$1
|
||||||
|
.\" ...\}
|
||||||
|
.\" .br
|
||||||
|
.\" ..
|
||||||
|
.
|
||||||
|
.de Au
|
||||||
|
.ft I
|
||||||
|
.in 1i
|
||||||
|
.ll -.5i
|
||||||
|
\\$1
|
||||||
|
.br
|
||||||
|
.ll +.5i
|
||||||
|
..
|
||||||
|
.de De
|
||||||
|
.ft R
|
||||||
|
.in .5i
|
||||||
|
.ll -.5i
|
||||||
|
\\$1
|
||||||
|
.br
|
||||||
|
.ll +.5i
|
||||||
|
.in 0
|
||||||
|
.sp .5
|
||||||
|
..
|
||||||
|
.de Co
|
||||||
|
..
|
||||||
|
.
|
||||||
|
.nr PS 9
|
||||||
|
.nr VS 11
|
||||||
|
.nf
|
||||||
|
.
|
||||||
|
.LP
|
||||||
|
.ps 12
|
||||||
|
.ce
|
||||||
|
.ie h .B "Plan 9 \(em The Documents (Volume 2)
|
||||||
|
.el .B "Table of Contents
|
||||||
|
.ps
|
||||||
|
.sp .5i
|
||||||
|
.He "Introduction
|
||||||
|
.
|
||||||
|
.Ti 1 9 "Plan 9 From Bell Labs
|
||||||
|
.Au "Rob Pike, Dave Presotto, Sean Dorward, Bob Flandrena, Ken Thompson, Howard Trickey, and Phil \%Winterbottom
|
||||||
|
.De "An overview of the system; read at least this paper before you install.
|
||||||
|
.Co seems ok; a little dated; unchanged except to mention appearance in Computing Systems
|
||||||
|
.Ti 23 names "The Use of Name Spaces in Plan 9
|
||||||
|
.Au "Rob Pike, Dave Presotto, Ken Thompson, Howard Trickey, and Phil \%Winterbottom
|
||||||
|
.Co updated only to mention appearance in SIGOPS
|
||||||
|
.De "What's in a name?
|
||||||
|
.Ti 29 net/net "The Organization of Networks in Plan 9
|
||||||
|
.Au "Dave Presotto and Phil Winterbottom
|
||||||
|
.De "Connecting the pieces. The details in the paper are outdated but the ideas still apply.
|
||||||
|
.Ti 43 auth "Security in Plan 9
|
||||||
|
.Au "Russ Cox, Eric Grosse, Rob Pike, Dave Presotto, and Sean Quinlan
|
||||||
|
.De "An overview of the security architecture.
|
||||||
|
.He "Programming
|
||||||
|
.Ti 63 comp "How to Use the Plan 9 C Compiler
|
||||||
|
.Au "Rob Pike
|
||||||
|
.Co updated
|
||||||
|
.De "The starting point for C programming under Plan 9.
|
||||||
|
.Ti 77 prog4 "Changes to the Programming Environment in the Fourth Release of Plan 9
|
||||||
|
.Au "Rob Pike
|
||||||
|
.De "An overview of the changes to the C library since the Third Release.
|
||||||
|
.Ti 83 ape "APE \(em The ANSI/POSIX Environment
|
||||||
|
.Au "Howard Trickey
|
||||||
|
.Co updated
|
||||||
|
.De "Moving C code between UNIX and Plan 9.
|
||||||
|
.Ti 87 acidpaper "Acid: A Debugger Built From A Language
|
||||||
|
.Au "Phil Winterbottom
|
||||||
|
.Co fine
|
||||||
|
.De "An overview paper about the Acid debugger.
|
||||||
|
.Ti 101 acid "Acid Manual
|
||||||
|
.Au "Phil Winterbottom
|
||||||
|
.Co updated
|
||||||
|
.De "The reference manual for the language and its libraries.
|
||||||
|
.Ti 127 mk "Maintaining Files on Plan 9 with Mk
|
||||||
|
.Au "Andrew G. Hume and Bob Flandrena
|
||||||
|
.Co updated
|
||||||
|
.De "An introduction to Plan 9's replacement for \f(CWmake\fP.
|
||||||
|
.Ti 141 mkfiles "Plan 9 Mkfiles
|
||||||
|
.Au "Bob Flandrena
|
||||||
|
.Co updated
|
||||||
|
.De "The conventions for using \f(CWmk\fP in Plan 9.
|
||||||
|
.Ti 149 asm "A Manual for the Plan 9 assembler
|
||||||
|
.Au "Rob Pike
|
||||||
|
.Co updated
|
||||||
|
.De "Things you'd rather not know.
|
||||||
|
.bp
|
||||||
|
.He "User Interfaces
|
||||||
|
.Ti 159 8½/8½ "8½, the Plan 9 Window System
|
||||||
|
.Au "Rob Pike
|
||||||
|
.Co fine - introductory footnote tweaked
|
||||||
|
.De "An introduction to the (previous) window system and its unusual implementation.
|
||||||
|
.Ti 169 rc "Rc \(em The Plan 9 Shell
|
||||||
|
.Au "Tom Duff
|
||||||
|
.Co updated
|
||||||
|
.De "An introduction to the new shell, complete with examples.
|
||||||
|
.Ti 185 sam/sam "The Text Editor \&\f(CWsam\fP
|
||||||
|
.Au "Rob Pike
|
||||||
|
.Co fine
|
||||||
|
.De "\f(CWSam\fP is the standard editor on Plan 9.
|
||||||
|
.Ti 215 acme/acme "Acme: A User Interface for Programmers
|
||||||
|
.Au "Rob Pike
|
||||||
|
.Co fine
|
||||||
|
.De "A system with a more radical approach to programming and editing.
|
||||||
|
.Ti 231 plumb "Plumbing and Other Utilities
|
||||||
|
.Au "Rob Pike
|
||||||
|
.Co new
|
||||||
|
.De "Inter-process communication that enlivens the interactive user interface.
|
||||||
|
.He "Implementation
|
||||||
|
.Ti 247 utf "Hello World, or Καλημέρα κόσμε, or \f(Jpこんにちは 世界\fP
|
||||||
|
.Au "Rob Pike and Ken Thompson
|
||||||
|
.Co fine
|
||||||
|
.De "The details about Plan 9's character set: the Unicode Standard plus an ASCII-compatible encoding.
|
||||||
|
.Ti 259 compiler "Plan 9 C Compilers
|
||||||
|
.Au "Ken Thompson
|
||||||
|
.Co updated
|
||||||
|
.De "The design and some internals of the compiler suite.
|
||||||
|
.Ti 271 libmach "Adding Application Support for a New Architecture in Plan 9
|
||||||
|
.Au "Bob Flandrena
|
||||||
|
.Co updated
|
||||||
|
.De "The procedures necessary to add a new instruction set to Plan 9's programming environment.
|
||||||
|
.Ti 279 fs/fs "The Plan 9 File Server
|
||||||
|
.Au "Ken Thompson
|
||||||
|
.Co updated
|
||||||
|
.De "The design of the central file server and its novel backup system.
|
||||||
|
.Ti 287 venti/venti "Venti: A new approach to archival storage
|
||||||
|
.Au "Sean Quinlan and Sean Dorward
|
||||||
|
.De "Archival block-level storage using secure hashes as block identifiers.
|
||||||
|
.Ti 301 il/il "The IL protocol
|
||||||
|
.Au "Dave Presotto and Phil Winterbottom
|
||||||
|
.De "A description of the Internet protocol Plan 9 uses for internal communication.
|
||||||
|
.Ti 307 lexnames "Lexical File Names in Plan 9, or, Getting Dot-Dot Right
|
||||||
|
.Au "Rob Pike
|
||||||
|
.Co new
|
||||||
|
.De "A vexing old problem solved: how to make \f(CWpwd\fP get the right answer in the face of multiply-bound directories.
|
||||||
|
.Ti 319 sleep "Process Sleep and Wakeup on a Shared-memory Multiprocessor
|
||||||
|
.Au "Rob Pike, Dave Presotto, Ken Thompson, and Gerard Holzmann
|
||||||
|
.Co fine - updated with citation footnote
|
||||||
|
.De "A detailed study of a central issue in the Plan 9 kernel.
|
||||||
|
.He "Miscellany
|
||||||
|
.Ti 325 lp "A Guide to the Lp Printer Spooler
|
||||||
|
.Au "Paul Glick
|
||||||
|
.De "Adminstering the suite of tools to drive PostScript printers.
|
||||||
|
.Ti 333 troff "Troff User's Manual
|
||||||
|
.Au "Joseph F. Ossanna and Brian W. Kernighan
|
||||||
|
.Co updated
|
||||||
|
.De "The old warhorse, updated for Unicode characters.
|
||||||
|
.bp
|
||||||
|
.Ti 373 spin "Using SPIN
|
||||||
|
.Au "Gerard Holzmann
|
||||||
|
.Co updated
|
||||||
|
.De "An introduction to a tool for analyzing parallel and distributed programs.
|
||||||
|
.He "Installation
|
||||||
|
.Ti 400 port "The Various Ports
|
||||||
|
.De "The hardware requirements for the Plan 9 compilers and kernels.
|
||||||
|
.
|
||||||
|
.Hp
|
4490
sys/doc/contents.ps
Normal file
4490
sys/doc/contents.ps
Normal file
File diff suppressed because it is too large
Load diff
1
sys/doc/docfonts
Normal file
1
sys/doc/docfonts
Normal file
|
@ -0,0 +1 @@
|
||||||
|
%%DocumentFonts: LucidaSansUnicode20 LucidaSansUnicode00 LucidaSansUnicode03 LucidaSansUnicode04 LucidaSansUnicode21 LucidaSansUnicode22 LucidaSansUnicode25 LucidaSans-Demi LucidaSans-Italic LucidaTypewriter
|
4
sys/doc/fonts
Normal file
4
sys/doc/fonts
Normal file
|
@ -0,0 +1,4 @@
|
||||||
|
# mkfile rules to get fonts in Lucida Sans.
|
||||||
|
# if you don't have Lucida fonts, change this next line to
|
||||||
|
# FONTS=''
|
||||||
|
FONTS='.FP lucidasans'
|
1163
sys/doc/fossil.ms
Normal file
1163
sys/doc/fossil.ms
Normal file
File diff suppressed because it is too large
Load diff
BIN
sys/doc/fossil.pdf
Normal file
BIN
sys/doc/fossil.pdf
Normal file
Binary file not shown.
8521
sys/doc/fossil.ps
Normal file
8521
sys/doc/fossil.ps
Normal file
File diff suppressed because it is too large
Load diff
BIN
sys/doc/fs/fs.pdf
Normal file
BIN
sys/doc/fs/fs.pdf
Normal file
Binary file not shown.
7772
sys/doc/fs/fs.ps
Normal file
7772
sys/doc/fs/fs.ps
Normal file
File diff suppressed because it is too large
Load diff
33
sys/doc/fs/mkfile
Normal file
33
sys/doc/fs/mkfile
Normal file
|
@ -0,0 +1,33 @@
|
||||||
|
</sys/doc/fonts
|
||||||
|
OBJ=\
|
||||||
|
p0\
|
||||||
|
p1\
|
||||||
|
p2\
|
||||||
|
p3\
|
||||||
|
p4\
|
||||||
|
p5\
|
||||||
|
p6\
|
||||||
|
p7\
|
||||||
|
p8\
|
||||||
|
p9\
|
||||||
|
pa\
|
||||||
|
|
||||||
|
all:V: fs.ps fs.pdf fs.html
|
||||||
|
|
||||||
|
%.pdf:D: %.ps
|
||||||
|
cat ../docfonts $stem.ps >_$stem.ps
|
||||||
|
# distill _$stem.ps && mv _$stem.pdf $stem.pdf
|
||||||
|
ps2pdf _$stem.ps $stem.pdf && rm -f _$stem.ps
|
||||||
|
|
||||||
|
fs.ps:D: $OBJ
|
||||||
|
{echo $FONTS; tbl $OBJ } | eqn | troff -ms | lp -dstdout >$target
|
||||||
|
../cleanps $target
|
||||||
|
|
||||||
|
fs.trout:D: $OBJ
|
||||||
|
{echo $FONTS; tbl $OBJ } | eqn | troff -ms >$target
|
||||||
|
|
||||||
|
fs.html:D: $OBJ
|
||||||
|
{echo $FONTS; tbl $OBJ } | eqn | htmlroff -ms -mhtml >$target
|
||||||
|
|
||||||
|
clean:V:
|
||||||
|
rm -f fs.^(html trout ps pdf)
|
80
sys/doc/fs/p0
Normal file
80
sys/doc/fs/p0
Normal file
|
@ -0,0 +1,80 @@
|
||||||
|
.HTML "The 64-bit Standalone Plan 9 File Server
|
||||||
|
.de Ex
|
||||||
|
.TA 0.5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i
|
||||||
|
.P1
|
||||||
|
.TA 0.5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i
|
||||||
|
..
|
||||||
|
.de Ee
|
||||||
|
.P2
|
||||||
|
..
|
||||||
|
|
||||||
|
.EQ
|
||||||
|
delim $$
|
||||||
|
.EN
|
||||||
|
.FP lucidasans
|
||||||
|
|
||||||
|
.TL
|
||||||
|
The 64-bit Standalone Plan 9 File Server
|
||||||
|
.AU
|
||||||
|
Ken Thompson*
|
||||||
|
.CW ken@plan9.bell-labs.com
|
||||||
|
.FS
|
||||||
|
\l'4i'
|
||||||
|
.br
|
||||||
|
* now
|
||||||
|
.\" .CW ken@entrisphere.com
|
||||||
|
.CW ken@google.com
|
||||||
|
.FE
|
||||||
|
.AU
|
||||||
|
Geoff Collyer
|
||||||
|
.CW geoff@plan9.bell-labs.com
|
||||||
|
.AI
|
||||||
|
.MH
|
||||||
|
.AB
|
||||||
|
This paper is a revision of Thompson's
|
||||||
|
.I "The Plan 9 File Server" ,
|
||||||
|
and describes the structure
|
||||||
|
and the operation of the new 64-bit Plan 9 file servers.
|
||||||
|
Some specifics apply to the 32-bit
|
||||||
|
Plan 9 file server
|
||||||
|
Emelie,
|
||||||
|
which code is also the basis for
|
||||||
|
the user-level file server
|
||||||
|
.CW kfs .
|
||||||
|
.PP
|
||||||
|
In 2004,
|
||||||
|
Collyer created a 64-bit version of
|
||||||
|
Thompson's 32-bit file server, updating all file
|
||||||
|
offsets, sizes and block numbers to 64 bits.
|
||||||
|
In addition, triple- and quadruple-indirect
|
||||||
|
blocks were implemented.
|
||||||
|
File name components were extended from 27 to 55 bytes.
|
||||||
|
This code is also the basis for the user-level file server
|
||||||
|
.I cwfs (4).
|
||||||
|
.AE
|
||||||
|
.SH
|
||||||
|
Introduction
|
||||||
|
.PP
|
||||||
|
The Plan 9 file server
|
||||||
|
Emelie
|
||||||
|
is the oldest piece of system software
|
||||||
|
still in use on Plan 9.
|
||||||
|
It evolved from a user-level program that served
|
||||||
|
serial lines on a Sequent multi-processor.
|
||||||
|
The current implementation is neither clean nor
|
||||||
|
portable,
|
||||||
|
but it has slowly come to terms with
|
||||||
|
its particular set of cranky computers
|
||||||
|
and devices.
|
||||||
|
.PP
|
||||||
|
The file server
|
||||||
|
.I fs64
|
||||||
|
runs a revision of Emelie's code
|
||||||
|
with 64-bit file sizes, offsets and block numbers
|
||||||
|
and indirect blocks from single to quadruple.
|
||||||
|
Actually these are 63-bit values, since the type used is
|
||||||
|
.I vlong
|
||||||
|
(signed
|
||||||
|
.I "long long"
|
||||||
|
integer),
|
||||||
|
but 63 bits should suffice for a little while.
|
39
sys/doc/fs/p1
Normal file
39
sys/doc/fs/p1
Normal file
|
@ -0,0 +1,39 @@
|
||||||
|
.SH
|
||||||
|
Process Structure
|
||||||
|
.PP
|
||||||
|
The Plan 9 file system server is made from
|
||||||
|
an ancient version of the Plan 9 kernel.
|
||||||
|
The kernel contains process control,
|
||||||
|
synchronization,
|
||||||
|
locks,
|
||||||
|
and some memory
|
||||||
|
allocation.
|
||||||
|
The kernel has no user processes or
|
||||||
|
virtual memory.
|
||||||
|
.PP
|
||||||
|
The structure of the file system server
|
||||||
|
is a set of kernel processes
|
||||||
|
synchronizing mostly through message passing.
|
||||||
|
In
|
||||||
|
.I fs64
|
||||||
|
there are 27 processes of 11 types:
|
||||||
|
.KS
|
||||||
|
.TS
|
||||||
|
center ;
|
||||||
|
c l c
|
||||||
|
n lf(CW) l .
|
||||||
|
number name function
|
||||||
|
_
|
||||||
|
15 srv Main file system server processes
|
||||||
|
1 rah Block read-ahead processes
|
||||||
|
1 scp Sync process
|
||||||
|
1 wcp WORM copy process
|
||||||
|
1 con Console process
|
||||||
|
1 ilo IL protocol process
|
||||||
|
1 ilt IL timer process
|
||||||
|
2 ethi Ethernet input process
|
||||||
|
2 etho Ethernet output process
|
||||||
|
1 flo Floppy disk process
|
||||||
|
1 snt sntp clock-synchronisation process
|
||||||
|
.TE
|
||||||
|
.KE
|
179
sys/doc/fs/p2
Normal file
179
sys/doc/fs/p2
Normal file
|
@ -0,0 +1,179 @@
|
||||||
|
.SH
|
||||||
|
The server processes
|
||||||
|
.PP
|
||||||
|
The main file system algorithm is a set
|
||||||
|
of identical processes
|
||||||
|
named
|
||||||
|
.CW srv
|
||||||
|
that honor the
|
||||||
|
9P protocol.
|
||||||
|
Each file system process waits on
|
||||||
|
a message queue for an incoming request.
|
||||||
|
The request contains a 9P message and
|
||||||
|
the address of a reply queue.
|
||||||
|
A
|
||||||
|
.CW srv
|
||||||
|
process parses the message,
|
||||||
|
performs pseudo-disk I/O
|
||||||
|
to the corresponding file system block device,
|
||||||
|
formulates a response,
|
||||||
|
and sends the
|
||||||
|
response back to the reply queue.
|
||||||
|
.PP
|
||||||
|
The unit of storage is a
|
||||||
|
logical block
|
||||||
|
(not physical sector) of data on a device:
|
||||||
|
.Ex
|
||||||
|
.TA 0.5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i
|
||||||
|
enum
|
||||||
|
{
|
||||||
|
RBUFSIZE = 8*1024
|
||||||
|
};
|
||||||
|
|
||||||
|
typedef vlong Off;
|
||||||
|
typedef
|
||||||
|
struct
|
||||||
|
{
|
||||||
|
short pad;
|
||||||
|
short tag;
|
||||||
|
Off path;
|
||||||
|
} Tag;
|
||||||
|
|
||||||
|
enum
|
||||||
|
{
|
||||||
|
BUFSIZE = RBUFSIZE - sizeof(Tag)
|
||||||
|
};
|
||||||
|
|
||||||
|
typedef
|
||||||
|
struct
|
||||||
|
{
|
||||||
|
uchar data[BUFSIZE];
|
||||||
|
Tag tag;
|
||||||
|
} Block;
|
||||||
|
.Ee
|
||||||
|
All devices are idealized as a perfect disk
|
||||||
|
of contiguously numbered blocks each of size
|
||||||
|
.CW RBUFSIZE .
|
||||||
|
Each block has a tag that identifies what type
|
||||||
|
of block it is and a unique id of the file or directory
|
||||||
|
where this block resides.
|
||||||
|
The remaining data in the block depends on
|
||||||
|
what type of block it is.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW srv
|
||||||
|
process's main data structure is the directory entry.
|
||||||
|
This is the equivalent of a UNIX i-node and
|
||||||
|
defines the set of block addresses that comprise a file or directory.
|
||||||
|
Unlike the i-node,
|
||||||
|
the directory entry also has the name of the
|
||||||
|
file or directory in it:
|
||||||
|
.Ex
|
||||||
|
enum
|
||||||
|
{
|
||||||
|
NAMELEN = 56,
|
||||||
|
NDBLOCK = 6,
|
||||||
|
NIBLOCK = 4,
|
||||||
|
};
|
||||||
|
.Ee
|
||||||
|
.Ex
|
||||||
|
typedef
|
||||||
|
struct
|
||||||
|
{
|
||||||
|
char name[NAMELEN];
|
||||||
|
short uid;
|
||||||
|
short gid;
|
||||||
|
ushort mode;
|
||||||
|
short wuid;
|
||||||
|
Qid qid;
|
||||||
|
Off size;
|
||||||
|
Off dblock[NDBLOCK];
|
||||||
|
Off iblocks[NIBLOCK];
|
||||||
|
long atime;
|
||||||
|
long mtime;
|
||||||
|
} Dentry;
|
||||||
|
.Ee
|
||||||
|
Each directory entry holds the file or directory
|
||||||
|
name, protection mode, access times, user-id, group-id, and addressing
|
||||||
|
information.
|
||||||
|
The entry
|
||||||
|
.CW wuid
|
||||||
|
is the user-id of the last writer of the file
|
||||||
|
and
|
||||||
|
.CW size
|
||||||
|
is the size of the file in bytes.
|
||||||
|
The addresses of the first 6
|
||||||
|
blocks of the file are held in the
|
||||||
|
.CW dblock
|
||||||
|
array.
|
||||||
|
If the file is larger than that,
|
||||||
|
an indirect block is allocated that holds
|
||||||
|
the next
|
||||||
|
.CW BUFSIZE/sizeof(Off)
|
||||||
|
block addresses of the file.
|
||||||
|
The indirect block address is held in
|
||||||
|
.CW iblocks[0] .
|
||||||
|
If the file is larger yet,
|
||||||
|
then there is a double indirect block that points
|
||||||
|
at indirect blocks.
|
||||||
|
The double indirect address is held in
|
||||||
|
.CW iblocks[1]
|
||||||
|
and can point at another
|
||||||
|
.CW (BUFSIZE/sizeof(Off))\u\s-2\&2\s+2\d
|
||||||
|
blocks of data.
|
||||||
|
This is extended through a quadruple indirect block at
|
||||||
|
.CW iblocks[3]
|
||||||
|
but the code is now parameterised to permit easily changing the
|
||||||
|
number of direct blocks and the depth of indirect blocks,
|
||||||
|
and also the maximum size of a file name component.
|
||||||
|
The maximum addressable size of a file is
|
||||||
|
therefore 7.93 petabytes at a block size of 8k,
|
||||||
|
but 7.98 exabytes (just under $2 sup 63$ bytes) at a block size of 32k.
|
||||||
|
File size is restricted to $2 sup 63 - 1$ bytes in any case
|
||||||
|
because the length of a file is maintained in a
|
||||||
|
(signed)
|
||||||
|
.I vlong .
|
||||||
|
These numbers are based on
|
||||||
|
.I fs64
|
||||||
|
which has a block size of 8k and
|
||||||
|
.CW sizeof(Off)
|
||||||
|
is 8.
|
||||||
|
.PP
|
||||||
|
The declarations of the indirect and double indirect blocks
|
||||||
|
are as follows.
|
||||||
|
.Ex
|
||||||
|
enum
|
||||||
|
{
|
||||||
|
INDPERBUF = BUFSIZE/sizeof(Off),
|
||||||
|
};
|
||||||
|
.Ee
|
||||||
|
.Ex
|
||||||
|
typedef
|
||||||
|
{
|
||||||
|
Off dblock[INDPERBUF];
|
||||||
|
Tag ibtag;
|
||||||
|
} Iblock;
|
||||||
|
.Ee
|
||||||
|
.Ex
|
||||||
|
typedef
|
||||||
|
{
|
||||||
|
Off iblock[INDPERBUF];
|
||||||
|
Tag dibtag;
|
||||||
|
} Diblock;
|
||||||
|
.Ee
|
||||||
|
.PP
|
||||||
|
The root of a file system is a single directory entry
|
||||||
|
at a known block address.
|
||||||
|
A directory is a file that consists of a list of
|
||||||
|
directory entries.
|
||||||
|
To make access easier,
|
||||||
|
a directory entry cannot cross blocks.
|
||||||
|
In
|
||||||
|
.I fs64
|
||||||
|
there are 47 directory entries per block.
|
||||||
|
.PP
|
||||||
|
The device on which the blocks reside is implicit
|
||||||
|
and ultimately comes from the 9P
|
||||||
|
.CW attach
|
||||||
|
message that specifies the name of the
|
||||||
|
device containing the root.
|
55
sys/doc/fs/p3
Normal file
55
sys/doc/fs/p3
Normal file
|
@ -0,0 +1,55 @@
|
||||||
|
.SH
|
||||||
|
Buffer Cache
|
||||||
|
.PP
|
||||||
|
When the file server is
|
||||||
|
booted,
|
||||||
|
all of the unused memory is allocated to
|
||||||
|
a block buffer pool.
|
||||||
|
There are two major operations on the buffer
|
||||||
|
pool.
|
||||||
|
.CW Getbuf
|
||||||
|
will find the buffer associated with a
|
||||||
|
particular block on a particular device.
|
||||||
|
The returned buffer is locked so that the
|
||||||
|
caller has exclusive use.
|
||||||
|
If the requested buffer is not in the pool,
|
||||||
|
some other buffer will be relabeled and
|
||||||
|
the data will be read from the requested device.
|
||||||
|
.CW Putbuf
|
||||||
|
will unlock a buffer and
|
||||||
|
if the contents are marked as modified,
|
||||||
|
the buffer will be written to the device before
|
||||||
|
the buffer is relabeled.
|
||||||
|
If there is some special mapping
|
||||||
|
or CPU cache flushing
|
||||||
|
that must occur in order for the physical I/O
|
||||||
|
device to access the buffers,
|
||||||
|
this is done between
|
||||||
|
.CW getbuf
|
||||||
|
and
|
||||||
|
.CW putbuf .
|
||||||
|
The contents of a buffer is never touched
|
||||||
|
except while it is locked between
|
||||||
|
.CW getbuf
|
||||||
|
and
|
||||||
|
.CW putbuf
|
||||||
|
calls.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
file system server processes
|
||||||
|
prevent deadlock in the buffers by
|
||||||
|
always locking parent and child
|
||||||
|
directory entries in that order.
|
||||||
|
Since the entire directory structure
|
||||||
|
is a hierarchy,
|
||||||
|
this makes the locking well-ordered,
|
||||||
|
preventing deadlock.
|
||||||
|
The major problem in the locking strategy is
|
||||||
|
that locks are at a block level and there are many
|
||||||
|
directory entries in a single block.
|
||||||
|
There are unnecessary lock conflicts
|
||||||
|
in the directory blocks.
|
||||||
|
When one of these directory blocks is tied up
|
||||||
|
accessing the very slow WORM,
|
||||||
|
then all I/O to dozens of unrelated directories
|
||||||
|
is blocked.
|
194
sys/doc/fs/p4
Normal file
194
sys/doc/fs/p4
Normal file
|
@ -0,0 +1,194 @@
|
||||||
|
.SH
|
||||||
|
Block Devices
|
||||||
|
.PP
|
||||||
|
The block device I/O system is like a
|
||||||
|
protocol stack of filters.
|
||||||
|
There are a set of pseudo-devices that call
|
||||||
|
recursively to other pseudo-devices and real devices.
|
||||||
|
The protocol stack is compiled from a configuration
|
||||||
|
string that specifies the order of pseudo-devices and devices.
|
||||||
|
Each pseudo-device and device has a set of entry points
|
||||||
|
that corresponds to the operations that the file system
|
||||||
|
requires of a device.
|
||||||
|
The most notable operations are
|
||||||
|
.CW read ,
|
||||||
|
.CW write ,
|
||||||
|
and
|
||||||
|
.CW size .
|
||||||
|
.PP
|
||||||
|
The device stack can best be described by
|
||||||
|
describing the syntax of the configuration string
|
||||||
|
that specifies the stack.
|
||||||
|
Configuration strings are used
|
||||||
|
during the setup of the file system.
|
||||||
|
For a description see
|
||||||
|
.I fsconfig (8).
|
||||||
|
In the following recursive definition,
|
||||||
|
.I D
|
||||||
|
represents a
|
||||||
|
string that specifies a block device.
|
||||||
|
.IP "\fID\fP = (\fIDD\fP...)"
|
||||||
|
.br
|
||||||
|
This is a set of devices that
|
||||||
|
are concatenated to form a single device.
|
||||||
|
The size of the catenated device is the
|
||||||
|
sum of the sizes of each sub-device.
|
||||||
|
.IP "\fID\fP = [\fIDD\fP...]"
|
||||||
|
.br
|
||||||
|
This is the interleaving of the
|
||||||
|
individual devices.
|
||||||
|
If there are N devices in the list,
|
||||||
|
then the pseudo-device is the N-way block
|
||||||
|
interleaving of the sub-devices.
|
||||||
|
The size of the interleaved device is
|
||||||
|
N times the size of the smallest sub-device.
|
||||||
|
.IP "\fID\fP = {\fIDD\fP...}"
|
||||||
|
.br
|
||||||
|
This is a set of devices that
|
||||||
|
constitute a `mirror' of the first sub-device, and form a single device.
|
||||||
|
A write to the device is performed,
|
||||||
|
at the same block address,
|
||||||
|
on the sub-devices, in right-to-left order.
|
||||||
|
A read from the device is performed on each sub-device,
|
||||||
|
in left-to-right order, until a read succeeds without error,
|
||||||
|
or the set is exhausted.
|
||||||
|
One can think of this as a poor man's RAID 1.
|
||||||
|
The size of the device is the size of the smallest sub-device.
|
||||||
|
.IP "\fID\fP = \f(CWp\fP\fIDN1.N2\fP"
|
||||||
|
.br
|
||||||
|
This is a partition of a sub-device.
|
||||||
|
The sub-device is partitioned into 100 equal pieces.
|
||||||
|
If the size of the sub-device is not divisible by 100,
|
||||||
|
then there will be some slop thrown away at the top.
|
||||||
|
The pseudo-device starts at the N1-th piece and
|
||||||
|
continues for N2 pieces. Thus
|
||||||
|
.CW p\fID\fP67.33
|
||||||
|
will be the
|
||||||
|
last third of the device
|
||||||
|
.I D .
|
||||||
|
.IP "\fID\fP = \f(CWf\fP\fID\fP"
|
||||||
|
.br
|
||||||
|
This is a fake write-once-read-many device simulated by a
|
||||||
|
second read-write device.
|
||||||
|
This second device is partitioned
|
||||||
|
into a set of block flags and a set of blocks.
|
||||||
|
The flags are used to generate errors if a
|
||||||
|
block is ever written twice or read without being written first.
|
||||||
|
.IP "\fID\fP = \f(CWx\fP\fID\fP"
|
||||||
|
.br
|
||||||
|
This is a byte-swapped version of the file system on D.
|
||||||
|
Since the file server currently writes integers in metadata to disk
|
||||||
|
in native byte order, moving a file system to a machine of the other
|
||||||
|
major byte order (e.g., MIPS to Pentium)
|
||||||
|
requires the use of
|
||||||
|
.CW x .
|
||||||
|
It knows the sizes of the various integer fields in the file system metadata.
|
||||||
|
Ideally, the file server would follow the Plan 9 religion and write a consistent
|
||||||
|
byte order on disk, regardless of processor.
|
||||||
|
In the mean time, it should be possible to automatically determine the need
|
||||||
|
for byte-swapping by examining data in the super-block of each file system,
|
||||||
|
though this has not been implemented yet.
|
||||||
|
.IP "\fID\fP = \f(CWc\fP\fIDD\fP"
|
||||||
|
.br
|
||||||
|
This is the cache/WORM device made up of a cache (read-write)
|
||||||
|
device and a WORM (write-once-read-many) device.
|
||||||
|
More on this later.
|
||||||
|
.IP "\fID\fP = \f(CWo\fP"
|
||||||
|
.br
|
||||||
|
This is the dump file system that is the
|
||||||
|
two-level hierarchy of all dumps ever taken on a cache/WORM.
|
||||||
|
The read-only root of the cache/WORM file system
|
||||||
|
(on the dump taken Feb 18, 1995) can
|
||||||
|
be referenced as
|
||||||
|
.CW /1995/0218
|
||||||
|
in this pseudo device.
|
||||||
|
The second dump taken that day will be
|
||||||
|
.CW /1995/02181 .
|
||||||
|
.IP "\fID\fP = \f(CWw\fP\fIN1.N2.N3\fP"
|
||||||
|
.br
|
||||||
|
This is a SCSI disk on controller N1, target N2 and logical unit number N3.
|
||||||
|
.IP "\fID\fP = \f(CWh\fP\fIN1.N2.0\fP"
|
||||||
|
.br
|
||||||
|
This is an (E)IDE or *ATA disk on controller N1, target N2
|
||||||
|
(target 0 is the IDE master, 1 the slave device).
|
||||||
|
These disks are currently run via programmed I/O, not DMA,
|
||||||
|
so they tend to be slower to access than SCSI disks.
|
||||||
|
.IP "\fID\fP = \f(CWr\fP\fIN1\fP"
|
||||||
|
.br
|
||||||
|
This is the same as
|
||||||
|
.CW w ,
|
||||||
|
but refers to a side of a WORM disc.
|
||||||
|
See the
|
||||||
|
.I j
|
||||||
|
device.
|
||||||
|
.IP "\fID\fP = \f(CWl\fP\fIN1\fP"
|
||||||
|
.br
|
||||||
|
This is the same as
|
||||||
|
.CW r ,
|
||||||
|
but one block from the SCSI disk is removed for labeling.
|
||||||
|
.IP "\fID\fP = \f(CWj(\fP\fID\d\s-2\&1\s+2\u\fID\d\s-2\&2\s+2\u\f(CW*)\fID\d\s-2\&3\s+2\u\f1"
|
||||||
|
.br
|
||||||
|
.I D\d\s-2\&1\s+2\u
|
||||||
|
is the juke box SCSI interface.
|
||||||
|
The
|
||||||
|
.I D\d\s-2\&2\s+2\u 's
|
||||||
|
are the SCSI drives in the juke box
|
||||||
|
and the
|
||||||
|
.I D\d\s-2\&3\s+2\u 's
|
||||||
|
are the demountable platters in the juke box.
|
||||||
|
.I D\d\s-2\&1\s+2\u
|
||||||
|
and
|
||||||
|
.I D\d\s-2\&2\s+2\u
|
||||||
|
must be
|
||||||
|
.CW w .
|
||||||
|
.I D\d\s-2\&3\s+2\u
|
||||||
|
must be pseudo devices of
|
||||||
|
.CW w ,
|
||||||
|
.CW r ,
|
||||||
|
or
|
||||||
|
.CW l
|
||||||
|
devices.
|
||||||
|
.PP
|
||||||
|
For
|
||||||
|
.CW w ,
|
||||||
|
.CW h ,
|
||||||
|
.CW l ,
|
||||||
|
and
|
||||||
|
.CW r
|
||||||
|
devices any of the configuration numbers
|
||||||
|
can be replaced by an iterator of the form
|
||||||
|
.CW <\fIN1-N2\fP> .
|
||||||
|
N1 can be greater than N2, indicating a descending sequence.
|
||||||
|
Thus
|
||||||
|
.Ex
|
||||||
|
[w0.<2-6>]
|
||||||
|
.Ee
|
||||||
|
is the interleaved SCSI disks on SCSI targets
|
||||||
|
2 through 6 of SCSI controller 0.
|
||||||
|
The main file system on
|
||||||
|
Emelie
|
||||||
|
is defined by the configuration string
|
||||||
|
.Ex
|
||||||
|
c[w1.<0-5>.0]j(w6w5w4w3w2)(l<0-236>l<238-474>)
|
||||||
|
.Ee
|
||||||
|
This is a cache/WORM driver.
|
||||||
|
The cache is three interleaved disks on SCSI controller 1
|
||||||
|
targets 0, 1, 2, 3, 4, and 5.
|
||||||
|
The WORM half of the cache/WORM
|
||||||
|
is 474 jukebox disks.
|
||||||
|
Another file server,
|
||||||
|
.I choline ,
|
||||||
|
has a main file system defined by
|
||||||
|
.Ex
|
||||||
|
c[w<1-3>]j(w1.<6-0>.0)(l<0-124>l<128-252>)
|
||||||
|
.Ee
|
||||||
|
The order of
|
||||||
|
.CW w1.<6-0>.0
|
||||||
|
matters here, since the optical jukebox's WORM drives's
|
||||||
|
SCSI target ids,
|
||||||
|
as delivered,
|
||||||
|
run in descending order relative to the numbers of the drives
|
||||||
|
in SCSI commands
|
||||||
|
(e.g., the jukebox controller is SCSI target 6,
|
||||||
|
drive #1 is SCSI target 5,
|
||||||
|
and drive #6 is SCSI target 0).
|
39
sys/doc/fs/p5
Normal file
39
sys/doc/fs/p5
Normal file
|
@ -0,0 +1,39 @@
|
||||||
|
.SH
|
||||||
|
The read-ahead processes
|
||||||
|
.PP
|
||||||
|
There are a set of file system processes,
|
||||||
|
.CW rah ,
|
||||||
|
that wait for messages consisting of a device and block
|
||||||
|
address.
|
||||||
|
When a message comes in,
|
||||||
|
the process reads the specified block from the device.
|
||||||
|
This is done by calling
|
||||||
|
.CW getbuf
|
||||||
|
and
|
||||||
|
.CW putbuf .
|
||||||
|
The purpose of this is the hope that these blocks
|
||||||
|
will be used later and that they will reside in the
|
||||||
|
buffer cache long enough not to be discarded before
|
||||||
|
they are used.
|
||||||
|
.PP
|
||||||
|
The messages to the read-ahead processes are
|
||||||
|
generated by the server processes.
|
||||||
|
The server processes maintain a relative block mark in every
|
||||||
|
open file.
|
||||||
|
Whenever an open file reads that relative block,
|
||||||
|
the next 110 block addresses of the file are sent
|
||||||
|
to the read-ahead processes and
|
||||||
|
the relative block mark is advanced by 100.
|
||||||
|
The initial relative block is set to 1.
|
||||||
|
If the file is opened and
|
||||||
|
only a few bytes are read,
|
||||||
|
then no anticipating reads are performed
|
||||||
|
since the relative block mark is set to 1
|
||||||
|
and only block offset 0 is read.
|
||||||
|
This is to prevent some
|
||||||
|
fairly common action such as
|
||||||
|
.Ex
|
||||||
|
file *
|
||||||
|
.Ee
|
||||||
|
from swamping the file system with read-ahead
|
||||||
|
requests that will never be used.
|
255
sys/doc/fs/p6
Normal file
255
sys/doc/fs/p6
Normal file
|
@ -0,0 +1,255 @@
|
||||||
|
.SH
|
||||||
|
Cache/WORM Driver
|
||||||
|
.PP
|
||||||
|
The cache/WORM (cw) driver is by far the
|
||||||
|
largest and most complicated device driver in the file server.
|
||||||
|
There are four devices involved in the cw driver.
|
||||||
|
It implements a read/write pseudo-device (the cw-device)
|
||||||
|
and a read-only pseudo-device (the dump device)
|
||||||
|
by performing operations on its two constituent devices
|
||||||
|
the read-write c-device and the write-once-read-many
|
||||||
|
w-device.
|
||||||
|
The block numbers on the four devices are distinct,
|
||||||
|
although the
|
||||||
|
.I cw
|
||||||
|
addresses,
|
||||||
|
dump addresses,
|
||||||
|
and the
|
||||||
|
.I w
|
||||||
|
addresses are
|
||||||
|
highly correlated.
|
||||||
|
.PP
|
||||||
|
The cw-driver uses the w-device as the
|
||||||
|
stable storage of the file system at the time of the
|
||||||
|
last dump.
|
||||||
|
All newly written and a large number of recently used
|
||||||
|
exact copies of blocks of the w-device are kept on the c-device.
|
||||||
|
The c-device is much smaller than the w-device and
|
||||||
|
so the subset of w-blocks that are kept on the c-device are
|
||||||
|
mapped through a hash table kept on a partition of the c-device.
|
||||||
|
.PP
|
||||||
|
The map portion of the c-device consists of blocks of buckets of entries.
|
||||||
|
The declarations follow.
|
||||||
|
.Ex
|
||||||
|
enum
|
||||||
|
{
|
||||||
|
BKPERBLK = 10,
|
||||||
|
CEPERBK = (BUFSIZE - BKPERBLK*sizeof(Off)) /
|
||||||
|
(sizeof(Centry)*BKPERBLK),
|
||||||
|
};
|
||||||
|
.Ee
|
||||||
|
.Ex
|
||||||
|
typedef
|
||||||
|
struct
|
||||||
|
{
|
||||||
|
ushort age;
|
||||||
|
short state;
|
||||||
|
Off waddr;
|
||||||
|
} Centry;
|
||||||
|
.Ee
|
||||||
|
.Ex
|
||||||
|
typedef
|
||||||
|
struct
|
||||||
|
{
|
||||||
|
long agegen;
|
||||||
|
Centry entry[CEPERBK];
|
||||||
|
} Bucket;
|
||||||
|
.Ee
|
||||||
|
.Ex
|
||||||
|
Bucket bucket[BKPERBLK];
|
||||||
|
.Ee
|
||||||
|
There is exactly one entry structure for each block in the
|
||||||
|
data partition of the c-device.
|
||||||
|
A bucket contains all of the w-addresses that have
|
||||||
|
the same hash code.
|
||||||
|
There are as many buckets as will fit
|
||||||
|
in a block and enough blocks to have the required
|
||||||
|
number of entries.
|
||||||
|
The entries in the bucket are maintained
|
||||||
|
in FIFO order with an age variable and an incrementing age generator.
|
||||||
|
When the age generator is about to overflow,
|
||||||
|
all of the ages in the bucket are rescaled
|
||||||
|
from zero.
|
||||||
|
.PP
|
||||||
|
The following steps go into converting a w-address into a c-address.
|
||||||
|
The bucket is found by
|
||||||
|
.Ex
|
||||||
|
bucket_number = w-address % total_buckets;
|
||||||
|
getbuf(c-device, bucket_offset + bucket_number/BKPERBLK);
|
||||||
|
.Ee
|
||||||
|
After the desired bucket is found,
|
||||||
|
the desired entry is found by a linear search within the bucket for the
|
||||||
|
entry with the desired
|
||||||
|
.CW waddr .
|
||||||
|
.PP
|
||||||
|
The state variable in the entry is
|
||||||
|
one of the following.
|
||||||
|
.Ex
|
||||||
|
enum
|
||||||
|
{
|
||||||
|
Cnone = 0,
|
||||||
|
Cdirty,
|
||||||
|
Cdump,
|
||||||
|
Cread,
|
||||||
|
Cwrite,
|
||||||
|
Cdump1,
|
||||||
|
};
|
||||||
|
.Ee
|
||||||
|
Every w-address has a state.
|
||||||
|
Blocks that are not in the
|
||||||
|
c-device have the implied
|
||||||
|
state
|
||||||
|
.CW Cnone .
|
||||||
|
The
|
||||||
|
.CW Cread
|
||||||
|
state is for blocks that have the
|
||||||
|
same data as the corresponding block in
|
||||||
|
the w-device.
|
||||||
|
Since the c-device is much faster than the
|
||||||
|
w-device,
|
||||||
|
.CW Cread
|
||||||
|
blocks are kept as long as possible and
|
||||||
|
used in preference to reading the w-device.
|
||||||
|
.CW Cread
|
||||||
|
blocks may be discarded from the c-device
|
||||||
|
when the space is needed for newer data.
|
||||||
|
The
|
||||||
|
.CW Cwrite
|
||||||
|
state is when the c-device contains newer data
|
||||||
|
than the corresponding block on the w-device.
|
||||||
|
This happens when a
|
||||||
|
.CW Cnone ,
|
||||||
|
.CW Cread ,
|
||||||
|
or
|
||||||
|
.CW Cwrite
|
||||||
|
block is written.
|
||||||
|
The
|
||||||
|
.CW Cdirty
|
||||||
|
state
|
||||||
|
is when the c-device contains
|
||||||
|
new data and the corresponding block
|
||||||
|
on the w-device has never been written.
|
||||||
|
This happens when a new block has been
|
||||||
|
allocated from the free space on the w-device.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW Cwrite
|
||||||
|
and
|
||||||
|
.CW Cdirty
|
||||||
|
blocks are created and never removed.
|
||||||
|
Unless something is done to
|
||||||
|
convert these blocks,
|
||||||
|
the c-device will gradually
|
||||||
|
fill up and stop functioning.
|
||||||
|
Once a day,
|
||||||
|
or by command,
|
||||||
|
a
|
||||||
|
.I dump
|
||||||
|
of the cw-device
|
||||||
|
is taken.
|
||||||
|
The purpose of
|
||||||
|
a dump is to queue the writes that
|
||||||
|
have been shunted to the c-device
|
||||||
|
to be written to the w-device.
|
||||||
|
Since the w-device is a WORM,
|
||||||
|
blocks cannot be rewritten.
|
||||||
|
Blocks that have already been written to the WORM must be
|
||||||
|
relocated to the unused portion of the w-device.
|
||||||
|
These are precisely the
|
||||||
|
blocks with
|
||||||
|
.CW Cwrite
|
||||||
|
state.
|
||||||
|
.PP
|
||||||
|
The dump algorithm is as follows:
|
||||||
|
.IP a)
|
||||||
|
The tree on the cw-device is walked
|
||||||
|
as long as the blocks visited have been
|
||||||
|
modified since the last dump.
|
||||||
|
These are the blocks with state
|
||||||
|
.CW Cwrite
|
||||||
|
and
|
||||||
|
.CW Cdirty .
|
||||||
|
It is possible to restrict the search
|
||||||
|
to within these blocks
|
||||||
|
since the directory containing a modified
|
||||||
|
file must have been accessed to modify the
|
||||||
|
file and accessing a directory will set its
|
||||||
|
modified time thus causing the block containing it
|
||||||
|
to be written.
|
||||||
|
The directory containing that directory must be
|
||||||
|
modified for the same reason.
|
||||||
|
The tree walk is thus drastically restrained and the
|
||||||
|
tree walk does not take much time.
|
||||||
|
.IP b)
|
||||||
|
All
|
||||||
|
.CW Cwrite
|
||||||
|
blocks found in the tree search
|
||||||
|
are relocated to new blank blocks on the w-device
|
||||||
|
and converted to
|
||||||
|
.CW Cdump
|
||||||
|
state.
|
||||||
|
All
|
||||||
|
.CW Cdirty
|
||||||
|
blocks are converted to
|
||||||
|
.CW Cdump
|
||||||
|
state without relocation.
|
||||||
|
At this point,
|
||||||
|
all modified blocks in the cw-device
|
||||||
|
have w-addresses that point to unwritten
|
||||||
|
WORM blocks.
|
||||||
|
These blocks are marked for later
|
||||||
|
writing to the w-device
|
||||||
|
with the state
|
||||||
|
.CW Cdump .
|
||||||
|
.IP c)
|
||||||
|
All open files that were pointing to modified
|
||||||
|
blocks are reopened to point at the corresponding
|
||||||
|
reallocated blocks.
|
||||||
|
This causes the directories leading to the
|
||||||
|
open files to be modified.
|
||||||
|
Thus the invariant discussed in a) is maintained.
|
||||||
|
.IP d)
|
||||||
|
The background dumping process will slowly
|
||||||
|
go through the map of the c-device and write out
|
||||||
|
all blocks with
|
||||||
|
.CW Cdump
|
||||||
|
state.
|
||||||
|
.PP
|
||||||
|
The dump takes a few minutes to walk the tree
|
||||||
|
and mark the blocks.
|
||||||
|
It can take hours to write the marked blocks
|
||||||
|
to the WORM.
|
||||||
|
If a marked block is rewritten before the old
|
||||||
|
copy has been written to the WORM,
|
||||||
|
it must be forced to the WORM before it is rewritten.
|
||||||
|
There is no problem if another dump is taken before the first one
|
||||||
|
is finished.
|
||||||
|
The newly marked blocks are just added to the marked blocks
|
||||||
|
left from the first dump.
|
||||||
|
.PP
|
||||||
|
If there is an error writing a marked block
|
||||||
|
to the WORM
|
||||||
|
then the
|
||||||
|
.CW dump
|
||||||
|
state is converted to
|
||||||
|
.CW Cdump1
|
||||||
|
and manual intervention is needed.
|
||||||
|
(See the
|
||||||
|
.CW cwcmd
|
||||||
|
.CW mvstate
|
||||||
|
command in
|
||||||
|
.I fs (8)).
|
||||||
|
These blocks can be disposed of by converting
|
||||||
|
their state back to
|
||||||
|
.CW Cdump
|
||||||
|
so that they will be written again.
|
||||||
|
They can also be converted to
|
||||||
|
.CW Cwrite
|
||||||
|
state so that they will be allocated new
|
||||||
|
addresses at the next dump.
|
||||||
|
In most other respects,
|
||||||
|
a
|
||||||
|
.CW Cdump1
|
||||||
|
block behaves like a
|
||||||
|
.CW Cwrite
|
||||||
|
block.
|
48
sys/doc/fs/p7
Normal file
48
sys/doc/fs/p7
Normal file
|
@ -0,0 +1,48 @@
|
||||||
|
.SH
|
||||||
|
Sync Copy and WORM Copy Processes
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW scp
|
||||||
|
process
|
||||||
|
wakes up every ten seconds and
|
||||||
|
issues writes to blocks in the buffer cache
|
||||||
|
that have been modified.
|
||||||
|
This is done automatically on important
|
||||||
|
console commands such as
|
||||||
|
.CW halt
|
||||||
|
and
|
||||||
|
.CW dump .
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW wcp
|
||||||
|
process also wakes up every ten seconds
|
||||||
|
and tries to copy a
|
||||||
|
.CW dump
|
||||||
|
block from the cache to the WORM.
|
||||||
|
As long as there are
|
||||||
|
.CW dump
|
||||||
|
blocks to copy and there is no competition for
|
||||||
|
the WORM device,
|
||||||
|
the copy will continue at full speed.
|
||||||
|
Whenever there is competition for the WORM
|
||||||
|
or there are no more blocks to
|
||||||
|
copy,
|
||||||
|
then the process will sleep ten seconds
|
||||||
|
before looking again.
|
||||||
|
.PP
|
||||||
|
The HP WORM jukebox consists of
|
||||||
|
238 disks divided into 476 sides
|
||||||
|
or platters.
|
||||||
|
Platter 0 is the
|
||||||
|
.I A
|
||||||
|
side of disk 0.
|
||||||
|
Platter 1 is the
|
||||||
|
.I A
|
||||||
|
side of the disk 1.
|
||||||
|
Platter 238 is the
|
||||||
|
.I B
|
||||||
|
side of disk 0.
|
||||||
|
On Emelie,
|
||||||
|
the main file system is configured
|
||||||
|
on both sides of the first 237 disks,
|
||||||
|
platters 0\-236 and 238\-474.
|
38
sys/doc/fs/p8
Normal file
38
sys/doc/fs/p8
Normal file
|
@ -0,0 +1,38 @@
|
||||||
|
.SH
|
||||||
|
9P Protocol Drivers
|
||||||
|
.PP
|
||||||
|
The file server described so far
|
||||||
|
waits for 9P protocol messages to
|
||||||
|
appear in its input queue.
|
||||||
|
It processes each message and
|
||||||
|
sends the reply back to the originator.
|
||||||
|
There are groups of processes that
|
||||||
|
perform protocol I/O on some network or
|
||||||
|
device and the resulting messages
|
||||||
|
are sent to the file system queue.
|
||||||
|
.PP
|
||||||
|
There are two sets of processes
|
||||||
|
.CW ethi
|
||||||
|
and
|
||||||
|
.CW etho
|
||||||
|
that perform Ethernet input and output on two different networks.
|
||||||
|
These processes send Ethernet messages
|
||||||
|
to/from two more processes
|
||||||
|
.CW ilo
|
||||||
|
and
|
||||||
|
.CW ilt
|
||||||
|
that do the IL reliable datagram protocol
|
||||||
|
on top of IP packets.
|
||||||
|
.PP
|
||||||
|
The last process in Emelie,
|
||||||
|
.CW con ,
|
||||||
|
reads the console
|
||||||
|
and calls internal subroutines to
|
||||||
|
executes commands typed.
|
||||||
|
Since there is only one process,
|
||||||
|
only one command can be executing at a
|
||||||
|
time.
|
||||||
|
See
|
||||||
|
.I fs (8)
|
||||||
|
for a description of the
|
||||||
|
commands available at the console.
|
24
sys/doc/fs/p9
Normal file
24
sys/doc/fs/p9
Normal file
|
@ -0,0 +1,24 @@
|
||||||
|
.SH
|
||||||
|
Acknowledgements
|
||||||
|
.PP
|
||||||
|
Ken Thompson created the Plan 9 file server
|
||||||
|
and maintained it for many years.
|
||||||
|
The cached WORM driver is based upon
|
||||||
|
Sean Quinlan's PhD. thesis and prototype.
|
||||||
|
Jim McKie maintained the IBM-PC-dependent code,
|
||||||
|
a thankless job.
|
||||||
|
Bruce Ellis modified the
|
||||||
|
.I 8c
|
||||||
|
compiler in 2004
|
||||||
|
to generate much faster code for common
|
||||||
|
.I vlong
|
||||||
|
operations, which made the 64-bit file server feasible.
|
||||||
|
Nigel Roles contributed support for the APC UPS
|
||||||
|
and the NCR/Symbios/LSI-Logic SCSI host adaptors.
|
||||||
|
.
|
||||||
|
.SH
|
||||||
|
References
|
||||||
|
.IP [1]
|
||||||
|
Sean Quinlan, ``A Cached WORM File System,''
|
||||||
|
.I "Software\(emPractice and Experience" ,
|
||||||
|
Vol 21., No 12., December 1991, pp. 1289\-1299.
|
76
sys/doc/fs/pa
Normal file
76
sys/doc/fs/pa
Normal file
|
@ -0,0 +1,76 @@
|
||||||
|
.bp
|
||||||
|
.SH
|
||||||
|
Appendix:
|
||||||
|
Maximum File Sizes in the 64-bit File Server
|
||||||
|
.PP
|
||||||
|
The maximum size of a single file in a Plan 9 file server's
|
||||||
|
file system with 64-bit block numbers
|
||||||
|
is determined by the file system block size
|
||||||
|
(there are single, double, triple and quadruple indirect blocks).
|
||||||
|
The maximum size is thus
|
||||||
|
$d ( 6 + x + x sup 2 + x sup 3 + x sup 4 )$
|
||||||
|
bytes, where
|
||||||
|
$d = blocksize - ( 2 + 2 + 8 )$
|
||||||
|
and
|
||||||
|
$x = left floor d over 8 right floor$,
|
||||||
|
8 being the size in bytes of a
|
||||||
|
.I "long long"
|
||||||
|
block number.
|
||||||
|
.LP
|
||||||
|
Note that
|
||||||
|
$2 sup 63 ~ = ~ 9,223,372,036,854,775,808 ~ = ~ 8$
|
||||||
|
EB (binary exabytes).
|
||||||
|
.LP
|
||||||
|
.KS
|
||||||
|
.TS
|
||||||
|
center ;
|
||||||
|
c s s
|
||||||
|
c c c
|
||||||
|
n n n .
|
||||||
|
Maximum File Sizes
|
||||||
|
blocksize max. file size in bytes
|
||||||
|
_
|
||||||
|
1k 239.455G 257,112,525,120
|
||||||
|
2k 7.73795T 8,507,967,771,456
|
||||||
|
3k 59.4174T 65,330,091,351,360
|
||||||
|
4k 251.779T 276,833,619,879,744
|
||||||
|
5k 770.93T 847,646,649,807,168
|
||||||
|
6k 1.87752P 2,113,900,586,253,120
|
||||||
|
7k 4.0645P 4,576,215,491,839,296
|
||||||
|
8k 7.93382P 8,932,685,435,522,880
|
||||||
|
_
|
||||||
|
9k 14.3102P 16,111,863,841,429,824
|
||||||
|
10k 24.2524P 27,305,748,837,688,128
|
||||||
|
11k 39.0823P 44,002,768,605,261,120
|
||||||
|
12k 60.4146P 68,020,766,726,780,736
|
||||||
|
13k 90.1856P 101,539,987,535,380,800
|
||||||
|
14k 130.683P 147,136,061,463,530,304
|
||||||
|
15k 184.575P 207,812,990,391,866,688
|
||||||
|
16k 254.939P 287,036,132,998,029,120
|
||||||
|
_
|
||||||
|
17k 345.293P 388,765,190,105,491,776
|
||||||
|
18k 459.621P 517,487,190,032,397,120
|
||||||
|
19k 602.407P 678,249,473,940,389,184
|
||||||
|
20k 778.66P 876,692,681,183,446,848
|
||||||
|
21k 993.946P 1,119,083,734,656,717,120
|
||||||
|
22k 1.22502E 1,412,348,826,145,348,416
|
||||||
|
23k 1.53012E 1,764,106,401,673,323,840
|
||||||
|
24k 1.89319E 2,182,700,146,852,294,464
|
||||||
|
25k 2.32213E 2,677,231,972,230,412,608
|
||||||
|
26k 2.82551E 3,257,594,998,641,165,120
|
||||||
|
27k 3.41264E 3,934,506,542,552,206,656
|
||||||
|
28k 4.09355E 4,719,541,101,414,192,960
|
||||||
|
29k 4.87905E 5,625,163,339,009,614,144
|
||||||
|
30k 5.78076E 6,664,761,070,801,627,968
|
||||||
|
31k 6.81111E 7,852,678,249,282,893,120
|
||||||
|
32k 7.98341E 9,204,247,949,324,402,496
|
||||||
|
_
|
||||||
|
33k 9.31184E 10,735,825,353,524,316,480
|
||||||
|
\&...
|
||||||
|
48k 60.666E 69,943,138,363,646,533,440
|
||||||
|
\&...
|
||||||
|
56k 131.149E 151,204,569,706,075,533,120
|
||||||
|
\&...
|
||||||
|
64k 255.734E 294,841,790,119,418,167,104
|
||||||
|
.TE
|
||||||
|
.KE
|
395
sys/doc/il/il.ms
Normal file
395
sys/doc/il/il.ms
Normal file
|
@ -0,0 +1,395 @@
|
||||||
|
.HTML "The IL Protocol
|
||||||
|
.TL
|
||||||
|
The IL protocol
|
||||||
|
.AU
|
||||||
|
Dave Presotto
|
||||||
|
Phil Winterbottom
|
||||||
|
.sp
|
||||||
|
presotto,philw@plan9.bell-labs.com
|
||||||
|
.AB
|
||||||
|
To transport the remote procedure call messages of the Plan 9 file system
|
||||||
|
protocol 9P, we have implemented a new network protocol, called IL.
|
||||||
|
It is a connection-based, lightweight transport protocol that carries
|
||||||
|
datagrams encapsulated by IP.
|
||||||
|
IL provides retransmission of lost messages and in-sequence delivery, but has
|
||||||
|
no flow control and no blind retransmission.
|
||||||
|
.AE
|
||||||
|
.SH
|
||||||
|
Introduction
|
||||||
|
.PP
|
||||||
|
Plan 9 uses a file system protocol, called 9P [PPTTW93], that assumes
|
||||||
|
in-sequence guaranteed delivery of delimited messages
|
||||||
|
holding remote procedure call
|
||||||
|
(RPC) requests and responses.
|
||||||
|
None of the standard IP protocols [RFC791] is suitable for transmission of
|
||||||
|
9P messages over an Ethernet or the Internet.
|
||||||
|
TCP [RFC793] has a high overhead and does not preserve delimiters.
|
||||||
|
UDP [RFC768], while cheap and preserving message delimiters, does not provide
|
||||||
|
reliable sequenced delivery.
|
||||||
|
When we were implementing IP, TCP, and UDP in our system we
|
||||||
|
tried to choose a protocol suitable for carrying 9P.
|
||||||
|
The properties we desired were:
|
||||||
|
.IP \(bu
|
||||||
|
Reliable datagram service
|
||||||
|
.IP \(bu
|
||||||
|
In-sequence delivery
|
||||||
|
.IP \(bu
|
||||||
|
Internetworking using IP
|
||||||
|
.IP \(bu
|
||||||
|
Low complexity, high performance
|
||||||
|
.IP \(bu
|
||||||
|
Adaptive timeouts
|
||||||
|
.LP
|
||||||
|
No standard protocol met our needs so we designed a new one,
|
||||||
|
called IL (Internet Link).
|
||||||
|
.PP
|
||||||
|
IL is a lightweight protocol encapsulated by IP.
|
||||||
|
It is connection-based and
|
||||||
|
provides reliable transmission of sequenced messages.
|
||||||
|
No provision is made for flow control since the protocol
|
||||||
|
is designed to transport RPC
|
||||||
|
messages between client and server, a structure with inherent flow limitations.
|
||||||
|
A small window for outstanding messages prevents too
|
||||||
|
many incoming messages from being buffered;
|
||||||
|
messages outside the window are discarded
|
||||||
|
and must be retransmitted.
|
||||||
|
Connection setup uses a two-way handshake to generate
|
||||||
|
initial sequence numbers at each end of the connection;
|
||||||
|
subsequent data messages increment the
|
||||||
|
sequence numbers to allow
|
||||||
|
the receiver to resequence out of order messages.
|
||||||
|
In contrast to other protocols, IL avoids blind retransmission.
|
||||||
|
This helps performance in congested networks,
|
||||||
|
where blind retransmission could cause further
|
||||||
|
congestion.
|
||||||
|
Like TCP, IL has adaptive timeouts,
|
||||||
|
so the protocol performs well both on the
|
||||||
|
Internet and on local Ethernets.
|
||||||
|
A round-trip timer is used
|
||||||
|
to calculate acknowledge and retransmission times
|
||||||
|
that match the network speed.
|
||||||
|
.SH
|
||||||
|
Connections
|
||||||
|
.PP
|
||||||
|
An IL connection carries a stream of data between two end points.
|
||||||
|
While the connection persists,
|
||||||
|
data entering one side is sent to the other side in the same sequence.
|
||||||
|
The functioning of a connection is described by the state machine in Figure 1,
|
||||||
|
which shows the states (circles) and transitions between them (arcs).
|
||||||
|
Each transition is labeled with the list of events that can cause
|
||||||
|
the transition and, separated by a horizontal line,
|
||||||
|
the messages sent or received on that transition.
|
||||||
|
The remainder of this paper is a discussion of this state machine.
|
||||||
|
.KF
|
||||||
|
\s-2
|
||||||
|
.PS 5.5i
|
||||||
|
copy "transition.pic"
|
||||||
|
.PE
|
||||||
|
\s+2
|
||||||
|
.RS
|
||||||
|
.IP \fIackok\fR 1.5i
|
||||||
|
any sequence number between id0 and next inclusive
|
||||||
|
.IP \fI!x\fR 1.5i
|
||||||
|
any value except x
|
||||||
|
.IP \- 1.5i
|
||||||
|
any value
|
||||||
|
.RE
|
||||||
|
.sp
|
||||||
|
.ce
|
||||||
|
.I "Figure 1 - IL State Transitions
|
||||||
|
.KE
|
||||||
|
.PP
|
||||||
|
The IL state machine has five states:
|
||||||
|
.I Closed ,
|
||||||
|
.I Syncer ,
|
||||||
|
.I Syncee ,
|
||||||
|
.I Established ,
|
||||||
|
and
|
||||||
|
.I Closing .
|
||||||
|
The connection is identified by the IP address and port number used at each end.
|
||||||
|
The addresses ride in the IP protocol header, while the ports are part of the
|
||||||
|
18-byte IL header.
|
||||||
|
The local variables identifying the state of a connection are:
|
||||||
|
.RS
|
||||||
|
.IP state 10
|
||||||
|
one of the states
|
||||||
|
.IP laddr 10
|
||||||
|
32-bit local IP address
|
||||||
|
.IP lport 10
|
||||||
|
16-bit local IL port
|
||||||
|
.IP raddr 10
|
||||||
|
32-bit remote IP address
|
||||||
|
.IP rport 10
|
||||||
|
16-bit remote IL port
|
||||||
|
.IP id0 10
|
||||||
|
32-bit starting sequence number of the local side
|
||||||
|
.IP rid0 10
|
||||||
|
32-bit starting sequence number of the remote side
|
||||||
|
.IP next 10
|
||||||
|
sequence number of the next message to be sent from the local side
|
||||||
|
.IP rcvd 10
|
||||||
|
the last in-sequence message received from the remote side
|
||||||
|
.IP unacked 10
|
||||||
|
sequence number of the first unacked message
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
Unused connections are in the
|
||||||
|
.I Closed
|
||||||
|
state with no assigned addresses or ports.
|
||||||
|
Two events open a connection: the reception of
|
||||||
|
a message whose addresses and ports match no open connection
|
||||||
|
or a user explicitly opening a connection.
|
||||||
|
In the first case, the message's source address and port become the
|
||||||
|
connection's remote address and port and the message's destination address
|
||||||
|
and port become the local address and port.
|
||||||
|
The connection state is set to
|
||||||
|
.I Syncee
|
||||||
|
and the message is processed.
|
||||||
|
In the second case, the user specifies both local and remote addresses and ports.
|
||||||
|
The connection's state is set to
|
||||||
|
.I Syncer
|
||||||
|
and a
|
||||||
|
.CW sync
|
||||||
|
message is sent to the remote side.
|
||||||
|
The legal values for the local address are constrained by the IP implementation.
|
||||||
|
.SH
|
||||||
|
Sequence Numbers
|
||||||
|
.PP
|
||||||
|
IL carries data messages.
|
||||||
|
Each message corresponds to a single write from
|
||||||
|
the operating system and is identified by a 32-bit
|
||||||
|
sequence number.
|
||||||
|
The starting sequence number for each direction in a
|
||||||
|
connection is picked at random and transmitted in the initial
|
||||||
|
.CW sync
|
||||||
|
message.
|
||||||
|
The number is incremented for each subsequent data message.
|
||||||
|
A retransmitted message contains its original sequence number.
|
||||||
|
.SH
|
||||||
|
Transmission/Retransmission
|
||||||
|
.PP
|
||||||
|
Each message contains two sequence numbers:
|
||||||
|
an identifier (ID) and an acknowledgement.
|
||||||
|
The acknowledgement is the last in-sequence
|
||||||
|
data message received by the transmitter of the message.
|
||||||
|
For
|
||||||
|
.CW data
|
||||||
|
and
|
||||||
|
.CW dataquery
|
||||||
|
messages, the ID is its sequence number.
|
||||||
|
For the control messages
|
||||||
|
.CW sync ,
|
||||||
|
.CW ack ,
|
||||||
|
.CW query ,
|
||||||
|
.CW state ,
|
||||||
|
and
|
||||||
|
.CW close ,
|
||||||
|
the ID is one greater than the sequence number of
|
||||||
|
the highest sent data message.
|
||||||
|
.PP
|
||||||
|
The sender transmits data messages with type
|
||||||
|
.CW data .
|
||||||
|
Any messages traveling in the opposite direction carry acknowledgements.
|
||||||
|
An
|
||||||
|
.CW ack
|
||||||
|
message will be sent within 200 milliseconds of receiving the data message
|
||||||
|
unless a returning message has already piggy-backed an
|
||||||
|
acknowledgement to the sender.
|
||||||
|
.PP
|
||||||
|
In IP, messages may be delivered out of order or
|
||||||
|
may be lost due to congestion or faults.
|
||||||
|
To overcome this,
|
||||||
|
IL uses a modified ``go back n'' protocol that also attempts
|
||||||
|
to avoid aggravating network congestion.
|
||||||
|
An average round trip time is maintained by measuring the delay between
|
||||||
|
the transmission of a message and the
|
||||||
|
receipt of its acknowledgement.
|
||||||
|
Until the first acknowledge is received, the average round trip time
|
||||||
|
is assumed to be 100ms.
|
||||||
|
If an acknowledgement is not received within four round trip times
|
||||||
|
of the first unacknowledged message
|
||||||
|
.I "rexmit timeout" "" (
|
||||||
|
in Figure 1), IL assumes the message or the acknowledgement
|
||||||
|
has been lost.
|
||||||
|
The sender then resends only the first unacknowledged message,
|
||||||
|
setting the type to
|
||||||
|
.CW dataquery .
|
||||||
|
When the receiver receives a
|
||||||
|
.CW dataquery ,
|
||||||
|
it responds with a
|
||||||
|
.CW state
|
||||||
|
message acknowledging the highest received in-sequence data message.
|
||||||
|
This may be the retransmitted message or, if the receiver has been
|
||||||
|
saving up out-of-sequence messages, some higher numbered message.
|
||||||
|
Implementations of the receiver are free to choose whether to save out-of-sequence messages.
|
||||||
|
Our implementation saves up to 10 packets ahead.
|
||||||
|
When the sender receives the
|
||||||
|
.CW state
|
||||||
|
message, it will immediately resend the next unacknowledged message
|
||||||
|
with type
|
||||||
|
.CW dataquery .
|
||||||
|
This continues until all messages are acknowledged.
|
||||||
|
.PP
|
||||||
|
If no acknowledgement is received after the first
|
||||||
|
.CW dataquery ,
|
||||||
|
the transmitter continues to timeout and resend the
|
||||||
|
.CW dataquery
|
||||||
|
message.
|
||||||
|
The intervals between retransmissions increase exponentially.
|
||||||
|
After 300 times the round trip time
|
||||||
|
.I "death timeout" "" (
|
||||||
|
in Figure 1), the sender gives up and
|
||||||
|
assumes the connection is dead.
|
||||||
|
.PP
|
||||||
|
Retransmission also occurs in the states
|
||||||
|
.I Syncer ,
|
||||||
|
.I Syncee ,
|
||||||
|
and
|
||||||
|
.I Close .
|
||||||
|
The retransmission intervals are the same as for data messages.
|
||||||
|
.SH
|
||||||
|
Keep Alive
|
||||||
|
.PP
|
||||||
|
Connections to dead systems must be discovered and torn down
|
||||||
|
lest they consume resources.
|
||||||
|
If the surviving system does not need to send any data and
|
||||||
|
all data it has sent has been acknowledged, the protocol
|
||||||
|
described so far will not discover these connections.
|
||||||
|
Therefore, in the
|
||||||
|
.I Established
|
||||||
|
state, if no other messages are sent for a 6 second period,
|
||||||
|
a
|
||||||
|
.CW query
|
||||||
|
is sent.
|
||||||
|
The receiver always replies to a
|
||||||
|
.CW query
|
||||||
|
with a
|
||||||
|
.CW state
|
||||||
|
message.
|
||||||
|
If no messages are received for 30 seconds, the
|
||||||
|
connection is torn down.
|
||||||
|
This is not shown in Figure 1.
|
||||||
|
.SH
|
||||||
|
Byte Ordering
|
||||||
|
.PP
|
||||||
|
All 32- and 16-bit quantities are transmitted high-order byte first, as
|
||||||
|
is the custom in IP.
|
||||||
|
.SH
|
||||||
|
Formats
|
||||||
|
.PP
|
||||||
|
The following is a C language description of an IP+IL
|
||||||
|
header, assuming no IP options:
|
||||||
|
.P1
|
||||||
|
typedef unsigned char byte;
|
||||||
|
struct IPIL
|
||||||
|
{
|
||||||
|
byte vihl; /* Version and header length */
|
||||||
|
byte tos; /* Type of service */
|
||||||
|
byte length[2]; /* packet length */
|
||||||
|
byte id[2]; /* Identification */
|
||||||
|
byte frag[2]; /* Fragment information */
|
||||||
|
byte ttl; /* Time to live */
|
||||||
|
byte proto; /* Protocol */
|
||||||
|
byte cksum[2]; /* Header checksum */
|
||||||
|
byte src[4]; /* Ip source */
|
||||||
|
byte dst[4]; /* Ip destination */
|
||||||
|
byte ilsum[2]; /* Checksum including header */
|
||||||
|
byte illen[2]; /* Packet length */
|
||||||
|
byte iltype; /* Packet type */
|
||||||
|
byte ilspec; /* Special */
|
||||||
|
byte ilsrc[2]; /* Src port */
|
||||||
|
byte ildst[2]; /* Dst port */
|
||||||
|
byte ilid[4]; /* Sequence id */
|
||||||
|
byte ilack[4]; /* Acked sequence */
|
||||||
|
};
|
||||||
|
.P2
|
||||||
|
.LP
|
||||||
|
Data is assumed to immediately follow the header in the message.
|
||||||
|
.CW Ilspec
|
||||||
|
is an extension reserved for future protocol changes.
|
||||||
|
.PP
|
||||||
|
The checksum is calculated with
|
||||||
|
.CW ilsum
|
||||||
|
and
|
||||||
|
.CW ilspec
|
||||||
|
set to zero.
|
||||||
|
It is the standard IP checksum, that is, the 16-bit one's complement of the one's
|
||||||
|
complement sum of all 16 bit words in the header and text. If a
|
||||||
|
message contains an odd number of header and text bytes to be
|
||||||
|
checksummed, the last byte is padded on the right with zeros to
|
||||||
|
form a 16-bit word for the checksum.
|
||||||
|
The checksum covers from
|
||||||
|
.CW cksum
|
||||||
|
to the end of the data.
|
||||||
|
.PP
|
||||||
|
The possible
|
||||||
|
.I iltype
|
||||||
|
values are:
|
||||||
|
.P1
|
||||||
|
enum {
|
||||||
|
sync= 0,
|
||||||
|
data= 1,
|
||||||
|
dataquery= 2,
|
||||||
|
ack= 3,
|
||||||
|
query= 4,
|
||||||
|
state= 5,
|
||||||
|
close= 6,
|
||||||
|
};
|
||||||
|
.P2
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW illen
|
||||||
|
field is the size in bytes of the IL header (18 bytes) plus the size of the data.
|
||||||
|
.SH
|
||||||
|
Numbers
|
||||||
|
.PP
|
||||||
|
The IP protocol number for IL is 40.
|
||||||
|
.PP
|
||||||
|
The assigned IL port numbers are:
|
||||||
|
.RS
|
||||||
|
.IP 7 15
|
||||||
|
echo all input to output
|
||||||
|
.IP 9 15
|
||||||
|
discard input
|
||||||
|
.IP 19 15
|
||||||
|
send a standard pattern to output
|
||||||
|
.IP 565 15
|
||||||
|
send IP addresses of caller and callee to output
|
||||||
|
.IP 566 15
|
||||||
|
Plan 9 authentication protocol
|
||||||
|
.IP 17005 15
|
||||||
|
Plan 9 CPU service, data
|
||||||
|
.IP 17006 15
|
||||||
|
Plan 9 CPU service, notes
|
||||||
|
.IP 17007 15
|
||||||
|
Plan 9 exported file systems
|
||||||
|
.IP 17008 15
|
||||||
|
Plan 9 file service
|
||||||
|
.IP 17009 15
|
||||||
|
Plan 9 remote execution
|
||||||
|
.IP 17030 15
|
||||||
|
Alef Name Server
|
||||||
|
.RE
|
||||||
|
.SH
|
||||||
|
References
|
||||||
|
.LP
|
||||||
|
[PPTTW93] Rob Pike, Dave Presotto, Ken Thompson, Howard Trickey, and Phil Winterbottom,
|
||||||
|
``The Use of Name Spaces in Plan 9'',
|
||||||
|
.I "Op. Sys. Rev.,
|
||||||
|
Vol. 27, No. 2, April 1993, pp. 72-76,
|
||||||
|
reprinted in this volume.
|
||||||
|
.br
|
||||||
|
[RFC791] RFC791,
|
||||||
|
.I "Internet Protocol,
|
||||||
|
.I "DARPA Internet Program Protocol Specification,
|
||||||
|
September 1981.
|
||||||
|
.br
|
||||||
|
[RFC793] RFC793,
|
||||||
|
.I "Transmission Control Protocol,
|
||||||
|
.I "DARPA Internet Program Protocol Specification,
|
||||||
|
September 1981.
|
||||||
|
.br
|
||||||
|
[RFC768] J. Postel, RFC768,
|
||||||
|
.I "User Datagram Protocol,
|
||||||
|
.I "DARPA Internet Program Protocol Specification,
|
||||||
|
August 1980.
|
BIN
sys/doc/il/il.pdf
Normal file
BIN
sys/doc/il/il.pdf
Normal file
Binary file not shown.
5782
sys/doc/il/il.ps
Normal file
5782
sys/doc/il/il.ps
Normal file
File diff suppressed because it is too large
Load diff
9
sys/doc/il/mkfile
Normal file
9
sys/doc/il/mkfile
Normal file
|
@ -0,0 +1,9 @@
|
||||||
|
</sys/doc/fonts
|
||||||
|
|
||||||
|
il.ps:D: il.ms transition.pic
|
||||||
|
{echo $FONTS; cat il.ms} | pic | troff -ms | lp -dstdout >il.ps
|
||||||
|
../cleanps il.ps
|
||||||
|
|
||||||
|
il.html:D: il.ms transition.pic
|
||||||
|
pic il.ms | htmlroff -ms -mhtml >il.html
|
||||||
|
|
121
sys/doc/il/transition.art
Normal file
121
sys/doc/il/transition.art
Normal file
|
@ -0,0 +1,121 @@
|
||||||
|
G 0
|
||||||
|
t 7.160 7.970 pelm,unicode,9 User Close
|
||||||
|
l 6.600 7.900 7.700 7.900
|
||||||
|
t 7.450 7.730 pelm,unicode,9 snd(close(next, rcvd))
|
||||||
|
;
|
||||||
|
G 1
|
||||||
|
g 2 0.040 0.305
|
||||||
|
;
|
||||||
|
G 2
|
||||||
|
t 3.950 2.380 pelm,unicode,9 rcv(sync(rid0, 0))
|
||||||
|
l 3.000 2.300 4.850 2.290
|
||||||
|
t 3.900 2.100 pelm,unicode,9 snd(sync(id0, rid0))
|
||||||
|
;
|
||||||
|
c 1.400 6.100 0.700
|
||||||
|
c 3.933 3.799 0.700
|
||||||
|
c 3.932 8.401 0.700
|
||||||
|
t 1.400 6.100 pelm,unicode,9 Closed
|
||||||
|
t 3.932 8.401 pelm,unicode,9 Syncer
|
||||||
|
t 3.933 3.799 pelm,unicode,9 Syncee
|
||||||
|
t 5.400 6.100 pelm,unicode,9 Established
|
||||||
|
a 3.285 8.668 2.660 8.650 1.980 8.340 S <
|
||||||
|
a 1.440 7.810 1.220 7.430 1.197 6.770 S <
|
||||||
|
l 2.500 6.900 1.991 6.475 S >
|
||||||
|
l 1.837 5.553 2.100 5.300 S <
|
||||||
|
l 1.420 8.090 2.420 8.090
|
||||||
|
t 1.900 8.200 pelm,unicode,9 User Open
|
||||||
|
a 1.300 4.400 1.200 4.900 1.274 5.411 S <
|
||||||
|
a 3.265 3.589 2.500 3.500 1.600 3.910 S <
|
||||||
|
t 1.400 4.000 pelm,unicode,9 no connection
|
||||||
|
l 5.028 5.507 4.750 5.110 S <
|
||||||
|
l 4.600 4.800 4.312 4.388 S <
|
||||||
|
l 4.991 6.668 4.700 7.200 S <
|
||||||
|
l 4.600 7.400 4.361 7.848 S <
|
||||||
|
s 8 6.000 3.430 6.100 2.800 5.300 1.800 3.930 1.650 1.640 1.760 0.800 2.300 0.580 4.350 0.930 5.380
|
||||||
|
c 7.230 2.150 0.700
|
||||||
|
g 0 1.150 -2.200
|
||||||
|
a 7.230 4.960 7.000 5.630 6.098 6.049 S <
|
||||||
|
s 4 5.840 5.590 6.130 5.150 5.650 4.600 5.810 4.120
|
||||||
|
l 7.779 2.845 7.673 2.692 S >
|
||||||
|
l 7.250 4.280 7.240 2.850 S >
|
||||||
|
l 0.720 5.620 0.791 5.755 S >
|
||||||
|
l 0.930 5.380 0.986 5.535 S >
|
||||||
|
t 2.900 7.210 pelm,unicode,9 rcv(ack(-, !id0))
|
||||||
|
t 2.900 7.000 pelm,unicode,9 rcv(close(-, id0)
|
||||||
|
t 4.800 7.300 pelm,unicode,9 rcv(sync(-, id0))
|
||||||
|
t 4.700 5.000 pelm,unicode,9 rcv(ack(-, id0))
|
||||||
|
l 5.960 4.620 7.940 4.620
|
||||||
|
t 6.940 4.400 pelm,unicode,9 snd(close(next, rcvd))
|
||||||
|
t 6.950 4.710 pelm,unicode,9 rcv(close(-, ackok))
|
||||||
|
t 6.100 3.600 pelm,unicode,9 rcv(sync(!rid0, -))
|
||||||
|
t 7.230 2.150 pelm,unicode,9 Closing
|
||||||
|
l 3.326 4.147 2.915 4.510 S >
|
||||||
|
l 3.501 7.849 3.100 7.500 S >
|
||||||
|
t 3.800 0.900 pelm,unicode,9 rcv(close(-, next))
|
||||||
|
a 4.800 1.200 5.700 1.300 6.670 1.730 S <
|
||||||
|
s 6 2.640 1.170 1.600 1.200 0.540 1.370 0.320 2.820 0.280 4.340 0.720 5.620
|
||||||
|
t 2.680 4.810 pelm,unicode,9 rcv(close(-, id0))
|
||||||
|
g 1 0.665 0.099
|
||||||
|
t 2.300 2.900 pelm,unicode,9 rexmit timeout
|
||||||
|
t 2.600 4.600 pelm,unicode,9 death timeout
|
||||||
|
t 2.920 7.370 pelm,unicode,9 death timeout
|
||||||
|
t 6.030 3.820 pelm,unicode,9 death timeout
|
||||||
|
l 1.670 2.810 2.930 2.810
|
||||||
|
t 2.300 2.600 pelm,unicode,9 snd(sync(id0, rid0))
|
||||||
|
s 4 3.338 3.431 2.600 3.300 2.300 3.300 2.300 3.140
|
||||||
|
l 3.100 2.900 3.472 3.272 S >
|
||||||
|
s 4 4.533 3.438 4.800 3.400 5.100 3.300 5.090 3.100
|
||||||
|
l 4.200 2.900 4.133 3.128 S >
|
||||||
|
t 5.800 9.000 pelm,unicode,9 rexmit timeout
|
||||||
|
l 5.000 8.900 6.500 8.900
|
||||||
|
s 4 4.348 8.964 4.700 9.300 5.500 9.300 5.400 9.280
|
||||||
|
s 3 5.600 8.600 5.300 8.400 4.900 8.500
|
||||||
|
l 4.900 8.500 4.614 8.559 S >
|
||||||
|
l 5.300 3.700 6.700 3.700
|
||||||
|
t 3.600 6.400 pelm,unicode,9 rexmit timeout
|
||||||
|
t 3.500 6.200 pelm,unicode,9 rcv(state(-, -))
|
||||||
|
l 2.690 6.110 4.310 6.110
|
||||||
|
t 3.500 5.700 pelm,unicode,9 rcvd))
|
||||||
|
a 4.000 6.600 4.600 6.800 4.803 6.466 S <
|
||||||
|
a 4.766 5.802 4.400 5.500 4.000 5.800 S <
|
||||||
|
c 5.400 6.100 0.700
|
||||||
|
a 6.072 6.298 6.300 6.300 6.500 6.400 S <
|
||||||
|
s 4 6.098 6.150 7.300 6.200 7.600 6.100 7.700 5.900
|
||||||
|
s 4 4.562 4.106 6.300 5.500 7.200 5.700 7.500 5.700
|
||||||
|
s 5 4.617 8.255 7.600 8.200 8.500 8.100 8.800 7.400 8.600 6.100
|
||||||
|
l 8.600 5.440 7.779 2.845
|
||||||
|
t 3.500 5.900 pelm,unicode,9 snd(dataquery(unacked,
|
||||||
|
l 6.300 6.700 8.000 6.700
|
||||||
|
t 7.300 6.510 pelm,unicode,9 snd(state(next, rcvd))
|
||||||
|
t 7.200 7.000 pelm,unicode,9 rcv(dataquery(-,-))
|
||||||
|
t 7.200 6.800 pelm,unicode,9 rcv(query(-,-))
|
||||||
|
t 3.700 1.400 pelm,unicode,9 death timeout
|
||||||
|
l 7.500 5.700 7.600 5.700 S >
|
||||||
|
l 7.700 5.900 7.750 5.840 S >
|
||||||
|
l 8.600 6.100 8.590 6.020 S >
|
||||||
|
t 1.600 4.200 pelm,unicode,9 see message with
|
||||||
|
s 3 5.528 6.788 5.800 7.650 5.990 7.760
|
||||||
|
l 5.990 7.760 6.180 7.800 S >
|
||||||
|
l 5.825 6.656 6.210 6.910 S >
|
||||||
|
t 6.880 7.840 pelm,unicode,9 User Send
|
||||||
|
l 6.475 7.750 7.285 7.750
|
||||||
|
t 7.110 7.590 pelm,unicode,9 snd(data(next, rcvd))
|
||||||
|
s 4 6.360 7.480 6.210 7.290 5.900 7.230 5.740 6.900
|
||||||
|
l 5.740 6.900 5.657 6.751 S >
|
||||||
|
t 1.920 7.940 pelm,unicode,9 snd(sync(id0, 0))
|
||||||
|
t 5.750 8.720 pelm,unicode,9 snd(sync(id0, 0))
|
||||||
|
l 5.810 4.120 5.820 3.980 S >
|
||||||
|
l 2.300 3.140 2.300 2.990 S >
|
||||||
|
l 5.090 3.100 5.090 2.940 S >
|
||||||
|
l 5.400 9.280 5.520 9.210 S >
|
||||||
|
t 2.700 5.000 pelm,unicode,9 rcv(sync(-, !0))
|
||||||
|
t 2.740 5.200 pelm,unicode,9 rcv(sync(!rid0, -))
|
||||||
|
a 7.960 1.110 7.970 1.490 7.797 1.739 S <
|
||||||
|
a 7.210 1.090 7.160 1.230 7.134 1.457 S >
|
||||||
|
t 7.490 0.850 pelm,unicode,9 rexmit timeout
|
||||||
|
l 6.860 0.760 8.120 0.760
|
||||||
|
t 7.490 0.630 pelm,unicode,9 snd(close(next, rcvd))
|
||||||
|
l 3.115 1.310 4.285 1.310
|
||||||
|
t 3.700 1.220 pelm,unicode,9 no msg
|
||||||
|
l 2.920 0.800 4.620 0.800
|
||||||
|
t 3.790 0.670 pelm,unicode,9 snd(close(next, rcvd))
|
601
sys/doc/il/transition.fig
Normal file
601
sys/doc/il/transition.fig
Normal file
|
@ -0,0 +1,601 @@
|
||||||
|
.lf 1 transition.pic
|
||||||
|
... 0.34125 1.17 8.85 9.28069
|
||||||
|
... 0.000i 5.243i 5.500i 0.000i
|
||||||
|
.nr 00 \n(.u
|
||||||
|
.nf
|
||||||
|
.PS 5.243i 5.500i 5.5i
|
||||||
|
.lf 253
|
||||||
|
\h'0.232i'\v'2.056i'\D'c0.905i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.869i'\v'3.543i'\D'c0.905i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.869i'\v'0.569i'\D'c0.905i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.684i'\v'2.056i'\v'.2m'\h'-\w'Closed'u/2u'Closed
|
||||||
|
.sp -1
|
||||||
|
\h'2.321i'\v'0.569i'\v'.2m'\h'-\w'Syncer'u/2u'Syncer
|
||||||
|
.sp -1
|
||||||
|
\h'2.322i'\v'3.543i'\v'.2m'\h'-\w'Syncee'u/2u'Syncee
|
||||||
|
.sp -1
|
||||||
|
\h'3.270i'\v'2.056i'\v'.2m'\h'-\w'Established'u/2u'Established
|
||||||
|
.sp -1
|
||||||
|
\h'1.837i'\v'0.404i'\D'l0.066i -0.008i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.841i'\v'0.372i'\D'l0.062i 0.024i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.903i'\v'0.396i'\D'a-0.170i 1.107i -0.673i -0.895i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.682i'\v'1.011i'\D'l0.028i -0.061i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.657i'\v'0.991i'\D'l0.053i -0.040i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.710i'\v'0.951i'\D'a0.552i 0.483i -0.709i 0.189i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.395i'\v'1.539i'\D'l-0.329i 0.275i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.106i'\v'1.760i'\D'l-0.039i 0.054i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.126i'\v'1.785i'\D'l-0.060i 0.029i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.525i'\v'2.767i'\v'.2m'\h'-\w'rcv((Ilsync(rid0, !0))'u/2u'rcv((Ilsync(rid0, !0))
|
||||||
|
.sp -1
|
||||||
|
\h'1.025i'\v'2.443i'\D'l-0.058i -0.033i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.002i'\v'2.466i'\D'l-0.035i -0.056i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.967i'\v'2.410i'\D'l0.170i 0.164i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.697i'\v'0.770i'\D'l0.646i 0.000i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.020i'\v'0.867i'\v'.2m'\h'-\w'snd(Ilsync(id0, 0))'u/2u'snd(Ilsync(id0, 0))
|
||||||
|
.sp -1
|
||||||
|
\h'1.008i'\v'0.699i'\v'.2m'\h'-\w'User Open'u/2u'User Open
|
||||||
|
.sp -1
|
||||||
|
\h'0.603i'\v'2.501i'\D'a0.929i 0.303i -0.912i 0.350i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.583i'\v'3.099i'\D'l0.036i 0.056i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.614i'\v'3.088i'\D'l0.006i 0.066i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.814i'\v'3.472i'\D'a0.710i -0.787i 0.366i 0.995i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.834i'\v'3.715i'\D'l0.056i -0.036i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.823i'\v'3.684i'\D'l0.066i -0.005i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.684i'\v'3.413i'\v'.2m'\h'-\w'no connection'u/2u'no connection
|
||||||
|
.sp -1
|
||||||
|
\h'3.006i'\v'2.502i'\D'l0.024i -0.062i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.979i'\v'2.483i'\D'l0.050i -0.044i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.029i'\v'2.439i'\D'l-0.180i 0.257i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.729i'\v'2.959i'\D'l0.024i -0.062i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.703i'\v'2.940i'\D'l0.050i -0.044i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.753i'\v'2.896i'\D'l-0.186i 0.266i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.960i'\v'1.640i'\D'l0.045i 0.049i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.989i'\v'1.624i'\D'l0.017i 0.064i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.006i'\v'1.689i'\D'l-0.188i -0.344i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.708i'\v'1.166i'\D'l0.045i 0.049i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.737i'\v'1.151i'\D'l0.016i 0.065i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.753i'\v'1.216i'\D'l-0.154i -0.290i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.658i'\v'3.782i'\D'l0.007i 0.106i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.665i'\v'3.887i'\D'l-0.011i 0.113i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.654i'\v'4.000i'\D'l-0.029i 0.120i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.624i'\v'4.121i'\D'l-0.047i 0.128i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.577i'\v'4.249i'\D'l-0.032i 0.065i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.545i'\v'4.314i'\D'l-0.039i 0.062i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.506i'\v'4.376i'\D'l-0.047i 0.060i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.459i'\v'4.436i'\D'l-0.054i 0.057i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.404i'\v'4.493i'\D'l-0.062i 0.055i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.343i'\v'4.548i'\D'l-0.069i 0.053i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.274i'\v'4.600i'\D'l-0.077i 0.050i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.197i'\v'4.650i'\D'l-0.084i 0.048i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.113i'\v'4.698i'\D'l-0.091i 0.044i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.022i'\v'4.742i'\D'l-0.099i 0.038i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.923i'\v'4.780i'\D'l-0.106i 0.032i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.816i'\v'4.812i'\D'l-0.114i 0.027i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.702i'\v'4.839i'\D'l-0.122i 0.021i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.581i'\v'4.860i'\D'l-0.129i 0.016i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.452i'\v'4.876i'\D'l-0.137i 0.010i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.315i'\v'4.886i'\D'l-0.144i 0.004i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.171i'\v'4.890i'\D'l-0.290i -0.004i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.881i'\v'4.887i'\D'l-0.280i -0.018i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.601i'\v'4.869i'\D'l-0.269i -0.032i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.332i'\v'4.837i'\D'l-0.258i -0.046i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.074i'\v'4.792i'\D'l-0.121i -0.031i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.953i'\v'4.761i'\D'l-0.111i -0.041i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.842i'\v'4.720i'\D'l-0.100i -0.051i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.742i'\v'4.669i'\D'l-0.090i -0.061i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.652i'\v'4.608i'\D'l-0.079i -0.070i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.572i'\v'4.538i'\D'l-0.069i -0.080i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.503i'\v'4.458i'\D'l-0.058i -0.090i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.445i'\v'4.368i'\D'l-0.048i -0.100i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.397i'\v'4.268i'\D'l-0.040i -0.106i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.357i'\v'4.162i'\D'l-0.034i -0.108i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.323i'\v'4.054i'\D'l-0.028i -0.111i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.295i'\v'3.943i'\D'l-0.022i -0.113i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.274i'\v'3.830i'\D'l-0.016i -0.116i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.258i'\v'3.714i'\D'l-0.010i -0.118i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.248i'\v'3.596i'\D'l-0.004i -0.121i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.244i'\v'3.475i'\D'l0.002i -0.123i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.246i'\v'3.352i'\D'l0.016i -0.239i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.263i'\v'3.113i'\D'l0.028i -0.218i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.290i'\v'2.895i'\D'l0.039i -0.197i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.330i'\v'2.698i'\D'l0.051i -0.177i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.000i'\v'4.609i'\D'c0.905i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.151i'\v'2.269i'\v'.2m'\h'-\w'User Close'u/2u'User Close
|
||||||
|
.sp -1
|
||||||
|
\h'4.789i'\v'2.315i'\D'l0.711i 0.000i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.338i'\v'2.424i'\v'.2m'\h'-\w'snd(Ilclose(next, rcvd))'u/2u'snd(Ilclose(next, rcvd))
|
||||||
|
.sp -1
|
||||||
|
\h'4.453i'\v'2.793i'\D'a-0.704i -0.000i -0.028i -0.704i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.554i'\v'2.386i'\D'l0.039i 0.072i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.593i'\v'2.458i'\D'l0.024i 0.074i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.617i'\v'2.532i'\D'l0.008i 0.077i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.625i'\v'2.609i'\D'l-0.008i 0.079i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.617i'\v'2.688i'\D'l-0.036i 0.165i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.582i'\v'2.853i'\D'l-0.045i 0.175i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.537i'\v'3.027i'\D'l-0.018i 0.090i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.518i'\v'3.117i'\D'l-0.005i 0.090i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.513i'\v'3.207i'\D'l0.008i 0.090i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.521i'\v'3.297i'\D'l0.021i 0.090i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.808i'\v'4.160i'\D'l-0.069i 0.099i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.763i'\v'4.197i'\D'l-0.024i 0.062i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.789i'\v'4.215i'\D'l-0.050i 0.044i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.466i'\v'3.232i'\D'l0.000i 0.892i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.450i'\v'4.060i'\D'l0.016i 0.065i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.482i'\v'4.060i'\D'l-0.016i 0.065i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.245i'\v'2.366i'\D'l0.046i -0.087i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.275i'\v'2.344i'\D'l0.016i -0.065i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.246i'\v'2.329i'\D'l0.044i -0.050i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.381i'\v'2.521i'\D'l0.036i -0.100i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.410i'\v'2.487i'\D'l0.007i -0.066i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.380i'\v'2.476i'\D'l0.037i -0.055i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.654i'\v'1.338i'\v'.2m'\h'-\w'rcv(Ilack(-, !id0))'u/2u'rcv(Ilack(-, !id0))
|
||||||
|
.sp -1
|
||||||
|
\h'1.654i'\v'1.474i'\v'.2m'\h'-\w'rcv(Ilclose(-, id0)'u/2u'rcv(Ilclose(-, id0)
|
||||||
|
.sp -1
|
||||||
|
\h'2.882i'\v'1.280i'\v'.2m'\h'-\w'rcv(ilsync(-, id0))'u/2u'rcv(ilsync(-, id0))
|
||||||
|
.sp -1
|
||||||
|
\h'2.817i'\v'2.767i'\v'.2m'\h'-\w'rcv(Ilack(-, id0))'u/2u'rcv(Ilack(-, id0))
|
||||||
|
.sp -1
|
||||||
|
\h'3.632i'\v'3.013i'\D'l1.280i 0.000i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.265i'\v'3.155i'\v'.2m'\h'-\w'snd(Ilclose(next, rcvd))'u/2u'snd(Ilclose(next, rcvd))
|
||||||
|
.sp -1
|
||||||
|
\h'4.272i'\v'2.954i'\v'.2m'\h'-\w'rcv(Ilclose(-, ackok))'u/2u'rcv(Ilclose(-, ackok))
|
||||||
|
.sp -1
|
||||||
|
\h'3.722i'\v'3.672i'\v'.2m'\h'-\w'rcv(Ilsync(!rid0, -))'u/2u'rcv(Ilsync(!rid0, -))
|
||||||
|
.sp -1
|
||||||
|
\h'1.551i'\v'2.638i'\v'.2m'\h'-\w'rcv(Ilack(!rid0, -))'u/2u'rcv(Ilack(!rid0, -))
|
||||||
|
.sp -1
|
||||||
|
\h'4.453i'\v'4.609i'\v'.2m'\h'-\w'Closing'u/2u'Closing
|
||||||
|
.sp -1
|
||||||
|
\h'1.929i'\v'3.318i'\D'l-0.266i -0.235i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.723i'\v'3.114i'\D'l-0.059i -0.031i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.701i'\v'3.139i'\D'l-0.038i -0.055i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.042i'\v'0.925i'\D'l-0.259i 0.226i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.821i'\v'1.096i'\D'l-0.038i 0.055i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.843i'\v'1.121i'\D'l-0.059i 0.030i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.171i'\v'5.223i'\v'.2m'\h'-\w'rcv(Ilclose(-, next))'u/2u'rcv(Ilclose(-, next))
|
||||||
|
.sp -1
|
||||||
|
\h'2.947i'\v'5.208i'\D'l-0.065i 0.015i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.946i'\v'5.240i'\D'l-0.064i -0.017i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.882i'\v'5.223i'\D'a0.063i -2.080i 1.145i 1.738i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.486i'\v'5.243i'\D'l-0.337i -0.015i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.149i'\v'5.227i'\D'l-0.339i -0.027i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.810i'\v'5.201i'\D'l-0.083i -0.012i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.728i'\v'5.189i'\D'l-0.079i -0.019i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.649i'\v'5.170i'\D'l-0.074i -0.026i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.575i'\v'5.144i'\D'l-0.070i -0.033i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.504i'\v'5.111i'\D'l-0.066i -0.040i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.438i'\v'5.071i'\D'l-0.062i -0.048i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.376i'\v'5.023i'\D'l-0.058i -0.055i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.318i'\v'4.968i'\D'l-0.054i -0.062i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.264i'\v'4.907i'\D'l-0.049i -0.069i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.215i'\v'4.838i'\D'l-0.044i -0.076i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.171i'\v'4.762i'\D'l-0.039i -0.082i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.132i'\v'4.680i'\D'l-0.034i -0.089i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.099i'\v'4.590i'\D'l-0.029i -0.096i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.070i'\v'4.494i'\D'l-0.023i -0.103i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.047i'\v'4.391i'\D'l-0.018i -0.110i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.028i'\v'4.281i'\D'l-0.013i -0.117i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.015i'\v'4.165i'\D'l-0.014i -0.238i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.001i'\v'3.927i'\D'l-0.001i -0.235i'
|
||||||
|
.sp -1
|
||||||
|
\v'3.692i'\D'l0.012i -0.231i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.012i'\v'3.460i'\D'l0.026i -0.228i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.038i'\v'3.232i'\D'l0.037i -0.224i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.075i'\v'3.009i'\D'l0.047i -0.219i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.122i'\v'2.790i'\D'l0.057i -0.214i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.179i'\v'2.576i'\D'l0.066i -0.209i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.512i'\v'2.890i'\v'.2m'\h'-\w'rcv(Ilclose(-, id0))'u/2u'rcv(Ilclose(-, id0))
|
||||||
|
.sp -1
|
||||||
|
\h'2.788i'\v'4.199i'\v'.2m'\h'-\w'rcv(Ilsync(rid0, 0))'u/2u'rcv(Ilsync(rid0, 0))
|
||||||
|
.sp -1
|
||||||
|
\h'2.174i'\v'4.251i'\D'l1.196i 0.006i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.756i'\v'4.380i'\v'.2m'\h'-\w'snd(Ilsync(id0, rid0))'u/2u'snd(Ilsync(id0, rid0))
|
||||||
|
.sp -1
|
||||||
|
\h'1.266i'\v'4.124i'\v'.2m'\h'-\w'rexmit timeout'u/2u'rexmit timeout
|
||||||
|
.sp -1
|
||||||
|
\h'1.460i'\v'3.026i'\v'.2m'\h'-\w'death timeout'u/2u'death timeout
|
||||||
|
.sp -1
|
||||||
|
\h'1.667i'\v'1.235i'\v'.2m'\h'-\w'death timeout'u/2u'death timeout
|
||||||
|
.sp -1
|
||||||
|
\h'3.677i'\v'3.530i'\v'.2m'\h'-\w'death timeout'u/2u'death timeout
|
||||||
|
.sp -1
|
||||||
|
\h'0.859i'\v'4.183i'\D'l0.814i 0.000i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.266i'\v'4.318i'\v'.2m'\h'-\w'snd(Ilsync(id0, rid0))'u/2u'snd(Ilsync(id0, rid0))
|
||||||
|
.sp -1
|
||||||
|
\h'1.937i'\v'3.781i'\D'l-0.221i 0.037i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.716i'\v'3.818i'\D'l-0.185i 0.026i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.531i'\v'3.845i'\D'l-0.076i 0.012i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.454i'\v'3.857i'\D'l-0.062i 0.016i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.393i'\v'3.873i'\D'l-0.047i 0.020i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.346i'\v'3.893i'\D'l-0.032i 0.023i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.315i'\v'3.916i'\D'l-0.021i 0.028i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.293i'\v'3.944i'\D'l-0.015i 0.034i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.278i'\v'3.979i'\D'l-0.009i 0.041i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.269i'\v'4.019i'\D'l-0.003i 0.047i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.783i'\v'4.124i'\D'l0.240i -0.240i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.989i'\v'3.941i'\D'l0.034i -0.057i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.967i'\v'3.918i'\D'l0.057i -0.034i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.710i'\v'3.777i'\D'l0.178i 0.035i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.887i'\v'3.811i'\D'l0.043i 0.014i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.931i'\v'3.825i'\D'l0.038i 0.019i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.968i'\v'3.844i'\D'l0.032i 0.024i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.001i'\v'3.869i'\D'l0.027i 0.030i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.028i'\v'3.898i'\D'l0.021i 0.034i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.049i'\v'3.933i'\D'l0.015i 0.038i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.064i'\v'3.971i'\D'l0.009i 0.042i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.073i'\v'4.013i'\D'l0.003i 0.046i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.494i'\v'4.124i'\D'l-0.043i -0.147i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.485i'\v'4.035i'\D'l-0.034i -0.057i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.454i'\v'4.044i'\D'l-0.003i -0.067i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.529i'\v'0.375i'\v'.2m'\h'-\w'snd(Ilsync(id0, 0))'u/2u'snd(Ilsync(id0, 0))
|
||||||
|
.sp -1
|
||||||
|
\h'3.529i'\v'0.181i'\v'.2m'\h'-\w'rexmit timeout'u/2u'rexmit timeout
|
||||||
|
.sp -1
|
||||||
|
\h'3.011i'\v'0.246i'\D'l0.970i 0.000i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.590i'\v'0.205i'\D'l0.061i -0.051i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.651i'\v'0.154i'\D'l0.070i -0.044i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.722i'\v'0.110i'\D'l0.080i -0.037i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.801i'\v'0.072i'\D'l0.089i -0.031i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.890i'\v'0.042i'\D'l0.090i -0.023i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.979i'\v'0.019i'\D'l0.082i -0.014i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.062i'\v'0.005i'\D'l0.075i -0.005i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.137i'\D'l0.068i 0.004i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.205i'\v'0.004i'\D'l0.057i 0.009i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.262i'\v'0.013i'\D'l0.040i 0.011i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.302i'\v'0.024i'\D'l0.024i 0.013i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.327i'\v'0.037i'\D'l0.008i 0.015i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.399i'\v'0.440i'\D'l-0.049i 0.029i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.350i'\v'0.469i'\D'l-0.052i 0.023i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.298i'\v'0.493i'\D'l-0.054i 0.017i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.245i'\v'0.510i'\D'l-0.056i 0.011i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.189i'\v'0.521i'\D'l-0.058i 0.005i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.132i'\v'0.526i'\D'l-0.060i -0.001i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.072i'\v'0.525i'\D'l-0.062i -0.007i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.010i'\v'0.518i'\D'l-0.064i -0.013i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.947i'\v'0.505i'\D'l-0.185i -0.038i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.828i'\v'0.464i'\D'l-0.067i 0.003i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.822i'\v'0.495i'\D'l-0.060i -0.029i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.205i'\v'3.607i'\D'l0.905i 0.000i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.106i'\v'1.862i'\v'.2m'\h'-\w'rexmit timeout'u/2u'rexmit timeout
|
||||||
|
.sp -1
|
||||||
|
\h'2.042i'\v'1.991i'\v'.2m'\h'-\w'rcv(Ilstate(-, -))'u/2u'rcv(Ilstate(-, -))
|
||||||
|
.sp -1
|
||||||
|
\h'1.518i'\v'2.050i'\D'l1.047i 0.000i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.042i'\v'2.315i'\v'.2m'\h'-\w'rcvd))'u/2u'rcvd))
|
||||||
|
.sp -1
|
||||||
|
\h'2.884i'\v'1.819i'\D'a-0.269i 0.016i -0.250i -0.103i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.382i'\v'1.668i'\D'l-0.017i 0.064i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.411i'\v'1.684i'\D'l-0.046i 0.049i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.365i'\v'2.250i'\D'a0.247i -0.061i 0.248i 0.059i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.852i'\v'2.315i'\D'l0.008i -0.066i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.822i'\v'2.303i'\D'l0.038i -0.055i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.817i'\v'2.056i'\D'c0.905i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.721i'\v'1.464i'\D'l0.066i 0.010i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.734i'\v'1.434i'\D'l0.053i 0.040i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.787i'\v'1.474i'\D'a-0.097i 0.147i -0.165i 0.061i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.770i'\v'1.920i'\D'l-0.066i 0.008i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.767i'\v'1.952i'\D'l-0.062i -0.024i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.704i'\v'1.928i'\D'a0.071i -0.316i 0.206i 0.250i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.721i'\v'2.024i'\D'l0.352i -0.010i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.073i'\v'2.014i'\D'l0.279i 0.002i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.352i'\v'2.016i'\D'l0.110i 0.007i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.463i'\v'2.022i'\D'l0.088i 0.012i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.551i'\v'2.034i'\D'l0.066i 0.017i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.616i'\v'2.050i'\D'l0.043i 0.022i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.660i'\v'2.072i'\D'l0.057i 0.053i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.716i'\v'2.125i'\D'l0.040i 0.061i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.728i'\v'3.345i'\D'l0.272i -0.213i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.001i'\v'3.132i'\D'l0.255i -0.189i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.256i'\v'2.943i'\D'l0.239i -0.165i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.495i'\v'2.778i'\D'l0.222i -0.141i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.716i'\v'2.637i'\D'l0.199i -0.115i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.915i'\v'2.522i'\D'l0.170i -0.087i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.084i'\v'2.435i'\D'l0.141i -0.058i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.225i'\v'2.377i'\D'l0.059i -0.019i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.284i'\v'2.358i'\D'l0.052i -0.012i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.336i'\v'2.347i'\D'l0.170i -0.024i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.506i'\v'2.323i'\D'l0.121i -0.008i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.764i'\v'0.663i'\D'l0.880i 0.020i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.644i'\v'0.683i'\D'l0.712i 0.023i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.355i'\v'0.706i'\D'l0.287i 0.019i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.642i'\v'0.725i'\D'l0.123i 0.014i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.765i'\v'0.739i'\D'l0.109i 0.018i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.874i'\v'0.757i'\D'l0.096i 0.021i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.970i'\v'0.778i'\D'l0.082i 0.024i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.053i'\v'0.802i'\D'l0.069i 0.027i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.122i'\v'0.829i'\D'l0.055i 0.031i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.177i'\v'0.860i'\D'l0.046i 0.035i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.223i'\v'0.896i'\D'l0.040i 0.041i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.263i'\v'0.937i'\D'l0.035i 0.047i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.297i'\v'0.984i'\D'l0.029i 0.054i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.326i'\v'1.038i'\D'l0.023i 0.060i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.350i'\v'1.097i'\D'l0.018i 0.066i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.368i'\v'1.163i'\D'l0.012i 0.072i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.380i'\v'1.235i'\D'l0.007i 0.078i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.387i'\v'1.313i'\D'l0.003i 0.168i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.390i'\v'1.480i'\D'l-0.007i 0.180i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.383i'\v'1.660i'\D'l-0.017i 0.192i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.366i'\v'1.852i'\D'l-0.027i 0.204i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.338i'\v'2.483i'\D'l-0.531i 1.677i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.042i'\v'2.185i'\v'.2m'\h'-\w'snd(Ildataquerey(unacked,'u/2u'snd(Ildataquerey(unacked,
|
||||||
|
.sp -1
|
||||||
|
\h'3.852i'\v'1.668i'\D'l1.099i 0.000i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.498i'\v'1.791i'\v'.2m'\h'-\w'snd(Ilstate(next, rcvd))'u/2u'snd(Ilstate(next, rcvd))
|
||||||
|
.sp -1
|
||||||
|
\h'4.433i'\v'1.474i'\v'.2m'\h'-\w'rcv(Ildataquerey(-,-))'u/2u'rcv(Ildataquerey(-,-))
|
||||||
|
.sp -1
|
||||||
|
\h'4.433i'\v'1.604i'\v'.2m'\h'-\w'rcv(Ilquerey(-,-))'u/2u'rcv(Ilquerey(-,-))
|
||||||
|
.sp -1
|
||||||
|
\h'2.171i'\v'5.094i'\v'.2m'\h'-\w'death timeout'u/2u'death timeout
|
||||||
|
.sp -1
|
||||||
|
\h'4.627i'\v'2.315i'\D'l0.065i 0.000i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.627i'\v'2.331i'\D'l0.065i -0.016i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.627i'\v'2.298i'\D'l0.065i 0.016i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.757i'\v'2.185i'\D'l0.032i 0.039i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.735i'\v'2.185i'\D'l0.054i 0.039i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.760i'\v'2.164i'\D'l0.029i 0.060i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.338i'\v'2.056i'\D'l-0.006i 0.052i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.324i'\v'2.042i'\D'l0.008i 0.066i'
|
||||||
|
.sp -1
|
||||||
|
\h'5.356i'\v'2.046i'\D'l-0.024i 0.062i'
|
||||||
|
.sp -1
|
||||||
|
\h'0.814i'\v'3.284i'\v'.2m'\h'-\w'see message with'u/2u'see message with
|
||||||
|
.sp -1
|
||||||
|
.sp 1+5.243i
|
||||||
|
.PE
|
||||||
|
.if \n(00 .fi
|
||||||
|
.lf 253
|
282
sys/doc/il/transition.pic
Normal file
282
sys/doc/il/transition.pic
Normal file
|
@ -0,0 +1,282 @@
|
||||||
|
.PS
|
||||||
|
define grp0 {[
|
||||||
|
"User Close" at (7.16,7.97);
|
||||||
|
line from (6.6,7.9) to (7.7,7.9);
|
||||||
|
"snd(close(next, rcvd))" at (7.45,7.73);
|
||||||
|
]}
|
||||||
|
define grp1 {[
|
||||||
|
grp2() with (0,0) at (0.04,0.305);
|
||||||
|
]}
|
||||||
|
define grp2 {[
|
||||||
|
"rcv(sync(rid0, 0))" at (3.95,2.38);
|
||||||
|
line from (3,2.3) to (4.85,2.29);
|
||||||
|
"snd(sync(id0, rid0))" at (3.9,2.1);
|
||||||
|
]}
|
||||||
|
circle at (1.4,6.1) rad 0.7;
|
||||||
|
circle at (3.933,3.799) rad 0.7;
|
||||||
|
circle at (3.932,8.401) rad 0.7;
|
||||||
|
"Closed" at (1.4,6.1);
|
||||||
|
"Syncer" at (3.932,8.401);
|
||||||
|
"Syncee" at (3.933,3.799);
|
||||||
|
"Established" at (5.4,6.1);
|
||||||
|
arc <- ccw from (3.285,8.668) to (1.98,8.34) rad 1.73202;
|
||||||
|
arc <- ccw from (1.44,7.81) to (1.197,6.77) rad 1.13475;
|
||||||
|
line -> from (2.5,6.9) to (1.991,6.475);
|
||||||
|
line <- from (1.837,5.553) to (2.1,5.3);
|
||||||
|
line from (1.42,8.09) to (2.42,8.09);
|
||||||
|
"User Open" at (1.9,8.2);
|
||||||
|
arc <- cw from (1.3,4.4) to (1.274,5.411) rad 1.51113;
|
||||||
|
arc <- cw from (3.265,3.589) to (1.6,3.91) rad 1.64006;
|
||||||
|
"no connection" at (1.4,4);
|
||||||
|
line <- from (5.028,5.507) to (4.75,5.11);
|
||||||
|
line <- from (4.6,4.8) to (4.312,4.388);
|
||||||
|
line <- from (4.991,6.668) to (4.7,7.2);
|
||||||
|
line <- from (4.6,7.4) to (4.361,7.848);
|
||||||
|
line from (6,3.43) to (6.01094,3.26672)
|
||||||
|
line from (6.01094,3.26672) to (5.99375,3.09187)
|
||||||
|
line from (5.99375,3.09187) to (5.94844,2.90547)
|
||||||
|
line from (5.94844,2.90547) to (5.875,2.7075)
|
||||||
|
line from (5.875,2.7075) to (5.82551,2.6075)
|
||||||
|
line from (5.82551,2.6075) to (5.76453,2.51125)
|
||||||
|
line from (5.76453,2.51125) to (5.69207,2.41875)
|
||||||
|
line from (5.69207,2.41875) to (5.60812,2.33)
|
||||||
|
line from (5.60812,2.33) to (5.5127,2.245)
|
||||||
|
line from (5.5127,2.245) to (5.40578,2.16375)
|
||||||
|
line from (5.40578,2.16375) to (5.28738,2.08625)
|
||||||
|
line from (5.28738,2.08625) to (5.1575,2.0125)
|
||||||
|
line from (5.1575,2.0125) to (5.01605,1.94496)
|
||||||
|
line from (5.01605,1.94496) to (4.86297,1.88609)
|
||||||
|
line from (4.86297,1.88609) to (4.69824,1.8359)
|
||||||
|
line from (4.69824,1.8359) to (4.52188,1.79438)
|
||||||
|
line from (4.52188,1.79438) to (4.33387,1.76152)
|
||||||
|
line from (4.33387,1.76152) to (4.13422,1.73734)
|
||||||
|
line from (4.13422,1.73734) to (3.92293,1.72184)
|
||||||
|
line from (3.92293,1.72184) to (3.7,1.715)
|
||||||
|
line from (3.7,1.715) to (3.25078,1.72078)
|
||||||
|
line from (3.25078,1.72078) to (2.81813,1.74812)
|
||||||
|
line from (2.81813,1.74812) to (2.40203,1.79703)
|
||||||
|
line from (2.40203,1.79703) to (2.0025,1.8675)
|
||||||
|
line from (2.0025,1.8675) to (1.81496,1.9157)
|
||||||
|
line from (1.81496,1.9157) to (1.64359,1.97906)
|
||||||
|
line from (1.64359,1.97906) to (1.4884,2.05758)
|
||||||
|
line from (1.4884,2.05758) to (1.34937,2.15125)
|
||||||
|
line from (1.34937,2.15125) to (1.22652,2.26008)
|
||||||
|
line from (1.22652,2.26008) to (1.11984,2.38406)
|
||||||
|
line from (1.11984,2.38406) to (1.02934,2.5232)
|
||||||
|
line from (1.02934,2.5232) to (0.955,2.6775)
|
||||||
|
line from (0.955,2.6775) to (0.893398,2.84129)
|
||||||
|
line from (0.893398,2.84129) to (0.841094,3.00891)
|
||||||
|
line from (0.841094,3.00891) to (0.798086,3.18035)
|
||||||
|
line from (0.798086,3.18035) to (0.764375,3.35562)
|
||||||
|
line from (0.764375,3.35562) to (0.739961,3.53473)
|
||||||
|
line from (0.739961,3.53473) to (0.724844,3.71766)
|
||||||
|
line from (0.724844,3.71766) to (0.719023,3.90441)
|
||||||
|
line from (0.719023,3.90441) to (0.7225,4.095)
|
||||||
|
line from (0.7225,4.095) to (0.747656,4.46406)
|
||||||
|
line from (0.747656,4.46406) to (0.790625,4.80125)
|
||||||
|
line from (0.790625,4.80125) to (0.851406,5.10656)
|
||||||
|
line from (0.851406,5.10656) to (0.93,5.38)
|
||||||
|
circle at (7.23,2.15) rad 0.7;
|
||||||
|
grp0() with (0,0) at (1.15,-2.2);
|
||||||
|
arc <- ccw from (7.23,4.96) to (6.098,6.049) rad 1.0893;
|
||||||
|
line from (5.84,5.59) to (5.90047,5.47828)
|
||||||
|
line from (5.90047,5.47828) to (5.93688,5.36313)
|
||||||
|
line from (5.93688,5.36313) to (5.94922,5.24453)
|
||||||
|
line from (5.94922,5.24453) to (5.9375,5.1225)
|
||||||
|
line from (5.9375,5.1225) to (5.88188,4.8725)
|
||||||
|
line from (5.88188,4.8725) to (5.81,4.6175)
|
||||||
|
line from (5.81,4.6175) to (5.78,4.48984)
|
||||||
|
line from (5.78,4.48984) to (5.77,4.36437)
|
||||||
|
line from (5.77,4.36437) to (5.78,4.24109)
|
||||||
|
line from (5.78,4.24109) to (5.81,4.12)
|
||||||
|
line -> from (7.779,2.845) to (7.673,2.692);
|
||||||
|
line -> from (7.25,4.28) to (7.24,2.85);
|
||||||
|
line -> from (0.72,5.62) to (0.791,5.755);
|
||||||
|
line -> from (0.93,5.38) to (0.986,5.535);
|
||||||
|
"rcv(ack(-, !id0))" at (2.9,7.21);
|
||||||
|
"rcv(close(-, id0)" at (2.9,7);
|
||||||
|
"rcv(sync(-, id0))" at (4.8,7.3);
|
||||||
|
"rcv(ack(-, id0))" at (4.7,5);
|
||||||
|
line from (5.96,4.62) to (7.94,4.62);
|
||||||
|
"snd(close(next, rcvd))" at (6.94,4.4);
|
||||||
|
"rcv(close(-, ackok))" at (6.95,4.71);
|
||||||
|
"rcv(sync(!rid0, -))" at (6.1,3.6);
|
||||||
|
"Closing" at (7.23,2.15);
|
||||||
|
line -> from (3.326,4.147) to (2.915,4.51);
|
||||||
|
line -> from (3.501,7.849) to (3.1,7.5);
|
||||||
|
"rcv(close(-, next))" at (3.8,0.9);
|
||||||
|
arc <- ccw from (4.8,1.2) to (6.67,1.73) rad 3.2198;
|
||||||
|
line from (2.64,1.17) to (2.11875,1.19375)
|
||||||
|
line from (2.11875,1.19375) to (1.595,1.235)
|
||||||
|
line from (1.595,1.235) to (1.46695,1.25305)
|
||||||
|
line from (1.46695,1.25305) to (1.34531,1.28219)
|
||||||
|
line from (1.34531,1.28219) to (1.23008,1.32242)
|
||||||
|
line from (1.23008,1.32242) to (1.12125,1.37375)
|
||||||
|
line from (1.12125,1.37375) to (1.01883,1.43617)
|
||||||
|
line from (1.01883,1.43617) to (0.922813,1.50969)
|
||||||
|
line from (0.922813,1.50969) to (0.833203,1.5943)
|
||||||
|
line from (0.833203,1.5943) to (0.75,1.69)
|
||||||
|
line from (0.75,1.69) to (0.673984,1.79652)
|
||||||
|
line from (0.673984,1.79652) to (0.605938,1.91359)
|
||||||
|
line from (0.605938,1.91359) to (0.545859,2.04121)
|
||||||
|
line from (0.545859,2.04121) to (0.49375,2.17937)
|
||||||
|
line from (0.49375,2.17937) to (0.449609,2.32809)
|
||||||
|
line from (0.449609,2.32809) to (0.413438,2.48734)
|
||||||
|
line from (0.413438,2.48734) to (0.385234,2.65715)
|
||||||
|
line from (0.385234,2.65715) to (0.365,2.8375)
|
||||||
|
line from (0.365,2.8375) to (0.342813,3.20609)
|
||||||
|
line from (0.342813,3.20609) to (0.34125,3.56937)
|
||||||
|
line from (0.34125,3.56937) to (0.360312,3.92734)
|
||||||
|
line from (0.360312,3.92734) to (0.4,4.28)
|
||||||
|
line from (0.4,4.28) to (0.4575,4.62625)
|
||||||
|
line from (0.4575,4.62625) to (0.53,4.965)
|
||||||
|
line from (0.53,4.965) to (0.6175,5.29625)
|
||||||
|
line from (0.6175,5.29625) to (0.72,5.62)
|
||||||
|
"rcv(close(-, id0))" at (2.68,4.81);
|
||||||
|
grp1() with (0,0) at (0.665,0.099);
|
||||||
|
"rexmit timeout" at (2.3,2.9);
|
||||||
|
"death timeout" at (2.6,4.6);
|
||||||
|
"death timeout" at (2.92,7.37);
|
||||||
|
"death timeout" at (6.03,3.82);
|
||||||
|
line from (1.67,2.81) to (2.93,2.81);
|
||||||
|
"snd(sync(id0, rid0))" at (2.3,2.6);
|
||||||
|
line from (3.338,3.431) to (2.99638,3.37369)
|
||||||
|
line from (2.99638,3.37369) to (2.7095,3.33275)
|
||||||
|
line from (2.7095,3.33275) to (2.49613,3.29819)
|
||||||
|
line from (2.49613,3.29819) to (2.42403,3.27955)
|
||||||
|
line from (2.42403,3.27955) to (2.375,3.26)
|
||||||
|
line from (2.375,3.26) to (2.34219,3.2375)
|
||||||
|
line from (2.34219,3.2375) to (2.31875,3.21)
|
||||||
|
line from (2.31875,3.21) to (2.30469,3.1775)
|
||||||
|
line from (2.30469,3.1775) to (2.3,3.14)
|
||||||
|
line -> from (3.1,2.9) to (3.472,3.272);
|
||||||
|
line from (4.533,3.438) to (4.80825,3.3845)
|
||||||
|
line from (4.80825,3.3845) to (4.8748,3.36472)
|
||||||
|
line from (4.8748,3.36472) to (4.93269,3.33987)
|
||||||
|
line from (4.93269,3.33987) to (4.98192,3.30997)
|
||||||
|
line from (4.98192,3.30997) to (5.0225,3.275)
|
||||||
|
line from (5.0225,3.275) to (5.05391,3.23594)
|
||||||
|
line from (5.05391,3.23594) to (5.07563,3.19375)
|
||||||
|
line from (5.07563,3.19375) to (5.08766,3.14844)
|
||||||
|
line from (5.08766,3.14844) to (5.09,3.1)
|
||||||
|
line -> from (4.2,2.9) to (4.133,3.128);
|
||||||
|
"rexmit timeout" at (5.8,9);
|
||||||
|
line from (5,8.9) to (6.5,8.9);
|
||||||
|
line from (4.348,8.964) to (4.443,9.04275)
|
||||||
|
line from (4.443,9.04275) to (4.552,9.111)
|
||||||
|
line from (4.552,9.111) to (4.675,9.16875)
|
||||||
|
line from (4.675,9.16875) to (4.812,9.216)
|
||||||
|
line from (4.812,9.216) to (4.94894,9.25244)
|
||||||
|
line from (4.94894,9.25244) to (5.07175,9.27775)
|
||||||
|
line from (5.07175,9.27775) to (5.18044,9.29194)
|
||||||
|
line from (5.18044,9.29194) to (5.275,9.295)
|
||||||
|
line from (5.275,9.295) to (5.39375,9.28875)
|
||||||
|
line from (5.39375,9.28875) to (5.41094,9.28469)
|
||||||
|
line from (5.41094,9.28469) to (5.4,9.28)
|
||||||
|
line from (5.6,8.6) to (5.52344,8.55469)
|
||||||
|
line from (5.52344,8.55469) to (5.44375,8.51875)
|
||||||
|
line from (5.44375,8.51875) to (5.36094,8.49219)
|
||||||
|
line from (5.36094,8.49219) to (5.275,8.475)
|
||||||
|
line from (5.275,8.475) to (5.18594,8.46719)
|
||||||
|
line from (5.18594,8.46719) to (5.09375,8.46875)
|
||||||
|
line from (5.09375,8.46875) to (4.99844,8.47969)
|
||||||
|
line from (4.99844,8.47969) to (4.9,8.5)
|
||||||
|
line -> from (4.9,8.5) to (4.614,8.559);
|
||||||
|
line from (5.3,3.7) to (6.7,3.7);
|
||||||
|
"rexmit timeout" at (3.6,6.4);
|
||||||
|
"rcv(state(-, -))" at (3.5,6.2);
|
||||||
|
line from (2.69,6.11) to (4.31,6.11);
|
||||||
|
"rcvd))" at (3.5,5.7);
|
||||||
|
arc <- cw from (4,6.6) to (4.803,6.466) rad 0.417517;
|
||||||
|
arc <- cw from (4.766,5.802) to (4,5.8) rad 0.394055;
|
||||||
|
circle at (5.4,6.1) rad 0.7;
|
||||||
|
arc <- ccw from (6.072,6.298) to (6.5,6.4) rad 0.500723;
|
||||||
|
line from (6.098,6.15) to (6.64262,6.16563)
|
||||||
|
line from (6.64262,6.16563) to (7.0745,6.1625)
|
||||||
|
line from (7.0745,6.1625) to (7.24503,6.15234)
|
||||||
|
line from (7.24503,6.15234) to (7.38112,6.13437)
|
||||||
|
line from (7.38112,6.13437) to (7.48278,6.10859)
|
||||||
|
line from (7.48278,6.10859) to (7.55,6.075)
|
||||||
|
line from (7.55,6.075) to (7.6375,5.99375)
|
||||||
|
line from (7.6375,5.99375) to (7.7,5.9)
|
||||||
|
line from (4.562,4.106) to (4.98341,4.43584)
|
||||||
|
line from (4.98341,4.43584) to (5.37862,4.72838)
|
||||||
|
line from (5.37862,4.72838) to (5.74766,4.98359)
|
||||||
|
line from (5.74766,4.98359) to (6.0905,5.2015)
|
||||||
|
line from (6.0905,5.2015) to (6.39778,5.37897)
|
||||||
|
line from (6.39778,5.37897) to (6.66012,5.51288)
|
||||||
|
line from (6.66012,5.51288) to (6.87753,5.60322)
|
||||||
|
line from (6.87753,5.60322) to (6.96938,5.63205)
|
||||||
|
line from (6.96938,5.63205) to (7.05,5.65)
|
||||||
|
line from (7.05,5.65) to (7.3125,5.6875)
|
||||||
|
line from (7.3125,5.6875) to (7.5,5.7)
|
||||||
|
line from (4.617,8.255) to (5.97831,8.22469)
|
||||||
|
line from (5.97831,8.22469) to (7.07925,8.18875)
|
||||||
|
line from (7.07925,8.18875) to (7.5227,8.1593)
|
||||||
|
line from (7.5227,8.1593) to (7.71299,8.13701)
|
||||||
|
line from (7.71299,8.13701) to (7.88231,8.10969)
|
||||||
|
line from (7.88231,8.10969) to (8.03068,8.07732)
|
||||||
|
line from (8.03068,8.07732) to (8.15808,8.03992)
|
||||||
|
line from (8.15808,8.03992) to (8.26452,7.99748)
|
||||||
|
line from (8.26452,7.99748) to (8.35,7.95)
|
||||||
|
line from (8.35,7.95) to (8.4207,7.89531)
|
||||||
|
line from (8.4207,7.89531) to (8.48281,7.83125)
|
||||||
|
line from (8.48281,7.83125) to (8.53633,7.75781)
|
||||||
|
line from (8.53633,7.75781) to (8.58125,7.675)
|
||||||
|
line from (8.58125,7.675) to (8.61758,7.58281)
|
||||||
|
line from (8.61758,7.58281) to (8.64531,7.48125)
|
||||||
|
line from (8.64531,7.48125) to (8.66445,7.37031)
|
||||||
|
line from (8.66445,7.37031) to (8.675,7.25)
|
||||||
|
line from (8.675,7.25) to (8.67969,6.99063)
|
||||||
|
line from (8.67969,6.99063) to (8.66875,6.7125)
|
||||||
|
line from (8.66875,6.7125) to (8.64219,6.41563)
|
||||||
|
line from (8.64219,6.41563) to (8.6,6.1)
|
||||||
|
line from (8.6,5.44) to (7.779,2.845);
|
||||||
|
"snd(dataquery(unacked," at (3.5,5.9);
|
||||||
|
line from (6.3,6.7) to (8,6.7);
|
||||||
|
"snd(state(next, rcvd))" at (7.3,6.51);
|
||||||
|
"rcv(dataquery(-,-))" at (7.2,7);
|
||||||
|
"rcv(query(-,-))" at (7.2,6.8);
|
||||||
|
"death timeout" at (3.7,1.4);
|
||||||
|
line -> from (7.5,5.7) to (7.6,5.7);
|
||||||
|
line -> from (7.7,5.9) to (7.75,5.84);
|
||||||
|
line -> from (8.6,6.1) to (8.59,6.02);
|
||||||
|
"see message with" at (1.6,4.2);
|
||||||
|
line from (5.528,6.788) to (5.65887,7.172)
|
||||||
|
line from (5.65887,7.172) to (5.7795,7.462)
|
||||||
|
line from (5.7795,7.462) to (5.83597,7.57175)
|
||||||
|
line from (5.83597,7.57175) to (5.88987,7.658)
|
||||||
|
line from (5.88987,7.658) to (5.94122,7.72075)
|
||||||
|
line from (5.94122,7.72075) to (5.99,7.76)
|
||||||
|
line -> from (5.99,7.76) to (6.18,7.8);
|
||||||
|
line -> from (5.825,6.656) to (6.21,6.91);
|
||||||
|
"User Send" at (6.88,7.84);
|
||||||
|
line from (6.475,7.75) to (7.285,7.75);
|
||||||
|
"snd(data(next, rcvd))" at (7.11,7.59);
|
||||||
|
line from (6.36,7.48) to (6.275,7.39313)
|
||||||
|
line from (6.275,7.39313) to (6.17,7.3225)
|
||||||
|
line from (6.17,7.3225) to (6.05438,7.25125)
|
||||||
|
line from (6.05438,7.25125) to (5.9375,7.1625)
|
||||||
|
line from (5.9375,7.1625) to (5.88109,7.10953)
|
||||||
|
line from (5.88109,7.10953) to (5.82937,7.04813)
|
||||||
|
line from (5.82937,7.04813) to (5.78234,6.97828)
|
||||||
|
line from (5.78234,6.97828) to (5.74,6.9)
|
||||||
|
line -> from (5.74,6.9) to (5.657,6.751);
|
||||||
|
"snd(sync(id0, 0))" at (1.92,7.94);
|
||||||
|
"snd(sync(id0, 0))" at (5.75,8.72);
|
||||||
|
line -> from (5.81,4.12) to (5.82,3.98);
|
||||||
|
line -> from (2.3,3.14) to (2.3,2.99);
|
||||||
|
line -> from (5.09,3.1) to (5.09,2.94);
|
||||||
|
line -> from (5.4,9.28) to (5.52,9.21);
|
||||||
|
"rcv(sync(-, !0))" at (2.7,5);
|
||||||
|
"rcv(sync(!rid0, -))" at (2.74,5.2);
|
||||||
|
arc <- ccw from (7.96,1.11) to (7.797,1.739) rad 0.548809;
|
||||||
|
arc -> cw from (7.21,1.09) to (7.134,1.457) rad 0.825566;
|
||||||
|
"rexmit timeout" at (7.49,0.85);
|
||||||
|
line from (6.86,0.76) to (8.12,0.76);
|
||||||
|
"snd(close(next, rcvd))" at (7.49,0.63);
|
||||||
|
line from (3.115,1.31) to (4.285,1.31);
|
||||||
|
"no msg" at (3.7,1.22);
|
||||||
|
line from (2.92,0.8) to (4.62,0.8);
|
||||||
|
"snd(close(next, rcvd))" at (3.79,0.67);
|
||||||
|
.PE
|
2854
sys/doc/il/xx
Normal file
2854
sys/doc/il/xx
Normal file
File diff suppressed because it is too large
Load diff
332
sys/doc/index.html
Normal file
332
sys/doc/index.html
Normal file
|
@ -0,0 +1,332 @@
|
||||||
|
<?xml version="1.0" encoding="utf-8"?>
|
||||||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
|
||||||
|
"http://www.w3.org/TR/html4/loose.dtd">
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta http-equiv=Content-Type content="text/html; charset=utf8">
|
||||||
|
<title>Plan 9 — The Documents (Volume 2)</title>
|
||||||
|
</meta>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.05in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.50in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: center;">
|
||||||
|
<span style="font-size: 12pt"></span><span style="font-size: 12pt"><b>Plan 9 — The Documents (Volume 2)</b></span><span style="font-size: 12pt"></span></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.50in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Introduction
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Plan 9 From Bell Labs
|
||||||
|
(<a href="9.html">html</a> |
|
||||||
|
<a href="9.ps">ps</a> |
|
||||||
|
<a href="9.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike, Dave Presotto, Sean Dorward, Bob Flandrena, Ken Thompson, Howard Trickey, and Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An overview of the system; read at least this paper before you install.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Use of Name Spaces in Plan 9
|
||||||
|
(<a href="names.html">html</a> |
|
||||||
|
<a href="names.ps">ps</a> |
|
||||||
|
<a href="names.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike, Dave Presotto, Ken Thompson, Howard Trickey, and Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">What’s in a name?
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Organization of Networks in Plan 9
|
||||||
|
(<a href="net/net.html">html</a> |
|
||||||
|
<a href="net/net.ps">ps</a> |
|
||||||
|
<a href="net/net.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Dave Presotto and Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Connecting the pieces. The details in the paper are outdated but the ideas still apply.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Security in Plan 9
|
||||||
|
(<a href="auth.html">html</a> |
|
||||||
|
<a href="auth.ps">ps</a> |
|
||||||
|
<a href="auth.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Russ Cox, Eric Grosse, Rob Pike, Dave Presotto, and Sean Quinlan
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An overview of the security architecture.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Programming
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">How to Use the Plan 9 C Compiler
|
||||||
|
(<a href="comp.html">html</a> |
|
||||||
|
<a href="comp.ps">ps</a> |
|
||||||
|
<a href="comp.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The starting point for C programming under Plan 9.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Changes to the Programming Environment in the Fourth Release of Plan 9
|
||||||
|
(<a href="prog4.html">html</a> |
|
||||||
|
<a href="prog4.ps">ps</a> |
|
||||||
|
<a href="prog4.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An overview of the changes to the C library since the Third Release.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">APE — The ANSI/POSIX Environment
|
||||||
|
(<a href="ape.html">html</a> |
|
||||||
|
<a href="ape.ps">ps</a> |
|
||||||
|
<a href="ape.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Howard Trickey
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Moving C code between UNIX and Plan 9.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Acid: A Debugger Built From A Language
|
||||||
|
(<a href="acidpaper.html">html</a> |
|
||||||
|
<a href="acidpaper.ps">ps</a> |
|
||||||
|
<a href="acidpaper.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An overview paper about the Acid debugger.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Acid Manual
|
||||||
|
(<a href="acid.html">html</a> |
|
||||||
|
<a href="acid.ps">ps</a> |
|
||||||
|
<a href="acid.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The reference manual for the language and its libraries.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Maintaining Files on Plan 9 with Mk
|
||||||
|
(<a href="mk.html">html</a> |
|
||||||
|
<a href="mk.ps">ps</a> |
|
||||||
|
<a href="mk.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Andrew G. Hume and Bob Flandrena
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An introduction to Plan 9’s replacement for </span><span style="font-size: 10pt"><tt>make</tt></span><span style="font-size: 10pt">.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Plan 9 Mkfiles
|
||||||
|
(<a href="mkfiles.html">html</a> |
|
||||||
|
<a href="mkfiles.ps">ps</a> |
|
||||||
|
<a href="mkfiles.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Bob Flandrena
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The conventions for using </span><span style="font-size: 10pt"><tt>mk</tt></span><span style="font-size: 10pt"> in Plan 9.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A Manual for the Plan 9 assembler
|
||||||
|
(<a href="asm.html">html</a> |
|
||||||
|
<a href="asm.ps">ps</a> |
|
||||||
|
<a href="asm.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Things you’d rather not know.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>User Interfaces
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">8½, the Plan 9 Window System
|
||||||
|
(<a href="8½/8½.html">html</a> |
|
||||||
|
<a href="8½/8½.ps">ps</a> |
|
||||||
|
<a href="8½/8½.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An introduction to the (previous) window system and its unusual implementation.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Rc — The Plan 9 Shell
|
||||||
|
(<a href="rc.html">html</a> |
|
||||||
|
<a href="rc.ps">ps</a> |
|
||||||
|
<a href="rc.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Tom Duff
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An introduction to the new shell, complete with examples.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Text Editor </span><span style="font-size: 10pt"><tt>sam</tt></span><span style="font-size: 10pt">
|
||||||
|
(<a href="sam/sam.html">html</a> |
|
||||||
|
<a href="sam/sam.ps">ps</a> |
|
||||||
|
<a href="sam/sam.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><tt>Sam</tt></span><span style="font-size: 10pt"> is the standard editor on Plan 9.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Acme: A User Interface for Programmers
|
||||||
|
(<a href="acme/acme.html">html</a> |
|
||||||
|
<a href="acme/acme.ps">ps</a> |
|
||||||
|
<a href="acme/acme.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A system with a more radical approach to programming and editing.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Plumbing and Other Utilities
|
||||||
|
(<a href="plumb.html">html</a> |
|
||||||
|
<a href="plumb.ps">ps</a> |
|
||||||
|
<a href="plumb.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Inter-process communication that enlivens the interactive user interface.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Implementation
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Hello World, or Καλημέρα κόσμε, or </span><span style="font-size: 10pt">こんにちは 世界</span><span style="font-size: 10pt">
|
||||||
|
(<a href="utf.html">html</a> |
|
||||||
|
<a href="utf.ps">ps</a> |
|
||||||
|
<a href="utf.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike and Ken Thompson
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The details about Plan 9’s character set: the Unicode Standard plus an ASCII-compatible encoding.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Plan 9 C Compilers
|
||||||
|
(<a href="compiler.html">html</a> |
|
||||||
|
<a href="compiler.ps">ps</a> |
|
||||||
|
<a href="compiler.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Ken Thompson
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The design and some internals of the compiler suite.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Adding Application Support for a New Architecture in Plan 9
|
||||||
|
(<a href="libmach.html">html</a> |
|
||||||
|
<a href="libmach.ps">ps</a> |
|
||||||
|
<a href="libmach.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Bob Flandrena
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The procedures necessary to add a new instruction set to Plan 9’s programming environment.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Plan 9 File Server
|
||||||
|
(<a href="fs/fs.html">html</a> |
|
||||||
|
<a href="fs/fs.ps">ps</a> |
|
||||||
|
<a href="fs/fs.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Ken Thompson
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The design of the central file server and its novel backup system.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Venti: A new approach to archival storage
|
||||||
|
(<a href="venti/venti.html">html</a> |
|
||||||
|
<a href="venti/venti.ps">ps</a> |
|
||||||
|
<a href="venti/venti.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Sean Quinlan and Sean Dorward
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Archival block-level storage using secure hashes as block identifiers.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The IL protocol
|
||||||
|
(<a href="il/il.html">html</a> |
|
||||||
|
<a href="il/il.ps">ps</a> |
|
||||||
|
<a href="il/il.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Dave Presotto and Phil Winterbottom
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A description of the Internet protocol Plan 9 uses for internal communication.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Lexical File Names in Plan 9, or, Getting Dot-Dot Right
|
||||||
|
(<a href="lexnames.html">html</a> |
|
||||||
|
<a href="lexnames.ps">ps</a> |
|
||||||
|
<a href="lexnames.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A vexing old problem solved: how to make </span><span style="font-size: 10pt"><tt>pwd</tt></span><span style="font-size: 10pt"> get the right answer in the face of multiply-bound directories.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Process Sleep and Wakeup on a Shared-memory Multiprocessor
|
||||||
|
(<a href="sleep.html">html</a> |
|
||||||
|
<a href="sleep.ps">ps</a> |
|
||||||
|
<a href="sleep.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Rob Pike, Dave Presotto, Ken Thompson, and Gerard Holzmann
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A detailed study of a central issue in the Plan 9 kernel.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Miscellany
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">A Guide to the Lp Printer Spooler
|
||||||
|
(<a href="lp.html">html</a> |
|
||||||
|
<a href="lp.ps">ps</a> |
|
||||||
|
<a href="lp.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Paul Glick
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Adminstering the suite of tools to drive PostScript printers.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Troff User’s Manual
|
||||||
|
(<a href="troff.ps">ps</a> |
|
||||||
|
<a href="troff.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Joseph F. Ossanna and Brian W. Kernighan
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The old warhorse, updated for Unicode characters.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">Using SPIN
|
||||||
|
(<a href="spin.html">html</a> |
|
||||||
|
<a href="spin.ps">ps</a> |
|
||||||
|
<a href="spin.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 2.00in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><i>Gerard Holzmann
|
||||||
|
</i></span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">An introduction to a tool for analyzing parallel and distributed programs.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt"><b>Installation
|
||||||
|
</b></span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="line-height: 1.2em; margin-left: 1.00in; text-indent: 0.00in; margin-right: 1.00in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The Various Ports
|
||||||
|
(<a href="port.html">html</a> |
|
||||||
|
<a href="port.ps">ps</a> |
|
||||||
|
<a href="port.pdf">pdf</a>)
|
||||||
|
</span></p><p style="line-height: 1.2em; margin-left: 1.50in; text-indent: 0.00in; margin-right: 1.50in; margin-top: 0; margin-bottom: 0; text-align: left;">
|
||||||
|
<span style="font-size: 10pt">The hardware requirements for the Plan 9 compilers and kernels.
|
||||||
|
</span></p><p style="margin-top: 0; margin-bottom: 0.08in"></p>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.17in"></p>
|
||||||
|
<center><a href="/plan9/">Plan 9 Home Page</a></center>
|
||||||
|
<p style="margin-top: 0; margin-bottom: 0.50in"></p>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
|
1213
sys/doc/lexnames.ms
Normal file
1213
sys/doc/lexnames.ms
Normal file
File diff suppressed because it is too large
Load diff
9568
sys/doc/lexnames.ps
Normal file
9568
sys/doc/lexnames.ps
Normal file
File diff suppressed because it is too large
Load diff
882
sys/doc/libmach.ms
Normal file
882
sys/doc/libmach.ms
Normal file
|
@ -0,0 +1,882 @@
|
||||||
|
.HTML "Adding Application Support for a New Architecture in Plan 9
|
||||||
|
.TL
|
||||||
|
Adding Application Support for a New Architecture in Plan 9
|
||||||
|
.AU
|
||||||
|
Bob Flandrena
|
||||||
|
bobf@plan9.bell-labs.com
|
||||||
|
.SH
|
||||||
|
Introduction
|
||||||
|
.LP
|
||||||
|
Plan 9 has five classes of architecture-dependent software:
|
||||||
|
headers, kernels, compilers and loaders, the
|
||||||
|
.CW libc
|
||||||
|
system library, and a few application programs. In general,
|
||||||
|
architecture-dependent programs
|
||||||
|
consist of a portable part shared by all architectures and a
|
||||||
|
processor-specific portion for each supported architecture.
|
||||||
|
The portable code is often compiled and stored in a library
|
||||||
|
associated with
|
||||||
|
each architecture. A program is built by
|
||||||
|
compiling the architecture-specific code and loading it with the
|
||||||
|
library. Support for a new architecture is provided
|
||||||
|
by building a compiler for the architecture, using it to
|
||||||
|
compile the portable code into libraries,
|
||||||
|
writing the architecture-specific code, and
|
||||||
|
then loading that code with
|
||||||
|
the libraries.
|
||||||
|
.LP
|
||||||
|
This document describes the organization of the architecture-dependent
|
||||||
|
code and headers on Plan 9.
|
||||||
|
The first section briefly discusses the layout of
|
||||||
|
the headers and the source code for the kernels, compilers, loaders, and the
|
||||||
|
system library,
|
||||||
|
.CW libc .
|
||||||
|
The second section provides a detailed
|
||||||
|
discussion of the structure of
|
||||||
|
.CW libmach ,
|
||||||
|
a library containing almost
|
||||||
|
all architecture-dependent code
|
||||||
|
used by application programs.
|
||||||
|
The final section describes the steps required to add
|
||||||
|
application program support for a new architecture.
|
||||||
|
.SH
|
||||||
|
Directory Structure
|
||||||
|
.PP
|
||||||
|
Architecture-dependent information for the new processor
|
||||||
|
is stored in the directory tree rooted at \f(CW/\fP\fIm\fP
|
||||||
|
where
|
||||||
|
.I m
|
||||||
|
is the name of the new architecture (e.g.,
|
||||||
|
.CW mips ).
|
||||||
|
The new directory should be initialized with several important
|
||||||
|
subdirectories, notably
|
||||||
|
.CW bin ,
|
||||||
|
.CW include ,
|
||||||
|
and
|
||||||
|
.CW lib .
|
||||||
|
The directory tree of an existing architecture
|
||||||
|
serves as a good model for the new tree.
|
||||||
|
The architecture-dependent
|
||||||
|
.CW mkfile
|
||||||
|
must be stored in the newly created root directory
|
||||||
|
for the architecture. It is easiest to copy the
|
||||||
|
mkfile for an existing architecture and modify
|
||||||
|
it for the new architecture. When the mkfile
|
||||||
|
is correct, change the
|
||||||
|
.CW OS
|
||||||
|
and
|
||||||
|
.CW CPUS
|
||||||
|
variables in the
|
||||||
|
.CW /sys/src/mkfile.proto
|
||||||
|
to reflect the addition of the new architecture.
|
||||||
|
.SH
|
||||||
|
Headers
|
||||||
|
.LP
|
||||||
|
Architecture-dependent headers are stored in directory
|
||||||
|
.CW /\fIm\fP/include
|
||||||
|
where
|
||||||
|
.I m
|
||||||
|
is the name of the architecture (e.g.,
|
||||||
|
.CW mips ).
|
||||||
|
Two header files are required:
|
||||||
|
.CW u.h
|
||||||
|
and
|
||||||
|
.CW ureg.h .
|
||||||
|
The first defines fundamental data types,
|
||||||
|
bit settings for the floating point
|
||||||
|
status and control registers, and
|
||||||
|
.CW va_list
|
||||||
|
processing which depends on the stack
|
||||||
|
model for the architecture. This file
|
||||||
|
is best built by copying and modifying the
|
||||||
|
.CW u.h
|
||||||
|
file from an architecture
|
||||||
|
with a similar stack model.
|
||||||
|
The
|
||||||
|
.CW ureg.h
|
||||||
|
file
|
||||||
|
contains a structure describing the layout
|
||||||
|
of the saved register set for
|
||||||
|
the architecture; it is defined by the kernel.
|
||||||
|
.LP
|
||||||
|
Header file
|
||||||
|
.CW /sys/include/a.out.h
|
||||||
|
contains the definitions of the magic
|
||||||
|
numbers used to identify executables for
|
||||||
|
each architecture. When support for a new
|
||||||
|
architecture is added, the magic number
|
||||||
|
for the architecture must be added to this file.
|
||||||
|
.LP
|
||||||
|
The header format of a bootable executable is defined by
|
||||||
|
each manufacturer. Header file
|
||||||
|
.CW /sys/include/bootexec.h
|
||||||
|
contains structures describing the headers currently
|
||||||
|
supported. If the new architecture uses a common header
|
||||||
|
such as COFF,
|
||||||
|
the header format is probably already defined,
|
||||||
|
but if the bootable header format is non-standard,
|
||||||
|
a structure defining the format must be added to this file.
|
||||||
|
.LP
|
||||||
|
.SH
|
||||||
|
Kernel
|
||||||
|
.LP
|
||||||
|
Although the kernel depends critically on the properties of the underlying
|
||||||
|
hardware, most of the
|
||||||
|
higher-level kernel functions, including process
|
||||||
|
management, paging, pseudo-devices, and some
|
||||||
|
networking code, are independent of processor
|
||||||
|
architecture. The portable kernel code
|
||||||
|
is divided into two parts: that implementing kernel
|
||||||
|
functions and that devoted to the boot process.
|
||||||
|
Code in the first class is stored in directory
|
||||||
|
.CW /sys/src/9/port
|
||||||
|
and the portable boot code is stored in
|
||||||
|
.CW /sys/src/9/boot .
|
||||||
|
Architecture-dependent kernel code is stored in the
|
||||||
|
subdirectories of
|
||||||
|
.CW /sys/src/9
|
||||||
|
named for each architecture.
|
||||||
|
.LP
|
||||||
|
The relationship between the kernel code and the boot code
|
||||||
|
is convoluted and subtle. The portable boot code
|
||||||
|
is compiled into a library for each architecture. An architecture-specific
|
||||||
|
main program is loaded with the appropriate library and the resulting
|
||||||
|
executable is compiled into the kernel where it is executed as
|
||||||
|
a user process during the final stages of kernel initialization. The boot process
|
||||||
|
performs authentication, attaches the name space root to the appropriate
|
||||||
|
file system and starts the
|
||||||
|
.CW init
|
||||||
|
process.
|
||||||
|
.LP
|
||||||
|
The organization of the portable kernel source code differs from that
|
||||||
|
of most other architecture-specific code.
|
||||||
|
Instead of storing the portable code in a library
|
||||||
|
and loading it with the architecture-specific
|
||||||
|
code, the portable code is compiled directly into
|
||||||
|
the directory containing the architecture-specific code
|
||||||
|
and linked with the object files built from the source in that directory.
|
||||||
|
.LP
|
||||||
|
.SH
|
||||||
|
Compilers and Loaders
|
||||||
|
.LP
|
||||||
|
The compiler source code conforms to the usual
|
||||||
|
organization: portable code is compiled into a library
|
||||||
|
for each architecture
|
||||||
|
and the architecture-dependent code is loaded with
|
||||||
|
that library.
|
||||||
|
The common compiler code is stored in
|
||||||
|
.CW /sys/src/cmd/cc .
|
||||||
|
The
|
||||||
|
.CW mkfile
|
||||||
|
in this directory compiles the portable source and
|
||||||
|
archives the objects in a library for each architecture.
|
||||||
|
The architecture-specific compiler source
|
||||||
|
is stored in a subdirectory of
|
||||||
|
.CW /sys/src/cmd
|
||||||
|
with the same name as the compiler (e.g.,
|
||||||
|
.CW /sys/src/cmd/vc ).
|
||||||
|
.LP
|
||||||
|
There is no portable code shared by the loaders.
|
||||||
|
Each directory of loader source
|
||||||
|
code is self-contained, except for
|
||||||
|
a header file and an instruction name table
|
||||||
|
included from the
|
||||||
|
directory of the associated
|
||||||
|
compiler.
|
||||||
|
.LP
|
||||||
|
.SH
|
||||||
|
Libraries
|
||||||
|
.LP
|
||||||
|
Most C library modules are
|
||||||
|
portable; the source code is stored in
|
||||||
|
directories
|
||||||
|
.CW /sys/src/libc/port
|
||||||
|
and
|
||||||
|
.CW /sys/src/libc/9sys .
|
||||||
|
Architecture-dependent library code
|
||||||
|
is stored in the subdirectory of
|
||||||
|
.CW /sys/src/libc
|
||||||
|
named the same as the target processor.
|
||||||
|
Non-portable functions not only
|
||||||
|
implement architecture-dependent operations
|
||||||
|
but also supply assembly language implementations
|
||||||
|
of functions where speed is critical.
|
||||||
|
Directory
|
||||||
|
.CW /sys/src/libc/9syscall
|
||||||
|
is unusual because it
|
||||||
|
contains architecture-dependent information
|
||||||
|
for all architectures.
|
||||||
|
It holds only a header file defining
|
||||||
|
the names and numbers of system calls
|
||||||
|
and a
|
||||||
|
.CW mkfile .
|
||||||
|
The
|
||||||
|
.CW mkfile
|
||||||
|
executes an
|
||||||
|
.CW rc
|
||||||
|
script that parses the header file, constructs
|
||||||
|
assembler language functions implementing the system
|
||||||
|
call for each architecture, assembles the code,
|
||||||
|
and archives the object files in
|
||||||
|
.CW libc .
|
||||||
|
The assembler language syntax and the system interface
|
||||||
|
differ for each architecture.
|
||||||
|
The
|
||||||
|
.CW rc
|
||||||
|
script in this
|
||||||
|
.CW mkfile
|
||||||
|
must be modified to support a new architecture.
|
||||||
|
.LP
|
||||||
|
.SH
|
||||||
|
Applications
|
||||||
|
.LP
|
||||||
|
Application programs process two forms of architecture-dependent
|
||||||
|
information: executable images and intermediate object files.
|
||||||
|
Almost all processing is on executable files.
|
||||||
|
System library
|
||||||
|
.CW libmach
|
||||||
|
provides functions that convert
|
||||||
|
architecture-specific data
|
||||||
|
to a portable format so application programs
|
||||||
|
can process this data independent of its
|
||||||
|
underlying representation.
|
||||||
|
Further, when a new architecture is implemented
|
||||||
|
almost all code changes
|
||||||
|
are confined to the library;
|
||||||
|
most affected application programs need only be reloaded.
|
||||||
|
The source code for the library is stored in
|
||||||
|
.CW /sys/src/libmach .
|
||||||
|
.LP
|
||||||
|
An application program running on one type of
|
||||||
|
processor must be able to interpret
|
||||||
|
architecture-dependent information for all
|
||||||
|
supported processors.
|
||||||
|
For example, a debugger must be able to debug
|
||||||
|
the executables of
|
||||||
|
all architectures, not just the
|
||||||
|
architecture on which it is executing, since
|
||||||
|
.CW /proc
|
||||||
|
may be imported from a different machine.
|
||||||
|
.LP
|
||||||
|
A small part of the application library
|
||||||
|
provides functions to
|
||||||
|
extract symbol references from object files.
|
||||||
|
The remainder provides the following processing
|
||||||
|
of executable files or memory images:
|
||||||
|
.IP \(bu
|
||||||
|
Header interpretation.
|
||||||
|
.IP \(bu
|
||||||
|
Symbol table interpretation.
|
||||||
|
.IP \(bu
|
||||||
|
Execution context interpretation, such as stack traces
|
||||||
|
and stack frame location.
|
||||||
|
.IP \(bu
|
||||||
|
Instruction interpretation including disassembly and
|
||||||
|
instruction size and follow-set calculations.
|
||||||
|
.IP \(bu
|
||||||
|
Exception and floating point number interpretation.
|
||||||
|
.IP \(bu
|
||||||
|
Architecture-independent read and write access through a
|
||||||
|
relocation map.
|
||||||
|
.LP
|
||||||
|
Header file
|
||||||
|
.CW /sys/include/mach.h
|
||||||
|
defines the interfaces to the
|
||||||
|
application library. Manual pages
|
||||||
|
.I mach (2),
|
||||||
|
.I symbol (2),
|
||||||
|
and
|
||||||
|
.I object (2)
|
||||||
|
describe the details of the
|
||||||
|
library functions.
|
||||||
|
.LP
|
||||||
|
Two data structures, called
|
||||||
|
.CW Mach
|
||||||
|
and
|
||||||
|
.CW Machdata ,
|
||||||
|
contain architecture-dependent parameters and
|
||||||
|
a jump table of functions.
|
||||||
|
Global variables
|
||||||
|
.CW mach
|
||||||
|
and
|
||||||
|
.CW machdata
|
||||||
|
point to the
|
||||||
|
.CW Mach
|
||||||
|
and
|
||||||
|
.CW Machdata
|
||||||
|
data structures associated with the target architecture.
|
||||||
|
An application determines the target architecture of
|
||||||
|
a file or executable image, sets the global pointers
|
||||||
|
to the data structures associated with that architecture,
|
||||||
|
and subsequently performs all references indirectly through the
|
||||||
|
pointers.
|
||||||
|
As a result, direct references to the tables for each
|
||||||
|
architecture are avoided and the application code intrinsically
|
||||||
|
supports all architectures (though only one at a time).
|
||||||
|
.LP
|
||||||
|
Object file processing is handled similarly: architecture-dependent
|
||||||
|
functions identify and
|
||||||
|
decode the intermediate files for the processor.
|
||||||
|
The application indirectly
|
||||||
|
invokes a classification function to identify
|
||||||
|
the architecture of the object code and to select the
|
||||||
|
appropriate decoding function. Subsequent calls
|
||||||
|
then use that function to decode each record. Again,
|
||||||
|
the layer of indirection allows the application code
|
||||||
|
to support all architectures without modification.
|
||||||
|
.LP
|
||||||
|
Splitting the architecture-dependent information
|
||||||
|
between the
|
||||||
|
.CW Mach
|
||||||
|
and
|
||||||
|
.CW Machdata
|
||||||
|
data structures
|
||||||
|
allows applications to choose
|
||||||
|
an appropriate level of service. Even though an application
|
||||||
|
does not directly reference the architecture-specific data structures,
|
||||||
|
it must load the
|
||||||
|
architecture-dependent tables and code
|
||||||
|
for all architectures it supports. The size of this data
|
||||||
|
can be substantial and many applications do not require
|
||||||
|
the full range of architecture-dependent functionality.
|
||||||
|
For example, the
|
||||||
|
.CW size
|
||||||
|
command does not require the disassemblers for every architecture;
|
||||||
|
it only needs to decode the header.
|
||||||
|
The
|
||||||
|
.CW Mach
|
||||||
|
data structure contains a few architecture-specific parameters
|
||||||
|
and a description of the processor register set.
|
||||||
|
The size of the structure
|
||||||
|
varies with the size of the register
|
||||||
|
set but is generally small.
|
||||||
|
The
|
||||||
|
.CW Machdata
|
||||||
|
data structure contains
|
||||||
|
a jump table of architecture-dependent functions;
|
||||||
|
the amount of code and data referenced by this table
|
||||||
|
is usually large.
|
||||||
|
.SH
|
||||||
|
Libmach Source Code Organization
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW libmach
|
||||||
|
library provides four classes of functionality:
|
||||||
|
.LP
|
||||||
|
.IP "Header and Symbol Table Decoding\ -\ "
|
||||||
|
Files
|
||||||
|
.CW executable.c
|
||||||
|
and
|
||||||
|
.CW sym.c
|
||||||
|
contain code to interpret the header and
|
||||||
|
symbol tables of
|
||||||
|
an executable file or executing image.
|
||||||
|
Function
|
||||||
|
.CW crackhdr
|
||||||
|
decodes the header,
|
||||||
|
reformats the
|
||||||
|
information into an
|
||||||
|
.CW Fhdr
|
||||||
|
data structure, and points
|
||||||
|
global variable
|
||||||
|
.CW mach
|
||||||
|
to the
|
||||||
|
.CW Mach
|
||||||
|
data structure of the target architecture.
|
||||||
|
The symbol table processing
|
||||||
|
uses the data in the
|
||||||
|
.CW Fhdr
|
||||||
|
structure to decode the symbol table.
|
||||||
|
A variety of symbol table access functions then support
|
||||||
|
queries on the reformatted table.
|
||||||
|
.IP "Debugger Support\ -\ "
|
||||||
|
Files named
|
||||||
|
.CW \fIm\fP.c ,
|
||||||
|
where
|
||||||
|
.I m
|
||||||
|
is the code letter assigned to the architecture,
|
||||||
|
contain the initialized
|
||||||
|
.CW Mach
|
||||||
|
data structure and the definition of the register
|
||||||
|
set for each architecture.
|
||||||
|
Architecture-specific debugger support functions and
|
||||||
|
an initialized
|
||||||
|
.CW Machdata
|
||||||
|
structure are stored in
|
||||||
|
files named
|
||||||
|
.CW \fIm\fPdb.c .
|
||||||
|
Files
|
||||||
|
.CW machdata.c
|
||||||
|
and
|
||||||
|
.CW setmach.c
|
||||||
|
contain debugger support functions shared
|
||||||
|
by multiple architectures.
|
||||||
|
.IP "Architecture-Independent Access\ -\ "
|
||||||
|
Files
|
||||||
|
.CW map.c ,
|
||||||
|
.CW access.c ,
|
||||||
|
and
|
||||||
|
.CW swap.c
|
||||||
|
provide accesses through a relocation map
|
||||||
|
to data in an executable file or executing image.
|
||||||
|
Byte-swapping is performed as needed. Global variables
|
||||||
|
.CW mach
|
||||||
|
and
|
||||||
|
.CW machdata
|
||||||
|
must point to the
|
||||||
|
.CW Mach
|
||||||
|
and
|
||||||
|
.CW Machdata
|
||||||
|
data structures of the target architecture.
|
||||||
|
.IP "Object File Interpretation\ -\ "
|
||||||
|
These files contain functions to identify the
|
||||||
|
target architecture of an
|
||||||
|
intermediate object file
|
||||||
|
and extract references to symbols. File
|
||||||
|
.CW obj.c
|
||||||
|
contains code common to all architectures;
|
||||||
|
file
|
||||||
|
.CW \fIm\fPobj.c
|
||||||
|
contains the architecture-specific source code
|
||||||
|
for the machine with code character
|
||||||
|
.I m .
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW Machdata
|
||||||
|
data structure is primarily a jump
|
||||||
|
table of architecture-dependent debugger support
|
||||||
|
functions. Functions select the
|
||||||
|
.CW Machdata
|
||||||
|
structure for a target architecture based
|
||||||
|
on the value of the
|
||||||
|
.CW type
|
||||||
|
code in the
|
||||||
|
.CW Fhdr
|
||||||
|
structure or the name of the architecture.
|
||||||
|
The jump table provides functions to swap bytes, interpret
|
||||||
|
machine instructions,
|
||||||
|
perform stack
|
||||||
|
traces, find stack frames, format floating point
|
||||||
|
numbers, and decode machine exceptions. Some functions, such as
|
||||||
|
machine exception decoding, are idiosyncratic and must be
|
||||||
|
supplied for each architecture. Others depend
|
||||||
|
on the compiler run-time model and several
|
||||||
|
architectures may share code common to a model. For
|
||||||
|
example, many architectures share the code to
|
||||||
|
process the fixed-frame stack model implemented by
|
||||||
|
several of the compilers.
|
||||||
|
Finally, some
|
||||||
|
functions, such as byte-swapping, provide a general capability and
|
||||||
|
the jump table need only select an implementation appropriate
|
||||||
|
to the architecture.
|
||||||
|
.LP
|
||||||
|
.SH
|
||||||
|
Adding Application Support for a New Architecture
|
||||||
|
.LP
|
||||||
|
This section describes the
|
||||||
|
steps required to add application-level
|
||||||
|
support for a new architecture.
|
||||||
|
We assume
|
||||||
|
the kernel, compilers, loaders and system libraries
|
||||||
|
for the new architecture are already in place. This
|
||||||
|
implies that a code-character has been assigned and
|
||||||
|
that the architecture-specific headers have been
|
||||||
|
updated.
|
||||||
|
With the exception of two programs,
|
||||||
|
application-level changes are confined to header
|
||||||
|
files and the source code in
|
||||||
|
.CW /sys/src/libmach .
|
||||||
|
.LP
|
||||||
|
.IP 1.
|
||||||
|
Begin by updating the application library
|
||||||
|
header file in
|
||||||
|
.CW /sys/include/mach.h .
|
||||||
|
Add the following symbolic codes to the
|
||||||
|
.CW enum
|
||||||
|
statement near the beginning of the file:
|
||||||
|
.RS
|
||||||
|
.IP \(bu
|
||||||
|
The processor type code, e.g.,
|
||||||
|
.CW MSPARC .
|
||||||
|
.IP \(bu
|
||||||
|
The type of the executable. There are usually
|
||||||
|
two codes needed: one for a bootable
|
||||||
|
executable (i.e., a kernel) and one for an
|
||||||
|
application executable.
|
||||||
|
.IP \(bu
|
||||||
|
The disassembler type code. Add one entry for
|
||||||
|
each supported disassembler for the architecture.
|
||||||
|
.IP \(bu
|
||||||
|
A symbolic code for the object file.
|
||||||
|
.RE
|
||||||
|
.LP
|
||||||
|
.IP 2.
|
||||||
|
In a file name
|
||||||
|
.CW /sys/src/libmach/\fIm\fP.c
|
||||||
|
(where
|
||||||
|
.I m
|
||||||
|
is the identifier character assigned to the architecture),
|
||||||
|
initialize
|
||||||
|
.CW Reglist
|
||||||
|
and
|
||||||
|
.CW Mach
|
||||||
|
data structures with values defining
|
||||||
|
the register set and various system parameters.
|
||||||
|
The source file for a similar architecture
|
||||||
|
can serve as template.
|
||||||
|
Most of the fields of the
|
||||||
|
.CW Mach
|
||||||
|
data structure are obvious
|
||||||
|
but a few require further explanation.
|
||||||
|
.RS
|
||||||
|
.IP "\f(CWkbase\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of the kernel
|
||||||
|
.CW ublock .
|
||||||
|
The debuggers
|
||||||
|
assume the first entry of the kernel
|
||||||
|
.CW ublock
|
||||||
|
points to the
|
||||||
|
.CW Proc
|
||||||
|
structure for a kernel thread.
|
||||||
|
.IP "\f(CWktmask\fP\ -\ "
|
||||||
|
This field
|
||||||
|
is a bit mask used to calculate the kernel text address from
|
||||||
|
the kernel
|
||||||
|
.CW ublock
|
||||||
|
address.
|
||||||
|
The first page of the
|
||||||
|
kernel text segment is calculated by
|
||||||
|
ANDing
|
||||||
|
the negation of this mask with
|
||||||
|
.CW kbase .
|
||||||
|
.IP "\f(CWkspoff\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the byte offset in the
|
||||||
|
.CW Proc
|
||||||
|
data structure to the saved kernel
|
||||||
|
stack pointer for a suspended kernel thread. This
|
||||||
|
is the offset to the
|
||||||
|
.CW sched.sp
|
||||||
|
field of a
|
||||||
|
.CW Proc
|
||||||
|
table entry.
|
||||||
|
.IP "\f(CWkpcoff\fP\ -\ "
|
||||||
|
This field contains the byte offset into the
|
||||||
|
.CW Proc
|
||||||
|
data structure
|
||||||
|
of
|
||||||
|
the program counter of a suspended kernel thread.
|
||||||
|
This is the offset to
|
||||||
|
field
|
||||||
|
.CW sched.pc
|
||||||
|
in that structure.
|
||||||
|
.IP "\f(CWkspdelta\fP and \f(CWkpcdelta\fP\ -\ "
|
||||||
|
These fields
|
||||||
|
contain corrections to be added to
|
||||||
|
the stack pointer and program counter, respectively,
|
||||||
|
to properly locate the stack and next
|
||||||
|
instruction of a kernel thread. These
|
||||||
|
values bias the saved registers retrieved
|
||||||
|
from the
|
||||||
|
.CW Label
|
||||||
|
structure named
|
||||||
|
.CW sched
|
||||||
|
in the
|
||||||
|
.CW Proc
|
||||||
|
data structure.
|
||||||
|
Most architectures require no bias
|
||||||
|
and these fields contain zeros.
|
||||||
|
.IP "\f(CWscalloff\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the byte offset of the
|
||||||
|
.CW scallnr
|
||||||
|
field in the
|
||||||
|
.CW ublock
|
||||||
|
data structure associated with a process.
|
||||||
|
The
|
||||||
|
.CW scallnr
|
||||||
|
field contains the number of the
|
||||||
|
last system call executed by the process.
|
||||||
|
The location of the field varies depending on
|
||||||
|
the size of the floating point register set
|
||||||
|
which precedes it in the
|
||||||
|
.CW ublock .
|
||||||
|
.RE
|
||||||
|
.LP
|
||||||
|
.IP 3.
|
||||||
|
Add an entry to the initialization of the
|
||||||
|
.CW ExecTable
|
||||||
|
data structure at the beginning of file
|
||||||
|
.CW /sys/src/libmach/executable.c .
|
||||||
|
Most architectures
|
||||||
|
require two entries: one for
|
||||||
|
a normal executable and
|
||||||
|
one for a bootable
|
||||||
|
image. Each table entry contains:
|
||||||
|
.RS
|
||||||
|
.IP \(bu
|
||||||
|
Magic Number\ \-\
|
||||||
|
The big-endian magic number assigned to the architecture in
|
||||||
|
.CW /sys/include/a.out.h .
|
||||||
|
.IP \(bu
|
||||||
|
Name\ \-\
|
||||||
|
A string describing the executable.
|
||||||
|
.IP \(bu
|
||||||
|
Executable type code\ \-\
|
||||||
|
The executable code assigned in
|
||||||
|
.CW /sys/include/mach.h .
|
||||||
|
.IP \(bu
|
||||||
|
\f(CWMach\fP pointer\ \-\
|
||||||
|
The address of the initialized
|
||||||
|
.CW Mach
|
||||||
|
data structure constructed in Step 2.
|
||||||
|
You must also add the name of this table to the
|
||||||
|
list of
|
||||||
|
.CW Mach
|
||||||
|
table definitions immediately preceding the
|
||||||
|
.CW ExecTable
|
||||||
|
initialization.
|
||||||
|
.IP \(bu
|
||||||
|
Header size\ \-\
|
||||||
|
The number of bytes in the executable file header.
|
||||||
|
The size of a normal executable header is always
|
||||||
|
.CW sizeof(Exec) .
|
||||||
|
The size of a bootable header is
|
||||||
|
determined by the size of the structure
|
||||||
|
for the architecture defined in
|
||||||
|
.CW /sys/include/bootexec.h .
|
||||||
|
.IP \(bu
|
||||||
|
Byte-swapping function\ \-\
|
||||||
|
The address of
|
||||||
|
.CW beswal
|
||||||
|
or
|
||||||
|
.CW leswal
|
||||||
|
for big-endian and little-endian
|
||||||
|
architectures, respectively.
|
||||||
|
.IP \(bu
|
||||||
|
Decoder function\ -\
|
||||||
|
The address of a function to decode the header.
|
||||||
|
Function
|
||||||
|
.CW adotout
|
||||||
|
decodes the common header shared by all normal
|
||||||
|
(i.e., non-bootable) executable files.
|
||||||
|
The header format of bootable
|
||||||
|
executable files is defined by the manufacturer and
|
||||||
|
a custom function is almost always
|
||||||
|
required to decode it.
|
||||||
|
Header file
|
||||||
|
.CW /sys/include/bootexec.h
|
||||||
|
contains data structures defining the bootable
|
||||||
|
headers for all architectures. If the new architecture
|
||||||
|
uses an existing format, the appropriate
|
||||||
|
decoding function should already be in
|
||||||
|
.CW executable.c .
|
||||||
|
If the header format is unique, then
|
||||||
|
a new function must be added to this file.
|
||||||
|
Usually the decoding function for an existing
|
||||||
|
architecture can be adopted with minor modifications.
|
||||||
|
.RE
|
||||||
|
.LP
|
||||||
|
.IP 4.
|
||||||
|
Write an object file parser and
|
||||||
|
store it in file
|
||||||
|
.CW /sys/src/libmach/\fIm\fPobj.c
|
||||||
|
where
|
||||||
|
.I m
|
||||||
|
is the identifier character assigned to the architecture.
|
||||||
|
Two functions are required: a predicate to identify an
|
||||||
|
object file for the architecture and a function to extract
|
||||||
|
symbol references from the object code.
|
||||||
|
The object code format is obscure but
|
||||||
|
it is often possible to adopt the
|
||||||
|
code of an existing architecture
|
||||||
|
with minor modifications.
|
||||||
|
When these
|
||||||
|
functions are in hand, insert their addresses
|
||||||
|
in the jump table at the beginning of file
|
||||||
|
.CW /sys/src/libmach/obj.c .
|
||||||
|
.LP
|
||||||
|
.IP 5.
|
||||||
|
Implement the required debugger support functions and
|
||||||
|
initialize the parameters and jump table of the
|
||||||
|
.CW Machdata
|
||||||
|
data structure for the architecture.
|
||||||
|
This code is conventionally stored in
|
||||||
|
a file named
|
||||||
|
.CW /sys/src/libmach/\fIm\fPdb.c
|
||||||
|
where
|
||||||
|
.I m
|
||||||
|
is the identifier character assigned to the architecture.
|
||||||
|
The fields of the
|
||||||
|
.CW Machdata
|
||||||
|
structure are:
|
||||||
|
.RS
|
||||||
|
.IP "\f(CWbpinst\fP and \f(CWbpsize\fP\ -\ "
|
||||||
|
These fields
|
||||||
|
contain the breakpoint instruction and the size
|
||||||
|
of the instruction, respectively.
|
||||||
|
.IP "\f(CWswab\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of a function to
|
||||||
|
byte-swap a 16-bit value. Choose
|
||||||
|
.CW leswab
|
||||||
|
or
|
||||||
|
.CW beswab
|
||||||
|
for little-endian or big-endian architectures, respectively.
|
||||||
|
.IP "\f(CWswal\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of a function to
|
||||||
|
byte-swap a 32-bit value. Choose
|
||||||
|
.CW leswal
|
||||||
|
or
|
||||||
|
.CW beswal
|
||||||
|
for little-endian or big-endian architectures, respectively.
|
||||||
|
.IP "\f(CWctrace\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of a function to perform a
|
||||||
|
C-language stack trace. Two general trace functions,
|
||||||
|
.CW risctrace
|
||||||
|
and
|
||||||
|
.CW cisctrace ,
|
||||||
|
traverse fixed-frame and relative-frame stacks,
|
||||||
|
respectively. If the compiler for the
|
||||||
|
new architecture conforms to one of
|
||||||
|
these models, select the appropriate function. If the
|
||||||
|
stack model is unique,
|
||||||
|
supply a custom stack trace function.
|
||||||
|
.IP "\f(CWfindframe\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of a function to locate the stack
|
||||||
|
frame associated with a text address.
|
||||||
|
Generic functions
|
||||||
|
.CW riscframe
|
||||||
|
and
|
||||||
|
.CW ciscframe
|
||||||
|
process fixed-frame and relative-frame stack
|
||||||
|
models.
|
||||||
|
.IP "\f(CWufixup\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of a function to adjust
|
||||||
|
the base address of the register save area.
|
||||||
|
Currently, only the
|
||||||
|
68020 requires this bias
|
||||||
|
to offset over the active
|
||||||
|
exception frame.
|
||||||
|
.IP "\f(CWexcep\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of a function to produce a
|
||||||
|
text
|
||||||
|
string describing the
|
||||||
|
current exception.
|
||||||
|
Each architecture stores exception
|
||||||
|
information uniquely, so this code must always be supplied.
|
||||||
|
.IP "\f(CWbpfix\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of a function to adjust an
|
||||||
|
address prior to laying down a breakpoint.
|
||||||
|
.IP "\f(CWsftos\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of a function to convert a single
|
||||||
|
precision floating point value
|
||||||
|
to a string. Choose
|
||||||
|
.CW leieeesftos
|
||||||
|
for little-endian
|
||||||
|
or
|
||||||
|
.CW beieeesftos
|
||||||
|
for big-endian architectures.
|
||||||
|
.IP "\f(CWdftos\fP\ -\ "
|
||||||
|
This field
|
||||||
|
contains the address of a function to convert a double
|
||||||
|
precision floating point value
|
||||||
|
to a string. Choose
|
||||||
|
.CW leieeedftos
|
||||||
|
for little-endian
|
||||||
|
or
|
||||||
|
.CW beieeedftos
|
||||||
|
for big-endian architectures.
|
||||||
|
.IP "\f(CWfoll\fP, \f(CWdas\fP, \f(CWhexinst\fP, and \f(CWinstsize\fP\ -\ "
|
||||||
|
These fields point to functions that interpret machine
|
||||||
|
instructions.
|
||||||
|
They rely on disassembly of the instruction
|
||||||
|
and are unique to each architecture.
|
||||||
|
.CW Foll
|
||||||
|
calculates the follow set of an instruction.
|
||||||
|
.CW Das
|
||||||
|
disassembles a machine instruction to assembly language.
|
||||||
|
.CW Hexinst
|
||||||
|
formats a machine instruction as a text
|
||||||
|
string of
|
||||||
|
hexadecimal digits.
|
||||||
|
.CW Instsize
|
||||||
|
calculates the size in bytes, of an instruction.
|
||||||
|
Once the disassembler is written, the other functions
|
||||||
|
can usually be implemented as trivial extensions of it.
|
||||||
|
.LP
|
||||||
|
It is possible to provide support for a new architecture
|
||||||
|
incrementally by filling the jump table entries
|
||||||
|
of the
|
||||||
|
.CW Machdata
|
||||||
|
structure as code is written. In general, if
|
||||||
|
a jump table entry contains a zero, application
|
||||||
|
programs requiring that function will issue an
|
||||||
|
error message instead of attempting to
|
||||||
|
call the function. For example,
|
||||||
|
the
|
||||||
|
.CW foll ,
|
||||||
|
.CW das ,
|
||||||
|
.CW hexinst ,
|
||||||
|
and
|
||||||
|
.CW instsize
|
||||||
|
jump table slots can be zeroed until a
|
||||||
|
disassembler is written.
|
||||||
|
Other capabilities, such as
|
||||||
|
stack trace or variable inspection,
|
||||||
|
can be supplied and will be available to
|
||||||
|
the debuggers but attempts to use the
|
||||||
|
disassembler will result in an error message.
|
||||||
|
.RE
|
||||||
|
.IP 6.
|
||||||
|
Update the table named
|
||||||
|
.CW machines
|
||||||
|
near the beginning of
|
||||||
|
.CW /sys/src/libmach/setmach.c .
|
||||||
|
This table binds the
|
||||||
|
file type code and machine name to the
|
||||||
|
.CW Mach
|
||||||
|
and
|
||||||
|
.CW Machdata
|
||||||
|
structures of an architecture.
|
||||||
|
The names of the initialized
|
||||||
|
.CW Mach
|
||||||
|
and
|
||||||
|
.CW Machdata
|
||||||
|
structures built in steps 2 and 5
|
||||||
|
must be added to the list of
|
||||||
|
structure definitions immediately
|
||||||
|
preceding the table initialization.
|
||||||
|
If both Plan 9 and
|
||||||
|
native disassembly are supported, add
|
||||||
|
an entry for each disassembler to the table. The
|
||||||
|
entry for the default disassembler (usually
|
||||||
|
Plan 9) must be first.
|
||||||
|
.IP 7.
|
||||||
|
Add an entry describing the architecture to
|
||||||
|
the table named
|
||||||
|
.CW trans
|
||||||
|
near the end of
|
||||||
|
.CW /sys/src/cmd/prof.c .
|
||||||
|
.RE
|
||||||
|
.IP 8.
|
||||||
|
Add an entry describing the architecture to
|
||||||
|
the table named
|
||||||
|
.CW objtype
|
||||||
|
near the start of
|
||||||
|
.CW /sys/src/cmd/pcc.c .
|
||||||
|
.RE
|
||||||
|
.IP 9.
|
||||||
|
Recompile and install
|
||||||
|
all application programs that include header file
|
||||||
|
.CW mach.h
|
||||||
|
and load with
|
||||||
|
.CW libmach.a .
|
7331
sys/doc/libmach.ps
Normal file
7331
sys/doc/libmach.ps
Normal file
File diff suppressed because it is too large
Load diff
824
sys/doc/lp.ms
Normal file
824
sys/doc/lp.ms
Normal file
|
@ -0,0 +1,824 @@
|
||||||
|
.HTML "A Guide to the Lp Printer Spooler
|
||||||
|
.TL
|
||||||
|
A Guide to the Lp
|
||||||
|
Printer Spooler
|
||||||
|
.AU
|
||||||
|
Paul Glick
|
||||||
|
pg@plan9.bell-labs.com
|
||||||
|
.AB
|
||||||
|
.PP
|
||||||
|
.I Lp
|
||||||
|
is a collection of programs used to provide an easy-to-use
|
||||||
|
interface for printing a variety of document types on a variety
|
||||||
|
of printers.
|
||||||
|
.I Lp
|
||||||
|
is the glue that connects various document language
|
||||||
|
translators and printer communication programs together so that
|
||||||
|
the users may have a consistent view of printers.
|
||||||
|
Most of the glue
|
||||||
|
is shell script, which can be easily modified.
|
||||||
|
The user need not
|
||||||
|
specify options to get sensible output in most cases.
|
||||||
|
.I Lp
|
||||||
|
is described here
|
||||||
|
so that others may make additions and changes.
|
||||||
|
.AE
|
||||||
|
\" .2C
|
||||||
|
.NH
|
||||||
|
Introduction
|
||||||
|
.PP
|
||||||
|
.I Lp
|
||||||
|
is used to format and print data on a variety of output devices.
|
||||||
|
The need for
|
||||||
|
.I lp
|
||||||
|
was rooted in the inability of other printer spoolers to do simple
|
||||||
|
tasks without a great deal of user specification of options.
|
||||||
|
At the time
|
||||||
|
.I lp
|
||||||
|
was written, there were several printer
|
||||||
|
languages, such as ImPress and PostScript, and
|
||||||
|
an internally developed printer that would accept
|
||||||
|
.I troff
|
||||||
|
output.
|
||||||
|
Now, all our printers take PostScript,
|
||||||
|
but printers that use HPCL and HPGL abound and
|
||||||
|
support for those printers may be added easily.
|
||||||
|
A great deal of what underlies
|
||||||
|
.I lp
|
||||||
|
is taken from BSD's
|
||||||
|
.I lpr
|
||||||
|
and System V's
|
||||||
|
.I lp .
|
||||||
|
The important features of this system are that most of the programs
|
||||||
|
are easily modified shell scripts and the user need not
|
||||||
|
learn to use the large amount of underlying software developed by others.
|
||||||
|
.I Lp
|
||||||
|
runs under Plan 9 and several flavors of
|
||||||
|
UNIX.
|
||||||
|
This document deals with
|
||||||
|
.I lp
|
||||||
|
as it relates to Plan 9.
|
||||||
|
.I Lp
|
||||||
|
was developed using both Datakit and Ethernet to transport data between machines.
|
||||||
|
Now only the Ethernet transport mechanism remains.
|
||||||
|
.PP
|
||||||
|
Text, graphics, and formatted text files are appropriately processed and
|
||||||
|
placed into a spool directory from which they are taken to be printed by a daemon process.
|
||||||
|
Additional functions include checking the status of a printer queue
|
||||||
|
and removing jobs from the printer queue.
|
||||||
|
.PP
|
||||||
|
All the shell scripts (see
|
||||||
|
.I rc (1))
|
||||||
|
associated with
|
||||||
|
.I lp
|
||||||
|
reside in the spool directory
|
||||||
|
.CW /sys/lib/lp
|
||||||
|
except for the
|
||||||
|
.I lp
|
||||||
|
command itself, which resides in
|
||||||
|
.CW /rc/bin .
|
||||||
|
Commands related to
|
||||||
|
.I lp
|
||||||
|
that are not shell scripts can most often be found
|
||||||
|
in
|
||||||
|
.CW /$cputype/bin/aux .
|
||||||
|
The directory where all the
|
||||||
|
.I lp
|
||||||
|
scripts reside is defined within
|
||||||
|
.I lp
|
||||||
|
by the shell variable
|
||||||
|
.CW LPLIB .
|
||||||
|
In the remainder of this document, file names will be specified
|
||||||
|
with this shell variable as their root.
|
||||||
|
.NH
|
||||||
|
Usage
|
||||||
|
.PP
|
||||||
|
.I Lp
|
||||||
|
requires an output device to be specified
|
||||||
|
before it will process input.
|
||||||
|
This can be done in any of three ways described here.
|
||||||
|
.IP 1)
|
||||||
|
The file
|
||||||
|
.CW $LPLIB/defdevice
|
||||||
|
may contain the name of a default output device.
|
||||||
|
This may not be practical for environments where
|
||||||
|
there are many printers.
|
||||||
|
.IP 2)
|
||||||
|
The user's environment variable
|
||||||
|
.CW LPDEST
|
||||||
|
may be set to the name of the device to be used.
|
||||||
|
This is often a more practical solution when there are several printers
|
||||||
|
available.
|
||||||
|
This overrides a
|
||||||
|
.CW defdevice
|
||||||
|
specification.
|
||||||
|
.IP 3)
|
||||||
|
The
|
||||||
|
.CW -d
|
||||||
|
.I printer
|
||||||
|
option to the
|
||||||
|
.I lp
|
||||||
|
command specifies
|
||||||
|
.I printer
|
||||||
|
as the device to which output should be directed, overriding the
|
||||||
|
previous two specifications.
|
||||||
|
.PP
|
||||||
|
.ti 0
|
||||||
|
If
|
||||||
|
.I printer
|
||||||
|
is
|
||||||
|
.CW ? ,
|
||||||
|
a list of printers and other information in the
|
||||||
|
.CW devices
|
||||||
|
file is printed, as shown in Figure 1.
|
||||||
|
Quote the question mark to prevent it from being
|
||||||
|
interpreted by the shell language as a metacharacter.
|
||||||
|
\" .1C
|
||||||
|
.KF
|
||||||
|
.P1
|
||||||
|
% lp -d'?'
|
||||||
|
device location host class
|
||||||
|
fn 2C-501 helix post/2+600dpi+duplex
|
||||||
|
pcclone - - post+nohead
|
||||||
|
peacock 2C-501 cetus post/2+300dpi+nohead+color
|
||||||
|
ps83 st8_fl3 rice post+300dpi+reverse
|
||||||
|
psu 2C-501 cetus post/2+1200dpi
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
%
|
||||||
|
.P2
|
||||||
|
.ce
|
||||||
|
.I "Figure 1. Sample listing of installed printers"
|
||||||
|
.KE
|
||||||
|
.PP
|
||||||
|
Normally,
|
||||||
|
.I lp
|
||||||
|
uses the
|
||||||
|
.CW file
|
||||||
|
command to figure out what type of input it is receiving.
|
||||||
|
This is done within the
|
||||||
|
.CW generic
|
||||||
|
process which is discussed later in this paper in the
|
||||||
|
.B "Process directory"
|
||||||
|
section.
|
||||||
|
To select a specific input processor the
|
||||||
|
\f(CW-p\fP\fIprocess\fP
|
||||||
|
option is used where
|
||||||
|
.I process
|
||||||
|
is one of the shell scripts in the
|
||||||
|
.CW process
|
||||||
|
directory.
|
||||||
|
.LP
|
||||||
|
Troff
|
||||||
|
output can be printed, in this case, on printer
|
||||||
|
.I fn
|
||||||
|
with
|
||||||
|
.P1
|
||||||
|
% troff -ms lp.ms | lp -dfn
|
||||||
|
.P2
|
||||||
|
.LP
|
||||||
|
A file can be converted to PostScript using the pseudo-printer
|
||||||
|
.CW stdout :
|
||||||
|
.P1
|
||||||
|
% troff -ms lp.ms | lp -dstdout > lp.ps
|
||||||
|
.P2
|
||||||
|
LaTeX (and analogously TeX)
|
||||||
|
documents are printed in two steps:
|
||||||
|
.P1
|
||||||
|
% latex lp.tex
|
||||||
|
.
|
||||||
|
.
|
||||||
|
% lp lp.dvi
|
||||||
|
.
|
||||||
|
.
|
||||||
|
%
|
||||||
|
.P2
|
||||||
|
LaTeX
|
||||||
|
produces a `.dvi' file and
|
||||||
|
does not permit the use of a pipe
|
||||||
|
connection to the standard input of
|
||||||
|
.I lp .
|
||||||
|
To look at the status and queue of a device, use
|
||||||
|
.CW -q :
|
||||||
|
.P1
|
||||||
|
% lp -dpsu -q
|
||||||
|
daemon status:
|
||||||
|
: 67.17% sent
|
||||||
|
printer status:
|
||||||
|
%%[ status: busy; source: lpd ]%%
|
||||||
|
|
||||||
|
queue on cetus:
|
||||||
|
job user try size
|
||||||
|
rice29436.1 pg 0 17454
|
||||||
|
slocum17565.1 ches 1 49995
|
||||||
|
%
|
||||||
|
.P2
|
||||||
|
This command can print the status and queue of the local
|
||||||
|
and remote hosts.
|
||||||
|
Administrators should be advised that working in an environment where the
|
||||||
|
.I lp
|
||||||
|
spool directory is shared among the local and remote hosts,
|
||||||
|
no spooling should be done on the local hosts.
|
||||||
|
The format of the status and queue printout is up to the administrator.
|
||||||
|
The job started above can be killed with
|
||||||
|
.CW -k :
|
||||||
|
.P1
|
||||||
|
$ lp -dpsu -k rice29436.1
|
||||||
|
rice29436.1 removed from psu queue on cetus
|
||||||
|
.P2
|
||||||
|
.NH
|
||||||
|
Options
|
||||||
|
.PP
|
||||||
|
There are options available to modify the way in which a job is handled.
|
||||||
|
It is the job of the
|
||||||
|
.I lp
|
||||||
|
programs to convert the option settings so they may be used by each of the
|
||||||
|
different translation and interface programs.
|
||||||
|
Not all options are applicable to all printer environments.
|
||||||
|
Table 1 lists the standard
|
||||||
|
.I lp
|
||||||
|
options, the shell variable settings, and description of the options.
|
||||||
|
\" .1C
|
||||||
|
.KF
|
||||||
|
.sp
|
||||||
|
.in 0
|
||||||
|
.TS
|
||||||
|
center;
|
||||||
|
c | c s s | c
|
||||||
|
c | c c c | c
|
||||||
|
lfCWp-2 | lfCWp-2 cfCWp-2 cfCWp-2 | lp-2w(3i).
|
||||||
|
=
|
||||||
|
option shell variable action
|
||||||
|
\^ name default set \^
|
||||||
|
_
|
||||||
|
-D DEBUG N 1 turn on debugging mode.
|
||||||
|
_
|
||||||
|
-H NOHEADER N 1 suppress header page.
|
||||||
|
_
|
||||||
|
-L LAND N 1 make long page dimension horizontal.
|
||||||
|
_
|
||||||
|
-M \fImach\fP LPMACHID N \fImach\fP set the source machine name.
|
||||||
|
_
|
||||||
|
-Q QONLY N 1 do not execute daemon; for debugging.
|
||||||
|
_
|
||||||
|
-c \fIn\fP COPIES N \fIn\fP number of copies to be printed.
|
||||||
|
_
|
||||||
|
-d \fIprinter\fP LPDEST U \fIprinter\fP set job destination; override other settings.
|
||||||
|
_
|
||||||
|
-f \fIfont.pt\fP FONT N \fIfont\fP set font style and point size for printing.
|
||||||
|
POINT N \fIpt\fP
|
||||||
|
_
|
||||||
|
-i \fIn\fP IBIN N \fIn\fP T{
|
||||||
|
select input paper tray options.
|
||||||
|
The argument given is dependent on the printer type.
|
||||||
|
A number can be given to select a particular tray and/or
|
||||||
|
.CW simplex
|
||||||
|
or
|
||||||
|
.CW duplex
|
||||||
|
may be used to get single or double sided output, where
|
||||||
|
applicable.
|
||||||
|
Multiple options should be separated by commas.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-k KILLFLAG 0 1 T{
|
||||||
|
take non-option arguments as job numbers to be removed from queue.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-l \fIn\fP LINES N \fIn\fP T{
|
||||||
|
for printed data, the number of lines per logical page.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-m \fIf\fP MAG N \fIf\fP T{
|
||||||
|
magnify the image by a factor \fIf\fP.
|
||||||
|
The factor should be a positive real number.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-n \fIn\fP NPAG N \fIn\fP T{
|
||||||
|
put \fIn\fP logical pages on a single physical page.
|
||||||
|
A simple algorithm is used to pack the pages.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-o \fIlist\fP OLIST N \fIlist\fP T{
|
||||||
|
print only those pages specified in the list.
|
||||||
|
The list may be a sequence of numbers or ranges separated by commas.
|
||||||
|
A range is a pair of numbers separated by a hyphen.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-p \fIproc\fP LPPROC L \fIproc\fP T{
|
||||||
|
use the preprocessor \fIproc\fP instead of the preprocessor given
|
||||||
|
in the
|
||||||
|
.CW devices
|
||||||
|
file for this printer.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-q LPQ N 1 T{
|
||||||
|
print the status and queue.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-r REVERSE L 1 T{
|
||||||
|
this toggles the
|
||||||
|
.CW REVERSE
|
||||||
|
flag, changing whether or not page reversal should occur in preprocessing.
|
||||||
|
Page reversal is needed if a printer delivers pages face up.
|
||||||
|
The keyword
|
||||||
|
.CW reverse
|
||||||
|
can be placed in the
|
||||||
|
.I lpclass
|
||||||
|
field of the
|
||||||
|
.CW devices
|
||||||
|
file.
|
||||||
|
If a document has already been processed this flag has no effect.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-u \fIuser\fP LPUSERID U \fIuser\fP T{
|
||||||
|
change the user id that appears on the cover page.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-x \fIoffset\fP XOFF N \fIoffset\fP T{
|
||||||
|
move the image \fIoffset\fP inches to the right.
|
||||||
|
A negative \fIoffset\fP will move the image to the left.
|
||||||
|
The \fIoffset\fP may be any reasonable real number.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
-y \fIoffset\fP YOFF N \fIoffset\fP T{
|
||||||
|
same as for
|
||||||
|
.CW -x
|
||||||
|
except a positive offset will move the image down.
|
||||||
|
T}
|
||||||
|
_
|
||||||
|
.T&
|
||||||
|
l l cp-2 lp-2 s
|
||||||
|
l l cfCWp-2 lp-2 s.
|
||||||
|
.vs -2p
|
||||||
|
|
||||||
|
default setting definition
|
||||||
|
N set to the null string (`') initially in \fIlp\fP.
|
||||||
|
L set from printer entry in \f(CW\\s-\\n(XPdevices\\s+\\n(XP\fP file.
|
||||||
|
U set from the user's environment.
|
||||||
|
.vs +2p
|
||||||
|
.TE
|
||||||
|
.sp
|
||||||
|
.ce
|
||||||
|
.I "Table 1. Lp Option List"
|
||||||
|
.sp
|
||||||
|
.ll \\n(LLu
|
||||||
|
.KE
|
||||||
|
\" .2C
|
||||||
|
.NH
|
||||||
|
Devices file
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW devices
|
||||||
|
file is found in the spool directory.
|
||||||
|
Each line in the file is composed of 12 fields, separated
|
||||||
|
by tabs or spaces, that describe the attributes
|
||||||
|
of the printer and how it should be serviced.
|
||||||
|
Within the
|
||||||
|
.CW lp
|
||||||
|
command, a shell variable is set for each attribute;
|
||||||
|
the following list describes them:
|
||||||
|
.IP "\f(CW\s-\n(XPLPDEST\s+\n(XP\fP " 12
|
||||||
|
is the name of the device as given to
|
||||||
|
.I lp
|
||||||
|
with the
|
||||||
|
.CW -d
|
||||||
|
option
|
||||||
|
or as specified by the shell environment variable
|
||||||
|
.CW LPDEST
|
||||||
|
or as specified by
|
||||||
|
the file
|
||||||
|
.CW $LPLIB/defdevice .
|
||||||
|
This name is used in creating directories and log files that are associated with
|
||||||
|
the printers operation.
|
||||||
|
.IP "\f(CW\s-\n(XPLOC\s+\n(XP\fP "
|
||||||
|
just describes where the printer is physically located.
|
||||||
|
.IP "\f(CW\s-\n(XPDEST_HOST\s+\n(XP\fP "
|
||||||
|
is the host from which the files are printed.
|
||||||
|
Files may be spooled on other machines before being transferred to the
|
||||||
|
destination host.
|
||||||
|
.IP "\f(CW\s-\n(XPOUT_DEV\s+\n(XP\fP "
|
||||||
|
is the physical device name or network address needed by the printer daemon
|
||||||
|
to connect to the printer.
|
||||||
|
This field depends on the requirements of the daemon and may contain a `\(en'
|
||||||
|
if not required.
|
||||||
|
.IP "\f(CW\s-\n(XPSPEED\s+\n(XP\fP "
|
||||||
|
is the baud rate setting for the port.
|
||||||
|
This field depends on the requirements of the daemon and may contain a `\(en'
|
||||||
|
if not required.
|
||||||
|
.IP "\f(CW\s-\n(XPLPCLASS\s+\n(XP\fP "
|
||||||
|
is used to encode minor printer differences.
|
||||||
|
The keyword
|
||||||
|
.CW reverse
|
||||||
|
is used by some of the preprocessors
|
||||||
|
to reverse the order the pages are printed to accommodate different output
|
||||||
|
trays (either face up or face down).
|
||||||
|
The keyword
|
||||||
|
.CW nohead
|
||||||
|
is used to suppress the header page.
|
||||||
|
This is used for special and color printers.
|
||||||
|
The keyword
|
||||||
|
.CW duplex
|
||||||
|
is used to coax double sided output from duplex printers.
|
||||||
|
.IP "\f(CW\s-\n(XPLPPROC\s+\n(XP\fP "
|
||||||
|
is the command from the
|
||||||
|
.CW LPLIB/process
|
||||||
|
directory to be used to convert input to a format
|
||||||
|
that will be accepted by the device.
|
||||||
|
The preprocessor is invoked by the spooler.
|
||||||
|
.IP "\f(CW\s-\n(XPSPOOLER\s+\n(XP\fP "
|
||||||
|
is the command from the
|
||||||
|
.CW LPLIB/spooler
|
||||||
|
directory which will select files using the
|
||||||
|
.CW SCHED
|
||||||
|
command and invoke the
|
||||||
|
.CW LPPROC
|
||||||
|
command, putting its output
|
||||||
|
into the remote spool directory.
|
||||||
|
The output is sent directly to the spool directory on the
|
||||||
|
destination machine to avoid conflicts when client and
|
||||||
|
server machines share spool directories.
|
||||||
|
.IP "\f(CW\s-\n(XPSTAT\s+\n(XP\fP "
|
||||||
|
is the command from the
|
||||||
|
.CW LPLIB/stat
|
||||||
|
directory that prints the status of the device and the list of jobs
|
||||||
|
waiting on the queue for the device.
|
||||||
|
The status information depends on what is available from the printer
|
||||||
|
and interface software.
|
||||||
|
The queue information should be changed to show information
|
||||||
|
useful in tracking down problems.
|
||||||
|
The
|
||||||
|
.CW SCHED
|
||||||
|
command is used to show the jobs in the order
|
||||||
|
in which they will be printed.
|
||||||
|
.IP "\f(CW\s-\n(XPKILL\s+\n(XP\fP "
|
||||||
|
is the command from the
|
||||||
|
.CW LPLIB/kill
|
||||||
|
that removes jobs from the queue.
|
||||||
|
The jobs to be removed are given as arguments to the
|
||||||
|
.I lp
|
||||||
|
command.
|
||||||
|
When possible, it should also abort the currently running job
|
||||||
|
if it has to be killed.
|
||||||
|
.IP "\f(CW\s-\n(XPDAEMON\s+\n(XP\fP "
|
||||||
|
is the command from the
|
||||||
|
.CW LPLIB/daemon
|
||||||
|
that is meant to run asynchronously to remove
|
||||||
|
jobs from the queue.
|
||||||
|
Jobs may either be passed on to another host or sent to the
|
||||||
|
printing device.
|
||||||
|
.I Lp
|
||||||
|
always tries to start a daemon process when one is specified.
|
||||||
|
.IP "\f(CW\s-\n(XPSCHED\s+\n(XP\fP "
|
||||||
|
is the command from the
|
||||||
|
.CW LPLIB/sched
|
||||||
|
that is used to present the job names to the
|
||||||
|
daemon and stat programs
|
||||||
|
in some order, e.g., first-in-first-out, smallest first.
|
||||||
|
.NH
|
||||||
|
Support programs
|
||||||
|
.PP
|
||||||
|
The following sections describe the basic functions of the programs
|
||||||
|
that are found in the subdirectories of
|
||||||
|
.CW $LPLIB .
|
||||||
|
The programs in a specific directory vary with the
|
||||||
|
type of output device or networks that have to be used.
|
||||||
|
.NH 2
|
||||||
|
Process directory
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW generic
|
||||||
|
preprocessor
|
||||||
|
is the default preprocessor for most printers.
|
||||||
|
It uses the
|
||||||
|
.I file (1)
|
||||||
|
command to determine the format of the input file.
|
||||||
|
The appropriate preprocessor is then selected to transform the
|
||||||
|
file to a format suitable for the printer.
|
||||||
|
.PP
|
||||||
|
Here is a list of some of the preprocessors and
|
||||||
|
a description of their function.
|
||||||
|
A complete list of preprocessors and their descriptions can be found in the manual page
|
||||||
|
.I lp (8).
|
||||||
|
.sp
|
||||||
|
.IP \f(CWdvipost\fP 14
|
||||||
|
Converts TeX or LaTeX output (\f(CW.dvi\fP files) to PostScript
|
||||||
|
.IP \f(CWppost\fP
|
||||||
|
Converts UTF text to PostScript.
|
||||||
|
The default font is Courier with Lucida fonts filling in
|
||||||
|
the remainder of the (available) Unicode character space.
|
||||||
|
.IP \f(CWtr2post\fP
|
||||||
|
Converts (device independent) troff output for the device type
|
||||||
|
.CW utf .
|
||||||
|
See
|
||||||
|
.CW /sys/lib/troff/font/devutf
|
||||||
|
directory for troff font width table descriptions.
|
||||||
|
See also the
|
||||||
|
.CW /sys/lib/postscript/troff
|
||||||
|
directory for mappings of
|
||||||
|
troff
|
||||||
|
.CW UTF
|
||||||
|
character space to PostScript font space.
|
||||||
|
.IP \f(CWp9bitpost\fP
|
||||||
|
Converts Plan 9 bitmaps (see
|
||||||
|
.I bitfile (9.6))
|
||||||
|
to PostScript.
|
||||||
|
.IP \f(CWg3post\fP
|
||||||
|
Converts fax (CCITT-G31 format) to PostScript.
|
||||||
|
.IP \f(CWhpost\fP
|
||||||
|
Does header page processing and page reversal processing, if
|
||||||
|
necessary.
|
||||||
|
Page reversal is done here so the header page always comes
|
||||||
|
out at the beginning of the job.
|
||||||
|
Header page processing is very location-dependent.
|
||||||
|
.NH 2
|
||||||
|
Spool directory
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW generic
|
||||||
|
spooler is responsible for executing the preprocessor
|
||||||
|
and directing its output to a file in the printer's queue.
|
||||||
|
An additional file is created containing information such as the system name,
|
||||||
|
user id, job number, and number of times this job was attempted.
|
||||||
|
.PP
|
||||||
|
Certain printer handling programs do not require separate
|
||||||
|
preprocessing and spooling.
|
||||||
|
For such circumstances a
|
||||||
|
.CW nospool
|
||||||
|
spooler is available that just executes the preprocessing program.
|
||||||
|
The processing and spooling functions are assumed by this program and the output is sent to
|
||||||
|
.CW OUT_DEV
|
||||||
|
or standard output if
|
||||||
|
.CW OUT_DEV
|
||||||
|
is '-'.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW pcclone
|
||||||
|
spooler is used to send print jobs directly to a printer connected
|
||||||
|
to a 386 compatible printer port (See
|
||||||
|
.I lpt (3)).
|
||||||
|
.NH 2
|
||||||
|
Stat directory
|
||||||
|
.PP
|
||||||
|
The function of the shell scripts in the
|
||||||
|
.CW stat
|
||||||
|
directory is to present status information about the
|
||||||
|
printer and its queue.
|
||||||
|
When necessary, the
|
||||||
|
.CW stat
|
||||||
|
scripts may be designed
|
||||||
|
to return information about the local queue as well as the remote queue.
|
||||||
|
This is not done on Plan 9 because many systems share the same queue directory.
|
||||||
|
The scheduler is used to print the queue in the order in which the jobs
|
||||||
|
will be executed.
|
||||||
|
.NH 2
|
||||||
|
Kill directory
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW kill
|
||||||
|
scripts receive command line arguments passed to them by
|
||||||
|
.I lp
|
||||||
|
and remove the job and id files which match the arguments
|
||||||
|
for the particular queue.
|
||||||
|
When a job is killed, the generic kill procedure:
|
||||||
|
.IP 1)
|
||||||
|
kills the daemon for this queue if the job being killed
|
||||||
|
is first in the queue,
|
||||||
|
.IP 2)
|
||||||
|
removes the files associated with the job from the queue,
|
||||||
|
.IP 3)
|
||||||
|
attempts to restart the daemon.
|
||||||
|
.NH 2
|
||||||
|
Daemon directory
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW daemon
|
||||||
|
shell scripts are the last to be invoked by
|
||||||
|
.I lp
|
||||||
|
if the
|
||||||
|
.CW -Q
|
||||||
|
option has not been given.
|
||||||
|
The daemon process is executed asynchronously
|
||||||
|
with its standard output and standard error appended to
|
||||||
|
the printer log file.
|
||||||
|
The log file is described in a subsequent section.
|
||||||
|
Because the daemon runs asynchronously, it must
|
||||||
|
catch signals that could cause it to terminate abnormally.
|
||||||
|
The daemon first checks to see that it is the only one running
|
||||||
|
by using the
|
||||||
|
.CW LOCK
|
||||||
|
program found in the
|
||||||
|
.CW /$cputype/bin/aux
|
||||||
|
directory.
|
||||||
|
The
|
||||||
|
.CW LOCK
|
||||||
|
command creates a
|
||||||
|
.CW LOCK
|
||||||
|
file in the printer's queue directory.
|
||||||
|
The daemon then executes the scheduler to obtain the name of the
|
||||||
|
next job on the queue.
|
||||||
|
.PP
|
||||||
|
The processing of jobs may entail transfer to another host
|
||||||
|
or transmission to a printer.
|
||||||
|
The details of this are specific to the individual daemons.
|
||||||
|
If a job is processed without error, it is removed from the queue.
|
||||||
|
If a job does not succeed, the associated files may be
|
||||||
|
moved to a printer specific directory in
|
||||||
|
.CW $LPLIB/prob .
|
||||||
|
In either case, the daemon can make an entry in the printer's
|
||||||
|
log file.
|
||||||
|
Before exiting, the daemon should clean up lock files by calling
|
||||||
|
.CW UNLOCK .
|
||||||
|
.PP
|
||||||
|
Several non-standard daemon programs have been designed
|
||||||
|
to suit various requirements and whims.
|
||||||
|
One such program announces job completion and empty paper trays
|
||||||
|
by causing icons to appear in peoples'
|
||||||
|
.CW seemail
|
||||||
|
window.
|
||||||
|
Another, using a voice synthesizer, makes verbal announcements.
|
||||||
|
Other daemons may be designed to taste.
|
||||||
|
.NH 2
|
||||||
|
Sched directory
|
||||||
|
.PP
|
||||||
|
The scheduler must decide which job files should be executed and
|
||||||
|
in what order.
|
||||||
|
The most commonly used scheduler program is
|
||||||
|
.CW FIFO ,
|
||||||
|
which looks like this:
|
||||||
|
.P1
|
||||||
|
ls -tr $* | sed -n -e 's/.* *//' \e
|
||||||
|
-e '/^[0-9][0-9]*\.[1-9][0-9]*$/p'
|
||||||
|
.P2
|
||||||
|
This lists all the job files in this printer's queue in modification
|
||||||
|
time order.
|
||||||
|
Jobs entering the queue have a dot (.) prefixed to their name
|
||||||
|
to keep the scheduler from selecting them before they are complete.
|
||||||
|
.NH
|
||||||
|
Where Things Go Wrong
|
||||||
|
.PP
|
||||||
|
There are four directories where
|
||||||
|
.I lp
|
||||||
|
writes files.
|
||||||
|
On the Plan 9 release these directories may be found
|
||||||
|
in a directory on a scratch filesystem that is not
|
||||||
|
backed-up.
|
||||||
|
This directory is
|
||||||
|
.CW /n/emelieother/lp .
|
||||||
|
It is built on top of a file system
|
||||||
|
.CW other
|
||||||
|
that is mounted on the file server
|
||||||
|
.CW emelie .
|
||||||
|
The four directories in
|
||||||
|
this scratch directory
|
||||||
|
are
|
||||||
|
.CW log ,
|
||||||
|
.CW prob ,
|
||||||
|
.CW queue ,
|
||||||
|
and
|
||||||
|
.CW tmp .
|
||||||
|
.I Lp
|
||||||
|
binds (see
|
||||||
|
.I bind (1))
|
||||||
|
the first three into the directory
|
||||||
|
.CW /sys/lib/lp
|
||||||
|
for its processes and their children.
|
||||||
|
The
|
||||||
|
.CW tmp
|
||||||
|
directory is bound to the
|
||||||
|
.CW /tmp
|
||||||
|
directory so that the lp daemons, which run as user `none',
|
||||||
|
may write into this directory.
|
||||||
|
.PP
|
||||||
|
On any new installation, it is important that these directories
|
||||||
|
be set up and that the
|
||||||
|
.I /rc/bin/lp
|
||||||
|
command be editted to reflect the change.
|
||||||
|
If you do not have a scratch filesystem for these directories,
|
||||||
|
create the four directories
|
||||||
|
.CW log ,
|
||||||
|
.CW prob ,
|
||||||
|
.CW queue ,
|
||||||
|
and
|
||||||
|
.CW tmp
|
||||||
|
in
|
||||||
|
.CW $LPLIB
|
||||||
|
.CW (/sys/lib/lp)
|
||||||
|
so that they are writable by anyone.
|
||||||
|
.NH 2
|
||||||
|
Log directory
|
||||||
|
.PP
|
||||||
|
The log files for a particular
|
||||||
|
.I printer
|
||||||
|
appear in a subdirectory of the spool directory
|
||||||
|
\f(CWlog\fP/\fIprinter\fP.
|
||||||
|
There are currently two types of log files.
|
||||||
|
One is for the daemon to log errors and successful completions
|
||||||
|
of jobs.
|
||||||
|
These are named
|
||||||
|
.I printer.day
|
||||||
|
where
|
||||||
|
.I day
|
||||||
|
is the three letter abbreviation for the day of the week.
|
||||||
|
These are overwritten once a week to avoid the need for regular
|
||||||
|
cleanup.
|
||||||
|
The other type of log file contains the status of the printer and
|
||||||
|
is written by the program that communicates with the printer itself.
|
||||||
|
These are named
|
||||||
|
\fIprinter\fP.\f(CWst\fP.
|
||||||
|
These are overwritten with each new job and are saved in the
|
||||||
|
.CW $LPLIB/prob
|
||||||
|
directory along with the job under circumstances described below.
|
||||||
|
When a printer does not appear to be functioning these files are the
|
||||||
|
place to look first.
|
||||||
|
.NH 2
|
||||||
|
Prob directory
|
||||||
|
.PP
|
||||||
|
When a job fails to produce output,
|
||||||
|
the log files should be checked for any obvious problems.
|
||||||
|
If none can be found, a directory with full read and write permissions
|
||||||
|
should be created with the name of the printer in the
|
||||||
|
.CW $LPLIB/prob
|
||||||
|
directory.
|
||||||
|
Subsequent failure of a job will cause the daemon to leave a
|
||||||
|
copy of the job and the printer communication log in
|
||||||
|
\f(CW$LPLIB/prob/\fP\fIprinter\fP
|
||||||
|
directory.
|
||||||
|
It is common for a printer to enter states from which
|
||||||
|
it cannot be rescued except by manually cycling the power on the printer.
|
||||||
|
After this is done the print daemon should recover by itself
|
||||||
|
(give it a minute).
|
||||||
|
If it does not recover, remove the
|
||||||
|
.CW LOCK
|
||||||
|
file from the printer's spool directory to kill the daemon.
|
||||||
|
The daemon will have to be restarted by sending another job
|
||||||
|
to the printer.
|
||||||
|
For PostScript printers just use:
|
||||||
|
.P1
|
||||||
|
echo '%!PS' | lp
|
||||||
|
.P2
|
||||||
|
.NH 2
|
||||||
|
Repairing Stuck Daemons
|
||||||
|
.PP
|
||||||
|
There are conditions that occur which are not handled
|
||||||
|
by the daemons.
|
||||||
|
One such problem can only be described as the printer entering a
|
||||||
|
comatose state.
|
||||||
|
The printer does not respond to any messages sent to it.
|
||||||
|
The daemon should recover from the reset and an error message
|
||||||
|
will appear in the log files.
|
||||||
|
If all else fails, one can kill the first job in the queue
|
||||||
|
or remove the
|
||||||
|
.CW LOCK
|
||||||
|
file from the queue directory.
|
||||||
|
This will kill the daemon, which will have to be restarted.
|
||||||
|
.NH
|
||||||
|
Interprocessor Communication
|
||||||
|
.PP
|
||||||
|
A Plan 9 CPU server can be set up as a printer's spooling host.
|
||||||
|
That is, the machine where jobs are spooled and from which those jobs
|
||||||
|
are sent directly to the printer.
|
||||||
|
To do this, the CPU must listen on TCP port 515 which is the well known
|
||||||
|
port for the BSD line printer daemon.
|
||||||
|
The file
|
||||||
|
.CW /rc/bin/service/tcp515
|
||||||
|
is executed when a call comes in on that port.
|
||||||
|
The Plan 9
|
||||||
|
.CW lpdaemon
|
||||||
|
will accept jobs sent from BSD LPR/LPD systems.
|
||||||
|
The
|
||||||
|
.CW /$cputype/bin/aux/lpdaemon
|
||||||
|
command is executed from the service call and it accepts print jobs, requests for status,
|
||||||
|
and requests to kill jobs.
|
||||||
|
The command
|
||||||
|
.CW /$cputype/bin/aux/lpsend
|
||||||
|
is used to send jobs
|
||||||
|
to other Plan 9 machines and is usually called from
|
||||||
|
within a spooler or daemon script.
|
||||||
|
The command
|
||||||
|
.CW /$cputype/bin/aux/lpdsend
|
||||||
|
is used to send jobs
|
||||||
|
to machines and printers that use the BSD LPR/LPD protocol and is also usually called from
|
||||||
|
within a spooler or daemon script.
|
||||||
|
.NH
|
||||||
|
Acknowledgements
|
||||||
|
.PP
|
||||||
|
Special thanks to Rich Drechsler for supplying and maintaining most of
|
||||||
|
the PostScript translation and interface programs,
|
||||||
|
without which
|
||||||
|
.I lp
|
||||||
|
would be an empty shell.
|
||||||
|
Tomas Rokicki provided the
|
||||||
|
TeX
|
||||||
|
to PostScript
|
||||||
|
translation program.
|
||||||
|
.NH
|
||||||
|
References
|
||||||
|
.LP
|
||||||
|
[Camp86] Ralph Campbell,
|
||||||
|
``4.3BSD Line Printer Spooler Manual'', UNIX System Manager's Manual,
|
||||||
|
May, 1986, Berkeley, CA
|
||||||
|
.br
|
||||||
|
[RFC1179] Request for Comments: 1179, Line Printer Daemon Protocol, Aug 1990
|
||||||
|
.br
|
||||||
|
[Sys5] System V manual, date unknown
|
7513
sys/doc/lp.ps
Normal file
7513
sys/doc/lp.ps
Normal file
File diff suppressed because it is too large
Load diff
1533
sys/doc/mk.ms
Normal file
1533
sys/doc/mk.ms
Normal file
File diff suppressed because it is too large
Load diff
9174
sys/doc/mk.ps
Normal file
9174
sys/doc/mk.ps
Normal file
File diff suppressed because it is too large
Load diff
5
sys/doc/mkdirlist
Normal file
5
sys/doc/mkdirlist
Normal file
|
@ -0,0 +1,5 @@
|
||||||
|
#!/bin/rc
|
||||||
|
# mkdirlist
|
||||||
|
for(i in $*)
|
||||||
|
if(~ $i */*)
|
||||||
|
basename -d $i
|
135
sys/doc/mkfile
Normal file
135
sys/doc/mkfile
Normal file
|
@ -0,0 +1,135 @@
|
||||||
|
# Changes made in this directory are invisible to the
|
||||||
|
# external web server. To publish changed documents
|
||||||
|
# to the external web server, mk install or name.install
|
||||||
|
# To publish changed ps/pdf files, see the install rule.
|
||||||
|
|
||||||
|
< /sys/doc/fonts
|
||||||
|
NPROC = 1
|
||||||
|
|
||||||
|
ALL=\
|
||||||
|
title\
|
||||||
|
trademarks\
|
||||||
|
contents\
|
||||||
|
9\
|
||||||
|
names\
|
||||||
|
net/net\
|
||||||
|
auth\
|
||||||
|
comp\
|
||||||
|
prog4\
|
||||||
|
ape\
|
||||||
|
acidpaper\
|
||||||
|
acid\
|
||||||
|
mk\
|
||||||
|
mkfiles\
|
||||||
|
asm\
|
||||||
|
8½/8½\
|
||||||
|
rc\
|
||||||
|
sam/sam\
|
||||||
|
acme/acme\
|
||||||
|
plumb\
|
||||||
|
utf\
|
||||||
|
compiler\
|
||||||
|
libmach\
|
||||||
|
fs/fs\
|
||||||
|
venti/venti\
|
||||||
|
il/il\
|
||||||
|
lexnames\
|
||||||
|
sleep\
|
||||||
|
lp\
|
||||||
|
troff\
|
||||||
|
spin\
|
||||||
|
port\
|
||||||
|
colophon\
|
||||||
|
|
||||||
|
ALLPS=${ALL:%=%.ps}
|
||||||
|
HTML=${ALL:%=%.html} release3.html release4.html
|
||||||
|
PDF=${ALL:%=%.pdf} release3.pdf release4.pdf
|
||||||
|
FILES=`{mkfilelist $ALL}
|
||||||
|
DIRS=`{mkdirlist $ALL}
|
||||||
|
NAMES=$FILES $DIRS
|
||||||
|
|
||||||
|
all:V: ${FILES:%=%.ps} dirs
|
||||||
|
|
||||||
|
dirs:V:
|
||||||
|
for(i in $DIRS) @{
|
||||||
|
cd $i
|
||||||
|
mk
|
||||||
|
}
|
||||||
|
|
||||||
|
print:V: $ALLPS
|
||||||
|
lp -H -i0 $prereq
|
||||||
|
|
||||||
|
title.ps:D: title
|
||||||
|
troff $prereq | lp -dstdout > $target
|
||||||
|
cleanps $target
|
||||||
|
|
||||||
|
trademarks.ps:D: /sys/lib/man/trademarks
|
||||||
|
troff $prereq | lp -dstdout > $target
|
||||||
|
cleanps $target
|
||||||
|
|
||||||
|
colophon.ps:D: /sys/lib/man/colophon
|
||||||
|
troff $prereq | lp -dstdout > $target
|
||||||
|
cleanps $target
|
||||||
|
|
||||||
|
# troff gets some scary-looking errors but they're okay
|
||||||
|
%.ps:D: %.ms
|
||||||
|
mac=(-ms)
|
||||||
|
if(~ $stem comp utf 9 contents) mac=(-ms -mnihongo)
|
||||||
|
{ echo $FONTS; cat $stem.ms } | pic | tbl | eqn |
|
||||||
|
troff $mac | lp -dstdout > $target
|
||||||
|
cleanps $target
|
||||||
|
|
||||||
|
%.trout:D: %.ms
|
||||||
|
mac=(-ms)
|
||||||
|
if(~ $stem comp utf 9 contents) mac=($mac -mnihongo)
|
||||||
|
{ echo $FONTS; cat $stem.ms } | pic | tbl | eqn |
|
||||||
|
troff $mac > $target
|
||||||
|
|
||||||
|
html:V: $HTML
|
||||||
|
|
||||||
|
9.trout 9.ps 9.html: network.pic
|
||||||
|
|
||||||
|
%.html: /$objtype/bin/htmlroff /sys/lib/tmac/tmac.s
|
||||||
|
|
||||||
|
index.html: contents.html
|
||||||
|
cp contents.html index.html
|
||||||
|
|
||||||
|
&.html:D: &.ms
|
||||||
|
pic $stem.ms | tbl | eqn | htmlroff -ms -mhtml >$target
|
||||||
|
|
||||||
|
pdf:V: $PDF
|
||||||
|
|
||||||
|
^(8½|acme|fs|il|net|sam|venti)/([^/]*\.(pdf|ps|html))'$':R:
|
||||||
|
cd $stem1
|
||||||
|
mk $stem2
|
||||||
|
|
||||||
|
^(8½|acme|fs|il|net|sam|venti)\.html'$':R: \1/\1.html
|
||||||
|
cp $stem1/$stem1.html .
|
||||||
|
|
||||||
|
%.pdf: %.ps
|
||||||
|
cat docfonts $stem.ps >_$stem.ps
|
||||||
|
# distill _$stem.ps && mv _$stem.pdf $stem.pdf
|
||||||
|
ps2pdf _$stem.ps $stem.pdf && rm -f _$stem.ps
|
||||||
|
|
||||||
|
%.all:V:
|
||||||
|
mk $stem.ps $stem.pdf $stem.html
|
||||||
|
|
||||||
|
%.install:V: %.html
|
||||||
|
9fs other
|
||||||
|
files=`{ls $stem.html $stem^*.png $stem/*.png $stem/*.html >[2]/dev/null}
|
||||||
|
whatis stem
|
||||||
|
whatis files
|
||||||
|
cp $files /n/other/crp/sources.copy/sys/doc
|
||||||
|
|
||||||
|
%.page:V: %.ps
|
||||||
|
page -w $stem.ps
|
||||||
|
|
||||||
|
install:V: ${NAMES:%=%.install} release4.install release3.install
|
||||||
|
|
||||||
|
# ignore these
|
||||||
|
IGNHTML=title trademarks colophon troff
|
||||||
|
IGN=${IGNHTML:%=%.html} ${IGNHTML:%=%.install}
|
||||||
|
|
||||||
|
$IGN:QV:
|
||||||
|
# nothing
|
||||||
|
|
5
sys/doc/mkfilelist
Normal file
5
sys/doc/mkfilelist
Normal file
|
@ -0,0 +1,5 @@
|
||||||
|
#!/bin/rc
|
||||||
|
|
||||||
|
for(i in $*)
|
||||||
|
if(! ~ $i */*)
|
||||||
|
echo $i
|
751
sys/doc/mkfiles.ms
Normal file
751
sys/doc/mkfiles.ms
Normal file
|
@ -0,0 +1,751 @@
|
||||||
|
.HTML "Plan 9 Mkfiles
|
||||||
|
.TL
|
||||||
|
Plan 9 Mkfiles
|
||||||
|
.AU
|
||||||
|
Bob Flandrena
|
||||||
|
bobf@plan9.bell-labs.com
|
||||||
|
.SH
|
||||||
|
Introduction
|
||||||
|
.LP
|
||||||
|
Every Plan 9 source directory contains a file, called
|
||||||
|
.CW mkfile ,
|
||||||
|
specifying the rules for building the executable or
|
||||||
|
library that is the product of the directory.
|
||||||
|
.I Mk (1)
|
||||||
|
interprets the rules in the file, calculates
|
||||||
|
the dependencies, and executes an
|
||||||
|
.I rc (1)
|
||||||
|
script to construct the product.
|
||||||
|
If necessary components are supplied by
|
||||||
|
neighboring directories or sub-directories, the mkfiles in those
|
||||||
|
directories are first executed to build the components
|
||||||
|
before the local construction proceeds.
|
||||||
|
.LP
|
||||||
|
Most application source directories produce one of
|
||||||
|
four types of product:
|
||||||
|
a single executable, several
|
||||||
|
executables, a local library, or
|
||||||
|
a system library.
|
||||||
|
Four generic
|
||||||
|
mkfiles
|
||||||
|
define the normal rules
|
||||||
|
for building each type of product. The simplest
|
||||||
|
mkfiles need only
|
||||||
|
list the components
|
||||||
|
and include the appropriate
|
||||||
|
generic
|
||||||
|
mkfile
|
||||||
|
to do the work.
|
||||||
|
More complex
|
||||||
|
mkfiles
|
||||||
|
may supply additional rules
|
||||||
|
to augment, modify, or override the generic rules.
|
||||||
|
.SH
|
||||||
|
Using a Mkfile
|
||||||
|
.LP
|
||||||
|
To build a product, change to the directory containing
|
||||||
|
its source and invoke
|
||||||
|
.I mk
|
||||||
|
with the appropriate target as an argument.
|
||||||
|
All mkfiles provide the following standard targets:
|
||||||
|
.TS
|
||||||
|
lw(1i) lw(4.5i).
|
||||||
|
\f(CWall\fP T{
|
||||||
|
Build a local version of the product or products for the
|
||||||
|
current architecture. If the product is a single program,
|
||||||
|
the result is stored in file
|
||||||
|
.CW $O.out .
|
||||||
|
If the directory produces multiple executables, they are
|
||||||
|
stored in the files named
|
||||||
|
.CW $O.\fIprogname,\fP
|
||||||
|
where
|
||||||
|
.I progname
|
||||||
|
is the name of each executable.
|
||||||
|
A product may be built for a different architecture by
|
||||||
|
prefacing the
|
||||||
|
.CW mk
|
||||||
|
command with
|
||||||
|
\f(CWobjtype=\fP\fIarchitecture\fP,
|
||||||
|
where
|
||||||
|
.I architecture
|
||||||
|
is the name of the target architecture.
|
||||||
|
Directories producing system
|
||||||
|
libraries always operate directly on the installed version of the
|
||||||
|
library; in this case the target
|
||||||
|
.CW all
|
||||||
|
is equivalent to the target
|
||||||
|
.CW install .
|
||||||
|
T}
|
||||||
|
\f(CWinstall\fP T{
|
||||||
|
Build and install the product or products for the current
|
||||||
|
architecture.
|
||||||
|
T}
|
||||||
|
\f(CWinstallall\fP T{
|
||||||
|
Build and install the product or products for all architectures.
|
||||||
|
T}
|
||||||
|
\f(CWclean\fP T{
|
||||||
|
Rid the directory and its subdirectories of the by-products of
|
||||||
|
the build process. Intermediate files that are easily reproduced
|
||||||
|
(e.g., object files,
|
||||||
|
.CW yacc
|
||||||
|
intermediates, target executables) are always
|
||||||
|
removed. Complicated intermediates, such as local libraries, are
|
||||||
|
usually preserved.
|
||||||
|
T}
|
||||||
|
\f(CWnuke\fP T{
|
||||||
|
Remove all intermediates from the directory and any subdirectories.
|
||||||
|
This target guarantees that a subsequent build for the
|
||||||
|
architecture is performed
|
||||||
|
from scratch.
|
||||||
|
T}
|
||||||
|
.TE
|
||||||
|
.LP
|
||||||
|
If no target is specified on the
|
||||||
|
.CW mk
|
||||||
|
command line, the
|
||||||
|
.CW all
|
||||||
|
target is built by default. In a directory
|
||||||
|
producing multiple executables, there is
|
||||||
|
no default target.
|
||||||
|
.LP
|
||||||
|
In addition to the five standard targets,
|
||||||
|
additional targets may be supplied by each
|
||||||
|
generic mkfile or by the directory's mkfile.
|
||||||
|
.LP
|
||||||
|
The environment variable
|
||||||
|
.CW NPROC
|
||||||
|
is set by the system to the number of
|
||||||
|
available processors.
|
||||||
|
Setting
|
||||||
|
this variable, either in the environment or in
|
||||||
|
a mkfile, controls the amount of parallelism in
|
||||||
|
the build. For example, the command
|
||||||
|
.P1
|
||||||
|
NPROC=1 mk
|
||||||
|
.P2
|
||||||
|
restricts a build to a single thread of execution.
|
||||||
|
.SH
|
||||||
|
Creating a Mkfile
|
||||||
|
.LP
|
||||||
|
The easiest way to build a new mkfile is to copy and modify
|
||||||
|
an existing mkfile of the same type.
|
||||||
|
Failing that, it is usually possible to create a new
|
||||||
|
mkfile with minimal effort, since the appropriate
|
||||||
|
generic mkfile predefines the rules that do all the work.
|
||||||
|
In the simplest and most common cases, the new mkfile
|
||||||
|
need only define a couple of variables and include the appropriate
|
||||||
|
architecture-specific
|
||||||
|
and generic mkfiles.
|
||||||
|
.SH The Generic Mkfiles
|
||||||
|
.LP
|
||||||
|
There are four generic mkfiles containing commonly
|
||||||
|
used rules for building a product:
|
||||||
|
.CW mkone ,
|
||||||
|
.CW mkmany ,
|
||||||
|
.CW mklib ,
|
||||||
|
and
|
||||||
|
.CW mksyslib .
|
||||||
|
These rules
|
||||||
|
perform such actions as compiling C source files,
|
||||||
|
loading object files, archiving libraries, and
|
||||||
|
installing executables in the
|
||||||
|
.CW bin
|
||||||
|
directory of the appropriate architecture.
|
||||||
|
The generic mkfiles are stored in directory
|
||||||
|
.CW /sys/src/cmd .
|
||||||
|
Mkfile
|
||||||
|
.CW mkone
|
||||||
|
builds a single executable,
|
||||||
|
.CW mkmany
|
||||||
|
builds several executables from the source in a single
|
||||||
|
directory, and
|
||||||
|
.CW mklib
|
||||||
|
and
|
||||||
|
\f(CWmksyslib\fP,
|
||||||
|
maintain local and system libraries, respectively.
|
||||||
|
The rules in the generic mkfiles are driven by
|
||||||
|
the values of variables, some of which must be
|
||||||
|
set by the product mkfile and some of which are
|
||||||
|
supplied by the generic mkfile. Variables in the
|
||||||
|
latter class include:
|
||||||
|
.TS
|
||||||
|
center;
|
||||||
|
ri ci li
|
||||||
|
rw(1i) cw(0.5i) lw(2i).
|
||||||
|
Variable Default Meaning
|
||||||
|
.sp .5
|
||||||
|
\f(CWCFLAGS\fP \f(CW-FVw\fP C compiler flags
|
||||||
|
\f(CWLDFLAGS\fP Loader flags
|
||||||
|
\f(CWYFLAGS\fP \f(CW-d\fP Yacc flags
|
||||||
|
\f(CWAFLAGS\fP Assembler flags
|
||||||
|
.TE
|
||||||
|
.LP
|
||||||
|
The following variables are set by the product mkfile
|
||||||
|
and used by the generic mkfile.
|
||||||
|
Any may be empty depending on the specific product being
|
||||||
|
made.
|
||||||
|
.TS
|
||||||
|
center;
|
||||||
|
lw(1i) lw(2.5i).
|
||||||
|
\f(CWTARG\fP Name(s) of the executable(s) to be built
|
||||||
|
\f(CWLIB\fP Library name(s)
|
||||||
|
\f(CWOFILES\fP Object files
|
||||||
|
\f(CWHFILES\fP Header files included by all source files
|
||||||
|
\f(CWYFILES\fP \f(CWYacc\fP input files
|
||||||
|
\f(CWBIN\fP Directory where executables are installed
|
||||||
|
.TE
|
||||||
|
.SH
|
||||||
|
Mkfile Organization
|
||||||
|
.LP
|
||||||
|
All
|
||||||
|
mkfiles
|
||||||
|
share the following common structure:
|
||||||
|
.P1
|
||||||
|
</$objtype/mkfile # \f1architecture-dependent definitions\fP
|
||||||
|
.sp
|
||||||
|
\fIvariable definitions\fP # TARG\f1, \fPOFILES\f1, \fPHFILES\f1, etc.\fP
|
||||||
|
.sp
|
||||||
|
</sys/src/cmd/\fIgeneric\fP # mkone\f1, \fPmkmany\f1, \fPmklib\f1, or \fPmksyslib
|
||||||
|
.sp
|
||||||
|
\fIvariable overrides\fP # CFLAGS\f1, \fPobjtype\f1, etc.\fP
|
||||||
|
.sp
|
||||||
|
\fIextra rules\fP # \f1overrides, augmented rules, additional targets\fP
|
||||||
|
.P2
|
||||||
|
Note that the architecture-dependent mkfiles include file
|
||||||
|
.CW /sys/src/mkfile.proto
|
||||||
|
for system-wide variables that are common to all architectures.
|
||||||
|
.LP
|
||||||
|
The variables driving the expansion of the generic mkfile
|
||||||
|
may be specified in any order as long as they are defined
|
||||||
|
before the inclusion of the generic mkfile. The value
|
||||||
|
of a variable may be changed by assigning a new value
|
||||||
|
following the inclusion of the generic mkfile, but the
|
||||||
|
effects are sometimes counter-intuitive.
|
||||||
|
Such variable assignments do not apply to the target and
|
||||||
|
prerequisite portions of any previously defined rules;
|
||||||
|
the new values only apply to the recipes of rules preceding
|
||||||
|
the assignment statement and
|
||||||
|
to all parts of any rules following it.
|
||||||
|
.LP
|
||||||
|
The rules supplied by the generic mkfile may
|
||||||
|
be overridden or augmented. The new rules must
|
||||||
|
be specified after the inclusion of the generic
|
||||||
|
mkfile. If the target and prerequisite portion
|
||||||
|
of the rule exactly match the target and prerequisite
|
||||||
|
portion of a previously defined rule and the new rule contains
|
||||||
|
a recipe, the new rule replaces the old one.
|
||||||
|
If the target of a new rule exactly matches the
|
||||||
|
target of a previous rule and one or more new
|
||||||
|
prerequisites are specified and the new rule contains
|
||||||
|
no recipe, the new prerequisites are added to the prerequisites
|
||||||
|
of the old rule.
|
||||||
|
.LP
|
||||||
|
Following sections discuss
|
||||||
|
each generic mkfile in detail.
|
||||||
|
.SH
|
||||||
|
Mkone
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW mkone
|
||||||
|
generic mkfile contains rules for building
|
||||||
|
a single executable from one or more files
|
||||||
|
in a directory.
|
||||||
|
The variable
|
||||||
|
.CW TARG
|
||||||
|
specifies the name of the executable and
|
||||||
|
variables
|
||||||
|
.CW OFILES
|
||||||
|
and
|
||||||
|
.CW YFILES
|
||||||
|
specify the object files and
|
||||||
|
.CW yacc
|
||||||
|
source files used to build it.
|
||||||
|
.CW HFILES
|
||||||
|
contains the names of the local header files
|
||||||
|
included in all source files.
|
||||||
|
.CW BIN
|
||||||
|
is the name of the directory where the executable
|
||||||
|
is installed.
|
||||||
|
.CW LIB
|
||||||
|
contains the names of local libraries used by the
|
||||||
|
linker. This variable is rarely needed
|
||||||
|
as libraries referenced by a
|
||||||
|
.CW #pragma
|
||||||
|
directive in an associated header file, including
|
||||||
|
all system libraries, are automatically
|
||||||
|
searched by the loader.
|
||||||
|
.LP
|
||||||
|
If
|
||||||
|
.CW mk
|
||||||
|
is executed without a target, the
|
||||||
|
.CW all
|
||||||
|
target is built; it
|
||||||
|
produces an executable in
|
||||||
|
.CW $O.out .
|
||||||
|
Variable
|
||||||
|
.CW HFILES
|
||||||
|
identifies the header files that
|
||||||
|
are included in all or most or
|
||||||
|
the C source files. Occasionally,
|
||||||
|
a program has other header files
|
||||||
|
that are only used in some
|
||||||
|
source files. A
|
||||||
|
header can be added to the prerequisites for
|
||||||
|
those object files by adding a rule of
|
||||||
|
the following form following the inclusion of generic mkfile
|
||||||
|
.CW mkone :
|
||||||
|
.P1
|
||||||
|
file.$O: header.h
|
||||||
|
.P2
|
||||||
|
.LP
|
||||||
|
The mkfile for a directory producing a single
|
||||||
|
executable using the normal set of rules is
|
||||||
|
trivial: a list of some files followed by the
|
||||||
|
inclusion of
|
||||||
|
.I mkone.
|
||||||
|
For example,
|
||||||
|
.CW /sys/src/cmd/diff/mkfile
|
||||||
|
contains:
|
||||||
|
.P1
|
||||||
|
< /$objtype/mkfile
|
||||||
|
|
||||||
|
TARG=diff
|
||||||
|
OFILES=\e
|
||||||
|
diffdir.$O\e
|
||||||
|
diffio.$O\e
|
||||||
|
diffreg.$O\e
|
||||||
|
main.$O\e
|
||||||
|
|
||||||
|
HFILES=diff.h
|
||||||
|
|
||||||
|
BIN=/$objtype/bin
|
||||||
|
</sys/src/cmd/mkone
|
||||||
|
.P2
|
||||||
|
The more complex mkfile in
|
||||||
|
.CW /sys/src/cmd/awk
|
||||||
|
overrides compiler and loader variables to
|
||||||
|
select the ANSI/POSIX Computing Environment with appropriately
|
||||||
|
defined command line variables. It also overrides
|
||||||
|
the default
|
||||||
|
.CW yacc
|
||||||
|
rule to place the output soure in file
|
||||||
|
.CW awkgram.c
|
||||||
|
and the
|
||||||
|
.CW clean
|
||||||
|
and
|
||||||
|
.CW nuke
|
||||||
|
rules, so it can remove the non-standard intermediate
|
||||||
|
files. Finally, the last three rules build a version of
|
||||||
|
.CW maketab
|
||||||
|
appropriate for the architecture where the
|
||||||
|
.CW mk
|
||||||
|
is being
|
||||||
|
run and then executes it to create source file
|
||||||
|
.CW proctab.c :
|
||||||
|
.P1
|
||||||
|
</$objtype/mkfile
|
||||||
|
|
||||||
|
TARG=awk
|
||||||
|
OFILES=re.$O\e
|
||||||
|
lex.$O\e
|
||||||
|
main.$O\e
|
||||||
|
parse.$O\e
|
||||||
|
proctab.$O\e
|
||||||
|
tran.$O\e
|
||||||
|
lib.$O\e
|
||||||
|
run.$O\e
|
||||||
|
awkgram.$O\e
|
||||||
|
|
||||||
|
HFILES=awk.h\e
|
||||||
|
y.tab.h\e
|
||||||
|
proto.h\e
|
||||||
|
|
||||||
|
YFILES=awkgram.y
|
||||||
|
|
||||||
|
BIN=/$objtype/bin
|
||||||
|
</sys/src/cmd/mkone
|
||||||
|
CFLAGS=-c -D_REGEXP_EXTENSION -D_RESEARCH_SOURCE \e
|
||||||
|
-D_BSD_EXTENSION -DUTF
|
||||||
|
YFLAGS=-S -d -v
|
||||||
|
CC=pcc
|
||||||
|
LD=pcc
|
||||||
|
cpuobjtype=`{sed -n 's/^O=//p' /$cputype/mkfile}
|
||||||
|
|
||||||
|
y.tab.h awkgram.c: $YFILES
|
||||||
|
$YACC -o awkgram.c $YFLAGS $prereq
|
||||||
|
|
||||||
|
clean:V:
|
||||||
|
rm -f *.[$OS] [$OS].out [$OS].maketab y.tab.? y.debug\e
|
||||||
|
y.output $TARG
|
||||||
|
|
||||||
|
nuke:V:
|
||||||
|
rm -f *.[$OS] [$OS].out [$OS].maketab y.tab.? y.debug\e
|
||||||
|
y.output awkgram.c $TARG
|
||||||
|
|
||||||
|
proctab.c: $cpuobjtype.maketab
|
||||||
|
./$cpuobjtype.maketab >proctab.c
|
||||||
|
|
||||||
|
$cpuobjtype.maketab: y.tab.h maketab.c
|
||||||
|
objtype=$cputype
|
||||||
|
mk maketab.$cputype
|
||||||
|
|
||||||
|
maketab.$cputype:V: y.tab.h maketab.$O
|
||||||
|
$LD -o $O.maketab maketab.$O
|
||||||
|
.P2
|
||||||
|
.SH
|
||||||
|
Mkmany
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW mkmany
|
||||||
|
generic mkfile builds several
|
||||||
|
executables from the files in a
|
||||||
|
directory. It differs from the operation of
|
||||||
|
.CW mkone
|
||||||
|
in three respects:
|
||||||
|
.CW TARG
|
||||||
|
specifies the names of all executables,
|
||||||
|
there is no default command-line target,
|
||||||
|
and additional rules allow a single executable to
|
||||||
|
be built or installed.
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW TARG
|
||||||
|
variable specifies the names of all
|
||||||
|
executables produced by the mkfile. The
|
||||||
|
rules assume the name of each executable is also
|
||||||
|
the name of the file containing its
|
||||||
|
.CW main
|
||||||
|
function.
|
||||||
|
.CW OFILES
|
||||||
|
specifies files containing
|
||||||
|
common subroutines loaded with all executables.
|
||||||
|
Consider the mkfile:
|
||||||
|
.P1
|
||||||
|
</$objtype/mkfile
|
||||||
|
|
||||||
|
TARG=alpha beta
|
||||||
|
OFILES=common.$O
|
||||||
|
BIN=/$objtype/bin
|
||||||
|
</sys/src/cmd/mkmany
|
||||||
|
.P2
|
||||||
|
It assumes the main functions for executables
|
||||||
|
.CW alpha
|
||||||
|
and
|
||||||
|
.CW beta
|
||||||
|
are in files
|
||||||
|
.CW alpha.$O
|
||||||
|
and
|
||||||
|
.CW beta.$O
|
||||||
|
and that both programs use the subroutines
|
||||||
|
in file
|
||||||
|
.CW common.$O .
|
||||||
|
The
|
||||||
|
.CW all
|
||||||
|
target builds all executables, leaving each in
|
||||||
|
a file with a name of the form
|
||||||
|
.CW $O.\fIprogname\fP
|
||||||
|
where
|
||||||
|
.I progname
|
||||||
|
is the name of the executable. In this
|
||||||
|
example the
|
||||||
|
.CW all
|
||||||
|
target produces executables
|
||||||
|
.CW $O.alpha
|
||||||
|
and
|
||||||
|
.CW $O.beta .
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW mkmany
|
||||||
|
rules provide additional
|
||||||
|
targets for building a single
|
||||||
|
executable:
|
||||||
|
.TS
|
||||||
|
lw(1i) lw(3.8i).
|
||||||
|
\f(CW$O.progname\fP T{
|
||||||
|
Builds executable
|
||||||
|
\f(CW$O.\fP\fIprogname\fP
|
||||||
|
in the current directory. When the target
|
||||||
|
architecture is not the current architecture
|
||||||
|
the
|
||||||
|
.CW mk
|
||||||
|
command
|
||||||
|
must be prefixed with the customary
|
||||||
|
.CW objtype=\fIarchitecture\fP
|
||||||
|
assignment to select the proper compilers and loaders.
|
||||||
|
T}
|
||||||
|
\f(CWprogname.install\fP T{
|
||||||
|
Installs executable
|
||||||
|
.I progname
|
||||||
|
for the target architecture.
|
||||||
|
T}
|
||||||
|
\f(CWprogname.installall\fP T{
|
||||||
|
Installs executable
|
||||||
|
.I progname
|
||||||
|
for all architectures.
|
||||||
|
T}
|
||||||
|
.TE
|
||||||
|
.SH
|
||||||
|
Mklib
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW mklib
|
||||||
|
generic mkfile builds a local library.
|
||||||
|
Since this form of mkfile constructs no
|
||||||
|
executable, the
|
||||||
|
.CW TARG
|
||||||
|
and
|
||||||
|
.CW BIN
|
||||||
|
variables are not needed. Instead, the
|
||||||
|
.CW LIB
|
||||||
|
variable specifies the library
|
||||||
|
to be built or updated. Variable
|
||||||
|
.CW OFILES
|
||||||
|
contains the names of the object files to be archived
|
||||||
|
in the library. The use of variables
|
||||||
|
.CW YFILES
|
||||||
|
and
|
||||||
|
.CW HFILES
|
||||||
|
does not change. When possible, only the
|
||||||
|
out-of-date members of the library are updated.
|
||||||
|
.LP
|
||||||
|
The variable
|
||||||
|
.CW LIBDIR
|
||||||
|
contains the name of the directory where the
|
||||||
|
library is installed; by default it selects
|
||||||
|
the current directory. It can be overridden
|
||||||
|
by assigning the new directory name after the
|
||||||
|
point where
|
||||||
|
.CW mklib
|
||||||
|
is included.
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW clean
|
||||||
|
target removes object files and
|
||||||
|
.CW yacc
|
||||||
|
intermediate files but does not touch the
|
||||||
|
library. The
|
||||||
|
.CW nuke
|
||||||
|
target removes the library as well as the
|
||||||
|
files removed by the
|
||||||
|
.CW clean
|
||||||
|
target. The command
|
||||||
|
.RS
|
||||||
|
.CW "mk -s clean all"
|
||||||
|
.RE
|
||||||
|
causes the existing library to be updated, or
|
||||||
|
created if it doesn't already exist. The command
|
||||||
|
.RS
|
||||||
|
.CW "mk -s nuke all"
|
||||||
|
.RE
|
||||||
|
forces the library to be rebuilt from scratch.
|
||||||
|
.LP
|
||||||
|
The mkfile from
|
||||||
|
.CW /sys/src/cmd/upas/libString
|
||||||
|
contains the following specifications to
|
||||||
|
build the local library
|
||||||
|
.CW libString.a$O
|
||||||
|
for the object architecture referenced by
|
||||||
|
.CW $O\fR\:\fP
|
||||||
|
.P1
|
||||||
|
</$objtype/mkfile
|
||||||
|
|
||||||
|
LIB=libString.a$O
|
||||||
|
OFILES= s_alloc.$O\e
|
||||||
|
s_append.$O\e
|
||||||
|
s_array.$O\e
|
||||||
|
s_copy.$O\e
|
||||||
|
s_getline.$O\e
|
||||||
|
s_grow.$O\e
|
||||||
|
s_nappend.$O\e
|
||||||
|
s_parse.$O\e
|
||||||
|
s_read.$O\e
|
||||||
|
s_read_line.$O\e
|
||||||
|
s_tolower.$O\e
|
||||||
|
|
||||||
|
</sys/src/cmd/mklib
|
||||||
|
|
||||||
|
nuke:V:
|
||||||
|
mk clean
|
||||||
|
rm -f libString.a[$OS]
|
||||||
|
.P2
|
||||||
|
The override of the rule for target
|
||||||
|
.CW nuke
|
||||||
|
removes the libraries for all architectures as
|
||||||
|
opposed to the default recipe for this target
|
||||||
|
which removes the library for the current architecture.
|
||||||
|
.SH
|
||||||
|
Mksyslib
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.CW mksyslib
|
||||||
|
generic mkfile is similar to the
|
||||||
|
.CW mklib
|
||||||
|
mkfile except that it operates on a system library
|
||||||
|
instead of a local library.
|
||||||
|
The
|
||||||
|
.CW install
|
||||||
|
and
|
||||||
|
.CW all
|
||||||
|
targets are the same; since there is no local copy of
|
||||||
|
the library, all updates are performed on the
|
||||||
|
installed library.
|
||||||
|
The rule for the
|
||||||
|
.CW nuke
|
||||||
|
target is identical to that of the
|
||||||
|
.CW clean
|
||||||
|
target; unlike the
|
||||||
|
.CW nuke
|
||||||
|
target for local libraries,
|
||||||
|
the library is never removed.
|
||||||
|
.LP
|
||||||
|
No attempt is made to determine if individual library
|
||||||
|
members are up-to-date; all members of a
|
||||||
|
library are always updated.
|
||||||
|
Special targets support manipulation of a single
|
||||||
|
object file; the target
|
||||||
|
.CW objfile
|
||||||
|
updates file
|
||||||
|
.CW objfile\f(CW.$O\fP
|
||||||
|
in the library of the current architecture and the target
|
||||||
|
.CW objfile.all
|
||||||
|
updates
|
||||||
|
.CW objfile\f(CW.$O\fP
|
||||||
|
in the libraries of all architectures.
|
||||||
|
.SH
|
||||||
|
Overrides
|
||||||
|
.LP
|
||||||
|
The rules provided by a generic mkfile or
|
||||||
|
the variables used to control the evaluation
|
||||||
|
of those rules may be overridden in most
|
||||||
|
circumstances. Overrides
|
||||||
|
must be specified in the product mkfile
|
||||||
|
after the point where the generic
|
||||||
|
mkfile is included; in general, variable
|
||||||
|
and rule overrides occupy the end of a
|
||||||
|
product mkfile.
|
||||||
|
.LP
|
||||||
|
The value of a variable is overridden by
|
||||||
|
assigning a new value to the variable.
|
||||||
|
Most variable overrides modify the
|
||||||
|
values of flags or the names of commands executed
|
||||||
|
in recipes. For example, the default value of
|
||||||
|
.CW CFLAGS
|
||||||
|
is often overridden or augmented and
|
||||||
|
the ANSI/POSIX Computing Environment is selected by
|
||||||
|
setting the
|
||||||
|
.CW CC
|
||||||
|
and
|
||||||
|
.CW LD
|
||||||
|
variables to
|
||||||
|
.CW pcc.
|
||||||
|
.LP
|
||||||
|
Modifying rules is trickier than modifying
|
||||||
|
variables. Additional constraints can be added
|
||||||
|
to a rule by specifying the target and
|
||||||
|
the new prerequisite. For example,
|
||||||
|
.P1
|
||||||
|
%.$O: header.h
|
||||||
|
.P2
|
||||||
|
adds file
|
||||||
|
.CW header.h
|
||||||
|
the set of prerequisites for all object files.
|
||||||
|
There is no mechanism for adding additional
|
||||||
|
commands to an existing recipe; if a
|
||||||
|
recipe is unsatisfactory, the rule and its recipe
|
||||||
|
must be completely overridden.
|
||||||
|
A rule is overridden only when the replacement rule
|
||||||
|
matches the target and prerequisite portions
|
||||||
|
of the original rule exactly. The recipe
|
||||||
|
associated with the new rule
|
||||||
|
then replaces the recipe of the original rule.
|
||||||
|
For example,
|
||||||
|
.CW /sys/src/cmd/lex/mkfile
|
||||||
|
overrides the default
|
||||||
|
.CW installall
|
||||||
|
rule to perform the normal loop on all
|
||||||
|
architectures and then copy a prototype file
|
||||||
|
to the system library directory.
|
||||||
|
.P1
|
||||||
|
</$objtype/mkfile
|
||||||
|
|
||||||
|
TARG=lex
|
||||||
|
OFILES=lmain.$O\e
|
||||||
|
y.tab.$O\e
|
||||||
|
sub1.$O\e
|
||||||
|
sub2.$O\e
|
||||||
|
header.$O\e
|
||||||
|
|
||||||
|
HFILES=ldefs.h\e
|
||||||
|
|
||||||
|
YFILES=parser.y\e
|
||||||
|
|
||||||
|
BIN=/$objtype/bin
|
||||||
|
</sys/src/cmd/mkone
|
||||||
|
|
||||||
|
installall:V:
|
||||||
|
for(objtype in $CPUS)
|
||||||
|
mk install
|
||||||
|
cp ncform /sys/lib/lex
|
||||||
|
.P2
|
||||||
|
Another way to perform the same override is to
|
||||||
|
add a dependency to the default
|
||||||
|
.CW installall
|
||||||
|
rule that executes an additional rule to
|
||||||
|
install the prototype file:
|
||||||
|
.P1
|
||||||
|
installall:V: ncform.install
|
||||||
|
|
||||||
|
ncform.install:V:
|
||||||
|
cp ncform /sys/lib/lex
|
||||||
|
.P2
|
||||||
|
.SH
|
||||||
|
Special Tricks
|
||||||
|
.LP
|
||||||
|
Two special cases
|
||||||
|
require extra deviousness.
|
||||||
|
.LP
|
||||||
|
In the first, a file needed to build an
|
||||||
|
executable is generated by a program that,
|
||||||
|
in turn, is built from a source file that
|
||||||
|
is not part of the product. In this case,
|
||||||
|
the
|
||||||
|
executable must be built for the
|
||||||
|
target architecture, but the intermediate
|
||||||
|
executable must be built for the architecture
|
||||||
|
.CW mk
|
||||||
|
is executing on. The intermediate executable
|
||||||
|
is built by recursively invoking
|
||||||
|
.CW mk
|
||||||
|
with the appropriate target and the
|
||||||
|
executing architecture as the target
|
||||||
|
architecture. When that
|
||||||
|
.CW mk
|
||||||
|
completes, the intermediate is
|
||||||
|
executed to generate the source file to
|
||||||
|
complete the build for the target architecture.
|
||||||
|
The earlier example of
|
||||||
|
.CW /sys/src/cmd/awk/mkfile
|
||||||
|
illustrates this technique.
|
||||||
|
.LP
|
||||||
|
Another awkward situation
|
||||||
|
occurs when a directory contains
|
||||||
|
source to build an executable as
|
||||||
|
well as source for auxiliary executables
|
||||||
|
that are not to be installed. In this case
|
||||||
|
the
|
||||||
|
.CW mkmany
|
||||||
|
generic rules are inappropriate, because
|
||||||
|
all executables would be built and installed.
|
||||||
|
Instead, use the
|
||||||
|
.CW mkone
|
||||||
|
generic file to build the primary executable
|
||||||
|
and provide extra targets to
|
||||||
|
build the auxiliary files. This
|
||||||
|
approach is also useful when the auxiliary
|
||||||
|
files are not executables;
|
||||||
|
.CW /sys/src/cmd/spell/mkfile
|
||||||
|
augments the default rules to build and install the
|
||||||
|
.CW spell
|
||||||
|
executable with
|
||||||
|
elaborate rules to generate
|
||||||
|
and maintain the auxiliary spelling lists.
|
6312
sys/doc/mkfiles.ps
Normal file
6312
sys/doc/mkfiles.ps
Normal file
File diff suppressed because it is too large
Load diff
674
sys/doc/names.ms
Normal file
674
sys/doc/names.ms
Normal file
|
@ -0,0 +1,674 @@
|
||||||
|
.HTML "The Use of Name Spaces in Plan 9
|
||||||
|
.TL
|
||||||
|
The Use of Name Spaces in Plan 9
|
||||||
|
.AU
|
||||||
|
Rob Pike
|
||||||
|
Dave Presotto
|
||||||
|
Ken Thompson
|
||||||
|
Howard Trickey
|
||||||
|
Phil Winterbottom
|
||||||
|
.AI
|
||||||
|
.MH
|
||||||
|
USA
|
||||||
|
.AB
|
||||||
|
.FS
|
||||||
|
Appeared in
|
||||||
|
.I
|
||||||
|
Operating Systems Review,
|
||||||
|
.R
|
||||||
|
Vol. 27, #2, April 1993, pp. 72-76
|
||||||
|
(reprinted from
|
||||||
|
.I
|
||||||
|
Proceedings of the 5th ACM SIGOPS European Workshop,
|
||||||
|
.R
|
||||||
|
Mont Saint-Michel, 1992, Paper nº 34).
|
||||||
|
.FE
|
||||||
|
Plan 9 is a distributed system built at the Computing Sciences Research
|
||||||
|
Center of AT&T Bell Laboratories (now Lucent Technologies, Bell Labs) over the last few years.
|
||||||
|
Its goal is to provide a production-quality system for software
|
||||||
|
development and general computation using heterogeneous hardware
|
||||||
|
and minimal software. A Plan 9 system comprises CPU and file
|
||||||
|
servers in a central location connected together by fast networks.
|
||||||
|
Slower networks fan out to workstation-class machines that serve as
|
||||||
|
user terminals. Plan 9 argues that given a few carefully
|
||||||
|
implemented abstractions
|
||||||
|
it is possible to
|
||||||
|
produce a small operating system that provides support for the largest systems
|
||||||
|
on a variety of architectures and networks. The foundations of the system are
|
||||||
|
built on two ideas: a per-process name space and a simple message-oriented
|
||||||
|
file system protocol.
|
||||||
|
.AE
|
||||||
|
.PP
|
||||||
|
The operating system for the CPU servers and terminals is
|
||||||
|
structured as a traditional kernel: a single compiled image
|
||||||
|
containing code for resource management, process control,
|
||||||
|
user processes,
|
||||||
|
virtual memory, and I/O. Because the file server is a separate
|
||||||
|
machine, the file system is not compiled in, although the management
|
||||||
|
of the name space, a per-process attribute, is.
|
||||||
|
The entire kernel for the multiprocessor SGI Power Series machine
|
||||||
|
is 25000 lines of C,
|
||||||
|
the largest part of which is code for four networks including the
|
||||||
|
Ethernet with the Internet protocol suite.
|
||||||
|
Fewer than 1500 lines are machine-specific, and a
|
||||||
|
functional kernel with minimal I/O can be put together from
|
||||||
|
source files totaling 6000 lines. [Pike90]
|
||||||
|
.PP
|
||||||
|
The system is relatively small for several reasons.
|
||||||
|
First, it is all new: it has not had time to accrete as many fixes
|
||||||
|
and features as other systems.
|
||||||
|
Also, other than the network protocol, it adheres to no
|
||||||
|
external interface; in particular, it is not Unix-compatible.
|
||||||
|
Economy stems from careful selection of services and interfaces.
|
||||||
|
Finally, wherever possible the system is built around
|
||||||
|
two simple ideas:
|
||||||
|
every resource in the system, either local or remote,
|
||||||
|
is represented by a hierarchical file system; and
|
||||||
|
a user or process
|
||||||
|
assembles a private view of the system by constructing a file
|
||||||
|
.I
|
||||||
|
name space
|
||||||
|
.R
|
||||||
|
that connects these resources. [Needham]
|
||||||
|
.SH
|
||||||
|
File Protocol
|
||||||
|
.PP
|
||||||
|
All resources in Plan 9 look like file systems.
|
||||||
|
That does not mean that they are repositories for
|
||||||
|
permanent files on disk, but that the interface to them
|
||||||
|
is file-oriented: finding files (resources) in a hierarchical
|
||||||
|
name tree, attaching to them by name, and accessing their contents
|
||||||
|
by read and write calls.
|
||||||
|
There are dozens of file system types in Plan 9, but only a few
|
||||||
|
represent traditional files.
|
||||||
|
At this level of abstraction, files in Plan 9 are similar
|
||||||
|
to objects, except that files are already provided with naming,
|
||||||
|
access, and protection methods that must be created afresh for
|
||||||
|
objects. Object-oriented readers may approach the rest of this
|
||||||
|
paper as a study in how to make objects look like files.
|
||||||
|
.PP
|
||||||
|
The interface to file systems is defined by a protocol, called 9P,
|
||||||
|
analogous but not very similar to the NFS protocol.
|
||||||
|
The protocol talks about files, not blocks; given a connection to the root
|
||||||
|
directory of a file server,
|
||||||
|
the 9P messages navigate the file hierarchy, open files for I/O,
|
||||||
|
and read or write arbitrary bytes in the files.
|
||||||
|
9P contains 17 message types: three for
|
||||||
|
initializing and
|
||||||
|
authenticating a connection and fourteen for manipulating objects.
|
||||||
|
The messages are generated by the kernel in response to user- or
|
||||||
|
kernel-level I/O requests.
|
||||||
|
Here is a quick tour of the major message types.
|
||||||
|
The
|
||||||
|
.CW auth
|
||||||
|
and
|
||||||
|
.CW attach
|
||||||
|
messages authenticate a connection, established by means outside 9P,
|
||||||
|
and validate its user.
|
||||||
|
The result is an authenticated
|
||||||
|
.I channel
|
||||||
|
that points to the root of the
|
||||||
|
server.
|
||||||
|
The
|
||||||
|
.CW clone
|
||||||
|
message makes a new channel identical to an existing channel,
|
||||||
|
which may be moved to a file on the server using a
|
||||||
|
.CW walk
|
||||||
|
message to descend each level in the hierarchy.
|
||||||
|
The
|
||||||
|
.CW stat
|
||||||
|
and
|
||||||
|
.CW wstat
|
||||||
|
messages read and write the attributes of the file pointed to by a channel.
|
||||||
|
The
|
||||||
|
.CW open
|
||||||
|
message prepares a channel for subsequent
|
||||||
|
.CW read
|
||||||
|
and
|
||||||
|
.CW write
|
||||||
|
messages to access the contents of the file, while
|
||||||
|
.CW create
|
||||||
|
and
|
||||||
|
.CW remove
|
||||||
|
perform, on the files, the actions implied by their names.
|
||||||
|
The
|
||||||
|
.CW clunk
|
||||||
|
message discards a channel without affecting the file.
|
||||||
|
None of the 9P messages consider caching; file caches are provided,
|
||||||
|
when needed, either within the server (centralized caching)
|
||||||
|
or by implementing the cache as a transparent file system between the
|
||||||
|
client and the 9P connection to the server (client caching).
|
||||||
|
.PP
|
||||||
|
For efficiency, the connection to local
|
||||||
|
kernel-resident file systems, misleadingly called
|
||||||
|
.I devices,
|
||||||
|
is by regular rather than remote procedure calls.
|
||||||
|
The procedures map one-to-one with 9P message types.
|
||||||
|
Locally each channel has an associated data structure
|
||||||
|
that holds a type field used to index
|
||||||
|
a table of procedure calls, one set per file system type,
|
||||||
|
analogous to selecting the method set for an object.
|
||||||
|
One kernel-resident file system, the
|
||||||
|
.I
|
||||||
|
mount device,
|
||||||
|
.R
|
||||||
|
translates the local 9P procedure calls into RPC messages to
|
||||||
|
remote services over a separately provided transport protocol
|
||||||
|
such as TCP or IL, a new reliable datagram protocol, or over a pipe to
|
||||||
|
a user process.
|
||||||
|
Write and read calls transmit the messages over the transport layer.
|
||||||
|
The mount device is the sole bridge between the procedural
|
||||||
|
interface seen by user programs and remote and user-level services.
|
||||||
|
It does all associated marshaling, buffer
|
||||||
|
management, and multiplexing and is
|
||||||
|
the only integral RPC mechanism in Plan 9.
|
||||||
|
The mount device is in effect a proxy object.
|
||||||
|
There is no RPC stub compiler; instead the mount driver and
|
||||||
|
all servers just share a library that packs and unpacks 9P messages.
|
||||||
|
.SH
|
||||||
|
Examples
|
||||||
|
.PP
|
||||||
|
One file system type serves
|
||||||
|
permanent files from the main file server,
|
||||||
|
a stand-alone multiprocessor system with a
|
||||||
|
350-gigabyte
|
||||||
|
optical WORM jukebox that holds the data, fronted by a two-level
|
||||||
|
block cache comprising 7 gigabytes of
|
||||||
|
magnetic disk and 128 megabytes of RAM.
|
||||||
|
Clients connect to the file server using any of a variety of
|
||||||
|
networks and protocols and access files using 9P.
|
||||||
|
The file server runs a distinct operating system and has no
|
||||||
|
support for user processes; other than a restricted set of commands
|
||||||
|
available on the console, all it does is answer 9P messages from clients.
|
||||||
|
.PP
|
||||||
|
Once a day, at 5:00 AM,
|
||||||
|
the file server sweeps through the cache blocks and marks dirty blocks
|
||||||
|
copy-on-write.
|
||||||
|
It creates a copy of the root directory
|
||||||
|
and labels it with the current date, for example
|
||||||
|
.CW 1995/0314 .
|
||||||
|
It then starts a background process to copy the dirty blocks to the WORM.
|
||||||
|
The result is that the server retains an image of the file system as it was
|
||||||
|
early each morning.
|
||||||
|
The set of old root directories is accessible using 9P, so a client
|
||||||
|
may examine backup files using ordinary commands.
|
||||||
|
Several advantages stem from having the backup service implemented
|
||||||
|
as a plain file system.
|
||||||
|
Most obviously, ordinary commands can access them.
|
||||||
|
For example, to see when a bug was fixed
|
||||||
|
.P1
|
||||||
|
grep 'mouse bug fix' 1995/*/sys/src/cmd/8½/file.c
|
||||||
|
.P2
|
||||||
|
The owner, access times, permissions, and other properties of the
|
||||||
|
files are also backed up.
|
||||||
|
Because it is a file system, the backup
|
||||||
|
still has protections;
|
||||||
|
it is not possible to subvert security by looking at the backup.
|
||||||
|
.PP
|
||||||
|
The file server is only one type of file system.
|
||||||
|
A number of unusual services are provided within the kernel as
|
||||||
|
local file systems.
|
||||||
|
These services are not limited to I/O devices such
|
||||||
|
as disks. They include network devices and their associated protocols,
|
||||||
|
the bitmap display and mouse,
|
||||||
|
a representation of processes similar to
|
||||||
|
.CW /proc
|
||||||
|
[Killian], the name/value pairs that form the `environment'
|
||||||
|
passed to a new process, profiling services,
|
||||||
|
and other resources.
|
||||||
|
Each of these is represented as a file system \(em
|
||||||
|
directories containing sets of files \(em
|
||||||
|
but the constituent files do not represent permanent storage on disk.
|
||||||
|
Instead, they are closer in properties to UNIX device files.
|
||||||
|
.PP
|
||||||
|
For example, the
|
||||||
|
.I console
|
||||||
|
device contains the file
|
||||||
|
.CW /dev/cons ,
|
||||||
|
similar to the UNIX file
|
||||||
|
.CW /dev/console :
|
||||||
|
when written,
|
||||||
|
.CW /dev/cons
|
||||||
|
appends to the console typescript; when read,
|
||||||
|
it returns characters typed on the keyboard.
|
||||||
|
Other files in the console device include
|
||||||
|
.CW /dev/time ,
|
||||||
|
the number of seconds since the epoch,
|
||||||
|
.CW /dev/cputime ,
|
||||||
|
the computation time used by the process reading the device,
|
||||||
|
.CW /dev/pid ,
|
||||||
|
the process id of the process reading the device, and
|
||||||
|
.CW /dev/user ,
|
||||||
|
the login name of the user accessing the device.
|
||||||
|
All these files contain text, not binary numbers,
|
||||||
|
so their use is free of byte-order problems.
|
||||||
|
Their contents are synthesized on demand when read; when written,
|
||||||
|
they cause modifications to kernel data structures.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.I process
|
||||||
|
device contains one directory per live local process, named by its numeric
|
||||||
|
process id:
|
||||||
|
.CW /proc/1 ,
|
||||||
|
.CW /proc/2 ,
|
||||||
|
etc.
|
||||||
|
Each directory contains a set of files that access the process.
|
||||||
|
For example, in each directory the file
|
||||||
|
.CW mem
|
||||||
|
is an image of the virtual memory of the process that may be read or
|
||||||
|
written for debugging.
|
||||||
|
The
|
||||||
|
.CW text
|
||||||
|
file is a sort of link to the file from which the process was executed;
|
||||||
|
it may be opened to read the symbol tables for the process.
|
||||||
|
The
|
||||||
|
.CW ctl
|
||||||
|
file may be written textual messages such as
|
||||||
|
.CW stop
|
||||||
|
or
|
||||||
|
.CW kill
|
||||||
|
to control the execution of the process.
|
||||||
|
The
|
||||||
|
.CW status
|
||||||
|
file contains a fixed-format line of text containing information about
|
||||||
|
the process: its name, owner, state, and so on.
|
||||||
|
Text strings written to the
|
||||||
|
.CW note
|
||||||
|
file are delivered to the process as
|
||||||
|
.I notes,
|
||||||
|
analogous to UNIX signals.
|
||||||
|
By providing these services as textual I/O on files rather
|
||||||
|
than as system calls (such as
|
||||||
|
.CW kill )
|
||||||
|
or special-purpose operations (such as
|
||||||
|
.CW ptrace ),
|
||||||
|
the Plan 9 process device simplifies the implementation of
|
||||||
|
debuggers and related programs.
|
||||||
|
For example, the command
|
||||||
|
.P1
|
||||||
|
cat /proc/*/status
|
||||||
|
.P2
|
||||||
|
is a crude form of the
|
||||||
|
.CW ps
|
||||||
|
command; the actual
|
||||||
|
.CW ps
|
||||||
|
merely reformats the data so obtained.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.I bitmap
|
||||||
|
device contains three files,
|
||||||
|
.CW /dev/mouse ,
|
||||||
|
.CW /dev/screen ,
|
||||||
|
and
|
||||||
|
.CW /dev/bitblt ,
|
||||||
|
that provide an interface to the local bitmap display (if any) and pointing device.
|
||||||
|
The
|
||||||
|
.CW mouse
|
||||||
|
file returns a fixed-format record containing
|
||||||
|
1 byte of button state and 4 bytes each of
|
||||||
|
.I x
|
||||||
|
and
|
||||||
|
.I y
|
||||||
|
position of the mouse.
|
||||||
|
If the mouse has not moved since the file was last read, a subsequent read will
|
||||||
|
block.
|
||||||
|
The
|
||||||
|
.CW screen
|
||||||
|
file contains a memory image of the contents of the display;
|
||||||
|
the
|
||||||
|
.CW bitblt
|
||||||
|
file provides a procedural interface.
|
||||||
|
Calls to the graphics library are translated into messages that are written
|
||||||
|
to the
|
||||||
|
.CW bitblt
|
||||||
|
file to perform bitmap graphics operations. (This is essentially a nested
|
||||||
|
RPC protocol.)
|
||||||
|
.PP
|
||||||
|
The various services being used by a process are gathered together into the
|
||||||
|
process's
|
||||||
|
.I
|
||||||
|
name space,
|
||||||
|
.R
|
||||||
|
a single rooted hierarchy of file names.
|
||||||
|
When a process forks, the child process shares the name space with the parent.
|
||||||
|
Several system calls manipulate name spaces.
|
||||||
|
Given a file descriptor
|
||||||
|
.CW fd
|
||||||
|
that holds an open communications channel to a service,
|
||||||
|
the call
|
||||||
|
.P1
|
||||||
|
mount(int fd, char *old, int flags)
|
||||||
|
.P2
|
||||||
|
authenticates the user and attaches the file tree of the service to
|
||||||
|
the directory named by
|
||||||
|
.CW old .
|
||||||
|
The
|
||||||
|
.CW flags
|
||||||
|
specify how the tree is to be attached to
|
||||||
|
.CW old :
|
||||||
|
replacing the current contents or appearing before or after the
|
||||||
|
current contents of the directory.
|
||||||
|
A directory with several services mounted is called a
|
||||||
|
.I union
|
||||||
|
directory and is searched in the specified order.
|
||||||
|
The call
|
||||||
|
.P1
|
||||||
|
bind(char *new, char *old, int flags)
|
||||||
|
.P2
|
||||||
|
takes the portion of the existing name space visible at
|
||||||
|
.CW new ,
|
||||||
|
either a file or a directory, and makes it also visible at
|
||||||
|
.CW old .
|
||||||
|
For example,
|
||||||
|
.P1
|
||||||
|
bind("1995/0301/sys/include", "/sys/include", REPLACE)
|
||||||
|
.P2
|
||||||
|
causes the directory of include files to be overlaid with its
|
||||||
|
contents from the dump on March first.
|
||||||
|
.PP
|
||||||
|
A process is created by the
|
||||||
|
.CW rfork
|
||||||
|
system call, which takes as argument a bit vector defining which
|
||||||
|
attributes of the process are to be shared between parent
|
||||||
|
and child instead of copied.
|
||||||
|
One of the attributes is the name space: when shared, changes
|
||||||
|
made by either process are visible in the other; when copied,
|
||||||
|
changes are independent.
|
||||||
|
.PP
|
||||||
|
Although there is no global name space,
|
||||||
|
for a process to function sensibly the local name spaces must adhere
|
||||||
|
to global conventions.
|
||||||
|
Nonetheless, the use of local name spaces is critical to the system.
|
||||||
|
Both these ideas are illustrated by the use of the name space to
|
||||||
|
handle heterogeneity.
|
||||||
|
The binaries for a given architecture are contained in a directory
|
||||||
|
named by the architecture, for example
|
||||||
|
.CW /mips/bin ;
|
||||||
|
in use, that directory is bound to the conventional location
|
||||||
|
.CW /bin .
|
||||||
|
Programs such as shell scripts need not know the CPU type they are
|
||||||
|
executing on to find binaries to run.
|
||||||
|
A directory of private binaries
|
||||||
|
is usually unioned with
|
||||||
|
.CW /bin .
|
||||||
|
(Compare this to the
|
||||||
|
.I
|
||||||
|
ad hoc
|
||||||
|
.R
|
||||||
|
and special-purpose idea of the
|
||||||
|
.CW PATH
|
||||||
|
variable, which is not used in the Plan 9 shell.)
|
||||||
|
Local bindings are also helpful for debugging, for example by binding
|
||||||
|
an old library to the standard place and linking a program to see
|
||||||
|
if recent changes to the library are responsible for a bug in the program.
|
||||||
|
.PP
|
||||||
|
The window system,
|
||||||
|
.CW 8½
|
||||||
|
[Pike91], is a server for files such as
|
||||||
|
.CW /dev/cons
|
||||||
|
and
|
||||||
|
.CW /dev/bitblt .
|
||||||
|
Each client sees a distinct copy of these files in its local
|
||||||
|
name space: there are many instances of
|
||||||
|
.CW /dev/cons ,
|
||||||
|
each served by
|
||||||
|
.CW 8½
|
||||||
|
to the local name space of a window.
|
||||||
|
Again,
|
||||||
|
.CW 8½
|
||||||
|
implements services using
|
||||||
|
local name spaces plus the use
|
||||||
|
of I/O to conventionally named files.
|
||||||
|
Each client just connects its standard input, output, and error files
|
||||||
|
to
|
||||||
|
.CW /dev/cons ,
|
||||||
|
with analogous operations to access bitmap graphics.
|
||||||
|
Compare this to the implementation of
|
||||||
|
.CW /dev/tty
|
||||||
|
on UNIX, which is done by special code in the kernel
|
||||||
|
that overloads the file, when opened,
|
||||||
|
with the standard input or output of the process.
|
||||||
|
Special arrangement must be made by a UNIX window system for
|
||||||
|
.CW /dev/tty
|
||||||
|
to behave as expected;
|
||||||
|
.CW 8½
|
||||||
|
instead uses the provision of the corresponding file as its
|
||||||
|
central idea, which to succeed depends critically on local name spaces.
|
||||||
|
.PP
|
||||||
|
The environment
|
||||||
|
.CW 8½
|
||||||
|
provides its clients is exactly the environment under which it is implemented:
|
||||||
|
a conventional set of files in
|
||||||
|
.CW /dev .
|
||||||
|
This permits the window system to be run recursively in one of its own
|
||||||
|
windows, which is handy for debugging.
|
||||||
|
It also means that if the files are exported to another machine,
|
||||||
|
as described below, the window system or client applications may be
|
||||||
|
run transparently on remote machines, even ones without graphics hardware.
|
||||||
|
This mechanism is used for Plan 9's implementation of the X window
|
||||||
|
system: X is run as a client of
|
||||||
|
.CW 8½ ,
|
||||||
|
often on a remote machine with lots of memory.
|
||||||
|
In this configuration, using Ethernet to connect
|
||||||
|
MIPS machines, we measure only a 10% degradation in graphics
|
||||||
|
performance relative to running X on
|
||||||
|
a bare Plan 9 machine.
|
||||||
|
.PP
|
||||||
|
An unusual application of these ideas is a statistics-gathering
|
||||||
|
file system implemented by a command called
|
||||||
|
.CW iostats .
|
||||||
|
The command encapsulates a process in a local name space, monitoring 9P
|
||||||
|
requests from the process to the outside world \(em the name space in which
|
||||||
|
.CW iostats
|
||||||
|
is itself running. When the command completes,
|
||||||
|
.CW iostats
|
||||||
|
reports usage and performance figures for file activity.
|
||||||
|
For example
|
||||||
|
.P1
|
||||||
|
iostats 8½
|
||||||
|
.P2
|
||||||
|
can be used to discover how much I/O the window system
|
||||||
|
does to the bitmap device, font files, and so on.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW import
|
||||||
|
command connects a piece of name space from a remote system
|
||||||
|
to the local name space.
|
||||||
|
Its implementation is to dial the remote machine and start
|
||||||
|
a process there that serves the remote name space using 9P.
|
||||||
|
It then calls
|
||||||
|
.CW mount
|
||||||
|
to attach the connection to the name space and finally dies;
|
||||||
|
the remote process continues to serve the files.
|
||||||
|
One use is to access devices not available
|
||||||
|
locally. For example, to write a floppy one may say
|
||||||
|
.P1
|
||||||
|
import lab.pc /a: /n/dos
|
||||||
|
cp foo /n/dos/bar
|
||||||
|
.P2
|
||||||
|
The call to
|
||||||
|
.CW import
|
||||||
|
connects the file tree from
|
||||||
|
.CW /a:
|
||||||
|
on the machine
|
||||||
|
.CW lab.pc
|
||||||
|
(which must support 9P) to the local directory
|
||||||
|
.CW /n/dos .
|
||||||
|
Then the file
|
||||||
|
.CW foo
|
||||||
|
can be written to the floppy just by copying it across.
|
||||||
|
.PP
|
||||||
|
Another application is remote debugging:
|
||||||
|
.P1
|
||||||
|
import helix /proc
|
||||||
|
.P2
|
||||||
|
makes the process file system on machine
|
||||||
|
.CW helix
|
||||||
|
available locally; commands such as
|
||||||
|
.CW ps
|
||||||
|
then see
|
||||||
|
.CW helix 's
|
||||||
|
processes instead of the local ones.
|
||||||
|
The debugger may then look at a remote process:
|
||||||
|
.P1
|
||||||
|
db /proc/27/text /proc/27/mem
|
||||||
|
.P2
|
||||||
|
allows breakpoint debugging of the remote process.
|
||||||
|
Since
|
||||||
|
.CW db
|
||||||
|
infers the CPU type of the process from the executable header on
|
||||||
|
the text file, it supports
|
||||||
|
cross-architecture debugging, too.
|
||||||
|
Care is taken within
|
||||||
|
.CW db
|
||||||
|
to handle issues of byte order and floating point; it is possible to
|
||||||
|
breakpoint debug a big-endian MIPS process from a little-endian i386.
|
||||||
|
.PP
|
||||||
|
Network interfaces are also implemented as file systems [Presotto].
|
||||||
|
For example,
|
||||||
|
.CW /net/tcp
|
||||||
|
is a directory somewhat like
|
||||||
|
.CW /proc :
|
||||||
|
it contains a set of numbered directories, one per connection,
|
||||||
|
each of which contains files to control and communicate on the connection.
|
||||||
|
A process allocates a new connection by accessing
|
||||||
|
.CW /net/tcp/clone ,
|
||||||
|
which evaluates to the directory of an unused connection.
|
||||||
|
To make a call, the process writes a textual message such as
|
||||||
|
.CW 'connect
|
||||||
|
.CW 135.104.53.2!512'
|
||||||
|
to the
|
||||||
|
.CW ctl
|
||||||
|
file and then reads and writes the
|
||||||
|
.CW data
|
||||||
|
file.
|
||||||
|
An
|
||||||
|
.CW rlogin
|
||||||
|
service can be implemented in a few of lines of shell code.
|
||||||
|
.PP
|
||||||
|
This structure makes network gatewaying easy to provide.
|
||||||
|
We have machines with Datakit interfaces but no Internet interface.
|
||||||
|
On such a machine one may type
|
||||||
|
.P1
|
||||||
|
import helix /net
|
||||||
|
telnet tcp!ai.mit.edu
|
||||||
|
.P2
|
||||||
|
The
|
||||||
|
.CW import
|
||||||
|
uses Datakit to pull in the TCP interface from
|
||||||
|
.CW helix ,
|
||||||
|
which can then be used directly; the
|
||||||
|
.CW tcp!
|
||||||
|
notation is necessary because we routinely use multiple networks
|
||||||
|
and protocols on Plan 9\(emit identifies the network in which
|
||||||
|
.CW ai.mit.edu
|
||||||
|
is a valid name.
|
||||||
|
.PP
|
||||||
|
In practice we do not use
|
||||||
|
.CW rlogin
|
||||||
|
or
|
||||||
|
.CW telnet
|
||||||
|
between Plan 9 machines. Instead a command called
|
||||||
|
.CW cpu
|
||||||
|
in effect replaces the CPU in a window with that
|
||||||
|
on another machine, typically a fast multiprocessor CPU server.
|
||||||
|
The implementation is to recreate the
|
||||||
|
name space on the remote machine, using the equivalent of
|
||||||
|
.CW import
|
||||||
|
to connect pieces of the terminal's name space to that of
|
||||||
|
the process (shell) on the CPU server, making the terminal
|
||||||
|
a file server for the CPU.
|
||||||
|
CPU-local devices such as fast file system connections
|
||||||
|
are still local; only terminal-resident devices are
|
||||||
|
imported.
|
||||||
|
The result is unlike UNIX
|
||||||
|
.CW rlogin ,
|
||||||
|
which moves into a distinct name space on the remote machine,
|
||||||
|
or file sharing with
|
||||||
|
.CW NFS ,
|
||||||
|
which keeps the name space the same but forces processes to execute
|
||||||
|
locally.
|
||||||
|
Bindings in
|
||||||
|
.CW /bin
|
||||||
|
may change because of a change in CPU architecture, and
|
||||||
|
the networks involved may be different because of differing hardware,
|
||||||
|
but the effect feels like simply speeding up the processor in the
|
||||||
|
current name space.
|
||||||
|
.SH
|
||||||
|
Position
|
||||||
|
.PP
|
||||||
|
These examples illustrate how the ideas of representing resources
|
||||||
|
as file systems and per-process name spaces can be used to solve
|
||||||
|
problems often left to more exotic mechanisms.
|
||||||
|
Nonetheless there are some operations in Plan 9 that are not
|
||||||
|
mapped into file I/O.
|
||||||
|
An example is process creation.
|
||||||
|
We could imagine a message to a control file in
|
||||||
|
.CW /proc
|
||||||
|
that creates a process, but the details of
|
||||||
|
constructing the environment of the new process \(em its open files,
|
||||||
|
name space, memory image, etc. \(em are too intricate to
|
||||||
|
be described easily in a simple I/O operation.
|
||||||
|
Therefore new processes on Plan 9 are created by fairly conventional
|
||||||
|
.CW rfork
|
||||||
|
and
|
||||||
|
.CW exec
|
||||||
|
system calls;
|
||||||
|
.CW /proc
|
||||||
|
is used only to represent and control existing processes.
|
||||||
|
.PP
|
||||||
|
Plan 9 does not attempt to map network name spaces into the file
|
||||||
|
system name space, for several reasons.
|
||||||
|
The different addressing rules for various networks and protocols
|
||||||
|
cannot be mapped uniformly into a hierarchical file name space.
|
||||||
|
Even if they could be,
|
||||||
|
the various mechanisms to authenticate,
|
||||||
|
select a service,
|
||||||
|
and control the connection would not map consistently into
|
||||||
|
operations on a file.
|
||||||
|
.PP
|
||||||
|
Shared memory is another resource not adequately represented by a
|
||||||
|
file name space.
|
||||||
|
Plan 9 takes care to provide mechanisms
|
||||||
|
to allow groups of local processes to share and map memory.
|
||||||
|
Memory is controlled
|
||||||
|
by system calls rather than special files, however,
|
||||||
|
since a representation in the file system would imply that memory could
|
||||||
|
be imported from remote machines.
|
||||||
|
.PP
|
||||||
|
Despite these limitations, file systems and name spaces offer an effective
|
||||||
|
model around which to build a distributed system.
|
||||||
|
Used well, they can provide a uniform, familiar, transparent
|
||||||
|
interface to a diverse set of distributed resources.
|
||||||
|
They carry well-understood properties of access, protection,
|
||||||
|
and naming.
|
||||||
|
The integration of devices into the hierarchical file system
|
||||||
|
was the best idea in UNIX.
|
||||||
|
Plan 9 pushes the concepts much further and shows that
|
||||||
|
file systems, when used inventively, have plenty of scope
|
||||||
|
for productive research.
|
||||||
|
.SH
|
||||||
|
References
|
||||||
|
.LP
|
||||||
|
[Killian] T. Killian, ``Processes as Files'', USENIX Summer Conf. Proc., Salt Lake City, 1984
|
||||||
|
.br
|
||||||
|
[Needham] R. Needham, ``Names'', in
|
||||||
|
.I
|
||||||
|
Distributed systems,
|
||||||
|
.R
|
||||||
|
S. Mullender, ed.,
|
||||||
|
Addison Wesley, 1989
|
||||||
|
.br
|
||||||
|
[Pike90] R. Pike, D. Presotto, K. Thompson, H. Trickey,
|
||||||
|
``Plan 9 from Bell Labs'',
|
||||||
|
UKUUG Proc. of the Summer 1990 Conf.,
|
||||||
|
London, England,
|
||||||
|
1990
|
||||||
|
.br
|
||||||
|
[Presotto] D. Presotto, ``Multiprocessor Streams for Plan 9'',
|
||||||
|
UKUUG Proc. of the Summer 1990 Conf.,
|
||||||
|
London, England,
|
||||||
|
1990
|
||||||
|
.br
|
||||||
|
[Pike91] Pike, R., ``8.5, The Plan 9 Window System'', USENIX Summer
|
||||||
|
Conf. Proc., Nashville, 1991
|
7351
sys/doc/names.ps
Normal file
7351
sys/doc/names.ps
Normal file
File diff suppressed because it is too large
Load diff
21
sys/doc/net/mkfile
Normal file
21
sys/doc/net/mkfile
Normal file
|
@ -0,0 +1,21 @@
|
||||||
|
</sys/doc/fonts
|
||||||
|
|
||||||
|
DEPS = net.ms\
|
||||||
|
tree.pout
|
||||||
|
|
||||||
|
net.ps:D: $DEPS
|
||||||
|
{ echo $FONTS; cat net.ms } | tbl | troff -ms | lp -dstdout > net.ps
|
||||||
|
../cleanps net.ps
|
||||||
|
|
||||||
|
net.trout:D: $DEPS
|
||||||
|
{ echo $FONTS; cat net.ms } | tbl | troff -ms > net.trout
|
||||||
|
|
||||||
|
tree.pout:D: tree
|
||||||
|
pic tree > tree.pout
|
||||||
|
|
||||||
|
net.html:D: $DEPS
|
||||||
|
tbl net.ms | htmlroff -ms -mhtml >net.html
|
||||||
|
|
||||||
|
clean:V:
|
||||||
|
rm -f net.ps tree.pout net.trout
|
||||||
|
|
1336
sys/doc/net/net.ms
Normal file
1336
sys/doc/net/net.ms
Normal file
File diff suppressed because it is too large
Load diff
BIN
sys/doc/net/net.pdf
Normal file
BIN
sys/doc/net/net.pdf
Normal file
Binary file not shown.
10217
sys/doc/net/net.ps
Normal file
10217
sys/doc/net/net.ps
Normal file
File diff suppressed because it is too large
Load diff
34
sys/doc/net/tree
Normal file
34
sys/doc/net/tree
Normal file
|
@ -0,0 +1,34 @@
|
||||||
|
.nf
|
||||||
|
.PS
|
||||||
|
scale=100
|
||||||
|
define t100 |
|
||||||
|
[ box invis ht 32 wid 22 with .sw at 0,0
|
||||||
|
"\f(CW\s10\ðer\f1\s0" at 11,24
|
||||||
|
"\f(CW\s10\&\f1\s0" at 11,8
|
||||||
|
] |
|
||||||
|
|
||||||
|
box invis ht 144 wid 408 with .sw at 0,0
|
||||||
|
"\f(CW\s10\&ctl\f1\s0" at 192,-10
|
||||||
|
"\f(CW\s10\&data\f1\s0" at 140,-10
|
||||||
|
"\f(CW\s10\&ctl\f1\s0" at 80,-10
|
||||||
|
line from 384,48 to 408,8
|
||||||
|
line from 368,48 to 344,8
|
||||||
|
"\f(CW\s10\&. . .\f1\s0" at 300,62
|
||||||
|
"\f(CW\s10\&clone\f1\s0" at 20,58
|
||||||
|
t100 with .nw at 161,142
|
||||||
|
line from 184,120 to 376,80
|
||||||
|
line from 176,120 to 224,80
|
||||||
|
line from 168,120 to 112,80
|
||||||
|
line from 160,120 to 24,80
|
||||||
|
"\fI\s10\&n\f1\s0" at 376,58
|
||||||
|
"\f(CW\s10\&2\f1\s0" at 228,58
|
||||||
|
"\f(CW\s10\&1\f1\s0" at 112,58
|
||||||
|
line from 232,48 to 256,8
|
||||||
|
line from 216,48 to 192,8
|
||||||
|
line from 120,48 to 144,8
|
||||||
|
line from 104,48 to 80,8
|
||||||
|
"\f(CW\s10\&data\f1\s0" at 408,-10
|
||||||
|
"\f(CW\s10\&ctl\f1\s0" at 344,-10
|
||||||
|
"\f(CW\s10\&data\f1\s0" at 256,-10
|
||||||
|
.PE
|
||||||
|
.fi
|
59
sys/doc/net/tree.pout
Normal file
59
sys/doc/net/tree.pout
Normal file
|
@ -0,0 +1,59 @@
|
||||||
|
.lf 1 tree
|
||||||
|
.nf
|
||||||
|
... 0 -10 408 144
|
||||||
|
... 0.000i 1.540i 4.080i 0.000i
|
||||||
|
.nr 00 \n(.u
|
||||||
|
.nf
|
||||||
|
.PS 1.540i 4.080i
|
||||||
|
.lf 34
|
||||||
|
\h'1.920i'\v'1.540i'\v'.2m'\h'-\w'\f(CW\s10\&ctl\f1\s0'u/2u'\f(CW\s10\&ctl\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'1.400i'\v'1.540i'\v'.2m'\h'-\w'\f(CW\s10\&data\f1\s0'u/2u'\f(CW\s10\&data\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'0.800i'\v'1.540i'\v'.2m'\h'-\w'\f(CW\s10\&ctl\f1\s0'u/2u'\f(CW\s10\&ctl\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'3.840i'\v'0.960i'\D'l0.240i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.680i'\v'0.960i'\D'l-0.240i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.000i'\v'0.820i'\v'.2m'\h'-\w'\f(CW\s10\&. . .\f1\s0'u/2u'\f(CW\s10\&. . .\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'0.200i'\v'0.860i'\v'.2m'\h'-\w'\f(CW\s10\&clone\f1\s0'u/2u'\f(CW\s10\&clone\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'1.720i'\v'0.100i'\v'.2m'\h'-\w'\f(CW\s10\ðer\f1\s0'u/2u'\f(CW\s10\ðer\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'1.720i'\v'0.260i'\v'.2m'\h'-\w'\f(CW\s10\&\f1\s0'u/2u'\f(CW\s10\&\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'1.840i'\v'0.240i'\D'l1.920i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.760i'\v'0.240i'\D'l0.480i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.680i'\v'0.240i'\D'l-0.560i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.600i'\v'0.240i'\D'l-1.360i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'3.760i'\v'0.860i'\v'.2m'\h'-\w'\fI\s10\&n\f1\s0'u/2u'\fI\s10\&n\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'2.280i'\v'0.860i'\v'.2m'\h'-\w'\f(CW\s10\&2\f1\s0'u/2u'\f(CW\s10\&2\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'1.120i'\v'0.860i'\v'.2m'\h'-\w'\f(CW\s10\&1\f1\s0'u/2u'\f(CW\s10\&1\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'2.320i'\v'0.960i'\D'l0.240i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'2.160i'\v'0.960i'\D'l-0.240i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.200i'\v'0.960i'\D'l0.240i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'1.040i'\v'0.960i'\D'l-0.240i 0.400i'
|
||||||
|
.sp -1
|
||||||
|
\h'4.080i'\v'1.540i'\v'.2m'\h'-\w'\f(CW\s10\&data\f1\s0'u/2u'\f(CW\s10\&data\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'3.440i'\v'1.540i'\v'.2m'\h'-\w'\f(CW\s10\&ctl\f1\s0'u/2u'\f(CW\s10\&ctl\f1\s0
|
||||||
|
.sp -1
|
||||||
|
\h'2.560i'\v'1.540i'\v'.2m'\h'-\w'\f(CW\s10\&data\f1\s0'u/2u'\f(CW\s10\&data\f1\s0
|
||||||
|
.sp -1
|
||||||
|
.sp 1+1.540i
|
||||||
|
.PE
|
||||||
|
.if \n(00 .fi
|
||||||
|
.lf 34
|
||||||
|
.fi
|
93
sys/doc/network.art
Normal file
93
sys/doc/network.art
Normal file
|
@ -0,0 +1,93 @@
|
||||||
|
G 0
|
||||||
|
l 5.150 5.810 5.150 5.400
|
||||||
|
a 5.630 5.810 5.400 5.670 5.150 5.810
|
||||||
|
a 5.630 5.810 5.400 5.950 5.150 5.810
|
||||||
|
l 5.630 5.810 5.630 5.400
|
||||||
|
a 5.630 5.400 5.400 5.260 5.150 5.400
|
||||||
|
;
|
||||||
|
G 1
|
||||||
|
l 6.260 4.290 6.260 3.810
|
||||||
|
l 6.120 4.190 6.400 4.190
|
||||||
|
l 6.120 4.090 6.400 4.090
|
||||||
|
;
|
||||||
|
G 2
|
||||||
|
c 3.270 4.090 0.250
|
||||||
|
t 3.270 4.090 pelm,unicode,9 Term
|
||||||
|
;
|
||||||
|
G 3
|
||||||
|
g 4 0.075 0.065
|
||||||
|
l 2.495 4.485 2.900 4.485
|
||||||
|
l 2.900 4.485 2.900 3.941
|
||||||
|
g 2 -0.370 -0.399
|
||||||
|
l 2.330 4.215 2.330 3.940
|
||||||
|
g 2 -0.940 -0.400
|
||||||
|
l 1.740 4.215 1.740 3.930
|
||||||
|
g 2 -1.540 -0.410
|
||||||
|
;
|
||||||
|
G 4
|
||||||
|
b 1.430 4.150 2.420 4.690
|
||||||
|
b 1.480 4.200 2.370 4.640
|
||||||
|
t 1.925 4.420 pelm,unicode,9 Datakit
|
||||||
|
;
|
||||||
|
b 2.140 5.350 2.820 5.730
|
||||||
|
l 2.140 5.540 2.000 5.540
|
||||||
|
b 3.180 5.350 3.860 5.730
|
||||||
|
b 3.180 5.350 3.860 5.730
|
||||||
|
b 4.220 5.350 4.900 5.730
|
||||||
|
l 2.480 5.350 2.480 5.090
|
||||||
|
l 4.560 5.350 4.560 5.090
|
||||||
|
l 3.520 5.350 3.520 5.090
|
||||||
|
l 2.430 5.350 2.430 5.090
|
||||||
|
l 2.530 5.350 2.530 5.090
|
||||||
|
l 3.470 5.350 3.470 5.090
|
||||||
|
l 3.570 5.350 3.570 5.090
|
||||||
|
l 4.510 5.350 4.510 5.090
|
||||||
|
l 4.610 5.350 4.610 5.090
|
||||||
|
l 2.300 5.040 6.810 5.040
|
||||||
|
l 2.300 4.990 6.810 4.990
|
||||||
|
l 4.900 5.540 5.150 5.540
|
||||||
|
g 0 0.000 0.000
|
||||||
|
t 2.480 5.540 pelm,unicode,9 CPU
|
||||||
|
t 3.520 5.540 pelm,unicode,9 CPU
|
||||||
|
b 2.140 5.350 2.820 5.730
|
||||||
|
b 0.500 5.350 1.180 5.730
|
||||||
|
t 0.840 5.540 pelm,unicode,9 File
|
||||||
|
l 0.840 5.350 0.840 5.100
|
||||||
|
g 0 -4.540 -0.850
|
||||||
|
t 4.560 5.540 pelm,unicode,9 File
|
||||||
|
l 0.500 6.330 6.680 6.330
|
||||||
|
l 0.840 5.730 0.840 6.330
|
||||||
|
l 2.480 5.730 2.480 6.330
|
||||||
|
l 3.520 5.730 3.520 6.330
|
||||||
|
l 4.560 5.730 4.560 6.330
|
||||||
|
l 6.340 6.330 6.340 5.730
|
||||||
|
b 6.000 5.350 6.680 5.730
|
||||||
|
t 6.810 7.670 pelm,unicode,9 Internet
|
||||||
|
t 6.340 5.540 pelm,unicode,9 Gateway
|
||||||
|
l 6.080 6.330 6.080 6.930
|
||||||
|
b 5.740 6.930 6.420 7.310
|
||||||
|
t 6.080 7.120 pelm,unicode,9 Gateway
|
||||||
|
l 6.080 7.310 6.080 7.610
|
||||||
|
g 1 -1.562 3.858
|
||||||
|
g 1 -2.430 3.677
|
||||||
|
g 1 -3.431 3.687
|
||||||
|
g 2 -1.150 3.740
|
||||||
|
l 1.500 6.330 1.500 6.800
|
||||||
|
g 2 -1.770 2.960
|
||||||
|
l 2.160 6.800 2.160 6.330
|
||||||
|
l 2.820 6.330 2.820 6.800
|
||||||
|
g 2 -1.110 2.960
|
||||||
|
g 2 -0.450 2.960
|
||||||
|
l 6.810 5.090 2.300 5.090
|
||||||
|
l 6.680 5.540 6.810 5.540
|
||||||
|
l 6.810 5.540 6.810 7.580 S >
|
||||||
|
l 6.340 5.350 6.340 5.090
|
||||||
|
l 6.390 5.350 6.390 5.090
|
||||||
|
l 6.290 5.350 6.290 5.090
|
||||||
|
t 5.160 6.420 pelm,unicode,9 Ethernet
|
||||||
|
t 4.515 4.850 pelm,unicode,9 Fiber Network
|
||||||
|
s 6 6.080 7.610 6.080 7.970 4.880 8.300 3.610 7.470 2.660 7.830 2.370 7.830
|
||||||
|
l 2.000 5.540 2.000 4.755
|
||||||
|
l 1.180 5.540 1.700 5.540
|
||||||
|
l 1.700 5.540 1.700 4.755
|
||||||
|
g 3 -0.125 0.000
|
117
sys/doc/network.pic
Normal file
117
sys/doc/network.pic
Normal file
|
@ -0,0 +1,117 @@
|
||||||
|
.PS 5.5i
|
||||||
|
define grp0 {[
|
||||||
|
line from (5.15,5.81) to (5.15,5.4);
|
||||||
|
arc cw from (5.63,5.81) to (5.15,5.81) rad 0.275539;
|
||||||
|
arc ccw from (5.63,5.81) to (5.15,5.81) rad 0.275539;
|
||||||
|
line from (5.63,5.81) to (5.63,5.4);
|
||||||
|
arc cw from (5.63,5.4) to (5.15,5.4) rad 0.275539;
|
||||||
|
]}
|
||||||
|
define grp1 {[
|
||||||
|
line from (6.26,4.29) to (6.26,3.81);
|
||||||
|
line from (6.12,4.19) to (6.4,4.19);
|
||||||
|
line from (6.12,4.09) to (6.4,4.09);
|
||||||
|
]}
|
||||||
|
define grp2 {[
|
||||||
|
circle at (3.27,4.09) rad 0.25;
|
||||||
|
"Term" at (3.27,4.09);
|
||||||
|
]}
|
||||||
|
define grp3 {[
|
||||||
|
grp4() with (0,0) at (0.075,0.065);
|
||||||
|
line from (2.495,4.485) to (2.9,4.485);
|
||||||
|
line from (2.9,4.485) to (2.9,3.941);
|
||||||
|
grp2() with (0,0) at (-0.37,-0.399);
|
||||||
|
line from (2.33,4.215) to (2.33,3.94);
|
||||||
|
grp2() with (0,0) at (-0.94,-0.4);
|
||||||
|
line from (1.74,4.215) to (1.74,3.93);
|
||||||
|
grp2() with (0,0) at (-1.54,-0.41);
|
||||||
|
]}
|
||||||
|
define grp4 {[
|
||||||
|
box wid 0.99 ht 0.54 at (1.925,4.42);
|
||||||
|
box wid 0.89 ht 0.44 at (1.925,4.42);
|
||||||
|
"Datakit" at (1.925,4.42);
|
||||||
|
]}
|
||||||
|
box wid 0.68 ht 0.38 at (2.48,5.54);
|
||||||
|
line from (2.14,5.54) to (2,5.54);
|
||||||
|
box wid 0.68 ht 0.38 at (3.52,5.54);
|
||||||
|
box wid 0.68 ht 0.38 at (3.52,5.54);
|
||||||
|
box wid 0.68 ht 0.38 at (4.56,5.54);
|
||||||
|
line from (2.48,5.35) to (2.48,5.09);
|
||||||
|
line from (4.56,5.35) to (4.56,5.09);
|
||||||
|
line from (3.52,5.35) to (3.52,5.09);
|
||||||
|
line from (2.43,5.35) to (2.43,5.09);
|
||||||
|
line from (2.53,5.35) to (2.53,5.09);
|
||||||
|
line from (3.47,5.35) to (3.47,5.09);
|
||||||
|
line from (3.57,5.35) to (3.57,5.09);
|
||||||
|
line from (4.51,5.35) to (4.51,5.09);
|
||||||
|
line from (4.61,5.35) to (4.61,5.09);
|
||||||
|
line from (2.3,5.04) to (6.81,5.04);
|
||||||
|
line from (2.3,4.99) to (6.81,4.99);
|
||||||
|
line from (4.9,5.54) to (5.15,5.54);
|
||||||
|
grp0() with (0,0) at (0,0);
|
||||||
|
"CPU" at (2.48,5.54);
|
||||||
|
"CPU" at (3.52,5.54);
|
||||||
|
box wid 0.68 ht 0.38 at (2.48,5.54);
|
||||||
|
box wid 0.68 ht 0.38 at (0.84,5.54);
|
||||||
|
"File" at (0.84,5.54);
|
||||||
|
line from (0.84,5.35) to (0.84,5.1);
|
||||||
|
grp0() with (0,0) at (-4.54,-0.85);
|
||||||
|
"File" at (4.56,5.54);
|
||||||
|
line from (0.5,6.33) to (6.68,6.33);
|
||||||
|
line from (0.84,5.73) to (0.84,6.33);
|
||||||
|
line from (2.48,5.73) to (2.48,6.33);
|
||||||
|
line from (3.52,5.73) to (3.52,6.33);
|
||||||
|
line from (4.56,5.73) to (4.56,6.33);
|
||||||
|
line from (6.34,6.33) to (6.34,5.73);
|
||||||
|
box wid 0.68 ht 0.38 at (6.34,5.54);
|
||||||
|
"Internet" at (6.81,7.67);
|
||||||
|
"Gateway" at (6.34,5.54);
|
||||||
|
line from (6.08,6.33) to (6.08,6.93);
|
||||||
|
box wid 0.68 ht 0.38 at (6.08,7.12);
|
||||||
|
"Gateway" at (6.08,7.12);
|
||||||
|
line from (6.08,7.31) to (6.08,7.61);
|
||||||
|
grp1() with (0,0) at (-1.562,3.858);
|
||||||
|
grp1() with (0,0) at (-2.43,3.677);
|
||||||
|
grp1() with (0,0) at (-3.431,3.687);
|
||||||
|
grp2() with (0,0) at (-1.15,3.74);
|
||||||
|
line from (1.5,6.33) to (1.5,6.8);
|
||||||
|
grp2() with (0,0) at (-1.77,2.96);
|
||||||
|
line from (2.16,6.8) to (2.16,6.33);
|
||||||
|
line from (2.82,6.33) to (2.82,6.8);
|
||||||
|
grp2() with (0,0) at (-1.11,2.96);
|
||||||
|
grp2() with (0,0) at (-0.45,2.96);
|
||||||
|
line from (6.81,5.09) to (2.3,5.09);
|
||||||
|
line from (6.68,5.54) to (6.81,5.54);
|
||||||
|
line -> from (6.81,5.54) to (6.81,7.58);
|
||||||
|
line from (6.34,5.35) to (6.34,5.09);
|
||||||
|
line from (6.39,5.35) to (6.39,5.09);
|
||||||
|
line from (6.29,5.35) to (6.29,5.09);
|
||||||
|
"Ethernet" at (5.16,6.42);
|
||||||
|
"Fiber Network" at (4.515,4.85);
|
||||||
|
line from (6.08,7.61) to (6.07531,7.65488)
|
||||||
|
line from (6.07531,7.65488) to (6.06125,7.69953)
|
||||||
|
line from (6.06125,7.69953) to (6.03781,7.74395)
|
||||||
|
line from (6.03781,7.74395) to (6.005,7.78812)
|
||||||
|
line from (6.005,7.78812) to (5.91125,7.87578)
|
||||||
|
line from (5.91125,7.87578) to (5.78,7.9625)
|
||||||
|
line from (5.78,7.9625) to (5.70004,8.00098)
|
||||||
|
line from (5.70004,8.00098) to (5.61016,8.03016)
|
||||||
|
line from (5.61016,8.03016) to (5.51035,8.05004)
|
||||||
|
line from (5.51035,8.05004) to (5.40062,8.06062)
|
||||||
|
line from (5.40062,8.06062) to (5.28098,8.06191)
|
||||||
|
line from (5.28098,8.06191) to (5.15141,8.05391)
|
||||||
|
line from (5.15141,8.05391) to (5.01191,8.0366)
|
||||||
|
line from (5.01191,8.0366) to (4.8625,8.01)
|
||||||
|
line from (4.8625,8.01) to (3.69,7.7675)
|
||||||
|
line from (3.69,7.7675) to (3.42781,7.72172)
|
||||||
|
line from (3.42781,7.72172) to (3.19625,7.70188)
|
||||||
|
line from (3.19625,7.70188) to (2.99531,7.70797)
|
||||||
|
line from (2.99531,7.70797) to (2.90633,7.72074)
|
||||||
|
line from (2.90633,7.72074) to (2.825,7.74)
|
||||||
|
line from (2.825,7.74) to (2.55625,7.8075)
|
||||||
|
line from (2.55625,7.8075) to (2.45281,7.82437)
|
||||||
|
line from (2.45281,7.82437) to (2.37,7.83)
|
||||||
|
line from (2,5.54) to (2,4.755);
|
||||||
|
line from (1.18,5.54) to (1.7,5.54);
|
||||||
|
line from (1.7,5.54) to (1.7,4.755);
|
||||||
|
grp3() with (0,0) at (-0.125,0);
|
||||||
|
.PE
|
1429
sys/doc/plumb.ms
Normal file
1429
sys/doc/plumb.ms
Normal file
File diff suppressed because it is too large
Load diff
12232
sys/doc/plumb.ps
Normal file
12232
sys/doc/plumb.ps
Normal file
File diff suppressed because it is too large
Load diff
499
sys/doc/port.ms
Normal file
499
sys/doc/port.ms
Normal file
|
@ -0,0 +1,499 @@
|
||||||
|
.HTML "The Various Ports
|
||||||
|
.TL
|
||||||
|
The Various Ports
|
||||||
|
.PP
|
||||||
|
This document collects comments about the various
|
||||||
|
architectures supported by Plan 9.
|
||||||
|
The system tries to hide most of the differences between machines,
|
||||||
|
so the machines as seen by a Plan 9
|
||||||
|
user look different from how they are perceived through commercial software.
|
||||||
|
Also, because we are a small group, we couldn't do everything:
|
||||||
|
exploit every optimization, support every model,
|
||||||
|
drive every device.
|
||||||
|
This document records what we
|
||||||
|
.I have
|
||||||
|
done.
|
||||||
|
The first section discusses the compiler/assembler/loader suite for each machine.
|
||||||
|
The second talks about
|
||||||
|
the operating system implemented on each of the various
|
||||||
|
machines.
|
||||||
|
.SH
|
||||||
|
The Motorola MC68020 compiler
|
||||||
|
.PP
|
||||||
|
This is the oldest compiler of the bunch. Relative to its
|
||||||
|
competitors\(emcommercial compilers for the same machine\(emit generates
|
||||||
|
quite good code.
|
||||||
|
It assumes at least a 68020 architecture: some of the addressing
|
||||||
|
modes it generates are not on the 68000 or 68010.
|
||||||
|
.PP
|
||||||
|
We also use this compiler for the 68040. Except for a few
|
||||||
|
instructions and registers available only from assembly language,
|
||||||
|
the only user-visible difference between these machines is in
|
||||||
|
floating point. Our 68020s all have 68881 or 68882 floating
|
||||||
|
point units attached, so to execute floating point programs we
|
||||||
|
depend on there being appropriate hardware.
|
||||||
|
Unfortunately, the 68040 is not quite so thorough in its implementation
|
||||||
|
of the IEEE 754 standard or in its provision of built-in instructions
|
||||||
|
for the
|
||||||
|
transcendental functions. The latter was easy to get around: we
|
||||||
|
don't use them on the 68020 either, but we do have a library,
|
||||||
|
.CW -l68881 ,
|
||||||
|
that you can use if you need the performance (which can be
|
||||||
|
substantial:
|
||||||
|
.CW astro
|
||||||
|
runs twice as fast).
|
||||||
|
We don't use this library by default because we want to run the same
|
||||||
|
binaries on both machines and don't want to emulate
|
||||||
|
.CW FCOSH
|
||||||
|
in the operating system.
|
||||||
|
.PP
|
||||||
|
The problem with IEEE is nastier. We didn't really want to deal
|
||||||
|
with gradual underflow and all that, especially since we had
|
||||||
|
half a dozen machines we'd need to do it on, so on the 68040
|
||||||
|
we implement non-trapping underflow as truncation to zero and
|
||||||
|
do nothing about denormalized numbers and not-a-numbers.
|
||||||
|
This means the 68020
|
||||||
|
and the 68040 are not precisely compatible.
|
||||||
|
.SH
|
||||||
|
The Motorola MC68000 compiler
|
||||||
|
.PP
|
||||||
|
This compiler is a stripped-down version of the MC68020 compiler
|
||||||
|
built for an abortive port to the Dragonball processor on the Palm Pilot.
|
||||||
|
It generates position-independent code whose overall quality is much
|
||||||
|
poorer than the code for the MC68020.
|
||||||
|
.SH
|
||||||
|
The MIPS compiler
|
||||||
|
.PP
|
||||||
|
This compiler generates code for the R2000, R3000, and R4000 machines configured
|
||||||
|
to be big-endians. The compiler generates no R4000-specific instructions
|
||||||
|
although the assembler and loader support the new user-mode instructions.
|
||||||
|
There are options to generate code for little-endian machines.
|
||||||
|
Considering its speed, the Plan 9 compiler generates good code,
|
||||||
|
but the commercial
|
||||||
|
MIPS compiler with all the stops pulled out consistently beats it
|
||||||
|
by 20% or so, sometimes more. Since ours compiles about 10 times
|
||||||
|
faster and we spend most of our time compiling anyway,
|
||||||
|
we are content with the tradeoff.
|
||||||
|
.PP
|
||||||
|
The compiler is solid: we've used it for several big projects and, of course,
|
||||||
|
all our applications run under it.
|
||||||
|
The behavior of floating-point programs is much like on the 68040:
|
||||||
|
the operating system emulates where necessary to get past non-trapping
|
||||||
|
underflow and overflow, but does not handle gradual underflow or
|
||||||
|
denormalized numbers or not-a-numbers.
|
||||||
|
.SH
|
||||||
|
The SPARC compiler
|
||||||
|
.PP
|
||||||
|
The SPARC compiler is also solid and fast, although we haven't
|
||||||
|
used it for a few years, due to a lack of current hardware. We have seen it do
|
||||||
|
much better than GCC with all the optimizations, but on average
|
||||||
|
it is probably about the same.
|
||||||
|
.PP
|
||||||
|
We used to run some old SPARC machines with no multiply or divide instructions,
|
||||||
|
so the compiler
|
||||||
|
does not produce them by default.
|
||||||
|
Instead it calls internal subroutines.
|
||||||
|
A loader flag,
|
||||||
|
.CW -M ,
|
||||||
|
causes the instructions to be emitted. The operating system has
|
||||||
|
trap code to emulate them if necessary, but the traps are slower than
|
||||||
|
emulating them in user mode.
|
||||||
|
In any modern lab, in which SPARCS have the instructions, it would be worth enabling the
|
||||||
|
.CW -M
|
||||||
|
flag by default.
|
||||||
|
.PP
|
||||||
|
The floating point story is the same as on the MIPS.
|
||||||
|
.SH
|
||||||
|
The Intel i386 compiler
|
||||||
|
.PP
|
||||||
|
This is really an
|
||||||
|
.I x 86
|
||||||
|
compiler, for
|
||||||
|
.I x >2.
|
||||||
|
It works only
|
||||||
|
if the machine is in 32-bit protected mode.
|
||||||
|
It is solid and generates tolerable code; it is our main compiler these days.
|
||||||
|
.PP
|
||||||
|
Floating point is well-behaved, but the compiler assumes i387-compatible
|
||||||
|
hardware to execute
|
||||||
|
the instructions. With 387 hardware,
|
||||||
|
the system does the full IEEE 754 job, just like
|
||||||
|
the MC68881. By default, the libraries don't use the 387 built-ins for
|
||||||
|
transcendentals.
|
||||||
|
If you want them,
|
||||||
|
build the code in
|
||||||
|
.CW /sys/src/libc/386/387 .
|
||||||
|
.SH
|
||||||
|
The Intel i960 compiler
|
||||||
|
.PP
|
||||||
|
This compiler was built as a weekend hack to let us get the Cyclone
|
||||||
|
boards running. It has only been used to run one program\(emthe on-board
|
||||||
|
code in the Cyclone\(emand is therefore likely to be buggy.
|
||||||
|
There are a number of obvious optimizations to the code that have
|
||||||
|
never been attempted.
|
||||||
|
For example, the compiler does not support pipelining.
|
||||||
|
The code runs in little-endian mode.
|
||||||
|
.SH
|
||||||
|
The DEC Alpha compiler
|
||||||
|
.PP
|
||||||
|
The Alpha compiler is based on a port done by David Hogan while
|
||||||
|
studying at the Basser Department of Computer Science, University of Sydney.
|
||||||
|
It has been used to build a running version of the operating system, but has
|
||||||
|
not been stressed as much as some of the other compilers.
|
||||||
|
.PP
|
||||||
|
Although the Alpha is a 64-bit architecture, this compiler treats
|
||||||
|
.CW int s,
|
||||||
|
.CW long s
|
||||||
|
and pointers as 32 bits. Access to the 64-bit operations is available through the
|
||||||
|
.CW vlong
|
||||||
|
type, as with the other architectures.
|
||||||
|
.PP
|
||||||
|
The compiler assumes that the target CPU supports the optional byte and
|
||||||
|
word memory operations (the ``BWX'' extension).
|
||||||
|
If you have an old system, you can generate code without using the extension
|
||||||
|
by passing the loader the
|
||||||
|
.CW -x
|
||||||
|
option.
|
||||||
|
.PP
|
||||||
|
There are a number of optimizations that the Alpha Architecture Handbook
|
||||||
|
recommends, but this compiler does not do. In particular, there is currently
|
||||||
|
no support for the code alignment and code scheduling optimizations.
|
||||||
|
.PP
|
||||||
|
The compiler tries to conform to IEEE, but some Alpha CPUs do not implement
|
||||||
|
all of the rounding and trapping modes in silicon. Fixing this problem requires
|
||||||
|
some software emulation code in the kernel; to date, this has not been attempted.
|
||||||
|
.SH
|
||||||
|
The PowerPC compiler
|
||||||
|
.PP
|
||||||
|
The PowerPC compiler supports the 32-bit PowerPC architecture only;
|
||||||
|
it does not support either the 64-bit extensions or the POWER compatibility instructions.
|
||||||
|
It has been used for production operating system work on the 603, 603e, 604e, 821, 823, and 860,
|
||||||
|
and experimental work on the 405, 440 and 450.
|
||||||
|
On the 8xx floating-point instructions must be emulated.
|
||||||
|
Instruction scheduling is not implemented; otherwise the code generated
|
||||||
|
is similar to that for the other load-store architectures.
|
||||||
|
The compiler makes little or no use of unusual PowerPC features such as the
|
||||||
|
counter register, several condition code registers, and multiply-accumulate
|
||||||
|
instructions, but they are sometimes
|
||||||
|
used by assembly language routines in the libraries.
|
||||||
|
.SH
|
||||||
|
The ARM compiler
|
||||||
|
.PP
|
||||||
|
The ARM compiler is fairly solid; it has been used for some production
|
||||||
|
operating system work including Inferno and the Plan 9 kernel
|
||||||
|
for the iPAQ, which uses a StrongArm SA1, and the Sheevaplug,
|
||||||
|
Guruplug, Dreamplug and others.
|
||||||
|
The compiler supports the ARMv4 architecture;
|
||||||
|
it does not support the Thumb instruction sets.
|
||||||
|
It has been used on ARM7500FE, ARM926 and Cortex-A8 processors
|
||||||
|
and the Strongarm SA1 core machines.
|
||||||
|
The compiler generates instructions for
|
||||||
|
ARM 7500 FPA floating-point coprocessor 1,
|
||||||
|
but probably should instead generate VFP 3+ instructions
|
||||||
|
for coprocessors 10 and 11.
|
||||||
|
.SH
|
||||||
|
The AMD 29000 compiler
|
||||||
|
.PP
|
||||||
|
This compiler was used to port an operating system to an AMD 29240 processor.
|
||||||
|
The project is long abandoned, but the compiler lives on.
|
||||||
|
.SH
|
||||||
|
The Carrera operating system
|
||||||
|
.PP
|
||||||
|
We used to have a number of MIPS R4400 PC-like devices called Carreras,
|
||||||
|
with custom-built frame buffers, that we used as terminals.
|
||||||
|
They're almost all decommissioned now, but we're including the source as a reference
|
||||||
|
in case someone wants to get another MIPS-based system running.
|
||||||
|
.SH
|
||||||
|
The IBM PC operating system
|
||||||
|
.PP
|
||||||
|
The PC version of Plan 9 can boot either from MS-DOS
|
||||||
|
or directly from a disk created by the
|
||||||
|
.CW format
|
||||||
|
command; see
|
||||||
|
.I prep (8).
|
||||||
|
Plan 9 runs in 32-bit mode\(emwhich requires a 386 or later model x86 processor\(emand
|
||||||
|
has an interrupt-driven I/O system, so it does not
|
||||||
|
use the BIOS (except for a small portion of the boot program and floppy boot block).
|
||||||
|
This helps performance but limits the set of I/O devices that it can support without
|
||||||
|
special code.
|
||||||
|
.PP
|
||||||
|
Plan 9 supports the ISA, EISA, and PCI buses as well as PCMCIA and PC card devices.
|
||||||
|
It is infeasible to list all the supported machines, because
|
||||||
|
the PC-clone marketplace is too volatile and there is
|
||||||
|
no guarantee that the machine you buy today will contain the
|
||||||
|
same components as the one you bought yesterday.
|
||||||
|
(For our lab, we buy components and assemble the machines
|
||||||
|
ourselves in an attempt to lessen this effect.)
|
||||||
|
Both IDE/ATA and SCSI disks are supported, and
|
||||||
|
there is support for large ATA drives.
|
||||||
|
CD-ROMs are supported two ways, either on the SCSI bus, or as ATA(PI) devices.
|
||||||
|
The SCSI adapter must be a member of the Mylex Multimaster (old Buslogic BT-*) series
|
||||||
|
or the Symbios 53C8XX series.
|
||||||
|
Supported Ethernet cards include the
|
||||||
|
AMD79C790,
|
||||||
|
3COM Etherlink III and 3C589 series,
|
||||||
|
Lucent Wavelan and compatibles,
|
||||||
|
NE2000,
|
||||||
|
WD8003,
|
||||||
|
WD8013,
|
||||||
|
SMC Elite and Elite Ultra,
|
||||||
|
Linksys Combo EthernetCard and EtherFast 10/100,
|
||||||
|
and a variety of controllers based on the
|
||||||
|
Intel i8255[789] and Digital (now Intel) 21114x chips.
|
||||||
|
We mostly use Etherlink III, i8255[789], and 21114x, so those drivers may be more robust.
|
||||||
|
There must be an explicit Plan 9 driver for peripherals;
|
||||||
|
it cannot use DOS or Windows drivers.
|
||||||
|
Also,
|
||||||
|
Plan 9 cannot exploit special hardware-related features that fall outside of the
|
||||||
|
IBM PC model,
|
||||||
|
such as power management,
|
||||||
|
unless architecture-dependent code is added to the kernel.
|
||||||
|
For more details see
|
||||||
|
.I plan9.ini (8).
|
||||||
|
.PP
|
||||||
|
Over the years,
|
||||||
|
Plan 9 has run on a number of VGA cards.
|
||||||
|
Recent changes to the graphics system have not been
|
||||||
|
tested on most of the older cards; some effort may be needed to get them working again.
|
||||||
|
In our lab, most of our machines use the ATI Mach64, S3 ViRGE, or S3 Savage chips,
|
||||||
|
so such devices are probably
|
||||||
|
the most reliable.
|
||||||
|
We also use a few Matrox and TNT cards.
|
||||||
|
The system requires a hardware cursor.
|
||||||
|
For more details see
|
||||||
|
.I vgadb (6)
|
||||||
|
and
|
||||||
|
.I vga (8).
|
||||||
|
The wiki
|
||||||
|
.CW http://plan9.bell-labs.com/wiki/plan9 ) (
|
||||||
|
contains the definitive list of cards that are known to work; see the ``supported PC hardware''
|
||||||
|
page.
|
||||||
|
.PP
|
||||||
|
For audio, Plan 9 supports the Sound Blaster 16 and compatibles.
|
||||||
|
(Note that audio doesn't work under Plan 9 with 8-bit Sound Blasters.)
|
||||||
|
There is also user-level support for USB audio devices; see
|
||||||
|
.I usb (4).
|
||||||
|
.PP
|
||||||
|
Finally, it's important to have a three-button mouse with Plan 9.
|
||||||
|
The system currently works only with mice on the PS/2 port or USB.
|
||||||
|
Serial mouse support should return before long.
|
||||||
|
.PP
|
||||||
|
Once you have Plan 9 installed (see the wiki's installation document)
|
||||||
|
run the program
|
||||||
|
.CW ld
|
||||||
|
from DOS
|
||||||
|
or use a boot disk. See
|
||||||
|
.I booting (8),
|
||||||
|
.I 9load (8),
|
||||||
|
and
|
||||||
|
.I prep (8)
|
||||||
|
for more information.
|
||||||
|
.SH
|
||||||
|
The Alpha PC operating system
|
||||||
|
.PP
|
||||||
|
Plan 9 runs on the Alpha PC 164.
|
||||||
|
The Alpha port has not been used as much as the others,
|
||||||
|
and should be considered a preliminary release.
|
||||||
|
.PP
|
||||||
|
The port uses the OSF/1 flavor
|
||||||
|
of PALcode, and should be booted from the SRM firmware (booting
|
||||||
|
from ARC is not supported).
|
||||||
|
Supported devices are a subset of the PC ones; currently
|
||||||
|
this includes DECchip 2114x-based ethernet cards, S3 VGA cards,
|
||||||
|
Sound Blaster 16-compatible audio, floppy drives, and ATA hard disks.
|
||||||
|
.PP
|
||||||
|
The system has to be booted via tftp.
|
||||||
|
See
|
||||||
|
.I booting (8)
|
||||||
|
for details.
|
||||||
|
.SH
|
||||||
|
The PowerPC operating system
|
||||||
|
.PP
|
||||||
|
We have a version of the system that runs on the PowerPC
|
||||||
|
on a home-grown machine called Viaduct.
|
||||||
|
The Viaduct minibrick is a small (12x9x3 cm) low-cost embedded
|
||||||
|
computer consisting of a 50Mhz MPC850, 16MB sdram, 2MB flash,
|
||||||
|
and two 10Mb Ethernet ports. It is designed for home/SOHO
|
||||||
|
networking applications such as VPN, firewalls, NAT, etc.
|
||||||
|
.PP
|
||||||
|
The kernel has also been ported to the Motorola MTX embedded motherboard;
|
||||||
|
that port is included in the distribution.
|
||||||
|
The port only works with a 604e processor (the 603e is substantially different)
|
||||||
|
and at present only a single CPU is permitted.
|
||||||
|
.SH
|
||||||
|
The Compaq iPAQ operating system
|
||||||
|
.PP
|
||||||
|
Plan 9 was ported to Compaq's iPAQ Pocket PC,
|
||||||
|
which uses the StrongArm SA1 processor.
|
||||||
|
The model we have is a 3630; neighboring models also work.
|
||||||
|
The kernel can drive a PCMCIA sleeve with a WaveLAN card, but no other PCMCIA
|
||||||
|
devices have been ported yet.
|
||||||
|
.PP
|
||||||
|
The iPAQ runs
|
||||||
|
.CW rio
|
||||||
|
with a small keyboard application that allows Palm-style handwriting
|
||||||
|
input as well as typing with the stylus on a miniature keyboard.
|
||||||
|
.PP
|
||||||
|
Fco. J. Ballesteros
|
||||||
|
.CW nemo@plan9.escet.urjc.es ) (
|
||||||
|
added support for hibernation, but we haven't been able to
|
||||||
|
get that to work again in the new kernel; the code is there, however,
|
||||||
|
for volunteers to play with.
|
||||||
|
See the file
|
||||||
|
.CW /sys/src/9/bitsy/Booting101
|
||||||
|
for information about installing Plan 9 on the iPAQ.
|
||||||
|
.SH
|
||||||
|
The Marvell Kirkwood operating system
|
||||||
|
.PP
|
||||||
|
This is an ARM kernel for the ARM926EJ-S processor
|
||||||
|
and it emulates floating-point and
|
||||||
|
CAS (compare-and-swap) instructions.
|
||||||
|
It is known to run on the Sheevaplug, Guruplug, Dreamplug
|
||||||
|
and Openrd-client boards.
|
||||||
|
It is derived from a port of native Inferno to the Sheevaplug
|
||||||
|
by Salva Peir\f(Jpó\fP and Mechiel Lukkien.
|
||||||
|
There are many features of the Kirkwood system-on-a-chip
|
||||||
|
that it does not exploit.
|
||||||
|
There are currently drivers for up to two
|
||||||
|
Gigabit Ethernet interfaces,
|
||||||
|
USB and the console serial port;
|
||||||
|
we hope to add crypto acceleration, and a video driver for the Openrd-client.
|
||||||
|
.SH
|
||||||
|
The Marvell PXA168 operating system
|
||||||
|
.PP
|
||||||
|
This is an ARM kernel for the ARM-v5-architecture processor in the
|
||||||
|
Marvell PXA168 system-on-a-chip
|
||||||
|
and it emulates floating-point and
|
||||||
|
CAS (compare-and-swap) instructions.
|
||||||
|
It is known to run on the Guruplug Display.
|
||||||
|
There are many features of the system-on-a-chip
|
||||||
|
that it does not exploit.
|
||||||
|
There are currently drivers for
|
||||||
|
a Fast Ethernet interface,
|
||||||
|
.\" USB
|
||||||
|
and the console serial port;
|
||||||
|
we hope to add crypto acceleration, and a video driver.
|
||||||
|
.SH
|
||||||
|
The TI OMAP35 operating system
|
||||||
|
.PP
|
||||||
|
This is an ARM kernel for the Cortex-A8 processor
|
||||||
|
and it emulates pre-VFPv3 floating-point and
|
||||||
|
CAS (compare-and-swap) instructions.
|
||||||
|
It is known to run on the IGEPv2 board and the Gumstix Overo,
|
||||||
|
and might eventually run on the Beagleboard, once USB is working.
|
||||||
|
There are many features of the OMAP system-on-a-chip that it does not exploit.
|
||||||
|
Initially, there are drivers for the SMSC 9221 100Mb/s Ethernet
|
||||||
|
interface in the IGEPv2 and Overo,
|
||||||
|
and the console serial port;
|
||||||
|
we hope to add USB, flash memory and video drivers.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.ig
|
||||||
|
.SH
|
||||||
|
The file server
|
||||||
|
.PP
|
||||||
|
The file server runs on only a handful of distinct machines.
|
||||||
|
It is a stand-alone program, distantly related to the CPU server
|
||||||
|
code, that runs no user code: all it does is serve files on
|
||||||
|
network connections.
|
||||||
|
It supports only SCSI disks, which can be interleaved for
|
||||||
|
faster throughput.
|
||||||
|
A DOS file on
|
||||||
|
an IDE drive can hold the configuration information.
|
||||||
|
See
|
||||||
|
.I fsconfig (8)
|
||||||
|
for an explanation of how
|
||||||
|
to configure a file server.
|
||||||
|
.PP
|
||||||
|
To boot a file server, follow the directions for booting a CPU server
|
||||||
|
using the file name
|
||||||
|
.CW 9\f2machtype\fPfs
|
||||||
|
where
|
||||||
|
.I machtype
|
||||||
|
is
|
||||||
|
.CW pc ,
|
||||||
|
etc. as appropriate.
|
||||||
|
We are releasing only the PC version.
|
||||||
|
.SH
|
||||||
|
The IBM PC file server
|
||||||
|
.PP
|
||||||
|
Except for the restriction to SCSI disks,
|
||||||
|
the PC file server has the same hardware requirements as
|
||||||
|
the regular PC operating system.
|
||||||
|
However, only a subset of the supported SCSI (Adaptec 1542, Mylex Multimaster,
|
||||||
|
and Symbios 53C8XX) and Ethernet (Digital 2114x,
|
||||||
|
Intel 8255x, and 3Com) controllers
|
||||||
|
may be
|
||||||
|
used.
|
||||||
|
Any of the boot methods described in
|
||||||
|
.I 9load (8)
|
||||||
|
will work.
|
||||||
|
.PP
|
||||||
|
To boot any PC, the file
|
||||||
|
.CW 9load
|
||||||
|
must reside on a MS-DOS formatted floppy, IDE disk,
|
||||||
|
or SCSI disk.
|
||||||
|
However, PCs have no non-volatile RAM in which the
|
||||||
|
file server can store its configuration information, so the system
|
||||||
|
stores it in a file on an MS-DOS file system instead.
|
||||||
|
This file, however, cannot live on a SCSI disk, only a floppy or IDE.
|
||||||
|
(This restriction avoids a lot of duplicated interfaces in the
|
||||||
|
system.)
|
||||||
|
Thus the file server cannot be all-SCSI.
|
||||||
|
See
|
||||||
|
.I plan9.ini (8)
|
||||||
|
for details about the
|
||||||
|
.I nvr
|
||||||
|
variable and specifying the console device.
|
||||||
|
.SH
|
||||||
|
Backup
|
||||||
|
.PP
|
||||||
|
Our main file server is unlikely to be much like yours.
|
||||||
|
It is a PC with 128 megabytes
|
||||||
|
of cache memory, 56 gigabytes of SCSI magnetic
|
||||||
|
disk, and a Hewlett-Packard SureStore Optical 1200ex
|
||||||
|
magneto-optical jukebox, with 1.2 terabytes of storage.
|
||||||
|
This driver runs the SCSI standard jukebox protocol.
|
||||||
|
We also have a driver for a (non-standard)
|
||||||
|
SONY WDA-610
|
||||||
|
Writable Disk Auto Changer (WORM),
|
||||||
|
which stores almost 350 gigabytes of data.
|
||||||
|
.PP
|
||||||
|
The WORM is actually the prime storage; the SCSI disk is just
|
||||||
|
a cache to improve performance.
|
||||||
|
Early each morning the system constructs on WORM an image of
|
||||||
|
the entire system as it appears that day. Our backup system
|
||||||
|
is therefore just a file server that lets
|
||||||
|
you look at yesterday's (or last year's) file system.
|
||||||
|
.PP
|
||||||
|
If you don't have a magneto-optical jukebox,
|
||||||
|
you might consider attaching a CD-R jukebox or even just
|
||||||
|
using a single WORM drive and managing the dumps a little less
|
||||||
|
automatically. This is just a long way of saying that the
|
||||||
|
system as distributed has no explicit method of backup other
|
||||||
|
than through the WORM jukebox.
|
||||||
|
.PP
|
||||||
|
Not everyone can invest in such expensive hardware, however.
|
||||||
|
Although it wouldn't be as luxurious,
|
||||||
|
it would be possible to use
|
||||||
|
.I mkfs (8)
|
||||||
|
to build regular file system archives and use
|
||||||
|
.I scuzz (8)
|
||||||
|
to stream them to a SCSI 8mm tape drive.
|
||||||
|
.CW Mkext
|
||||||
|
could then extract them.
|
||||||
|
Another alternative is to use
|
||||||
|
.I dump9660
|
||||||
|
(see
|
||||||
|
.I mk9660 (8)),
|
||||||
|
which stores incremental backups on CD images
|
||||||
|
in the form of a dump hierarchy.
|
||||||
|
.PP
|
||||||
|
It is also possible to treat a regular disk, or even a part of a disk,
|
||||||
|
as a fake WORM, which can then be streamed to tape when it fills.
|
||||||
|
This is a bad idea for a production system but a good way to
|
||||||
|
learn about the WORM software.
|
||||||
|
Again, see
|
||||||
|
.I fsconfig (8)
|
||||||
|
for details.
|
||||||
|
..
|
6091
sys/doc/port.ps
Normal file
6091
sys/doc/port.ps
Normal file
File diff suppressed because it is too large
Load diff
3128
sys/doc/preamble
Normal file
3128
sys/doc/preamble
Normal file
File diff suppressed because it is too large
Load diff
184
sys/doc/prfile
Normal file
184
sys/doc/prfile
Normal file
|
@ -0,0 +1,184 @@
|
||||||
|
#!/bin/rc
|
||||||
|
|
||||||
|
switch($#*){
|
||||||
|
case 1
|
||||||
|
outfile = $1
|
||||||
|
infile = $1.ms
|
||||||
|
case *
|
||||||
|
outfile = $1
|
||||||
|
shift
|
||||||
|
infile = $*
|
||||||
|
}
|
||||||
|
|
||||||
|
FONTS='.FP lucidasans'
|
||||||
|
|
||||||
|
MACS ='.de BT
|
||||||
|
.nr PX \\n(.s
|
||||||
|
.nr PF \\n(.f
|
||||||
|
.nr Bt 1
|
||||||
|
.ft 1
|
||||||
|
.ps \\n(PS
|
||||||
|
''lt \\n(LTu
|
||||||
|
.po \\n(POu
|
||||||
|
.if \\n%>0 .tl \(ts\\*(LF\(ts\\*(CF\(ts\\*(RF\(ts
|
||||||
|
.ft \\n(PF
|
||||||
|
.ps \\n(PX
|
||||||
|
..
|
||||||
|
.de PT
|
||||||
|
.lt \\n(LLu
|
||||||
|
.pc %
|
||||||
|
.nr PN \\n%
|
||||||
|
.nr Ps \\n(PS-1
|
||||||
|
.if \\n(Bt>0 .if e .tl @\\n% \s\\n(Ps\\*(Au\s0@@@
|
||||||
|
.if \\n(Bt>0 .if o .tl @@@\f2\\*(Tl\\f1 \\n%@
|
||||||
|
.lt \\n(.lu
|
||||||
|
..'
|
||||||
|
|
||||||
|
|
||||||
|
macros = -ms
|
||||||
|
|
||||||
|
switch($outfile){
|
||||||
|
case 8½ acme gfx panel sam
|
||||||
|
macros = ($macros -mpictures)
|
||||||
|
}
|
||||||
|
|
||||||
|
switch($outfile){
|
||||||
|
case 9 comp 8½ utf acme
|
||||||
|
macros = ($macros -mnihongo)
|
||||||
|
}
|
||||||
|
|
||||||
|
fn assemble{
|
||||||
|
switch($1){
|
||||||
|
case 9
|
||||||
|
pageno = 1
|
||||||
|
title = 'Plan 9 From Bell Labs'
|
||||||
|
author = 'INTRODUCTION'
|
||||||
|
case README
|
||||||
|
pageno = 23
|
||||||
|
title = '\s-1README\s0'
|
||||||
|
author = 'INTRODUCTION'
|
||||||
|
case names
|
||||||
|
pageno = 29
|
||||||
|
title = 'The Use of Name Spaces in Plan 9'
|
||||||
|
author = 'INTRODUCTION'
|
||||||
|
case net
|
||||||
|
pageno = 35
|
||||||
|
title = 'The Organization of Networks in Plan 9'
|
||||||
|
author = 'INTRODUCTION'
|
||||||
|
case comp
|
||||||
|
pageno = 49
|
||||||
|
title = 'How to Use the Plan 9 C Compiler'
|
||||||
|
author = 'PROGRAMMING'
|
||||||
|
case ape
|
||||||
|
pageno = 63
|
||||||
|
title = 'APE \(em The ANSI/POSIX Environment'
|
||||||
|
author = 'PROGRAMMING'
|
||||||
|
case ug
|
||||||
|
pageno = 67
|
||||||
|
title = 'Alef User''s Guide'
|
||||||
|
author = 'PROGRAMMING'
|
||||||
|
case alef
|
||||||
|
pageno = 103
|
||||||
|
title = 'Alef Language Reference Manual'
|
||||||
|
author = 'PROGRAMMING'
|
||||||
|
case acidpaper
|
||||||
|
pageno = 141
|
||||||
|
title = 'Acid: A Debugger Built From A Language'
|
||||||
|
author = 'PROGRAMMING'
|
||||||
|
case acid
|
||||||
|
pageno = 155
|
||||||
|
title = 'Acid Manual'
|
||||||
|
author = 'PROGRAMMING'
|
||||||
|
case mk
|
||||||
|
pageno = 181
|
||||||
|
title = 'Maintaining Files on Plan 9 with Mk'
|
||||||
|
author = 'PROGRAMMING'
|
||||||
|
case mkfiles
|
||||||
|
pageno = 195
|
||||||
|
title = 'Plan 9 Mkfiles'
|
||||||
|
author = 'PROGRAMMING'
|
||||||
|
case asm
|
||||||
|
pageno = 203
|
||||||
|
title = 'A Manual for the Plan 9 assembler'
|
||||||
|
author = 'PROGRAMMING'
|
||||||
|
case 8½
|
||||||
|
pageno = 211
|
||||||
|
title = '8½, the Plan 9 Window System'
|
||||||
|
author = 'USER INTERFACES'
|
||||||
|
case rc
|
||||||
|
pageno = 221
|
||||||
|
title = 'Rc \(em The Plan 9 Shell'
|
||||||
|
author = 'USER INTERFACES'
|
||||||
|
case sam
|
||||||
|
pageno = 237
|
||||||
|
title = 'The Text Editor Sam'
|
||||||
|
author = 'USER INTERFACES'
|
||||||
|
case acme # actually done in acme/mkfile
|
||||||
|
pageno = 267
|
||||||
|
title = 'The Text Editor Sam'
|
||||||
|
author = 'USER INTERFACES'
|
||||||
|
case utf
|
||||||
|
pageno = 283
|
||||||
|
title = 'Hello World, or \f1\S''12''Καλημέρα κόσμε\fP\S''0'', or \f(Jpこんにちは 世界\fP'
|
||||||
|
author = 'IMPLEMENTATION'
|
||||||
|
case compiler
|
||||||
|
pageno = 295
|
||||||
|
title = 'Plan 9 C Compilers'
|
||||||
|
author = 'IMPLEMENTATION'
|
||||||
|
case libmach
|
||||||
|
pageno = 305
|
||||||
|
title = 'Adding Application Support for a New Architecture'
|
||||||
|
author = 'IMPLEMENTATION'
|
||||||
|
case fs
|
||||||
|
pageno = 313
|
||||||
|
title = 'The Plan 9 File Server'
|
||||||
|
author = 'IMPLEMENTATION'
|
||||||
|
case il
|
||||||
|
pageno = 321
|
||||||
|
title = 'The IL Protocol'
|
||||||
|
author = 'IMPLEMENTATION'
|
||||||
|
case sleep
|
||||||
|
pageno = 327
|
||||||
|
title = 'Process Sleep and Wakeup on a Shared-memory Multiprocessor'
|
||||||
|
author = 'IMPLEMENTATION'
|
||||||
|
case gfx
|
||||||
|
pageno = 333
|
||||||
|
title = 'Raster Graphics in Plan 9'
|
||||||
|
author = 'MISCELLANY'
|
||||||
|
case panel
|
||||||
|
pageno = 343
|
||||||
|
title = 'A Quick Introduction to the Panel Library'
|
||||||
|
author = 'MISCELLANY'
|
||||||
|
case lp
|
||||||
|
pageno = 363
|
||||||
|
title = 'A Guide to the Lp Printer Spooler'
|
||||||
|
author = 'MISCELLANY'
|
||||||
|
case troff
|
||||||
|
pageno = 371
|
||||||
|
title = 'Troff User''s Manual'
|
||||||
|
author = 'MISCELLANY'
|
||||||
|
case spin
|
||||||
|
pageno = 411
|
||||||
|
title = 'Using SPIN'
|
||||||
|
author = 'MISCELLANY'
|
||||||
|
case port
|
||||||
|
pageno = 439
|
||||||
|
title = 'The Various Ports'
|
||||||
|
author = 'INSTALLATION'
|
||||||
|
case install
|
||||||
|
pageno = 447
|
||||||
|
title = 'Installing the Plan 9 Distribution'
|
||||||
|
author = 'INSTALLATION'
|
||||||
|
case *
|
||||||
|
echo $1 page number not known >[2=1]
|
||||||
|
exit page
|
||||||
|
}
|
||||||
|
echo $FONTS
|
||||||
|
echo .pn $pageno
|
||||||
|
echo .ds Tl "$title
|
||||||
|
echo .ds Au "$author
|
||||||
|
echo $MACS
|
||||||
|
pic $infile | tbl | eqn
|
||||||
|
}
|
||||||
|
|
||||||
|
assemble $outfile | troff $macros | lp -m.9 -dstdout > $outfile.bs
|
606
sys/doc/prog4.ms
Normal file
606
sys/doc/prog4.ms
Normal file
|
@ -0,0 +1,606 @@
|
||||||
|
.HTML "Changes to the Programming Environment in the Fourth Release of Plan 9
|
||||||
|
.FP lucidasans
|
||||||
|
.TL
|
||||||
|
Changes to the Programming Environment
|
||||||
|
.br
|
||||||
|
in the
|
||||||
|
.br
|
||||||
|
Fourth Release of Plan 9
|
||||||
|
.AU
|
||||||
|
Rob Pike
|
||||||
|
.sp
|
||||||
|
rob@plan9.bell-labs.com
|
||||||
|
.SH
|
||||||
|
Introduction
|
||||||
|
.PP
|
||||||
|
The fourth release of Plan 9 includes changes at many levels of the system,
|
||||||
|
with repercussions in the libraries and program interfaces.
|
||||||
|
This document summarizes the changes and describes how
|
||||||
|
existing programs must be modified to run in the new release.
|
||||||
|
It is not exhaustive, of course; for further detail about any of the
|
||||||
|
topics refer to the manual pages, as always.
|
||||||
|
.PP
|
||||||
|
Programmers new to Plan 9 may find valuable tidbits here, but the
|
||||||
|
real audience for this paper is those with a need to update applications
|
||||||
|
and servers written in C for earlier releases of the Plan 9 operating system.
|
||||||
|
.SH
|
||||||
|
9P, NAMELEN, and strings
|
||||||
|
.PP
|
||||||
|
The underlying file service protocol for Plan 9, 9P, retains its basic form
|
||||||
|
but has had a number of adjustments to deal with longer file names and error strings,
|
||||||
|
new authentication mechanisms, and to make it more efficient at
|
||||||
|
evaluating file names.
|
||||||
|
The change to file names affects a number of system interfaces;
|
||||||
|
because file name elements are no longer of fixed size, they can
|
||||||
|
no longer be stored as arrays.
|
||||||
|
.PP
|
||||||
|
9P used to be a fixed-format protocol with
|
||||||
|
.CW NAMELEN -sized
|
||||||
|
byte arrays representing file name elements.
|
||||||
|
Now, it is a variable-format protocol, as described in
|
||||||
|
.I intro (5),
|
||||||
|
in which strings are represented by a count followed by that many bytes.
|
||||||
|
Thus, the string
|
||||||
|
.CW ken
|
||||||
|
would previously have occupied 28
|
||||||
|
.CW NAMELEN ) (
|
||||||
|
bytes in the message; now it occupies 5: a two-byte count followed by the three bytes of
|
||||||
|
.CW ken
|
||||||
|
and no terminal zero.
|
||||||
|
(And of course, a name could now be much longer.)
|
||||||
|
A similar format change has been made to
|
||||||
|
.CW stat
|
||||||
|
buffers: they are no longer
|
||||||
|
.CW DIRLEN
|
||||||
|
bytes long but instead have variable size prefixed by a two-byte count.
|
||||||
|
And in fact the entire 9P message syntax has changed: every message
|
||||||
|
now begins with a message length field that makes it trivial to break the
|
||||||
|
string into messages without parsing them, so
|
||||||
|
.CW aux/fcall
|
||||||
|
is gone.
|
||||||
|
A new library entry point,
|
||||||
|
.CW read9pmsg ,
|
||||||
|
makes it easy for user-level servers to break the client data stream into 9P messages.
|
||||||
|
All servers should switch from using
|
||||||
|
.CW read
|
||||||
|
(or the now gone
|
||||||
|
.CW getS)
|
||||||
|
to using
|
||||||
|
.CW read9pmsg .
|
||||||
|
.PP
|
||||||
|
This change to 9P affects the way strings are handled by the kernel and throughout
|
||||||
|
the system.
|
||||||
|
The consequences are primarily that fixed-size arrays have been replaced
|
||||||
|
by pointers and counts in a variety of system interfaces.
|
||||||
|
Most programs will need at least some adjustment to the new style.
|
||||||
|
In summary:
|
||||||
|
.CW NAMELEN
|
||||||
|
is gone, except as a vestige in the authentication libraries, where it has been
|
||||||
|
rechristened
|
||||||
|
.CW ANAMELEN .
|
||||||
|
.CW DIRLEN
|
||||||
|
and
|
||||||
|
.CW ERRLEN
|
||||||
|
are also gone.
|
||||||
|
All programs that mention
|
||||||
|
these constants
|
||||||
|
will need to be fixed.
|
||||||
|
.PP
|
||||||
|
The simplest place to see this change is in the
|
||||||
|
.CW errstr
|
||||||
|
system call, which no longer assumes a buffer of length
|
||||||
|
.CW ERRLEN
|
||||||
|
but now requires a byte-count argument:
|
||||||
|
.P1
|
||||||
|
char buf[...];
|
||||||
|
|
||||||
|
errstr(buf, sizeof buf);
|
||||||
|
.P2
|
||||||
|
The buffer can be any size you like.
|
||||||
|
For convenience, the kernel stores error strings internally as 256-byte arrays,
|
||||||
|
so if you like \(em but it's not required \(em you can use the defined constant
|
||||||
|
.CW ERRMAX= 256
|
||||||
|
as a good buffer size.
|
||||||
|
Unlike the old
|
||||||
|
.CW ERRLEN
|
||||||
|
(which had value 64),
|
||||||
|
.CW ERRMAX
|
||||||
|
is advisory, not mandatory, and is not part of the 9P specification.
|
||||||
|
.PP
|
||||||
|
With names, stat buffers, and directories, there isn't even an echo of a fixed-size array any more.
|
||||||
|
.SH
|
||||||
|
Directories and wait messages
|
||||||
|
.PP
|
||||||
|
With strings now variable-length, a number of system calls needed to change:
|
||||||
|
.CW errstr ,
|
||||||
|
.CW stat ,
|
||||||
|
.CW fstat ,
|
||||||
|
.CW wstat ,
|
||||||
|
.CW fwstat ,
|
||||||
|
and
|
||||||
|
.CW wait
|
||||||
|
are all affected, as is
|
||||||
|
.CW read
|
||||||
|
when applied to directories.
|
||||||
|
.PP
|
||||||
|
As far as directories are concerned, most programs don't use the system calls
|
||||||
|
directly anyway, since they operate on the machine-independent form, but
|
||||||
|
instead call the machine-dependent
|
||||||
|
.CW Dir
|
||||||
|
routines
|
||||||
|
.CW dirstat ,
|
||||||
|
.CW dirread ,
|
||||||
|
etc.
|
||||||
|
These used to fill user-provided fixed-size buffers; now they return objects allocated
|
||||||
|
by
|
||||||
|
.CW malloc
|
||||||
|
(which must therefore be freed after use).
|
||||||
|
To `stat' a file:
|
||||||
|
.P1
|
||||||
|
Dir *d;
|
||||||
|
|
||||||
|
d = dirstat(filename);
|
||||||
|
if(d == nil){
|
||||||
|
fprint(2, "can't stat %s: %r\en", filename);
|
||||||
|
exits("stat");
|
||||||
|
}
|
||||||
|
use(d);
|
||||||
|
free(d);
|
||||||
|
.P2
|
||||||
|
A common new bug is to forget to free a
|
||||||
|
.CW Dir
|
||||||
|
returned by
|
||||||
|
.CW dirstat .
|
||||||
|
.PP
|
||||||
|
.CW Dirfstat
|
||||||
|
and
|
||||||
|
.CW Dirfwstat
|
||||||
|
work pretty much as before, but changes to 9P make
|
||||||
|
it possible to exercise finer-grained control on what fields
|
||||||
|
of the
|
||||||
|
.CW Dir
|
||||||
|
are to be changed; see
|
||||||
|
.I stat (2)
|
||||||
|
and
|
||||||
|
.I stat (5)
|
||||||
|
for details.
|
||||||
|
.PP
|
||||||
|
Reading a directory works in a similar way to
|
||||||
|
.CW dirstat ,
|
||||||
|
with
|
||||||
|
.CW dirread
|
||||||
|
allocating and filling in an array of
|
||||||
|
.CW Dir
|
||||||
|
structures.
|
||||||
|
The return value is the number of elements of the array.
|
||||||
|
The arguments to
|
||||||
|
.CW dirread
|
||||||
|
now include a pointer to a
|
||||||
|
.CW Dir*
|
||||||
|
to be filled in with the address of the allocated array:
|
||||||
|
.P1
|
||||||
|
Dir *d;
|
||||||
|
int i, n;
|
||||||
|
|
||||||
|
while((n = dirread(fd, &d)) > 0){
|
||||||
|
for(i=0; i<n; i++)
|
||||||
|
use(&d[i]);
|
||||||
|
free(d);
|
||||||
|
}
|
||||||
|
.P2
|
||||||
|
A new library function,
|
||||||
|
.CW dirreadall ,
|
||||||
|
has the same form as
|
||||||
|
.CW dirread
|
||||||
|
but returns the entire directory in one call:
|
||||||
|
.P1
|
||||||
|
n = dirreadall(fd, &d)
|
||||||
|
for(i=0; i<n; i++)
|
||||||
|
use(&d[i]);
|
||||||
|
free(d);
|
||||||
|
.P2
|
||||||
|
If your program insists on using the underlying
|
||||||
|
.CW stat
|
||||||
|
system call or its relatives, or wants to operate directly on the
|
||||||
|
machine-independent format returned by
|
||||||
|
.CW stat
|
||||||
|
or
|
||||||
|
.CW read ,
|
||||||
|
it will need to be modified.
|
||||||
|
Such programs are rare enough that we'll not discuss them here beyond referring to
|
||||||
|
the man page
|
||||||
|
.I stat (2)
|
||||||
|
for details.
|
||||||
|
Be aware, though, that it used to be possible to regard the buffer returned by
|
||||||
|
.CW stat
|
||||||
|
as a byte array that began with the zero-terminated
|
||||||
|
name of the file; this is no longer true.
|
||||||
|
With very rare exceptions, programs that call
|
||||||
|
.CW stat
|
||||||
|
would be better recast to use the
|
||||||
|
.CW dir
|
||||||
|
routines or, if their goal is just to test the existence of a file,
|
||||||
|
.CW access .
|
||||||
|
.PP
|
||||||
|
Similar changes have affected the
|
||||||
|
.CW wait
|
||||||
|
system call. In fact,
|
||||||
|
.CW wait
|
||||||
|
is no longer a system call but a library routine that calls the new
|
||||||
|
.CW await
|
||||||
|
system call and returns a newly allocated machine-dependent
|
||||||
|
.CW Waitmsg
|
||||||
|
structure:
|
||||||
|
.P1
|
||||||
|
Waitmsg *w;
|
||||||
|
|
||||||
|
w = wait();
|
||||||
|
if(w == nil)
|
||||||
|
error("wait: %r");
|
||||||
|
print("pid is %d; exit string %s\en", w->pid, w->msg);
|
||||||
|
free(w);
|
||||||
|
.P2
|
||||||
|
The exit string
|
||||||
|
.CW w->msg
|
||||||
|
may be empty but it will never be a nil pointer.
|
||||||
|
Again, don't forget to free the structure returned by
|
||||||
|
.CW wait .
|
||||||
|
If all you need is the pid, you can call
|
||||||
|
.CW waitpid ,
|
||||||
|
which reports just the pid and doesn't return an allocated structure:
|
||||||
|
.P1
|
||||||
|
int pid;
|
||||||
|
|
||||||
|
pid = waitpid();
|
||||||
|
if(pid < 0)
|
||||||
|
error("wait: %r");
|
||||||
|
print("pid is %d\en", pid);
|
||||||
|
.P2
|
||||||
|
.SH
|
||||||
|
Quoted strings and tokenize
|
||||||
|
.PP
|
||||||
|
.CW Wait
|
||||||
|
gives us a good opportunity to describe how the system copes with all this
|
||||||
|
free-format data.
|
||||||
|
Consider the text returned by the
|
||||||
|
.CW await
|
||||||
|
system call, which includes a set of integers (pids and times) and a string (the exit status).
|
||||||
|
This information is formatted free-form; here is the statement in the kernel that
|
||||||
|
generates the message:
|
||||||
|
.P1
|
||||||
|
n = snprint(a, n, "%d %lud %lud %lud %q",
|
||||||
|
wq->w.pid,
|
||||||
|
wq->w.time[TUser], wq->w.time[TSys], wq->w.time[TReal],
|
||||||
|
wq->w.msg);
|
||||||
|
.P2
|
||||||
|
Note the use of
|
||||||
|
.CW %q
|
||||||
|
to produce a quoted-string representation of the exit status.
|
||||||
|
The
|
||||||
|
.CW %q
|
||||||
|
format is like %s but will wrap
|
||||||
|
.CW rc -style
|
||||||
|
single quotes around the string if it contains white space or is otherwise ambiguous.
|
||||||
|
The library routine
|
||||||
|
.CW tokenize
|
||||||
|
can be used to parse data formatted this way: it splits white-space-separated
|
||||||
|
fields but understands the
|
||||||
|
.CW %q
|
||||||
|
quoting conventions.
|
||||||
|
Here is how the
|
||||||
|
.CW wait
|
||||||
|
library routine builds its
|
||||||
|
.CW Waitmsg
|
||||||
|
from the data returned by
|
||||||
|
.CW await :
|
||||||
|
.P1
|
||||||
|
Waitmsg*
|
||||||
|
wait(void)
|
||||||
|
{
|
||||||
|
int n, l;
|
||||||
|
char buf[512], *fld[5];
|
||||||
|
Waitmsg *w;
|
||||||
|
|
||||||
|
n = await(buf, sizeof buf-1);
|
||||||
|
if(n < 0)
|
||||||
|
return nil;
|
||||||
|
buf[n] = '\0';
|
||||||
|
if(tokenize(buf, fld, nelem(fld)) != nelem(fld)){
|
||||||
|
werrstr("couldn't parse wait message");
|
||||||
|
return nil;
|
||||||
|
}
|
||||||
|
l = strlen(fld[4])+1;
|
||||||
|
w = malloc(sizeof(Waitmsg)+l);
|
||||||
|
if(w == nil)
|
||||||
|
return nil;
|
||||||
|
w->pid = atoi(fld[0]);
|
||||||
|
w->time[0] = atoi(fld[1]);
|
||||||
|
w->time[1] = atoi(fld[2]);
|
||||||
|
w->time[2] = atoi(fld[3]);
|
||||||
|
w->msg = (char*)&w[1];
|
||||||
|
memmove(w->msg, fld[4], l);
|
||||||
|
return w;
|
||||||
|
}
|
||||||
|
.P2
|
||||||
|
.PP
|
||||||
|
This style of quoted-string and
|
||||||
|
.CW tokenize
|
||||||
|
is used all through the system now.
|
||||||
|
In particular, devices now
|
||||||
|
.CW tokenize
|
||||||
|
the messages written to their
|
||||||
|
.CW ctl
|
||||||
|
files, which means that you can send messages that contain white space, by quoting them,
|
||||||
|
and that you no longer need to worry about whether or not the device accepts a newline.
|
||||||
|
In other words, you can say
|
||||||
|
.P1
|
||||||
|
echo message > /dev/xx/ctl
|
||||||
|
.P2
|
||||||
|
instead of
|
||||||
|
.CW echo
|
||||||
|
.CW -n
|
||||||
|
because
|
||||||
|
.CW tokenize
|
||||||
|
treats the newline character as white space and discards it.
|
||||||
|
.PP
|
||||||
|
While we're on the subject of quotes and strings, note that the implementation of
|
||||||
|
.CW await
|
||||||
|
used
|
||||||
|
.CW snprint
|
||||||
|
rather than
|
||||||
|
.CW sprint .
|
||||||
|
We now deprecate
|
||||||
|
.CW sprint
|
||||||
|
because it has no protection against buffer overflow.
|
||||||
|
We prefer
|
||||||
|
.CW snprint
|
||||||
|
or
|
||||||
|
.CW seprint ,
|
||||||
|
to constrain the output.
|
||||||
|
The
|
||||||
|
.CW %q
|
||||||
|
format is cleverer than most in this regard:
|
||||||
|
if the string is too long to be represented in full,
|
||||||
|
.CW %q
|
||||||
|
is smart enough to produce a truncated but correctly quoted
|
||||||
|
string within the available space.
|
||||||
|
.SH
|
||||||
|
Mount
|
||||||
|
.PP
|
||||||
|
Although strings in 9P are now variable-length and not zero-terminated,
|
||||||
|
this has little direct effect in most of the system interfaces.
|
||||||
|
File and user names are still zero-terminated strings as always;
|
||||||
|
the kernel does the work of translating them as necessary for
|
||||||
|
transport.
|
||||||
|
And of course, they are now free to be as long as you might want;
|
||||||
|
the only hard limit is that their length must be represented in 16 bits.
|
||||||
|
.PP
|
||||||
|
One example where this matters is that the file system specification in the
|
||||||
|
.CW mount
|
||||||
|
system call can now be much longer.
|
||||||
|
Programs like
|
||||||
|
.CW rio
|
||||||
|
that used the specification string in creative ways were limited by the
|
||||||
|
.CW NAMELEN
|
||||||
|
restriction; now they can use the string more freely.
|
||||||
|
.CW Rio
|
||||||
|
now accepts a simple but less cryptic specification language for the window
|
||||||
|
to be created by the
|
||||||
|
.CW mount
|
||||||
|
call, e.g.:
|
||||||
|
.P1
|
||||||
|
% mount $wsys /mnt/wsys 'new -dx 250 -dy 250 -pid 1234'
|
||||||
|
.P2
|
||||||
|
In the old system, this sort of control was impossible through the
|
||||||
|
.CW mount
|
||||||
|
interface.
|
||||||
|
.PP
|
||||||
|
While we're on the subject of
|
||||||
|
.CW mount ,
|
||||||
|
note that with the new security architecture
|
||||||
|
(see
|
||||||
|
.I factotum (4)),
|
||||||
|
9P has moved its authentication outside the protocol proper.
|
||||||
|
(For a full description of this change to 9P, see
|
||||||
|
.I fauth (2),
|
||||||
|
.I attach (5),
|
||||||
|
and the paper
|
||||||
|
.I "Security in Plan 9\f1.)
|
||||||
|
The most explicit effect of this change is that
|
||||||
|
.CW mount
|
||||||
|
now takes another argument,
|
||||||
|
.CW afd ,
|
||||||
|
a file descriptor for the
|
||||||
|
authentication file through which the authentication will be made.
|
||||||
|
For most user-level file servers, which do not require authentication, it is
|
||||||
|
sufficient to provide
|
||||||
|
.CW -1
|
||||||
|
as the value of
|
||||||
|
.CW afd:
|
||||||
|
.P1
|
||||||
|
if(mount(fd, -1, "/mnt/wsys", MREPL,
|
||||||
|
"new -dx 250 -dy 250 -pid 1234") < 0)
|
||||||
|
error("mount failed: %r");
|
||||||
|
.P2
|
||||||
|
To connect to servers that require authentication, use the new
|
||||||
|
.CW fauth
|
||||||
|
system call or the reimplemented
|
||||||
|
.CW amount
|
||||||
|
(authenticated mount) library call.
|
||||||
|
In fact, since
|
||||||
|
.CW amount
|
||||||
|
handles both authenticating and non-authenticating servers, it is often
|
||||||
|
easiest just to replace calls to
|
||||||
|
.CW mount
|
||||||
|
by calls to
|
||||||
|
.CW amount ;
|
||||||
|
see
|
||||||
|
.I auth (2)
|
||||||
|
for details.
|
||||||
|
.SH
|
||||||
|
Print
|
||||||
|
.PP
|
||||||
|
The C library has been heavily reworked in places.
|
||||||
|
Besides the changes mentioned above, it
|
||||||
|
now has a much more complete set of routines for handling
|
||||||
|
.CW Rune
|
||||||
|
strings (that is, zero-terminated arrays of 16-bit character values).
|
||||||
|
The most sweeping changes, however, are in the way formatted I/O is performed.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.CW print
|
||||||
|
routine and all its relatives have been reimplemented to offer a number
|
||||||
|
of improvements:
|
||||||
|
.IP (1)
|
||||||
|
Better buffer management, including the provision of an internal flush
|
||||||
|
routine, makes it unnecessary to provide large buffers.
|
||||||
|
For example,
|
||||||
|
.CW print
|
||||||
|
uses a much smaller buffer now (reducing stack load) while simultaneously
|
||||||
|
removing the need to truncate the output string if it doesn't fit in the buffer.
|
||||||
|
.IP (2)
|
||||||
|
Global variables have been eliminated so no locking is necessary.
|
||||||
|
.IP (3)
|
||||||
|
The combination of (1) and (2) means that the standard implementation of
|
||||||
|
.CW print
|
||||||
|
now works fine in threaded programs, and
|
||||||
|
.CW threadprint
|
||||||
|
is gone.
|
||||||
|
.IP (4)
|
||||||
|
The new routine
|
||||||
|
.CW smprint
|
||||||
|
prints into, and returns, storage allocated on demand by
|
||||||
|
.CW malloc .
|
||||||
|
.IP (5)
|
||||||
|
It is now possible to print into a
|
||||||
|
.CW Rune
|
||||||
|
string; for instance,
|
||||||
|
.CW runesmprint
|
||||||
|
is the
|
||||||
|
.CW Rune
|
||||||
|
analog of
|
||||||
|
.CW smprint .
|
||||||
|
.IP (6)
|
||||||
|
There is improved support for custom
|
||||||
|
print verbs and custom output routines such as error handlers.
|
||||||
|
The routine
|
||||||
|
.CW doprint
|
||||||
|
is gone, but
|
||||||
|
.CW vseprint
|
||||||
|
can always be used instead.
|
||||||
|
However, the new routines
|
||||||
|
.CW fmtfdinit ,
|
||||||
|
.CW fmtstrinit ,
|
||||||
|
.CW fmtprint ,
|
||||||
|
and friends
|
||||||
|
are often a better replacement.
|
||||||
|
The details are too long for exposition here;
|
||||||
|
.I fmtinstall (2)
|
||||||
|
explains the new interface and provides examples.
|
||||||
|
.IP (7)
|
||||||
|
Two new format flags, space and comma, close somewhat the gap between
|
||||||
|
Plan 9 and ANSI C.
|
||||||
|
.PP
|
||||||
|
Despite these changes, most programs will be unaffected;
|
||||||
|
.CW print
|
||||||
|
is still
|
||||||
|
.CW print .
|
||||||
|
Don't forget, though, that
|
||||||
|
you should eliminate calls to
|
||||||
|
.CW sprint
|
||||||
|
and use the
|
||||||
|
.CW %q
|
||||||
|
format when appropriate.
|
||||||
|
.SH
|
||||||
|
Binary compatibility
|
||||||
|
.PP
|
||||||
|
The discussion so far has been about changes at the source level.
|
||||||
|
Existing binaries will probably run without change in the new
|
||||||
|
environment, since the kernel provides backward-compatible
|
||||||
|
system calls for
|
||||||
|
.CW errstr ,
|
||||||
|
.CW stat ,
|
||||||
|
.CW wait ,
|
||||||
|
etc.
|
||||||
|
The only exceptions are programs that do either a
|
||||||
|
.CW mount
|
||||||
|
system call, because of the security changes and because
|
||||||
|
the file descriptor in
|
||||||
|
.CW mount
|
||||||
|
must point to a new 9P connection; or a
|
||||||
|
.CW read
|
||||||
|
system call on a directory, since the returned data will
|
||||||
|
be in the new format.
|
||||||
|
A moment's reflection will discover that this means old
|
||||||
|
user-level file servers will need to be fixed to run on the new system.
|
||||||
|
.SH
|
||||||
|
File servers
|
||||||
|
.PP
|
||||||
|
A full description of what user-level servers must do to provide service with
|
||||||
|
the new 9P is beyond the scope of this paper.
|
||||||
|
Your best source of information is section 5 of the manual,
|
||||||
|
combined with study of a few examples.
|
||||||
|
.CW /sys/src/cmd/ramfs.c
|
||||||
|
is a simple example; it has a counterpart
|
||||||
|
.CW /sys/src/lib9p/ramfs.c
|
||||||
|
that implements the same service using the new
|
||||||
|
.I 9p (2)
|
||||||
|
library.
|
||||||
|
.PP
|
||||||
|
That said, it's worth summarizing what to watch for when converting a file server.
|
||||||
|
The
|
||||||
|
.CW session
|
||||||
|
message is gone, and there is a now a
|
||||||
|
.CW version
|
||||||
|
message that is exchanged at the start of a connection to establish
|
||||||
|
the version of the protocol to use (there's only one at the moment, identified by
|
||||||
|
the string
|
||||||
|
.CW 9P2000 )
|
||||||
|
and what the maximum message size will be.
|
||||||
|
This negotiation makes it easier to handle 9P encapsulation, such as with
|
||||||
|
.CW exportfs ,
|
||||||
|
and also permits larger message sizes when appropriate.
|
||||||
|
.PP
|
||||||
|
If your server wants to authenticate, it will need to implement an authentication file
|
||||||
|
and implement the
|
||||||
|
.CW auth
|
||||||
|
message; otherwise it should return a helpful error string to the
|
||||||
|
.CW Tauth
|
||||||
|
request to signal that authentication is not required.
|
||||||
|
.PP
|
||||||
|
The handling of
|
||||||
|
.CW stat
|
||||||
|
and directory reads will require some changes but they should not be fundamental.
|
||||||
|
Be aware that seeking on directories is forbidden, so it is fine if you disregard the
|
||||||
|
file offset when implementing directory reads; this makes it a little easier to handle
|
||||||
|
the variable-length entries.
|
||||||
|
You should still never return a partial directory entry; if the I/O count is too small
|
||||||
|
to return even one entry, you should return two bytes containing the byte count
|
||||||
|
required to represent the next entry in the directory.
|
||||||
|
User code can use this value to formulate a retry if it desires.
|
||||||
|
See the
|
||||||
|
DIAGNOSTICS section of
|
||||||
|
.I stat (2)
|
||||||
|
for a description of this process.
|
||||||
|
.PP
|
||||||
|
The trickiest part of updating a file server is that the
|
||||||
|
.CW clone
|
||||||
|
and
|
||||||
|
.CW walk
|
||||||
|
messages have been merged into a single message, a sort of `clone-multiwalk'.
|
||||||
|
The new message, still called
|
||||||
|
.CW walk ,
|
||||||
|
proposes a sequence of file name elements to be evaluated using a possibly
|
||||||
|
cloned fid.
|
||||||
|
The return message contains the qids of the files reached by
|
||||||
|
walking to the sequential elements.
|
||||||
|
If all the elements can be walked, the fid will be cloned if requested.
|
||||||
|
If a non-zero number of elements are requested, but none
|
||||||
|
can be walked, an error should be returned.
|
||||||
|
If only some can be walked, the fid is not cloned, the original fid is left
|
||||||
|
where it was, and the returned
|
||||||
|
.CW Rwalk
|
||||||
|
message should contain the partial list of successfully reached qids.
|
||||||
|
See
|
||||||
|
.I walk (5)
|
||||||
|
for a full description.
|
6493
sys/doc/prog4.ps
Normal file
6493
sys/doc/prog4.ps
Normal file
File diff suppressed because it is too large
Load diff
152
sys/doc/ps
Normal file
152
sys/doc/ps
Normal file
|
@ -0,0 +1,152 @@
|
||||||
|
8½/8½.ms
|
||||||
|
8½/8½.ps
|
||||||
|
8½/8½.trout
|
||||||
|
8½/fig1.ps
|
||||||
|
8½/mkfile
|
||||||
|
README.ms
|
||||||
|
README.ps
|
||||||
|
acid.ms
|
||||||
|
acid.ps
|
||||||
|
acid.troff
|
||||||
|
acidpaper.ms
|
||||||
|
acidpaper.ps
|
||||||
|
acme/acme.fig1
|
||||||
|
acme/acme.fig2
|
||||||
|
acme/acme.ms
|
||||||
|
acme/acme.ps
|
||||||
|
acme/mkfile
|
||||||
|
alef/alef.ps
|
||||||
|
alef/man
|
||||||
|
alef/mkfile
|
||||||
|
alef/ref.ms
|
||||||
|
alef/ug.ms
|
||||||
|
alef/ug.ps
|
||||||
|
ape.ms
|
||||||
|
ape.ps
|
||||||
|
asm.ms
|
||||||
|
asm.ps
|
||||||
|
cda/cda.i
|
||||||
|
cda/cda.ms
|
||||||
|
cda/fig1.g
|
||||||
|
cda/fig1.pic
|
||||||
|
cda/fig2.g
|
||||||
|
cda/fig2.pic
|
||||||
|
cda/fig3.g
|
||||||
|
cda/fig3.pic
|
||||||
|
cda/io.pins
|
||||||
|
cda/mkfile
|
||||||
|
cda/my.pins
|
||||||
|
cda/opm.g
|
||||||
|
cda/opm.pic
|
||||||
|
cda/opmcall.g
|
||||||
|
cda/opmcall.pic
|
||||||
|
cda/place.err
|
||||||
|
cda/schroff.board
|
||||||
|
cda/schroff.board.l
|
||||||
|
cda/toy
|
||||||
|
cda/toy.draw.r
|
||||||
|
cda/toy.fx
|
||||||
|
cda/toy.fx.l
|
||||||
|
cda/toy.g
|
||||||
|
cda/toy.pic
|
||||||
|
cda/toy.pins
|
||||||
|
cda/toy.pins.l
|
||||||
|
cda/toy.pkg
|
||||||
|
cda/toy.pos
|
||||||
|
cda/toy.w
|
||||||
|
cda/toy.w.l
|
||||||
|
cda/toy.wx
|
||||||
|
cda/toy.wx.l
|
||||||
|
comp.ms
|
||||||
|
comp.ps
|
||||||
|
compiler/compiler.ps
|
||||||
|
compiler/mkfile
|
||||||
|
compiler/p0
|
||||||
|
compiler/p1
|
||||||
|
compiler/p2
|
||||||
|
compiler/p3
|
||||||
|
compiler/p4
|
||||||
|
compiler/p5
|
||||||
|
compiler/p6
|
||||||
|
compiler/p7
|
||||||
|
compiler/p8
|
||||||
|
compiler/pr
|
||||||
|
contrib/nofileserver.ms
|
||||||
|
contrib/sunhints.ms
|
||||||
|
cstr158/1
|
||||||
|
cstr158/2
|
||||||
|
cstr158/3
|
||||||
|
cstr158/4
|
||||||
|
cstr158/5
|
||||||
|
cstr158/6
|
||||||
|
cstr158/7
|
||||||
|
cstr158/8
|
||||||
|
cstr158/README
|
||||||
|
fonts
|
||||||
|
gfx.ms
|
||||||
|
gfx.ps
|
||||||
|
install.ms
|
||||||
|
install.ps
|
||||||
|
libmach.ms
|
||||||
|
libmach.ps
|
||||||
|
mkfile
|
||||||
|
mkfiles.ms
|
||||||
|
mkfiles.ps
|
||||||
|
names.ms
|
||||||
|
names.ps
|
||||||
|
net/mkfile
|
||||||
|
net/net.ms
|
||||||
|
net/net.ps
|
||||||
|
net/tree
|
||||||
|
net/tree.pout
|
||||||
|
pcconfig.ms
|
||||||
|
pcconfig.ps
|
||||||
|
plan9/9.ms
|
||||||
|
plan9/9.ps
|
||||||
|
plan9/mkfile
|
||||||
|
plan9/refs
|
||||||
|
plan9/refs.ig
|
||||||
|
plan9/topo.pic
|
||||||
|
plan9/topo.pout
|
||||||
|
port.ms
|
||||||
|
port.ps
|
||||||
|
ps
|
||||||
|
rc.ms
|
||||||
|
rc.ps
|
||||||
|
release.ms
|
||||||
|
release.ps
|
||||||
|
release2.ms
|
||||||
|
release2.ps
|
||||||
|
sam/fig1.bm
|
||||||
|
sam/fig1.ps
|
||||||
|
sam/fig2.bm
|
||||||
|
sam/fig2.ps
|
||||||
|
sam/fig3.bm
|
||||||
|
sam/fig3.ps
|
||||||
|
sam/fig4.bm
|
||||||
|
sam/fig4.ps
|
||||||
|
sam/fig5.pic
|
||||||
|
sam/fig6.pic
|
||||||
|
sam/fig7.pic
|
||||||
|
sam/mkfile
|
||||||
|
sam/refs
|
||||||
|
sam/sam.ms
|
||||||
|
sam/sam.ps
|
||||||
|
sam/sam.tut
|
||||||
|
sleep.ms
|
||||||
|
sleep.ps
|
||||||
|
spin.ms
|
||||||
|
spin.ps
|
||||||
|
troff.ms
|
||||||
|
troff.ps
|
||||||
|
troff.trout
|
||||||
|
tromsø/mkfile
|
||||||
|
tromsø/topo.pic
|
||||||
|
tromsø/topo.pout
|
||||||
|
tromsø/tromsø.ms
|
||||||
|
tromsø/tromsø.ps
|
||||||
|
utf.ms
|
||||||
|
utf.ps
|
||||||
|
worm.ms
|
||||||
|
worm.ps
|
||||||
|
x
|
1589
sys/doc/rc.ms
Normal file
1589
sys/doc/rc.ms
Normal file
File diff suppressed because it is too large
Load diff
9577
sys/doc/rc.ps
Normal file
9577
sys/doc/rc.ps
Normal file
File diff suppressed because it is too large
Load diff
193
sys/doc/release3.ms
Normal file
193
sys/doc/release3.ms
Normal file
|
@ -0,0 +1,193 @@
|
||||||
|
.HTML "Plan 9 — Third Edition Release Notes
|
||||||
|
.TL
|
||||||
|
Plan 9 From Bell Labs
|
||||||
|
.br
|
||||||
|
Third Release Notes
|
||||||
|
.br
|
||||||
|
June 7, 2000
|
||||||
|
.LP
|
||||||
|
.sp -.4i
|
||||||
|
.nf
|
||||||
|
.ce 1000
|
||||||
|
Copyright © 2000 Lucent Technologies Inc.
|
||||||
|
All Rights Reserved
|
||||||
|
.sp .2i
|
||||||
|
.fi
|
||||||
|
.LP
|
||||||
|
The third release of the Plan 9 operating system from Bell Labs
|
||||||
|
is something of a snapshot of the current system.
|
||||||
|
This differs from the previous, 1995 release,
|
||||||
|
which was a more coordinated, well-defined release of an already-out-of-date
|
||||||
|
system.
|
||||||
|
Also, the previous releases were distributed on fixed media, while this release
|
||||||
|
is being done over the web.
|
||||||
|
The other major difference is that the third release is licensed under
|
||||||
|
an open source agreement, which we hope will encourage people
|
||||||
|
to experiment with it.
|
||||||
|
.LP
|
||||||
|
Beyond that, there are innumerable little changes throughout the code.
|
||||||
|
Although superficially it is the same environment, there is hardly an aspect
|
||||||
|
of the system that has not been redesigned, rewritten, or replaced.
|
||||||
|
The following is an incomplete list of changes.
|
||||||
|
.de Xx
|
||||||
|
.LP
|
||||||
|
\(bu
|
||||||
|
..
|
||||||
|
.Xx
|
||||||
|
The list of architectures has changed; more compilers are included
|
||||||
|
and the list of kernels has changed.
|
||||||
|
There is solid support for Intel x86 multiprocessors.
|
||||||
|
Also, although the sources are available for
|
||||||
|
other architectures, the binaries and libraries are built only for the
|
||||||
|
Intel x86 architectures.
|
||||||
|
Kernel source is available for x86, Mips, DEC Alpha, and Power PC architectures.
|
||||||
|
Compilers also exist for AMD 29000, Motorola MC68000 and MC68020,
|
||||||
|
Intel i960, and SPARC.
|
||||||
|
(Unlike the the last release, no SPARC kernel exists for the current system.)
|
||||||
|
The compilers and related tools
|
||||||
|
have been made easier to port to Unix and Windows.
|
||||||
|
.Xx
|
||||||
|
The kernel now has a file cache to improve I/O performance.
|
||||||
|
Other kernel changes include the replacement of the streams interface
|
||||||
|
with a simpler, faster, but less flexible I/O queue structure.
|
||||||
|
The x86 kernels support PCI and PCMCIA devices.
|
||||||
|
.Xx
|
||||||
|
Network management has been simplified and generalized.
|
||||||
|
DNS supports a resolver mode and the DNS server is now solid.
|
||||||
|
DHCP is supported both at the client and server ends.
|
||||||
|
The system can handle multiple IP stacks, which are also
|
||||||
|
no longer Ethernet-specific.
|
||||||
|
.Xx
|
||||||
|
The organization of disks in the kernel has been unified, providing
|
||||||
|
a consistent interface to all disks and controllers: SCSI or ATAPI,
|
||||||
|
magnetic or CD-ROM.
|
||||||
|
.Xx
|
||||||
|
File offsets, such as in the
|
||||||
|
.CW seek
|
||||||
|
system call, are now 64-bit values.
|
||||||
|
The 1995 release defined the type
|
||||||
|
.CW Length
|
||||||
|
for the x86 as
|
||||||
|
.P1
|
||||||
|
typedef union
|
||||||
|
{
|
||||||
|
char clength[8];
|
||||||
|
vlong vlength;
|
||||||
|
struct
|
||||||
|
{
|
||||||
|
long hlength;
|
||||||
|
long length;
|
||||||
|
};
|
||||||
|
} Length;
|
||||||
|
.P2
|
||||||
|
which is the wrong byte order.
|
||||||
|
Now, for all architectures,
|
||||||
|
.CW Length
|
||||||
|
is well handled by a
|
||||||
|
.CW vlong
|
||||||
|
.CW long "" (
|
||||||
|
.CW long )
|
||||||
|
type, although for compatibility it's still held in a union:
|
||||||
|
.P1
|
||||||
|
typedef union
|
||||||
|
{
|
||||||
|
vlong length;
|
||||||
|
} Length;
|
||||||
|
.P2
|
||||||
|
.Xx
|
||||||
|
The kernel now maintains a file name associated with each open file or
|
||||||
|
directory, which can be cheaply recovered by the
|
||||||
|
.CW fd2path
|
||||||
|
system call.
|
||||||
|
Plan 9 now does a much better job with
|
||||||
|
.CW ..
|
||||||
|
(dot-dot).
|
||||||
|
On a related note, a description of a process's name space may be
|
||||||
|
read with the
|
||||||
|
.CW ns
|
||||||
|
file in
|
||||||
|
.CW /proc ,
|
||||||
|
or by the
|
||||||
|
.CW ns
|
||||||
|
command.
|
||||||
|
.Xx
|
||||||
|
The security model is the same, although
|
||||||
|
the key format has changed.
|
||||||
|
If you have an old key file, use
|
||||||
|
.CW auth/convkeys2
|
||||||
|
(see
|
||||||
|
.I auth (8))
|
||||||
|
to update it.
|
||||||
|
There are new libraries for mulitprecision arithmetic and security.
|
||||||
|
.Xx
|
||||||
|
The graphics model is very different.
|
||||||
|
It is based on the Porter-Duff compositing algebra rather than
|
||||||
|
.CW bitblt ,
|
||||||
|
and the system supports everything from bitmaps to true-color displays.
|
||||||
|
Some of the graphics drivers exploit hardware acceleration.
|
||||||
|
.Xx
|
||||||
|
Coupled to the graphics changes, the image and font file formats have
|
||||||
|
changed.
|
||||||
|
They can represent a wider range of pixel formats and compress the data.
|
||||||
|
Also the white/black sense of value is reversed (zero is now black; pixels
|
||||||
|
represent light, not ink).
|
||||||
|
Most of the tools can handle the old format, but they all write the new format only.
|
||||||
|
.Xx
|
||||||
|
The user interface now incorporates plumbing, a language-driven
|
||||||
|
way for applications to communicate. See
|
||||||
|
.I plumb (6)
|
||||||
|
for information.
|
||||||
|
.Xx
|
||||||
|
Building on plumbing and a program that presents the mail box as a file
|
||||||
|
system, Plan 9 now has convenient support for MIME mail messages.
|
||||||
|
.Xx
|
||||||
|
.CW 8½
|
||||||
|
has been replaced by
|
||||||
|
.CW rio ,
|
||||||
|
which has a similar appearance but a different architecture.
|
||||||
|
Although still a file server, it is much more efficient: the kernel driver
|
||||||
|
multiplexes graphics output so
|
||||||
|
.CW rio
|
||||||
|
is not in the display path.
|
||||||
|
.CW Rio
|
||||||
|
handles input and window control only.
|
||||||
|
.Xx
|
||||||
|
PC booting is more sophisticated. PCs can now boot Plan 9 directly from
|
||||||
|
the disk without running DOS.
|
||||||
|
.Xx
|
||||||
|
Alef is gone.
|
||||||
|
It was deemed too difficult to maintain two sets of compilers and libraries
|
||||||
|
for all architectures.
|
||||||
|
Alef programs were translated into C, with the help of a new thread library
|
||||||
|
that preserves much of Alef's functionality, but none of its syntax.
|
||||||
|
.Xx
|
||||||
|
Mothra is gone. There is no web browser included in this release,
|
||||||
|
but something may well appear before long.
|
||||||
|
.Xx
|
||||||
|
The
|
||||||
|
.CW fb
|
||||||
|
(frame buffer) suite is gone. Most of its tools are
|
||||||
|
supplanted by new ones, such as
|
||||||
|
.CW page ,
|
||||||
|
.CW jpg ,
|
||||||
|
and
|
||||||
|
.CW togif .
|
||||||
|
.Xx
|
||||||
|
Also gone from this release are the games and support for
|
||||||
|
international input
|
||||||
|
.CW ktrans "" (
|
||||||
|
etc.).
|
||||||
|
Both may return.
|
||||||
|
.Xx
|
||||||
|
New things include an implementation of
|
||||||
|
.CW ssh ,
|
||||||
|
an IMAP4 server,
|
||||||
|
and some spam-filtering software (see
|
||||||
|
.I scanmail (8)).
|
||||||
|
.LP
|
||||||
|
There's lots more.
|
||||||
|
If you have problems, mail
|
||||||
|
.CW 9trouble@plan9.bell-labs.com .
|
||||||
|
Please don't mail us individually.
|
||||||
|
.LP
|
||||||
|
Good Luck!
|
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue