Compaq: FreePort Express User's Guide Chapter 1

United States

| About AMT

Migration Tools
FX!32
FreePort Express
Download
Quick Start
User's Guide
White Papers
DECmigrate

| Performance Tools
| Documentation & White Papers

User's Guide

Introduction |Translating | Debugging | Performance | fpx messages | fpxr messages

Chapter 1: Introducing FreePort Express

FreePort Express converts user executables for Solaris v1.n SPARC into functionally equivalent executables that run on Compaq's Tru64 UNIX.

Why use a SPARC to Alpha binary translator?
What kinds of executables can be translated?
Translation criteria
What are the translator components?
How does the translator work?
What are the hardware and software requirements?
Requirements to translate executables
Requirements to run translated executables

Why use a SPARC to Alpha binary translator?

Translating user applications for SunOS SPARC is a simple way to migrate them immediately. It provides robust performance now and introduces you to 64-bit computing on Alpha systems - systems that can expand to meet all your future computing needs. FreePort Express provides the following features:

Works like a compiler

The translator takes a user binary executable for SunOS SPARC as a source file and creates a Digital UNIX binary executable as the output file. It converts the SPARC executable directly into Alpha code - an executable that runs on Digital UNIX immediately. The translation takes minutes and requires only the binaries, any shared libraries on which they depend, and the translator.

Adjusts for the differences between the Alpha and SPARC architectures. | The translator automatically handles the changeovers from a 32-bit to a 64-bit architecture and from a big-endian to a little-endian architecture.
Provides you with flexibile porting options. | The translator allows you to run your SunOS SPARC user applications on Alpha systems while you port the source code. Or you can run translated applications indefinitely if the source code is not available.

Moves you to Alpha now

Alpha is a 64-bit architecture capable of expanding to meet your future computing needs. Following Digital's lead, most computer manufacturers are developing 64-bit-based systems, an acknowledgment that 64-bit addressing is essential to the future of computing.

What kinds of executables can be translated?

FreePort Express translates any nonprivileged user executable that runs on SunOS Version 4.1.n (Solaris Version 1.n), which includes both static and dynamic executables, as well as shared libraries. This description applies to nearly all application programs that run on SunOS Version 4.1.n, including programs that use Xview, Open Look, Motif, and all X11-based window managers. The section Translation criteria summarizes the criteria for executables that you can and cannot translate. Limitations for particular versions of the translator appear in FreePort Express Release Notes.

NOTE: FreePort Express should only be used to translate software that the user has the right to copy, translate and use on an Alpha system. The user is solely responsible for adhering to the provisions of any license(s) pertaining to software translated using FreePort Express.

Translated code provides good performance, but ported code is better still. In most cases, your better long term option is to port your application source code. Even so, translating an applicaton may be the only way to migrate it to Digital UNIX. Consider translation in the following instances:

| When the application sources are not available
| When the appropriate compiler for those sources is not available
| When recompiling the source code for a 64-bit environment introduces errors
| When software components assume that pointers and integers are always 32-bits wide

In the last case, FreePort Express accommodates such assumptions even when it is difficult to do so in the source code.

####
Translation criteria

You can translate if the executable:

| Uses SunOS Version 4.1.n
| Is written in user mode
| Is nonprivileged
| Is a binary executable
| Is an executable with an a.out header

You cannot translate if the executable:

| Is built for SunOS versions before Version 4.1
| Does not work on the native system
| Uses extensions to the SPARC instruction set
| Is an operating system
| Uses the SunView window system
| Is a driver or uses privileged opcodes or system calls
| Uses system calls unsupported on Digital UNIX (see the FreePort Express Release Notes)
| Uses registers %o7 through %i7 to examine SPARC code stream
| Reads /dev/mem or /dev/kmem
| Relies on the SunOS file system hierarchy or SunOS system file formats where they differ from Digital UNIX file system hierarchy or system file formats
| Uses Sun specific ioctl interfaces to control Sun display hardware

What are the translator components?

Translation tools and support for translated executables on Digital UNIX systems include

fpx

The fpx command accepts a user executable for SunOS SPARC as input, determines which shared libraries also need translation, analyzes the executable and shared libraries to locate SunOS SPARC code, and then creates a translated executable for Digital UNIX. The fpx command supports two sets of options. One set is for general use - these options specify input and output file names and request or suppress information. The other set is for special cases - these options affect translation or run time or help you debug a translated executable. For example, you can manipulate how the translator handles floating-point computations. See Chapter 2, Translating and Running an Executable, for instructions on how to use the fpx command and options.

fpxr | The fpxr run-time environment provides run-time support for translated executables. The fpxr routines are provided from a shared library (by default) and supply the translated executable with any resources it requires to run. For example, fpxr maintains the SPARC system context within which the translated code runs and interprets untranslated SPARC code encountered at run time. To control fpxr behavior, you can set one or more environment variables. For example, you can set environment variables that enable fpxr to provide feedback on how the translated executable performs. See Chapter 2, Translating and running an executable, for instructions on how to run a translated executable. See Chapter 4, Enhancing performance, for information about using fpxr feedback.

How does the translator work?

FreePort Express translates user executables and shared libraries for SunOS SPARC into functionally equivalent executables that run on Digital UNIX. Initially, the translator determines which shared libraries the executable needs and checks that they are available. If necessary, the translator converts the shared libraries as well as the executable itself. Checking for shared libraries is similar to a compiler checking for the files on which the source code depends. When translation is complete, the translator creates a Digital UNIX executable that is functionally identical to the original SunOS version. Here is a brief explanation of how the translator works:

Locating and translating required user shared libraries | The translator first examines header information in the input executable to identify any user shared libraries on which it depends. For each dependency, the translator searches for a translated version of the user library. If none is found, it searches for the untranslated user library and translates it into its Digital UNIX equivalent. The translator also creates an image information file (.iif file), which provides information about the library's entry points.

Locating SPARC code

The translator's objective is to locate as much code as possible because fpxr must interpret any untranslated code it encounters at run time. Interpreting code is much less efficient than executing translated code. To find code, the translator analyzes the input executable in two passes to:

| Find entry points.
| Separate the code and data.
| Abstract the code to an intermediate representation.
| Trace the program flow for later code optimizations.
| Detect anomalies that cannot be reproduced correctly on the Alpha system.

During pass 1, the translator searches for and reads the .iif file for every shared library that the input executable references. The translator also searches for a .hif file for the input executable itself. If the executable was translated and run on Digital UNIX previously, fpxr may have created a .hif file to record information about any code it had to interpret. (See the section Enhancing performance by repeating translation in Chapter 4.)

During pass 2, the translator goes back over the executable and tries to parse and translate portions of the executable that did not yield code during pass 1.

Generating Code | The translator converts the code it located into translated code and creates a Digital UNIX executable that contains both the translated code and the original SPARC executable. By default, the translated executables are in COFF format, the native format for executables compiled and linkedon Digital UNIX.

On the Alpha system, the fpxr run-time environment starts up automatically when you run the translated executable, which reproduces the behavior of the original program. In many cases, you can improve performance by retranslating the original executable with different fpx options or retranslating with information obtained at run time. You can also use the dbx tool to debug a translated executable.

What are the hardware and software requirements?

Translating executables and running the translated executables on Digital UNIX are separate operations with separate requirements.

Requirements to translate executables

FreePort Express requires an Alpha system running Digital UNIX Version 3.0 or later. Translation can require memory that is up to 40 times the size of the program text. For example, translating a 3MB executable requires a peak of about 120MB of virtual memory. Specific requirements depend on the executable being translated.

Make sure fpx can access any user shared libraries the executable needs. (See the section Locating and naming shared libraries in Chapter 2.) When fpx translates an executable, it identifies the user shared libraries used by the executable and translates them too, if they are not translated already.

Requirements to run translated executables

The run-time environment, fpxr, which is part of the FreePort Express software kit, must be available on the Alpha system. The Digital UNIX operating system must be Version 3.0 or later. Memory requirements depend on the executable that is running. The virtual memory requirements for the fpxr run-time environment are

virtual memory =
  virtual memory used by the original program +
  memory for the translated code +
  memory for the fpxr environment

The required virtual memory for the translated program itself is estimated as

virtual memory =
  virtual memory for the original program +
  virtual memory 2.4 times the size of the original program's text sections.

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

| Click to send feedback

privacy and legal statement