EM86: a Linux/x86 Emulator for Linux/Alpha ________________________________________________________________ EM86 0.9.1 README April 4, 1997 This document describes the EM86 0.9.1 beta software release. Contents Introduction................................. 1 Feedback..................................... 2 Package Contents............................. 2 Installation................................. 5 Running EM86................................. 5 Application Notes............................ 6 Restrictions................................. 8 ________________________________________________________________ Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ EM86 0.9.1 README EM86 0.9.1 README ______________________ WARNING ______________________ This early version of EM86 for Linux/Alpha is a developers' beta that we are releasing to the Linux community for evaluation purposes and for software verification. The current kit lacks numerous features that are planned for the final product; probably includes bugs; and has undergone little performance tuning. Therefore, the correctness and performance of this beta release in no way represents the quality of the final product. We also strongly recommend against using this beta in any production environment. _____________________________________________________ Introduction You've bought a Linux/Alpha system and now you want to run all the great software that's currently available only for Linux/x86. EM86, a Linux/x86 emulator for Linux/Alpha, makes this possible! Based on Digital's award-winning FX!32 technology, EM86 allows Linux/x86 binaries to run on Linux/Alpha without modification. So far, we have successfully tested the following applications for compatibility with EM86: Netscape Navigator Gold 3.01 Adobe Acrobat Reader 3.0 Applixware Version 4.2 Red Baron web browser 3.0 ________________________________________________________________ (c) Digital Equipment Corporation 1997. All rights reserved. Netscape Navigator Gold is a trademark of Netscape Communications Corporation. Acrobat Reader is a trademark of Adobe Systems Incorporated. Applixware is a trademark of Applix, Inc. EM86 0.9.1 README 1 EM86 0.9.1 README Introduction We will test many more between now and the final product release. Feedback We welcome suggestions, comments, and reports on your experiences testing EM86 0.9.1. You can send email to us at the following address: em86-bugs@amt.tay1.dec.com Package Contents The developers's beta release of EM86 is available from the following ftp site: ftp.digital.com:/pub/DEC/Linux-Alpha/em86 The EM86 distribution includes the following archive files: __________________________________________________________ File__________________Contents____________________________ em86-bin.tar.gz The EM86 binary and all auxiliary file binaries. em86-libs.tar.gz A collection of Linux/x86 shared libraries for running dynamically- linked ELF binaries. em86-src.tar.gz Sources for EM86 and related programs. kernel-patches.tar.gz Kernel patches needed to enable ______________________certain_EM86_features.______________ 2 EM86 0.9.1 README EM86 0.9.1 README Package Contents The following table describes the contents of each archive: __________________________________________________________ Archive_______________Contents____________________________ em86-bin.tar.gz This archive contains the following files: o /usr/bin/em86 The emulator itself. o /usr/bin/ldconfig86 A version of ldconfig for Linux/x86 ELF binaries that works with the modified library path that EM86 uses. o /usr/bin/ldd86 A version of ldd for Linux/x86 ELF binaries that works with the modified library path that EM86 uses. o /usr/x86/linux486.idx An auxiliary data file needed by EM86. o /usr/x86/lib/ld-linux.so.1.7.1.4.em86 A special version of the Linux/x86 ELF shared library loader that works with EM86. em86-libs.tar.gz This archive contains a snapshot of Linux/x86 shared libraries from the Red Hat 4.0 distribution. EM86 0.9.1 README 3 EM86 0.9.1 README Package Contents __________________________________________________________ Archive_______________Contents____________________________ em86-src.tar.gz This is the source for EM86. Note that the source code is provided for the runtime system but NOT for the x86 execution engine. The x86 execution engine is proprietary code of Digital Equipment Corporation and the source is not available. The source archive contains a binary object library for the execution engine in FX_EM486/libem486.a. kernel-patches.tar.gz This file contains kernel patches required to enable certain features of EM86. There are two files in this archive: o em86-patch This patch is required to implement transparent execution of Linux/x86 binaries. With this patch, you can simply invoke a Linux/x86 binary as you would any other program and the kernel automatically recognizes it and invokes EM86. Without this patch, the only way to run a Linux/x86 binary is to invoke EM86 explicitly. o traparg-patch-2.0 This patch for 2.0.x kernels passes additional information to the signal handler on memory faults. This is required in order to implement automatic stack growth. If you do not apply this patch, you may have problems if your program uses a large stack. __________________________________________________________ 4 EM86 0.9.1 README EM86 0.9.1 README Installation Installation To install EM86, you need at least the em86-bin.tar.gz archive. To install this archive, su to root and unpack this archive from the root directory, for example: $ su Password: # cd / # tar xvzpf /home/bob/em86-bin.tar.gz This setup enables you to run statically-linked Linux/x86 binaries by explicitly invoking EM86, for example: $ /usr/bin/em86 hello.x86 hello, world $ To run most significant Linux/x86 packages, you need Linux/x86 shared libraries. To avoid conflicts with the existing shared libraries on the Linux/Alpha system, EM86 looks for shared libraries in the /usr/x86 tree. The easiest way to install shared libraries is to install the em86-libs.tar.gz file as shown above for the archive em86-bin.tar.gz. However, if you have a slow network connection and a Linux/x86 system is available, you can copy the shared libraries to the Linux/Alpha system as follows: __________________________________________________________ Copy_from_x86_system_______To_this_Alpha_system_tree______ /lib/lib*.so* /usr/x86/lib /usr/lib/lib*.so* /usr/x86/usr/lib /usr/X11R6/lib/lib*.so*____/usr/x86/usr/X11R6/lib_________ Similarly, install any Linux/x86 shared libraries you need subsequently under the /usr/x86 hierarchy. DO NOT under any circumstances replace /usr/x86/lib/ld-linux.so.*, which is a special version built to operate with EM86. Replacing it with one not so modified can cause emulated programs not to work. EM86 0.9.1 README 5 EM86 0.9.1 README Installation Finally, for the smoothest operation of EM86, we strongly suggest that you apply the kernel patches described above (em86-patch and traparg-patch-2.0) and rebuild your kernel. The em86-patch adds a new configuration option (support for Linux/x86 ELF binaries). Be sure to enable this option! Running EM86 Once you have installed EM86 and applied the kernel patch em86-patch, Linux/Alpha invokes EM86 automatically when you invoke a Linux/x86 application. If you have not applied the patch, you can invoke EM86 to run a Linux/x86 executable with the following command: $ em86 x86_executable_name See the man page for details on the EM86 operating environment. Application Notes EM86 has been tested on numerous test cases and small applications (xtetris, for example). In addition, three major packages have been verified to run to varying degrees under EM86. Following are notes on each package. __________________________________________________________ Application___________Notes_______________________________ Netscape Navigator Install Netscape Navigator Gold Gold 3.01 as per the supplied installation instructions. _____________ WARNING_____________ DO NOT under ANY circumstances enable Java or JavaScript until further notice. Attempting to use these WILL crash your browser. While this is a known problem even under Linux/x86, none of the suggested workarounds improved the situation. We are currently investigating this problem. __________________________________ If Netscape has trouble locating Internet hosts, but you can ping these hosts from the command line, try installing an /etc/nsswitch.conf file. 6 EM86 0.9.1 README EM86 0.9.1 README Application Notes __________________________________________________________ Application___________Notes_______________________________ Adobe Acrobat Reader Use the supplied install procedure 3.0 to install Acrobat Reader. With the em86-patch applied to your kernel, this application should run normally. Otherwise, you will need to modify the script /usr/local/Acrobat3/bin/acroread to use EM86 to invoke the acroread binary. Applixware 4.2 Because Applixware uses rpm for installation, you must override the architecture check. (rpm does not normally allow you to install the binaries for one architecture onto a machine of a different architecture). To override, copy the install script from the CD to a writable location, then edit the script to supply the "-ignorearch" flag to rpm. Since Applixware has binaries that invoke other binaries, you need to apply the em86-patch to the kernel for it to run. Since Applixware pushes lots of data on the stack, you also need to apply ______________________the_traparg-patch_to_the_kernel.____ EM86 0.9.1 README 7 EM86 0.9.1 README Restrictions Restrictions The EM86 restrictions are as follows: o EM86 emulates user-mode code only. o EM86 cannot run programs that access virtual memory above the address 78000000. o EM86 does not now, nor will in the future, support the following system calls: setup, break, ptrace, stty, gtty, prof, acct, phys, lock, mpx, ulimit, profil, ioperm, iopl, idle, mx86, modify-Ldt, create_module, init_module, delete_module, get_kernel_syms, bdflush, afs_syscall, and sysctl. o EM86 0.9.1 does not support the following system calls that will be supported in future releases: mount, umount, uselib, old_readdir, sysinfo, ipc sigreturn, clone, adjtimex, quotactl, sysfs, flock, msync, mlock, munlock, mlockall, munlockall, sched_setparam, sched_getparam, sched_setscheduler, sched_getscheduler, sched_yield, sched_get_priority_max, sched_get_priority_min, sched_rr_get_interval, nanosleep, and mremap. 8 EM86 0.9.1 README