add missing port.ms and port.pdf, both updated

2 files changed, 573 insertions, 0 deletions

diff --git a/doc/port.ms b/doc/port.ms
new file mode 100644
index 00000000..0d11a578
--- /dev/null
+++ b/doc/port.ms
@@ -0,0 +1,573 @@
+.TL
+Inferno Ports: Hosted and Native
+.AU
+Vita Nuova
+27 April 2005
+Revised 22 January 2007
+.PP
+Inferno is a portable environment, encompassing operating system,
+languages, virtual machine and the tools required to build it.
+This section briefly summarises the state of the ports and compilers
+included in this release.
+Directory names are relative to the root of the Inferno release tree,
+unless otherwise specified by the context.
+.PP
+All components are built using the program
+.CW mk ,
+based on `make'-like recipes found in the
+.CW mkfile
+in each source directory throughout the Inferno tree.
+.CW Mk
+is described by the manual page
+.I mk (10.1)
+in Volume 1; a more tutorial discussion, including
+a summary of differences with Unix
+.I make ,
+can be found in
+.I "Maintaining Files on Plan 9 with Mk"
+by Hume and Flandera,
+reprinted in this volume.
+The source for
+.CW mk
+itself is included in
+.CW utils/mk .
+(It must be compiled manually on the initial port to a new host environment.)
+.NH 1
+The C compilers
+.PP
+An unusual property of the compiler suites used to compile native
+Inferno is that there is no difference in configuration or content
+between a `compiler' (compiling on the same system and processor type as the target)
+and a `cross compiler' (compiling on a host that differs from the target),
+even when the host operating systems are quite different.
+Indeed, in their ancestral home, Plan 9, it is the default action to compile
+instances of all compilers for all possible target architectures,
+as a matter of course.
+.PP
+The main difference between this suite and the original Plan 9 suite is
+that all Plan 9 C extensions have been eliminated from the compiler's own source,
+allowing it to be compiled on environments that accurately support
+ANSI C and a few necessary Posix functions.
+.PP
+The source for the compilers is found in subdirectories of
+.CW utils .
+The compilers are named as follows:
+.RS
+.IP \f50c\fP 8
+MIPS compiler for 64-bit little-endian R4000 MIPS (or `\f5spim\fP')
+.IP \f51c\fP
+68000 compiler, usable with the Motorola Dragonball
+.IP \f52c\fP
+680x0 compiler for x >= 2
+.IP \f55c\fP
+ARM compiler
+.IP \f56c\fP
+AMD64
+.IP \f58c\fP
+Intel x86 compiler, for x>2
+.IP \f5kc\fP
+Sun SPARC compiler
+.IP \f5qc\fP
+PowerPC compiler
+.IP \f5vc\fP
+MIPS R[234]000 in 32-bit big-endian mode
+.RE
+.LP
+The compilers share components, compiled into a library from
+source in the directory
+.CW utils/cc .
+The corresponding assemblers and linkers are found in similarly
+named directories:
+.CW 2a
+and
+.CW 2l
+are the assembler and linker for use with
+.CW 2c
+for instance.
+Note that this suite is unusual in that the compilers and assemblers produce
+a binary assembly language that is finally converted to machine code
+by the linker.
+The assembler is used only to write machine-language assist for the operating
+system, or a run-time routines using instructions not accessible from C,
+and is not used by the compiler.
+See the paper ``Plan 9 C compilers'' by Ken Thompson,
+reprinted in this volume.
+.PP
+With the exception of the 68000 compiler, all the compilers have been
+used extensively to compile Inferno, and most have been used
+to compile Plan 9 and all its applications; and we have found them solid.
+The 68000 compiler was used to attempt a port of Inferno to the Motorola
+Dragonball (in the Palm Pilot).
+It is included here in case someone wishes to have another go.
+We have no experience with it.
+.PP
+The ARM compiler
+.CW 5c
+supports the ARM (Strongarm, PXA) architecture;
+the related compiler
+.CW tc
+generates ARM's Thumb instructions instead.
+The output of both can be linked together by the ARM loader
+.CW 5l
+to achieve ARM-Thumb interworking.
+.CW 5c
+has been used to generate code for the StrongARM SA110 and SA1100
+processors (the primary
+targets for native Inferno for many years).
+The code generated was greatly improved by Richard Miller.
+The floating-point support is adequate for C programs: the compiler
+generates ARM floating-point instructions, as implemented on the ARM7500 but
+not on the Strongarm, where they must be emulated.
+.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 405EP, 603, 70x, 821, 823, and 860.
+On the embedded processors such as 405 and 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.
+The compiler does replace explicit comparisons by condition-setting instructions.
+Its run-time conventions are more efficient than those of the PowerPC ABI.
+.NH 1
+Applications
+.PP
+Dis object files are portable across all variants of Inferno, hosted and native.
+There need be only one copy of the Dis files to serve many different
+versions of Inferno; they need not be rebuilt for each platform
+and can be shared by different types of host.
+Limbo insulates the programmer from all details of
+the particular processor, including byte-ordering,
+and consequently the applications themselves are portable.
+.PP
+The source for the applications is found in subdirectories of
+.CW appl :
+.CW appl/cmd
+holds the source for most command line applications (that use no graphics);
+.CW appl/wm
+contains the source for most applications that run under
+.I wm (1);
+.CW appl/svc
+contains the source for various system services and file servers;
+.CW appl/mux ,
+the source for the interactive television demo
+.I mux (1);
+.CW appl/charon ,
+the source for the Charon web browser; and
+.CW appl/acme
+the source for Acme written in Limbo.
+.PP
+The
+.CW mkfile
+in each directory can currently only be used by an instance of
+.CW mk
+running
+.I outside
+the Inferno environment, under the host operating system.
+This complicates its use with
+.I acme (1),
+normally requiring the use of the
+.I os (1)
+command.
+In a few cases, there is a
+.CW mashfile
+that can be used by
+.I mash-make (1)
+to build a Limbo application from within Inferno (native or hosted).
+A consistent approach to building applications both inside and outside
+Inferno is being developed.
+In any case, the resulting Dis files are portable once produced.
+.NH 1
+Hosted Inferno (emu)
+.PP
+There are currently four main variants of hosted Inferno: Plan 9, Unix (and clones), MacOS X and Windows.
+The source is held in directory
+.CW emu ,
+with a subdirectory for each hosted platform:
+.CW FreeBSD ,
+.CW Irix ,
+.CW Linux ,
+.CW Nt
+(for all Windows platforms, including the Internet Explorer plug-in),
+.CW MacOSX ,
+.CW Plan9 ,
+and so on.
+Each platform directory has a
+.CW mkfile
+and one or more configuration files of the form described by
+.I config (6).
+An executable for a particular host type is built on that host type,
+under the host's own command interpreter, not under Inferno.
+Move to the
+.CW emu
+subdirectory appropriate to that host,
+ensure the command interpreter's path variable includes
+the directory containing the Inferno
+.CW bin
+directory for that host
+(eg,
+.CW /home/inferno/Solaris/sparc/bin ),
+and run
+.CW mk .
+.PP
+Like the native kernels
+.CW emu
+relies on several auxiliary libraries (the source of which
+it often shares with the native kernels).
+Emu itself is built by the
+.CW mkfile
+in the
+.CW emu
+platform directory for the host, as described above.
+Each library has its own
+.CW mkfile ;
+the various components are made in the right order by the
+.CW mkfile
+at the root of the Inferno tree.
+The
+.CW mkfile
+for each platform will also invoke
+.CW mk
+recursively to make the appropriate libraries
+for a given configuration.
+.PP
+The Unix emu variant generally is covered by `POSIX' (with common extensions)
+but each Unix port has one file that differs considerably for each port,
+namely \f5emu/\fP\fIplatform\fP\f5/os.c\fP, the differences
+corresponding to the different ways under Unix of implementing kernel-scheduled
+threads efficiently.
+.PP
+There are working emu versions
+for
+FreeBSD/386,
+Irix/mips,
+Linux/386,
+MacOSX/power,
+Plan 9,
+Solaris/sparc,
+and Windows (NT, 2000 and Explorer plug-in).
+Each platform typically uses mechanisms specific to the host operating
+system to implement Inferno's internal thread/process structure.
+POSIX threads have often been found to be insufficient (poorly implemented)
+on some platforms, and if so are avoided.
+See
+.CW kproc
+in
+.CW emu/*/os.c .
+.PP
+Source is included for ports to HP/UX (S800 architecture),
+Solaris/386, and Unixware, in case someone wishes to take them up now,
+but we have not determined their fitness.
+.PP
+The Plan 9 hosted implementation is unusual in that it supports
+several processor types:
+.CW 386 ,
+.CW mips ,
+.CW power
+(Power PC)
+and
+.CW sparc .
+Furthermore, all versions of
+.CW emu
+can be built on any processor type, in the usual way for Plan 9.
+.PP
+Otherwise, as distributed,
+.CW emu
+for a platform can only be built when running on that platform.
+.PP
+One unusual variant makes the whole of Inferno a plug-in for Microsoft's
+Internet Explorer, giving the same environment for Inferno applications
+running in an HTML page as is provided by hosted or native Inferno.
+That is, there is not a distinct `applet' environment with special programming interfaces.
+The source for the various plug-in components is found in
+.CW /tools/plugin
+and
+.CW /usr/internet
+within the Inferno tree; they use the version of
+.I emu
+defined by the configuration file
+.CW /emu/Nt/ie .
+.PP
+All the libraries an executables can be built in a tree containing only the source code.
+To do that for a supported variant of hosted Inferno, on Unix or Plan 9, do the following
+in the root of the Inferno tree:
+.IP 1.
+Run
+.CW makemk.sh
+to rebuild the
+.CW mk
+command, which is used to build everything else.
+.IP 2.
+Set
+.CW PATH
+(or
+.CW path
+on Plan 9)
+to include the
+.CW bin
+directory for the platform, which will now contain the
+.CW mk
+binary just built.
+On Unix, export
+.CW PATH .
+.IP 3.
+Then
+.CW "mk nuke"
+to remove any extraneous object files.
+.IP 4.
+Finally,
+.CW "mk install"
+to create and install the libraries,
+.CW limbo
+compiler,
+.CW emu
+for hosted Inferno, and auxiliary commands.
+The rules do that in an order that ensures that the commands or libraries
+needed by a later stage are built and installed first.
+(Note that a plain
+.CW mk
+will not suffice, because it does not put the results in the search path.)
+.LP
+Doing something similar on Windows or Plan 9 currently requires the executable for
+.CW mk
+to be available in the search path,
+since there is no equivalent of
+.CW makemk.sh .
+Otherwise the procedure is the same.
+On Plan 9, of course, the host system's normal version of
+.CW mk
+should be adequate.
+.NH 1
+Native Inferno
+.PP
+As with the different versions of emu, once the native kernel is running, all applications
+work straight away;
+the same applications are used in native and emulated mode, subject to
+suitable devices being available.
+Because the portable compiler suite is used to compile native kernels,
+and those compilers are automatically cross-compilers, all native Inferno
+implementations can be built on any host platform.
+Furthermore, the build procedures and resulting object files are the same.
+.PP
+Early ports in 1996 were made by Bell Labs to an internal device based on
+the AMD 29000, an early ARM-based `network computer', and Intel-based PCs.
+Between 1997 and 1999, Lucent concentrated mainly on the Strongarm platform
+(SA1100), for various Digital/Intel development boards,
+and especially several `web phones', including the Sword Webphone Reference Design.
+It also undertook ports to other devices for experiment, or under contract.
+.PP
+Vita Nuova Limited also ported the system, both for its own purposes
+and under contract to Lucent.
+Targets included a small 386-based Internet device,
+a set top Internet box using the PowerPC 603e,
+a digital television set top box with a Strongarm SA110 and a Teralogic TL750 graphics chip,
+the USR/3Com Edgeserver (in a chassis containing various types of line card),
+various boards based on the PowerPC 823/821/860,
+many different configurations of IBM PC,
+and a Ziatech Pentium-based VME crate.
+.PP
+Distribution of most previous and existing ports is restricted by
+the terms on which they were undertaken,
+or because they were ports of older Inferno releases and not kept up to date.
+We have included the following as examples in this distribution.
+.SH
+The StrongARM kernel
+.PP
+The source for the StrongARM kernels is split across several directories.
+The directory
+.CW os/sa1110
+contains all code that is generally architecture-specific but platform-independent.
+Other directories contain platform-specific code:
+.CW os/cerf1110
+for the Intrinsyc Cerfcube1110,
+and
+.CW os/ipaq1110
+for the Compaq (as it then was) IPAQ H3650.
+Earlier Webphone ports are tied to hardware that is not generally obtainable
+and the ports to those
+platforms included some software (notably modem software)
+that cannot generally be distributed.
+.PP
+There is also a preliminary port to the ARM-based Intel XScale.
+The code common to PXA implementations is in
+.CW os/pxa .
+The initial platform was the Intrinsyc Cerfboard 250; its code is in
+.CW os/cerf250 .
+A port to the Gumstix (see
+.CW www.gumstix.com )
+is in progress.
+.PP
+The platform's own bootstrap is used in all cases.
+On the IPAQ, the Linux bootloader from Compaq (HP) Research must
+be loaded onto the device first, following instructions given at
+.CW www.handhelds.org .
+See the
+.CW README
+file in each
+.CW os
+source directory for details.
+.PP
+Other ARM-based processors to which Inferno has been ported include
+the ARM-7 evaluator kit (see
+.CW os/ks32 ),
+although its memory is tight,
+and the TI925 including the TI OMAP.
+The latter two ports were to proprietary TI925 implementations, and have not
+been included, but there is a body of code common to all such platforms that
+could be made available if that were useful.
+.SH
+The PowerPC kernel
+.PP
+The directory
+.CW os/fads
+contains the port of Inferno to the MPC8xx FADS development board.
+It has been used with the MPC821, MPC823 and MPC860 processors.
+It uses code common to MPC8xx processors, found in
+.CW os/mpc .
+The interface to the CPM is provided by
+.CW cpm.c .
+There are drivers for the real time clock,
+flash devices (including a Flash Translation Layer driver),
+and communications controllers in Ethernet,
+UART, and IrDA mode
+(see
+.CW etherscc.c
+and
+.CW devuart.c ).
+The IrDA has been used for Styx transport between a FADS board
+and an IBM Thinkpad 560.
+The file
+.CW screen.c
+drives an 8-bit per pixel LCD (TFT) display panel.
+A sample interface to the on-chip video device of the MPC823 (only)
+as wired on the FADS board using auxiliary chips can be found in
+.CW devvid.c .
+The York Electronics Centre developed a touch panel for us,
+connected using SPI;
+the driver is
+.CW devtouch.c ,
+and could be adapted for similar devices.
+.PP
+The bootstrap program for the FADS board is in
+.CW os/boot/mpc ,
+loosely derived from an older version of
+.CW os/boot/pc .
+It is initially converted to S records that are loaded into flash by MPC8BUG
+from a PC, and thereafter the images of the boot and kernel images can
+be updated using the flash devices provided by the system itself,
+and the utility programs
+.CW qconfig.b
+and
+.CW qflash.b
+in
+.CW appl/cmd/mpc .
+.PP
+Another port is to the Brightstar Engineering ip-Engine containing an MPC823
+and an Altera FPGA.
+See
+.CW os/ipengine .
+It uses common code from
+.CW os/mpc .
+The device driver that loads the FPGA is in
+.CW devfpga.c ;
+see
+.I fpga (3)
+for the interface and
+.I fpgaload (8)
+for a command to do it.
+See the
+.CW README
+file for information on loading the kernel into the flash.
+.PP
+The most recent PowerPC port is to the IBM 405EP, and more specifically
+to the Intrinsyc Cerfcube 405EP.
+The source for that port is in
+.CW os/cerf405 ;
+lacking another 405EP platform for reference, the source code has not yet
+been split into that common to all 405EP implementations and that specific
+to the Cerfcube, although that would be easy to do.
+.SH
+The x86 kernel
+.PP
+The
+.CW os/pc
+directory contains the components for ports to 386, 486 and Pentium class machines.
+The main difficulty is device support: in particular
+only a limited set of Ethernet and graphics cards is supported.
+We have used mainly the 3Com and Intel 82557 drivers.
+A `generic' PC port is included that has a graphics driver that
+should run on systems that provide a VESA BIOS mode.
+.PP
+We have a (slow) floating-point emulator for the 386 found in
+.CW os/pc/fpi387.c ;
+code to invoke it in trap can be provided on request.
+.PP
+The source for the PC bootstrap program
+.CW 9load
+is in
+.CW os/boot/pc .
+It is simply a copy of the current Plan 9 PC bootstrap program, with slight modifications
+to allow it to be compiled on many host systems.
+.SH
+The Javastation 1 kernel
+.PP
+The directory
+.CW os/js
+has the first port
+to the Sun Javastation 1.
+It was done by Tad Hunt and Eric Van Hensbergen
+in a matter of days to demonstrate Inferno at Java One in 1997.
+It boots over the net using TFTP.
+Javastations being a bit thin on the ground now,
+it is unlikely to be directly usable unless you can find one second hand
+(you might find a Javastation 2 coffee pot, but that is slightly different again).
+That is a pity, because the machine was quite usable running Inferno and
+Limbo applications, often surprising those used to the Java-based
+offering on the same platform.
+It is included as an example of a micro-SPARC port.
+Beware that
+.CW screen.c
+has not yet been converted for Fourth Edition graphics
+(partly because we no longer have a suitable device for testing).
+.NH 1
+Supporting tools
+.PP
+The
+.CW utils
+directory also contains ANSI C versions of other components of the
+Plan 9 development suite,
+such as
+.CW nm ,
+.CW ksize ,
+.CW ar ,
+and of course
+the
+.CW acid
+debugger.
+Most rely on
+.CW libmach ,
+a suite of functions forming a
+library to handle the various object and executable files in one place.
+.PP
+Some other utilities give a portable
+way to express some of the kernel build scripts:
+.CW sed ,
+.CW test ,
+.CW rm ,
+and
+.CW mkdir .
+On Plan 9,
+.CW mk
+and kernel build scripts use Plan 9's own shell,
+.I rc .
+On Unix systems, they use
+.I sh .
+On Windows, a version of Plan 9's
+.I rc
+has been ported to reduce the number of variants
+to two, and keep the system self-contained; its source is in
+.CW utils/rcsh 
+and installs as
+.CW rcsh.exe .
diff --git a/doc/port.pdf b/doc/port.pdf
new file mode 100644
index 00000000..3d5795ff
--- /dev/null
+++ b/doc/port.pdf