mxr(1) General Commands Manual mxr(1)
NAME
mxr - DECmigrate: MIPS Translator Runtime Environment
SYNOPSIS
[executable_name] [options...]
/usr/bin/mxr -help
/usr/bin/mxr -V
OPTIONS
Display the mxr help message. Display the mxr version number.
DESCRIPTION
The MIPS Translator Runtime Environment, mxr, supports binary executables produced by DECmigrate (mx). When you execute the output exe-
cutable on an Alpha system running Tru64 UNIX, mxr is automatically invoked either as a shared image or as a shared library. The mxr envi-
ronment provides the translated executable with any MIPS or ULTRIX resources it requires to run.
In cases where there is no Tru64 UNIX translation for an ULTRIX operation, mxr supports the executable by emulating that operation. In
addition, mxr provides feedback, enabling mx to retranslate the executable, eliminate some or all instances of emulation, and improve run-
time performance.
RESTRICTIONS
The mxr environment does not support certain ULTRIX operations. See the release notes for the unsupported ULTRIX operation. The mxr envi-
ronment only supports executables that were translated by mx.
The mxr environment only supports setuid or setgid programs or OMAGIC executions if the executable was translated using the -coff option
(the default) to the mx command. In addition, mxr only supports non-finite numbers if the executable was translated with the -full_fp
option to the mx command.
DEBUGGING
This section describes situations when the translated executable fails at runtime, runs but produces different results than the original
executable, or runs slowly.
If an executable runs properly on an ULTRIX system but fails when translated and run on a Tru64 UNIX system, check the following: File
Names: Some executables read the name with which they were invoked to determine operating behavior. To enable these executables to run
properly on a Tru64 UNIX system, ensure that the file names match the original names of the files on the ULTRIX system. Restore filenames
as necessary. Missing Files: See if there are any files that need to be moved to the Tru64 UNIX system. Some executables require certain
files to exist at specific places in the file system, and fail when that is not true. For example, many X clients require files in
/usr/lib/X11/app-defaults and /usr/lib/X11/uid. Translated MicroFocus COBOL programs attempt to access the file /usr/lib/cobol/rts32, and
abort if that file is not present.
To see a list of the files that a program is trying to find, set the environment variable MXR_TRACE_VARIABLES to stat,open.
To run translated programs, copy the missing files to the Tru64 UNIX system and place them in directories that correspond to their
original directories. For example, to run translated MicroFocus COBOL programs on a Tru64 UNIX system, do the following: On the
Tru64 UNIX system, create the /usr/lib/cobol directory. Copy the /usr/lib/cobol/rts32 file from the ULTRIX system on which COBOL is
installed to the /usr/lib/cobol directory on the Tru64 UNIX system. Invoke the translated executable. Floating Point Exceptions:
Floating point calculations involving non-finite numbers such as infinites, denormalized numbers, or Not-a-Numbers (NaNs), generate
exceptions on the Alpha architecture. These calculations are handled silently by the MIPS architecture. If an executable generates
SIGFPEs, an error message of the following form displays and the program terminates:
The translated program attempted a floating-point calculation with a denormalized number or NaN. Retranslate using the -full_fp
option to mx.
To reproduce the MIPS system behavior, mxr must intercept these exceptions and perform the appropriate actions without signaling the
translated program. Retranslate program using the -full_fp option to mx, then run the new translated executable. The results of the
calculations using or producing non-finite numbers are consistent with IEEE/ANSI 754-1985 and should produce the same results as the
original program. See the user manual for more information. If the executable still generates SIGFPEs, try translating with the mx
option -trapb. If you do this, please file an SPR including the results with Compaq so that -full_fp option can be enhanced. You
can still use MXR_GENERATE_FEEDBACK, but -full_fp must be set each time you retranslate the executable. See the FEEDBACK section.
Error message saying "Unaligned access on ldt" or "Unaligned access on stt:" If you get a message of this form, retranslate using
the -F option to mx. This causes mx to assume that all floating-point loads and stores are potentially unaligned, and to generate
code accordingly. Refer to the EXAMPLES section. Error message saying "Stack not longword aligned:" This error message indicates a
serious bug in your original program.
If an executable runs on the Tru64 UNIX system but does not produce the same output as the ULTRIX executable, check the following:
Some executables look at the stack and use the return address to examine the MIPS code stream. These executables will not work
properly when translated. These executables include: Ada executables that use exceptions PL/1 executables that use signals Some
classes of FORTRAN executables Some programs that use Compaq's VMS portability library (plib). Some executables expect non-finite,
floating point numbers, such as infinities, denormalized numbers, and Not-a-Numbers, to behave as specified in the IEEE/ANSI
754-1985 standard. To support this, you must translate the executable with the -full_fp option. Otherwise, the results of the
translated executable might be different from the original executable, or may abort with a floating-point exception. Error message
saying "The program changes the rounding mode to -Infinity..." Retranslate the executable using the -fixround option. At runtime,
code checks the rounding mode, and changes each instance of floating point rounding to RM (minus infinity) to floating point round-
ing to RZ (zero).
This may cause a slight loss of precision, but might substantially improve the runtime performance of the translated program. The
/bin/time file created by the executable shows large amounts of time being spent on system operations. Translate executable using
the -fixround option. At runtime, code checks the rounding mode, and changes each instance of floating point rounding to minus
infinity (RM) to floating point rounding to zero (RZ).
This may cause a slight loss of precision, but might substantially improve the runtime performance of the translated program.
If the translated executable runs, but slowly, see if the translation can be improved with feedback. See the FEEDBACK section.
FEEDBACK
If you set the MXR_GENERATE_FEEDBACK environment variable and the executable creates or extends a file when executing, this means mxr dis-
covered new entry points while executing the executable. Retranslating the executable allows mx to access the entry points and improve the
speed of the executable. Do the following: Delete or remove the translated executable. You do not need it to create the next version.
Copy only the file to the system and directory containing both mx and the original input executable. Be sure the name of the file is exe-
cutable.hif, where executable is the file name of the input executable. Retranslate the original input executable using mx.
The mx translator reads the file and uses the information in it to improve the translation. Run the retranslated executable with
the MXR_GENERATE_FEEDBACK environment variable set. If the retranslated executable discovers more entry points, it appends entries
to the file, extending the file. Repeat steps 1, 2, 3, and 4 until no new entries are created during execution.
ERROR MESSAGES
Error messages are described in the DECmigrate User's Guide.
The severity levels are as follows: Informational message. Not displayed unless MXR_VERBOSE is set. Warning message. Warning messages
are displayed unless MXR_QUIET is set. A warning usually results in the specified operation, such as syscall, returning an error status,
but the translated program continues to run. Fatal error message. Always displayed if an error occurs. Error messages cause immediate
termination of the translated program.
ENVIRONMENT VARIABLES
The mxr environment modifies its behavior if any of the following environment variables are set when you execute a translated executable:
Generate a file to use as feedback for a subsequent retranslation. This is overridden by the -nohifs option in mx. See the FEEDBACK sec-
tion. Redirect mxr input/output through an xterm window. This is useful for separating mxr diagnostic messages. Print all debugging out-
put in detailed form. Prints program header information and "unrecognized error tag" messages. Prints program load/execute progress.
Prints program exit details and homing map. Prints signal details. Prints ioctl() details. Prints brk() details. Prints computed branch
details. Suppress all mxr output except for fatal errors. Note: You may be suppressing nonfatal error messages that indicate you are
using an unsupported feature. The executable still runs, but its function is unpredictable. Trace all system calls. If no system calls
are specified, all system calls are traced. If any system calls are specified or if the word "all" appears in the list, only those calls
are traced. Preceding a system call name with a hyphen (-) forces it not to be traced. The list is scanned left-to-right. Separate the
system call names with commas (,). For example:
MXR_TRACE_SYSCALLS open, close, read, write
Traces the calls specified.
MXR_TRACE_SYSCALLS all, -read, -write
Traces all syscalls except read and write. If you are using either the ksh or sh shell, the format is:
MXR_TRACE_SYSCALLS=xxx,xxx export MXR_TRACE_SYSCALLS Display runtime statistics when the executable exits. Trace all signals and
signal system calls.
EXAMPLES
The following is an excerpt from the terminal output of an executable that needs to be retranslated by mx with the -F option. The opcodes
stt (type=stt) and ldt (type=ldt) are the ones in error.
[963] piston:person> dxpsview quilt.ps Unaligned access pid=419 <mxr> va=10041624 reg=4 type=stt pc=58cbd8 ra=58c8f0 Unaligned access
pid=419 <mxr> va=1004161c reg=2 type=ldt pc=58cbd8 ra=58c8f0
FILES
The run-time support for executables translated using the -coff option to the mx command. Resides on the Tru64 UNIX system, and called in
as a shared library by the translated executable. The runtime support for executables translated using the -script option in mx. The
default name of the translated output file.
SEE ALSO
DECmigrate User's Guide
mxr(1)