%!PS-Adobe-2.0
%%Title: poe_notes.mss
%%DocumentFonts: (atend)
%%Creator: Mary Thompson and Scribe 7(1700)
%%CreationDate: 14 April 1994 13:36
%%Pages: (atend)
%%EndComments
% PostScript Prelude for Scribe.
/BS {/SV save def 0.0 792.0 translate .01 -.01 scale} bind def
/ES {showpage SV restore} bind def
/SC {setrgbcolor} bind def
/FMTX matrix def
/RDF {WFT SLT 0.0 eq
{SSZ 0.0 0.0 SSZ neg 0.0 0.0 FMTX astore}
{SSZ 0.0 SLT neg sin SLT cos div SSZ mul SSZ neg 0.0 0.0 FMTX astore}
ifelse makefont setfont} bind def
/SLT 0.0 def
/SI { /SLT exch cvr def RDF} bind def
/WFT /Courier findfont def
/SF { /WFT exch findfont def RDF} bind def
/SSZ 1000.0 def
/SS { /SSZ exch 100.0 mul def RDF} bind def
/AF { /WFT exch findfont def /SSZ exch 100.0 mul def RDF} bind def
/MT /moveto load def
/XM {currentpoint exch pop moveto} bind def
/UL {gsave newpath moveto dup 2.0 div 0.0 exch rmoveto
setlinewidth 0.0 rlineto stroke grestore} bind def
/LH {gsave newpath moveto setlinewidth
0.0 rlineto
gsave stroke grestore} bind def
/LV {gsave newpath moveto setlinewidth
0.0 exch rlineto
gsave stroke grestore} bind def
/BX {gsave newpath moveto setlinewidth
exch
dup 0.0 rlineto
exch 0.0 exch neg rlineto
neg 0.0 rlineto
closepath
gsave stroke grestore} bind def
/BX1 {grestore} bind def
/BX2 {setlinewidth 1 setgray stroke grestore} bind def
/PB {/PV save def newpath translate
100.0 -100.0 scale pop /showpage {} def} bind def
/PE {PV restore} bind def
/GB {/PV save def newpath translate rotate
div dup scale 100.0 -100.0 scale
/showpage {} def
/letter {} def
/lettersmall {} def
/note {} def
} bind def
/GE {PV restore} bind def
/FB {dict dup /FontMapDict exch def begin} bind def
/FM {cvn exch cvn exch def} bind def
/FE {end /original-findfont /findfont load def /findfont
{dup FontMapDict exch known{FontMapDict exch get} if
original-findfont} def} bind def
/BC {gsave moveto dup 0 exch rlineto exch 0 rlineto neg 0 exch rlineto closepath clip} bind def
/EC /grestore load def
/SH /show load def
/MX {exch show 0.0 rmoveto} bind def
/W {0 32 4 -1 roll widthshow} bind def
/WX {0 32 5 -1 roll widthshow 0.0 rmoveto} bind def
/RC {100.0 -100.0 scale
612.0 0.0 translate
-90.0 rotate
.01 -.01 scale} bind def
/URC {100.0 -100.0 scale
90.0 rotate
-612.0 0.0 translate
.01 -.01 scale} bind def
/RCC {100.0 -100.0 scale
0.0 -792.0 translate 90.0 rotate
.01 -.01 scale} bind def
/URCC {100.0 -100.0 scale
-90.0 rotate 0.0 792.0 translate
.01 -.01 scale} bind def
%%EndProlog
%%Page: 0 1
BS
0 SI
15 /Helvetica-Bold AF
17301 8294 MT
(A Brief Description of the POE server)SH
10 /Helvetica AF
26988 10647 MT
(Mary Thompson)SH
27654 12330 MT
(14 April 1994)SH
12 /Helvetica-Bold AF
7200 16085 MT
(1. Overview)SH
10 /Helvetica AF
8312 17511 MT
(POE is a small multi-threaded server that runs on top)
89 W( of Mach micro-kernel. It provides support for a)88 W
7200 18937 MT
(simple user)
103 W( environment and allows bootstrapping of programs designed to be run on the Mach micro-)104 W
7200 20363 MT
(kernel. It uses the existing transparent emulation library taken from the)
210 W( single-server environment to)209 W
7200 21789 MT
(provide binary compatible support for Unix system calls. It provides the Unix fork and)
14 W( exec semantics and)15 W
7200 23215 MT
(thus supports the execution of some Unix binaries, including /bin/csh and and /bin/sh.)
14 W( Poe is not intended)13 W
7200 24641 MT
(to support a complete Unix kernel environment, but only to give you enough tools to)
243 W( start building)244 W
7200 26067 MT
(traditional "user level applications".)SH
8312 28634 MT
(It has three logical control paths: an external pager for mapped special)
101 W( devices, a external pager for)100 W
7200 30060 MT
(mapped files, and a server loop waiting for requests from user processes. The external pagers)
87 W( service)88 W
7200 31486 MT
(paging requests from the kernel, the)
63 W( user requests are mostly Unix system calls. Each control path has)62 W
7200 32912 MT
(several cthreads implementing it.)SH
12 /Helvetica-Bold AF
7200 34898 MT
(Unix features supported by POE)SH
10 /Symbol AF
9242 36468 MT
(\267)SH
/Helvetica SF
9980 XM
(Reading from a BSD 4.3 file system)SH
/Symbol SF
9242 38283 MT
(\267)SH
/Helvetica SF
9980 XM
(Reading and writing from raw \050character\051 disk devices)SH
/Symbol SF
9242 40098 MT
(\267)SH
/Helvetica SF
9980 XM
(Reading and writing to /dev/console and physical ttys)SH
/Symbol SF
9242 41913 MT
(\267)SH
/Helvetica SF
9980 XM
(Some Unix signal semantics)SH
/Symbol SF
9242 43728 MT
(\267)SH
/Helvetica SF
9980 XM
(Fork and exec)SH
/Symbol SF
9242 45543 MT
(\267)SH
/Helvetica SF
9980 XM
(Pipe and redirection semantics)SH
12 /Helvetica-Bold AF
7200 47529 MT
(Unix features not supported by POE)SH
10 /Symbol AF
9242 49099 MT
(\267)SH
/Helvetica SF
9980 XM
(Sockets - network support)SH
/Symbol SF
9242 50914 MT
(\267)SH
/Helvetica SF
9980 XM
(Writing to disks as block devices or to File Systems.)SH
8312 53481 MT
(As a small multi-threaded)
67 W( pure Mach server which provide some useful functionality, POE could have)68 W
7200 54907 MT
(been an excellent programming example. Unfortunately it was never documented and is almost totally)137 W
7200 56333 MT
(devoid of comments. This document is an attempt to provide some pointers to people trying to figure)
49 W( out)50 W
7200 57759 MT
(how it works. Be warned that these notes were written after reading the code)
47 W( and not by the people who)46 W
7200 59185 MT
(wrote the code, so there could be errors and there are plenty of omissions.)SH
12 /Helvetica-Bold AF
7200 62940 MT
(2. Poe components)SH
11 SS
7200 66622 MT
(2.1. emulator)SH
10 /Helvetica AF
8312 68048 MT
(The emulator subdirectory contains the code for the transparent)
158 W( emulation library. These files were)159 W
7200 69474 MT
(taken from the emulation library of the Unix server and thus provide)
53 W( redirection of all Unix systems calls.)52 W
7200 70900 MT
(The emulation library gets built as a)
11 W( separate piece of code and is loaded by POE with each program that)12 W
ES
%%Page: 1 2
BS
0 SI
10 /Helvetica-Bold AF
30322 4329 MT
(1)SH
/Helvetica SF
7200 7929 MT
(it execs. This library is built as poe_emulator.. Syscall traps are caught)
84 W( by the micro-kernel)83 W
7200 9355 MT
(and redirected to known locations in the user's copy of the emulation library. This code then makes)
85 W( the)86 W
7200 10781 MT
(appropriate remote procedure call to the POE server to service the syscall.)SH
8312 13348 MT
(There are small pieces of machine dependent code in the i386 and mips subdirectories.)SH
8312 15915 MT
(The emulator should be installed as /mach_servers/poe_emulator)SH
/Helvetica-Oblique SF
37602 XM
(and)SH
/Helvetica SF
39548 XM
(/mach_servers/emulator.)SH
11 /Helvetica-Bold AF
7200 19597 MT
(2.2. poe)SH
10 /Helvetica AF
8312 21023 MT
(These are the files that comprise)
157 W( the poe server. They build the file poe.. There are a)156 W
7200 22449 MT
(small number of machine dependent file in the i386 and mips subdirectories.)SH
8312 25016 MT
(The poe server should be installed as /mach_servers/startup.)SH
11 /Helvetica-Bold AF
7200 28698 MT
(2.3. poe_init, boot)SH
10 SS
8312 30124 MT
(poe_init)SH
/Helvetica SF
12451 XM
(is the)
27 W( first program to be called by the POE server, i.e. the equivalent of /etc/init or mach_init.)28 W
7200 31550 MT
(If the boot switch -s was not given, poe_init will run the script)122 W
/Helvetica-Bold SF
35853 XM
(/mach_servers/rc)SH
/Helvetica SF
(. It "exits" by exec'ing)121 W
7200 32976 MT
(/bin/csh. The)
324 W( first)
23 W( argument is its name, the second argument is the boot flags where -s is the only one it)24 W
7200 34402 MT
(uses, and the third argument will be used as its home directory.)SH
8312 36969 MT
(poe_init is)
1 W( built from the file minit.c and can be build either in a stand-alone or second server version. It)SH
7200 38395 MT
(should be installed as /mach_servers/poe_init.)SH
/Helvetica-Bold SF
8312 40962 MT
(boot)SH
/Helvetica SF
10901 XM
(is a program that can be used to bootstrap another server program. It handles the)
145 W( details of)146 W
7200 42388 MT
(making the privileged Mach)
50 W( ports available to another server via the same interface the kernel uses. It is)49 W
7200 43814 MT
(built from boot.c in the poe directory. It forks and the child process exec's the program that was passed)
SH( as)1 W
7200 45240 MT
(the first argument. The parent process waits to handle)
92 W( the request for the privileged ports. Boot can be)91 W
7200 46666 MT
(run on a UX server system)
33 W( and used to start the second server version of poe, or it can be run on poe to)34 W
7200 48092 MT
(start the multi-servers configuration server. The first argument to boot is the name of the file to run.)
9 W( All the)8 W
7200 49518 MT
(rest of the arguments are passed on to that program.)SH
11 /Helvetica-Bold AF
7200 53200 MT
(2.4. poe/include/{mips,i386})SH
10 /Helvetica AF
8312 54626 MT
(These directories just contain Makefiles to)
21 W( cause the .h files in the "machine" subdirectory to be copied)22 W
7200 56052 MT
(to the "poe/export" area for building.)SH
11 /Helvetica-Bold AF
7200 59734 MT
(2.5. conf)SH
10 /Helvetica AF
8312 61160 MT
(This directory)
106 W( contains a few files used by the build process to create a version string to identify the)105 W
7200 62586 MT
(poe server.)SH
12 /Helvetica-Bold AF
7200 66341 MT
(3. Build procedure)SH
10 /Helvetica AF
8312 67767 MT
(This document assumes you have some background knowledge of)
145 W( building and installing the Mach)146 W
7200 69193 MT
(system. The)
340 W( poe Makefiles are set up to use the standard Mach)
31 W( ODE build tools which are used to build)30 W
7200 70619 MT
(the kernel and other Mach collections. Information)
5 W( on how to obtain and use these tools can be found the)6 W
ES
%%Page: 2 3
BS
0 SI
10 /Helvetica-Bold AF
30322 4329 MT
(2)SH
/Helvetica SF
7200 7929 MT
(the Mach FTP area)
1001 W( on mach.cs.cmu.edu in doc/unpublished/mach3_build.{ps,doc}. The)1000 W
7200 9355 MT
(mach3_setup.{ps,doc} document explains how to install the Mach kernel and servers. The)
389 W( tools)390 W
7200 10781 MT
(themselves can be FTP'ed from public/src/buildtools)
67 W( \050sources\051 or public/src/release \050binaries\051 or SUP'ed)66 W
7200 12207 MT
(as either the mach3.buildtools collection \050sources\051 or the mach3.release collections \050binaries\051)SH
8312 14774 MT
(The include files in the mach,)
55 W( device and machine subdirectories should come from the version of the)56 W
7200 16200 MT
(kernel you are using. A normal kernel build will export the necessary files)
1035 W( to)1034 W
7200 17626 MT
(.../export//include/mach. A)
688 W( kernel release pass will put them in /include/mach.)206 W
7200 19052 MT
(You can also get these files as part)
144 W( of the mach3.release collection. The POE build will find them in)143 W
7200 20478 MT
(either place. The TOSTAGE should correspond to the -systembase arg to setvar.csh. For)
231 W( example,)232 W
7200 21904 MT
(/usr/mach or /usr/mach/latest.)SH
8312 24471 MT
(There are no rules in the poe Makefiles to install the)
70 W( things that are built. There are three files which)69 W
7200 25897 MT
(need to be put in a directory of your choosing \050usually /mach_servers\051 on the)
9 W( root partition of the machine)10 W
7200 27323 MT
(you want to boot. Just copy the following files from the object area to .)SH
/Symbol SF
9242 28795 MT
(\267)SH
/Helvetica SF
9980 XM
(