diff options
| -rw-r--r-- | CHANGES | 2 | ||||
| -rw-r--r-- | doc/port.ms | 573 | ||||
| -rw-r--r-- | doc/port.pdf | bin | 0 -> 50037 bytes | |||
| -rw-r--r-- | lib/proto/src | 2 |
4 files changed, 577 insertions, 0 deletions
@@ -1,3 +1,5 @@ +20070122 + add doc/port.ms, doc/port.pdf to src proto. add brief instructions for source rebuild to port.ms 20070118 add json(2) {/appl/lib/json.b, /module/json.m, /dis/lib/json.dis} for RFC4627 notation [json(6)] 20070117 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 Binary files differnew file mode 100644 index 00000000..3d5795ff --- /dev/null +++ b/doc/port.pdf diff --git a/lib/proto/src b/lib/proto/src index 850d6b42..b741ce66 100644 --- a/lib/proto/src +++ b/lib/proto/src @@ -68,6 +68,8 @@ doc perform perform.ms perform.pdf + port.ms + port.pdf realinferno real.ms real.pdf |