9 Absolute Lister Description

The ARM absolute lister is a debugging tool that accepts linked object files as input and creates .abs files as output. These .abs files can be assembled to produce a listing that shows the absolute addresses of object code. Manually, this could be a tedious process requiring many operations; however, the absolute lister utility performs these operations automatically.

9.1 Producing an Absolute Listing

Figure 9-1 illustrates the steps required to produce an absolute listing.

Figure 9-1 Absolute Lister Development Flow

9.2 Invoking the Absolute Lister

The syntax for invoking the absolute lister is:

armabs [-options] input file

armabs	is the command that invokes the absolute lister.
options	identifies the absolute lister 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 (-). The absolute lister options are as follows:
	-e	enables you to change the default naming conventions for filename extensions on assembly files, C source files, and C header files. The valid options are: ea [.]asmext for assembly files (default is .asm) ec [.]cext for C source files (default is .c) eh [.]hext for C header files (default is .h) ep [.]pext for CPP source files (default is cpp)
		The . in the extensions and the space between the option and the extension are optional.
	-q	(quiet) suppresses the banner and all progress information.
input file	names the linked object file. If you do not supply an extension, the absolute lister assumes that the input file has the default extension .out. If you do not supply an input filename when you invoke the absolute lister, the absolute lister prompts you for one.

The absolute lister produces an output file for each file that was linked. These files are named with the input filenames and an extension of .abs. Header files, however, do not generate a corresponding .abs file.

Assemble these files with the --absolute_listing assembler option as follows to create the absolute listing:

armcl --absolute_listing filename .abs

The -e options affect both the interpretation of filenames on the command line and the names of the output files. They should always precede any filename on the command line.

The -e options are useful when the linked object file was created from C files compiled with the debugging option (--symdebug:dwarf compiler option). When the debugging option is set, the resulting linked object file contains the name of the source files used to build it. In this case, the absolute lister does not generate a corresponding .abs file for the C header files. Also, the .abs file corresponding to a C source file uses the assembly file generated from the C source file rather than the C source file itself.

For example, suppose the C source file hello.csr is compiled with the debugging option set; the debugging option generates the assembly file hello.s. The hello.csr file includes hello.hsr. Assuming the executable file created is called hello.out, the following command generates the proper .abs file:

armabs -ea s -ec csr -eh hsr hello.out

An .abs file is not created for hello.hsr (the header file), and hello.abs includes the assembly file hello.s, not the C source file hello.csr.

9.3 Absolute Lister Example

This example uses three source files. The files module1.asm and module2.asm both include the file globals.def.

module1.asm

        .text
 .bss dflag, 1
 .bss array, 100
dflag_a .word dflag
array_a .word array
offst_a .word offst
 .copy globals.def
 LDR r4, array_a 
 LDR r5, offst_a
 LDR r3, dflag_a
 LDR r0, [r4, r5]
 STR r0, [r3]

module2.asm

        .text
 .bss offst, 1
offst_a .word offst
 .copy globals.def
 LDR r4, offst_a
 STR r0, [r4]

globals.def

        .global array
 .global offst
 .global dflag

The following steps create absolute listings for the files module1.asm and module2.asm:

Step 1:	First, assemble module1.asm and module2.asm: `armcl module1 armcl module2` This creates two object files called module1.obj and module2.obj.
Step 2:	Next, link module1.obj and module2.obj using the following linker command file, called bttest.cmd:

            --output_file=bttest.out
 --map_file=bttest.map
 module1.obj
 module2.obj
 MEMORY
 {
 P_MEM : org = 0x00000000 len = 0x00001000
 D_MEM : org = 0x00001000 len = 0x00001000
 }
 SECTIONS
 { 
 .data: >D_MEM
 .text: >P_MEM
 .bss: >D_MEM
 }

Invoke the linker: armcl --run_linker bttest.cmd

This command creates an executable object file called bttest.out; use this file as input for the absolute lister.

Step 3:

Now, invoke the absolute lister:

armabs bttest.out

This command creates two files called module1.abs and module2.abs:

module1.abs:

                       .nolist
 array .setsym 000001001h
 dflag .setsym 000001000h
 offst .setsym 000001068h
 .data .setsym 000001000h
 edata .setsym 000001000h
 .text .setsym 000000000h
 etext .setsym 00000002ch
 .bss .setsym 000001000h
 end .setsym 00000106ch
 .setsect ".text",000000000h
 .setsect ".data",000001000h
 .setsect ".bss",000001000h
 .list
 .text
 .copy "module1.asm"

module2.abs:

                       .nolist
 array .setsym 000001001h
 dflag .setsym 000001000h
 offst .setsym 000001068h
 .data .setsym 000001000h
 edata .setsym 000001000h
 .text .setsym 000000000h
 etext .setsym 00000002ch
 .bss .setsym 000001000h
 end .setsym 00000106ch
 .setsect ".text",000000020h
 .setsect ".data",000001000h
 .setsect ".bss",000001068h
 .list
 .text
 .copy "module2.asm"

These files contain the following information that the assembler needs for Step 4:

They contain .setsym directives, which equate values to global symbols. Both files contain global equates for the symbol dflag. The symbol dflag was defined in the file globals.def, which was included in module1.asm and module2.asm.
They contain .setsect directives, which define the absolute addresses for sections.
They contain .copy directives, which defines the assembly language source file to include.

The .setsym and .setsect directives are useful only for creating absolute listings, not normal assembly.

Step 4:

Finally, assemble the .abs files created by the absolute lister (remember that you must use the --absolute_listing option when you invoke the assembler):

armcl --absolute_listing module1.abs
armcl --absolute_listing module2.abs

This command sequence creates two listing files called module1.lst and module2.lst; no object code is produced. These listing files are similar to normal listing files; however, the addresses shown are absolute addresses.

The absolute listing files created are module1.lst (see Example 9-1 ) and module2.lst (see Example 9-2).

Example 9-1 module1.lst

module1.abs PAGE 1
 15 00000000 .text
 16 .copy "module1.asm" A 1 00000000 .text
 A 2 00001000 .bss dflag, 1
 A 3 00001001 .bss array, 100
 A 4 00000000 00001000- dflag_a .word dflag
 A 5 00000004 00001001- array_a .word array
 A 6 00000008 00001068! offst_a .word offst
 A 7 .copy globals.def
 B 1 .global array
 B 2 .global offst
 B 3 .global dflag
 A 8 
 A 9 0000000c E51F4010 LDR r4, array_a 
 A 10 00000010 E51F5010 LDR r5, offst_a
 A 11 00000014 E51F301C LDR r3, dflag_a
 A 12 00000018 E7940005 LDR r0, [r4, r5]
 A 13 0000001c E5830000 STR r0, [r3]
 No Errors, No Warnings

Example 9-2 module2.lst

module2.abs PAGE 1
 15 00000020 .text
 16 .copy "module2.asm" A 1 00000020 .text
 A 2 00001068 .bss offst, 1
 A 3 00000020 00001068- offst_a .word offst
 A 4 .copy globals.def
 B 1 .global array
 B 2 .global offst
 B 3 .global dflag
 A 5 
 A 6 00000024 E51F400C LDR r4, offst_a
 A 7 00000028 E5840000 STR r0, [r4]
 No Errors, No Warnings