Compaq: FreePort Express User's Guide Chapter 2

User's Guide

Chapter 2: Translating and Running an Executable

This chapter describes how to translate user executables for Solaris v1.n SPARC and how to run the translations on Digital UNIX. It discusses the following topics:

Translating an executable and shared libraries

Locating and naming shared libraries

Translation problems

fpx environment variable

fpx command and options

Running the translated executable

Run-time feedback

Run-time problems

Options for the run-time environment

fpxr shell prompt commands

Arguments for the translated executable

Translating an executable

To translate an executable, follow these steps:

Determine that the executable is eligible for translation. See What kinds of executables can be translated? in Chapter 1 for the required characteristics and restrictions for input executables. The executable for the simple hello C program used in the following example meets the requirements.

Make sure that user shared libraries referenced by the executable are available in the current directory or in a directory specified by the environment variable FPX_LIBSRC_PATH. The fpx command translates referenced shared libraries if they are not translated already. Note that the original shared libraries must always be available, even if translated versions already exist. See Locating and naming shared libraries in this chapter.

Translate the executable and shared libraries by using the following command:

% fpx options executable [library [...library]]

where:

fpx is the command invoking the translator.

options are command options, listed in fpx command and options.

executable is the name of the input executable.

library is the name of a shared library for the translated executable to be linked against. See library argument for further information.

For example:

% setenv FPX_LIBSRC_PATH /usr/shlib: Specify /usr/shlib as the search path for untranslated shared libraries. fpx searches here before searching the current directory.
% fpx -o hello.alpha hello: Translate a SunOS SPARC executable called hello, and name the translated executable hello.alpha.

Locating and naming shared libraries

At the beginning of the translation, fpx determines which libraries, if any, the executable references. By default, fpx searches for translated versions first and then for untranslated versions and chooses the highest minor version-numbered library that matches the required major version number, regardless of the directory in which it is found. Even if a translated version already exists, fpx must be able to access the original user shared library. Exceptions to the default behavior apply to the libc library (see libc Library for translated executables) and to libraries specified in the command line (see library argument).

Shared library search paths

You can either rely on fpx searching in the current directory for untranslated libraries or you can use the environment variable FPX_LIBSRC_PATH to tell fpx which paths to search. If you use the variable FPX_LIBSRC_PATH, fpx searches the specified paths first. Then it looks in the current directory ("."). The following example sets the initial search path to /usr/smith/lib:


% setenv FPX_LIBSRC_PATH /usr/smith/lib

fpx uses the same search rules as the SunOS dynamic loader - it assumes the following names:

libname.so.major.minor

where:

*name*	is the library name as specified on the -l option to the ld or cc command
*major*	is the decimal number of the librar
*minor*	is the decimal minor version of the library

When fpx finds the untranslated libraries, it translates them and names them according to the following convention:

libname.so.major.minor.fpx.so

where:

name, major, and minor fields correspond to the original libraries.

libc library for translated executables

FreePort Express uses different search path rules for libc libraries. Unless you name a specific libc library in the command line, fpx uses the library libc.so.1.109.fpx.so by default. This version of libc is specially tuned for the translated environment. The following files must all be accessible in a system-defined library such as /usr/shlib:

libc.so.1.109.fpx.so
libfpxc.so.1.0.fpx.so
libfpxr

library argument

To instruct fpx to link the translated executable against one or more specific libraries, use the library command argument. The library argument takes one of the following forms:

libname	The name of the library (libdl, for example) without any version numbers. This format instructs fpx to link the translated executable against the same version of the library that the orginal executable was linked against.
libnameso.x	The library name followed by the major version number, x, and the minor version number, y. This format instructs fpx to link the translated executable against the exact library version specified.

Examples:

% fpx -o xaccount.alpha account.exe libc libdl

This command instructs fpx to translate account.exe, to name the translated version xaccount.alpha, and to link xaccount.alpha against the same libc and libdl libraries that account.exe was linked against on the SunOS system.

% fpx -o xaccount.alpha account.exe libc.so.1.7

This command instructs fpx to translate account.exe, to name the translated version xaccount.alpha, and to link xaccount.alpha against the library libc.so.1.7.

Translation problems

If the fpx command issues error messages, refer to Chapter 3, Debugging a translation, for information about debugging the problems. Appendix A, fpx command messages, provides a complete alphabetical listing of fpx messages and suggested user actions.

fpx environment variable

fpx supports the following environment variable:

FPX_LIBSRC_PATH path[:...:path]: Specifies one or more directory paths. The translator searches these paths to locate untranslated shared libraries before it searches the default paths. See Locating and naming shared libraries in this chapter.

fpx command and options

The fpx command accepts general use options and debugging and performance options . In most cases, you only need the general options. Use the remaining options to debug a translated executable or to achieve specific results.

The general use options are

-help	Display a summary of fpx command syntax and options.
*-l [filename]*	Put listing file in filename (the default is executable.lis).
-nohifs	Prevent .hif files from being generated even if the environment variable FPXR_GENERATE_FEEDBACK is set at run time. See Chapter 4, Enhancing performance.
-o outfile	Put translated executable in outfile (the default is `a.out`).
-v	Display informational and warning messages in addition to error and fatal messages. If you omit the -v option, fpx prints only error and fatal messages.
-V	Print the version of FreePort Express.
-w	Suppress warning messages.

The debugging and performance options are

-c	Translate the input executable but do not link it with its translated shared libraries.
-F	Generate conservative (slower) floating-point optimizations when there are alignment errors. See Correcting unaligned double-precision floating-point numbers in Chapter 4
-fixround	Generate a code sequence that affects floating-point rounding mode at run time so that each instance of floating-point rounding to RM (minus infinity) is changed so it rounds to RZ (zero). This may cause a slight loss of precision, but may substantially improve the run-time performance of the translated executable.
-full_fp	Translate all SPARC floating-point computations to completion-safe floating-point code on Alpha. Use when an executable runs without problems on SunOS but generates SIGFPEs at run time when translated to Alpha. Slows performance but enables executable to run correctly. See Correcting for nonfinite numbers and SIGFPEs in Chapter 4 for further explanation.
-opt_lita	Optimize the translation for a minimum number of entries in the .lita section of the Digital UNIX object file. Using this switch lowers the translated executable’s performance -- use it only if translation generates the message Too many address literals, link will fail. Please retranslate with -opt_lita.
-m	Generate a machine code listing for the input executable and its translated output. Useful when debugging with the dbx debugging tool. If a file name for the listing is not specified using the -l option, then a listing is created by default in the file executable.lis.
*-M [filename]*	Generate and keep a makefile (the default is makefile). fpx generates a makefile to direct the translation of the executable and shared libraries. Use this option to retain a copy of the makefile.
-O	Perform peephole optimizations and Alpha instruction scheduling
-O0	Do not perform optimizations.
-O1	Perform peephole optimizations.
-O2	Perform peephole optimizations and Alpha instruction scheduling. Identical to -O.

Running the translated executable

To run the executable after translation, follow these steps:

1	Make sure that the translated executable, shared libraries, and any other supporting files are available on the Digital UNIX system. If you have not already done so, rename the translated executable so it uses the same file name it used on the SunOS system. For example, rename hello.alpha to hello.
2	Set the LD_BIND_NOW environment variable to 1.
3	Use the LD_LIBRARY_PATH variable to identify the location of translated libraries if you copy them to nondefault locations. Otherwise, fpxr searches the following default system directories: /usr/shlib /usr/lib /usr/local/lib /var/shlib
4	Set whichever environment variables, listed in Options for the run-time environment, are appropriate for your needs
5	Invoke the translated executable by using the same command used to invoke it on the SunOS system. The executable invokes fpxr automatically.
6	The executable performs the equivalent functions performed on the SunOS SPARC system

For example:

% mv a.out hello: Rename the translated executable to hello - its original name on the SunOS SPARC system.
% setenv LD_BIND_NOW 1: Set the LD_BIND_NOW environment variable to 1.
% setenv LD_LIBRARY_PATH /usr/xshlib: Define /usr/xshlib as the search path for translated libraries.
% setenv FPXR_LOGFILE hello.log: Redirect fpxr output to a file named hello.log.
% hello hello, world!: Use the original name to invoke the translated executable. fpxr autmatically provides the translated executable with required run-time support.

Run-time feedback

When you run a translated executable, fpxr may need to interpret SPARC code that fpx was not able to detect at the previous translation. If you set the environment variable FPXR_GENERATE_FEEDBACK at run time, fpxr records information about the interpreted code to a feedback file. When you subsequently retranslate the original executable, fpx uses the feedback information to locate and translate the code. The next time you run the translated executable, its performance should improve because translated code is more efficient than interpreted code. See Chapter 4, Enhancing performance, for further information on run-time feedback.

Run-time problems

If fpxr displays error messages, refer to Appendix B, fpxr Run-time messages, for a complete alphabetical listing of fpxr messages and suggested user actions. Refer to Chapter 3, Debugging a translation, for debugging suggestions. If the executable runs, but slowly, refer to Chapter 3, Debugging a translation, and Chapter 4, Enhancing performance, for instructions on improving performance.

Options for the run-time environment

The fpxr environment modifies its behavior if you set any of the following environment variables before running a translated executable:

FPXR_GENERATE_
FEEDBACK Generate a .hif file to use as feedback for a subsequent retranslation. This variable is ignored if the executable was translated with the -nohifs option. See Chapter 4, Enhancing performance, for information on feedback files

FPXR_LOGFILE logfile_name Redirect all fpxr output to the specified file. This is especially useful when combined with other debugging options in environments where the terminal output needs to be undisturbed, for example, screen-based editors.

FPXR_QUIET Suppress all output related to the fpxr environment except for fatal errors.

FPXR_STATS_
DISPLAY Display run-time statistics when the executable exits. These statistics provide a snapshot of how fpxr supports the executable.

FPXR_TRACE_
SIGNALS Trace all signals and signal system calls.

FPXR_TRACE_
SYSCALLS [call[call,...]]

Trace 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 specified are traced. To prevent tracing a specific system call, begin the name with a hyphen. Separate the names of system calls with commas (,). For example, to trace several calls, enter the following:

% FPXR_TRACE_SYSCALLS
open,close,read

To trace all system calls except read and write, enter the following:

% FPXR_TRACE_SYSCALLS
all,-read,-write

If you are using either the ksh or sh shell, use the following format:

FPXR_TRACE_SYSCALLS=call,call
export FPXR_TRACE_SYSCALLS

FPXR_VERBOSE n

Print detailed information about fpxr processing. If you are using either the ksh or sh shell, use the following format:

FPXR_VERBOSE=n
export FPXR_VERBOSE

The possible values for n and associated results are as follows:

1	Print program header information, "unrecognized error tag" messages
2	Print program load/execute progress plus details above
3-6	Print program exit details and homing map plus all above
7	Print signal details plus all above
8	Print `ioctl ()` details plus all above
9	Print`brk (`) details plus all above
10	Print computed branch details plus all above

FPXR_XTERM Redirect fpxr input/output through an xterm window. Useful with FPXR_VERBOSE or FPXR_TRACE_xxx variables.

fpxr Shell Prompt Commands

You can enter the following commands at the shell prompt to obtain information about fpxr itself:

fpxr -help	Display a summary of fpxr environment variables.
fpxr -V	Print the version of the fpx command.

Arguments for the translated executable

Translation does not change the user interface for the executable. You can supply any arguments to the translated executable that are used with the SunOS SPARC version of the executable.

If you have questions about FreePort Express, send email to fpx-info@scrugs.lkg.dec.com.

Click to send feedback