 |
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
| Datasheet File OCR Text: |
| ST7ASMLK ASSEMBLER, LINKER, FORMATTER, AND LIBRARIAN FOR THE ST7 FAMILY PREFACE Purpose of the Manual This manual describes how to use the ST7 software tools, allowing you to develop applications for the ST7 family of microcontrollers: These tools are part of a generic tool-chain development system that includes: * a meta-assembler: * a generic linker: * a generic formatter: * a generic librarian: Audience This book is intended for persons who need to know how to write, assemble and run programs designed for ST7 microcontrollers. No preliminary knowledge in the field of microcontrollers is required, however. ASM LYN OBSEND LIB Related Publications The reading of the following publications will be profitable: * ST7-Family Data Sheets, * ST7-Family Starter Kit, Getting Started, Ref. Doc-ST7MDTx-KIT * ST7-Family Development Kit, Getting Started, Ref. Doc-ST7MDTx-DVP * ST7-Family Programming Manual, * Windows Debugger for the ST7 Family, Ref. Doc-ST7-WGDB7. This manual will help you debug and finalize your programs. Rev. 1.2 July 1998 1/134 15 Table of Contents ST7 SOFTWARE TOOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1 TOOL-CHAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2 ASM (ASSEMBLER) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3 LYN (LINKER) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.4 OBSEND (FORMATTER) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2 INSTALLATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3 ST7 ADDRESSING MODEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2 INHERENT ADDRESSING MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.3 IMMEDIATE OPERAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.4 SHORT AND LONG ADDRESSING MODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.5 X AND Y INDEXED MODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.6 RELATIVE MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.7 MEMORY INDIRECT ADDRESSING MODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.8 HIGH, LOW ADDRESSING MODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4 ASSEMBLER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.2 SOURCE CODE FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.2.1 Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.2 Assembly Source Code Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.3 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.4 Opcodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.5 Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.6 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.7 A Source Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 SEGMENTATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.3 Copying Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.4 MACROS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 12 14 17 18 24 24 25 25 26 30 30 4.4.1 Defining Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.4.2 Parameter Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 4.5 CONDITIONAL ASSEMBLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 4.5.1 IF/#ELSE#ENDIF directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 4.6 RUNNING THE ASSEMBLER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.6.1 Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.6.2 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 LINKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1 WHAT THE LINKER DOES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 36 40 40 5.2 INVOKING THE LINKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 5.2.1 Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 . 40 ... 5.2.2 Response files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 5.3 LINKING IN DETAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 2/134 16 Table of Contents 5.3.1 PUBLICs and EXTERNs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.2 Segments in the Linker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.3 Symbol Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4 THE LINKER IN MORE DETAIL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1 The Composition of the .OBJ Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.2 The Composition of the .COD Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.3 Reading a Mapfile Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 OBSEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1 WHAT OBSEND DOES FOR YOU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 42 44 45 45 45 46 48 48 6.2 INVOKING OBSEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 6.2.1 Destination Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 6.2.2 Destination Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 6.3 FORMAT DEFINITIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 6.3.1 Straight Binary Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.2 Intel Hex Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.3 Motorola S-record Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.4 ST 2 and ST 4 S-record Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.5 GP Binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 LIBRARIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 50 51 52 52 53 53 7.2 INVOKING THE LIBRARIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 7.3 ADDING MODULES TO A LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 7.4 DELETING MODULES FROM A LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 7.5 COPYING MODULES FROM A LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 7.6 GETTING DETAILS IN YOUR LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 A Assembler Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 B Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 B.1 FORMAT OF ERROR MESSAGES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 B.2 FILE CBE.ERR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 B.3 ASSEMBLER ERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 B.4 LINKER ERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 3/134 17 ST7ASMLK Organization of the Manual This manual is made up of seven chapters, and two appendixes: Chapter 1 INTRODUCTION, introduces you to the components of the ST7 Software Tools. Chapter 2 INSTALLATION, describes how to install the software package on various computers. Chapter 3, ST7 ADDRESSING MODEL, discusses the addressing structure of the ST7 processor family. Chapter 4, ASSEMBLER, explains how to use the Assembler. Chapter 5, LINKER, describes the linking process. Chapter 6, OBSEND, explains the role of the formatter in the program preparation process. Chapter 7, LIBRARIAN, explains the role of the librarian. Appendix A provides information on assembler directives. Appendix B provides information on assembler and linker error messages. 4/134 18 ST7ASMLK 1 INTRODUCTION 1.1 TOOL-CHAIN The tool-chain development system includes: * a meta-assembler: * a generic linker: * a generic formatter: * a generic librarian: ASM LYN OBSEND LIB 1.2 ASM (ASSEMBLER) The role of the assembler is to translate the code you have written (the source code) into a code specific to the target machine, the so-called "object code". The assembler takes as input file an assembly file ".ASM" and produces as output an object file ".OBJ". If desired, a listing file ".LST" can be obtained. The meta-assembler can be targeted to various processors, using machine description files. The machine description file name for the ST7 processor family is ST7.TAB. 1.3 LYN (LINKER) The linker takes as input one or several object files ".OBJ" files produced by the assembler, and produces as output an object code file ".COD". LYN resolves all cross-references between object files, and locates all the modules in memory. 1.4 OBSEND (FORMATTER) Once your application is linked, you must output it in a suitable format. The formatter takes as input the object code file ".COD" produced by the linker. The default suffix for the output file is ".FIN", but it is possible to specify other suffixes, for example: OBSEND 5/134 19 ST7ASMLK 2 INSTALLATION To install the ST7 software tools, run the setup.exe file from the CD-ROM included in the delivery package, and follow the instructions displayed on screen. When the installation is completed, the installation directory (typically C:\st7tools\asm) contains the following files: Table 1: ASM.EXE LYN.EXE OBSEND.EXE LIB.EXE ST7.TAB ASLI.BAT README.TXT assembler linker formatter librarian ST7 description file batch file ASM+LYN+OBSEND release notes Look at file readme.txt for up-to-date release notes. Other files contain examples. Note: With Windows 3.1x or Windows 95, the installation process updates the autoexec.bat file so as to provide suitable path specifications to access the assembler tool-chain. To take into account the the new autoexec.bat file contents, reboot your computer. You may also directly access the assembler tool-chain from any MS-DOS window by running C:\st7tools\asm\st7vars.bat. 6/134 20 ST7ASMLK 3 ST7 ADDRESSING MODEL 3.1 OVERVIEW The ST7 provides a single source-coding model regardless of which components are operands, the accumulator (A), an index register (X or Y), the stack pointer (S), the condition code register (CC), or a memory location. For example, a single instruction, ld, originates register to register transfers as well as memory to accumulator data movements. Two-operand instructions are coded with destination operand appearing at first position. Examples: lab01 lab02 ld A,memory ld memory,A ld X,A ; load accumulator A with memory contents ; load memory location with A contents ; load X with accumulator contents 3.2 INHERENT ADDRESSING MODE This concept is hardware-oriented: it means that instruction operand(s) is (are) coded inside the operation code; at source coding level, operand(s) is (are) explicitly written. Examples: lab06 lab07 push mul A X,A ; put accumulator A onto the stack ; multiply X by A 3.3 IMMEDIATE OPERAND This kind of operand is introduced by a sharp sign (#). Examples: lab08 lab09 ld bset btjt A,#1 memory,#3 memory,#3,label ; load A with immediate value 1 ; set bit #3 in memory location ; test bit #3 of memory and ; jump if true (set) 7/134 21 ST7ASMLK Unsigned notations are accepted for defining the immediate value (0 to 255 values for an 8-bit immediate operand). 3.4 SHORT AND LONG ADDRESSING MODES These two modes differ by the size of the memory address (one or two bytes) and thus by the target address range of the operand: 0-$FF $100-$FFFF for short addressing mode for long addressing mode Some instructions accept both types of addressing modes, and some others only short addressing: Examples: lab10 lab11 add inc A,memory memory ; both types of addressing modes ; only short addressing mode For instructions supporting both formats, short and long, when external symbol are referenced, long mode is chosen by the Assembler: Example: EXTERN symb3 symb1 ... ld ld A,symb1 A,symb3 equ $10 ; ; ; short mode ; long mode chosen 8/134 22 ST7ASMLK 3.5 X AND Y INDEXED MODES The ST7 hardware supports three variants of indexed modes: * indexed without offset, * indexed with 8-bit unsigned offset [0 ,255 range], * indexed with 16-bit offset. Source coding form is: (X) or (Y) (offset,X) or (offset,Y) for no-offset indexing for the two others Some instructions - ld A, add, ... - support the three forms, some others - inc, ... -, only the first two. The ST7 Assembler performs the same kind of 8-bit / 16-bit offset selection than between short/long modes described in previous sections. Examples: ld ld ld ld A,(X) A,(0,X) A,(127,X) A,(259,X) ; no-offset mode ; 8-bit offset mode ; idem ; 16-bit offset mode 3.6 RELATIVE MODE This mode is used by JRxx, CALLR, and BTJx instructions. A conditional jump is done to a program label in the [-128 , 127] range from the value of the PC for the instruction following the jump. At source coding level, the target label is specified (and the assembler computes the displacement). 9/134 23 ST7ASMLK 3.7 MEMORY INDIRECT ADDRESSING MODES This last group consists in memory indirect variants of short indirect, long indirect, short indirect indexed, long indirect indexed. The address specified must always be in page 0 (i.e. its address must be less than $100). Examples: ld ld ld lab12 equ A,[80] A,[80.b] A,[80.w] 80 ; short indirect ; short indirect ; long indirect ld ld ld A,([lab12],X) A,([lab12.b],X) A,([lab12.w],Y) ; short indirect X-indexed ; short indirect X-indexed ; long indirect Y-indexed To make the distinction between short and long indirect addressing mode, the suffix .w is specified to indicate that you want to work in long indirect mode (idem with indexed addressing mode). Implicitly, if nothing is specified, the short indirect addressing mode is assumed. You can also use .b to specify short indirect addressing mode.(idem with indexed addressing mode). 3.8 HIGH, LOW ADDRESSING MODES In some instances, it may be necessary to access the highest part of an address (8 highest bits) or the lowest part of an address (8 lowest bits) as well. For this feature, the syntax is the following one: 10/134 24 ST7ASMLK Examples: lab12 equ nop $0012 ld ld A,#lab12.h A,#lab12.l ; load A with $00 ; load A with $12 For more information about each instruction and the various addressing modes, refer to the ST7 PROGRAMMING MANUAL. 11/134 25 ST7ASMLK 4 ASSEMBLER 4.1 OVERVIEW The assembler is a cross-assembler, i.e., it produces code for a target machine, the SGSTHOMSON ST7 microprocessor family, different from the host machine. The assembler will turn your source code files into relocatable objects modules ready for linking. During the process, it checks for many different types of errors. They are recorded in an ASCII file: cbe.err. The linker also writes to this file. Error messages are explained in the appendix B "Error Messages" on page 125. To produce code ready for execution, you must run the assembler (ASM), the linker (LYN), and the object code formatter(OBSEND). * Segmentation * Macros * Conditional assembly * Source file inclusion * Absolute patch on assembly listing * Symbol cross reference listing 4.2 SOURCE CODE FORMAT 4.2.1 Source Files Source program code is organised in an ASCII text file named source file. A source file has the extension .asm. It is made up of lines, each of which is terminated by a new line character. 4.2.2 Assembly Source Code Format The first line of an assembly source code file is reserved for specifying the TARGET PROCESSOR. Even comments are prohibited. The '.TAB' suffix may be left out. For example, to use the ST7 processor: c:\st7tools\asm\st7/ File ST7.TAB must be located in the directory c:\st7tools\asm. 12/134 26 ST7ASMLK If it can't be found in the given directory, then an error is produced and assembly is aborted. There is also an environment variable 'METAI'. This variable specifies the directory where the file 'ST7.TAB' is located. Examples: PC/MS-DOS: SET METAI=c:\st7tools\asm If the environment variable METAI is defined, the first line of the assembly program is: st7/ Note The installation process automatically sets the METAI variable in the autoexec.bat file. Remaining source code lines have the following general format: [label[:]] where All four fields may be left blank, but the Example: examp ld A,$ffff ; long addressing mode opcode label operand separator comments 13/134 27 ST7ASMLK 4.2.3 Labels 4.2.3.1 Label Structure Labels must start in column one. A label may contain up to eight of any of the following characters: * Upper Case letters (A-Z) * Lower case letters (a-z) * Digits (0-9) * Underscore (_) The first letter of a label must be a letter or an underscore. Note that upper and lower case are treated as different because the assembler is case sensitive. When labels are defined there are several attributes defined along with the value. These are: * Size (Byte, Word or Long) * Relativity (Linker Relative or Absolute) * Scope (Internally or Externally defined) The function of each attribute is explained in the following paragraphs. 4.2.3.2 Label Size The size of a label allows the assembler to make decisions on what kind of addressing mode to choose even if the label value itself is undefined. You can force a label to refer to a certain size of memory location by giving the label name a suffix when it is defined. The suffix isn't used when the label is referred to. If you give no suffix, then the default size is assumed. BYTES, WORDS and LONGS directives allow to change the default. Without directives, the default is WORDS. 14/134 28 ST7ASMLK Examples: lab label1.b label2.l equ 0 equ 5 equ 123 ; word (default) label ; byte label ; long label ; force size of label to bytes ; byte default label ; a word space is defined ; at this label segment byte at: 80 `ram' bytes count pointer ds.b ds.w 4.2.3.3 Label Relativity There are two sorts of labels: ABSOLUTE labels and RELATIVE labels. ABSOLUTE labels are usually assigned to constants, such as IO port addresses, or common values used within the program. RELATIVE labels are defined as (or derived from) an EXTERNAL label or a label derived from the position of some program code. They are exclusively used for labels defined within pieces of program or data. Example: lab ioport equ 0 equ $8000 ; absolute label `count' ; absolute word label `ioport' segment `eprom' start ld X,#count ld A,#'*' loop ld ioport,A dec X jrne loop stop jp stop ; then loop for ever Only the linker can sort out the actual address of the code, as the assembler has no idea how many segments precede this one in the class. At assembly time, labels such as 'start' or 'loop' 15/134 29 ST7ASMLK are actually allocated 'blank' values ($0000). These values will be filled later by the linker. Labels such as 'count' or 'ioport', which were defined absolutely will be filled by the assembler. Source code lines that have arguments containing relative labels are marked with an 'R' on the listing, showing that they are 'linker relative'. Segments are discussed in "Segmentation" on page 25. 4.2.3.4 Label Scope Often, in multi-module programs, a piece of code will need to refer to a label that is actually defined in another module. To do this, the module that exports the label must declare it PUBLIC, and the module which imports the label must declare it EXTERN. The two directives EXTERN and PUBLIC go together as a pair. Most labels in a program will be of no interest for other pieces of the program: these are known as 'internal' labels since they are only used in the module where they are defined. Labels are 'internal' by default. Here are two incomplete example modules that pass labels between them: module 1 EXTERN _sig1.w EXTERN _sig2.w PUBLIC _handlers segment byte `P' _handlers: jp _sig1 jp _sig2 end ; define _handlers ; refer to _sig1 ; refer to _sig2 ; import _sig1 ; import _sig2 ; export _handlers module 2 EXTERN _handlers.w PUBLIC _sig2 ; import _handlers (addr. is a word) ; export _sig2 16/134 30 ST7ASMLK segment byte `P' _sig2: ... call _handlers ... ret end ; refer to _handlers ; define _sig2 As you can see, module 1 refers to the '_sig2' subroutine which is defined in module 2. Note that when module 1 refers to the '_sig2' label in an EXTERN directive it specifies a WORD size with the '.w' suffix. Because the assembler cannot look up the definition of '_sig2' it has to be told its address size explicitly. It doesn't need to be told relativity: all external labels are assumed to be relative. Absolute labels declared between modules should be defined in an INCLUDE file that is called by all modules in the program; this idea of using INCLUDE files is very important since it can cut down the number of PUBLIC symbols - and therefore the link time - significantly. Lines in the source code listing which refer to external labels are marked with an X and given 'empty' values for the linker to fill. As a short cut, labels may be declared as PUBLIC by preceding them with a '.' at their definition. If this is done the label name need not be given in a PUBLIC directive. For example, the following code fragment declares the label 'lab4' as PUBLIC automatically: Example: lab3 ld A,#0 ret .lab4 nop ret 4.2.4 Opcodes The Opcode field may serve three different purposes. It may contain: * The opcode mnemonic for an assembly instruction, * The name of a directive, * The name of a macro to be invoked. 17/134 31 ST7ASMLK Opcodes must be separated from the preceding field (label, if there is one) by a space or a tab. A comprehensive Opcode description can be found in the ST7 PROGRAMMING MANUAL. Macros are discussed in "Macros" on page 30 Directives are discussed in "Assembler Directives" on page 63 . 4.2.5 Operands 4.2.5.1 General Operands may be: * Numbers, * String and character constants, * Program Counter references, * Expressions. 4.2.5.2 Number and Address Representation By default, the representation of numbers and addresses follows the MOTOROLA syntax. When you want to use hexadecimal number with instructions or labels, they must be preceded by $. When nothing is specified, the default base is decimal. Examples: lab03 lab04 equ 10 equ $10 ld A,$ffff ld A,#$cb ld A,#100 ; decimal 10 ; hexadecimal 10 ; long addressing mode ; immediate addressing mode ; decimal representation You can change the Motorola format representation by using directives (.INTEL,.TEXAS) to indicate the new setting format. For more information, refer to the appendix "Assembler Directives" on page 63. 18/134 32 ST7ASMLK CAUTION Addresses for SEGMENT definition are always given in hexadecimal: segment byte at: 100-1FF 'test' The segment 'test' is defined within the 256-511 address range. 4.2.5.3 Numeric Constants and Radix Constants may need special characters to define the radix of the given number. The assembler supports the MOTOROLA format by default. INTEL, TEXAS, ZILOG formats are also available if the format is forced by .INTEL .TEXAS or.ZILOG directives. (Decimal constants are always the default, and require no special characters). Motorola Format Hex Binary Octal Current PC Intel Format Hex Binary Octal Current PC Texas Format Hex Binary Octal Current PC Zilog Format Hex %ABCD >ABCD ?100 ~665 $ 0ABCDh 100b 665o or 665q $ $ABCD or &ABCD %100 ~665 * (use MULT for MULTIPLY) 19/134 33 ST7ASMLK Binary Octal Current PC %(2)100 %(8)665 $ 4.2.5.4 String Constants String constants are strings of ASCII characters surrounded by double quotes. Example: "This is an ASCII string" 4.2.5.5 ASCII Character Constants The assembler's arithmetic parser also handles ASCII characters in single quotes, returning the ASCII of the given character(s). Examples: `A' `6' `AB' $41 $06 $4142 Up to 4 characters may be used within a single pair of quotes to give a long constant. The following special sequences are used to denote special characters: backspace formfeed linefeed carriage return tabulation slash single-quote `\b' `\f' `\n' `\r' `\t' `\\' `\' $7F $0C $0A $0D $09 $5C $27 20/134 34 ST7ASMLK `\0' `\"' $00 $22 null double-quote 4.2.5.6 Program Counter Reference The current value of the program counter (PC) can be specified by * Example: lab05 jra * 4.2.5.7 Expressions and Operators Expressions Expressions are numeric values that may be made up from labels, constants, brackets and operators. Labels and constants have been discussed in previous paragraphs. Arithmetic brackets are allowed up to 8 nested levels: the curly braces {} are used instead of the common "(" and ")" because instructions may use a parenthesis to denote indexed addressing modes. Operators There are 4 levels of precedence. Operators in level #1 take precedence over operators in level #2, and so on. In each level, operators have same precedence: they are evaluated from left to right. . Table 2: Operation -a negated a Result, level #1 21/134 35 ST7ASMLK Table 2: Operation a and b a or b a xor b a shr b a shl b a lt b a gt b a eq b a ge b a ne b high a low a offset a seg a bnot a wnot a lnot a sexbw a sexbl a sexwl a logical AND of A and B logical OR of A and B logical XOR of A and B a shifted right b times a shifted left b times 1 if a 22/134 36 ST7ASMLK Table 3: Operation a/b a div b a divided by b a divided by b Result, level #2 Table 4: Operation a*b a mult b a multiplied by b as above for motorola (character * is reserved) Result, level #3 Table 5: Operation a-b a+b a minus b a plus b Result, level #4 Operator names longer than one character must be followed by a space character. For example, '1 AND 2' is correct, '1AND2' is not. Place the curly braces { } around arithmetic expressions. Also, always use curly braces at the top-level, when defining a numeric expression. Not doing so may produce unexpected results. 23/134 37 ST7ASMLK Wrong syntax: #define SIZE 128 DS.W SIZE+1 #IF SIZE eq 1 #ENDIF ; Wrong, syntax error ; Wrong, same as #IF SIZE Correct syntax: #define SIZE 128 DS.W {SIZE+1} #IF {SIZE eq 1} #ENDIF ; OK ; OK 4.2.6 Comments Comments are preceded by a semicolon. Characters following a semicolon are ignored by the assembler. 4.2.7 A Source Code Example st7/ ; small example module showing source formats ioport handshake equ $8000 equ $9000 ; 8 bit I0 port A ; write xx here to strobe segment 'program' start loop ld a,#0 ld ioport,x ; zero counter ; store into ioport segment word at: FFFC 'code' WORD start end Don't worry if some directives don't make sense yet; they will be covered soon; also, take special notice of the SEGMENT directive. 24/134 38 ST7ASMLK 4.3 SEGMENTATION 4.3.1 Introduction Segments are very, very important. You have to know about segments before you can use the assembler. Take the time now to understand them and you'll save yourself a lot of puzzling. Segmentation is a way of 'naming' areas of your code and making sure that the linker collates areas of the same name together in the same memory area, whatever the order of the segments in the object files. Up to 128 different segments may be defined in each module. The segment directive itself has four arguments, separated by spaces: [ SEGMENT [ Examples: File1: st7/ BYTES segment byte at: 80-FF `RAM0' counter.b address.b ds.b ds.w ds.b 15 stack ds.b ; loop counter ; address storage ; stack allocation ; stack grows downward segment byte at: E000-FFFF `eprom' ld A,#stack ld S,A end ; init stack pointer File2: st7/ segment `RAM0' serialtemp ds.b 25/134 39 ST7ASMLK serialcou ds.b WORDS segment `eprom' serial_in ld A,#0 end FILE1 and FILE2 are two separate modules belonging to the same program. FILE1 introduces two classes: 'RAM0' and 'eprom'. The class-names may be any names you choose up to 30 characters. The first time a class is used - introduced - you have to tell the default alignment, the start and the end addresses of the class, and, of course the name of the class. Users generally specify a new class for each 'area' of their target system. In the examples above the user has one class for the 128 bytes of on-chip RAM from 0080 to 00FF ('RAM0') and another for the 'eprom'. The code is stored from E000 to FFFF ('eprom'). You have to supply all this information the very first time you use a new class, else only the class-name is necessary, as in FILE2. 4.3.2 Parameters The following paragraphs describe each argument in detail. 4.3.2.1 Name The 26/134 40 ST7ASMLK Table 6: Type byte word para 64 128 page long 1k 4k Any address Next address on boundary Next address on 16-byte boundary Next address on 64-byte boundary Next address on 128-byte boundary Next address on 256-byte boundary Next address on 4-byte boundary Next address on 1k-byte boundary Next address on 4K-byte boundary 1001->1002 1001->1010 1001->1040 1001->1080 1001->1100 1001->1004 1001->1400 1001->2000 Description Examples Looking back to our examples earlier, you should now be able to see that the 'RAM0' class will allocate 80 to counter, 81 to address, 92 to stack in FILE1, and when the linker meets the segment in FILE2 of the same class, serialtemp will be allocated 93, and serialcou 94. The same processing happens to the two 'eprom ' class segments: the second, in FILE2 will be tacked on to the end of the first in FILE1. If the FILE2 'eprom' class segment had specified, say, the long align type instead of the default byte, then that segment would have been put on the next long-word boundary after the end of the FILE1 'eprom' class segment. 4.3.2.3 Combine The 27/134 41 ST7ASMLK Table 7: Type at:X[-Y] common Description Starts a new class from address X [to address Y] All common segments that have the same class name will start at the same address. This address is figured out by the linker. Follows on from end of last segment of this class. The at-type The at-type Example: st7/ dat1 segment byte at: 10 'DATA' ds.w com1 .lab1 com1 .lab2 com2 .lab3 com2 .lab4 segment common 'DATA' ds.w 4 segment common 'DATA' ds.w 2 segment common 'DATA' ds.w segment common 'DATA' ds.w 2 28/134 42 ST7ASMLK dat2 .lab5 segment 'DATA' ds.w 2 end The values for labels lab1, lab2, lab3, lab4, and lab5 are 12, 12, 1A, 1A and 1E, respectively. Note: Since you can't specify both at and common combines simultaneously, the only way to specify the exact location of commons is to insert an empty at combine segment before the first common declaration. Example: com1 com1 segment byte at: 10 'DATA' segment common 'DATA' ... com1 segment common 'DATA' ... 4.3.2.4 Cod parameter, Output File Control The last field of a SEGMENT directive controls where the linker places the code for a given class. When introducing a class, if this field is not specified, the code for this class will be sent to the normal, default .COD file by the linker. If the [cod] file is given a number between 0 and 9 then all code generated under the class being introduced will be sent to a different '.COD' file by the linker. If the linker produces a file called 'prog.cod', for example, then all code produced under classes with no [cod] field will go into that file, as normal. If one class is introduced with a [cod] field of 1, though, then all code produced under that class is sent instead to a file prog_1.cod. The code produced under the other classes is sent on as usual to prog.cod. 29/134 43 ST7ASMLK Using this scheme, you can do bank switching schemes quickly and directly, even when multiple EPROMs share the same addressing space. Simply allocate each EPROM class of its own, and introduce each class with a different [cod] field. This will result in the linker collating EPROM's contents into a different .COD file for you to OBSEND independently. Example: segment byte at:8000-BFFF 'eprom1' 1 segment byte at:8000-BFFF 'eprom2' 2 4.3.3 Copying Code It sometimes happens that you need to copy a block of code from EPROM to RAM. This presents some difficulties because all labels in that piece of code must have the RAM addresses, otherwise any absolute address references in the code will point back to the EPROM copy. You can specify a class for execution, and use a different class for storage. In the following example: segment byte at: 0 'code' segment byte at: 8000 'ram' segment 'ram>code' label1: nop The code starting from 'label1' will be stored in the 'code' class as usual, but all the labels in that special segment will be given addresses in the 'ram' class, and memory will also be reserved in the ram class for the contents of the special segment. 4.4 MACROS Macros are assembly-time subroutines. When you call an execution-time subroutine you have to go through several time-consuming steps: loading registers with the arguments for the subroutine, having saved out the old con- 30/134 44 ST7ASMLK tents of the registers if necessary, pushing registers used by the subroutine (with its attendant stack activity) and returning from the subroutine (more stack activity) then popping off preserved registers and continuing. Although macros don't get rid of all these problems, they can go a long way toward making your program execute faster than using subroutines - at a cost. The cost is program size. Each time you invoke a macro to do a particular job, the whole macro assembly code is inserted into your source code. This means there is no stacking for return addresses: your program just runs straight into the code; but it's obviously not feasible to do this for subroutines above certain size. The true use of macros is in small snippets of code that you use repeatedly - perhaps with different arguments - which can be formalized into a 'template' for the macros' definition. 4.4.1 Defining Macros Macros are defined using three directives: MACRO, MEND and LOCAL. the format is: [parameter-1][, parameter-2 ...] [LOCAL] Example: add16 MACRO first,second,result ld A,first adc A,second ld result,A MEND The piece of code of the example might be called by: add16 index,offset,index which would add the following statements to the source code at that point: 31/134 45 ST7ASMLK ld A,index adc A,offset ld index.X,A Note that the formal parameters given in the definition have been replaced by the actual parameters given on the calling line. These new parameters may be expressions or strings as well as label names or constants: it's because they may be complex expression that they are bracketed when there is any extra numeric activity: this is to make sure they come out with the precedence correctly parsed. Macros do not need to have any parameters: in which case leave the MACRO argument field blank, and give none on the calling line. There is one further problem: because a macro may be called several times in the same module, any labels defined in the macro will be duplicated. The LOCAL directive gets around this problem: Example: getio MACRO LOCAL loop loop ld A,$C000 jra loop MEND This macro creates the code for a loop to await IO port at $C000 to go low. Without the LOCAL directive, the label 'loop' would be defined as many times as the macro is called, producing syntax errors at assembly time. Because it's been declared LOCAL at the start of the MACRO definition, the assembler takes care of it. Wherever it sees the label 'loop' inside the macro, it changes the name 'loop' to 'LOCXXXX' where XXXX is a hex number from 0000 to FFFF. Each time a local label is used, XXXX is incremented. So, the first time the getio macro is called, 'loop' is actually defined as 'LOC0', the second time as 'LOC1' and so on, each of these being a unique reference name. The reference to 'loop' in the 'if' statement is also detected and changed to the appropriate new local variable. 32/134 46 ST7ASMLK The following directives are very useful, in conjunction with macros: Table 8: Directive #IFB #IFDEF #IFLAB #IFIDN Usage To implement macro optional parameters. To test if a parameter is defined. To test if a parameter is a label. To compare a parameter to a given string. 4.4.2 Parameter Substitution The assembler looks for macro parameters after every space character. If you want to embed a parameter, for example, in the middle of a label, you must precede the parameter name with an ampersand '&' character, to make the parameter visible to the preprocessor. For example, if we have a parameter called 'param': dc.w param it works as expected but the ampersand is necessary on: label¶m: label¶m&_¶m: nop nop otherwise 'labelparam' would be left as a valid label name; If the macro parameter 'param' had the value '5', then 'label5' and 'label5_5' would be created. 4.5 CONDITIONAL ASSEMBLY Conditional assembly is used to choose to ignore or to select whole areas of assembler code. This is useful for generating different versions of a program by setting a particular variable in an INCLUDE file that forces the use of special pieces of code instead of others. 4.5.1 IF/#ELSE#ENDIF directives There are three main directives used to perform conditional assembly: 33/134 47 ST7ASMLK Table 9: Directive #IF Usage marks the start of the conditional and decides whether the following zone will be assembled or not. optionally reserves the condition of the previous #IF for the following zone. marks the end of the previous #IF's. #ELSE #ENDIF The condition given with the '#IF' may take the form of any numeric expression; the rule for deciding whether it resolves to 'true' or 'false' is simple: if it has a zero value then it's false, else it's true. These directives should NOT start at column 1 of line, reserved for labels. Example: #IF {count eq 1} %OUT 'true' #ELSE %OUT 'false' #ENDIF This sequence would print 'true' if the label 'count' did equal 1, and `false' if it didn't. Example: #IF {count gt 1} %OUT count more than one #IF {count gt 2} %OUT ...and more of TWO ! #ELSE %OUT ...but not more than two! #ENDIF 34/134 48 ST7ASMLK #ELSE %OUT count not more than one #ENDIF As you can see, conditionals may be nested: the #ELSE and #ENDIF directive are assumed to be assumed to the most recent unterminated #IF. Other special #IF directives are available: Table 10: Directive #IF1 and #IF2 Usage require no conditional argument. If the appropriate pass is being assembled, the condition is considered 'true'; for instance #IF1 will be considered true while the assembler is in first pass, #IF2 while in the second pass. checks for label definition. checks for empty argument (i.e., empty, or containing spaces / tabs), useful for testing macro parameter existence. (IF False) is similar to #IF, but checks the negation of the condition argument. tests for string equality between two arguments separated by a space. This is useful for testing macro parameters against fixed strings. checks if the argument is a predefined label. #IFDEF #IFB #IFF #IFIDN #IFLAB 4.6 RUNNING THE ASSEMBLER 4.6.1 Command Line The assembler needs the following arguments: ASM 35/134 49 ST7ASMLK If any or all the arguments are left out of the command line, you'll be prompted for the remaining arguments. Example: ASM SGS-THOMSON Microelectronics - Assembler - rel. 1.8 File to Assemble: game In the example above, no parameters were given on the command line, so all the parameters were prompted for. The The listing file is the file to which the assembly report is sent if selected. The default filename (which is displayed in square brackets), is made from the path and base-name of the file to assemble. The default filename suffix for the assembly report file is ".LST". For instance, if you type 'game', then 'game.lst' is the actual filename used. Note that unless the assembler is told to create either a pass-1 or pass-2 complete listing by the options argument, the listing file will not be created. 4.6.2 Options Options are always preceded with a minus sign '-'. Upper and lower cases are accepted to define options. Supported options are: Table 11: Option -LI -PA -OBJ= 36/134 50 ST7ASMLK Table 11: Option -SYM -NP -FI= 4.6.2.1 SYM Option Description: Format: This option allows the generation of a symbol table. ASM 4.6.2.2 LI Option Description: Format: Request to generate a complete listing file. ASM 4.6.2.3 OBJ Option Description: Format: Example: You can force the .OBJ file to be generated in a specific directory using the following option (note -obj: must be the last switch): ASM 37/134 51 ST7ASMLK 4.6.2.4 FI Option Description: One side effect of using a linker is that all modules are assembled separately, leaving inter modules' cross-references to be fixed up by the linker. As a result the assembler listing file set all unresolved references to 0, and displays a warning character. The '-fi' option enables you to perform an absolute patch on the desired listing. Therefore, you must have produced a listing file (.LST) and linked your application to compute relocations and produce a .COD file and a map file. When you want a full listing to be generated, you must not have made any edits since the last link (otherwise the named map-file would be 'out of date' for the module being assembled). This is not usually a problem since full listings are only needed after all the code has been completed. -fi automatically selects a complete listing. Format: ASM Note that when assembling in '-fi' mode, the assembler uses the map file produced by the linker, and no object files are generated. 4.6.2.5 D Option Description: The -d switch allows you to define the first string to be replaced by the second string during the assembly. A space is needed between the two strings. This is extremely useful for changing the assembly of a module using #IF directives, because you can change the value of the #IF tests from the assembler's command line. It means that you can run the assembler with different -D switches on the same source file, to produce different codes. Note that if you specify multiple -D switches, they should be separated by a space. 38/134 52 ST7ASMLK Example: ASM ex1 -D EPROM 1 -D RAM 2 4.6.2.6 PA option Description: Request to generate a pass-1 listing. It means that in this listing internal forward references are not yet known. They are marked as undefined with a 'U' in the listing file. ASM Format: 4.6.2.7 NP option Description: Format: Example: This option disables the error generation. ASM 39/134 53 ST7ASMLK 5 LINKER 5.1 WHAT THE LINKER DOES After having separately assembled all the component modules in your program, the next step is to link them together into a .COD file which can then be sent on to its final destination using OBSEND. This linking process is not just as a simple concatenation of the object modules. It resolves all the external references. If a referenced label is not defined as PUBLIC, an error is detected. It also checks the type of relocation to do, places the segment according to your mapping, and checks if any of them is overrun. 5.2 INVOKING THE LINKER 5.2.1 Command Line The linker needs the following arguments: LYN <.OBJ file>[+<.OBJ file>...], [<.COD file>],[ If all or any arguments are left out of the command line, you'll be prompted. Example: LYN SGS-THOMSON Microelectronics - Linker - rel 1.6 .OBJ files: begin .COD file [begin.cod]: begin Libraries: The .OBJ files are simply a list of all the object files that form your program. The .OBJ suffix may be left out, and if more than one is specified they should be separated by '+' characters, for example game+scores+keys would tell the linker to link 'game.obj', 'scores.obj' and 'key.obj'. Object file path names should not include '-' or ';' characters. Character '.' should be avoided, except for suffixes. 40/134 54 ST7ASMLK The .COD file has a default name formed of the first object file's name with forced suffix of '.COD'. This will be the name of the file produced at the end of the link session: It contains all the information from the link session in a special format: however, OBSEND must be used on the .COD file before it is ready to use. If the default filename is not what you want, the filename given at the prompt is used instead. The suffix will be forced to .COD if left blank. The default is selected by leaving this argument blank at the command line, or pressing Examples: Linking together the modules game.obj, scores.obj, key.obj, game1.obj, game2.obj and game3.obj without using any libraries and generating a .COD file named game.cod, requires the following command line: LYN game+scores+keys+game1+game2+game3; Linking the same modules in the same environment, but generating a .cod file named prog.cod requires: LYN game+scores+keys+game1+game2+game3,prog; 5.2.2 Response files Responses files are text files that replace the command line to generate the arguments required. Although they can be used on the assembler and linker, it only really makes sense to use them on the linker. The command line given with the name of the program to execute (here LYN) can only take up to 128 characters as its argument. For most programs this is fine, but the linker allows up to128 modules to be linked in one run; all their names have to be declared to the linker in its first argument. This is where response files come in: they allow you to redirect the command line parser to a file instead of expecting arguments to come from the command line or the keyboard. A response file is invoked by giving an `@' sign and a filename in response to the first argument you want to come from the response file. 41/134 55 ST7ASMLK The filename is assumed to have a suffix '.RSP' if none is supplied. Repeating our example used as earlier, but this time with a response file called game.rsp: LYN @game.rsp is all that needs to be typed, and the file game.rsp must contain: game+scores+keys+ game1+ game2+game3 prog Which echoes what would have been typed at the keyboard. If the response file ends prematurely, the remaining arguments are prompted for at the keyboard. In very large session, the .OBJ files argument won't fit on one line: it can be continued to the next by ending the last .OBJ file on the first line with a '+'. Note that when using response files, there must be at least two carriage returns at the end of the file. 5.3 LINKING IN DETAIL 5.3.1 PUBLICs and EXTERNs All labels declared external in the modules being linked together must have a corresponding PUBLIC definition in another module. If it doesn't, it may be an error. Similarly, there must only be one PUBLIC definition of a given label. The bulk of the linker's job is filling those relative or external blanks left by the assembler in the .OBJ files; to a lesser extent, it also handles special functions such as DATE or SKIP directives. Equally important, it has to collate together and allocate addresses to segments. 5.3.2 Segments in the Linker A typical system may look like the diagram alongside: a good candidate for four different segments, perhaps named 'RAM0', 'RAM1', 'EPROM' and 'ROM'. If the reset and interrupt vectors live at the end of the map, perhaps from FFEE-FFFF then we might mark a fifth segment called 'vectors' at those addresses and truncate 'ROM' to end at FFED; that way the linker will warn us if 'ROM' has so much code in it that it overflows into where the vectors live. 42/134 56 ST7ASMLK These classes would be introduced as follows: segment byte at: 0-FF segment byte at: 100-027F segment byte at: 8000-BFFF segment byte at: C000-FFDF segment byte at: FFE0-FFFF 'RAM0' 'RAM1' 'EPROM' 'ROM' 'VECTORS' After their full introduction that needs only be done once in the whole program, the rest of the program can refer to the classes just by giving the class names in quotes: Example: segment 'RAM0' xtemp time ds.w ds.b segment 'ROM' hex ld A,#1 add A,#10 nop ; temp storage for X register ; timer count index If this example followed immediately after the class instruction the 'xtemp' label would be given the value 0, time would be given 2 and hex C000. If, however, the code was several modules away from the introduction with segments of the classes 'RAM0' or 'ROM', then the value allocated to all the labels will depend on how much space was used up by those modules. The linker takes care of all this allocation. This is the way the linker handles the problems of relocatability; keep in mind that this link system is going to have to handle compiled code from high level languages and you'll perhaps begin to understand why things have to be generalized so much. So far the segments we've looked at, had no Example: 43/134 57 ST7ASMLK grafix cursor_buf segment byte at: 100-027F 'RAM1' ds.b 64 ; buffer for map under cursor segment byte at: 8000-BFFF 'ROM' show_page nop segment 'RAM1' field-buf ds.b {{256 mult 256}/8} segment 'ROM' dump_buf grafix cursor_temp ld A,field_buffer segment 'RAM1' ds.b 64 This complex sequence of segments shows now instances of the class 'RAM1' being used with a segment name of 'grafix'. Because the first instance of the class 'RAM1' had the name 'grafix' the two 'grafix' RAM1 segments are placed in memory first followed by the nullname RAM1 segment (which defines 'field_buf'). Note this is not the order of the segments in the code: segments with the same name are collated together (even from separate .OBJ files), and the lumps of segments of the same name are put into memory in the order that the names are found in the .OBJ files. As explained in the assembler sections ("ASSEMBLER" on page 12), if x is your cod file suffix when introducing a class, all code for that code is sent into a new cod-file named file_x.cod, where file is the name of the first cod file, and x is the cod-file suffix (1-9). 5.3.3 Symbol Files At the end of a successful link, one or more .OBJ files will have been combined into a single .COD file. A .MAP file will have been produced, containing textual information about the segments, classes and external labels used by the .OBJ module(s). Finally a compact .SYM file is generated, containing all PUBLIC symbols found in the link with their final values. The linker supports a special feature - you can link in .SYM files from other link sessions. This means with huge programs, you cannot only partition your code at assembler level, but divide the code up into 'lumps' which are linked and loaded separately, but have access to each other's label as EXTERNs. You can 'link in' a symbol table simply by giving its name with the suffix .SYM. Always give symbol tables at the start of the object file list. 44/134 58 ST7ASMLK OBJ File Example: LYN prog1.sym+prog2,vectors,irq; Once this is done, all the PUBLIC symbols from prog1.sym are now available as PUBLICs to prog2.obj, vectors.obj and irq.obj. Because changes in one link will not automatically update references to the changed link code in other links, it's necessary when using this technique to 'fix' each link in an area of memory, and have a 'jump table' at the top of each area. This means that all 'function' addresses are permanently fixed as jump table offset, and changes to each link will result in automatic redirection of the jump targets to the new start of each routine. Put another way, each link must have entry fixed points to all its routine, otherwise re-linking one 'lump' of a program could make references to its addresses in other modules out of date. 5.4 THE LINKER IN MORE DETAIL. 5.4.1 The Composition of the .OBJ Files The .OBJ files produced by the assembler contain an enormous amount of overhead, mostly as coded expressions describing exactly what needs to go into the 'blank spaces' the assembler has been so liberal with. The linker contains a full arithmetic parser for 'working out' complex expressions that include external labels: This means (unlike most other assemblers) there are few restrictions on where external labels may appear. The assembler also includes line-number information with the .OBJ file, connecting each piece of generated object code with a line number from a given source file. OBJ files also contain 'special' markers for handling SKIP and DATE type directive. 5.4.2 The Composition of the .COD Files .COD files, on the other hand, contain very little overhead: there are six bytes per segment that describe the start address and length of that segment; Besides that, the rest of the code is in its final form. A segment of zero length marks the end of the file. It only remains for OBSEND to take the code segment by segment and send it on to its destination. 45/134 59 ST7ASMLK 5.4.3 Reading a Mapfile Listing The linker also generates files with the suffix .SYM and .MAP in addition to the .COD file we have already discussed. The .SYM file contains a compact symbol table list suitable with the debuggers and simulators. The .MAP file listing shows three important things: a table of segments with their absolute address, a table of all classes in the program, and a list of all external labels with their true values, modules they were defined in and size. Here is an example MAPFILE, where one of the class, ROM, has gone past its limit, overwriting (or more correctly, having part of itself overwritten by) VECTORS. The [void] on some segments in the segment list says that these segments were not used to create object code, but were used for non-coding-creating tasks such as allocating label values with ds.b etc. The number in straight brackets on the segment as true address list shows how many segments 'into' the module this segment is, i.e., the 1st, 2nd etc. of the given module. The first x-y shows the range of addresses. The def (line) field on the external labels list shows the source code file and line number that his label was defined in. The number at the start of each class list line is the cod-file that the class contents were sent to (default is 0). Segment Address List: prog [1] prog [2] main [1] prog [4] main [2] monitor [1] monitor [2] 108882825688448- 86 278 563 889 1456 446 467 01008000C000C509F579FFEE- 6 138 875B C508 F578 FFF9 FFFF `RAM0' [void] 'RAM1' 'eprom' 'rom' 'rom' 'rom' 'vectors' [void] 46/134 60 ST7ASMLK Class List: 0 0 0 0 0 `RAM0' `RAM1' `eprom' `rom' `vectors' byte from 0 to 78 (lim FF) 45% D byte from 100 to 138 (lim 27F) 50% D byte from 8000 to 875B (lim BFFF) 21% C byte from C000 to FFF9 (lim FFDF) C*Overrun* byte from FFEE to FFFF (lim FFFF) 100% D External Label List: Symbol Name Value Size Def(line) char char1 label 64 66 ABCD BYTE BYTE WORD game.obj(10) game.obj(11) game.obj(25) 3 labels The external label list only includes labels that were declared PUBLIC: labels used internally to the module are not included. This table is most useful for debugging purposes, since the values of labels are likely to be relocated between assemblies. The labels are given in firstcharacter-alphabetic order. 47/134 61 ST7ASMLK 6 OBSEND 6.1 WHAT OBSEND DOES FOR YOU After your program has been assembled and linked to form a '.COD' file it needs to be sent on to the place where it'll be executed; now your code is just sitting in a disc file where the target system can't get at it. OBSEND is a general purpose utility for .COD files in various ways using various formats. 6.2 INVOKING OBSEND OBSEND follows the same standard formats as the rest of the assembler / linker; arguments can be given from the command line, keyboard or response file. The general syntax is: OBSEND where OBSEND SGS-THOMSON Microelectronics - Obsend - rel. 1.2 File to Send: test Destination Type ( 6.2.1 Destination Type 6.2.2 Destination Arguments When the destination type is "f" (file) the argument 48/134 62 ST7ASMLK Example: OBSEND test,f,image.s19,s The command generates the file 'image.s19' containing the code from 'test.cod', in ST Srecord s format. When the destination code is "v" (video), this field is void. 6.3 FORMAT DEFINITIONS Table 12: 49/134 63 ST7ASMLK 6.3.1 Straight Binary Format Note: When the destination is the screen (the destination code is "v"), don't use this format; otherwise you will only get weird control codes. 6.3.2 Intel Hex Format The first thing to note is that every thing is in printable ASCII. Eight bit numbers are converted into two-characters hexadecimal representation. Each line begins with an ASCII ':' ($3A) character. The next two characters form a byte that declares how many data bytes follow in the data byte section little further along. The next four characters form a 16-bit high-byte first number that specifies the address for the first byte of this data; the rest follows on sequentially. 50/134 64 ST7ASMLK The next two characters are the record type for this line: 00 is a data line, and 01 signals EOF. The following characters until the last two are up the 16 data bytes for this line and, the last two are a checksum for the line, calculated by starting with $00 subtracting the real value of all characters sent after the ':' until the checksum itself. 'Real value' means that for example, the two characters 3 and 0 should subtract $30 from the checksum, not 51 and 48. Every line ends with a CR-LF combination, $0A and $0D. The last line sent must be an END-OF-FILE line, which is denoted by a line with no data bytes and a record type of 01 instead of 00. Giving I32 or i32 instead of intel as the argument uses the same format, but sends 32 bytes of data per line. 6.3.3 Motorola S-record Format The first two characters define the record type: S0, S1, S2 or S9. The next two characters form a hexadecimal representation of the numbers of bytes left in the record (i.e., numbers of characters /2) This count must include the checksum and addresses bytes that follow. The address field is four characters wide in S0, S1, S9 and six characters wide in S2. The most significant character always comes first. OBSEND will always use S1 type records wherever possible (i.e., when the address is less than $10000) and use S2 type data records where it has to (i.e., address > $FFFF). Up to 16 data bytes then follow, with the checksum appended on the end. The checksum is calculated by starting with $FF and subtracting the 'real value' of all bytes sent from and including the byte count field until the checksum itself. In this context, 'real value' means the value of the byte before it is expanded into two ASCII characters. 51/134 65 ST7ASMLK The record is concluded by a CR-LF combination $0A, $0D. The S0 and S9 (i.e., header and EOF) records are always the same: S00600004844521B and: S9030000FC a complete example of S-record transmission may look like: S00600004844521B S113001AFF120094FF130094D08AFF390094FF1250 S20801C004FFC0000073 where 0000 are four ASCII zeroes, and LABEL is five ASCII characters. There are two spaces after the SX and one space after the 0000. 0000 represents the hexadecimal value of the label. LABEL may extend to 31 characters, and end with a carriage return. 6.3.4 ST 2 and ST 4 S-record Format 6.3.5 GP Binary 52/134 66 ST7ASMLK 7 LIBRARIAN 7.1 OVERVIEW If you do a lot of work on similar boards especially those with the same processor, it makes a great deal of sense to reuse lumps of code you've already written to do the same task in a different program. At the simplest level, you could just copy the source code as a block of text into the new program. This works fine, but has a subtle disadvantage: if you update the subroutine, you have to hunt around all the usages of it, performing the update on each. To get around this problem, many people have the source for common routines in one place, and link the .OBJ module with each program needing routine. Then you only need to update the source code once, reassemble it to get a new .OBJ file, then link again all the users of the routine, who will now have the new .OBJ file. This scheme works good, too. But it generates some problems of its own. For example, each routine needs its own .OBJ file. By their nature, these common routines tend to be small, so you end up giving dozens of extra .OBJ modules to the linker, and having the .OBJ modules scattered around your disc. The base concept of a librarian is to combine all these small, useful .OBJ modules into one large .LIB library file. You could then tell the linker about the library, and it would take care of sorting out which .OBJ modules to pull into link. It would know which ones to pull by the fact that the main code being linked would have undefined externals, for example, to call the missing library routines. The librarian simply takes each undefined external in turn, and checks it against all the modules in the library. If any of the modules declares a PUBLIC of the same name, it knows you need that .OBJ module and it includes it automatically. 7.2 INVOKING THE LIBRARIAN The librarian is called LIB, and takes one command line argument that is the name of the library to operate on. If not given, you'll be prompted for it. LIB [library name] .LIB is added if the suffix is left off. If the library you gave doesn't exist, LIB asks you if it's a new library. 53/134 67 ST7ASMLK Example: LIB LIB1 SGS-THOMSON Microelectronics - Librarian - rel 1.00 Couldn't open Library file 'LIB1.LIB' is it a new file? (y/n): y If the answer is 'n', LIB aborts. If the library exists, LIB prints up a report on the library. Library LIB1.LIB is 2K long. 16/1024 Public labels used in 2/128 modules. Next you're faced with the main prompt: LIB1.LIB: Operation ( Pressing ENTER gives you access to the following options: Table 13: Operation +filename -filename !filename *filename ? x Description add/update object module to/in library delete object module from library update object module in library copy object module to separate file from library list contents of library Exit to DOS 54/134 68 ST7ASMLK 7.3 ADDING MODULES TO A LIBRARY Typing for example: +user1\board would look for a file, called user1\board.obj, and add it to the library. If LIB can't find the named file, LIB reports the fact and returns to the operations prompt. Else LIB issues the following message: Adding new board.obj ... 15 labels added Done. If the library already contained a file board.obj, it would prompt you with: board.obj already in library LIB1.LIB, replace with board.obj (Y/N): Responding with 'N' returns you to the operations prompt, while 'Y' first removes the old board.obj then continues as above. 7.4 DELETING MODULES FROM A LIBRARY This is done by, for example: -board If LIB cannot find board.obj in the current library, it reports an error and aborts back to the operation prompt. If it can find it, it makes sure you know what you are doing with: board.obj to be deleted from library LIB1.LIB: Are you sure (Y/N): N' aborts to operation prompt. 'Y' continues, reporting: Removing old board.obj ... Done. 55/134 69 ST7ASMLK 7.5 COPYING MODULES FROM A LIBRARY To make a copy of a .OBJ module in a library back to disc, use, for example: *board This will check the existence of board.obj in the current library, if not it'll report the failure and abort the operation prompt. If it does find it, it invites you to give it the name of the disc file to create to contain the copy of the .OBJ module. Copy into .obj file [board.obj]: if you type File board.obj already exists; overwrite? (Y/N): Again, responding 'N' aborts to the operations prompt, while 'Y' does the copy with the message: Copying board.obj to disk... Done. 7.6 GETTING DETAILS IN YOUR LIBRARY The last operation: ? causes LIB to print out details on the current library. Library LIB1.LIB is 2K long 16/1024 Publics labels used on 2/128 modules 0: z1.obj (z1.asm) length 2DE 1: board.obj (board.asm) length 7FFF The name in brackets is the source module from which the named object module was assembled. 56/134 70 ST7ASMLK Appendix A A ASSEMBLER DIRECTIVES A.1 Introduction Each directive has been given a new section to itself, and an entry in the index. The name of the directive, which will always appear in the second field is given in the heading at the top of the section. Next there is a line showing arguments allowed (if any) for this directive. The penultimate section describes the action of the directive and the format and nature of the argument specified in the previous section, and the last section gives one or more example of the directive in use. There is a 'see also' cross reference at the bottom of the page. All the directives must be placed in the second, OPCODE, field, with any arguments one tab away in the argument field. 57/134 71 ST7ASMLK A.2 .BELL Purpose: Format: Description: Ring bell on console. .BELL This directive simply rings the bell at the console; it can be used to signal the end of pass-1 or pass-2 with #IF1 or #IF2. This directive does not generate assembly code or data. .BELL Example: See Also: 58/134 72 ST7ASMLK A.3 BYTE Purpose: Format: Description: Define byte in object code. BYTE 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 See Also: DC.B, STRING, WORD, LONG, DC.W, DC.L 59/134 73 ST7ASMLK A.4 BYTES Purpose: Format: Description: Label type definition type=byte. BYTES When a label is defined, 4 separate attributes are defined with it: scope (internally or externally defined), value (actual numerical value of the label), relativity (absolute or relative), and length, (BYTE, WORD and LONG). All these attributes except length are defined explicitly before or at the definition: you can force the label to be a certain length by giving a dot suffix, eg. 'label.b' forces it to be byte length. You may also define a default state for label length: labels are created to this length unless otherwise forced with a suffix. The default is set to WORD at the start of the assembly, but may be changed by BYTES, WORDS or LONGS to the appropriate length. Example: lab1 BYTES EQU 5 ; byte length for lab1 See Also: LONGS, WORDS 60/134 74 ST7ASMLK A.5 CEQU Purpose: Format: Description: Equate preexisting label to expression. label CEQU This directive is similar to EQU, but allows to change the label's value. Used in macros and as counter for REPEAT / UNTIL. Example: lab1 CEQU {lab1+1} ; inc lab1 See Also: EQU, REPEAT, UNTIL 61/134 75 ST7ASMLK A.6 .CTRL Purpose: Format: Description: Send control codes to the printer. .CTRL Example: .CTRL 27,18 See Also: .LIST, .NOLIST, .BELL 62/134 76 ST7ASMLK A.7 DATE Purpose: Format: Description: Define 12-byte ASCII date into object code. DATE This directive leaves a message for the linker to place the date of the link in a 12-byte block the assembler leaves spare at the position of the DATE directive. This means that every link will leave its date in the object code, allowing automatic version control. The date takes the form (in ASCII) DD_MMM_YYYY where character '_' represents a space; for example 18 JUL. 1988. The date is left for the linker to fill instead of the assembler since the source code module containing the DATE directive may not be reassembled after every editing session and it would be possible to lose track. Example: DATE See Also: 63/134 77 ST7ASMLK A.8 DC.B Purpose: Format: Description: Define byte(s) in object code. DC.B 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 See Also: 64/134 78 ST7ASMLK A.9 DC.W Purpose: Format: Description: Define word(s) in object code. DC.W Example: DC.W 1,2,3,4,$1234 ;0001,0002,0003,0004,1234 See Also: DC.B, BYTE, STRING, WORD, LONG, DC.L 65/134 79 ST7ASMLK A.10 DC.L Purpose: Format: Description: Define long word(s) in object code. DC.L Example: DC.L 1,$12345678 LONG 1,$12345678 ; 0000,0001,1234,5678 ; 0100,0000,7856,3421 See Also: DC.B, DC.W, BYTE, STRING, WORD, LONG 66/134 80 ST7ASMLK A.11 #DEFINE Purpose: Format: Description: Define manifest constant. #DEFINE Example: #define value 5 ld a,#value ; ld a,#5 See Also: 67/134 81 ST7ASMLK A.12 DS.B Purpose: Format: Description: Define byte space in object code. DS.B [optional number of bytes] This directive is used to 'space out' label definitions. For example let's say we need a set of byte-sized temporary storage locations to be defined in RAM, starting at address $4000. We could write: segment byte at 4000 'RAM' temp1 temp2 equ $4000 equ $4001 which would work fine, however, we recommend you to write: segment byte at 4000 'RAM' temp1 temp2 DS.B DS.B which does the same job. The advantage is that the PC is incremented automatically. There are two other types of DS instructions available for doing WORD and LONG length storage areas: DS.W and DS.L. Note that the areas in question are not initialised to any value; it's merely a way of allocating values to labels. The optional argument specifies how many bytes to allocate; the default is 1. Because no code is generated to fill the space, you are not allowed to use DS.B in segments containing code, only for segments with data definitions. Example: labl DS.B See Also: DS.W, DS.L 68/134 82 ST7ASMLK A.13 DS.W Purpose: Format: Description: Define word space in object code. DS.W [optional number of words] This directive is used to 'space out' label definitions. For example let's say we need a set of word-sized temporary storage locations to be defined in RAM, starting at address $4000. We could write: segment byte at 4000 'RAM' temp1 temp2 equ $4000 equ $4002 which would work fine, however, we recommend you to write: segment byte at 4000 'RAM' temp1 temp2 DS.W DS.W which does the same job. The advantage is that the PC is incremented automatically. There are two other types of DS instructions available for doing BYTE and LONG length storage areas: DS.B and DS.L. Note that the areas in question are not initialised to any value; it's merely a way of allocating values to labels. The optional argument specifies how many bytes to allocate; the default is 1. Because no code is generated to fill the space, you are not allowed to use DS.W in segments containing code, only for segments with data definitions. Example: labl DS.W See Also: DS.B, DS.L 69/134 83 ST7ASMLK A.14 DS.L Purpose: Format: Description: Define long space in object code. DS.L [optional number of long words] This directive is used to 'space out' label definitions. For example let's say we need a set of long-word-sized temporary storage locations to be defined in RAM, starting at address $4000. We could write: segment byte at 4000 'RAM' temp1 temp2 equ $4000 equ $4004 which would work fine, however, we recommend you to write: segment byte at 4000 'RAM' temp1 temp2 DS.L DS.L which does the same job. The advantage is that the PC is incremented automatically. There are two other types of DS instructions available for doing BYTE and WORD length storage areas: DS.B and DS.W. Note that the areas in question are not initialised to any value; it's merely a way of allocating values to labels. The optional argument specifies how many bytes to allocate; the default is 1. Because no code is generated to fill the space, you are not allowed to use DS.L in segments containing code, only for segments with data definitions. Example: labl DS.L See Also: DS.B, DS.W 70/134 84 ST7ASMLK A.15 END Purpose: Format: Description: End of source code. END This directive marks the end of the assembly on the main source code file. If no END directive is supplied in a source-code file then an illegal EOF error will be generated by the assembler. Include files do not require an END directive. END Example: See Also: 71/134 85 ST7ASMLK A.16 EQU Purpose: Format: Description: Equate the label to expression. label EQU Example: See Also: labl END 5 72/134 86 ST7ASMLK A.17 EXTERN Purpose: Format: Description: Declare external labels. EXTERN When your program consists of several modules, some modules need to refer to labels that are defined in other modules. Since the modules are assembled separately, it is not until the link stage that all the necessary label values are going to be known. Whenever a label appears in an EXTERN directive, a note is made for the linker to resolve the reference. Declaring a label external is just a way of telling the assembler not to expect that label to be defined in this module, although it will be used. Obviously, external labels must be defined in other modules at link stage, so that all the gaps left by the assembler can be filled with the right values. Because the labels declared external are not actually defined, the assembler has no way of knowing the length, i.e., (byte, word or long) of the label. Therefore, a suffix must be used on each label in an EXTERN directive declaring its type; if the type is undefined, the current default label scope (set by BYTES, WORDS, LONGS directives) is assumed. Example: EXTERN label.w, label1.b, label2.l See Also: PUBLIC 73/134 87 ST7ASMLK A.18 #ELSE Purpose: Format: Description: Conditional ELSE. #ELSE This directive forces execution of the statements until the next #ENDIF if the last #IF statement was found false or disables execution of the statements until the next #ENDIF if the last #IF statement was found true. The #ELSE is optional in #IF / #ENDIF structures. In case of nested #ELSE statements, a #ELSE refers to the last #IF. Example: #IF {1 eq 0} #ELSE ; block B ... assembled #ENDIF ; ; block A ... not assembled See Also: #IF, #ENDIF 74/134 88 ST7ASMLK A.19 #ENDIF Purpose: Format: Description: Conditional terminator. #ENDIF This is the non optional terminator of a #IF structure. If there is only one level of #IF nesting in force, then the statements after this directive will never be ignored, no matter what the result of the previous #IF was. In other words, the #ENDIF ends the capability of the previous #IF to suppress assembly. When used in a nested situation it does the same job, but if the last #IF / #ENDIF structure was in a block of source suppressed by a previous #IF still in force, the whole of the last #IF / #ENDIF structure will be ignored no matter what the result of the previous #IF was. Example: #IF {count gt 0} ... #ENDIF See Also: #IF, #ELSE 75/134 89 ST7ASMLK A.20 FCS Purpose: Format: Description: Form constant string. FCS <"string"> | Example: FCS "ALLO" STRING "ALLO" ; 41,4C,4C,CF ; 41,4C,4C,4F See Also: STRING 76/134 90 ST7ASMLK A.21 .FORM Purpose: Format: Description: Set form length of the listing device. .FORM Example: .FORM 72 See Also: TITLE, SUBTTL, %OUT, .LALL, .XALL, .SALL, .LIST,.NOLIST 77/134 91 ST7ASMLK A.22 GROUP Purpose: Format: Description: Name area of source code. GROUP Example: GROUP mainloop See Also: 78/134 92 ST7ASMLK A.23 #IF Purpose: Format: Description: Start conditional assembly. #IF Example: #IF {1 eq 1} %out true #FALSE %out false #ENDIF See Also: #ENDIF, #ELSE, #IF1, #IF2 79/134 93 ST7ASMLK A.24 #IF1 Conditional Purpose: Format: Description: Conditional on being in pass #1. #IF1 This directive works just like #IF except it has no argument and only evaluates itself as true if the assembler is on its first pass through the source code. Can use #ELSE and requires #ENDIF. Example: #IF1 %OUT "Starting Assembly" #ENDIF See Also: #IF2, #ELSE, #IF, #ENDIF 80/134 94 ST7ASMLK A.25 #IF2 Purpose: Format: Description: Conditional on being in pass #2. #IF2 This directive works just like #IF except it has no argument and evaluates itself as true only if the assembler is on its second pass through the source code. Example: #IF2 %OUT "GONE through PASS-1 OK" #ENDIF See Also: #IF1, #IF, #ENDIF, #ELSE 81/134 95 ST7ASMLK A.26 #IFB Purpose: Format: Description: Conditional on argument being blank. #IFB Example: check MACRO param1 #IFB param1 %OUT "No param1" #ELSE %OUT param1 #ENDIF MEND ... check , check 5 See Also: #IF2, #ELSE, #IF, #END 82/134 96 ST7ASMLK A.27 #IFIDN Purpose: Format: Description: Conditional on arguments being identical. #IFIDN Example: check MACRO param1 #IFIDN param1 HELLO %OUT "Hello" #ELSE %OUT "No Hello" #ENDIF MEND See Also: #IF2, #ELSE, #IF, #END 83/134 97 ST7ASMLK A.28 #IFDEF Purpose: Format: Description: Conditional on argument being defined. #IFDEF Example: check MACRO param1 #IFDEF param1 %OUT "Arg is OK" #ELSE %OUT "Arg is undefined" #ENDIF MEND See Also: #IF2, #ELSE, #IF, #END 84/134 98 ST7ASMLK A.29 #IFLAB Purpose: Format: Description: Conditional on argument being a label. #IFLAB Example: check MACRO param1 #IFLAB param1 %OUT "LABEL" #ENDIF MEND See Also: #IF2, #ELSE, #IF, #END 85/134 99 ST7ASMLK A.30 #INCLUDE Purpose: Format: Description: Insert external source code file. #INCLUDE " Example: st7/ #include "defst7.h" ... END See Also: 86/134 100 ST7ASMLK A.31 INTEL Purpose: Format: Description: Force Intel-style radix specifier. INTEL The Intel style: 0ABh 17o or 17q 100b 17 $ Hexadecimal Octal Binary Decimal (default) Current program counter This directive forces the INTEL format to be required during the assembly. Example: INTEL ld X,0FFFFh See Also: MOTOROLA, TEXAS, ZILOG 87/134 101 ST7ASMLK A.32 .LALL Purpose: Format: Description: List whole body of macro calls. .LALL This directive forces the complete listing of a macro expansion each time a macro is invoked. This is the default. This directive does not generate assembly code or data. Example: .LALL See Also: .XALL, .SALL 88/134 102 ST7ASMLK A.33 .LIST Purpose: Format: Description: Enable listing (default). .LIST This directive switches on the listing if a previous .NOLIST has disabled it. The -'pa' or -'li' options must also have been set from the command line to generate a listing. This directive, in conjunction with the directive .NOLIST, can be used to control the listing of macro definitions. This directive does not generate assembly code or data. Example: .LIST See Also: .NOLIST 89/134 103 ST7ASMLK A.34 #LOAD Purpose: Format: Description: Load named object file at link time. #LOAD "path-name[.ext]" This directive leaves a message for the linker to load the contents of the named file at the current position in the current segment. The file should be in 'straight binary' format, i.e., a direct image of the bytes you want into the object code. Example: segment byte at 8000-C000 'EPROM1' #LOAD "table.hex" See Also: 90/134 104 ST7ASMLK A.35 LOCAL Purpose: Format: Description: Define labels as local to macro. LOCAL waiter MACRO ads loop ld A,ads jrne loop MEND If this macro is called twice, you will be creating two labels called 'loop'. The answer is to declare very early in the MACRO all labels created by the macro as LOCAL. This has the effect of replacing the actual name of a local label (here 'loop') with LOCXXXX where XXXX starts from 0 and increments each time a local label is used. This provides each occurrence of the labels created inside the macro with a unique identity. Example: waiter MACRO ads LOCAL loop loop ld A,ads jrne loop MEND See Also: MACRO, MEND 91/134 105 ST7ASMLK A.36 LONG Purpose: Format: Description: Define long word in object code. LONG Example: DC.L 1,$12345678 LONG 1,$12345678 ; 0000,0001,1234,5678 ; 0100,0000,7856,3421 See Also: DC.B, DC.L, DC.W, BYTE, STRING, WORD 92/134 106 ST7ASMLK A.37 LONGS Purpose: Format: Description: Default new label length long. LONGS When a label is defined, four SEPARATE attributes are defined with it: scope (internally or externally defined), value (actual numerical value of the label), relativity (absolute or relative), and lastly, length (BYTE, WORD or LONG). All these attributes except length are defined explicitly before or at the end of the definition: you can force a label to be a certain length by giving a dot suffix, eg. 'label.b' forces it to be byte length. You may also define a default state for label length: labels are created to this length unless otherwise forced with a suffix. The default is set to WORD at the start of the assembly, but may be changed by BYTES, WORDS or LONGS to the appropriate length. Example: lab1 LONGS EQU 5 ; long length for lab1 See Also: BYTES, WORDS 93/134 107 ST7ASMLK A.38 MACRO Purpose: Format: Description: Define macro template. Example: cmp16 MACRO first,second,result LOCAL trylow ld A,first add A,second cp A,#0 jreq trylow cpl A ld result,A MEND trylow See Also: MEND, .LALL, .SALL, .XAL 94/134 108 ST7ASMLK A.39 MEND Purpose: Format: Description: Example: End of macro definition. MEND End of macro definition. cmp16 trylow MACRO first,second,result LOCAL trylow ld A,first add A,second cp A,#0 jreq trylow cpl A ld result,A MEND See Also: MACRO 95/134 109 ST7ASMLK A.40 MOTOROLA Purpose: Format: Description: Force Motorola-style radix specifier. MOTOROLA The Motorola style: $AB ~17 %100 17 * Hexadecimal Octal Binary Decimal (default) Current program counter This directive forces the Motorola format to be required during the assembly. The default format is MOTOROLA. Example: MOTOROLA ld X,$FFFF See Also: INTEL, TEXAS, ZILOG 96/134 110 ST7ASMLK A.41 .NOCHANGE Purpose: Format: Description: List original #define strings. .NOCHANGE Strings named in the first argument of a #DEFINE directive will be changed to the second argument of the #DEFINE: the default is that the changed strings will be listed. If you want the original source code to be listed instead, place a .NOCHANGE directive near the start of your source code. This directive does not generate assembly code or data. Example: .NOCHANGE See Also: #DEFINE 97/134 111 ST7ASMLK A.42 .NOLIST Purpose: Format: Description: Turn off listing. .NOLIST Certain parts of your modules may not be required on a listing; this directive disables the listing until the next .LIST directive. The default is for the listing to be enabled. This directive, in conjunction with the directive .LIST, can be used to control the listing of macro definitions. This directive does not generate assembly code or data. Example: .NOLIST See Also: LIST 98/134 112 ST7ASMLK A.43 %OUT Purpose: Format: Description: Output string to the console. %OUT string This directive prints its argument (which does not need to be enclosed in quotes) to the console. This directive does not generate assembly code or data. Example: %OUT hello! See Also: 99/134 113 ST7ASMLK A.44 .PAGE Purpose: Format: Description: Perform a form feed. .PAGE Forces a new page listing. This directive does not generate assembly code or data. Example: .PAGE See Also: 100/134 114 ST7ASMLK A.45 PUBLIC Purpose: Format: Description: Make labels public. PUBLIC Example: module1.asm EXTERN print.w, print1.w ... call print ... jp print1 module2.asm PUBLIC print print nop .print1 nop See Also: EXTERN 101/134 115 ST7ASMLK A.46 REPEAT Purpose: Format: Description: Assembly-time loop initiator. REPEAT Used together with UNTIL to make assembly-time loops; it is useful for making tables etc. This directive should not be used within macros. Example: REPEAT See Also: CEQU, UNTIL 102/134 116 ST7ASMLK A.47 .SALL Purpose: Format: Description: Suppress all body of called macro. .SALL This directive forces the complete suppression of the listing of a macro expansion each time a macro is invoked. This instruction itself is never listed. Note:This directive may produce confusing listings. Example: .SALL See Also: .LALL, .XALL 103/134 117 ST7ASMLK A.48 SEGMENT Purpose: Format: Description: Start of new segment. [ Align Type: byte no alignment; can start on any byte boundaries word aligned to next word boundaries if necessary, i.e., 8001=8002 para aligned to the next paragraph (=16 bytes) boundary, i.e., 8001=8010 64 128 aligned to the next 64-byte boundary, i.e., 8001=8040 aligned to the next 128-byte boundary, i.e., 8001=8080 page aligned to the next page (=256 bytes) boundary ,i.e., 8001=8100 long aligned to the next long-word(=4 bytes) boundary, i.e., 8001=8004 1K 4K aligned to next 1K boundaries, i.e., 8001=8400 aligned to next 4K boundaries, i.e., 8001=9000 104/134 118 ST7ASMLK SEGMENT (Continued) Combine:at X[-Y] Introduces new class that starts from X and goes through to address Y. Address Y is optional. Tack this code on the end of the last segment of this class. Put the segment at the same address than other common segments that have the same name, and note the longest length segment. The optional [cod] suffix is a number from 0 to 9 - it decides into which. COD file the linker sends the contents of this class. 0 is the default and is chosen if the suffix is left off. A suffix of 1-9 will cause the linker to open the [cod] suffix, and send the contents of this class into the cod file instead of the default. This allows bank switching to be supported directly at link level- different code areas at the same address can be separated out into different .cod files. See Also: For more information, see Chapter 3, "Segmentation" on page 31 105/134 119 ST7ASMLK A.49 .SETDP Purpose: Format: Description: Set base address for direct page. .SETDP Example: .SETDP $400 ld A,$401 ; direct mode chosen See Also: 106/134 120 ST7ASMLK A.50 SKIP Purpose: Format: Description: Inserts given number of bytes with an initialization value. SKIP Example: SKIP 100,$FF ; insert 100 bytes all $FF See Also: 107/134 121 ST7ASMLK A.51 STRING Purpose: Format: Description: Define a byte-level string. STRING 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 See Also: DC.B, BYTE, WORD, LONG, DC.W, DC.L, FCS 108/134 122 ST7ASMLK A.52 SUBTTL Purpose: Format: Description: Define a subtitle for listing heading. SUBTTL " Example: SUBTTL "A/D control routines" See Also: TITLE 109/134 123 ST7ASMLK A.53 .TAB Purpose: Format: Description: Set listing field lengths. .TAB |
Price & Availability of 6135
 |
|
|
|
|
All Rights Reserved © IC-ON-LINE 2003 - 2022 |
| [Add Bookmark] [Contact Us] [Link exchange] [Privacy policy] |
|
Mirror Sites : [www.datasheet.hk]
[www.maxim4u.com] [www.ic-on-line.cn]
[www.ic-on-line.com] [www.ic-on-line.net]
[www.alldatasheet.com.cn]
[www.gdcy.com]
[www.gdcy.net] |