ASSEMBLER LINKER FORMATTER LIBRARIAN Family Release Ref
|
|
|
Top Searches for this datasheet
Software Tools
ASSEMBLER LINKER FORMATTER LIBRARIAN
Family
Release
Ref: Doc-ST7XXX-SW
Software Tools
ASSEMBLER LINKER FORMATTER LIBRARIAN
Family
Release
March 1998
LIFE SUPPORT DEVICES SYSTEMS MUST EXPRESSLY AUTHORIZED. SGS-THOMSON PRODUCTS AUTHORIZED CRITICAL COMPONENTS LIFE SUPPORT DEVICES SYSTEMS WITHOUT EXPRESS WRITTEN APPROVAL SGS-THOMSON Microelectronics.
used herein: Life support devices systems those which intended surgical implant into body, support sustain life, whose failure perform, when properly used accordance with instructions provided with product, reasonably
expected result significant injury user. critical component component life support device system whose failure perform reasonably expected cause failure life support device system, affect safety effectiveness.
SOFTWARE TOOLS
ASM, LYN, OBSEND,
PREFACE
Purpose Manual This manual describes software tools, allowing develop applications family microcontrollers:
These tools part generic tool-chain development system that includes: meta-assembler: generic linker: generic formatter: generic librarian: Audience This book intended persons need know write, assemble programs designed microcontrollers. preliminary knowledge field microcontrollers required, however. OBSEND
Related Publications reading following publications will profitable: ST7-Family Data Books, Starter Kit, Getting Started, Ref. Doc-ST7XXX-KIT. ST7-Family Programming Manual, Windows Debugger Family, Ref. Doc-ST7XXX-WGDB7XXX. This manual will help debug finalize your programs.
March 1998
This preliminary information product development undergoing evaluation. Details subject change without notice.
5/144
SOFTWARE TOOLS
Organization Manual
This manual made seven chapters, appendixes:
Chapter INTRODUCTION, introduces components Software Tools.
Chapter INSTALLATION, describes install software package various computers.
Chapter ADDRESSING MODEL, discusses addressing structure processor family.
Chapter ASSEMBLER, explains Assembler.
Chapter LINKER, describes linking process.
Chapter OBSEND, explains role formatter program preparation process.
Chapter LIBRARIAN, explains role librarian.
Appendix provides information assembler directives.
Appendix provides information assembler linker error messages.
6/144
Table Contents
INTRODUCTION TOOL-CHAIN (ASSEMBLER) (LINKER) OBSEND (FORMATTER) INSTALLATION ADDRESSING MODEL OVERVIEW INHERENT ADDRESSING MODE IMMEDIATE OPERAND SHORT LONG ADDRESSING MODES INDEXED MODES RELATIVE MODE MEMORY INDIRECT ADDRESSING MODES HIGH, ADDRESSING MODES ASSEMBLER OVERVIEW SOURCE CODE FORMAT 4.2.1 4.2.2 4.2.3 4.2.4 4.2.5 4.2.6 4.2.7 Source Files Assembly Source Code Format Labels Opcodes Operands Comments Source Code Example
SEGMENTATION 4.3.1 Introduction 4.3.2 Parameters 4.3.3 Copying Code MACROS
7/144
Table Contents
4.4.1 Defining Macros 4.4.2 Parameter Substitution CONDITIONAL ASSEMBLY 4.5.1 IF/#ELSE#ENDIF directives RUNNING ASSEMBLER 4.6.1 Command Line 4.6.2 Options LINKER WHAT LINKER DOES INVOKING LINKER 5.2.1 Command Line 5.2.2 Response files LINKING DETAIL 5.3.1 PUBLICs EXTERNs 5.3.2 Segments Linker 5.3.3 Symbol Files LINKER MORE DETAIL. 5.4.1 Composition .OBJ Files 5.4.2 Composition .COD Files 5.4.3 Reading Mapfile Listing OBSEND WHAT OBSEND DOES INVOKING OBSEND 6.2.1 Destination Type 6.2.2 Destination Arguments FORMAT DEFINITIONS 6.3.1 6.3.2 6.3.3 6.3.4 6.3.5 Straight Binary Format Intel Format Motorola S-record Format S-record Format Binary
LIBRARIAN OVERVIEW
8/144
Table Contents
INVOKING LIBRARIAN ADDING MODULES LIBRARY DELETING MODULES FROM LIBRARY COPYING MODULES FROM LIBRARY GETTING DETAILS YOUR LIBRARY ASSEMBLER DIRECTIVES ERROR MESSAGES FORMAT ERROR MESSAGES FILE CBE.ERR ASSEMBLER ERRORS LINKER ERRORS
9/144
SOFTWARE TOOLS
10/144
SOFTWARE TOOLS INTRODUCTION
INTRODUCTION
TOOL-CHAIN tool-chain development system includes: meta-assembler: generic linker: generic formatter: generic librarian: OBSEND
(ASSEMBLER) role assembler translate code have written (the source code) into code specific target machine, so-called "object code". assembler takes input file assembly file ".ASM" produces output object file ".OBJ". desired, listing file ".LST" obtained. meta-assembler targeted various processors, using machine description files. machine description file name processor family ST7.TAB.
(LINKER) linker takes input several object files ".OBJ" files produced assembler, produces output object code file ".COD". resolves cross-references between object files, locates modules memory.
OBSEND (FORMATTER) Once your application linked, must output suitable format. formatter takes input object code file ".COD" produced linker. default suffix output file ".FIN", possible specify other suffixes, example: OBSEND <file>,f,<file>.s19,s Note: utility file asli.bat automatically runs ASM, LYN, OBSEND after each other you. this batch file only have only assembly source file ".ASM".
11/144
SOFTWARE TOOLS INSTALLATION
INSTALLATION
install software tools, setup.exe file from CD-ROM included delivery package, follow instructions displayed screen.
When installation completed, installation directory (typically C:\st7tools\asm) contains following files:
Table
ASM.EXE LYN.EXE OBSEND.EXE LIB.EXE ST7.TAB ASLI.BAT README.TXT
assembler linker formatter librarian description file batch file ASM+LYN+OBSEND release notes
Look file readme.txt up-to-date release notes. Other files contain examples. Note: With Windows 3.1x Windows installation process updates autoexec.bat file provide suitable path specifications access assembler tool-chain. take into account autoexec.bat file contents, reboot your computer. also directly access assembler tool-chain from MS-DOS window running C:\st7tools\asm\st7vars.bat.
12/144
SOFTWARE TOOLS ADDRESSING MODEL
ADDRESSING MODEL
OVERVIEW provides single source-coding model regardless which components operands, accumulator (A), index register stack pointer (S), condition code register (CC), memory location. example, single instruction, originates register register transfers well memory accumulator data movements. Two-operand instructions coded with destination operand appearing first position. Examples:
lab01 lab02
A,memory memory,A
load accumulator with memory contents load memory location with contents load with accumulator contents
INHERENT ADDRESSING MODE This concept hardware-oriented: means that instruction operand(s) (are) coded inside operation code; source coding level, operand(s) (are) explicitly written.
Examples:
lab06 lab07
push
accumulator onto stack multiply
IMMEDIATE OPERAND This kind operand introduced sharp sign (#).
Examples:
lab08 lab09
bset
btjt
A,#1
memory,#3 memory,#3,label
load with immediate value memory location test memory jump true (set)
13/144
SOFTWARE TOOLS ADDRESSING MODEL
Unsigned notations accepted defining immediate value values 8-bit immediate operand).
SHORT LONG ADDRESSING MODES These modes differ size memory address (one bytes) thus target address range operand:
0-$FF $100-$FFFF
short addressing mode long addressing mode
Some instructions accept both types addressing modes, some others only short addressing:
Examples:
lab10 lab11
A,memory memory
both types addressing modes only short addressing mode
instructions supporting both formats, short long, when external symbol referenced, long mode chosen Assembler:
Example:
EXTERN symb3 symb1 A,symb1 A,symb3
short mode long mode chosen
14/144
SOFTWARE TOOLS ADDRESSING MODEL
INDEXED MODES hardware supports three variants indexed modes: indexed without offset, indexed with 8-bit unsigned offset ,255 range], indexed with 16-bit offset.
Source coding form
(offset,X) (offset,Y)
no-offset indexing others
Some instructions add, support three forms, some others inc, only first two. Assembler performs same kind 8-bit 16-bit offset selection than between short/long modes described previous sections. Examples: A,(X) A,(0,X) A,(127,X) A,(259,X) no-offset mode 8-bit offset mode
idem
16-bit offset mode
RELATIVE MODE This mode used JRxx, CALLR, BTJx instructions. conditional jump done program label [-128 127] range from value instruction following jump. source coding level, target label specified (and assembler computes displacement).
15/144
SOFTWARE TOOLS ADDRESSING MODEL
MEMORY INDIRECT ADDRESSING MODES This last group consists memory indirect variants short indirect, long indirect, short indirect indexed, long indirect indexed. address specified must always page (i.e. address must less than $100).
Examples:
lab12
A,[80] A,[80.b] A,[80.w]
short indirect short indirect
long indirect
A,([lab12],X) A,([lab12.b],X) A,([lab12.w],Y)
short indirect X-indexed short indirect X-indexed
long indirect Y-indexed
make distinction between short long indirect addressing mode, suffix specified indicate that want work long indirect mode (idem with indexed addressing mode). Implicitly, nothing specified, short indirect addressing mode assumed. also specify short indirect addressing mode.(idem with indexed addressing mode).
HIGH, ADDRESSING MODES some instances, necessary access highest part address highest bits) lowest part address lowest bits) well. this feature, syntax following one:
<expression> where expression symbol.H (highest part) symbol.L (lowest part).
16/144
SOFTWARE TOOLS ADDRESSING MODEL
Examples:
lab12 $0012
A,#lab12.h A,#lab12.l
load with load with
more information about each instruction various addressing modes, refer PROGRAMMING MANUAL.
17/144
SOFTWARE TOOLS ASSEMBLER
ASSEMBLER
OVERVIEW assembler cross-assembler, i.e., produces code target machine, SGSTHOMSON microprocessor family, different from host machine. assembler will turn your source code files into relocatable objects modules ready linking. During process, checks many different types errors. They recorded ASCII file: cbe.err. linker also writes this file. Error messages explained appendix "Error Messages" page 125. produce code ready execution, must assembler (ASM), linker (LYN), object code formatter(OBSEND).
Segmentation Macros Conditional assembly Source file inclusion Absolute patch assembly listing Symbol cross reference listing
SOURCE CODE FORMAT 4.2.1 Source Files Source program code organised ASCII text file named source file. source file extension .asm. made lines, each which terminated line character.
4.2.2 Assembly Source Code Format first line assembly source code file reserved specifying TARGET PROCESSOR. Even comments prohibited. '.TAB' suffix left out. example, processor: c:\st7tools\asm\st7/
File ST7.TAB must located directory c:\st7tools\asm.
18/144
SOFTWARE TOOLS ASSEMBLER
can't found given directory, then error produced assembly aborted. There also environment variable 'METAI'. This variable specifies directory where file 'ST7.TAB' located.
Examples:
PC/MS-DOS:
METAI=c:\st7tools\asm
environment variable METAI defined, first line assembly program st7/ Note installation process automatically sets METAI variable autoexec.bat file.
Remaining source code lines have following general format:
where <space> refers either SPACE ($20) ($09) characters.
four fields left blank, <space> fields mandatory unless: whole line blank, line begins comment, line ends before remaining fields.
Example:
examp
A,$ffff
long addressing mode
opcode label operand
separator
comments
19/144
SOFTWARE TOOLS ASSEMBLER
4.2.3 Labels 4.2.3.1 Label Structure Labels must start column one. label contain eight following characters: Upper Case letters (A-Z) Lower case letters (a-z) Digits (0-9) Underscore
first letter label must letter underscore. Note that upper lower case treated different because assembler case sensitive.
When labels defined there several attributes defined along with value. These are: Size (Byte, Word Long) Relativity (Linker Relative Absolute) Scope (Internally Externally defined)
function each attribute explained following paragraphs.
4.2.3.2 Label Size size label allows assembler make decisions what kind addressing mode choose even label value itself undefined.
force label refer certain size memory location giving label name suffix when defined. suffix isn't used when label referred give suffix, then default size assumed. BYTES, WORDS LONGS directives allow change default. Without directives, default WORDS.
20/144
SOFTWARE TOOLS ASSEMBLER
Examples:
label1.b label2.l word (default) label byte label
long label
force size label bytes byte default label word space defined this label
segment byte `ram' bytes count pointer ds.b ds.w
4.2.3.3 Label Relativity There sorts labels: ABSOLUTE labels RELATIVE labels.
ABSOLUTE labels usually assigned constants, such port addresses, common values used within program.
RELATIVE labels defined derived from) EXTERNAL label label derived from position some program code. They exclusively used labels defined within pieces program data. Example:
ioport $8000 absolute label `count' absolute word label `ioport'
segment `eprom' start X,#count A,#'*' loop ioport,A jrne loop stop stop then loop ever
Only linker sort actual address code, assembler idea many segments precede this class. assembly time, labels such 'start' 'loop'
21/144
SOFTWARE TOOLS ASSEMBLER
actually allocated 'blank' values ($0000). These values will filled later linker. Labels such 'count' 'ioport', which were defined absolutely will filled assembler.
Source code lines that have arguments containing relative labels marked with listing, showing that they 'linker relative'.
Segments discussed "Segmentation" page
4.2.3.4 Label Scope Often, multi-module programs, piece code will need refer label that actually defined another module. this, module that exports label must declare PUBLIC, module which imports label must declare EXTERN. directives EXTERN PUBLIC together pair.
Most labels program will interest other pieces program: these known 'internal' labels since they only used module where they defined. Labels 'internal' default.
Here incomplete example modules that pass labels between them:
module EXTERN _sig1.w EXTERN _sig2.w PUBLIC _handlers segment byte _handlers: _sig1 _sig2 define _handlers refer _sig1 refer _sig2 import _sig1 import _sig2 export _handlers
module EXTERN _handlers.w PUBLIC _sig2 import _handlers (addr. word) export _sig2
22/144
SOFTWARE TOOLS ASSEMBLER
segment byte _sig2: call _handlers refer _handlers define _sig2
see, module refers '_sig2' subroutine which defined module Note that when module refers '_sig2' label EXTERN directive specifies WORD size with '.w' suffix. Because assembler cannot look definition '_sig2' told address size explicitly. doesn't need told relativity: external labels assumed relative. Absolute labels declared between modules should defined INCLUDE file that called modules program; this idea using INCLUDE files very important since down number PUBLIC symbols therefore link time significantly. Lines source code listing which refer external labels marked with given 'empty' values linker fill. short cut, labels declared PUBLIC preceding them with their definition. this done label name need given PUBLIC directive. example, following code fragment declares label 'lab4' PUBLIC automatically:
Example:
lab3 A,#0 .lab4
4.2.4 Opcodes Opcode field serve three different purposes. contain: opcode mnemonic assembly instruction, name directive, name macro invoked.
23/144
SOFTWARE TOOLS ASSEMBLER
Opcodes must separated from preceding field (label, there one) space tab. comprehensive Opcode description found PROGRAMMING MANUAL. Macros discussed "Macros" page Directives discussed "Assembler Directives" page
4.2.5 Operands 4.2.5.1 General
Operands Numbers, String character constants, Program Counter references, Expressions.
4.2.5.2 Number Address Representation default, representation numbers addresses follows MOTOROLA syntax. When want hexadecimal number with instructions labels, they must preceded When nothing specified, default base decimal.
Examples:
lab03 lab04 A,$ffff A,#$cb A,#100 decimal hexadecimal
long addressing mode immediate addressing mode decimal representation
change Motorola format representation using directives (.INTEL,.TEXAS) indicate setting format. more information, refer appendix "Assembler Directives" page
24/144
SOFTWARE TOOLS ASSEMBLER
CAUTION Addresses SEGMENT definition always given hexadecimal: segment byte 100-1FF 'test' segment 'test' defined within 256-511 address range.
4.2.5.3 Numeric Constants Radix Constants need special characters define radix given number. assembler supports MOTOROLA format default. INTEL, TEXAS, ZILOG formats also available format forced .INTEL .TEXAS or.ZILOG directives. (Decimal constants always default, require special characters).
Motorola Format Binary Octal Current Intel Format Binary Octal Current Texas Format Binary Octal Current Zilog Format %ABCD >ABCD ?100 ~665 0ABCDh 100b 665o 665q $ABCD &ABCD %100 ~665 (use MULT MULTIPLY)
25/144
SOFTWARE TOOLS ASSEMBLER
Binary Octal Current
%(2)100 %(8)665
4.2.5.4 String Constants String constants strings ASCII characters surrounded double quotes.
Example:
"This ASCII string"
4.2.5.5 ASCII Character Constants assembler's arithmetic parser also handles ASCII characters single quotes, returning ASCII given character(s).
Examples:
`AB' $4142
characters used within single pair quotes give long constant. following special sequences used denote special characters:
`\b' `\f' `\n' `\r' `\t' `\\' `\0' `\"'
backspace formfeed linefeed carriage return tabulation slash single-quote null double-quote
26/144
SOFTWARE TOOLS ASSEMBLER
4.2.5.6 Program Counter Reference current value program counter (PC) specified
Example:
lab05
4.2.5.7 Expressions Operators
Expressions Expressions numeric values that made from labels, constants, brackets operators.
Labels constants have been discussed previous paragraphs.
Arithmetic brackets allowed nested levels: curly braces used instead common because instructions parenthesis denote indexed addressing modes.
Operators There levels precedence. Operators level take precedence over operators level each level, operators have same precedence: they evaluated from left right.
Table
Operation negated logical logical Result, level
27/144
SOFTWARE TOOLS ASSEMBLER
Table
Operation high offset bnot wnot lnot sexbw sexbl sexwl logical shifted right times shifted left times a<b, else a>b, else a=b, else a>=b, else unequal else a/256, force BYTE type 256, force BYTE type 65536, force WORD*16 type a/65536, force WORD*16 type invert bits invert bits invert bits sign extend byte bits sign extend byte bits sign extend word bits Result, level
Table
Operation divided Result, level
28/144
SOFTWARE TOOLS ASSEMBLER
Table
Operation divided Result, level
Table
Operation mult multiplied above motorola (character reserved) Result, level
Table
Operation minus plus Result, level
Operator names longer than character must followed space character. example, correct, '1AND2' not. Place curly braces around arithmetic expressions. Also, always curly braces top-level, when defining numeric expression. doing produce unexpected results.
Wrong syntax: #define SIZE DS.W SIZE+1 SIZE Wrong, syntax error Wrong, same SIZE
29/144
SOFTWARE TOOLS ASSEMBLER
#ENDIF
Correct syntax: #define SIZE DS.W {SIZE+1} {SIZE #ENDIF
4.2.6 Comments Comments preceded semicolon. Characters following semicolon ignored assembler.
4.2.7 Source Code Example
st7/ small example module showing source formats ioport handshake $8000 $9000 port write here strobe
segment 'program' start loop a,#0 ioport,x zero counter store into ioport
segment word FFFC 'code' WORD start
Don't worry some directives don't make sense yet; they will covered soon; also, take special notice SEGMENT directive.
30/144
SOFTWARE TOOLS ASSEMBLER
SEGMENTATION 4.3.1 Introduction Segments very, very important. have know about segments before assembler. Take time understand them you'll save yourself puzzling. Segmentation 'naming' areas your code making sure that linker collates areas same name together same memory area, whatever order segments object files. different segments defined each module.
segment directive itself four arguments, separated spaces:
[<name>]
SEGMENT [<align>] [<combine>] '<class>' [cod]
Examples:
File1:
st7/ BYTES segment byte 80-FF `RAM0' counter.b address.b ds.b ds.w ds.b stack ds.b loop counter address storage stack allocation stack grows downward
segment byte E000-FFFF `eprom' A,#stack init stack pointer
File2:
st7/ segment `RAM0' serialtemp ds.b
31/144
SOFTWARE TOOLS ASSEMBLER
serialcou
ds.b
WORDS segment `eprom' serial_in A,#0
FILE1 FILE2 separate modules belonging same program. FILE1 introduces classes: 'RAM0' 'eprom'. class-names names choose characters.
first time class used introduced have tell default alignment, start addresses class, and, course name class. Users generally specify class each 'area' their target system.
examples above user class bytes on-chip from 0080 00FF ('RAM0') another 'eprom'. code stored from E000 FFFF ('eprom'). have supply this information very first time class, else only class-name necessary, FILE2.
4.3.2 Parameters following paragraphs describe each argument detail.
4.3.2.1 Name <name> argument optional; contain name characters. does, then segments with same name grouped together within their class, order that names defined. 4.3.2.2 Align <align> argument defines threshold which each segment must start: default alignment specified introduction class none specified class introduction then para alignment assumed), although following allowed specified overriding default:
32/144
SOFTWARE TOOLS ASSEMBLER
Table
Type byte word para page long address Next address boundary Next address 16-byte boundary Next address 64-byte boundary Next address 128-byte boundary Next address 256-byte boundary Next address 4-byte boundary Next address 1k-byte boundary Next address 4K-byte boundary 1001->1002 1001->1010 1001->1040 1001->1080 1001->1100 1001->1004 1001->1400 1001->2000 Description Examples
Looking back examples earlier, should able that 'RAM0' class will allocate counter, address, stack FILE1, when linker meets segment FILE2 same class, serialtemp will allocated serialcou same processing happens 'eprom class segments: second, FILE2 will tacked first FILE1. FILE2 'eprom' class segment specified, say, long align type instead default byte, then that segment would have been next long-word boundary after FILE1 'eprom' class segment.
4.3.2.3 Combine <combine> argument tells assembler linker treat segment. There three types handle
33/144
SOFTWARE TOOLS ASSEMBLER
Table
Type at:X[-Y] common Description Starts class from address address common segments that have same class name will start same address. This address figured linker. Follows from last segment this class.
<none>
at-type <combine> must used introduction class, only once.
at-type <combine> must have argument: start address class, optionally given address limit) class too. given, linker checks that items class have gone over limit address; does, warning issued link time. hexadecimal numbers should have radix specifiers. common-type <combine> segments that have same class name will start same address. linker keeps track longest segment. common segments used sharing data across different applications.
Example:
st7/ dat1 segment byte 'DATA' ds.w com1 .lab1 com1 .lab2 com2 .lab3 com2 .lab4 segment common 'DATA' ds.w segment common 'DATA' ds.w segment common 'DATA' ds.w segment common 'DATA' ds.w
34/144
SOFTWARE TOOLS ASSEMBLER
dat2 .lab5
segment 'DATA' ds.w
values labels lab1, lab2, lab3, lab4, lab5 respectively.
Note: Since can't specify both common combines simultaneously, only specify exact location commons insert empty combine segment before first common declaration.
Example:
com1 com1 segment byte 'DATA' segment common 'DATA' com1 segment common 'DATA'
4.3.2.4 parameter, Output File Control last field SEGMENT directive controls where linker places code given class. When introducing class, this field specified, code this class will sent normal, default .COD file linker. [cod] file given number between then code generated under class being introduced will sent different '.COD' file linker.
linker produces file called 'prog.cod', example, then code produced under classes with [cod] field will into that file, normal.
class introduced with [cod] field though, then code produced under that class sent instead file prog_1.cod. code produced under other classes sent usual prog.cod.
35/144
SOFTWARE TOOLS ASSEMBLER
Using this scheme, bank switching schemes quickly directly, even when multiple EPROMs share same addressing space. Simply allocate each EPROM class own, introduce each class with different [cod] field. This will result linker collating EPROM's contents into different .COD file OBSEND independently.
Example:
segment byte at:8000-BFFF 'eprom1' segment byte at:8000-BFFF 'eprom2'
4.3.3 Copying Code sometimes happens that need copy block code from EPROM RAM. This presents some difficulties because labels that piece code must have addresses, otherwise absolute address references code will point back EPROM copy. specify class execution, different class storage.
following example:
segment byte 'code' segment byte 8000 'ram' segment 'ram>code' label1:
code starting from 'label1' will stored 'code' class usual, labels that special segment will given addresses 'ram' class, memory will also reserved class contents special segment.
MACROS Macros assembly-time subroutines. When call execution-time subroutine have through several time-consuming steps: loading registers with arguments subroutine, having saved con-
36/144
SOFTWARE TOOLS ASSEMBLER
tents registers necessary, pushing registers used subroutine (with attendant stack activity) returning from subroutine (more stack activity) then popping preserved registers continuing. Although macros don't these problems, they long toward making your program execute faster than using subroutines cost. cost program size. Each time invoke macro particular job, whole macro assembly code inserted into your source code. This means there stacking return addresses: your program just runs straight into code; it's obviously feasible this subroutines above certain size. true macros small snippets code that repeatedly perhaps with different arguments which formalized into 'template' macros' definition. 4.4.1 Defining Macros Macros defined using three directives: MACRO, MEND LOCAL. format
<macro-name> MACRO
[parameter-1][, parameter-2
[LOCAL] <label-name>[, label-name <body-of-macro> MEND
Example:
add16 MACRO first,second,result A,first A,second result,A MEND
piece code example might called add16 index,offset,index
which would following statements source code that point:
37/144
SOFTWARE TOOLS ASSEMBLER
A,index A,offset index.X,A
Note that formal parameters given definition have been replaced actual parameters given calling line. These parameters expressions strings well label names constants: it's because they complex expression that they bracketed when there extra numeric activity: this make sure they come with precedence correctly parsed. Macros need have parameters: which case leave MACRO argument field blank, give none calling line. There further problem: because macro called several times same module, labels defined macro will duplicated. LOCAL directive gets around this problem:
Example:
getio MACRO LOCAL loop loop A,$C000 loop MEND
This macro creates code loop await port $C000 low. Without LOCAL directive, label 'loop' would defined many times macro called, producing syntax errors assembly time. Because it's been declared LOCAL start MACRO definition, assembler takes care Wherever sees label 'loop' inside macro, changes name 'loop' 'LOCXXXX' where XXXX number from 0000 FFFF. Each time local label used, XXXX incremented. first time getio macro called, 'loop' actually defined 'LOC0', second time 'LOC1' each these being unique reference name. reference 'loop' 'if' statement also detected changed appropriate local variable.
38/144
SOFTWARE TOOLS ASSEMBLER
following directives very useful, conjunction with macros:
Table
Directive #IFB #IFDEF #IFLAB #IFIDN Usage implement macro optional parameters. test parameter defined. test parameter label. compare parameter given string.
4.4.2 Parameter Substitution assembler looks macro parameters after every space character. want embed parameter, example, middle label, must precede parameter name with ampersand character, make parameter visible preprocessor. example, have parameter called 'param': dc.w param works expected ampersand necessary label¶m: label¶m&_¶m:
otherwise 'labelparam' would left valid label name; macro parameter 'param' value '5', then 'label5' 'label5_5' would created.
CONDITIONAL ASSEMBLY Conditional assembly used choose ignore select whole areas assembler code. This useful generating different versions program setting particular variable INCLUDE file that forces special pieces code instead others.
4.5.1 IF/#ELSE#ENDIF directives There three main directives used perform conditional assembly:
39/144
SOFTWARE TOOLS ASSEMBLER
Table
Directive Usage marks start conditional decides whether following zone will assembled not. optionally reserves condition previous following zone. marks previous #IF's.
#ELSE #ENDIF
condition given with '#IF' take form numeric expression; rule deciding whether resolves 'true' 'false' simple: zero value then it's false, else it's true. These directives should start column line, reserved labels.
Example:
{count %OUT 'true' #ELSE %OUT 'false' #ENDIF
This sequence would print 'true' label 'count' equal `false' didn't.
Example:
{count
%OUT count more than {count
%OUT .and more #ELSE %OUT .but more than two! #ENDIF
40/144
SOFTWARE TOOLS ASSEMBLER
#ELSE %OUT count more than #ENDIF
see, conditionals nested: #ELSE #ENDIF directive assumed assumed most recent unterminated #IF. Other special directives available:
Table
Directive #IF1 #IF2 Usage require conditional argument. appropriate pass being assembled, condition considered 'true'; instance #IF1 will considered true while assembler first pass, #IF2 while second pass. checks label definition. checks empty argument (i.e., empty, containing spaces tabs), useful testing macro parameter existence. False) similar #IF, checks negation condition argument. tests string equality between arguments separated space. This useful testing macro parameters against fixed strings. checks argument predefined label.
#IFDEF #IFB
#IFF
#IFIDN
#IFLAB
RUNNING ASSEMBLER 4.6.1 Command Line assembler needs following arguments:
<file assemble>, <listing file>, <switches>
41/144
SOFTWARE TOOLS ASSEMBLER
arguments left command line, you'll prompted remaining arguments.
Example:
SGS-THOMSON Microelectronics Assembler rel. File Assemble: game
example above, parameters were given command line, parameters were prompted for.
<file assemble> parameter assumes default suffix ".ASM". example, type 'game' then 'game.asm' actual filename used.
listing file file which assembly report sent selected. default filename (which displayed square brackets), made from path base-name file assemble. default filename suffix assembly report file ".LST". instance, type 'game', then 'game.lst' actual filename used.
Note that unless assembler told create either pass-1 pass-2 complete listing options argument, listing file will created.
4.6.2 Options Options always preceded with minus sign '-'. Upper lower cases accepted define options. Supported options are:
Table
Option -OBJ=<path> enable pass-2 listing enable pass-1 listing specify .OBJ file Function
42/144
SOFTWARE TOOLS ASSEMBLER
Table
Option -SYM -FI=<mapfile> enable symbol table listing disable phase errors specify 'final' listing mode #define Function
4.6.2.1 Option Description: Format: This option allows generation symbol table. <file> -sym output file <file>.sym Example: prog -sym
4.6.2.2 Option Description: Format: Request generate complete listing file. <file> output file <file>.lst Example: prog
4.6.2.3 Option Description: Format: Example: force .OBJ file generated specific directory using following option (note -obj: must last switch): <file> -obj=<directory> prog -obj=d:prog Force assembler generate object file 'd:prog.obj' 'user1/ prog.obj'.
43/144
SOFTWARE TOOLS ASSEMBLER
4.6.2.4 Option Description: side effect using linker that modules assembled separately, leaving inter modules' cross-references fixed linker. result assembler listing file unresolved references displays warning character. '-fi' option enables perform absolute patch desired listing. Therefore, must have produced listing file (.LST) linked your application compute relocations produce .COD file file. When want full listing generated, must have made edits since last link (otherwise named map-file would 'out date' module being assembled). This usually problem since full listings only needed after code been completed. automatically selects complete listing. Format: <file> -fi=<map-file> output <file>.LST contains absolute patches. Example: ex1+ex2,ex -fi=ex.map -fi=ex.map (produces ex1.lst) (produces ex2.lst) (produces ex.map, ex.cod) "LINKER" page (produces ex1.lst) (produces ex2.lst)
Note that when assembling '-fi' mode, assembler uses file produced linker, object files generated.
4.6.2.5 Option Description: switch allows define first string replaced second string during assembly. space needed between strings. This extremely useful changing assembly module using directives, because change value tests from assembler's command line. means that assembler with different switches same source file, produce different codes. Note that specify multiple switches, they should separated space.
44/144
SOFTWARE TOOLS ASSEMBLER
Example:
EPROM
4.6.2.6 option Description: Request generate pass-1 listing. means that this listing internal forward references known. They marked undefined with listing file. <file> output <file>.lst Example: file1
Format:
4.6.2.7 option Description: Format: Example: This option disables error generation. <file> file1
45/144
SOFTWARE TOOLS LINKER
LINKER
WHAT LINKER DOES After having separately assembled component modules your program, next step link them together into .COD file which then sent final destination using OBSEND.
This linking process just simple concatenation object modules. resolves external references. referenced label defined PUBLIC, error detected. also checks type relocation places segment according your mapping, checks them overrun.
INVOKING LINKER 5.2.1 Command Line linker needs following arguments:
<.OBJ file>[+<.OBJ file>.], [<.COD file>],[<lib>][+<lib>.]
arguments left command line, you'll prompted.
Example:
SGS-THOMSON Microelectronics Linker .OBJ files: begin .COD file [begin.cod]: begin Libraries:
.OBJ files simply list object files that form your program. .OBJ suffix left out, more than specified they should separated characters, example game+scores+keys would tell linker link 'game.obj', 'scores.obj' 'key.obj'. Object file path names should include characters. Character should avoided, except suffixes.
46/144
SOFTWARE TOOLS LINKER
.COD file default name formed first object file's name with forced suffix '.COD'. This will name file produced link session: contains information from link session special format: however, OBSEND must used .COD file before ready use. default filename what want, filename given prompt used instead. suffix will forced .COD left blank. default selected leaving this argument blank command line, pressing <ENTER> prompt. 'Libraries' prompt asks list library files generated utility that should searched case finding unresolved external references. format giving multiple libraries same .OBJ list, except suffix .LIB assumed.
Examples: Linking together modules game.obj, scores.obj, key.obj, game1.obj, game2.obj game3.obj without using libraries generating .COD file named game.cod, requires following command line: Linking same modules same environment, generating .cod file named prog.cod requires:
5.2.2 Response files Responses files text files that replace command line generate arguments required. Although they used assembler linker, only really makes sense them linker. command line given with name program execute (here LYN) only take characters argument. most programs this fine, linker allows to128 modules linked run; their names have declared linker first argument. This where response files come they allow redirect command line parser file instead expecting arguments come from command line keyboard. response file invoked giving sign filename response first argument want come from response file.
47/144
SOFTWARE TOOLS LINKER
filename assumed have suffix '.RSP' none supplied. Repeating example used earlier, this time with response file called game.rsp: @game.rsp that needs typed, file game.rsp must contain: game+scores+keys+ game1+ game2+game3 prog Which echoes what would have been typed keyboard. response file ends prematurely, remaining arguments prompted keyboard. very large session, .OBJ files argument won't line: continued next ending last .OBJ file first line with '+'. Note that when using response files, there must least carriage returns file. LINKING DETAIL 5.3.1 PUBLICs EXTERNs labels declared external modules being linked together must have corresponding PUBLIC definition another module. doesn't, error. Similarly, there must only PUBLIC definition given label.
bulk linker's filling those relative external blanks left assembler .OBJ files; lesser extent, also handles special functions such DATE SKIP directives. Equally important, collate together allocate addresses segments.
5.3.2 Segments Linker typical system look like diagram alongside: good candidate four different segments, perhaps named 'RAM0', 'RAM1', 'EPROM' 'ROM'. reset interrupt vectors live map, perhaps from FFEE-FFFF then might mark fifth segment called 'vectors' those addresses truncate 'ROM' FFED; that linker will warn 'ROM' much code that overflows into where vectors live.
48/144
SOFTWARE TOOLS LINKER
These classes would introduced follows: segment byte 0-FF segment byte 100-027F segment byte 8000-BFFF segment byte C000-FFDF segment byte FFE0-FFFF 'RAM0' 'RAM1' 'EPROM' 'ROM' 'VECTORS'
After their full introduction that needs only done once whole program, rest program refer classes just giving class names quotes:
Example:
segment 'RAM0' xtemp time ds.w ds.b segment 'ROM' A,#1 A,#10 temp storage register timer count index
this example followed immediately after class instruction 'xtemp' label would given value time would given C000. however, code several modules away from introduction with segments classes 'RAM0' 'ROM', then value allocated labels will depend much space used those modules. linker takes care this allocation. This linker handles problems relocatability; keep mind that this link system going have handle compiled code from high level languages you'll perhaps begin understand things have generalized much. segments we've looked <name> field, more accurately, they null name field. ensure that related segments same class, perhaps scattered over your modules with segments same class collated together contiguous area class memory giving them same name.
Example:
49/144
SOFTWARE TOOLS LINKER
grafix cursor_buf
segment byte 100-027F 'RAM1' ds.b buffer under cursor
segment byte 8000-BFFF 'ROM' show_page segment 'RAM1' field-buf ds.b {{256 mult 256}/8} segment 'ROM' dump_buf grafix cursor_temp A,field_buffer segment 'RAM1' ds.b
This complex sequence segments shows instances class 'RAM1' being used with segment name 'grafix'. Because first instance class 'RAM1' name 'grafix' 'grafix' RAM1 segments placed memory first followed nullname RAM1 segment (which defines 'field_buf'). Note this order segments code: segments with same name collated together (even from separate .OBJ files), lumps segments same name into memory order that names found .OBJ files.
explained assembler sections ("ASSEMBLER" page 18), your file suffix when introducing class, code that code sent into cod-file named file_x.cod, where file name first file, cod-file suffix (1-9).
5.3.3 Symbol Files successful link, more .OBJ files will have been combined into single .COD file. .MAP file will have been produced, containing textual information about segments, classes external labels used .OBJ module(s). Finally compact .SYM file generated, containing PUBLIC symbols found link with their final values. linker supports special feature link .SYM files from other link sessions. This means with huge programs, cannot only partition your code assembler level, divide code into 'lumps' which linked loaded separately, have access each other's label EXTERNs. 'link symbol table simply giving name with suffix .SYM. Always give symbol tables start object file list.
50/144
SOFTWARE TOOLS LINKER
File Example: prog1.sym+prog2,vectors,irq;
Once this done, PUBLIC symbols from prog1.sym available PUBLICs prog2.obj, vectors.obj irq.obj.
Because changes link will automatically update references changed link code other links, it's necessary when using this technique 'fix' each link area memory, have 'jump table' each area. This means that 'function' addresses permanently fixed jump table offset, changes each link will result automatic redirection jump targets start each routine. another way, each link must have entry fixed points routine, otherwise re-linking 'lump' program could make references addresses other modules date. LINKER MORE DETAIL. 5.4.1 Composition .OBJ Files .OBJ files produced assembler contain enormous amount overhead, mostly coded expressions describing exactly what needs into 'blank spaces' assembler been liberal with. linker contains full arithmetic parser 'working out' complex expressions that include external labels: This means (unlike most other assemblers) there restrictions where external labels appear.
assembler also includes line-number information with .OBJ file, connecting each piece generated object code with line number from given source file. files also contain 'special' markers handling SKIP DATE type directive.
5.4.2 Composition .COD Files .COD files, other hand, contain very little overhead: there bytes segment that describe start address length that segment; Besides that, rest code final form. segment zero length marks file. only remains OBSEND take code segment segment send destination.
51/144
SOFTWARE TOOLS LINKER
5.4.3 Reading Mapfile Listing linker also generates files with suffix .SYM .MAP addition .COD file have already discussed. .SYM file contains compact symbol table list suitable with debuggers simulators.
.MAP file listing shows three important things: table segments with their absolute address, table classes program, list external labels with their true values, modules they were defined size.
Here example MAPFILE, where class, ROM, gone past limit, overwriting more correctly, having part itself overwritten VECTORS.
[void] some segments segment list says that these segments were used create object code, were used non-coding-creating tasks such allocating label values with ds.b etc. number straight brackets segment true address list shows many segments 'into' module this segment i.e., 1st, etc. given module. first shows range addresses. (line) field external labels list shows source code file line number that label defined number start each class list line cod-file that class contents were sent (default
Segment Address List:
prog prog main prog main monitor monitor
108882825688448-
1456
01008000C000C509F579FFEE-
875B C508 F578 FFF9 FFFF
`RAM0' [void] 'RAM1' 'eprom' 'rom' 'rom' 'rom' 'vectors'
[void]
Class List:
52/144
SOFTWARE TOOLS LINKER
`RAM0' `RAM1' `eprom' `rom' `vectors'
byte from (lim
byte from (lim 27F) byte from 8000 875B (lim BFFF) byte from C000 FFF9 (lim FFDF) C*Overrun* byte from FFEE FFFF (lim FFFF) 100%
External Label List:
Symbol Name
Value
Size
Def(line)
char char1 label
ABCD
BYTE BYTE WORD
game.obj(10) game.obj(11) game.obj(25)
labels
external label list only includes labels that were declared PUBLIC: labels used internally module included. This table most useful debugging purposes, since values labels likely relocated between assemblies. labels given firstcharacter-alphabetic order.
53/144
SOFTWARE TOOLS OBSEND
OBSEND
WHAT OBSEND DOES After your program been assembled linked form '.COD' file needs sent place where it'll executed; your code just sitting disc file where target system can't
OBSEND general purpose utility .COD files various ways using various formats.
INVOKING OBSEND OBSEND follows same standard formats rest assembler linker; arguments given from command line, keyboard response file. general syntax
OBSEND
where <file> name .COD file formatted (default extension .COD). given command line, you're prompted keyboard with:
OBSEND SGS-THOMSON Microelectronics Obsend rel. File Send: test Destination Type (<f>ile,<v>ideo): Final Object code Filename [test.fin]: test.s19 Object Format <ENTER>=Straight Binary, <2>, <4>:
6.2.1 Destination Type <destination> (file) (video). Only single character required.
6.2.2 Destination Arguments When destination type (file) argument <filename> tells OBSEND where send code. default suffix '.FIN' assumed none given.
54/144
SOFTWARE TOOLS OBSEND
Example:
OBSEND test,f,image.s19,s
command generates file 'image.s19' containing code from 'test.cod', Srecord format. When destination code (video), this field void.
FORMAT DEFINITIONS <format> specifies output format:
Table
<format> <none> Output Format straight binary, i.e., image Intel Intel with 32-byte data line Intel extended Motorola S-record byte address, e.g. ST7) Motorola S-record extended with symbol file S-record bytes address, e.g. D950) S-record bytes address, e.g. ST18932 program space) 'Filled' straight binary format Industrial binary format
55/144
SOFTWARE TOOLS OBSEND
6.3.1 Straight Binary Format <format>= <none> This simplest formats. nothing bit-for-bit copy original file. This usual mode sending EPROM Emulators, etc., default format argument given.
Note: When destination screen (the destination code "v"), don't this format; otherwise will only weird control codes.
<format>= This `filled' straight binary format where gaps between adjacent segments filled with $FF.
6.3.2 Intel Format <format>= This format very much more complex. Intel Hex, bears similarities S-record that we'll looking later. Let's look line Intel format detail: 1900 number data bytes decimal) address record type data bytes checksum
first thing note that every thing printable ASCII. Eight numbers converted into two-characters hexadecimal representation.
Each line begins with ASCII ($3A) character. next characters form byte that declares many data bytes follow data byte section little further along. next four characters form 16-bit high-byte first number that specifies address first byte this data; rest follows sequentially.
56/144
SOFTWARE TOOLS OBSEND
next characters record type this line: data line, signals EOF. following characters until last data bytes this line and, last checksum line, calculated starting with subtracting real value characters sent after until checksum itself. 'Real value' means that example, characters should subtract from checksum, Every line ends with CR-LF combination, $0D. last line sent must END-OF-FILE line, which denoted line with data bytes record type instead Giving instead intel argument uses same format, sends bytes data line.
6.3.3 Motorola S-record Format <format>= This another complex method sending data. Again cuts data into 16-byte 'records' with overhead either sides. S-record come four types: known header record, data records with address fields, record. S10D0010E0006285E000628562856D 0010 record type number bytes left, address, data checksum decimal) address data bytes checksum
first characters define record type: next characters form hexadecimal representation numbers bytes left record (i.e., numbers characters This count must include checksum addresses bytes that follow. address field four characters wide characters wide most significant character always comes first. OBSEND will always type records wherever possible (i.e., when address less than $10000) type data records where (i.e., address $FFFF). data bytes then follow, with checksum appended end. checksum calculated starting with subtracting 'real value' bytes sent from including byte count field until checksum itself. this context, 'real value' means value byte before expanded into ASCII characters.
57/144
SOFTWARE TOOLS OBSEND
record concluded CR-LF combination $0A, $0D. (i.e., header EOF) records always same: S00600004844521B and: S9030000FC complete example S-record transmission look like: S00600004844521B S20801C004FFC0000073
<format>= extended S-record format, selected format sends code described above, except that after sends list records, after other, format: 0000 LABEL
where 0000 four ASCII zeroes, LABEL five ASCII characters. There spaces after space after 0000. 0000 represents hexadecimal value label. LABEL extend characters, with carriage return.
6.3.4 S-record Format <format>= <format>= These industrial formats defined specific needs. This format allows specify 2-byte words address. This format allows specify 4-byte words address.
6.3.5 Binary <format>= This format simple. 16-byte count beginning low-byte first, calculated starting adding value each byte until data reached. there 'gaps' your code, obsend will fill them with $FF, adjust checksum accordingly. After that four bytes header information, data follows block.
58/144
SOFTWARE TOOLS LIBRARIAN
LIBRARIAN
OVERVIEW work similar boards especially those with same processor, makes great deal sense reuse lumps code you've already written same task different program. simplest level, could just copy source code block text into program. This works fine, subtle disadvantage: update subroutine, have hunt around usages performing update each.
around this problem, many people have source common routines place, link .OBJ module with each program needing routine. Then only need update source code once, reassemble .OBJ file, then link again users routine, will have .OBJ file.
This scheme works good, too. generates some problems own. example, each routine needs .OBJ file. their nature, these common routines tend small, giving dozens extra .OBJ modules linker, having .OBJ modules scattered around your disc.
base concept librarian combine these small, useful .OBJ modules into large .LIB library file. could then tell linker about library, would take care sorting which .OBJ modules pull into link. would know which ones pull fact that main code being linked would have undefined externals, example, call missing library routines. librarian simply takes each undefined external turn, checks against modules library. modules declares PUBLIC same name, knows need that .OBJ module includes automatically. INVOKING LIBRARIAN librarian called LIB, takes command line argument that name library operate given, you'll prompted
[library name] .LIB added suffix left off.
library gave doesn't exist, asks it's library.
59/144
SOFTWARE TOOLS LIBRARIAN
Example:
LIB1 SGS-THOMSON Microelectronics Librarian 1.00 Couldn't open Library file 'LIB1.LIB' file? (y/n):
answer 'n', aborts. library exists, prints report library.
Library LIB1.LIB long. 16/1024 Public labels used 2/128 modules.
Next you're faced with main prompt:
LIB1.LIB: Operation (<ENTER> help):
Pressing ENTER gives access following options:
Table
Operation +filename -filename !filename *filename Description add/update object module to/in library delete object module from library update object module library copy object module separate file from library list contents library Exit
60/144
SOFTWARE TOOLS LIBRARIAN
ADDING MODULES LIBRARY Typing example: +user1\board would look file, called user1\board.obj, library. can't find named file, reports fact returns operations prompt. Else issues following message: Adding board.obj labels added Done. library already contained file board.obj, would prompt with:
board.obj already library LIB1.LIB, replace with board.obj (Y/N):
Responding with returns operations prompt, while first removes board.obj then continues above.
DELETING MODULES FROM LIBRARY This done example: -board cannot find board.obj current library, reports error aborts back operation prompt. find makes sure know what doing with:
board.obj deleted from library LIB1.LIB: sure (Y/N):
aborts operation prompt. continues, reporting:
Removing board.obj Done.
61/144
SOFTWARE TOOLS LIBRARIAN
COPYING MODULES FROM LIBRARY make copy .OBJ module library back disc, use, example: *board This will check existence board.obj current library, it'll report failure abort operation prompt. does find invites give name disc file create contain copy .OBJ module. Copy into .obj file [board.obj]:
type <ENTER>, it'll select original name object module copy's name. Otherwise, give path spec. file give already exists, says:
File board.obj already exists; overwrite? (Y/N):
Again, responding aborts operations prompt, while does copy with message:
Copying board.obj disk. Done. GETTING DETAILS YOUR LIBRARY last operation: causes print details current library. Library LIB1.LIB long 16/1024 Publics labels used 2/128 modules z1.obj (z1.asm) length board.obj (board.asm) length 7FFF name brackets source module from which named object module assembled.
62/144
SOFTWARE TOOLS Assembler Directives
Appendix
ASSEMBLER DIRECTIVES
Introduction Each directive been given section itself, entry index. name directive, which will always appear second field given heading section. Next there line showing arguments allowed any) this directive. penultimate section describes action directive format nature argument specified previous section, last section gives more example directive use. There 'see also' cross reference bottom page. directives must placed second, OPCODE, field, with arguments away argument field.
63/144
SOFTWARE TOOLS Assembler Directives
.BELL
Purpose: Format: Description:
Ring bell console. .BELL This directive simply rings bell console; used signal pass-1 pass-2 with #IF1 #IF2. This directive does generate assembly code data. .BELL
Example: Also:
64/144
SOFTWARE TOOLS Assembler Directives
BYTE
Purpose: Format: Description:
Define byte object code. BYTE <exp "string">,[,<exp "string">.] This directive forces byte(s) argument list into object code current address. argument composed complex expressions, which even include external labels. argument expression value greater than then lower bits expression used errors generated. String argument(s) must surrounded double quotes: theses translated into ASCII processed byte byte. It's generally used defining data tables. Synonymous with STRING DC.B.
Example:
BYTE 1,2,3 generates 01,02,03 BYTE "HELLO" generates 48,45,4C,4C,4F BYTE "HELLO",0 generates 48,45,4C,4C,4F,00
Also:
DC.B, STRING, WORD, LONG, DC.W, DC.L
65/144
SOFTWARE TOOLS Assembler Directives
BYTES
Purpose: Format: Description:
Label type definition type=byte. BYTES When label defined, separate attributes defined with scope (internally externally defined), value (actual numerical value label), relativity (absolute relative), length, (BYTE, WORD LONG). these attributes except length defined explicitly before definition: force label certain length giving suffix, 'label.b' forces byte length. also define default state label length: labels created this length unless otherwise forced with suffix. default WORD start assembly, changed BYTES, WORDS LONGS appropriate length.
Example: lab1
BYTES
byte length lab1
Also:
LONGS, WORDS
66/144
SOFTWARE TOOLS Assembler Directives
CEQU
Purpose: Format: Description:
Equate preexisting label expression. label CEQU <exp>
This directive similar EQU, allows change label's value. Used macros counter REPEAT UNTIL.
Example:
lab1
CEQU {lab1+1} lab1
Also:
EQU, REPEAT, UNTIL
67/144
SOFTWARE TOOLS Assembler Directives
.CTRL
Purpose: Format: Description:
Send control codes printer. .CTRL <ctrl>[,<ctrl>]. This directive used send printing printing control codes selected listing device. It's intended sending control codes embolden underline, etc. areas listing printer. arguments sent listing device listing currently selected. This directive does generate assembly code data.
Example:
.CTRL 27,18
Also:
.LIST, .NOLIST, .BELL
68/144
SOFTWARE TOOLS Assembler Directives
DATE
Purpose: Format: Description:
Define 12-byte ASCII date into object code. DATE This directive leaves message linker place date link 12-byte block assembler leaves spare position DATE directive. This means that every link will leave date object code, allowing automatic version control. date takes form ASCII) DD_MMM_YYYY where character represents space; example JUL. 1988. date left linker fill instead assembler since source code module containing DATE directive reassembled after every editing session would possible lose track.
Example:
DATE
Also:
69/144
SOFTWARE TOOLS Assembler Directives
DC.B
Purpose: Format: Description:
Define byte(s) object code. DC.B <exp "string">,[,<exp "string">] This directive forces byte(s) argument list into object code current address. argument composed complex expressions, which even include external labels. argument expression value greater than then lower bits expression used errors generated. String argument(s) must surrounded double-quotes: these translated into ASCII processed byte byte. It's generally used defining data tables. Synonymous with BYTE STRING.
Example:
DC.B 1,2,3 generates 01,02,03 DC.B "HELLO" generates 48,45,4C,4C,4F DC.B "HELLO",0 generates 48,45,4C,4C,4F,00
Also:
70/144
SOFTWARE TOOLS Assembler Directives
DC.W
Purpose: Format: Description:
Define word(s) object code. DC.W<exp>[, <exp>.] This directive forces word(s) argument list into object code current address. arguments composed complex expressions, which even include external labels. argument expression value greater than FFFF then lower bits expression used errors generated. DC.W sends words with most significant byte first. It's generally used defining data tables. Synonymous with WORD, except that DC.W places words High order.
Example:
DC.W 1,2,3,4,$1234
;0001,0002,0003,0004,1234
Also:
DC.B, BYTE, STRING, WORD, LONG, DC.L
71/144
SOFTWARE TOOLS Assembler Directives
A.10 DC.L
Purpose: Format: Description:
Define long word(s) object code. DC.L <exp>[,<exp>.] This directive forces long word(s) argument list into object code current address. arguments composed complex expressions, which even include external labels. argument expression value greater than FFFFFFFF then bits expression used errors generated. DC.L sends words with most significant byte first. It's generally used defining data tables. Synonymous with LONG, except that DC.L stores long-words High order.
Example:
DC.L 1,$12345678 LONG 1,$12345678
0000,0001,1234,5678 0100,0000,7856,3421
Also:
DC.B, DC.W, BYTE, STRING, WORD, LONG
72/144
SOFTWARE TOOLS Assembler Directives
A.11 #DEFINE
Purpose: Format: Description:
Define manifest constant. #DEFINE <CONSTANT <real characters> benefits using labels assembler level programming obvious well known. Sometimes, though, values other than straight numerics allowed labels used repeatedly programs ideal candidates 'labelifying'. #DEFINE directive allows define special labels called 'manifest constants'. These basically labels that contain strings instead numeric constants. During assembly, wherever manifest found source code, replaced real argument before assembly proceeds. #DEFINE definition label, space must precede declaration.
Example:
#define value a,#value
a,#5
Also:
73/144
SOFTWARE TOOLS Assembler Directives
A.12 DS.B
Purpose: Format: Description:
Define byte space object code. DS.B [optional number bytes] This directive used 'space out' label definitions. example let's need byte-sized temporary storage locations defined RAM, starting address $4000. could write: segment byte 4000 'RAM' temp1 temp2 $4000 $4001
which would work fine, however, recommend write: segment byte 4000 'RAM' temp1 temp2 DS.B DS.B
which does same job. advantage that incremented automatically. There other types instructions available doing WORD LONG length storage areas: DS.W DS.L. Note that areas question initialised value; it's merely allocating values labels. optional argument specifies many bytes allocate; default Because code generated fill space, allowed DS.B segments containing code, only segments with data definitions.
Example:
labl
DS.B
Also:
DS.W, DS.L
74/144
SOFTWARE TOOLS Assembler Directives
A.13 DS.W
Purpose: Format: Description:
Define word space object code. DS.W [optional number words] This directive used 'space out' label definitions. example let's need word-sized temporary storage locations defined RAM, starting address $4000. could write: segment byte 4000 'RAM' temp1 temp2 $4000 $4002
which would work fine, however, recommend write: segment byte 4000 'RAM' temp1 temp2 DS.W DS.W
which does same job. advantage that incremented automatically. There other types instructions available doing BYTE LONG length storage areas: DS.B DS.L. Note that areas question initialised value; it's merely allocating values labels. optional argument specifies many bytes allocate; default Because code generated fill space, allowed DS.W segments containing code, only segments with data definitions.
Example:
labl
DS.W
Also:
DS.B, DS.L
75/144
SOFTWARE TOOLS Assembler Directives
A.14 DS.L
Purpose: Format: Description:
Define long space object code. DS.L [optional number long words] This directive used 'space out' label definitions. example let's need long-word-sized temporary storage locations defined RAM, starting address $4000. could write: segment byte 4000 'RAM' temp1 temp2 $4000 $4004
which would work fine, however, recommend write: segment byte 4000 'RAM' temp1 temp2 DS.L DS.L
which does same job. advantage that incremented automatically. There other types instructions available doing BYTE WORD length storage areas: DS.B DS.W. Note that areas question initialised value; it's merely allocating values labels. optional argument specifies many bytes allocate; default Because code generated fill space, allowed DS.L segments containing code, only segments with data definitions.
Example:
labl
DS.L
Also:
DS.B, DS.W
76/144
SOFTWARE TOOLS Assembler Directives
A.15
Purpose: Format: Description:
source code. This directive marks assembly main source code file. directive supplied source-code file then illegal error will generated assembler. Include files require directive.
Example: Also:
77/144
SOFTWARE TOOLS Assembler Directives
A.16
Purpose: Format: Description:
Equate label expression. label <EXPRESSIONS> Most labels created program attached source code line that generates object code, used target jumps memory references. rest labels used 'constants', used example, hold port number system keyboard: number that will remain constant throughout program. directive allocates value, segment type length label field. value derived from result expression, relativity (absolute segment-relative derived from most recent segment), length BYTE, WORD LONG, derived from size default (starts WORD changed directives BYTES, WORDS LONGS).
Example: Also:
labl
78/144
SOFTWARE TOOLS Assembler Directives
A.17 EXTERN
Purpose: Format: Description:
Declare external labels. EXTERN When your program consists several modules, some modules need refer labels that defined other modules. Since modules assembled separately, until link stage that necessary label values going known. Whenever label appears EXTERN directive, note made linker resolve reference. Declaring label external just telling assembler expect that label defined this module, although will used. Obviously, external labels must defined other modules link stage, that gaps left assembler filled with right values. Because labels declared external actually defined, assembler knowing length, i.e., (byte, word long) label. Therefore, suffix must used each label EXTERN directive declaring type; type undefined, current default label scope (set BYTES, WORDS, LONGS directives) assumed.
Example:
EXTERN label.w, label1.b, label2.l
Also:
PUBLIC
79/144
SOFTWARE TOOLS Assembler Directives
A.18 #ELSE
Purpose: Format: Description:
Conditional ELSE. #ELSE This directive forces execution statements until next #ENDIF last statement found false disables execution statements until next #ENDIF last statement found true. #ELSE optional #ENDIF structures. case nested #ELSE statements, #ELSE refers last #IF.
Example: #ELSE block assembled #ENDIF block assembled
Also:
#IF, #ENDIF
80/144
SOFTWARE TOOLS Assembler Directives
A.19 #ENDIF
Purpose: Format: Description:
Conditional terminator. #ENDIF This optional terminator structure. there only level nesting force, then statements after this directive will never ignored, matter what result previous was. other words, #ENDIF ends capability previous suppress assembly. When used nested situation does same job, last #ENDIF structure block source suppressed previous still force, whole last #ENDIF structure will ignored matter what result previous was.
Example:
{count #ENDIF
Also:
#IF, #ELSE
81/144
SOFTWARE TOOLS Assembler Directives
A.20
Purpose: Format: Description:
Form constant string. <"string"> |<bytes> [<"string"> |<bytes>]. This directive works same common STRING directive, except that last character string argument (e.g. MSB) forced high. Numeric arguments same list left untouched.
Example:
"ALLO" STRING "ALLO"
41,4C,4C,CF 41,4C,4C,4F
Also:
STRING
82/144
SOFTWARE TOOLS Assembler Directives
A.21 .FORM
Purpose: Format: Description:
form length listing device. .FORM <exp> assembler paginates listing (when selected) with default lines page. This directive changes page length from default. This directive does generate assembly code data.
Example:
.FORM
Also:
TITLE, SUBTTL, %OUT, .LALL, .XALL, .SALL, .LIST,.NOLIST
83/144
SOFTWARE TOOLS Assembler Directives
A.22 GROUP
Purpose: Format: Description:
Name area source code. GROUP <exp> source code following GROUP directive until next GROUP directive file 'belongs' named group. Source code included inside group allocated special group called 'Default'.
Example:
GROUP mainloop
Also:
84/144
SOFTWARE TOOLS Assembler Directives
A.23
Purpose: Format: Description:
Start conditional assembly. <exp> Sometimes necessary have different versions program macro. This achieved completely SEPARATE programs macros, this solution associated problem that changes part program common versions requires them being changed, which tedious. Conditional assembly offers solution controlled 'switching off' assembly source code, depending value numeric expressions. structure known 'IF/ELSE/ENDIF': example format. #ELSE statement optional. expression resolves expression assumed have 'false' result: source code between false next #ENDIF #ELSE supplied) will assembled. #ELSE supplied, code following #ELSE will assembled only condition false. Conditionals nested levels: when nesting them, keep mind that each must have #ENDIF level, that #ENDIFs #ELSEs refer last unterminated #IF.
Example: %out true #FALSE %out false #ENDIF
Also:
#ENDIF, #ELSE, #IF1, #IF2
85/144
SOFTWARE TOOLS Assembler Directives
A.24 #IF1 Conditional
Purpose: Format: Description:
Conditional being pass #IF1 This directive works just like except argument only evaluates itself true assembler first pass through source code. #ELSE requires #ENDIF.
Example:
#IF1 %OUT "Starting Assembly" #ENDIF
Also:
#IF2, #ELSE, #IF, #ENDIF
86/144
SOFTWARE TOOLS Assembler Directives
A.25 #IF2
Purpose: Format: Description:
Conditional being pass #IF2 This directive works just like except argument evaluates itself true only assembler second pass through source code.
Example:
#IF2 %OUT "GONE through PASS-1 #ENDIF
Also:
#IF1, #IF, #ENDIF, #ELSE
87/144
SOFTWARE TOOLS Assembler Directives
A.26 #IFB
Purpose: Format: Description:
Conditional argument being blank. #IFB <arg> This directive works just like except doesn't evaluate argument: simply checks empty blank. Spaces count blank.
Example:
check
MACRO param1 #IFB param1 %OUT param1" #ELSE %OUT param1 #ENDIF MEND check check
Also:
#IF2, #ELSE, #IF, #END
88/144
SOFTWARE TOOLS Assembler Directives
A.27 #IFIDN
Purpose: Format: Description:
Conditional arguments being identical. #IFIDN <arg-1> <arg-2> This directive works just like except compares strings separated space. identical, result true.
Example:
check
MACRO param1 #IFIDN param1 HELLO %OUT "Hello" #ELSE %OUT Hello" #ENDIF MEND
Also:
#IF2, #ELSE, #IF, #END
89/144
SOFTWARE TOOLS Assembler Directives
A.28 #IFDEF
Purpose: Format: Description:
Conditional argument being defined. #IFDEF <exp> This directive works just like except tests argument being defined.
Example:
check
MACRO param1 #IFDEF param1 %OUT "Arg #ELSE %OUT "Arg undefined" #ENDIF MEND
Also:
#IF2, #ELSE, #IF, #END
90/144
SOFTWARE TOOLS Assembler Directives
A.29 #IFLAB
Purpose: Format: Description:
Conditional argument being label. #IFLAB <arg> This directive works just like except tests that argument valid, predefined label.
Example:
check
MACRO param1 #IFLAB param1 %OUT "LABEL" #ENDIF MEND
Also:
#IF2, #ELSE, #IF, #END
91/144
SOFTWARE TOOLS Assembler Directives
A.30 #INCLUDE
Purpose: Format: Description:
Insert external source code file. #INCLUDE "<filename>" INCLUDE files source code files same format normal modules with important differences: first line usually reserved processor name like other source line, they have directive. They used contain #DEFINE macro definitions that used many different modules your program. Instead having each module declare #DEFINE macro definitions, each module just includes contents same #INCLUDE file. assembler goes named INCLUDE file assembles this file before returning line after #INCLUDE directive former source code file. benefit that alterations made macro must done once, include file; you'll still have reassemble modules referring changed entry. NOTE that filename must inside double-quotes.
Example:
st7/ #include "defst7.h"
Also:
92/144
SOFTWARE TOOLS Assembler Directives
A.31 INTEL
Purpose: Format: Description:
Force Intel-style radix specifier. INTEL Intel style: 0ABh 100b Hexadecimal Octal Binary Decimal (default) Current program counter
This directive forces INTEL format required during assembly.
Example:
INTEL X,0FFFFh
Also:
MOTOROLA, TEXAS, ZILOG
93/144
SOFTWARE TOOLS Assembler Directives
A.32 .LALL
Purpose: Format: Description:
List whole body macro calls. .LALL This directive forces complete listing macro expansion each time macro invoked. This default. This directive does generate assembly code data.
Example:
.LALL
Also:
.XALL, .SALL
94/144
SOFTWARE TOOLS Assembler Directives
A.33 .LIST
Purpose: Format: Description:
Enable listing (default). .LIST This directive switches listing previous .NOLIST disabled -'pa' -'li' options must also have been from command line generate listing. This directive, conjunction with directive .NOLIST, used control listing macro definitions. This directive does generate assembly code data.
Example:
.LIST
Also:
.NOLIST
95/144
SOFTWARE TOOLS Assembler Directives
A.34 #LOAD
Purpose: Format: Description:
Load named object file link time. #LOAD "path-name[.ext]" This directive leaves message linker load contents named file current position current segment. file should 'straight binary' format, i.e., direct image bytes want into object code.
Example:
segment byte 8000-C000 'EPROM1' #LOAD "table.hex"
Also:
96/144
SOFTWARE TOOLS Assembler Directives
A.35 LOCAL
Purpose: Format: Description:
Define labels local macro. LOCAL <arg> macro that generates loop code gives rise assembly problem since loop label would defined many times macro called. LOCAL directive enables overcome this difficulty. Consider following piece code:
waiter MACRO loop A,ads jrne loop MEND
this macro called twice, will creating labels called 'loop'. answer declare very early MACRO labels created macro LOCAL. This effect replacing actual name local label (here 'loop') with LOCXXXX where XXXX starts from increments each time local label used. This provides each occurrence labels created inside macro with unique identity. Example:
waiter MACRO LOCAL loop loop A,ads jrne loop MEND
Also:
MACRO, MEND
97/144
SOFTWARE TOOLS Assembler Directives
A.36 LONG
Purpose: Format: Description:
Define long word object code. LONG <exp>[,<exp>.] This directive forces long word(s) argument list into object code current address. arguments composed complex expressions, which even include external labels. argument expression value greater than FFFFFFFF then bits expression used errors generated. LONG sends long words with least significant byte first. It's generally used defining data tables. Synonymous with DC.L, except that LONG sends low-byte first.
Example:
DC.L 1,$12345678 LONG 1,$12345678
0000,0001,1234,5678 0100,0000,7856,3421
Also:
DC.B, DC.L, DC.W, BYTE, STRING, WORD
98/144
SOFTWARE TOOLS Assembler Directives
A.37 LONGS
Purpose: Format: Description:
Default label length long. LONGS When label defined, four SEPARATE attributes defined with scope (internally externally defined), value (actual numerical value label), relativity (absolute relative), lastly, length (BYTE, WORD LONG). these attributes except length defined explicitly before definition: force label certain length giving suffix, 'label.b' forces byte length. also define default state label length: labels created this length unless otherwise forced with suffix. default WORD start assembly, changed BYTES, WORDS LONGS appropriate length.
Example: lab1
LONGS
long length lab1
Also:
BYTES, WORDS
99/144
SOFTWARE TOOLS Assembler Directives
A.38 MACRO
Purpose: Format: Description:
Define macro template. <macro> MACRO [param-1][,param-2]. This directive defines macro template that invoked later program. label field holds name macro: this name used invoke rest macro whenever found opcode field. arguments dummy names parameters that will passed macro when used: these dummy names will replaced actual calling line's arguments. Note: don't want definition macro listed, insert directive .NOLIST before macro definition, append directive .LIST after macro definition.
Example: cmp16 MACRO first,second,result LOCAL trylow A,first A,second A,#0 jreq trylow result,A MEND
trylow
Also:
MEND, .LALL, .SALL, .XAL
100/144
SOFTWARE TOOLS Assembler Directives
A.39 MEND
Purpose: Format: Description: Example:
macro definition. MEND macro definition.
cmp16
trylow
MACRO first,second,result LOCAL trylow A,first A,second A,#0 jreq trylow result,A MEND
Also:
MACRO
101/144
SOFTWARE TOOLS Assembler Directives
A.40 MOTOROLA
Purpose: Format: Description:
Force Motorola-style radix specifier. MOTOROLA Motorola style: %100 Hexadecimal Octal Binary Decimal (default) Current program counter
This directive forces Motorola format required during assembly. default format MOTOROLA.
Example:
MOTOROLA X,$FFFF
Also:
INTEL, TEXAS, ZILOG
102/144
SOFTWARE TOOLS Assembler Directives
A.41 .NOCHANGE
Purpose: Format: Description:
List original #define strings. .NOCHANGE Strings named first argument #DEFINE directive will changed second argument #DEFINE: default that changed strings will listed. want original source code listed instead, place .NOCHANGE directive near start your source code. This directive does generate assembly code data.
Example:
.NOCHANGE
Also:
#DEFINE
103/144
SOFTWARE TOOLS Assembler Directives
A.42 .NOLIST
Purpose: Format: Description:
Turn listing. .NOLIST Certain parts your modules required listing; this directive disables listing until next .LIST directive. default listing enabled. This directive, conjunction with directive .LIST, used control listing macro definitions. This directive does generate assembly code data.
Example:
.NOLIST
Also:
LIST
104/144
SOFTWARE TOOLS Assembler Directives
A.43 %OUT
Purpose: Format: Description:
Output string console. %OUT string This directive prints argument (which does need enclosed quotes) console. This directive does generate assembly code data.
Example:
%OUT hello!
Also:
105/144
SOFTWARE TOOLS Assembler Directives
A.44 .PAGE
Purpose: Format: Description:
Perform form feed. .PAGE Forces page listing. This directive does generate assembly code data.
Example:
.PAGE
Also:
106/144
SOFTWARE TOOLS Assembler Directives
A.45 PUBLIC
Purpose: Format: Description:
Make labels public. PUBLIC <arg> This directive marks given labels defined during assembly 'PUBLIC', i.e., accessible other modules. This directive related EXTERN; module wants label defined another, then other module must have that label declared PUBLIC. label also declared PUBLIC definition preceding label name with dot; won't need declared PUBLIC directive then.
Example:
module1.asm EXTERN print.w, print1.w call print print1 module2.asm PUBLIC print print .print1
Also:
EXTERN
107/144
SOFTWARE TOOLS Assembler Directives
A.46 REPEAT
Purpose: Format: Description:
Assembly-time loop initiator. REPEAT Used together with UNTIL make assembly-time loops; useful making tables etc. This directive should used within macros.
Example:
REPEAT
Also:
CEQU, UNTIL
108/144
SOFTWARE TOOLS Assembler Directives
A.47 .SALL
Purpose: Format: Description:
Suppress body called macro. .SALL This directive forces complete suppression listing macro expansion each time macro invoked. This instruction itself never listed. Note:This directive produce confusing listings.
Example:
.SALL
Also:
.LALL, .XALL
109/144
SOFTWARE TOOLS Assembler Directives
A.48 SEGMENT
Purpose: Format: Description:
Start segment. [<name>] SEGMENT <align> <combine> '<class>' [cod] SEGMENT directive very important: every module your program will need least one. <name> field characters length, include underscores. <align> field following:
Align Type:
byte alignment; start byte boundaries word aligned next word boundaries necessary, i.e., 8001=8002 para aligned next paragraph (=16 bytes) boundary, i.e., 8001=8010 aligned next 64-byte boundary, i.e., 8001=8040 aligned next 128-byte boundary, i.e., 8001=8080
page aligned next page (=256 bytes) boundary ,i.e., 8001=8100 long aligned next long-word(=4 bytes) boundary, i.e., 8001=8004 aligned next boundaries, i.e., 8001=8400 aligned next boundaries, i.e., 8001=9000
110/144
SOFTWARE TOOLS Assembler Directives
SEGMENT (Continued)
Combine:at
X[-Y] <none> common
Introduces class that starts from goes through address Address optional. Tack this code last segment this class. segment same address than other common segments that have same name, note longest length segment. optional [cod] suffix number from decides into which. file linker sends contents this class. default chosen suffix left off. suffix will cause linker open [cod] suffix, send contents this class into file instead default. This allows bank switching supported directly link level- different code areas same address separated into different .cod files.
Also:
more information, Chapter "Segmentation" page
111/144
SOFTWARE TOOLS Assembler Directives
A.49 .SETDP
Purpose: Format: Description:
base address direct page. .SETDP <base address> have used processor you'll aware 'zero-page' 'direct' addressing modes. These addresses range 00.FF shorter, faster instructions than more general 0000.FFFF versions. Other processors, same scheme twist choose 'base page', that direct mode does have range 0000 00FF from nn00.nnFF where nn00 'base page', loaded into register run-time. Because assembler cannot track what's base page register run-time, need fill about current 'base page' with .SETDP directive. start assembly, SETDP defaults 0000.
Example:
.SETDP $400 A,$401
direct mode chosen
Also:
112/144
SOFTWARE TOOLS Assembler Directives
A.50 SKIP
Purpose: Format: Description:
Inserts given number bytes with initialization value. SKIP <number bytes>,<value fill> This directive leaves message linker that want number bytes inserted into object code this point. Both arguments must absolute values rather than external relative values.
Example:
SKIP 100,$FF
insert bytes
Also:
113/144
SOFTWARE TOOLS Assembler Directives
A.51 STRING
Purpose: Format: Description:
Define byte-level string. STRING <exp "string">,[,<exp "string">.] This directive forces byte(s) argument list into object code current address. arguments composed complex expressions, which even include external labels. argument expression value greater than lower bits expression used errors generated. String argument(s) must surrounded double-quotes: these translated into ASCII processed byte byte. It's generally used defining data tables. Synonymous BYTE DC.B.
Example:
STRING 1,2,3 generates 01,02,03 STRING "HELLO" generates 48,45,4C,4C,4F STRING "HELLO",0 generates 48,45,4C,4C,4F,00
Also:
DC.B, BYTE, WORD, LONG, DC.W, DC.L,
114/144
SOFTWARE TOOLS Assembler Directives
A.52 SUBTTL
Purpose: Format: Description:
Define subtitle listing heading. SUBTTL "<Subtitle string>" This directive related TITLE directive: argument used subtitle beginning each page listing. recommend that individual subtitles generated each module program, while TITLE defined once include file called modules. This directive does generate assembly code data.
Example:
SUBTTL "A/D control routines"
Also:
TITLE
115/144
SOFTWARE TOOLS Assembler Directives
A.53 .TAB
Purpose: Format: Description:
listing field lengths. .TAB Sets size four source code fields listings. defaults 80-column printer; yours wider, need tell assembler using this directive. four fields width label field, opcode field, operand comment. This directive does generate assembly code data.
Example:
.tab 10,6,16,40
Also:
.LIST, .NOLIST
116/144
SOFTWARE TOOLS Assembler Directives
A.54 TEXAS
Purpose: Format: Description:
Texas-Instrument style radix specifier. TEXAS Motorola style: ?100 Hexadecimal Octal Binary Decimal (default) Current program counter
This directive forces Texas format required during assembly.
Example:
TEXAS X,>FFFF
Also:
INTEL, MOTOROLA, ZILOG
117/144
SOFTWARE TOOLS Assembler Directives
A.55 TITLE
Purpose: Format: Description:
Define main title listing. TITLE "<Subtitle string>" first fifty-nine characters argument (which must enclosed double-quotes) will included first line each page listing main title listing. suggest title include file called each module your program, give each module separate subtitle (see SUBTTL section). This directive does generate assembly code data.
Example:
TITLE "ST7 controller program"
Also:
SUBTTL
118/144
SOFTWARE TOOLS Assembler Directives
A.56 UNTIL
Purpose: Format: Description:
Assembly time loop terminator. UNTIL <exp> Related REPEAT directive: expression argument resolves zero value then assembler returns line following last REPEAT directive. This directive cannot used inside macros.
Example:
CEQU REPEAT DC.L mult val} CEQU {val+1} UNTIL {val
Also:
CEQU, REPEAT
119/144
SOFTWARE TOOLS Assembler Directives
A.57 WORD
Purpose: Format: Description:
Define word object code. WORD <exp>[, <exp>.] This directive forces word(s) argument list into object code current address. arguments composed complex expressions that even include external labels. argument expression value greater than FFFF then lower bits expression used errors generated. WORD sends words with least significant byte first. It's generally used defining data tables. Synonymous with DC.W.
Example:
WORD 1,2,3,4,$1234
;0001,0002,0003,0004,1234
Also:
DC.B, BYTE, STRING, DC.W, LONG, DC.L
120/144
SOFTWARE TOOLS Assembler Directives
A.58 WORDS
Purpose: Format: Description:
Default label length word. WORDS When label defined, four SEPARATE attributes defined with scope (internal external defined) value (actual numerical value label) relativity (the label ABSOLUTE RELATIVE), lastly length (BYTE, WORD, LONG). these attributes except length defined explicitly before definition: force label certain length giving suffix, 'label.b' forces byte length. also define default state label length: label created this length unless otherwise forced with suffix. default WORD start assembly, CHANGED BYTES, WORDS LONGS appropriate length.
Example: lab1
WORDS
word length lab1
Also:
BYTES, WORDS
121/144
SOFTWARE TOOLS Assembler Directives
A.59 .XALL
Purpose: Format: Description:
List only code producing macro lines. .XALL This directive forces reduced listing macro expansion each time macro invoked. Only those lines macro that generated object code listed. This instruction itself listed. This directive does generate assembly code data.
Example:
.XALL
Also:
.LALL,.SALL
122/144
SOFTWARE TOOLS Assembler Directives
A.60 ZILOG
Purpose: Format: Description:
Force Zilog-style radix specifiers. ZILOG Motorola style: %(8)17 %(2)100 Hexadecimal Octal Binary Decimal (default) Current program counter
This directive forces Zilog format required during assembly.
Example:
ZILOG X,%FFFF
Also:
INTEL, MOTOROLA, TEXAS
123/144
SOFTWARE TOOLS Assembler Directives
124/144
SOFTWARE TOOLS Error Messages
Appendix
ERROR MESSAGES
Format Error Messages There classes errors trapped assembler: fatal recoverable. fatal error stops assembly there then, returning caller (which DOS; also invoke assembler) with message error number describing problem.
actual format error messages follows:
file.asm(line): as<pass> Error <errno> <message> '<text>'
Example:
prog.asm(10): Error Doubly defined label 'fred'
error number
string describing error
name program that handled error line number file name file where error found
Notes name program that handled error (third field), depending pass progress when error found. error number (fourth field) used index find more complete description error next section (fatal errors read 'FATAL instead 'ERROR nn').
125/144
SOFTWARE TOOLS Error Messages
File CBE.ERR Fatal recoverable errors both copied into file CBE.ERR they occur. this error file give automatic error-finding. Most linker errors also copied into CBE.ERR.
LINKER errors described page 133.
ASSEMBLER ERRORS Empty file assembler couldn't read even first line given source code file. while Macro Definition file ended while macro being defined; should last macro definition properly with MEND. Couldn't return place source file 'X.asm' This error should never occur; implies have disc fault some kind. After #include, assembler returns line after #include itself. cannot return that line this error produced. Illegal Source Main source code files must with directive carriage-return. before line terminator directive must have least after example <TAB> <EOF> will generate this error while <TAB> <EOF> will work fine. Code produced outside Segment code produced assembler going have placed given address target system day. Since segments assemblers allocating addresses lumps code, code generated before first SEGMENT directive nonsense. Move line current window Move last line current window Undo changes last edited line
126/144
SOFTWARE TOOLS Error Messages
Drop start black marker Drop black marker Find Source Code address Report value given label Report address current Editor line These functions mostly explain themselves; Alternate functions same original functions same name: having indexes same allows cursor keys control codes move cursor, whichever user prefers. Some indexes used default sequence matrix; these allow some WordStar-like commands implemented with more meaning. Multiple-key sequences, such those found WordStar format control codes need implemented follows: take sequence <^Y><L>, i.e., CTRL-Y followed letter should coded ^Y+L where denotes that following character needs CTRL SHIFT. File capture Error #Include problems finding named file. Can't find position Source File Again with #include, another 'impossible' error reporting that couldn't find current position source file remember after #include. Can't have more than #defines Each #define checked each possible position each source line: having tons them slows assembly noticeably. Although have #defines, there also limits storage space both arguments (error 23); average eight characters both arguments catered for. #define storage space Error #define second argument #define requires space between parts argument delimit #define storage space above; you've reached limit storage space aside second argument #defines. strings DC.W Strings only allowed parts BYTE, DC.B STRING directives.
127/144
SOFTWARE TOOLS Error Messages
strings DC.L Strings only allowed parts BYTE, DC.B STRING directives. Illegal External Suffix Only suffixes legal after external label external directive. suffix left then default label size used BYTES, WORDS LONGS; default WORDS). Character public line More than four characters single quotes This assembler uses double-quotes surround string items single-quotes surround character constants. "Source Code Format" page Uneven Single Quotes Single-quoted items must have closing quote delimit. Sequential operator error does allow arithmetic operators hard against each other. lvalue Expression. lvalue left-hand argument operator: lvalue. would cause this error. Divide zero Attempt divide number zero, numeric expression. nested past levels Exceeded maximum number nested statements. Spurious ELSE ELSE discovered when active force. Spurious ENDIF ENDIF discovered when active force. Only allowed inside Macros LOCAL directive attempted outside Macro definition. strings Word Error string Long Error REPEAT this UNTIL
128/144
SOFTWARE TOOLS Error Messages
UNTIL directive found with matching REPEAT directive. Couldn't return place Source Similar Error generated UNTIL instead #include. Syntax Error SKIP arguments SKIP expects numeric arguments, separated comma. First SKIP argument extern/relative; SKIP aborted SKIP arguments must known assembler absolutely. Extern relative arguments allowed, although arithmetic need move page, example, SEGMENT same class with page align type. Second SKIP argument extern/Relative; SKIP aborted Error Undefined label This error happens when reference made undefined label. label space maximum 1024 labels allowed module, aside contain their names. either these limits exceeded, this error results. module into smaller ones; assemblies will happen twice fast you'll only have reassemble half you've made changes speeding things Label more than characters Labels longer than characters allowed. Label defined PUBLIC twice This warning occurs same label appears more than once PUBLIC statement. It's trapped because second appearance mistype slightly different label wanted declared public. Doubly Defined label This happens when label defined twice more. Phase Inconsistency (P1=X,P2=Y) 'label' Reports that named label allocated different values from pass-1 pass-2, implies awful things. It's generally caused when some reason assembler generated different lengths same instruction between pass-1 pass-2. Sometimes assembler problems identifying which addressing mode wanted particular instruction because mistypes, labels that discovered undefined during second pass give error (see Error create object code that line. labels after that line will then allocated different values
129/144
SOFTWARE TOOLS Error Messages
seeing object code that many bytes shorter, causing tons Phase Inconsistency errors. Because this mass Error sometimes hide real cause error, special assembler switch phase [errors]' used switch them off. strongly suggest that don't always your assemblies; only when need might miss critical phase errors. Public Symbol Undefined defined symbol PUBLIC directive that defined module. Missing Number assembler expect number found zero length. Can't match Addressing Mode This error catchall assembler cannot anything wrong with your line cannot match known addressing mode either. There main causes errors: significant ordering numeric range errors. significant ordering error simple mistype: what should have been (val),y coded (valy, whatever. components addressing mode properly formed; it's just that ordering wrong. numeric range errors harder detect. example, 8-bit relative branch branching range would trapped addressing mode error. diagnostics what went wrong assembler dumps model line screen just before error. Numerics printed value followed attribute string: INTernal, EXTernal, ABSolute, RELative Significands printed characters they represent, strings printed with their string. Numeric range errors also trapped link stage (See "What linker does" page 46). PSIG Index 'impossible' error that could only occur through corruption .TAB file. Un-recognized Opcode Opcode (second field) could matched against opcode names this instruction set, could matched against macro names directives. closing quote String must have closing double-quote before line. more than Numerics allowed line These's limit Numeric units allowed line: this usually only matters long DC.B-type directives where data tables being defined. it's problem, simply offending long line into shorter lines.
130/144
SOFTWARE TOOLS Error Messages
space Macro Definition Macro Storage area 64K) been overflowed. must have some really macros! many Macros Attempted There limit Macros allowed source code module. Mend only allowed Macro MEND directive found with matching MACRO directive. closing single Quote error Ending Another 'impossible' error, saying that source code line missing. Character line each source code line read into assembler it's checked non-ASCII characters (i.e., >128). Parameter Mismatch macro definition implies that there different number parameters than there actually were this calling line. Currently Unknown Numeric type error your Tabgen File, corrupted .TAB file: numeric handler asked check number against undefined numeric type. using latest version ASM.EXE your. file Improper Characters Unusual characters have been spotted source file, value >127. Label used before EXTERN definition Labels must declared EXTERNAL before their use, preferably group file. Ambiguous Label Name label name single-quotes error-line confused with register name this instruction set. Change name. Cannot have DS.X segments containing code/data! (only [void] segs!) DS.X does produce code; simply advances assembler's notional Program Counter. cannot used same segment real 'code' data.
131/144
SOFTWARE TOOLS Error Messages
Cannot have code segments previously containing DS.X (only non-void segs!) DS.X does produce code; simply advances assembler's notional Program Counter. cannot used same segment real 'code' data. Constant large directive 'value' DC.B cannot given argument >255, example. OFFSET operators truncate wild arguments. Couldn't find entry segment mapfile This listings produced with '-fi' option. Complex include file structures empty segments sometimes throw assembler track. index only allowed Introduction When you're using multiple linker output file scheme, only specify linker output file number particular class time that class's introduction. #LOAD before Segment! #load given address! Before first segment assembler won't know what address Shift #load after SEGMENT directive. #LOAD before Segment! assembler problems finding file you've named #LOAD directive. EQUs Involving External args must before first segment! Cannot nest #includes levels Couldn't find label list mapfile Happens with option '-fi' Implies problem with mapfile itself, unsuccessful previous link, etc. Couldn't find label mapfile above. Mapfile date with your Edits label declared EXTERN, never used. Couldn't find label mapfile date info stored given address before SEGMENT there address information assembler work string given line? used defining strings. there string this line? intend that? DC.B BYTE. Address WORD boundary
132/144
SOFTWARE TOOLS Error Messages
68000 certain other genuine 16-bit, Opcodes must word boundary. This error occurs have assembled instruction address. Your processor would crash! Byte size label value >255 (need WORDS?) Word size label value 65535 (need LONGS?) Over Macline Pull Internal Error. Source File Internal Error. arguments incorrect Must order num, num, num, example,
LINKER ERRORS File List must supplied Incomplete Object File Fatal error linker identified that given object file been truncated. disc space? Size mismatch EXTERN from says PUBLIC from says When declared PUBLIC file label given size attribute However, when came file EXTERN statement named being size they didn't tally. They must. Find which incorrect alter info start address class 'class' first time linker sees class (remember goes through object files order given link command line), must given full 'introduction' class, with start stop addresses. "Segmentation" page many secondary externals (32) Secondary Externals ought occur only rarely your code you're using then your structure something seriously wrong with Hint your labels that used over place, like constants, addresses like: make module just them, just containing EQUs and/or DS.Xs, declared public. arithmetic needs
133/144
SOFTWARE TOOLS Error Messages
doing more than once throughout your code, there, declare result with public label. Then refer these PUBLICs using simple EXTERNs each module. Corrupted Object File Disc Nastiness. Reassemble. There object code inconsistency: re-assemble files, link again. Public same name secondary EXTERN already exists! This error cannot seen until link time. Rename other. many XREFs link (12048) Undefined EXTERN (from Couldn't seek back file 'F1' Internal Error. Should never occur. Unexpected Disc nastiness. Reassemble. Byte size >Offh 'value' Needs looking what intended, either operator upper bits, change size attribute.
134/144
Index
Symbols
.asm .cod .11, .fin .lib .map .obj. .rsp .s19 .sym .tab assembler switch sign (linker) character. labels asli.bat assembler (role). assembler options -li. -obj -sym attributes byte externally internally linker relative absolute long relativity .20, scope .20, size word autoexec.bat.
Numerics
128-byte boundary 16-byte boundary 1k-byte boundary 256-byte boundary characters. 4-byte boundary 4K-byte boundary 64-byte boundary 80-column printer
cbe.err .18, CD-ROM class-names combine .34, common .34, Combine argument segment comments conditional assembly conditionals (nesting). constants .25, copied code cross-references
address representation align byte long page para word Align argument segments ampersand ('&') character.
delivery package directives #DEFINE. #ELSE
135/144
Index
#ENDIF. #IF1 #IF2 #IFB #IFDEF #IFIDN #IFLAB #INCLUDE #LOAD %OUT .BELL .CTRL .FORM .LALL .LIST .NOCHANGE 103, .NOLIST .PAGE. .SALL .SETDP .TAB .XALL BYTE BYTES CEQU DATE DC.B DC.L DC.W DS.B DS.L DS.W EXTERN.22, GROUP INTEL LOCAL LONG LONGS MACRO MEND MOTOROLA PUBLIC REPEAT SEGMENT SKIP STRING SUBTTL TEXAS TITLE UNTIL WORD WORDS ZILOG.
environment variable (METAI) errors #define second argument #LOAD before Segment! Address WORD boundary. EQUs Involving External args must before first segment! Ambiguous Label Name Character line Character public line Ending PSIG Index Byte size >Offh 'value' Byte size label value >255 Can't find position Source File Can't have more than #defines
Can't match Addressing Mode Cannot have code segments previously containing DS.X. Cannot have DS.X segments containing code/data!. Cannot nest #includes levels index only allowed Introduction Code produced outside Segment. Constant large directive 'value'
Corrupted Object File Couldn't find entry segment map-
136/144
Index
file. Couldn't find label mapfile Couldn't find label list mapfile Couldn't return place Source
Couldn't return place source file 'X.asm' Couldn't seek back file 'F1'. Currently Unknown Numeric type Divide zero Doubly Defined label Empty file before line terminator while Macro Definition File capture Error File List must supplied First SKIP argument extern/relative
label space space Macro Definition Over Macline Pull Parameter Mismatch Phase Inconsistency (P1=X,P2=Y) 'label' Public same name secondary EXTERN already exists! Public Symbol Undefined #define storage space
#define storage space
nested past levels. Illegal External Suffix Illegal Source Improper Characters Incomplete Object File Label defined PUBLIC twice Label more than characters Label used before EXTERN definition Mend only allowed Macro Missing Number More than four characters single quotes. closing quote closing single Quote info start address class 'class' lvalue Expression more than Numerics allowed line REPEAT this UNTIL string given line? string Long strings DC.L strings DC.W strings Word Only allowed inside Macros
Source File Second SKIP argument extern/Relative Sequential operator error Size mismatch EXTERN from says PUBLIC from says Spurious ELSE Spurious ENDIF Syntax Error SKIP arguments arguments incorrect many XREFs link (12048) many Macros Attempted many secondary externals (32)
Undefined EXTERN (from Undefined label. Uneven Single Quotes Unexpected Un-recognized Opcode Word size label value 65535133 executable files executables LIB. OBSEND. expressions extended S-record format external label list
137/144
Index
files asli.bat autoexec.bat cbe.err readme.txt response files setup.exe st7.tab st7vars.bat formats INTEL MOTOROLA TEXAS ZILOG
machine description files macro parameters macros mapfile listing METAI variable module (segments modules linked MOTOROLA format MOTOROLA S-record format
Name segment nested levels nesting conditionals number representation numbers $ABCD %(2)100 %(8)665 %100 %ABCD &ABCD >ABCD ?100 ~665 0ABCDH 100B 665O 665Q
binary Industrial binary format
INCLUDE files installation directory INTEL format INTEL format
label structure labels with librarian library files linker linker (role) linker (segments linking modules listing file LOCXXXX
object file OBSEND OBSEND (role) obsend formats
138/144
Index
i32. Opcodes Operands operators bnot high lnot mult offset precedence sexbl sexbw sexwl wnot
radix readme.txt representation addresses representation numbers. response files role OBSEND role assembler role linker
segment segment address list Segment name segmentation segments linker setup.exe SKIP aborted source files S-record S-record format st7.tab. st7vars.bat straight binary format .55, string constants suffixes .asm .11, .cod .fin .11, .lib .lst .map .obj .rsp .s19 .11, .sym .tab
pass-1,-2 pass-1,-2 listing precedence (operators) program counter PUBLIC labels
table segments TEXAS format
139/144
Index
tool-chain
utilities asli.bat
ZILOG format
140/144
THIS PAGE INTENTIONALLY LEFT BLANK
141/144
SALES OFFICES
EUROPE
DENMARK
2730 HERLEV Herlev Torv, Tel.: (45-44) 94.85.33 Telefax: (45-44) 948694
ITALY
20090 ASSAGO (MI) V.le Milanofiori Strada Palazzo A/4/A Tel.: (39-2) 57546.1 linee) Telefax: (39-2) 8250449 40033 CASALECCHIO RENO (BO) Fucini, Tel.: (39-51) 591914 Telefax: (39-51) 591305 00161 ROMA Torlonia, Tel.: (39-6) 44251142 Telefax: (39-6) 85354438
FINLAND
LOHJA SF-08150 Ratakatu, Tel.: (358-19) 32821 Telefax.: (358-19) 3155.66
FRANCE
94253 GENTILLY Cedex avenue Gallieni Tel.: (33-1) 47.40.75.75 Telefax: (33-1) 47.40.79.10 67000 STRASBOURG Place Halles Tel.: (33-3) 88.75.50.66 Telefax: (33-3) 88.22.29.32
NETHERLANDS
5652 EINDHOVEN Meerenakkerweg Tel.: (31-40) 2509600 Telefax: (31-40) 2528835
POLAND
WARSAW 00517 Marszalkowska Tel.(0048-22) 0561 Telefax: (0048-22) 6437
GERMANY
D-85630 GRASBRUNN Bretonischer Ring Postfach 1122 Tel.: (49-89) 460060 Telefax: (49-89) 4605454 D-30916 ISERNHAGEN Ernst-Grote-Strasse Tel. (49-511) 9027513 Telefax: (49-511) 90275555 D-90491 Erlenstegenstrasse, Tel.: (49-911) 959840 Telefax: (49-911) 9598499 D-70499 STUTTGART Mittlerer Pfad Tel.: (49-711) 13968-0 Telefax: (49-711) 8661427
SPAIN
E-08004 BARCELONA Calle Gran Corts Catalanes, Floor, Door Tel.: (34-3) 4251800 Telefax: (34-3) 4253674 E-28027 MADRID Calle Albacete, Tel. (34-1) 4051615 Telefax: (34-1) 4031134
SWEDEN
S-16421 KISTA Borgarfjordsgatan, 1094 Tel.: (46-8) 7936920 Telefax: (46-8) 7504950
SWITZERLAND
1215 GENEVA Route Tel.: (41-22) 9292929 Telefax: (41-22) 9292900
UNITED KINGDOM EIRE
MARLOW, BUCKS Planar House, Parkway Globe Park Tel.: (44-1628) 890800 Telefax: (44-1628) 890391
Internet Address http://www.st.com (Home Page) Product Support
SALES OFFICES
AMERICAS
BRAZIL
05413 PAULO Henriqu
Other recent searches
SY100E122 - SY100E122 SY100E122 Datasheet
RFG50N06 - RFG50N06 RFG50N06 Datasheet
RFP50N06 - RFP50N06 RFP50N06 Datasheet
QL2020L - QL2020L QL2020L Datasheet
PM50RSA120 - PM50RSA120 PM50RSA120 Datasheet
ICS1890 - ICS1890 ICS1890 Datasheet
ISO9001 - ISO9001 ISO9001 Datasheet
QS9000 - QS9000 QS9000 Datasheet
IBM11M16730CB16M - IBM11M16730CB16M IBM11M16730CB16M Datasheet
IBM11M16735B - IBM11M16735B IBM11M16735B Datasheet
IBM11M16735C - IBM11M16735C IBM11M16735C Datasheet
HM200102 - HM200102 HM200102 Datasheet
HM112 - HM112 HM112 Datasheet
FM4032W - FM4032W FM4032W Datasheet
DUR57A - DUR57A DUR57A Datasheet
2SA1171 - 2SA1171 2SA1171 Datasheet
Privacy Policy | Disclaimer
© 2012 Datasheet Archive
