2 ASSEMBLER

This chapter contains the following sections:

Description
Invocation
Detailed Description of Assembler Options
Sections and Memory Allocation
Environment Variables used by asxa
List File
Absolute List File Generation
Page Header
Source Listing

2.1 Description

The XA assembler asxa is an optimizing assembler. During assembly the assembler builds an internal representation of the program. This representation, the flow graph, is used to optimize the program. Examples of the optimizations are choosing alternatives for instructions and removal of unneeded instructions. After optimization the object file and the list file are generated.

The following phases can be identified during assembly:

1. Preprocess, check the syntax and create the flow graph

2. Legality check of all instructions

3. Optimization, jump optimization

4. Address calculation

5. Generation of object and list file

The assembler generates relocatable object files using the IEEE-695 object format. This file format specifies a code part and a symbol part as well as a symbolic debug information part.

File inclusion and macro facilities are integrated into the assembler. See the chapter Macro Operations for more information.

2.2 In vocation

The compiler control program, ccxa, may call the assembler automatically. ccxa translates some of its command line options to options of asxa. However, the assembler can be invoked as an individual program also.

The command line invocation of asxa is:

When you use a UNIX shell (C-shell, Bourne shell), options containing special characters (such as '( )' ) must be enclosed with "". The invocations for UNIX and PC are the same, except for the -? option in the C-shell:

Invocation with -V only displays a version header. -? shows the invocation syntax.

The source-file must be an assembly source file. This file is the input source of the assembler. This file contains assembly code which is either user written, generated by cxa or processed by mppxa. Any name is allowed for this file. If this name does not have an extension, the extension .asm is assumed or, if the file is still not found, the extension .src is assumed.

In the default situation, an object file with extension .obj and a list file with extension .lst is produced. With the -l option you can suppress the list file generation.

Options can appear anywhere in any order, controls must be placed after the filename. The first non-option is taken as the input file. For a description of all possible controls, please refer to the chapter on assembler controls. Options are preceded by a '-' (minus sign). Options can not be combined after a single '-'. If all goes well, the assembler generates a relocatable object module which contains the object code, with the default extension .obj. You can specify another output filename with the -o option. Error messages are written to the terminal, unless they are directed to an error list file with the -err assembler option.

The following list describes the assembler options briefly. The next section gives a more detailed description. Some options have an equivalent control.

Option Description
-? or -H Display invocation syntax
-Ccpu Use special function register definitions for cpu
-Dmacro[=def] Define preprocessor macro
-Idirectory Look in directory for include files
-L[flag...] Remove specified source lines from list file
-O[flag...] Optimization on/off switches
-V Display version header only
-c Switch to case sensitive mode
-e Remove object file on assembly errors
-err Redirect error messages to error file
-f file Read options from file
-g[a|h|l|s] Generate assembly level debug information
-i[l|g] Default label style local or global
-l Do not generate listing file
-o filename Specify name of output file
-r Read both 8051 AND XA assembly
-t[flag...] Display section summary
-v Verbose mode. Print the filenames and numbers of the passes while they progress
-w[num] Suppress one or all warning messages

Table 2-1: Options summary

2.3 Detailed Description of Assembler Options

With options that can be set from within EDE, you will find a mouse icon that describes the corresponding action.

-?

Option:

-?

Description:

Display an explanation of options at stdout.

Example:

asxa  -?

-C

Option:

Choose a cpu from the EDE | Processor Options... | Processor menu item.

-Ccpu

Arguments:

The cpu name which identifies your XA derivative.

Description:

Use special function register definitions for cpu. The filename looked for is "regcpu.sfr".

Example:

To use SFR definitions from the file regxag3.sfr, enter:

-c

Option:

Select the EDE | Assembler Options | Project Options... menu item. Enable the Assembler works case sensitive check box in the Miscellaneous tab.

-c

Control:

CASE

Default:

Case insensitive

Description:

Switch to case sensitive mode. By default, the assembler operates in case insensitive mode.

Example:

To switch to case sensitive mode, enter:

-D

Option:

Select the EDE | Assembler Options | Project Options... menu item. Define a macro (syntax: macro[=def]) in the Preprocessing tab. You can specify define more macros by separating them with commas.

-Dmacro[=def]

Arguments:

The macro you want to define and optionally its definition.

Description:

Define macro as in 'define'. If def is not given ('=' is absent), '1' is assumed. Any number of symbols can be defined.

Example:

asxa -DPI=3.1416 test.src

-e

Option:

EDE always calls the assembler with the -e option.

-e

Control:

NOKEEPOBJECT

Description:

Use this option if you do not want an object file when the assembler generates errors. With this option the 'make' utility always does the proper productions.

Example:

asxa -e test.src

-err

Option:

In EDE this option is not so useful. If you would use this option you would not see the error messages in the Build tab.

-err

Control:

ERRORPRINT( file )

Description:

The assembler redirects error messages to a file with the same basename as the output file and the extension .ers. The assembler uses the basename of the output file instead of the input file.

Example:

To write errors to the file test.ers instead of stderr, enter:

-f

Option:

Select the EDE | Assembler Options | Project Options... menu item. Add the option to the User options field in the Miscellaneous tab.

-f file

Arguments:

A filename for command line processing. The filename "-" may be used to denote standard input.

Description:

Use file for command line processing. To get around the limits on the size of the command line, it is possible to use command files. These command files contain the options that could not be part of the real command line. Command files can also be generated on the fly, for example by the make utility.

More than one -f option is allowed.

Some simple rules apply to the format of the command file:

1. It is possible to have multiple arguments on the same line in the command file.

2. To include whitespace in the argument, surround the argument with either single or double quotes.

3. If single or double quotes are to be used inside a quoted argument, we have to go by the following rules:

a. If the embedded quotes are only single or double quotes, use the opposite quote around the argument. Thus, if a argument should contain a double quote, surround the argument with single quotes.

b. If both types of quotes are used, we have to split the argument in such a way that each embedded quote is surrounded by the opposite type of quote.

Example:

or

or

4. Some operating systems impose limits on the length of lines within a text file. To circumvent this limitation it is possible to use continuation lines. These lines end with a backslash and newline. In a quoted argument, continuation lines will be appended without stripping any whitespace on the next line. For non-quoted arguments, all whitespace on the next line will be stripped.

Example:

5. It is possible to nest command line files up to 25 levels.

Example:

Suppose the file mycmds contains the following line:

The command line can now be:

-g

Option:

Select the EDE | Assembler Options | Project Options... menu item. Choose a Debug info option in the Code Generation tab.

-g[a|h|l|s]...

Control:

DEBUG
LOCALS

Default:

-gAhLS (only HLL debug)

Description:

Specify to generate debug information. If you do not use this option or if you specify -g without a flag, the default is -gAhLS, which only passes the high level language debug information.

Flags can be switched on with the lower case letter and switched off with the uppercase letter.

An overview of the flags is given below.

a - assembler source line information
h - pass HLL debug information
l - local symbols debug information
s - always debug; either "AhL" or "aHl"

With -ga you enable assembler source line information. With -gh the assembler passes the high level language debug information from the compiler to the object file. These two types of debug information cannot be used both. So, -gah is not allowed.

With -gl you enable the generation of local symbols debug information. You can use this option independent of the setting of the -ga and -gh options.

With -gs you instruct the assembler to always generate debug information. If HLL debug information is present in the source file, the assembler passes this information (same as -gAhL). If no HLL debug information is present, the assembler generates assembler source line information and local symbols debug information (same as -gaHl).

Examples:

To pass high level symbolic debug information to the output files and generate local symbols debug information, enter:

To generate assembler source line information, enter:

To always generate debug information, depending on the debug information in the source file, enter:

-I

Option:

Select the EDE | Directories... menu item. Add one or more directory paths to the Include Files Path field.

-Idirectory

Arguments:

The name of the directory to search for include file(s).

Description:

Change the algorithm for searching include files whose names do not have an absolute pathname to look in directory. Thus, include files whose names are enclosed in "" are searched for first in the directory of the file containing the include line, then in the current directory, then in directories named in -I options in left-to-right order. If the include file is still not found, the assembler searches in a directory specified with the environment variable ASXAINC ASXAINC can contain more than one directory. Separate multiple directories with ';' for PC (':' for UNIX). Finally, the directory ../include relative to the directory where the assembler binary is located is searched.

For include files whose names are in <>, the directory of the file containing the include line and the current directory are not searched. However, the directories named in -I options (and the one in ASXAINC and the relative path) are still searched.

Example:

asxa -I/proj/include test.src

-i

Option:

Select the EDE | Assembler Options | Project Options... menu item. Choose one of the Labels are local/global by default options in the Miscellaneous tab.

-i[l|g]

Default:

-il (local labels)

Description:

Select default handling for label identifiers. -il specifies that data and code assembly labels are by default treated as LOCAL labels, unless overruled by the PUBLIC directive. With -ig data and code assembly labels are by default treated as GLOBAL labels, unless overruled by the LOCAL directive..

The compiler generates local code and data labels which requires the default option (-il) to be enabled. When data and code assembly labels are by default treated as GLOBALS labels, labels of different modules can lead to compile time errors.

Example:

To specify that assembly label identifiers are treated as GLOBAL labels (PUBLIC) by default, enter:

-L

Option:

Select the EDE | Assembler Options | Project Options... menu item. Enable or disable one or more check boxes in the List File tab and Adv. List File tab.

-L[flag...]

Arguments:

Optionally one or more flags specifying which source lines are to be removed from the list file.

Default:

-LcDElMnPQsWXy

Description:

Specify which source lines are to be removed from the list file. A list file is generated byt default. If you do not specify the -L option the assembler removes source lines containing #line directives or symbolic debug information, empty source lines and puts wrapped source lines on one line. -L without any flags, is equivalent to -Lcdelmnpqswxy, which removes all specified source lines form the list file.

Flags can be switched on with the lower case letter and switched off with the uppercase letter. The following flags are allowed:

c Default. Remove source lines containing assembler controls.

C Keep source lines containing assembler controls.

d Remove source lines containing section directives (the SEGMENT, xSEG directives).

D Default. Keep source lines containing section directives.

e Remove source lines containing one of the symbol definition directives EXTRN, PUBLIC, LOCAL or CALLS.

E Default. Keep source lines containing symbol definition directives.

l Default. Remove source lines containing C preprocessor line information (lines with #line).

L Keep source lines containing C preprocessor line information.

m Remove source lines containing macro/dup directives (lines with MACRO or DUP).

M Default. Keep source lines containing macro/dup directives.

n Default. Remove empty source lines (newlines).

N Keep empty source lines.

p Remove source lines containing conditional assembly (lines with IF, ELSE, ENDIF). Only the valid condition is shown.

P Default. Keep source lines containing conditional assembly.

q Remove source lines containing assembler equates (lines with EQU or =).

Q Default. Keep source lines containing assembler equates.

s Default. Remove source lines containing high level language symbolic debug information (lines with SYMB).

S Keep source lines containing HLL symbolic debug information.

w Remove wrapped part of source lines.

W Default. Keep wrapped source lines.

x Remove source lines containing MACRO/DUP expansions.

X Default. Keep source lines containing MACRO/DUP expansions.

y Default. Hide cycle counts.

Y Show cycle counts.

Example:

To remove source lines with assembler controls from the resulting list file and to remove wrapped source lines, enter:

-l

Option:

Select the EDE | Assembler Options | Project Options... menu item. Disable the Generate list file check box in the Output tab. This also disables the List File tab and Adv. List File tab.

-l

Control:

NOPRINT

Description:

Do not generate listing file. By default a listing file is generated. The listing file has the same basename as the output file. The extension is .lst.

Example:

To suppress the generation of a list file, enter:

-O

Option:

Select the EDE | Assembler Options | Project Options... menu item. Enable or disable one or more Control optimization check boxes in the Optimization tab.

-O[flag...]

Arguments:

Optionally one or more optimization flags.

Default:

-OfHjs

Description:

Control optimization. The -O option without any flags is the same as specifying -OfHjs.

Flags can be switched on with the lower case letter and switched off with the uppercase letter. The following flags are allowed:

f Default. Generic branch and jump instructions can be converted to far instructions on out of range detection. This option only has effect when the CPU large memory mode is selected.

F Generic branch and jump instructions cannot be converted to far instructions on out of range detection. Explicit fjmp or fcall instructions are accepted.

h Allow hardware instructions only. This optimization affects instructions that have an operand size (.B, .W and .D) e.g. ADD.B, ASL.W. When such an instruction without an operand size is detected an error will be triggered. Since the compiler generates generic instructions enabling this option may lead to assembler errors.

H Default. Use both hardware instructions and generic instructions.

j Default. Enable jump and branch range optimization. The assembler tries to replace jumps and branches with shorter or faster functionally equivalent branches.

J Disable jump and branch optimization.

s Default. Enable short instruction optimization. The assembler tries to replace mov instructions with the shorter equivalent movs instructions.

S Disable short instruction optimization.

Example:

To use hardware instructions only, enter:

-o

Option:

Select the EDE | Assembler Options | Project Options... menu item. Add the option to the User options field in the Miscellaneous tab.

-o filename

Arguments:

An output filename. The filename may not start immediately after the option. There must be a tab or space in between.

Default:

Basename of assembly file with .obj suffix.

Description:

Use filename as output filename of the assembler, instead of the basename of the assembly file with the .obj extension.

Example:

To create the object file myfile.obj instead of test.obj, enter:

-r

Option:

Select the EDE | Processor Options... menu item. Select the 8051 compatibility mode radio button in the SCR tab.

-r

Description:

With this option the assembler translates 8051 instructions to XA equivalents. Instructions that are legal for both 8051 and the XA are handled as 8051 instructions. By default the assembler reads XA instructions only.

Example:

asxa -r test51.src

See Appendix H , Translate 8051 to XA, for more information.

-t

Option:

Select the EDE | Assembler Options | Project Options... menu item. Enable the Generate section summary check box in the List File tab.

-t[flag...]

Arguments:

Optionally one or more output flags.

Default:

-tCL

Description:

Produce totals (section size summary). For each section its memory address, size, number of cycles and name is listed. The -t option without any flags is the same as specifying -tcl.

Flags can be switched on with the lower case letter and switched off with the uppercase letter. The following flags are allowed:

c Section summary listed on stdout.

C Default. Section summary not listed on stdout.

l Section summary listed in list file.

L Default. Section summary not listed in list file.

Example:

asxa -tc test.src
Section summary:

 NR ADDR   SIZE CYCLE NAME
  1        0009     0 TEST_PR
  2        000d     0 CXA_INI_NE

-V

Option:

Select the EDE | Assembler Options | Project Options... menu item. Add the option to the User options field in the Miscellaneous tab.

-V

Description:

With this option you can display the version header of the assembler. This option must be the only argument of asxa. Other options are ignored. The assembler exits after displaying the version header.

Example:

asxa -V
XA assembler va.b rc    SN00000000-015 (c) year TASKING, Inc.

-v

Option:

Select the EDE | Assembler Options | Project Options... menu item. Add the option to the User options field in the Miscellaneous tab.

-v

Description:

Verbose mode. With this option specified, the assembler prints the filenames and the assembly passes while they progress. So you can see the current status of the assembler.

Example:

asxa -v test.src
Parsing "test.src"
   48 lines (total now 43)
Optimizing
Evaluating absolute ORG addresses
Parsing symbolic debug information
Creating object file "test.obj"
Closing object file

-w

Option:

Select the EDE | Assembler Options | Project Options... menu item. Select one of the Diagnostics options in the Output tab and optionally fill in specific message numbers to suppress.

-w[num]

Arguments:

Optionally the warning number to suppress.

Description:

-w suppress all warning messages. -wnum suppresses warning messages with number num. More than one -wnum option is allowed.

Example:

The following example suppresses warnings 113 and 114:

2.4 Sections and Memory Allocation

A section is a logical piece of code or data which will be assigned to memory as a single block. Every section has a name, a memory type and possibly some section attributes. There are two types of sections: relocatable sections and absolute sections.

Each module consists of at least one section. Sections in different modules, but with the same name will be combined into one section by the linker. Refer to the paragraph Sections and the chapter Operands and Expressions for more information about sections.

2.5 Environment Variables used by asxa

ASXAINC With this environment variable you can specify directories where the asxa assembler will search for include files. You can overrule this search path with the -I command line option. Multiple pathnames can be separated with semicolons.

TMPDIR With the TMPDIR environment symbol you can specify the directory where the assembler can generate temporary files. If the assembler terminates normally, the temporary file will be removed automatically.
If you do not set TMPDIR, the temporary file will be created in the current working directory.

2.6 List File

The list file is the output file of the assembler which contains information about the generated code. The amount and form of information depends on the use of the -L option. The name is the basename of the output file with the extension .lst, unless the PRINT control is used. The list file can be suppressed whith the -l option or the NOPRINT control. From EDE you can suppress the list file generation by disabling the Generate list file check box in the Output tab of the EDE | Assembler Options | Project Options... menu item. A list file is also generated when assembly errors/warnings occur. In this case the error/warning is given just below the source line containing the error/warning.

2.6.1 Absolute List File Generation

After locating the whole application, an absolute list file can be generated for all assembly source input files with the assembler. To generate an absolute list file from an assembly source file the source code needs to be assembled again with use of the locator map file of the application the assembly source belongs to. See section 10.6, Locator Output, how to produce a locator map file.

When a map file is specified as input for the assembler, an absolute list file is generated, unless you specify the option -l. The previously generated object file is not overwritten when absolute list file generation is enabled. Absolute list file generation is only enabled when a map file is specified on the input using the MAP control.

When you want to generate an absolute list file, you have to specify the same options as you did when generating the object file. If the options are not the same you might get an incorrect absolute list file.

Example:

Suppose your first invocation was:

then when you want to generate an absolute list file you have to specify the same option (-Oh) and the map control:

With this command he absolute list file "test.lst" is created.

2.6.2 Page Header

The page header consists of four lines.

The first line contains the following information:

- information about assembler name

- version and serial number

- copyright notice

The second line contains a title specified by the TITLE (first page) control and a page number.

The third line contains the name of the file (first page) or is empty (succeeding pages).

The fourth line contains the header of the source listing as described in the next section.

Example:

XA assembler va.b rc     SNzzzzzzzz-zzz (c) year TASKING, Inc.
Title for demo use only                               page   1
/tmp/hello.src
ADDR   CODE            LINE SOURCELINE

2.6.3 Source Listing

The following line appears in the page header:

ADDR   CODE            LINE SOURCELINE

The different columns are discussed below.

ADDR This is the memory address. The address is a (6 digit) hexadecimal number that represents the offset from the beginning of a relocatable section or the absolute address for an absolute section.

Example:

ADDR   CODE            LINE SOURCELINE
                          .
                          .
                          3 $ZPAGE
                          4         NAME    HELLO
                          7         PUBLIC  _main
000000                    8 HELLO_PR        SEGMENT CODE
000000                    9         RSEG    HELLO_PR
                         10 _main:
000000 9908rrrr          13         MOV.W   R0,#_3
000004 C5rrrr            14         CALL    _printf
000007 D680              15         RET
                         19         EXTRN   CODE(_printf)

CODE This is the object code generated by the assembler for this source line, displayed in hexadecimal format. The displayed code need not be the same as the generated code that is entered in the object module. The code can also be relocatable code or a relocatable part and external part. In this case the letter 'r' is printed for the relocatable code part in the listing.

Example:

ADDR   CODE            LINE SOURCELINE
                          .
                          .
                          4         NAME    T
                          7         PUBLIC  _f
000000                    8 T_PR    SEGMENT CODE
000000                    9         RSEG    T_PR
000000                   10         DS      4
   |  RESERVED
000003
                         11 _f:
000004 8Errrr            14         MOV.W   R1,_a
000007 6911              15         OR.W    R1,R1

LINE This column contains the line number. This is a decimal number indicating each input line, starting from 1 and incrementing with each source line. If listing of the line is suppressed (i.e. by $NOLIST), the number increases by one anyway.

Example:

The following source part,

results in the following list file part:

SOURCELINE
This column contains the source text. This is a copy of the source line from the source module. For ease of reading the list file, tabs are expanded with sufficient numbers of blank spaces.

Example:

ADDR   CODE      LINE SOURCELINE
                    .
                    .
021271             29         cseg     rom
asxa E226: /tmp/t.src line 29 : unknown symbol attribute: ROM


Copyright © 2000 TASKING, Inc.