DECmigrate for DEC OSF/1 AXP Systems: Release Notes for Version 1.2 02-Mar-1994 Audience These release notes apply to users who are installing DECmigrate Version 1.2 from a CD-ROM. Introduction DECmigrate for DEC OSF/1 AXP Systems Version 1.2 translates binary executables that run on the MIPS hardware architecture on a Digital RISC ULTRIX system to equivalent COFF executables that run on DEC OSF/1 AXP systems. It is a maintenance update from Version 1.1. Changes from Version 1.1 Release When you install DECmigrate from CD-ROM according to the instructions in the installation guide, you install Version 1.2. Version 1.2 supports the translator option, -small, described in New Features. Version 1.2 of mxr replaces Version 1.1 of mxr that is on the DEC OSF/1 1.2 operating system. General Restriction ________________________ Note ________________________ Executables translated and debugged on a particular version of mxr must be run on a system with that version of mxr or higher. For example, if you distribute an executable that was executed and tested with mxr Version 1.1, the recipients must run it on a system containing mxr Version 1.1 or higher. ______________________________________________________ In addition to numerous minor bug fixes, changes from Version 1.1 are as follows: o Applications using NIS/YP now operate correctly when translated. o Signal handling at run time is more robust. The runtime environment operates correctly even when: - the application is interrupted by signals - a user signal handler is run 1 - the translated program processes signals many times per second - signal handlers change MIPS cpu registers in the sigcontext area o The termios ioctl() functions now work correctly. o The indirect system call syscall() works correctly. o The code generation bug that caused incorrect results at the -O1 optimization level has been fixed. New Features The only new feature is the -small option in mx. o Function: If you specify the -small option at translation, the mx translator generates a smaller PC correlation table in the output executable. o Default function: By default, mx generates one entry in the PC correlation table for each basic block in the program. o Consequences of using -small: With the -small option, mx generates one entry per routine in the PC correlation table. This reduces the size of the output executable. The smaller table slightly increases the chance that a computed branch will not be resolved and that the interpreter will be called, slowing performance. o To improve performance after using -small: Calls to the interpreter can be reduced or eliminated by using the user feedback and retranslation processes described in the manpages and in the user manual. o Restrictions: The -small option cannot be specified with the -g option. 2 Description of DECmigrate DECmigrate consists of two parts: o MIPS Translator (mx) The mx translator reads a DEC ULTRIX RISC binary executable, and translates it to an equivalent COFF executable that runs on a DEC OSF/1 AXP system. The mx translator translates user-mode non-privileged ULTRIX 4.0 or later executables and supports all R2000 and R3000 user mode code and signal handlers. The default name for the output executable is mx.out. The output executable runs on a DEC OSF/1 AXP system on which mxr is installed. o MIPS Translator Runtime Environment (mxr) The mxr environment provides run-time support for translated executables running on DEC OSF/1 AXP. The mxr environment must be installed on your DEC OSF/1 AXP system. ________________________ Note ________________________ Because DECmigrate is divided into mx and mxr, so are the reference pages (manpages); the file names for the reference pages are mx.1 and mxr.1. ______________________________________________________ Hardware and Software Requirements The hardware and software requirements for DECmigrate are as follows: o For installation: You need the DEC OSF/1 Version 2.0 Layered Products CD-ROM or a DECmigrate Version 1.2 for DEC OSF/1 AXP CD-ROM. o For mx: The mx translator requires an AXP system running DEC OSF/1 Version 1.2 or later. 3 The mx translator uses a considerable amount of virtual memory during translation. To translate an executable of size x, mx uses up to 20x bytes of virtual memory. Users should configure swap space on their system to handle this virtual memory requirement. While sufficient swap space is necessary for translating large executables, the time taken to translate depends on the system physical memory and system load. o For mxr: Translated executables require an AXP system running DEC OSF/1 Version 1.2 or later with mxr Version 1.2 installed. Memory requirements vary with the executable being run. Running a translated program requires an amount of virtual memory equal to the virtual memory used by the original program, plus memory for the translated code and mxr. As a rule, the virtual memory required for the translated program is calculated as: virtual memory = virtual memory requirements for the original program + virtual memory 1.4 times the size of the original program's text section Note that the translated executable is loaded using the mmap facility. If the interpreter is never used, then the pages corresponding to the MIPS code are never paged in. Because they are mapped by mmap to the executable, the MIPS code thus consumes neither physical memory nor swap space, just a small amount of kernel internal table space. Documentation The user manual, DECmigrate for DEC OSF/1 AXP: Translating Executables, is available in Bookreader format on the DEC OSF/1 Version 2.0 Layered Products Online Documentation CD-ROM, and is also available in hard copy. Reference pages (manpages) for DECmigrate are included with the DECmigrate software. The reference page files are called mx.1 for the translator and mxr.1 for the run-time environment. 4 Kit Location and Contents The software kit for DECmigrate is on the CD-ROM in the directory DMG120. You must have a DEC OSF/1 AXP Operating System Version 1.2 or higher to support translated executables. The DECmigrate kit contains the following items: o The mx translator running on DEC OSF/1 AXP o The mxr environment Version 1.2, to support translated executables running on DEC OSF/1 AXP o The reference pages (mx.1 and mxr.1) and release notes for DECmigrate Installing DECmigrate To install the kit, refer to the DECmigrate for DEC OSF/1 AXP Installation Guide. Restrictions The following restrictions apply to this version of DECmigrate: o Executables that were generated with the -script option are supported only for backwards compatibility. The -script option should not be used for any new translations. We will not support /usr/bin/mxr and and executables using -script in future releases. o Translating compilers does not change the machine code that the compiler produces. For example, translating a MIPS COBOL compiler with DECmigrate yields a COBOL compiler that runs on DEC OSF/1 AXP, but the translated compiler still produces MIPS instructions. For compilers that produce executable files, the user must use DECmigrate to translate the resulting MIPS executable into a DEC OSF/1 AXP executable before attempting to run it on a DEC OSF/1 system. "Incremental" compilers, those which produce MIPS code in memory and then jump into this code, are problematic. The only way to run this code is through the MIPS interpreter in mxr. While the code runs, it is approximately 100 times slower than equivalent translated code. The resulting performance is likely to 5 be barely adequate for prototyping and unacceptable for production. o Applications using file locking may need to start the lock daemons before run time on the DEC OSF/1 AXP system. Lock daemons are not started by default on DEC OSF/1. To see if a failure is related to locking, such as an fcntl() returning "No locks available," set the mxr environment variable MXR_TRACE_SYSCALLS. o The following system calls are completely unsupported: cacheflush(), cachectl() getdopt(), setdopt() mincore() mount(), umount() mremap() nfs_getfh() ptrace() vadvise(), vhangup() setquota(), quota() sigcleanup() sstk() startcpu(), stopcpu() sysmips() utc_gettime(), utc_adjtime() Version 1.2 Known Problems This section lists known problems in the software or documentation: o If you get an error message at runtime saying, "longjmp botch," you may not have installed the latest version of mxr. Verify that the mxr on the DEC OSF/1 AXP system is Version 1.2 by typing mxr -V at the prompt. If necessary, install mxr Version 1.2 from the CD-ROM, subset DMGMXR120. You do not need a software license to install mxr. o Occasionally a program translated with the -O0 option produces the message, "WARNING: INTERNAL ERROR: Internal inconsistency detected in IresourceTempRegister::save_ offset." If this happens, retranslate the program using the -O1 or -O2 option. 6 o The following ioctl() functions are not supported in Version 1.2: BIOGMODE BIOGTYPE BIOSMODE BIOSTYPE DIOCDGTPT DIOCSETPT FIOCINUSE FIONBDONE FIONBUF FIONONBUF FIOSINUSE SIOCGETEVENTS SIOCMANREQ TIOAUTO TIOCMASTER TIOCX29GET TIOCX29SET Submitting Questions and Bug Reports If you want to submit a Software Performance Report (SPR) reporting a bug, call your Customer Support Center (CSC) for information. When submitting bug reports, please report the output of both the mx -V command and the mxr -V command. Dealing with Problems The documentation contains sections on debugging problems with translation. If an executable runs properly on an ULTRIX system but fails during run time on DEC OSF/1 AXP, check the Debugging sections in the documentation. 7