8 ASSEMBLER CONTROLS

This chapter contains the following sections:

Introduction
Overview Assembler Controls
Description of Assembler Controls
CASE
DEBUG
IDENT
LIST ON/OFF
LIST
OBJECT
PAGE
PAGE Settings
PAGELENGTH
PAGEWIDTH
PAGING
PRCTL
PRINT
STITLE
TITLE
WARNING

8.1 Introduction

Assembler controls are provided to alter the default behavior of the assembler. They can be specified on 'control lines', embedded in the source file. A control line is a line starting with a dollar sign ($). Such a line is not processed like a normal assembly source line, but as an assembler control line. One control per source line is allowed. An assembler control line may contain comments. Upper and lower case letters are considered equivalent for assembler directives.

The controls are classified as: primary or general.

Primary controls

Primary controls effect the overall behavior of the assembler and remain in effect throughout the assembly. For this reason, you must use primary controls only at the beginning of a source file, before the assembly starts. If you use a primary control after the beginning of the source file, a warning is given and the control is ignored. If you specify a primary control more than once, a warning is given and the last definition is used. When you use a corresponding command line option to specify a control, this overrides the control specified in the source file.

General controls

General controls are used to control the assembler during assembly. General controls may appear anywhere in a source file. When you use a corresponding command line option to specify a general control, the general controls in the source file are ignored.

In the following sections the available assembler controls are listed in alphabetic order. Some controls are set by default, and some controls have a default value.

8.2 Overview Assembler Controls

Control Type Def. Description
$CASE ON
$CASE OFF
pri ON All user names are case sensitive.
User names are not case sensitive.
$DEBUG ON
$DEBUG OFF
$DEBUG "flags"
pri

AhLS
Produce local symbolic debug info.
Do not produce local symbols
Produce symbolic debug info.
$HW_ONLY pri Map mnemonics literally on the instructions.
$FPU pri Allow single precision FPU instructions in the assembly source.
$IDENT LOCAL
$IDENT GLOBAL
pri LOCAL Default local labels.
Default global labels.
$LIST ON
$LIST OFF
gen Resume listing.
Stop listing.
$LIST "flags" pri cDElMnPQsWXy Define what to include in/exclude from the list file.
$MMU pri Allow memory management -
instructions in the assembly source
$OBJECT "file "
$OBJECT OFF
pri
pri
src.obj Alternative name for object file.
Do not produce an object file.
$PAGE gen Generate formfeed in list file.
$PAGE width[,length, top, bottom, left] gen 80,66, 0,0,0 Change list file page settings.
$PAGELENGTH (length) pri 66 Sets page length of list file
$PAGEWIDTH (width) pri 80 Sets width of list file
$PAGING
$NOPAGING
pri PAGING Format print file into pages
Do not format print file into pages
$PRCTL exp|"string" gen Output string to the list file.
$PRINT(print-file)
$NOPRINT
pri src.lst Define print file name
Do not create print file
$TCdefect ON

$TCdefect OFF
gen OFF Enable checks for CPU functional problem defect
Enable checks for CPU functional problem defect
$STITLE "title" gen Set list page header title for next pages.
$TITLE "title" pri spaces Set list page header title for first page.
$WARNING OFF
$WARNING OFF num
pri Suppress all warnings.
Suppress one warning.
Type: Type of control: pri for primary controls, gen for general controls.
Def.: Default.

Table 8-1: Assembler controls

8.3 Description of Assembler Controls

CASE

Control:

$CASE ON
$CASE OFF

Related option:

-c Set case sensitivity off; overrules the control.

Class:

Primary

Default:

$CASE ON

Description:

Selects whether the assembler operates in case sensitive mode or not. In case insensitive mode the assembler maps characters on input to uppercase. (literal strings excluded).

Example:

;Begin of source
$case off     ;assembler in case insensitive mode

DEBUG

Control:

$DEBUG ON
$DEBUG OFF
$DEBUG "flags"

Related option:

-g[a|h|l|s]... Produce assembly debug information

Class:

Primary

Default:

$DEBUG "AhLS" (only HLL debug)

Description:

Controls the generation of debugging information in the object file. $DEBUG ON enables the generation of local (assembler) debugging information (same as -gl) and $DEBUG OFF disables it.

With $DEBUG "flags" you have more control over the generation of debugging information. Flags can be switched on with the lower case letter and switched off with the uppercase letter. The following flags are available:

Flags a and h cannot be combined.

The debugging information generated by the C compiler is always passed on to the object file.

Example:

;Begin of source
$debug on     ; generate local assembly 
              ; debug information

FPU

Control:

$FPU

Related option:

-FPU

Class:

Primary

Default:

(none) No fpu instructions allowed.

Description:

When you use the $FPU control you allow the assembler to accept single precision FPU instructions in the assembl y source file and encode them properly. When you use this control, the define _FPU is set to 1 allowing you to use single precision floating point instructions. Default the define _FPU is set to 0 which tells the assembler not to accept single precision floating point instructions.

For a more detailed description about the floating point arithmetic see section Floating Point Arithmetic in Chapter Runtime of the C Cross Compiler Users Manual.

Example:

;Begin of source
$FPU     ; the use of single precision FPU instructions
         ; in this source are allowed.

HW_ONLY

Control:

$HW_ONLY

Related option:

-hw_only

Class:

Primary

Default:

none Substitutions by faster or smaller instructions is allowed.

Description:

Normally the assembler may replace instructions by other, smaller or faster instructions. For example, the instruction jeq d0,#0,label1 is replaced by jz d0,label1.

With the $HW_ONLY control you instruct the assembler to encode all instruction as they are. The assembler does not substitute instructions with other, faster or smaller instructions. When you use this control, the define _HW_ONLY is set to 1 (no substition of instructions).

Example:

To prevent the assembler from substituting instructions with other, smaller or faster instructions:

;Begin of source
$HW_ONLY   ; the assembler does not substitute
           ; instructions with other, smaller or
           ; faster instructions.

IDENT

Control:

$IDENT LOCAL
$IDENT GLOBAL

Related option:

-i[l|g] Default labels are local or global.

Class:

Primary

Default:

$IDENT LOCAL

Description:

With the $IDENT control you specify how a label is to be treated by the assembler. This is for code and data labels only. $IDENT LOCAL specifies that labels are local by default, with $IDENT GLOBAL labels are global by default.

.SET identifiers are always treated as local symbols.

You can always overrule the default settings with the .LOCAL or .GLOBAL directives for a specific label.

Example:

;Begin of source
$ident global     ; assembly labels are global
                  ; by default

LIST ON/OFF

Control:

$LIST ON
$LIST OFF

Related option:

-l Produce an assembler list file

Class:

General

Default:

$LIST ON

Description:

Switch the listing generation on or off. These controls take effect starting at the next line. Actual list file generation is selected on the command line. Without the command line option -l, no list file is produced.

Example:

$list off     ; Turn listing off. These lines are
              ; not present in the list file
.
.
$list on      ; Turn listing back on. These lines
              ; are present in the list file
.
.

LIST

Control:

$LIST "flags"

Related option:

-L[flag...] Remove specified source lines from list file

Class:

Primary

Default:

$LIST "cDElMnPQsWXy"

Description:

Specify which source lines are to be removed from the list file. The flags defined within the string are the same as for the -L command line option.

Example:

;Begin of source
$list "cw"     ; Remove source lines with assembler
               ; controls from the resulting list
               ; file and remove wrapped source lines
.
.

See the -L option for an explanation of each flag available.

MMU

Control:

$MMU

Related option:

-MMU

Class:

Primary

Default:

$MMU The use of memory management instructions is allowed.

Description:

The $MMU control allows the use of memory management instructions in the assembly source. When you use this control, the define _MMU is set to 1 allowing you to use memory management instructions.

Example:

To allow the use of memory management instructions in the assembly source, enter:

;Begin of source
$MMU     ; Allow the use of memory management
         ; instructions in the assembly source.

OBJECT

Control:

$OBJECT "file"
$OBJECT OFF

Related option:

-o file Specify name of output file

Class:

Primary

Default:

$OBJECT "sourcefile.obj"

Description:

The $OBJECT "file" control specifies an alternative name for the object file. The $OBJECT OFF control causes no object file to be generated.

Examples:

;Begin of source
$object "x1.obj"        ; generate object file x1.obj

PAGE

Control:

$PAGE

Class:

General

Default:

New page started when page length is reached.

Description:

The current page is terminated with a formfeed after the current (control) line, the page number is incremented and a new page is started. Ignored if LIST OFF is in effect.

Example:

.          ; assembler source lines
.
$page      ; generate a formfeed
.
.          ; more source lines
$page      ; generate a formfeed
.
. 

PAGE Settings

Control:

$PAGE exp1[,exp2,...,exp5]

Related option:

-l Produce an assembler list file

Class:

General

Default:

$PAGE 80,66,0,0,0

Description:

Change page settings. The $PAGE control with arguments can be used to specify the printed format of the output listing. Arguments may be any positive absolute integer expression. The arguments in the operand field (as explained below) are separated by commas. Any argument can be left as the default or last set value by omitting the argument and using two adjacent commas. The $PAGE control with arguments will not cause a page eject and will be printed in the source listing.

The arguments in order are:

PAGE_WIDTH exp1

PAGE_LENGTH exp2

BLANK_TOP exp3

BLANK_BOTTOM exp4

BLANK_LEFT exp5

The following relationship must be maintained:

Examples:

$PAGE 132,,3,3     ;Set width to 132, 
                   ;default 66 lines
                   ;3 line top/bottom margins

PAGELENGTH

Control:

$PAGELENGTH(length)

Related option:

-ll Set listing page length

Class:

Primary

Default:

$PAGELENGTH(66)

Description:

Sets the maximum number of lines on one page of the listing file. This number includes the lines used by the page header (4) and the lines with error messages. The default page length is 80. The minimum page length is 10.

Example:

$pagelength(50)   ; set page length to 50 lines per page 

PAGEWIDTH

Control:

$PAGEWIDTH(width)

Related option:

-lw Set listing page width

Class:

Primary

Default:

$PAGEWIDTH(80)

Description:

Sets the maximum number of characters on one line in the list file. Lines that exceed this width are wrapped on the next lines. The default page width is 66. The minimum page width is 40.

Example:

$pagelength(50)   ; set page width to 50 chars per line

PAGING

Control:

$PAGING
$NOPAGING

Related option:

-nopi Disable format listing file into pages

Class:

Primary

Default:

Paging is turned on.

Description:

Turn the generation of formfeeds and page headers on or off.

Example:

$nopaging   ; turn paging off

PRCTL

Control:

$PRCTL exp|string[,exp|string]...

Related option:

-l Produce an assembler list file

Class:

General

Default:

-

Description:

Send Control String to Printer. $PRCTL simply concatenates its arguments and ships them to the listing file (the control line itself is not printed unless there is an error). exp is a byte expression and string is an assembler string. A byte expression would be used to encode non-printing control characters, such as ESC. The string may be of arbitrary length, up to the maximum assembler-defined limits.

$PRCTL may appear anywhere in the source file and the control string will be output at the corresponding place in the listing file. However, if a $PRCTL directive is the last line in the last input file to be processed, the assembler insures that all error summaries, symbol tables, and cross-references have been printed before sending out the control string. This is so a $PRCTL control can be used to restore a printer to a previous mode after printing is done. Similarly, if the $PRCTL control appears as the first line in the first input file, the control string will be output before page headings or titles.

The $PRCTL control only works if the -l command line option is given; otherwise it is ignored.

Examples:

$PRCTL $1B,'E'     ;Reset HP LaserJet printer

PRINT

Control:

$PRINT(file)
$NOPRINT

Related option:

-l Produce an assembler list file
-ln Define an assembler list file name

Class:

Primary

Default:

$PRINT(sourcefile.lst)

Description:

The $PRINT control specifies an alternative name for the listing file. The $NOPRINT control causes no listing file to be generated.

Examples:

$PRINT(mylist.lst)   ; generate an assembler list file
                       with the name 'mylist.lst'.

STITLE

Control:

$STITLE "title"

Related option:

-l Produce an assembler list file

Class:

General

Default:

$STITLE ""

Description:

Initialize Program Sub-Title. The $STITLE control initializes the program subtitle to the title in the operand field. The subtitle will be printed on the top of all succeeding pages until another $STITLE control is encountered. The subtitle is initially blank. The $STITLE control will not be printed in the source listing. An $STITLE control with no string argument will cause the current subtitle to be blank.

If the page width is too small for the title to fit in the header, it will be truncated.

Example:

$stitle "Demo title"

; title in page header on succeeding pages
; is Demo title

TITLE

TC

Control:

$TCdefect ON
$TCdefect OFF

Related option:

-zdefect Set checking for CPU functional problem defect on

Class:

General

Default:

$TCdefect OFF

Description:

With this control you can enable or disable specific CPU functional problem checks.

To enable the assembler checks for all TriCore CPU TC112 problems (respectively TC113 problems) at once, use the control $TC112_DEFECTS ($TC113_DEFECTS).

Example:

$TC112_COR1  ON     ; enables assembler checks for CPU
                    ; functional problem TC112_COR1

Appendix CPU Functional Problems in the C Cross-Compiler User's Guide for a complete overview of all CPU functional problems that are supported by the assembler.

TITLE

Control:

$TITLE "title"

Related option:

-lt Set listing page header title

Class:

Primary

Default:

spaces

Description:

This control specifies the title to be used in the page heading of the first page of the list file.

If the page width is too small for the title to fit in the header, it will be truncated.

Example:

;Begin of source
$title "NEWTITLE"

; title in page header on first page is NEWTITLE

STITLE

WARNING

Control:

$WARNING OFF
$WARNING OFF num

Related option:

-w[num] Suppress one or all warning messages

Class:

Primary

Default:

- (All warnings enabled)

Description:

$WARNING suppresses all warnings. This is the same as -w. $WARNING OFF num suppresses one warning message, where num is the warning message number (same as the -wnum option).

Example:

;Begin of source
$warning off     ; switch all warnings off

Copyright © 2002 Altium BV