11 Object File Utilities

This chapter describes how to invoke the following utilities:

The object file display utility prints the contents of object files, executable files, and/or archive libraries in both text and XML formats.
The disassembler accepts object files and executable files as input and produces an assembly listing as output. This listing shows assembly instructions, their opcodes, and the section program counter values.
The name utility prints a list of names defined and referenced in an object file, executable files, and/or archive libraries.
The strip utility removes symbol table and debugging information from object and executable files.

11.1 Invoking the Object File Display Utility

The object file display utility, armofd, prints the contents of object files (.obj), executable files (.out), and/or archive libraries (.lib) in both text and XML formats. Hidden symbols are listed as no name, while localized symbols are listed like any other local symbol.

To invoke the object file display utility, enter the following:

armofd [options] input filename [input filename]

armofd	is the command that invokes the object file display utility.
input filename	names the object file (.obj), executable file (.out), or archive library (.lib) source file. The filename must contain an extension.
options	identify the object file display utility options that you want to use. Options are not case sensitive and can appear anywhere on the command line following the command. Precede each option with a hyphen.
	--dwarf_display=attributes	controls the DWARF display filter settings by specifying a comma-delimited list of attributes. When prefixed with no, an attribute is disabled instead of enabled.
		Examples:	--dwarf_display=nodabbrev,nodline --dwarf_display=all,nodabbrev --dwarf_display=none,dinfo,types
		The ordering of attributes is important (see --obj_display). The list of available display attributes can be obtained by invoking armofd --dwarf_display=help.
	--dynamic_info	outputs dynamic linking information.
	-g	appends DWARF debug information to program output.
	-h	displays help
	-o=filename	sends program output to filename rather than to the screen.
	--obj_displayattributes	controls the object file display filter settings by specifying a comma-delimited list of attributes. When prefixed with no, an attribute is disabled instead of enabled.
		Examples:	--obj_display=rawdata,nostrings --obj_display=all,norawdata --obj_display=none,header
		The ordering of attributes is important. For instance, in "--obj_display=none,header", armofd disables all output, then re-enables file header information. If the attributes are specified in the reverse order, (header,none), the file header is enabled, the all output is disabled, including the file header. Thus, nothing is printed to the screen for the given files. The list of available display attributes can be obtained by invoking armofd --obj_display=help.
	-v	prints verbose text output.
	-x	displays output in XML format.
	--xml_indent=num	sets the number of spaces to indent nested XML tags.

If an archive file is given as input to the object file display utility, each object file member of the archive is processed as if it was passed on the command line. The object file members are processed in the order in which they appear in the archive file.

If the object file display utility is invoked without any options, it displays information about the contents of the input files on the console screen.

NOTE

Object File Display Format

The object file display utility produces data in a text format by default. This data is not intended to be used as input to programs for further processing of the information. XML format should be used for mechanical processing.

11.2 Invoking the Disassembler

The disassembler, armdis, examines the output of the assembler or linker. This utility accepts an object file or executable file as input and writes the disassembled object code to standard output or a specified file.

To invoke the disassembler, enter the following:

armdis[options] input filename[.] [output filename]

armdis	is the command that invokes the disassembler.
options	identifies the name utility options you want to use. Options are not case sensitive and can appear anywhere on the command line following the invocation. Precede each option with a hyphen (-). The name utility options are as follows:
	-a	disables printing of address along with label names within instructions.
	-b	displays data as bytes instead of words.
	-be8	disassembles in BE-8 mode.
	-c	dumps the object file information.
	--copy_tables	(aliased as -y, or -Y) displays copy tables and the sections copied. The table information is dumped first, then each record followed by its load and run data. See Example 11-3.
	-d	disables display of data sections.
	-e	displays integer values in hexadecimal.
	-h	shows the current help screen.
	-i	disassembles data sections as text.
	`-I`	disassembles text as data.
	-n	dumps the symbol table.
	-q	(quiet mode) suppresses the banner and all progress information.
	-qq	(super quiet mode) suppresses all headers.
	-r	uses raw register IDs (R0, R1, etc.).
	-R	shows run-time address if different from load-time address.
	-s	suppresses printing of address and data words.
input filename[.ext]	is the name of the input file. If the optional extension is not specified, the file is searched for in this order: infile infile.out, an executable file infile.obj, an object file
output filename	is the name of the optional output file to which the disassembly will be written. If an output filename is not specified, the disassembly is written to standard output.

When the example file in Example 11-1 is compiled, the assembler produces an object file, memcpy32.obj.

Example 11-1 Object File memcpy32.asm

            .global C_MEMCPY 
C_MEMCPY: .asmfunc stack_usage(12)

 CMP r2, #0 ; CHECK FOR n == 0
 BXEQ lr ;
 STMFD sp!, {r0, lr} ; SAVE RETURN VALUE AND ADDRESS
 TST r1, #0x3 ; CHECK ADDRESS ALIGNMENT
 BNE _unaln ; IF NOT WORD ALIGNED, HANDLE SPECIALLY
 TST r0, #0x3 ;
 BNE _saln ;

_aln: CMP r2, #16 ; CHECK FOR n >= 16
 BCC _l16 ;
 STMFD sp!, {r4} ;
 SUB r2, r2, #16 ;

As shown in Example 11-2, the disassembler can produce disassembly from the object file, memcpy32.obj. The first two lines are entered on the command line.

Example 11-2 Disassembly From memcpy32.asm

TEXT Section .text, 0x180 bytes at 0x0

000000: C_MEMCPY:

000000: .state32

000000: E3520000 CMP R2, #0

000004: 012FFF1E BXEQ R14

000008: E92D4001 STMFD R13!, {R0, R14}

00000c: E3110003 TST R1, #3

000010: 1A00002B BNE 0x000000C4

000014: E3100003 TST R0, #3

000018: 1A00002F BNE 0x000000DC

00001c: E3520010 CMP R2, #16

000020: 3A000008 BCC 0x00000048

000024: E92D0010 STMFD R13!, {R4}

000028: E2422010 SUB R2, R2, #16

Example 11-3 provides an example of how the output would appear if a copy record refers to different load and run sections and the --copy_table option is used.

Example 11-3 Partial Copy Record Output With Different Load and Run Address

     COPY TABLE: _data2_ctbl, 0x30 at 0x5E10, 1 record(s)

 _data2_ctbl[0]: load addr=0x200158, size=0x12B, encoding=lzss

 DATA Section .data2_scn.load, 0x12B bytes at 0x200158
 200158: $d:
 200158: 020f0000 .word 0x020f0000
 20015c: beef0003 .word 0xbeef0003
 .
 .

 _data2_ctbl[0]: run addr=0x52A0, size=0x960

 DATA Section .data1_scn, 0x960 bytes at 0x52A0
 0052a0: data1:
 0052a0: $d:
 0052a0: .data1_scn:
 0052a0: 0000beef .word 0x0000beef
 0052a4: 0000beef .word 0x0000beef
 .
 .

11.3 Invoking the Name Utility

The name utility, armnm, prints the list of names defined and referenced in an object file, executable file, or archive library. It also prints the symbol value and an indication of the kind of symbol. Hidden symbols are listed as "".

To invoke the name utility, enter the following:

armnm [-options] [input filenames]

armnm	is the command that invokes the name utility.
input filename	is an object file (.obj), executable file (.out), or archive library (.lib).
options	identifies the name utility options you want to use. Options are not case sensitive and can appear anywhere on the command line following the invocation. Precede each option with a hyphen (-). The name utility options are as follows:
	-a	prints all symbols.
	-f	prepends file name to each symbol.
	-g	prints only global symbols.
	-h	shows the current help screen.
	-l	produces a detailed listing of the symbol information.
	-n	sorts symbols numerically rather than alphabetically.
	-o file	outputs to the given file.
	-p	causes the name utility to not sort any symbols.
	-q	(quiet mode) suppresses the banner and all progress information.
	-r	sorts symbols in reverse order.
	-s	lists symbols in the dynamic symbol table for an ELF object module.
	-u	only prints undefined symbols.

11.4 Invoking the Strip Utility

The strip utility, armstrip, removes symbol table and debugging information from object and executable files.

To invoke the strip utility, enter the following:

armstrip [-p] input filename [input filename]

armstrip	is the command that invokes the strip utility.
input filename	is an object file (.obj) or an executable file (.out).
options	identifies the strip utility options you want to use. Options are not case sensitive and can appear anywhere on the command line following the invocation. Precede each option with a hyphen (-). The strip utility option is as follows:
	-o filename	writes the stripped output to filename.
	-p	removes all information not required for execution. This option causes more information to be removed than the default behavior, but the object file is left in a state that cannot be linked. This option should be used only with executable (.out) files.
When the strip utility is invoked without the -o option, the input object files are replaced with the stripped version.