unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



mxr(1)								       mxr(1)



NAME

  mxr -	DECmigrate: MIPS Translator Runtime Environment

SYNOPSIS

  [executable_name] [options...]

  /usr/bin/mxr -help

  /usr/bin/mxr -V

OPTIONS

  -help
      Display the mxr help message.

  -V  Display the mxr version number.

DESCRIPTION

  The MIPS Translator Runtime Environment, mxr,	supports binary	executables
  produced by DECmigrate (mx).	When you execute the output executable on an
  Alpha	system running Tru64 UNIX, mxr is automatically	invoked	either as a
  shared image or as a shared library.	The mxr	environment 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 environment
  only supports	executables that were translated by mx.

  The mxr environment only supports setuid or setgid programs or OMAGIC	exe-
  cutions 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:

	1.  On the Tru64 UNIX system, create the /usr/lib/cobol	directory.

	2.  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.

	3.  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 excep-
       tions 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 calcu-
       lations 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 accord-
       ingly. 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:

	1.  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).

	2.  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 dif-
	    ferent from	the original executable, or may	abort with a
	    floating-point exception.

    +  Error message saying "The program changes the rounding mode to -Infin-
       ity..." Retranslate the executable using	the -fixround option. At run-
       time, code checks the rounding mode, and	changes	each instance of
       floating	point rounding to RM (minus infinity) to floating point
       rounding	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 execut-
  able creates or extends a .hif file when executing, this means mxr
  discovered 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:

   1.  Delete or remove	the translated executable.  You	do not need it to
       create the next version.

   2.  Copy only the .hif file to the system and directory containing both mx
       and the original	input executable.  Be sure the name of the .hif	file
       is executable.hif, where	executable is the file name of the input exe-
       cutable.

   3.  Retranslate the original	input executable using mx.

       The mx translator reads the .hif	file and uses the information in it
       to improve the translation.

   4.  Run the retranslated executable with the	MXR_GENERATE_FEEDBACK
       environment variable set.

   5.  If the retranslated executable discovers	more entry points, it appends
       entries to the .hif file, extending the file.  Repeat steps 1, 2, 3,
       and 4 until no new .hif entries are created during execution.

ERROR MESSAGES

  Error	messages are described in the DECmigrate User's	Guide.

  The severity levels are as follows:

  INFO
      Informational message.  Not displayed unless MXR_VERBOSE is set.

  WARNING
      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 contin-
      ues to run.

  ERROR
      Fatal error message.  Always displayed if	an error occurs.  Error	mes-
      sages cause immediate termination	of the translated program.

ENVIRONMENT VARIABLES

  The mxr environment modifies its behavior if any of the following environ-
  ment variables are set when you execute a translated executable:

  MXR_GENERATE_FEEDBACK
      Generate a .hif file to use as feedback for a subsequent retranslation.
      This is overridden by the	-nohifs	option in mx.  See the FEEDBACK	sec-
      tion.

  MXR_XTERM
      Redirect mxr input/output	through	an xterm window.  This is useful for
      separating mxr diagnostic	messages.

  MXR_VERBOSE n
      Print all	debugging output in detailed form.

      1	  Prints program header	information and	"unrecognized error tag" mes-
	  sages.

      2	  Prints program load/execute progress.

      3	  Prints program exit details and homing map.

      7	  Prints signal	details.

      8	  Prints ioctl() details.

      9	  Prints brk() details.

      10  Prints computed branch details.

  MXR_QUIET
      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.

  MXR_TRACE_SYSCALLS xxx,xxx
      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

  MXR_STATS_DISPLAY
      Display runtime statistics when the executable exits.

  MXR_TRACE_SIGNALS
      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

  /usr/shlib/mxr.so
      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.

  /usr/bin/mxr
      The runtime support for executables translated using the -script option
      in mx.

  mx.out
      The default name of the translated output	file.

SEE ALSO

  DECmigrate User's Guide