Log In | Not a Member? | Support | |
SYNTAX
DumpXCOFF xcoffObjFile… [-a[nnotate] {-v[erbose]}] [-c[heck]] DESCRIPTION The DumpXCOFF tool validates and displays the contents of XCOFF files, with each section appropriately formatted and each field annotated according to section type. The .text (code) section is shown as disassembled POWER, PowerPC 601, 32-bit PowerPC, or 64-bit PowerPC assembler instructions. For the PowerPC 601, a special check (-w601) can be enabled to issue a warning when POWER instructions are used as opposed to PowerPC instructions. Any or all sections can be selectively displayed. The validations check all fields that can be reasonably checked. Errors and warnings are reported as part of the standard output. If you specify the -check option, only the validations are performed, without generating any output (errors or warnings resulting from incorrect fields are reported). INPUT XCOFF object files (xcoffObjFile). DumpXCOFF does not read standard input. If no input files are specified, DumpXCOFF displays help information. OUTPUT DumpXCOFF writes the formatted object file structures and disassembled code to standard output. STATUS
DumpXCOFF can return the following status codes:
PARAMETERS xcoffObjFile Specifies one or more XCOFF object files to display. OPTIONS The option descriptions are grouped into the following functional categories:
IMPORTANT These are the main control options that determine what DumpXCOFF processes. -c[heck] Checks (validates) only. All output to the standard output is suppressed. Only errors and warnings, if any, are reported to the diagnostic output. -do all | optLetters
Processes the specified XCOFF sections. You specify either all
or selected sections using one or more of the following options (optLetters):
-n[ames] spec Lists only symbol table or loader section symbols. If this option is specified, the -do option is ignored. The spec parameter specifies which symbols are to be listed and from which section, using the following syntax (the parentheses and braces are part of the syntax): keyword[(csectType)][{csectClass}] or keyword[,csectType][,csectClass]
where
Notes: [1] Specifying all displays all the symbol table names while allLdr displays all the loader section symbol names.
[2] Symbol table storage classes are the standard storage class names defined by XCOFF. The following symbol table storage class names are currently used in XCOFF object files:
The classes C_EXT and C_HIDEXT are treated together in that specifying one implies the other.
[3] The following Csect types are accepted:
[4] The following Csect storage classes are accepted:
[5] Specifying functions is a special case for possible function names. These are entries that are either C_EXT(LD){PR} or C_EXT(SD){PR} for a function (technically, a Csect with a function auxiliary entry). [6] Loader symbol table entries are indicated by specifying one of the identifiers Imp[ort], Exp[ort], or Ent[ry]. Combinations of these are indicated by combining these words with a bar (|) or ampersand (&). [7] The -section option can be used to further qualify the listed names to only those associated with the specified section. [8] In MPW and UNIX, bars have special meaning. In addition, in MPW, braces also have special meaning. Quoting is therefore necessary if the full syntax is used. The alternate syntax, using all commas and ampersands, is provided to get around these limitations. You can define an MPW Shell variable to give the appearance of using the full syntax. For example, if PR is defined as '{PR}' (including the quotes), then {PR} alone can be used in the syntax. -powerOpen Enforces compliance with the XCOFF format as defined by the PowerOpen PowerPC Application Binary Interface (ABI) instead of AIX. The ABI specifies additional or different meanings for some fields and different value ranges for others. Specifying this option causes the validations to be done according to the ABI instead of AIX. -sect[ion] s Limits section processing to section s. The section may be specified either as a number if it is known or a section name (for example, .text, .data, .bss, and so on). This option acts as an additional qualifier to the -do option for section-oriented portions of the XCOFF file by limiting processing to only the specified section. This includes the section headers, raw data sections, relocation information, line number information, and symbol table entries. This option also limits the -names listing of symbol table entries to only those symbols belonging to that section. For example, if -do all is specified with -section .text, then in addition to the main and auxiliary header (both of which are not associated with any one section), only the section header, .text raw data section, its relocation and line number information (if any), and all symbols in the symbol table that reference the section are displayed. In other words, everything dealing only with the .text section. Note that specifying -section .text with -do t is redundant since -do t effectively implies processing of only the .text section. However, since -section is an additional qualification, if -section .data is specified along with -do t, no output is generated. In summary, the main uses for -section are with -do all and with the -names option. These options control how the disassembly of the .text code section is processed. -dialect cpu[,vec[tor]] Sets the disassembly dialect to cpu, where cpu is one of the following: Power {Pwr} RS/6000 POWER architecture PowerPC601 {PPC601} PowerPC 601 architecture PowerPC32 {PPC32} 32-bit PowerPC architecture PowerPC64 {PPC64} 64-bit PowerPC architecture vec[tor] vector extensions Except for vector, only one cpu can be specified. Vector may be combined with any of the others (except Power) separated by a comma or used alone when specifying the default dialect. When vector is specified, AltiVec instructions will be disassembled instead of being treated as illegal instructions. A 'V' flag will appear in the flags column to indicate AltiVec instructions. -format {-fmt} fmtParams[,fmtParams]… Changes the default disassembly formatting options. The fmtParams parameter uses the following syntax: on=fmtOptions | off=fmtOptions
Where fmtOptions is one or more of the following characters:
-i dirPath1[,dirPath2] … Performs "interlisting." That is, DumpXCOFF inserts the original source text lines into the disassembly at the point corresponding to their generated code. The option also specifies all the directories in which to search for the source files. Use the colon character (: ) to indicate the current directory. Your XCOFF file must include line number and filename information in order for DumpXCOFF to correlate source lines with their resulting code. The XCOFF filename information specifies all the source files used to generate the XCOFF file, that is, the main input file and all included files. Because DumpXCOFF always strips out any directory path information from the source filenames contained in the XCOFF file, you must specify one or more directory paths describing the location of all source files referenced by the XCOFF file. DumpXCOFF searches each directory path (dirPath) specified by the -i option (in the order specified) to find the source files. If a file cannot be opened, no error is given. Instead, only the filename and line number information is shown exactly as if the -ln option were used. The only message that may appear is a warning that a source file is "newer" than the object file being used. Further, no interlisting can be performed if the XCOFF file does not contain line number information. -ibm Formats the disassembly using IBM Assembler conventions for comments and directives. The default is to use Apple PowerPC Assembler conventions. Using this option, comments are introduced with a pound sign (#) instead of a semicolon (;), and directives (Csects, data definitions, and so on) use the IBM format (for example, .long instead of dc.l). -ln Shows file and line number information in the disassembly for the lines that generated the assembly code that follows. The lines are generated in the following format: File "filename"; Line n You can execute these commands in the MPW Shell to quickly locate particular source code lines, as long as the target filename is in the current directory. Note that this option provides a simplified form of the interlisting performed by the -i option. But if this is all the information you need, the -ln option offers considerably faster execution times. -only name1[,name2]… Disassembles only the specified function names. These are symbol table names corresponding to C_EXT and C_HIDEXT section definitions (SD). The specified name must match exactly the symbol table names. You can use the -names functions option to find out how the names are spelled. The name generated by the compiler is usually not exactly the same as the original source name, especially in the case of C++. -notracebacks {-ntb} Specifies that there are no traceback tables in the code. Normally, an all zero instruction, or the location defined by a C_FCN ".ef" (under certain conditions) defines where the traceback table begins. If you know there are no traceback tables in the code, use this option to indicate that all data is to be interpreted as instructions and disassembled. Without this option, if DumpXCOFF encounters data that appears to be a traceback table, it interprets it as such. If the data is not a traceback table, the output may be confusing. -tb Displays traceback tables appropriately formatted and annotated. Normally the display of the traceback information is suppressed. Use the -notracebacks option if you know there are no tracebacks in the code.
Loc Flags Object Code Label Opcode Operand Comment 0134 0200 csect .__start{PR} ; [0] 0134 0200 82420000 lwz r18,_adata{TC} ; 0x00000202 0138 0204 80F20008 lwz r7,0x0008(r18) 013C 0208 X 39000000 li r8,0 0140 020C 91070000 stw r8,0x0000(r7) 0144 0210 81320000 lwz r9,0x0000(r18)
The Flags column displays additional information about the instructions. The following flags are defined:
-a[nnotate] {-v[erbose]} Annotates every XCOFF data field with information appropriate to that field. This annotation, while more informative, causes much more output than the default format. The default format provides most of the same data but annotates it more briefly and displays it in a wider format. The -annotate format is narrower. -m[ark] Generates MPW Shell markers on each title in the output and also the TOC anchor. There is no restriction on the standard output file (that is, it can be an open window) other than the fact that markers are not generated for the output file if that output file is also the window from which you initiated the DumpXCOFF command.
Note -markfuncts {-mf} Same as -mark except that markers are also generated for function labels in the .text code disassembly. -maxlines n Limits all section displays (except the main, auxiliary, and section headers) to n lines. Only the first n lines of each section are displayed and processed. -o[ffsets] Suppresses the display of the XCOFF file offsets. The default is to show the file offsets at the left edge of the output for every field displayed. -u[nmangle] Unmangles C++ names. DumpXCOFF attempts to unmangle symbols from the symbol table or the loader section symbol table. This option should only be used if the XCOFF file is from a C++ compiler. -w Suppresses warnings. Only error messages, if any, are shown and counted (for the summary). -w601 Generates explicit warning messages about the use of POWER instructions and PowerPC 601-specific SPRs when the -dialect PowerPC601 option is specified and the .text code section is disassembled. The default is to generate a flag in the disassembly (see the description of the -tb option), but these instructions are always counted to report in the summary that POWER instructions were used. Use this option to find where these instructions exist in the file and what they are, since the disassembled line is always shown with the warning. -cache on | off Enables (on) or disables (off) headers, symbol table, symbol string table, and .debug section string caching. By default, DumpXCOFF caches these items for speed efficiency, particularly during .text and .data disassemblies. The cost is increased memory usage. By turning the cache off, memory requirements are lower, but execution time increases. See the Limitations section for more information. -h {-?} Displays a brief summary of DumpXCOFF options. This option overrides all other options. The help information is also displayed if no XCOFF object files are specified on the command line. -p Writes the version and progress information to the diagnostic output file. This option is useful for large XCOFF files. See the Limitations section for more information. -summarize Displays a summary of the results of processing each file. The summary is sent to the diagnostic output and is always generated if any errors or warnings are reported. -y Prevents the audible warning sound (system beep) that normally occurs when the summary indicates there were POWER instructions used with the -dialect PowerPC601 option specified. -z c Defines the pathname separator character. The default is the colon (:), which is correct for the Macintosh. UNIX systems use the slash (/). When either the -i or -ln options are used, the directory path (if any) prefixing a filename in the symbol table is removed. For the -i option, the directories specified for that option define the search path that DumpXCOFF uses to locate the file. For the -ln option, the filename is simply displayed. DumpXCOFF requires the pathname separator character in order to remove the pathname. For object files generated and displayed in the Macintosh environment, the default is correct and you do not need to specify this option. To display XCOFF object files that were generated in another environment (for example, AIX) you must specify the pathname separator character. EXAMPLES The default options assume the PowerPC 601 dialect, process the headers and disassemble the .text, .data, and .bss sections. The disassembly uses extended mnemonics where it can, and signed immediate and field values are shown in decimal. The command below processes the file moof.o according to the default options. DumpXCOFF moof.o >moof.xcoff This is identical to the following command: DumpXCOFF moof.o -dialect PowerPC601 -do htdb -fmt on=xsf >moof.xcoff In the example below, only the .text section is processed and disassembled. MPW Shell markers are placed on the titles and each function label in the output file, moof.xcoff. DumpXCOFF moof.o -mf -do t >moof.xcoff The following command displays all the function names in the .text section according to the symbol table. DumpXCOFF moof.o -names functs -section .text Assuming one of the names from the previous example was .moof, the following example illustrates how to disassemble only .moof along with its traceback table. DumpXCOFF moof.o -do t -tb -m .moof >moof.xcoff The command below processes the entire file (-do all) for validation purposes only (-check). If there are any errors or warnings, they are written to the diagnostic file. No standard output file is generated. DumpXCOFF moof.o -check -do all The following command checks the .text code section to see if there are any POWER instructions in it, and generates warnings if there are. The POWER instructions are also shown along with the XCOFF file offset where they occur. DumpXCOFF moof.o -c -w601 -do t LIMITATIONS • DumpXCOFF is used primarily for debugging compiler or linker output. If you are generating output (that is, the -check option is not specified) for a large file, you may want to use the -maxlines option to limit the amount of output, which is potentially large. • Some PowerPC instructions take an rA parameter, used as the base for calculating an effective address. The rA parameter can be either 0 or r1-r31. The PowerPC Disassembler library mistakenly displays the value of 0 as r0 in these cases. This does not reflect on the correctness of the underlying code, because both 0 and r0 are represented by a zero at the instruction level, but it could be confusing when you are using DumpXCOFF.
• Unless you specify -cache off, DumpXCOFF
attempts to cache the section headers, symbol table, symbol string table, and .debug
section strings the first time it needs any of these items. This is done for speed efficiency, because DumpXCOFF
generally seeks (and reseeks) all other information directly from the XCOFF file. • The disassembly analysis tables require additional memory to annotate the disassembly. The memory requirement is, conservatively, about two times the size of the largest .text or .data section to be processed. If you use the -maxlines option, the requirement is about eight times the number of lines. • Label and Csect information in disassemblies is determined from information derived from the XCOFF symbol table. The start of traceback tables is determined by either the presence of an all-zero instruction or XCOFF symbol table C_FCN ".ef" (end of function) entries. XCOFF files generated by most of the language compilers follow uniform code generation conventions (for example, code and data are kept separate; tracebacks, if any, appear only at the ends of functions) and define all the appropriate XCOFF symbol table entries necessary for DumpXCOFF to do a reasonable job in disassembling. However, for assembler-generated XCOFF files, the only rules imposed are those used by the assembler programmer. Local labels, which might indicate the beginning of local functions, embedded data, and so on, may not be identifiable because there are usually no XCOFF symbol table entries. DumpXCOFF may not produce useful results from such XCOFF files. The best that can be suggested for this case is to use the -ntb option to suppress all traceback detection. This is appropriate if you know there are no tracebacks or there is embedded data with the value 0x00000000. This stops DumpXCOFF from trying to process as a traceback table the actual data that happens to start with 0x00000000. Unfortunately, the data is then interpreted as code and may produce unexpected results or "invalid instruction" messages.
• DumpXCOFF
does not correctly handle relocations of data values (in the .data
section) that are not on a 4-byte boundary and are not 4-bytes long. The smallest unit of identification is 4-bytes. Relocations of data smaller than this generally produce results that are difficult to interpret. Because most language compilers follow standard data size and alignment conventions, this situation generally occurs only with assembler-generated XCOFF files. SEE ALSO
|