TOCPREVNEXTINDEX

Lund Performance Solutions

The AVATAR Tool
AVATAR’s decompiler capabilities include the ability to find, view, and modify the contents of any Native Mode program file, object file, executable library, or relocatable library. The AVATAR command set includes a variety of commands that simplify tasks like disassembling and modifying program files. Other features are geared towards deciphering header information in executable libraries and extracting portions of code into assembly language source.
Warning: AVATAR was designed to be used by experienced software engineers. In terms of how it is used, AVATAR is very similar in feel to Hewlett-Packard’s DEBUG. Therefore, if you are not comfortable using DEBUG you will not be comfortable using AVATAR. Proceed at your own risk, exercising appropriate caution.
AVATAR is more effectively used if you understand the following concepts:
  • HPPA assembly language
  • Procedure calling
  • Parameter passing conventions

    • Operation

    The primary use of AVATAR is to perform operations on SOMs. A SOM is a file that conforms to HP’s Standard Object Module conventions. There are four classes of files with which AVATAR is particularly familiar. Each of these four classes is easily identified by its filecode:

    NMPRG
    Native mode program files
    NMXL
    Native mode executable libraries
    NMRL
    Native mode relocatable libraries
    NMOBJ
    Native mode object files

    In addition to working on the file classes listed above, AVATAR can also be used as a binary editor to display and modify most other MPE files.
    When AVATAR is used as a decompiler, its output is displayed as assembly language and hexadecimal constants. To add symbolic information about register usage to the disassembled display, use AVATAR’s SYN command.
    A complete description of the assembly language can be found in HP’s Precision Architecture and Instruction Reference Manual. Another useful manual is HP’s Procedure Calling Convention Reference Manual, which describes how the general registers and stack frame are set up for procedure calls. Use the CSEQ tool to display the calling sequences for MPE intrinsics.
    After starting AVATAR, the AVATAR: prompt will be displayed. The next step is usually to OPEN a file. At that point, commands are entered to accomplish the task at hand. The general form for entering commands is:
    AVATAR: <command> [<expression>]
    The sections that follows describe the syntax and usage for all of AVATAR’s commands as well as the structure of an expression.

    Capabilities

    Program capabilities required include IA, BA, PM, DS, and PH. PM is required to run DEBUG.

    Usage

    AVATAR can be started from the supplied UDC or from a RUN statement. AVATAR does not use the INFO string or PARM.
    To start AVATAR, use one of the following methods:
  • UDC
    • :AVATAR
  • RUN
    • :RUN AVATAR.PUB.LPSTOOLS

    Expression Structure

    Expressions are used in many of the commands.
    Syntax:
    <expression> ::= <term> [ + | - <term> ]
    <term> ::= <factor> [ * | / <factor> ]
    <factor> ::= [ + | - ] <primary>
    <primary> ::= [ <expression> ]
    [` <assembler instruction> `]
    [ <number> ]
    [ SOM_HEADER ]
    [ LST_HEADER ]
    [ AUX_HEADER ]
    [ SPACE_DICT ]
    [ SUBSPACE_DICT ]
    [ LOADER_FIXUP ]
    [ SPACE_STRINGS ]
    [ INIT_ARRAY ]
    [ COMPILER_DICT ]
    [ SYMBOL_DICT ]
    [ FIXUP ]
    [ SYMBOL_STRINGS ]
    [ UNL_SPACE ]
    [ PROCTIME ]
    [ <symbol> ]
    [ " <symbol> " ]
    <assembler instruction>
    Is a valid assembler instruction. The instruction is enclosed in back-quotes.
    <number> ::=
    [ $ <hexadecimal digits> ]
    [ % <octal digits> ]
    [ # <decimal digits> ]
    [ <digits in current radix> ]
    <symbol>
    Is the value of any symbol defined in the current SOM. If the symbol is not enclosed in quotes, then it can not be one of the previously defined words (i.e. PROCTIME) and it can only contain characters from the set 'A'..'Z', 'a'..'z', '0'..'9', '_', '$', '#', '%'.
     
    If the name of the symbol is preceded with a ? then the value of a stub with that name is used.
     
    Strings are also used in many commands. Strings can be given as a simple string or as a compound string. A simple string is 'zero or more characters enclosed in double-quotes'. A compound string is a list of substrings, enclosed in braces ({}). A substring can be a string enclosed in double-quotes or a number representing the value of one byte. Example: "This is a string", while {"This is a string with a new-line character" $a}.

    Foundation Topic Discussions

    This section discusses concepts and terminology that you may find helpful in understanding the information presented about AVATAR. First, a brief background section introduces Standard Object Modules (SOMs), and then assembly language and mapped files are discussed in relation to how they are used in AVATAR.

    Standard Object Modules

    Standard Object Modules are the smallest unit which may be generated by a compiler. They correspond to a given order, regardless of the file type. For instance, the architecture of an NMPRG begins with header and procedural information that is important to the operating system. After this, data and code segments follow.
    A set of SOMs is defined as a library which may be either executable (NMXL) or relocatable (NMRL). Each library will contain library symbol table (LST) that describes its contents in terms of SOMs.
    Relocatable libraries contain one or more SOMs that must be linked (using LINKEDIT) with the SOM that references it. Executable libraries contain one or more SOMs that have already been linked and are ready to execute. The SOMs in an executable library are dynamically loaded by MPE/iX when referenced.
    Multiple SOMs can be stored in an object file, an executable library or a relocatable library. Once procedures are bound into a single SOM, they cannot be separated. AVATAR provides the capability to patch the assembler code of your compiled program. This means you now have the ability to support discontinued programs that may be important to your business or patch those almost-perfect programs when your vendor’s bug priority list doesn’t quite coincide with yours.
    A SOM can contain many procedures that have been combined into a single SOM. Normally, once a set of procedures has been combined by a compiler into a SOM, they are not easily separated from the SOM. AVATAR’s EXTRACT command breaks the SOM out into a separate ASCII file in assembler format that can be edited and assembled.

    Assembly Language

    Hewlett-Packard’s Precessions Architecture Assembly Language is a symbolic, more approachable, representation of MPE/iX machine language. Familiarity with assembly language may prove helpful in understanding AVATAR’s output, capabilities, and features.

    Mapped Files

    "Mapped Files" refers to the virtual address space used by files. This gives the operating system direct reference to all types of information in a manner that is reminiscent of disk-caching. Every byte of every opened file ha a unique virtual address. Portions of files are brought into real memory on demand, leaving behind other portions that are not yet required.

    NOTE Use the KLONDIKE tool from the System Manager’s Toolbox to view how much of a file is in real memory.

    MPE/iX’s treatment of virtual memory brings efficiency and flexibility to memory management that was non-existent with MPE V.

    Command Summary

    The following list provides a simple description of AVATAR commands that you can use to quickly locate the command that suits the task at hand. Detailed information on each command is provided in the next section.

    NOTE Portions of the Command Codes are printed in uppercase to denote the part of the command that AVATAR requires in order to distinguish one command from another. The commands themselves are not case-sensitive.

    Table 3.1 AVATAR Commands
    Command Code
    Description
    =
    Calculates a value from an expression
    ASM
    Shows the machine code for an assembler instruction
    AUX
    Prints the auxiliary headers
    CALCulate
    Evaluates an expression and displays the result
    CALLee
    Lists all calls to a given object from a code range
    CALLS
    Lists all call objects from a code range
    CHecksum
    Computes a new SOM checksum value
    CLose
    Closes a SOM file
    COmpiler
    Displays compiler information
    COUnt
    Counts all symbol types
    DC
    Displays data at a code address
    DD
    Displays data at a data address
    Debug
    Enters the system debugger
    DIsasm
    Shows the assembler instruction for a binary machine code
    DP
    Displays data starting at a procedure
    DR
    Displays real memory, use with extreme caution
    DV
    Displays data at a file offset
    Exit
    Terminates AVATAR
    EXtract
    Extracts a portion of code into an assembler source file
    Find
    Finds a symbol in the current SOM
    FINDAll
    Finds a symbol in all SOMs in the current SOM file
    FIXup
    Displays fixup information
    FORMAT
    Format data at a file offset
    HELP
    Invokes AVATAR help
    Init
    Displays initialization record information
    Look
    Looks at a symbols attributes
    LSt
    Lists all module names in SOM
    MC
    Modifies data at a code address
    MD
    Modifies data at a data address
    MV
    Modifies data at a file offset
    Next
    Displays more data, after a DC, DD, DP or DV command
    Open
    Opens a SOM file for processing
    Quit
    Exits the program
    Radix
    Changes the default radix
    Search
    Search for a value in the SOM file
    SPace
    Displays space header information
    STatistics
    Displays SOM file statistics
    STRIP
    Remove symbolic information from SOM
    SUbspace
    Displays subspace header information
    SYMFormat
    Format options for SYMOS information display
    SYMOpen
    Opens a SYMOS file for examination
    SYn
    Sets up synonyms for registers
    UNCALLED
    Displays entry points that are never called
    UNWIND
    Displays unwind descriptors
    Most commands may be abbreviated somewhat.
    Although most of the AVATAR commands require that a SOM file be open, the DV and MV commands can be used after OPENing any kind of file.

    Command Definitions

    This section describes AVATAR commands in detail.

    =

    This command has the following syntax:
    = <expression>
    The equal sign (=) operator when followed by an expression can be used to calculate the value of the expression.
    Example 1: = 5+3
    Example 2: = ’nop’

    ASM

    This command has the following syntax:
    ASM <assembler instruction>
    The ASM (assemble) command shows the binary machine code for an assembler instruction.
    <assembler instruction> = a valid assembler instruction.
    Example1: ASM ldo 1(0),31
    Example 2: ASM bl $$lr_unk_unk,31

    AUX

    The AUX command prints all the auxiliary headers from the current SOM. The format will depend on the actual header type of each header. Each auxiliary header is constructed of 6 fields:

    MANDATORY
    The MANDATORY field is used to indicate if this SOM contains information that the linker must understand.
    COPY
    The COPY field is used to indicate that this auxiliary header should be copied without change to any new SOM created from this SOM.
    APPEND
    The APPEND field is used to indicate entries with the same TYPE and APPEND fields should be merged together.
    IGNORE
    The IGNORE field is used to indicate this auxiliary header should be ignored if its TYPE field is unknown.
    TYPE
    The TYPE field is a numeric field that is used to describe the contents of this auxiliary header. The list of known values are provided next.
    LENGTH
    See the following table.

    Known values for the Type field are shown in the following table:
    Table 3.2 TYPE field values
    Value
    Meaning
    Associated Auxiliary Header
    0
    NULL
     
    1
    LINK information
    LINK aux header
    2,7
    HP Program
    HP Program aux header
    3
    DEBUG
    DEBUG aux header
    4
    HP-UX aux header
    HP-UX aux header
    5
    IPL aux header
    IPL aux header
    6
    User string aux header
    User string aux header
    8
    SOM
    HP SOM aux header
    The LENGTH field contains the number of bytes in the auxiliary header less 4 bytes.
    Auxiliary Header Definitions
    The various headers that can be used with the AUX command are described below:

    LINK
    This auxiliary header is used to record the last time the linker modified the SOM. The four elements in this header include:
    aux header id
    linker version id
    linker product id
    link time
    HP Program
    This auxiliary header contains information that is used by the operating system to load an executable. The seven elements in this header include:
    aux header id
    unsat names
    capabilities
    max stacksize
    entry name
    search list
    max heapsize
     
    DEBUG
    This auxiliary header is used to record the last time that the debugger modified the SOM. The four elements in this header include:
    aux header id
    debugger version id
    debugger product id
    debug time
    HP-UX
    This auxiliary header contains information that is used by the UX loader. The eleven elements in this header include:
    aux header id
    execute code size
    execute code offset memory
    execute code offset SOM
    execute data size
    execute data offset memory
    execute data offset SOM
    execute uninitialized data size
    execute start entry
    execute initialized data
    execute loader flags
    IPL
    This auxiliary header contains information that is used for loading bootable utilities. The six elements in this header include:
    aux header id
    physical address destination
    bbs size
    file length
    entry offset
    checksum
    User String
    This auxiliary header is used to store user definable strings. Typically the user-definable strings are defined through compiler directives like VERSION and COPYRIGHT. The three elements in this header are:
    aux header id
    string length
    string