1.TL 2Inferno Ports: Hosted and Native 3.AU 4Vita Nuova 527 April 2005 6Revised 22 January 2007 7.PP 8Inferno is a portable environment, encompassing operating system, 9languages, virtual machine and the tools required to build it. 10This section briefly summarises the state of the ports and compilers 11included in this release. 12Directory names are relative to the root of the Inferno release tree, 13unless otherwise specified by the context. 14.PP 15All components are built using the program 16.CW mk , 17based on `make'-like recipes found in the 18.CW mkfile 19in each source directory throughout the Inferno tree. 20.CW Mk 21is described by the manual page 22.I mk (10.1) 23in Volume 1; a more tutorial discussion, including 24a summary of differences with Unix 25.I make , 26can be found in 27.I "Maintaining Files on Plan 9 with Mk" 28by Hume and Flandrena, 29reprinted in this volume. 30The source for 31.CW mk 32itself is included in 33.CW utils/mk . 34It is included ready-made in the full and source-only distributions, to make life easier. 35It must be compiled manually only on the initial port to a new host environment; 36instructions for that are given below. 37.PP 38.NH 1 39The C compilers 40.PP 41An unusual property of the compiler suites used to compile native 42Inferno is that there is no difference in configuration or content 43between a `compiler' (compiling on the same system and processor type as the target) 44and a `cross compiler' (compiling on a host that differs from the target), 45even when the host operating systems are quite different. 46Indeed, in their ancestral home, Plan 9, it is the default action to compile 47instances of all compilers for all possible target architectures, 48as a matter of course. 49.PP 50The main difference between this suite and the original Plan 9 suite is 51that all Plan 9 C extensions have been eliminated from the compiler's own source, 52allowing it to be compiled on environments that accurately support 53ANSI C and a few necessary Posix functions. 54.PP 55The source for the compilers is found in subdirectories of 56.CW utils . 57The compilers are named as follows: 58.RS 59.IP \f50c\fP 8 60MIPS compiler for 64-bit little-endian R4000 MIPS (or `\f5spim\fP') 61.IP \f51c\fP 6268000 compiler, usable with the Motorola Dragonball 63.IP \f52c\fP 64680x0 compiler for x >= 2 65.IP \f55c\fP 66ARM compiler 67.IP \f56c\fP 68AMD64 69.IP \f58c\fP 70Intel x86 compiler, for x>2 71.IP \f5kc\fP 72Sun SPARC compiler 73.IP \f5qc\fP 74PowerPC compiler 75.IP \f5vc\fP 76MIPS R[234]000 in 32-bit big-endian mode 77.RE 78.LP 79The compilers share components, compiled into a library from 80source in the directory 81.CW utils/cc . 82The corresponding assemblers and linkers are found in similarly 83named directories: 84.CW 2a 85and 86.CW 2l 87are the assembler and linker for use with 88.CW 2c 89for instance. 90Note that this suite is unusual in that the compilers and assemblers produce 91a binary assembly language that is finally converted to machine code 92by the linker. 93The assembler is used only to write machine-language assist for the operating 94system, or a run-time routines using instructions not accessible from C, 95and is not used by the compiler. 96See the paper ``Plan 9 C compilers'' by Ken Thompson, 97reprinted in this volume. 98.PP 99With the exception of the 68000 compiler, all the compilers have been 100used extensively to compile Inferno, and most have been used 101to compile Plan 9 and all its applications; and we have found them solid. 102The 68000 compiler was used to attempt a port of Inferno to the Motorola 103Dragonball (in the Palm Pilot). 104It is included here in case someone wishes to have another go. 105We have no experience with it. 106.PP 107The ARM compiler 108.CW 5c 109supports the ARM (Strongarm, PXA) architecture; 110the related compiler 111.CW tc 112generates ARM's Thumb instructions instead. 113The output of both can be linked together by the ARM loader 114.CW 5l 115to achieve ARM-Thumb interworking. 116.CW 5c 117has been used to generate code for the StrongARM SA110 and SA1100 118processors (the primary 119targets for native Inferno for many years). 120The code generated was greatly improved by Richard Miller. 121The floating-point support is adequate for C programs: the compiler 122generates ARM floating-point instructions, as implemented on the ARM7500 but 123not on the Strongarm, where they must be emulated. 124.PP 125The PowerPC compiler supports the 32-bit PowerPC architecture only; 126it does not support either the 64-bit extensions or the POWER compatibility instructions. 127It has been used for production operating system work on the 405EP, 603, 70x, 821, 823, and 860. 128On the embedded processors such as 405 and 8xx floating-point instructions must be emulated. 129Instruction scheduling is not implemented; otherwise the code generated 130is similar to that for the other load-store architectures. 131The compiler makes little or no use of unusual PowerPC features such as the 132counter register, several condition code registers, and multiply-accumulate 133instructions, but they are sometimes 134used by assembly language routines in the libraries. 135The compiler does replace explicit comparisons by condition-setting instructions. 136Its run-time conventions are more efficient than those of the PowerPC ABI. 137.NH 1 138Applications 139.PP 140Dis object files are portable across all variants of Inferno, hosted and native. 141There need be only one copy of the Dis files to serve many different 142versions of Inferno; they need not be rebuilt for each platform 143and can be shared by different types of host. 144Limbo insulates the programmer from all details of 145the particular processor, including byte-ordering, 146and consequently the applications themselves are portable. 147.PP 148The source for the applications is found in subdirectories of 149.CW appl : 150.CW appl/cmd 151holds the source for most command line applications (that use no graphics); 152.CW appl/wm 153contains the source for most applications that run under 154.I wm (1); 155.CW appl/svc 156contains the source for various system services and file servers; 157.CW appl/mux , 158the source for the interactive television demo 159.I mux (1); 160.CW appl/charon , 161the source for the Charon web browser; and 162.CW appl/acme 163the source for Acme written in Limbo. 164.PP 165The 166.CW mkfile 167in each directory can currently only be used by an instance of 168.CW mk 169running 170.I outside 171the Inferno environment, under the host operating system. 172This complicates its use with 173.I acme (1), 174normally requiring the use of the 175.I os (1) 176command. 177In a few cases, there is a 178.CW mashfile 179that can be used by 180.I mash-make (1) 181to build a Limbo application from within Inferno (native or hosted). 182A consistent approach to building applications both inside and outside 183Inferno is being developed. 184In any case, the resulting Dis files are portable once produced. 185.NH 1 186Hosted Inferno (emu) 187.PP 188There are currently four main variants of hosted Inferno: Plan 9, Unix (and clones), MacOS X and Windows. 189The source is held in directory 190.CW emu , 191with a subdirectory for each hosted platform: 192.CW AIX , 193.CW FreeBSD , 194.CW Irix , 195.CW Linux , 196.CW MacOSX , 197.CW NetBSD , 198.CW Nt 199(for all Windows platforms, including the Internet Explorer plug-in), 200.CW Plan9 , 201.CW Solaris , 202and so on. 203Each platform directory has a 204.CW mkfile 205and one or more configuration files of the form described by 206.I config (6). 207An executable for a particular host type is built on that host type, 208using the host's own command interpreter, not under Inferno. 209Move to the 210.CW emu 211subdirectory appropriate to that host, 212ensure the command interpreter's path variable includes 213the directory containing the Inferno 214.CW bin 215directory for that host 216(eg, 217.CW /home/inferno/Solaris/sparc/bin ), 218and run 219.CW mk . 220.PP 221Like the native kernels 222.CW emu 223relies on several auxiliary libraries (the source of which 224it often shares with the native kernels). 225Emu itself is built by the 226.CW mkfile 227in the 228.CW emu 229subdirectory containing the platform-specific source for the host platform. 230Each library has its own 231.CW mkfile ; 232the various components are made in the right order by the 233.CW mkfile 234at the root of the Inferno tree. 235The 236.CW mkfile 237for each platform will also invoke 238.CW mk 239recursively to make the appropriate libraries 240for a given configuration. 241.PP 242The Unix emu variant generally is covered by `POSIX' (with common extensions) 243but each Unix port has one file that differs considerably for each port, 244namely \f5emu/\fP\fIplatform\fP\f5/os.c\fP, the differences 245corresponding to the different ways under Unix of implementing kernel-scheduled 246threads efficiently. 247.PP 248There are working emu versions 249for 250AIX/power, 251FreeBSD/386, 252Irix/mips, 253Linux/386, 254NetBSD/386, 255MacOSX/386, 256MacOSX/power, 257Plan 9, 258Solaris/sparc, 259and Windows (NT, 2000 and Explorer plug-in). 260Each platform typically uses mechanisms specific to the host operating 261system to implement Inferno's internal thread/process structure. 262POSIX threads have often been found to be insufficient (poorly implemented) 263on some platforms, and if so are avoided. 264See 265.CW kproc 266in 267.CW emu/*/os.c . 268.PP 269Source is included for ports to HP/UX (S800 architecture), 270Solaris/386, and Unixware, in case someone wishes to take them up now, 271but we have not determined their fitness. 272.PP 273The Plan 9 hosted implementation is unusual in that it supports 274several processor types: 275.CW 386 , 276.CW mips , 277.CW power 278(Power PC) 279and 280.CW sparc . 281Furthermore, all versions of 282.CW emu 283can be built on any processor type, in the usual way for Plan 9. 284.PP 285Otherwise, as distributed, 286.CW emu 287for a platform can only be built when running on that platform. 288.PP 289One unusual variant makes the whole of Inferno a plug-in for Microsoft's 290Internet Explorer, giving the same environment for Inferno applications 291running in an HTML page as is provided by hosted or native Inferno. 292That is, there is not a distinct `applet' environment with special programming interfaces. 293The source for the various plug-in components is found in 294.CW /tools/plugin 295and 296.CW /usr/internet 297within the Inferno tree; they use the version of 298.I emu 299defined by the configuration file 300.CW /emu/Nt/ie . 301.PP 302All the libraries and executables can be built in a tree containing only the source code. 303To do that for a supported variant of hosted Inferno, on Unix or Plan 9, do the following 304in the root of the Inferno tree: 305.nr Ci 0 +1 306.de Xx 307.IP \\n+(Ci 308.. 309.Xx 310Edit 311.CW mkconfig 312to reflect your host environment, 313specifically ROOT (which must be an absolute path name), SYSHOST and OBJTYPE. 314The comments in the file should help you choose. 315.Xx 316Run 317.CW makemk.sh 318to rebuild the 319.CW mk 320command, which is used to build everything else. 321.Xx 322Set 323.CW PATH 324(or 325.CW path 326on Plan 9) 327to include the 328.CW bin 329directory for the platform, which will now contain the 330.CW mk 331binary just built. 332On Unix, export 333.CW PATH . 334.Xx 335Then 336.CW "mk nuke" 337to remove any extraneous object files. 338.Xx 339Finally, 340.CW "mk install" 341to create and install the libraries, 342.CW limbo 343compiler, 344.CW emu 345for hosted Inferno, and auxiliary commands. 346The rules do that in an order that ensures that the commands or libraries 347needed by a later stage are built and installed first. 348(Note that a plain 349.CW mk 350will not suffice, because it does not put the results in the search path.) 351.LP 352Doing something similar on Windows or Plan 9 currently requires the executable for 353.CW mk 354to be available in the search path, 355since there is no equivalent of 356.CW makemk.sh . 357Otherwise the procedure is the same. 358On Plan 9, of course, the host system's normal version of 359.CW mk 360should be adequate. 361.NH 1 362Native Inferno 363.PP 364As with the different versions of emu, once the native kernel is running, all applications 365work straight away; 366the same applications are used in native and emulated mode, subject to 367suitable devices being available. 368Because the portable compiler suite is used to compile native kernels, 369and those compilers are automatically cross-compilers, all native Inferno 370implementations can be built on any host platform. 371Furthermore, the build procedures and resulting object files are the same. 372.PP 373Early ports in 1996 were made by Bell Labs to an internal device based on 374the AMD 29000, an early ARM-based `network computer', and Intel-based PCs. 375Between 1997 and 1999, Lucent concentrated mainly on the Strongarm platform 376(SA1100), for various Digital/Intel development boards, 377and especially several `web phones', including the Sword Webphone Reference Design. 378It also undertook ports to other devices for experiment, or under contract. 379.PP 380Vita Nuova Limited also ported the system, both for its own purposes 381and under contract to Lucent. 382Targets included a small 386-based Internet device, 383a set top Internet box using the PowerPC 603e, 384a digital television set top box with a Strongarm SA110 and a Teralogic TL750 graphics chip, 385the USR/3Com Edgeserver (in a chassis containing various types of line card), 386various boards based on the PowerPC 823/821/860, 387many different configurations of IBM PC, 388and a Ziatech Pentium-based VME crate. 389.PP 390Distribution of most previous and existing ports is restricted by 391the terms on which they were undertaken, 392or because they were ports of older Inferno releases and not kept up to date. 393We have included the following as examples in this distribution. 394.SH 395The StrongARM kernel 396.PP 397The source for the StrongARM kernels is split across several directories. 398The directory 399.CW os/sa1110 400contains all code that is generally architecture-specific but platform-independent. 401Other directories contain platform-specific code: 402.CW os/cerf1110 403for the Intrinsyc Cerfcube1110, 404and 405.CW os/ipaq1110 406for the Compaq (as it then was) IPAQ H3650. 407Earlier Webphone ports are tied to hardware that is not generally obtainable 408and the ports to those 409platforms included some software (notably modem software) 410that cannot generally be distributed. 411.PP 412There is also a preliminary port to the ARM-based Intel XScale. 413The code common to PXA implementations is in 414.CW os/pxa . 415The initial platform was the Intrinsyc Cerfboard 250; its code is in 416.CW os/cerf250 . 417A port to the Gumstix (see 418.CW www.gumstix.com ) 419is in progress. 420.PP 421The platform's own bootstrap is used in all cases. 422On the IPAQ, the Linux bootloader from Compaq (HP) Research must 423be loaded onto the device first, following instructions given at 424.CW www.handhelds.org . 425See the 426.CW README 427file in each 428.CW os 429source directory for details. 430.PP 431Other ARM-based processors to which Inferno has been ported include 432the ARM-7 evaluator kit (see 433.CW os/ks32 ), 434although its memory is tight, 435and the TI925 including the TI OMAP. 436The latter two ports were to proprietary TI925 implementations, and have not 437been included, but there is a body of code common to all such platforms that 438could be made available if that were useful. 439.SH 440The PowerPC kernel 441.PP 442The directory 443.CW os/fads 444contains the port of Inferno to the MPC8xx FADS development board. 445It has been used with the MPC821, MPC823 and MPC860 processors. 446It uses code common to MPC8xx processors, found in 447.CW os/mpc . 448The interface to the CPM is provided by 449.CW cpm.c . 450There are drivers for the real time clock, 451flash devices (including a Flash Translation Layer driver), 452and communications controllers in Ethernet, 453UART, and IrDA mode 454(see 455.CW etherscc.c 456and 457.CW devuart.c ). 458The IrDA has been used for 9P transport between a FADS board 459and an IBM Thinkpad 560. 460The file 461.CW screen.c 462drives an 8-bit per pixel LCD (TFT) display panel. 463A sample interface to the on-chip video device of the MPC823 (only) 464as wired on the FADS board using auxiliary chips can be found in 465.CW devvid.c . 466The York Electronics Centre developed a touch panel for us, 467connected using SPI; 468the driver is 469.CW devtouch.c , 470and could be adapted for similar devices. 471.PP 472The bootstrap program for the FADS board is in 473.CW os/boot/mpc , 474loosely derived from an older version of 475.CW os/boot/pc . 476It is initially converted to S records that are loaded into flash by MPC8BUG 477from a PC, and thereafter the images of the boot and kernel images can 478be updated using the flash devices provided by the system itself, 479and the utility programs 480.CW qconfig.b 481and 482.CW qflash.b 483in 484.CW appl/cmd/mpc . 485.PP 486Another port is to the Brightstar Engineering ip-Engine containing an MPC823 487and an Altera FPGA. 488See 489.CW os/ipengine . 490It uses common code from 491.CW os/mpc . 492The device driver that loads the FPGA is in 493.CW devfpga.c ; 494see 495.I fpga (3) 496for the interface and 497.I fpgaload (8) 498for a command to do it. 499See the 500.CW README 501file for information on loading the kernel into the flash. 502.PP 503The most recent PowerPC port is to the IBM 405EP, and more specifically 504to the Intrinsyc Cerfcube 405EP. 505The source for that port is in 506.CW os/cerf405 ; 507lacking another 405EP platform for reference, the source code has not yet 508been split into that common to all 405EP implementations and that specific 509to the Cerfcube, although that would be easy to do. 510.SH 511The x86 kernel 512.PP 513The 514.CW os/pc 515directory contains the components for ports to 386, 486 and Pentium class machines. 516The main difficulty is device support: in particular 517only a limited set of Ethernet and graphics cards is supported. 518We have used mainly the 3Com and Intel 82557 drivers. 519A `generic' PC port is included that has a graphics driver that 520should run on systems that provide a VESA BIOS mode. 521.PP 522We have a (slow) floating-point emulator for the 386 found in 523.CW os/pc/fpi387.c ; 524code to invoke it in trap can be provided on request. 525.PP 526The source for the PC bootstrap program 527.CW 9load 528is in 529.CW os/boot/pc . 530It is simply a copy of the current Plan 9 PC bootstrap program, with slight modifications 531to allow it to be compiled on many host systems. 532.SH 533The Javastation 1 kernel 534.PP 535The directory 536.CW os/js 537has the first port 538to the Sun Javastation 1. 539It was done by Tad Hunt and Eric Van Hensbergen 540in a matter of days to demonstrate Inferno at Java One in 1997. 541It boots over the net using TFTP. 542Javastations being a bit thin on the ground now, 543it is unlikely to be directly usable unless you can find one second hand 544(you might find a Javastation 2 coffee pot, but that is slightly different again). 545That is a pity, because the machine was quite usable running Inferno and 546Limbo applications, often surprising those used to the Java-based 547offering on the same platform. 548It is included as an example of a micro-SPARC port. 549Beware that 550.CW screen.c 551has not yet been converted for Fourth Edition graphics 552(partly because we no longer have a suitable device for testing). 553.NH 1 554Supporting tools 555.PP 556The 557.CW utils 558directory also contains ANSI C versions of other components of the 559Plan 9 development suite, 560such as 561.CW nm , 562.CW ksize , 563.CW ar , 564and of course 565the 566.CW acid 567debugger. 568Most rely on 569.CW libmach , 570a suite of functions forming a 571library to handle the various object and executable files in one place. 572.PP 573Some other utilities give a portable 574way to express some of the kernel build scripts: 575.CW sed , 576.CW test , 577.CW rm , 578and 579.CW mkdir . 580On Plan 9, 581.CW mk 582and kernel build scripts use Plan 9's own shell, 583.I rc . 584On Unix systems, they use 585.I sh . 586On Windows, a version of Plan 9's 587.I rc 588has been ported to reduce the number of variants 589to two, and keep the system self-contained; its source is in 590.CW utils/rcsh 591and installs as 592.CW rcsh.exe . 593