166/167 assembler and utilitiesee192/sp05/documents/... · 2004-04-06 · 166/167 assembler and...

166/167 Assemblerand Utilities

A166 Macro AssemblerL166 Linker/Locator

LIB166 Library ManagerOH166 Object File Converter

RTX166 Tiny Real-Time Operating SystemMonitor166 Target Monitor

User’s Guide 07.96

ii Keil Software

Information in this document is subject to change without notice and does notrepresent a commitment on the part of the manufacturer. The software describedin this document is furnished under license agreement or nondisclosure agreementand may be used or copied only in accordance with the terms of the agreement. Itis against the law to copy the software on any medium except as specificallyallowed in the license or nondisclosure agreement. The purchaser may make onecopy of the software for backup purposes. No part of this manual may bereproduced or transmitted in any form or by any means, electronic or mechanical,including photocopying, recording, or information storage and retrieval systems,for any purpose other than for the purchaser’s personal use, without writtenpermission.

Copyright © 1990-1996 Keil Elektronik GmbH., and Keil Software, Inc.All rights reserved.

Keil C166™ and dScope™ are trademarks of Keil Elektronik GmbH.Microsoft®, MS-DOS®, and Windows™ are trademarks or registered trademarksof Microsoft Corporation.IBM®, PC®, and PS/2® are registered trademarks of International BusinessMachines Corporation.

Every effort was made to ensure accuracy in this manual and to give appropriatecredit to persons, companies, and trademarks referenced herein.

166/167 Assembler and Utilities iii

PrefaceThis manual describes the application range and use of the A166 MacroAssembler and utilities. The assembler translates programs written in assemblylanguage into executable machine instructions. The A166 assembler may be usedfor all processors of the 166/167 family including the 80C167CR and the 80C165.This user’s guide assumes that you are familiar with the MS-DOS operatingsystem and how to program the 166/167 processors.

This user’s guide is divided into the following eight chapters:

“Chapter 1. Introduction”, describes the operation of A166, L166, LIB166 andOH166 and explains their functions with a sample program.

“Chapter 2. Operands and Expressions”, describes the operands, addressdescriptors, and the rules for arithmetic and logical expressions.

“Chapter 3. Assembler Directives”, describes the A166 Assembler directives thatdefine symbols and segments as well as control the memory of the 166/167 CPU.

“Chapter 4. Invocation and Controls”, describes the control instructions thateffect the operation of the A166 assembler.

“Chapter 5. The Macro Processor”, describes the function and controlinstructions of the macro processor and the necessary instruction control for use.

“Chapter 6. Error Messages”, contains a list of all A166 error messages anddescribes their causes and how to avoid them.

“Chapter 7. Implementation Specifics”, contains a list of reserved words,predefined special function registers and all the 166/167 instructions.

“Chapter 8. L166 Linker/Locator”, describes the linker and explains how to usethe command-line directives. This chapter also includes a reference section of alllinker directives and application examples.

The Appendix explains the 166/167 utility tools: LIB166 Library Manager,OH166 Object Hex Converter, RTX166 Tiny Real-Time Operating System,Monitor-166 Target Monitor, the dScope Monitor Interface, and the AMAKEDOS-based Project Management Utility.

iv Preface

Document ConventionsThis document uses the following conventions:

Examples Description

README.TXT Bold capital text is used for the names of executable programs, data files,source files, environment variables, and commands you enter at theMS-DOS command prompt. This text usually represents commands thatyou must type in literally. For example:

CLS DIR L166.EXE

Note that you are not required to enter these commands using all capitalletters.

Courier Text in this typeface is used to represent information that displays on screenor prints at the printer.

This typeface is also used within the text when discussing or describingcommand line items.

Variables Text in italics represents information that you must provide. For example,projectfile in a syntax string means that you must supply the actual projectfile name.

Occasionally, italics are also used to emphasize words in the text.

Elements that repeat… Ellipses (…) are used in examples to indicate an item that may be repeated.

Omitted code...

Vertical ellipses are used in source code examples to indicate that afragment of the program is omitted. For example:

void main (void) {...while (1);

�Optional Items� Optional arguments in command-line and option fields are indicated bydouble brackets. For example:

A166 TEST.A66 PRINT �( filename ) �{ opt1 | opt2 } Text contained within braces, separated by a vertical bar represents a group

of items from which one must be chosen. The braces enclose all of thechoices and the vertical bars separate the choices. One item in the listmust be selected.

Keys Text in this sans serif typeface represents actual keys on the keyboard. Forexample, “Press Enter to continue.”

166/167 Assembler and Utilities v

Contents

Chapter 1. Introduction................................................................................... 1What is an Assembler? ............................................................................................ 1How to Develop A Program..................................................................................... 2

Advantages of Modular Programming................................................................ 2Efficient Program Development......................................................................... 2Multiple Use of Subprograms............................................................................. 3Ease of Debugging and Modifying..................................................................... 3

Modular Program Development Process.................................................................. 3Sections, Modules, and Programs....................................................................... 3Program Entry and Exit ..................................................................................... 4Assembly........................................................................................................... 4Relocation and Linkage...................................................................................... 4Keeping Track of Files....................................................................................... 5

Writing and Assembling Programs .......................................................................... 6

Chapter 2. Operands and Expressions.......................................................... 11Instruction Operands ............................................................................................. 12Expressions........................................................................................................... 13Numbers................................................................................................................ 13Character Strings................................................................................................... 13Symbols................................................................................................................. 14

Labels.............................................................................................................. 15Special Assembly Symbols............................................................................... 16

Operators............................................................................................................... 17Addition and Subtraction ................................................................................. 18Multiplication, Division, Modulo..................................................................... 19Sign Operators ................................................................................................. 19Shift Operators................................................................................................. 20Relational Operators........................................................................................ 20Logical Operators............................................................................................. 20HIGH and LOW............................................................................................... 21DOT Operator.................................................................................................. 21Page Override Operator.................................................................................... 22PTR Operator................................................................................................... 22DATA Operator............................................................................................... 23SHORT Operator............................................................................................. 24SEG Operator .................................................................................................. 25PAG Operator.................................................................................................. 25SOF Operator................................................................................................... 26POF Operator................................................................................................... 26BOF Operator.................................................................................................. 27

Chapter 3. Assembler Directives................................................................... 31SECTIONS............................................................................................................ 31

vi Contents

SECTION / ENDS............................................................................................32GROUP..................................................................................................................37ASSUME...............................................................................................................38REGDEF / REGBANK..........................................................................................41PECDEF................................................................................................................42SSKDEF................................................................................................................42PROC / ENDP........................................................................................................43EQU.......................................................................................................................46SET........................................................................................................................47BIT ........................................................................................................................48LABEL ..................................................................................................................49DEFR / DEFA / DEFB...........................................................................................50LIT ........................................................................................................................52TYPEDEC.............................................................................................................53ORG ......................................................................................................................53EVEN....................................................................................................................54EXTERN / EXTRN................................................................................................55PUBLIC / GLOBAL...............................................................................................57Defining and Initializing Variables ........................................................................59Defining and Initializing Pointers ..........................................................................62NAME ...................................................................................................................63END.......................................................................................................................63

Chapter 4. Invocation and Controls................................................................65Running A166........................................................................................................65

Command Files.................................................................................................66DOS ERRORLEVEL........................................................................................66Output Files......................................................................................................67

Assembler Controls................................................................................................67ABSOLUTE.....................................................................................................70CASE / NOCASE.............................................................................................71COND / NOCOND...........................................................................................72DATE...............................................................................................................73DEBUG / NODEBUG.......................................................................................74EJECT..............................................................................................................75ERRORPRINT / NOERRORPRINT..................................................................76EXPDECNUM.................................................................................................77GEN / GENONLY / NOGEN...........................................................................78INCDIR............................................................................................................79INCLUDE ........................................................................................................80LIST / NOLIST................................................................................................81MACRO / NOMACRO.....................................................................................82MOD166 / NOMOD166...................................................................................83MOD167..........................................................................................................84OBJECT / NOOBJECT.....................................................................................85PAGELENGTH................................................................................................86PAGEWIDTH..................................................................................................87

166/167 Assembler and Utilities vii

PAGING / NOPAGING................................................................................... 88PRINT / NOPRINT.......................................................................................... 89REGUSE.......................................................................................................... 90SAVE / RESTORE.......................................................................................... 92SEGMENTED / NONSEGMENTED............................................................... 93SYMBOLS / NOSYMBOLS............................................................................ 94TABS............................................................................................................... 95TITLE.............................................................................................................. 96TYPE / NOTYPE............................................................................................. 97USEDEXTONLY............................................................................................. 98XREF / NOXREF............................................................................................ 99

Directives for Conditional Assembly.....................................................................100SET / RESET..................................................................................................101IF....................................................................................................................102ELSEIF...........................................................................................................103ELSE..............................................................................................................104ENDIF............................................................................................................105

Chapter 5. The Macro Processor................................................................ 107Introduction..........................................................................................................107

Overview.........................................................................................................107Creating and Calling Macros ..........................................................................107Creating Parameterless Macros .......................................................................108Macros with Parameters ..................................................................................109Local Symbols List..........................................................................................111

Macro Processor Functions...................................................................................111Comment Function..........................................................................................112Escape Function..............................................................................................112Bracket Function.............................................................................................113METACHAR Function...................................................................................114Numbers and Expressions...............................................................................114SET Function..................................................................................................116EVAL Function...............................................................................................117Logical Expressions and String Comparison ...................................................118

Conditional Macro Processing..............................................................................119IF Function .....................................................................................................119WHILE Function.............................................................................................120REPEAT Function..........................................................................................121EXIT Function................................................................................................121

String Manipulation Functions .............................................................................122LEN Function.................................................................................................122SUBSTR Function...........................................................................................123MATCH Function...........................................................................................123

Console I/O Functions..........................................................................................124Advanced Macro Processing.................................................................................125

Literal Delimiters............................................................................................126Blank Delimiters.............................................................................................127

viii Contents

Identifier Delimiters .......................................................................................127Literal and Normal Mode................................................................................128

MACRO Errors....................................................................................................129

Chapter 6. Error Messages..........................................................................131Fatal Errors..........................................................................................................131Non-Fatal Errors ..................................................................................................134

Chapter 7. Implementation Specifics...........................................................145Implementation Limits .........................................................................................145166/167 Instruction Set ........................................................................................145

Basic Instruction Set.......................................................................................146Software Instruction Set..................................................................................148

Reserved Words in A166......................................................................................149Predefined SFR and Bit Names............................................................................151

Chapter 8. L166 Linker/Locator .................................................................153L166 Overview.....................................................................................................155

Combining program modules..........................................................................156Sections..........................................................................................................156Section Alignment ..........................................................................................156Combining Sections........................................................................................157Classes............................................................................................................157Groups............................................................................................................158Allocating 166/167 Memory...........................................................................159Producing a Listing File..................................................................................160Using RTX166 and RTX166 Tiny..................................................................161

Linking Programs with L166................................................................................161Long Command Lines....................................................................................163Command Files...............................................................................................163Command-Line Examples...............................................................................163DOS Errorlevel...............................................................................................164Entering Names in Lower Case.......................................................................164Command-Line Directives..............................................................................165ASSIGN.........................................................................................................168CLASSES.......................................................................................................169DPPUSE.........................................................................................................170GROUPS........................................................................................................172INTNO ...........................................................................................................173IXREF............................................................................................................174LINKONLY ...................................................................................................175NAME............................................................................................................176NOAMAKE....................................................................................................177NOCASE........................................................................................................178NOCOMMENTS............................................................................................179NODEFAULTLIBRARY ................................................................................180NOINIT ..........................................................................................................181NOLINES.......................................................................................................182

166/167 Assembler and Utilities ix

NOMAP..........................................................................................................183NOPUBLICS..................................................................................................184NOTYPE........................................................................................................185NOVECTAB...................................................................................................186OBJECTCONTROLS.....................................................................................187PAGELENGTH..............................................................................................188PAGEWIDTH.................................................................................................189PRINT............................................................................................................190PRINTCONTROLS........................................................................................191PUBLICSONLY.............................................................................................192PURGE...........................................................................................................193REGBANK.....................................................................................................194REGFILE........................................................................................................195RESERVE......................................................................................................196RTX166..........................................................................................................197RTX166TINY.................................................................................................198SECSIZE........................................................................................................199SECTIONS.....................................................................................................200VECTAB........................................................................................................201WARNINGLEVEL .........................................................................................202

Definition of the Physical Memory Layout............................................................203Advanced Techniques.....................................................................................205

TGROUPS (Siemens Task Concept).....................................................................207Compatibility to Siemens Tools.......................................................................208

Error Messages.....................................................................................................210Warnings ........................................................................................................210Non Fatal Errors .............................................................................................212Fatal Errors.....................................................................................................215Exception Messages........................................................................................218

Application Example ............................................................................................219

Appendix A. LIB166 Library Manager ...................................................... 229Using LIB166.......................................................................................................229Interactive Mode...................................................................................................229Command Summary.............................................................................................230Creating a Library ................................................................................................231Adding Object Modules........................................................................................232Removing Object Modules....................................................................................233Listing Library Contents.......................................................................................234Help Information..................................................................................................235LIB166 Error Messages........................................................................................236

Fatal Errors.....................................................................................................236Errors..............................................................................................................237

Appendix B. OH166 Object-Hex Converter............................................... 239Using OH166........................................................................................................239OH166 Error Messages.........................................................................................240

x Contents

Intel HEX File Format..........................................................................................241Record Format................................................................................................241Data Record....................................................................................................242End-of-File (EOF) Record...............................................................................2428086 Segment Address Record........................................................................243Extended Linear Address Record....................................................................243Example Intel HEX File..................................................................................244

Appendix C. RTX166 TINY........................................................................245Introduction .........................................................................................................245

Round-Robin Task Switching.........................................................................246Wait for Timeout............................................................................................247Wait for Signal ...............................................................................................248Generating RTX166 Applications...................................................................249

RTX166 Tiny Technical Data ..............................................................................250RTX166 Tiny Functions.................................................................................250

RTX166 Full Technical Data ...............................................................................251RTX166 Full Functions..................................................................................251

Software Requirements.........................................................................................253Task Management................................................................................................253

Task Switching...............................................................................................254Task Declaration.............................................................................................255

C166 Specific Support..........................................................................................255Interrupt Handling..........................................................................................256C166 Memory Models....................................................................................256Use of the C166 Run-Time Library.................................................................256

RTX166 Tiny System Functions...........................................................................257Name Assignment ..........................................................................................257Return Values.................................................................................................257Include Files...................................................................................................257Function Overview..........................................................................................259os_clear_signal...............................................................................................260os_create_task.................................................................................................261os_delay_task..................................................................................................262os_delete_task.................................................................................................263os_running_task_id ........................................................................................264os_send_signal / isr_send_signal ....................................................................265os_wait...........................................................................................................266os_wait_signal................................................................................................268

Configuration.......................................................................................................269CONF_TNY.A66............................................................................................269CPUTIMER.INC............................................................................................269Stack Management .........................................................................................270Optimizing RTX166 Tiny Applications ..........................................................271System Debugging..........................................................................................271

Application Examples ..........................................................................................273RTX_EX1: The first RTX166 Program..........................................................273

166/167 Assembler and Utilities xi

RTX_EX2: A simple RTX166 Application....................................................275Traffic: Pedestrian Traffic Light Controller....................................................277

Appendix D. Monitor-166............................................................................ 289Hardware and Software Requirements..................................................................289MON166.EXE: DOS Monitor Driver....................................................................290

MON166.EXE Control Keys...........................................................................292MON166.EXE Terminal Control Codes..........................................................293Serial Transmission Line ................................................................................294MON166.EXE Commands..............................................................................295Help Commands..............................................................................................297Displaying and Changing Memory.................................................................298Breakpoint Commands....................................................................................302Test Commands..............................................................................................305Load and Save.................................................................................................307Predefined Special Function Registers.............................................................308MON166 Error Messages................................................................................309

MON166.DLL: dScope Monitor Driver...............................................................312MON166.DLL Configuration Dialog...............................................................312Restrictions of dScope with MON166.DLL.....................................................313Resources used by Monitor-166.......................................................................314

Monitor-166 Configuration...................................................................................314

Appendix E. AMAKE Project Management Utility.................................... 317Using AMAKE.....................................................................................................317Re-translating an Object File ................................................................................318Re-creating a Linker Output File ..........................................................................319Application-wide Register Optimization...............................................................319List Project Information........................................................................................320Create a Batch File ...............................................................................................321AMAKE Template File........................................................................................322Removing AMAKE Information...........................................................................323AMAKE Invocation..............................................................................................324

Invocation Examples.......................................................................................325AMAKE Error Messages......................................................................................326

Fatal Errors.....................................................................................................326

Glossary........................................................................................................ 329

Index............................................................................................................. 335

xii Contents

166/167 Assembler and Utilities 1

1Chapter 1. Introduction

This manual describes the A166 macro assembler and explains the process ofdeveloping software in assembly language for the 166/167 microcontroller family.

Assembly language programs translate directly into machine instructions whichinstruct the processor what operations to perform. Therefore, to effectively writeassembly programs, you should be familiar with both the microcomputerarchitecture and assembly language. This chapter presents an overview of theA166 macro assembler and how it is used.

What is an Assembler?An assembler is a software tool—a program—designed to simplify the task ofwriting computer programs. It performs the clerical task of translating symboliccode into executable object code. This object code may then be programmed intoan 166/167 microcontroller and executed. If you have ever written a computerprogram directly in machine-recognizable form, such as binary or hexadecimalcode, you will appreciate the advantages of programming in symbolic assemblylanguage.

Assembly language operation codes (mnemonics) are easily remembered (MOVfor move instructions, ADD for addition, and so on). You can also symbolicallyexpress addresses and values referenced in the operand field of instructions. Sinceyou assign these names, you can make them as meaningful as the mnemonics forthe instructions. For example, if your program must manipulate a date as data,you can assign it the symbolic name DATE. If your program contains a set ofinstructions used as a timing loop (a set of instructions executed repeatedly until aspecific amount of time has passed), you can name the instruction groupTIMER_LOOP.

An assembly program has three constituent parts:

� Machine instructions

� Assembler directives

� Assembler controls

A machine instruction is a machine code that can be executed by the machine.Detailed discussion of the machine instructions can be found in the hardware

2 Chapter 1. Introduction

1manuals of the 166/167 microcontrollers. Appendix A provides an overviewabout machine instructions.

Assembler directives are used to define the program structure and symbols, andgenerate non-executable code (data, messages, etc.). Refer to “Chapter 3.Assembler Directives” on page 31 for details on all of the assembler directives.

Assembler controls set the assembly modes and direct the assembly flow.“Chapter 4. Invocation and Controls” on page 65 contains a comprehensive guideto all the assembler controls.

How to Develop A ProgramThe A166 assembler enables the user to program in a modular fashion. Thefollowing paragraphs explain the basics of modular program development.

Advantages of Modular Programming

Many programs are too long or complex to write as a single unit. Programmingbecomes much simpler when the code is divided into small functional units.Modular programs are usually easier to code, debug, and change than monolithicprograms.

The modular approach to programming is similar to the design of hardware thatcontains numerous circuits. The device or program is logically divided into “blackboxes” with specific inputs and outputs. Once the interfaces between the unitshave been defined, the detailed design of each unit can proceed separately.

Efficient Program Development

Programs can be developed more quickly with the modular approach since smallsubprograms are easier to understand, design, and test than large programs. Withthe module inputs and outputs defined, the programmer can supply the neededinput and verify the correctness of the module by examining the output. Theseparate modules are than linked and located by the linker into an absoluteexecutable single program module. Finally, the complete module is tested.


1Multiple Use of Subprograms

Code written for one program is often useful in others. Modular programmingallows these sections to be saved for future use. Because the code is relocatable,saved modules can be linked to any program which fulfills their input and outputrequirements. With monolithic programming, such sections of code are buriedinside the program and are not so available for use by other programs.

Ease of Debugging and Modifying

Modular programs are generally easier to debug than monolithic programs.Because of the well defined module interfaces of the program, problems can beisolated to specific modules. Once the faulty module has been identified, fixingthe problem is considerably simpler. When a program must be modified, modularprogramming simplifies the job. You can link new or debugged modules to anexisting program with the confidence that the rest of the program will not change.

Modular Program Development ProcessThis section is a brief discussion of the program development process with therelocatable A166 assembler, L166 Linker/Locator, and the OH166 codeconversion program.

Sections, Modules, and Programs

In the initial design stages, the tasks to be performed by the program are defined,and then partitioned into subprograms. Here are brief introductions to the kinds ofsubprograms used with the A166 assembler and L166 linker/locator.

A section is a block of code or data memory. A section may be relocatable orabsolute. A relocatable section has a name, type, and other attributes. Sectionswith the same name, from different modules, are considered part of the samesection and are called “partial section.” Partial sections are combined intosections by L166. An absolute segment cannot be combined with other segments.

A module contains one or more segments or partial segments. A module has aname assigned by the user. The module definitions determine the scope of localsymbols.


1A program consists of a single absolute module, merging all absolute andrelocatable segments from all input modules.

Program Entry and Exit

After the design is completed, the source code for each module is entered into adisk file using any text editor. When errors are detected in the developmentprocess, the text editor may be used to make corrections in the source code.

Assembly

The A166 assembler translates the source code into object code. The assemblerproduces a relocatable object file and a listing file showing the results of theassembly. When the assembler invocation contains the DEBUG control, theobject file also receives the debug information for use during the symbolicdebugging of the program. This debugging may be via the dScope-166Debugger/Simulator, or in-circuit emulators available from many vendors.

Object File: the object file contains machine language instructions and data thatcan be loaded into memory for execution or interpretation. In addition, it containscontrol information governing the loading process.

Listing File: The listing file provides both the source program and the objectcode. The assembler also produces diagnostic messages in the listing file forsyntax and other coding errors. For example, if you specify a 16-bit value for aninstruction that can only use an 8-bit value, the assembler tells you that the valueexceeds the permissible range. Appendix F describes the format of the listing file.In addition, you can also request a symbol table to be appended to the listing. Thesymbol table lists all the symbols and their attributes.

Relocation and Linkage

After assembly of all modules of the program, L166 processes the object modulefiles. the L166 program assigns absolute memory locations to all the relocatablesegments, combining segments with the same name and type. L166 also resolvesall references between modules. L166 outputs an absolute object module file withthe completed program, and a summary listing file showing the results of thelink/locate process.


1Keeping Track of Files

It is convenient to use the extensions of filename to indicate the stage in theprocess represented by the contents of each file. Thus, source code files can useextensions like .SRC or .A66 (indicating that the code is for input to the A166assembler). Object code files receive the extension .OBJ by default, or the usercan specify another extension. Executable files generally have no extension.Listing files can use .LST, the default extension assigned by the assembler. L166uses .M66 for the default linker map file extension.


1Writing and Assembling ProgramsThere are several steps necessary to incorporate a 166/167 microcomputer in yourapplication. The following figure shows an overview of the steps involved increating a program for the 166 or a 167 derivative.

Assembler

Source File

A166Macro Assembler

Object

File

L166Linker/Locater

AbsoluteObject

File

OH166Object Hex Converter

HEX

File

dScope-166HLL Debugger

PROM Programmer

In-CircuitEmulator

OtherObjects orLibraries

MAPFile

Listing

File


1If you are developing hardware for your application, consult the 166/167hardware manuals.

Following is an example listing file generated by the assembler.

A166 MACRO ASSEMBLER SAMPLE 24/04/92 15:44:45 PAGE 1

DOS MACRO ASSEMBLER A166 V3.00OBJECT MODULE PLACED IN SAMPLE.OBJASSEMBLER INVOKED BY: E:A166.EXE SAMPLE.A66 SET(SMALL) XREF PW(78)DEBUG

LOC OBJ LINE SOURCE

1 $SEGMENTED 2 3 $IF MEDIUM OR LARGE Model LIT 'FAR' $ELSE 6 Model LIT 'NEAR' 7 $ENDIF 8 9 PUBLIC SERINIT, timerstop, timerstart 10 ASSUME DPP3:SYSTEM 11 12 ?PR?SERINIT section code 13 14 SERINIT proc NEAR 15 16 ;******************************* 17 ;*** INIT SERIAL INTERFACE 0 *** 18 ;******************************* 190000 AFE2 20 BSET P3.10 ; OUTPUT LATCH (TXD)0002 AFE3 21 BSET DP3.10 ; DIR-CONTROL (TXD OUTPUT)0004 BEE3 22 BCLR DP3.11 ; DIR-CONTROL (RXD INPUT)0006 E7B68000 23 MOVB S0TIC,#080H ; TRANSMIT INTERRUPT FLAG000A E7B70000 24 MOVB S0RIC,#000H ; RECEIVE INTERRUPT FLAG000E E65A4000 25 MOV S0BG ,#0040H ; 9600 BAUD0012 E6D81180 26 MOV S0CON,#8011H ; SET SERIAL MODE0016 CB00 27 RET 28 SERINIT endp 29 30 31 timerstart proc NEAR0018 E6A00000 32 MOV T2CON,#0001C E6A10000 33 MOV T3CON,#00020 E6200000 34 MOV T2,#00024 E6210000 35 MOV T3,#00028 E6A14000 36 MOV T3CON,#0040H002C E6A04F00 37 MOV T2CON,#004FH0030 CB00 38 RET 39 timerstart endp 40 41 42 timerstop proc NEAR0032 E6A00000 43 MOV T2CON,#00036 E6A10000 44 MOV T3CON,#0003A F2F442FE 45 MOV R4,T3003E F2F540FE 46 MOV R5,T20042 CB00 47 RET 48 timerstop endp 49 50 ?PR?SERINIT ends 51 52 end


1A166 MACRO ASSEMBLER SAMPLE 24/04/92 15:44:45 PAGE 2

XREF SYMBOL TABLE LISTING---- ------ ----- -------

N A M E TYPE VALUE I ATTRIBUTES

?PR?SERINIT. . . . ---- ---- SECTION 12# 50DP3. . . . . . . . WORD FFC6H A SFR 21 22DPP3 . . . . . . . WORD FE06H A SFR 10MODEL. . . . . . . LIT "NEAR" 6#P3 . . . . . . . . WORD FFC4H A SFR 20S0BG . . . . . . . WORD FEB4H A SFR 25S0CON. . . . . . . WORD FFB0H A SFR 26S0RIC. . . . . . . WORD FF6EH A SFR 24S0TIC. . . . . . . WORD FF6CH A SFR 23SERINIT. . . . . . NEAR 0000H R PUB SEC=?PR?SERINIT 9 14# 28T2 . . . . . . . . WORD FE40H A SFR 34 46T2CON. . . . . . . WORD FF40H A SFR 32 37 43T3 . . . . . . . . WORD FE42H A SFR 35 45T3CON. . . . . . . WORD FF42H A SFR 33 36 44TIMERSTART . . . . NEAR 0018H R PUB SEC=?PR?SERINIT 9 31# 39TIMERSTOP. . . . . NEAR 0032H R PUB SEC=?PR?SERINIT 9 42# 48

ASSEMBLY COMPLETE. 0 WARNING(S), 0 ERROR(S)

The fields in the listing file have the following meaning:

0000 AFE2 20 BSET P3.10 ; OUTPUT LATCH (TXD)

original source line

line number (issued by the assembler)

R/E indicates relocatable or external expression that must becalculated by the Linker/Locator L166

hexadecimal form of the generated object code

state of the address counter in the current section

The symbol table at the end of the listing is as follows:


?PR?SERINIT. . . . ---- ---- SECTION 12# 50DP3. . . . . . . . WORD FFC6H A SFR 21 22DPP3 . . . . . . . WORD FE06H A SFR 10MODEL. . . . . . . LIT "NEAR" 6#

The NAME field shows the name of the symbol. The TYPE field specifies thetype of the symbol which is one of the following:


1Type Description

BIT type bit

BTWRD type BITWORD (word in bit-addressable space)

BYTE type byte (8 bit)

DAT16 a constant value in range 0 to 65535

DATA3 a constant value in range 0 to 7



FAR a label of type far

INTNO a symbolic interrupt number

LIT a text literal

NEAR a label of type near

RBANK a symbolic name for a register bank

SHORT a short label (+127/-128 words short range)

WORD type word (16 bit)

The VALUE field shows the numeric value of the symbol. The value is shown asa hexadecimal number. In case of type LIT , the literal expansion text is shown forthe value.

A character (A) following the value indicates an absolute value. A character (R)following the values designates a relocatable value. Expressions with relocatable,external or section symbols are calculated during link/locate time by L166.

The ATTRIBUTES column shows attributes and line numbers of the particularsymbol:

Attributes Description

EXT The symbol is external in some other module

GLB The symbol is global

GROUP The symbol represents a group name

PUB The symbol is public

SECTION The symbol represents a section name

SFR The symbol is a special function register (SFR)

If the symbol is a member of some section, then the name of the parent sectioncontaining the symbol is displayed in the form SEC=<section_name>.

The line numbers contain each line of code in which the symbol was referenced. Ahash mark (#) following a line number indicates that the value of the symbol wasdefined in that line. A cross reference is listed only if the XREF directive is used.


1 SERINIT. . . NEAR 0000H R PUB SEC=?PR?SERINIT 9 14# 28

relocatable

'SERINIT' was defined (and used) in line 14,and also used in line 9 and 28. The parentsections name is '?PR?SERINIT'

the numerical value of 'LOOP' is 0000H

'SERINIT' is a label of type 'near'

the name of the symbol is 'SERINIT'

To assemble the above module, the assembler was invoked using the followingcommand line:

A166 SAMPLE.A66 SET(SMALL) XREF PW(78)

The assembler output for this command line is:

DOS MACRO ASSEMBLER A166 V3.00COPYRIGHT KEIL ELEKTRONIK GmbH 1992 - 1996


After assembly, the object modules are linked and all variables and addresses areresolved and located into an executable program by the L166 linker. The linker isinvoked with the following command line.

L166 SAMPLE.OBJ

The linker generates an absolute object file as well as a listing file and screenmessages. The screen output for the linker is:

DOS LINKER/LOCATOR L166 V3.00COPYRIGHT KEIL ELEKTRONIK GmbH 1992 - 1996

L166 LINKING COMPLETE, 0 WARNINGS, 0 ERRORS


2

Chapter 2. Operands and ExpressionsAssembler Programs for the 166/167 processor family consist of lines of166/167mnemonic instructions. A line can contain at most one machine instruction. Thegeneral form of all instruction lines is as follows:

[label:] mnemonic[Expr.][,Expr.][,Expr.] [; comment] <eol>:

example:

start: MOV DPP2,#PAG D_GROUP ; initialize DPP0 MOV DPP3,#3 ; load System Page MOV R0,R15

The use of a label is optional. Labels basically serve two purposes:

� the 166/167 instruction at the label can be jumped to by using the symboliclabel name for the destination address. The same also applies for subroutinecalls.

� labels are also available for symbolic debugging. This simplifies the testing ofsoftware since physical addresses can be specified using the symbolic name.

The number and required type of operands expected depend entirely on theassembler mnemonic. Some instructions require no operands, some require one,two or three operands to form a valid instruction. Operands can be classified asfollows:

� Special assembler symbols like register names.

� Program symbols like labels, section names, group names, and externalnames.

� Direct and indirect addresses.

� Constants.

Comments can be inserted into the source program. A comment is introduced witha leading semicolon (;). The rest of the line following the semicolon is ignored.

START: CALLS SEG (FARPROC), FARPROC ; comment after instruction; a pure comment line.

Comments may be used liberally for documenting programs. They do not affectthe object code.

12 Chapter 2. Operands and Expressions

2

Instruction OperandsAn operand is part of the instruction that follows the instruction opcode. Theinstructions for the 166/167 require zero to three operands. Depending on theinstruction, the type of operands differs:

Rn,Rm direct access to the General Purpose Registers (GPR’s)within the current registerbank. Each registerbank normallycontains the registers R0 to R15. Since the GPR’s are locatedin on-chip RAM of the CPU, the registerbank acts like aregister window, which can be switched to another bank bymeans of changing the context pointer (CP).

REG direct access to any GPR or special function register (SFR).REG forms an 8-bit number to designate the required locationin internal memory.

BITWORD access to some word in the bit-addressable memory space.

BITADDR access to some single bit in the bit-addressable memoryspace.

MEM access to any memory location.

[Rn],[Rm] indirect access to the entire memory space by the content of aGPR.

#DATAn an immediate constant value where n = 3, 4, 8, 16.

CADDR 16-bit code address within the current 64K segment for use inbranch instructions.

REL relative offset for use in a branch instruction. The coveredrange is +127 / -128 words relative to the current offset.

SEG code segment number. The 166/167 addresses up to 256K ofmemory, therefore the segment numbers 0, 1, 2 and 3 exist.

#TRAP a 7-bit constant used as interrupt vector numbers.

CC_cond condition code; CC_UC for unconditionally, CC_ULE forunsigned lower or equal condition and so on.


2

ExpressionsInstruction operands are primarily expressions. Expressions consist of numbers,symbols and operators. If all components of an expression are known at assemblytime, (no external at relocatable components), then the expression is considered tobe an absolute expression, otherwise it is a relocatable expression where the finalvalue will be computed by the linker/locator L166.

The following chapters describe the basic components of an expression and theoperators.

NumbersNumbers can be specified in hexadecimal (base 16), decimal (base 10), octal (base8) and binary (base 2). A number without an explicit base is interpreted asdecimal, this being the default representation. The first character of a number mustalways be a digit between 0 and 9. Hexadecimal numbers which do not have adigit as the first character must have a 0 placed in front of them.

Base Suffix Valid Characters Examples

Hexadecimal H,h 0-9, A-F, a-f 1234H 99H 123H 0A0F0H 0FFH

Decimal D,d 0-9 1234 65590D 20d 123

Octal O,o,Q,q 0-7 177O 7777o 25O 123o 177777O

Binary B,b 0-1 1111B 10011111B 101010101B

Hexadecimal numbers must be preceded with a 0, if the first digit is in range A to F.

Dollar ($) signs can be placed within numbers to make them more readable.However a $ sign is not allowed to be the first or last character of a number andwill not be interpreted.

1111$0000$1010$0011B - is equivalent to - 1111000010100011B1$2$3$4 - is equivalent to - 1234

Character StringsThe A166 assembler allows the use of ASCII character strings in expressions. Anexpression is permitted to have a maximum of two ASCII characters enclosed insingle quote characters (’).


2

Character strings can also be used outside of expressions (example: the DBdirective). The limit of two characters does not apply in this case.

NOTECharacter strings are not permitted to have a null length!

A null character string consists of two single quotes that enclose no othercharacters (‘’).

‘A’ evaluates to 0041H

‘AB’ evaluates to 4142H

‘a’ evaluates to 0061H

‘ab’ evaluates to 6162H

‘’ the null string is not valid!

‘abc’ ERROR due to more than two characters

TEST: MOV RL0, # ‘A’SUB RL0, # ‘0’

TABLE: DB ‘ENTER ANY KEY TO CONTINUE’ , 0

SymbolsThe A166 assembler allows the use of symbols. Symbols may represent numericvalues or addresses and make a program easier to read and understand. Symbolshave the following attributes:

TYPE: each symbol has a type, for example: bit, byte, word, ordata3. The type is used by the assembler to determine theaccess type and generate the appropriate instruction, exampleMOVB vs. MOVW. Another purpose is type checking so thatfor example a call to a data label instead of a code addresswill be caught by the assembler.


2

SECTION: most user defined symbols belong to some section. A sectionis a segment in memory containing executable code ,constants or variables.

SCOPE: is the visibility: local to module, global, public or externalconstants and relocatable symbols.

VALUE: This is the numeric value or offset the symbol represents.

CHANGEABLE: Symbols that have been defined using the SET directive canbe changed using the SET directive. Symbols which have notbeen defined using the SET directive may not be redefined.

Once a symbol has been defined it can be used as a numeric operand inexpressions similar to the way a numerical constant is used.

Symbol names must adhere to the following conventions:

� maximum of 31 characters in length

� first character must be one of ‘A’-‘Z’, ‘a’-‘z’, ‘_’, or ‘?’

� subsequent characters must be one of ‘A’-‘Z’, ‘a’-‘z’, ‘_’, ‘?’, or ‘0’-‘9’

The assembler contains predefined symbols for mnemonics, operands and 166/167specific data and bit addresses. These names are described as reserved words andare not allowed to be used by the programmer to define symbols or labels.

Labels

A label is a symbol, and the rules for symbols also apply to labels. A label is thefirst field in a line, but may be preceded by tabs or spaces. A colon (:) must beplaced after a label to identify it as a label. Only one label is permitted per line.

When a label is defined, it receives the current numerical value of the addresscounter of the currently active section. A label may not be defined more than onceand is not allowed to have the name of a reserved word.

The following are examples of the use of labels:LABEL2: ; a comment line with a labelCOPY: MOVB [R1],RL4


2

Special Assembly Symbols

Some symbols are predefined and are to be treated as reserved words. Theyusually refer to names of the processor registers:

R0 - R15: general purpose registers (GPR)

The dollar sign ($) represents the current offset in the active section. There is aseparate address counter for each section. The address counter is increased aftereach instruction by length. The ORG directive can be used to change the value ofthe address counter. The address counter automatically changes to the newsegment if the current section is changed.

Note that $ is incremented with every instruction. But this only occurs when theinstruction has been completely translated. On DB (define byte) and DW (defineword) statements, the address counter is advanced on each element of the list.

The following examples show the use of the $ address counter:MSG: DB LEN, 'THIS IS A MESSAGE',0LEN EQU $ - MSG - 1

HALT: JMP $: ; jump to 'HALT'TABLE: DW $, $, $, $ ;

Expressions, which contain variables or labels defined in relocatable sectionscannot be evaluated at assembly time, since the final address of these symbols isnot known. The address evaluation is performed by the linker/locator L166.

Relocatable symbols are:

� Section namesThe name of a section specifies the address of the section (base-relocatable).

� Group namesA group name specifies the address of the group of sections (base-relocatable).

� Variables and labelsThe offset of variables and labels, which are defined inside of relocatablesections, are relocatable (offset relocatable).

� External constantsExternally defined constants are relocatable values. Relocatable in this contextmeans that L166 will ‘fill in’ the constant value which must be defined insome other source module.


2

The following examples show how the above mentioned relocatable symbols aregenerated. The details on the used keywords can be found in the appropriatechapters.

Example 1, external constants:EXTRN XVAL : DATA4: ; an external 4-bit constantEXTRN YVAL : DATA8: ; an external 8-bit constant

Example 2, group name using sections from example 3:DGR DGROUP D100, D200 ; group consists of section D100 and D200

Example 3, section names:D100 SECTION DATA ; relocatable data section V1 DSW 1 ; reserve one word V2 DSB 1 ; reserve one byteD100 ENDS ; end of data section

D200 SECTION DATA SBASE DW D100 ; init word with base of sect. D100 GBASE DW DGR ; init word with base of group 'DGR'D200 ENDS

MOV R5,#DGR ; DGR is relocatableMOV R4,#V2-V1 ; V2-V2 is absolute (2)MOV R1,#XVAL ; use external constant (data4 short form)MOV R3,#4 * 8 ; absolute expression

OperatorsOperators fall into two classes: unary operators and binary operators. Unaryoperators require one operand whereas binary operands require two operands. Ifthe grouping of the is not specified with parentheses, the operator priority is usedto determine evaluation order. The operators and default priority levels are listedin the following table in decreasing priority.

Priority Operator Example Meaning

0 ( ) (2+8)*12 Change Order Of Evaluation

1 . SYSCON.3 Bit Position Separator

2 BIT PTR BIT PTR xbit Type Override

2 BYTE PTR BYTE PTR wvar Type Override

2 WORD PTR WORD PTR bvar Type Override

2 NEAR PTR NEAR PTR flab Type Override (Near/Far)

2 FAR PTR FAR PTR nlab Type Override (Near/Far)

2 DATA3 DATA3 2 Use 3-Bit Constant (0-7)



2

Priority Operator Example Meaning



2 DPP0-DPP3 DPP2:var Data Page Pointer Override

2 SEG SEG var Get Segment Number (64K Segments)

2 PAG PAG var Get Page Number (16K Pages)

2 SOF SOF var Get Segment Offset Of ‘Var’

2 POF POF var Get Page Offset Of ‘Var’

2 BOF BOF xbit Get Bitpos Of ‘Xbit’ Within Bitword Base

3 HIGH HIGH 1234H Get High Value From Expression (12H)

3 LOW LOW 1234H Get Low Value From Expression (34H)

3 NOT NOT 0 Bit Complement Operator

3 +, - -2 Unary Plus, Minus

4 *, /, MOD 100 MOD 7 Multiply, Division, Remainder

5 +, - 4 + 100 Addition, Subtraction

6 SHL, << 1 SHL 3 Shift Left

6 SHR, >> 100 >> 7 Shift Right

7 AND, & 1234 & 7 Bit And

7 OR, | 1234 | 1 Bit Or

7 XOR, ^ 1234 XOR 5 Bit Xor

8 LT, < 5 < 2 Lower Than

8 LE, <= 5 <= 2 Lower Than Or Equal

8 GT, > 5 > 2 Greater Than

8 GE, >= 5 >= 2 Greater Than Or Equal

8 ULT 5 ULT 3 Unsigned Lower Than

8 ULE 5 ULE 3 Unsigned Lower Than Or Equal

8 UGT 5 UGT 3 Unsigned Greater Than

8 UGE 5 UGE 3 Unsigned Greater Than Or Equal

9 SHORT SHORT lab Short Jump-Range Operator

Addition and Subtraction

Addition and subtraction may be used on absolute and relocatable operands.Together with the operators HIGH and LOW and the relational operators, this arethe only operators which can be used to operate on absolute and relocatableoperands, all other operators require absolute operands. The table below showsvalid operand combinations (ABS=absolute, REL=relocatable).

Syntax: operand + operandoperand - operand:


2

Operand ± Operand Result

ABS + ABS ABS

ABS - ABS ABS

ABS + REL REL

ABS - REL *** ERROR ***

REL + ABS REL

REL - ABS REL

REL + REL *** ERROR ***

REL - REL ABS

The operation ‘REL-REL’ is allowed for relocatable operands only when bothoperands are defined in the same parent-section, external operands are notallowed. In this case the result is absolute, because the address difference is knownat assembly time and can never change.

As a general rule, relocatable expressions must evaluate to a relocatable symbolplus or minus an optional constant value (displacement).

Multiplication, Division, Modulo

These operators perform the usual well known operations and require absoluteoperands.

Syntax: operand * operand ; multiplicationoperand / operand ; divisionoperand MOD operand ; discard quotient, result = remainder

Sign Operators

The unary plus operator does not modify its operand. The unary minus makes itsoperand negative by evaluating ‘0 - operand’.

Syntax: + operandoperand


2

Shift Operators

These operators shift their left operand either left (SHL, <<) or right (SHR, >>)by the number of bits specified in the operand right to the operator. Both operandsrequired to be absolute.

Syntax: operand SHR operand -oroperand >> operandoperand SHL operand -oroperand << operand

Relational Operators

The relational operators compare their operands. The result is either 0 (‘false’) or1 (‘true’). The operands can be either absolute or offset-relocatable.

Syntax: operand EQ operand ; equaloperand == operand ; same as EQoperand NE operand ; not equaloperand != operand ; same as NEoperand LT operand ; lower thanoperand < operand ; same as LToperand LE operand ; lower than or equaloperand <= operand ; same as LEoperand GT operand ; greater thanoperand >= operand ; same as GToperand ULT operand ; unsigned lower thanoperand ULE operand ; unsigned lower than or equaloperand UGT operand ; unsigned greater thanoperand UGE operand ; unsigned greater than or equal

Logical Operators

The logical operators operate on absolute operands only and evaluate to anabsolute result. The NOT operator performs a bitwise complementation on itsoperand.

Syntax: NOT operand ; bitwise notoperand AND operand ; bitwise andoperand & operand ; same as ANDoperand OR operand ; bitwise ORoperand | operand ; same as OR


2

operand XOR operand ; bitwise XORoperand ^ operand ; same as XOR

HIGH and LOW

HIGH returns the high byte of its operand, LOW returns the low byte of itsoperand (a 16-bit operand is assumed). The operand must be either absolute or aconstant defined as ‘ extern <e_con>:DATAn’. Relocatable operands of othertypes are not allowed.

Syntax: HIGH operand ; HIGH 1234H --> 12HLOW operand ; LOW 1234H --> 34H

DOT Operator

Syntax: bitword.bitpos

The dot (.) operator serves the purpose to designate a bit to the right of theoperator from the bitword-base to the left of the dot operator. The ‘bitpos’operand must be an absolute operand evaluating to a number in range 0 to 15. Thebitword base identifies a bit-addressable word in internal RAM or SFR area:

00000H to 0007FH: 8-bit word number in RAM00080H to 000EFH: 8-bit word number in SFR area0FD00H to 0FDFEH: bitword in internal RAM0FF00H to 0FFDEH: SFR area

Another possibility for the bitword base is an even aligned word in a bit-addressable data section:

BD10 SECTION DATA BITADDRESSABLE BW0 DSW1BD10 ENDSEXTRN BW1 : BITWORD ; external bitword

BCLR BW0.3 ; valid bitaddressBCLR BW1.15 ; external bitword in bitaddressBCLR 0FD00H.15 ;


2

Page Override Operator

Syntax: DPPn:operand ; DPP0,DPP1,DPP2,DPP3

Each variable is physically located somewhere in memory. The 16K page, whichcontains a variable, is the parent page. Access to the content of the variablerequires a data page pointer (one of DPP0 to DPP3) to hold the page number ofthe target page. In practice, A166 keeps track of what DPP will keep the sectionor group base address by means of the ASSUME directive.

The page override undergoes the ASSUME mechanism by using the DPP from theprefix for addressing. It is the users responsibility to make sure, that the givenDPP is loaded with the correct base to get a valid runtime address.

Example:ASSUME DPP2:D100

D100 SECTION DATA V1 DSW 1 V2 DSW 1D100 ENDS

C100 SECTION CODE MOV DPP2,#D100 ; establish data page addressability NOP ; pipeline delay MOV R10,V1 ; DPP2:V1 used per ASSUME

MOV DPP1,#D100 ; set up DPP1 for later override NOP MOV R13,DPP1:V2 ; addressing per DPP1; undergoing ASSUMEC100 ENDS

PTR Operator

Syntax: type PTR : operand

The PTR operator is used to give a memory reference a specified type and maytherefore override the real type of the operand. The keyword ‘PTR’ is optional, theoperand can be any address expression which represents a data variable or a codelabel.

‘type’ can be one the following types:

� BIT

� BYTE


2

� WORD

� BITWORD

� NEAR

� FAR

The PTR operator cannot be used on section and group names and externalconstants (extern DATAn:name). The type ‘BIT PTR’ can only by applied on bits,it is not possible to change the access type from some other type to type bit.

Examples:D100 SECTION DATA V1 DSW 1 V2 DSW 1

B1 DSB 1 B2 DSB 1D100 ENDS

EXTRN XPROC:NEAR

C100 SECTION CODE CALL FAR PTR XPROC ; override type near by far MOV RL0,BYTE PTR V2 MOV R15,WORD B1 MOV [R1],200 ; type of move unsure MOV [R1],BYTE 200 ; byte move MOV [R1],WORD 200 ; word moveC100 ENDS

DATA Operator

Syntax: DATAn operand

The DATAn operator is used to specify the type of constants in both instructionsand externally defined constants. There are four different DATAn operators, eachdefines a specific value range. ‘n’ specifies the number of bits:

DATA3 3-bit: values in range 0 to 7DATA4 4-bit: values in range 0 to 15DATA8 8-bit: values in range 0 to 255DATA16 16-bit: values in range 0 to 65535

When A166 encounters an immediate expression using just a constant, it mustmake an assumption about the type based on the value of the constant. Assemblersfrom other vendors use the DATAn operator to resolve the type in case of forward


2

references. Due to the three pass nature of A166, it is not necessary to use theDATAn operator in instructions and still get the shortest possible instructionopcodes.

Examples: 1 C100 SECTION CODE 2 P100 PROC NEAR0000 E070 3 MOV R0,#CONS0002 E6F10700 4 MOV R1,#DATA16 CONS0006 E002 E 5 MOV R2,#CON3 6 P100 ENDP 7 C100 ENDS 8 9 EXTRN CON3 : DATA3 10 CONS EQU 7 ; DATA3 type derived 11 ; from value 7 12 END

The example shows the use of the DATAn operator. Although forward referencesare contained (CON3 and CONS), the assembler still generates the short form ofthe MOV instruction. The DATAn operator can be used to ‘enlarge’ the type, it isnot possible to ‘shrink’ the type of a constant, for example ‘DATA3 12’. In thiscase the assembler will truncate the value and give a warning.

SHORT Operator

Syntax: SHORT label

The SHORT operator is used to generate a short distance branch (call or jumprelative to within -128 to +127 words to the current instruction) to a forwardreferenced label. The branch target will be checked in pass2 against violence of themaximum relative distance.

Due to the three pass nature of A166, it is not necessary to use the SHORToperator in forward references. Pass 2 of the A166 automatically determinesdistances and will use the shortest form of the branch instructions (JMPR,CALLR).

Example:C100 SECTION CODEP100 PROC NEAR JMP LAB JMP SHORT LABLAB: MOV R15,R3P100 ENDPC100 ENDS


2

SEG Operator

Syntax: SEG operand

The SEG operator returns a relocatable 2-bit (8-bit for 167) segment number ofthe named operand. The segment number is the number of the 64K segment wherethe operand is located in.

The operand normally should be the name of a variable, section, group or a specialfunction register (SFR) or registerbank. If SEG is used on system names (SFR’s)the result is absolute and has value 0.

Examples:

1 C100 SECTION CODE 2 P100 PROC NEAR0000 E000 3 MOV R0,#SEG SYSCON ; result:00002 E001 R 4 MOV R1,#SEG P100 ; relocatable0004 E022 5 MOV R2,#SEG 22000H ; result:2 6 P100 ENDP 7 C100 ENDS

PAG Operator

Syntax: PAG operand

The PAG operator returns a relocatable 4-bit (10-bit for 80C167) page number ofthe named operand. The page number is the number of 16K page which theoperand is located in.

The operand normally should be the name of a variable, section, group, specialfunction register (SFR) or registerbank. If PAG is used on system names (SFR’s)the result is the absolute page number 3.]

Examples: 1 D100 SECTION DATA ; relocatable datasection0000 2 V1 DSW 1 3 D100 ENDS ; end of section 4 5 C100 SECTION CODE 6 P100 PROC NEAR0000 E6020000 R 7 MOV DPP2,#PAG D100 ; base page of sectionD1000004 E6030300 8 MOV DPP3,#PAG SYSCON; page nr. of internalRAM0008 E6F00300 9 MOV R0,#PAG SYSCON ; result: 3000C E6F10000 R 10 MOV R1,#PAG P100 ; relocatable


2

0010 E6F20800 11 MOV R2,#PAG 22000H ; result: 80014 E082 12 MOV R2,#DATA4 (PAG 22000H) ; result: 8 13 P100 ENDP 14 C100 ENDS 15 END

SOF Operator

Syntax: SOF operand

The SOF operator returns the 16-bit offset of its operand from the base of the 64Ksegment in which it is defined. SOF cannot be applied to group names.

The primary use of the SOF operator is for loading the peripheral event controllerwith source and destination addresses. Since the PEC unit works with linearaddresses not using the DPPn mechanism, the user must use the SOF operator toobtain linear addresses.

The operand normally should be the name of a variable, section, special functionregister (SFR) or registerbank. If SOF is used on system names (SFR’s) the resultis the absolute offset relative to segment 0.

Examples: 1 D100 SECTION DATA0000 2 V1 DSW 200028 0000 R 3 V2 DW SOF V1 ; segment offset of V1002A 0000 R 4 V3 DW PAG V1 ; page offset of V1 5 D100 ENDS 6 7 DSTP7 EQU 0FDFEH 8 9 C100 SECTION CODE 10 P100 PROC NEAR0000 E6F80000 R 11 MOV R8,#SOF V1 ; segment offset0004 F6F8FEFD 12 MOV DSTP7,R8 ; destination for PECC70008 E6F50000 R 13 MOV R5,#SOF P100 ; SOF of parentprocedure 14 P100 ENDP 15 C100 ENDS 16 END

POF Operator

Syntax: POF operand

The POF operator returns the 14-bit page offset of its operand from the base ofthe 16K page in which it is defined. POF cannot be applied to group names.


2

The operand normally should be the name of a variable, section, special functionregister (SFR) or registerbank. If POF is used on system names (SFR’s) the resultis the absolute page offset relative to page 3.

Examples: 1 D100 SECTION DATA0000 2 V1 DSW 200028 0000 R 3 V2 DW POF V1 ; page offset of V1002A 0000 R 4 V3 DW PAG V1 ; page number of V1 5 D100 ENDS 6 7 DSTP7 EQU 0FDFEH 8 9 C100 SECTION CODE 10 P100 PROC NEAR0000 E6F80000 R 11 MOV R8,#POF V10004 E6F92800 R 12 MOV R9,#POF V20008 E6F70C3F 13 MOV R7,#POF SYSCON ; system name000C E6F60000 R 14 MOV R6,#POF C100 ; segment to page conv0010 E6F5FE3D 15 MOV R5,#POF DSTP7 ; result is 3DFEH 16 P100 ENDP 17 C100 ENDS 18 END

The POF operator is implied when memory accesses to data variables are codedsince data is always located in 16K pages (MOV R8,V2).

BOF Operator

Syntax: BOF bit-operand

The BOF operator returns the bit position of a bit variable from the bit-addressable word, in which it is defined. The result is always an absolute number(exception: BOF applied to an externally defined bit variable). The operand toBOF must be of type bit, otherwise an error occurs.

Examples:1 D100 SECTION DATA BITADDRESSABLE0000 2 V1 DSW 1 3 D100 ENDS 4 5 BIT1 BIT V1.15 6 BIT2 BIT V1.1 7 BIT3 BIT 0FD10H.8 8 EXTRN EBIT : BIT 9 10 C100 SECTION CODE 11 P100 PROC NEAR0000 E084 12 MOV R4,#BOF BIT3 ; result is 80002 E0F5 13 MOV R5,#BOF BIT1 ; result is 150004 E015 14 MOV R5,#BOF BIT2 ; result is 10006 E005 E 15 MOV R5,#BOF EBIT ; result determined byL166 16 P100 ENDP


2

17 C100 ENDS 18 END


2


3

Chapter 3. Assembler DirectivesAssembler directives are used to control the assembly process rather than beingtranslated into 166/167 machine code. The A166 assembler offers variousdirectives, which serve the following purposes:

� definition of SECTIONS (SECTION)

� definition of GROUPS (GROUP)

� DPPn-tracking (ASSUME)

� internal resource reservation (REGDEF, SSKDEF, PECDEF)

� definition of symbols (BIT, EQU, SET, LIT)

� memory space reservation (DS, DSW, DSB, DBIT)

� memory space initialization (DB, DW, DBPTR, DSPTR, DPPTR)

� program linkage (EXTERN, PUBLIC, GLOBAL, NAME)

� assembler state control (ORG, END)

SECTIONSA Section is a portion of memory which may be addressed by a section base andan offset. Sections of different modules may be combined to a larger section or agroup at link time and may have a class name to allow different sections to beplaced near each other in memory. Due to the difference in addressing code anddata, different types of sections and groups are provided.

The 166/167 CPU addresses up to 16MB of memory. The memory map isdivided into segments of 64KB each. Accessing memory locations requires an 18-bit physical address which is composed of the following:

CODE Address: Segment number for 166/167 (8 bits, 0 to 256),offset (16 bits, 0 to 65535)

DATA Address: Page number supplied via data page pointer for 166/167 (10bits, 0 to 1023), offset (14 bits, 0 to 16383)

32 Chapter 3. Assembler Directives

3

SECTION / ENDS

The SECTION / ENDS directive is used to define logical memory sections whichmay be combined with sections of equal names. Sections are placed withinphysical segments in case of code sections or physical pages in case of datasections. Within one source module, each occurrence of an equivalent section(having the same name) is viewed as one section consisting of two or more partialsections. The 166/167 knows two fundamental operating modes: the segmentedmode and the non-segmented mode. In segmented mode, the CPU can address upto 16MB of memory. In non-segmented mode, the CPU can address up to 64K ofmemory, the total space required for code and data must not exceed 64K. Allreferences are of type near since the data page pointers are loaded once on startupand no segmented calls (CALLS) are necessary.

Syntax: name SECTION sectype [align-type] [combine-type] [‘ class-name’] data definitions or codename ENDS

Description of fields:

name is the name of the section. The name must be an uniqueidentifier.

sectype is CODE, DATA or BIT.

CODE sections will be mapped to physical segments. If theCPU operates in non-segmented mode, a total of 64KB (0 to0FFFFH) can be addressed. In segmented mode, sections oftype CODE can be located anywhere in the 166/167 addressspace.

DATA sections are mapped to physical 16KB pages. In non-segmented mode this page will be within the first 64Kbytesegment, otherwise a page may be located anywhere withinthe 166/167 address space.

BIT sections will be mapped into the bit-addressable spacelocated in on-chip RAM at addresses 0FD00H to 0FDFFH.The location counter is advanced in units of bits.


3

align-type The alignment type field specifies the boundaries of sectionswhich must be observed and handled by the linker whencombining or locating sections. The align-type must be oneof the following:

no alignment type given; the default alignment derived fromsection type is used (BIT for bit-sections, WORD for code,data and bit-addressable data sections.

BIT the section will be combined or located at a bitboundary. This allows combination of bit sections with nointervening gaps.

BYTE the section will be combined or located at a byteboundary. Sections which contain word variables or codemay not receive byte alignment, since word accesses must beat even addresses, otherwise an execution trap will occursince byte alignment may lead to accesses from odd wordaddresses.

WORD the section will be forced to an even address.

DWORD the section will start at an address divisible by 4without remainder.

PAGE the section will start at a 16K page boundary.

SEGMENT the section will start at a 64K segmentboundary.

BITADDRESSABLE implies WORD alignment, sectionsstart on an even word address in bit-addressable RAMcontained in the CPU at address 0FD00H to 0FDFEH.

PECADDRESSABLE implies WORD alignment, sectionsstart at an even address in internal RAM at address 0FDE0Hto 0FDFEH.


3

combine-type This field specifies how sections are combined with sectionsfrom other modules to form a page or segment in memory.The actual combination of sections is processed by thelinker/locator L166. The following combine-type specifiersare possible:

PRIVATE or combine type omitted; the section receivesthe attribute non-combinable. This is true only for sectionscontained in different modules. Sections within one moduleare still combined to one section.

PUBLIC all sections having the same name will becombined to one section. The length of the combined sectionwill be the sum of the lengths of the sections being combined.

GLOBAL has the same semantic as PUBLIC, but by-passesthe TRGOUP level. TGROUPS are individual program units.Public makes sections or symbols visible one TGROUP unit.Global makes sections or symbols visible for the wholeapplication (beyond TGROUP units).

COMMON all sections having the same name with theattribute COMMON are overlapped in memory to form onesection. All combined sections start at the same memoryaddress. The length of the combined section is equal to thelength of the largest section combined.

SYSSTACK all sections of the same name are combined toone section by adding the sections. The final section will beplaced in on-chip RAM by L166 and is used for the systemstack. The system stack is accessed via the stack pointer SPwith the instructions CALL, PUSH, POP and SCXT. Due tothe limited size of the system stack, automatic variables fromC are placed on the user stack.

USRSTACK the same combination semantics are used aswith SYSSTACK. The difference is that the final section isplaced somewhere in memory and is addressed using theDPPn:offset method. This kind of stack is normally used forlocal (stack based) variables in high level languages. Theuser stack can have a total length of 16K.


3

GLBUSRSTACK the same semantics as with USRSTACKare used. The difference to USRSTACK is that sections arecombined on a system wide base which is beyond TGROUPSunits.

AT expression the section is placed at an absolute addressspecified by expression in memory. The expression mustevaluate to a constant value with no forward references. Thedetails on the absolute address depend on the section-type andalign-type. A bit-addressable data section, for example, mustbe placed at appropriate addresses in internal RAM. The ATattribute implies a non-combinable section. The assemblerchecks the expression for consistence with the sectype andalign-type and the CPU mode segmented or non-segmented.

class-name is used to specify all sections with the same class name atlink/locate level. The idea is to place this sections in generalmemory areas, for example to place sections containingconstants and others containing code into PROM area. Theclass name must be an unique identifier.

Example:C100 SECTION CODE ‘INITROM’C100 ENDS

Multiple Section Definition

A Section may be opened and closed many times. All parts of the section arecombined to one section. When a section is reopened, the attributes (with theexception of section-type) need not be specified. If the attributes are specified,they cannot re-specify previous attributes.

The following example shows multiple sections using the same name, onegenerating an error because of section attribute redefinition:

1 D100 SECTION DATA BITADDRESSABLE0000 2 V1 DSW 1 ; reserve one word of storage 3 D100 ENDS 4 5 D100 SECTION DATA0002 6 V2 DSW 1 ; reserve one word of storage 7 D100 ENDS 8 9 ; the above sections are equal to: 10 11 ;D100 SECTION DATA BITADDRESSABLE


3

12 ; V1 DSW 1 ; reserve one word of storage 13 ; V2 DSW 1 ; reserve one word of storage 14 ;D100 ENDS 15 16 ; the following is an error because of align-typeredefinition: 17 18 D100 SECTION DATA WORD*** _________________________________^*** ERROR #31, LINE #18, REDEFINITION: 'ALIGN TYPE'0008 19 V3 DSW 1 ; reserve one word of storage 20 D100 ENDS 21 22 END

Nested Sections

The definition of sections can be nested, although sections are never nestedphysically in memory. Nesting of code sections is not allowed. Data sections maybe defined within code sections. Up to ten nested sections are allowed. Nestedsections must be closed inside out, that is, the innermost section must be closedfirst and so on. The following examples shows a nested section definition, wherean absolute data section is nested within a relocatable data section:

1 D100 SECTION DATA BITADDRESSABLE0000 2 V1 DSW 1 ; relocatable word 3 D200 SECTION DATA AT 4000H0000 4 A1 DSW 1 ; absolute word at 4000H0002 5 A2 DSW 1 ; absolute word at 4002H 6 D200 ENDS ; D200 gets closed0002 7 V2 DSW 1 ; section D100 is resumed 8 D100 ENDS


3

GROUPThe GROUP directive is used to define groups of sections. A group is a collectionof one or more sections, all contained within one data page in case of a data groupor within one segment in case of a code group. The reason for having two types ofgroups (code groups and data groups) is the difference of the 166/167 CPU inaddressing code and data. A GROUP serves as shorthand to refer to a collectionof sections.

Syntax: group-name CGROUP section-name [, section-name [, …]]group-name DGROUP section-name [, section-name [, …]]


group-name is the name of the group. The name must be an uniqueidentifier.

CGROUP / DGROUP specifies whether a code or datagroup is to be defined. In case of code groups, only codesections can be member of. The total size of a code groupmay not exceed 64KB. A data group can have only datasections as associated members. The total size of a datagroup may exceed 16KB. The order of sections in a groupderived from the section name list is not necessarily the sameafter linking and locating since the order may be changed atlink time. A group is located as one logical unit to onephysical segment or page.

section-name one or more section names, separated by comma. If onemember of a group is an absolute section, then the groupbecomes absolute as well. In this case the order of thesections highly depends on the absolute section. A data groupmay contain the dummy section ‘SYSTEM’. SYSTEMcovers the internal special function register area. SinceSFR’s are not defined using ordinary section directives, theSYSTEM section serves as a placeholder for the SFR area.SYSTEM specifies an absolute section within page 3.


3

Example of group definitions: 1 $SEGMENTED 2 3 GDATA DGROUP D100, D200 4 GCODE CGROUP C100 5 ASSUME DPP2 : GDATA 6 7 D100 SECTION DATA0000 8 V1 DSW 1 9 D100 ENDS 10 11 D200 SECTION DATA0000 12 V2 DSW 1 13 D200 ENDS 14 15 C100 SECTION CODE PUBLIC 'ROM1' 16 P100 PROC NEAR0000 E6020000 R 17 MOV DPP2,#GDATA ; load group base page0004 CC00 18 NOP ; pipeline delay0006 F2F10000 R 19 MOV R1,V2 ; load content of 'V1'000A E6F50000 R 20 MOV R5,#POF V1 ; derive page offset of 'V1'000E E6F60000 R 21 MOV R6,#POF V2 ; derive page offset of 'V2' 22 P100 ENDP 23 C100 ENDS 24 25 END

ASSUMEAt runtime, every data memory reference requires two parts of information inorder to form a valid data address:

� a page number of a 16KB page which is referred.

� an 14 bit offset into the target page.

The page number is contained in one of the data page pointers. The information,which data page pointer is to be used is contained in the instruction opcode. It ispossible to use any of the four data page pointers.

The assembler receives the information about runtime contents of the data pagepointers per ASSUME. Going this way, the assembler makes sure that a variablewill be correctly addressed at runtime. The ASSUME directive does not initializedata page pointers in any sense, it is used by the assembler to help you be aware ofthe consistent addressing of your data. If the assembler finds an instructionoperand not having an associated DPP or an explicit page override operator, itreports an error. The ASSUME directive gives the assembler the requiredinformation for automatic generation of the page override instruction prefix.


3

Syntax: ASSUME DPPn: section nameASSUME DPPn: SYSTEMASSUME DPPn: group nameASSUME DPPn: variable or label nameASSUME DPPn: NOTHING


DPPn: is one of DPP0, DPP1, DPP2 or DPP3

section-name all references to variables of the given section will use thegiven data page pointer.

SYSTEM is a dummy section which encloses the special functionregister (SFR) area within the internal RAM of the CPU.SFR’s are normally predefined within the assembler and arenever defined using ‘normal’ sections. Since the accesses toSFR’s also use the data page mechanism, they also require anassociated DPP for correct accesses.

Without having the SYSTEM dummy section, it would notbe possible to have one DPP representing the base of somedata section contained in internal RAM and the SFR area(both physically located in the same page-3), since one DPPcan hold only one base at a time.

group name all references to variables of sections which are members ofthe named group will use the given data page pointer.

variable or label namethe parent section of the given variable or label is derived.

NOTHING resets the previous ASSUME for the given DPP. Theassembler is informed that the given DPP is no longer valid.To invalidate all DPP-assumes, the short form ASSUMENOTHING is provided.

The assume(s) are valid until another assume changes the runtime assumptions onthe given data page pointer.

Data page information can be also given by means of an explicit page override, forexample:


3

MOV R15,DPP1 : V1; use DPP1 to access variable 'V1'

As a general rule, explicit page overrides should be avoided since programs maybecome hard to maintain, if excessive used. In case of configuration changes onsections or groups, every DPP override has to be changed by hand which tends tobe erroneous. When using the ASSUME directive, only a few assumes along withsome MOV DPP instructions must be changed to get a new data pageconfiguration.

Examples: 1 $SEGMENTED 2 3 GDATA DGROUP D100, D200 4 GCODE CGROUP C100 5 6 D100 SECTION DATA0000 7 V1 DSW 1 8 D100 ENDS 9 10 D200 SECTION DATA0000 11 V2 DSW 1 12 D200 ENDS 13 14 C100 SECTION CODE PUBLIC 'ROM1' 15 P100 PROC NEAR 16 ASSUME DPP2 : D200 ;0000 E6020000 R 17 MOV DPP2,#PAG D200 ; page number of 'D200'0004 CC00 18 NOP ; pipeline delay0006 F2FF0000 R 19 MOV R15,V2 ; DPP2 is used for reference 20 21 MOV P1,P2 ; move Port-2 content toPort1*** ____________________________________^*** ERROR #77, LINE #21, MISSING 'DPP' INFORMATION 22 ; an error: no associatedDPP! 23 ASSUME DPP3 : SYSTEM ; est addressability ofSFR's000E E6030300 24 MOV DPP3,#PAG P1 ; Page-3 is the system page0012 CC00 25 NOP ; pipeline delay0014 F282C0FF 26 MOV P1,P2 ; now correct 27 28 ASSUME DPP2 : GDATA ; D100 and D200 use DPP2 now0018 E6020000 R 29 MOV DPP2,#PAG GDATA001C CC00 30 NOP001E F2F10000 R 31 MOV R1,V10022 02F10000 R 32 ADD R1,V20026 F6F10000 R 33 MOV V2,R1 34 P100 ENDP 35 C100 ENDS 36 37 END

The error in line 21 results from an access to SFR port-2 with no associated DPPfor the system area.


3

REGDEF / REGBANKAll 16 of the 166/167 general purpose registers (GPRs) are mapped to on-chipRAM. A context switch to a new register bank can be done very quickly using adifferent register bank by name. The base of the actual register bank is containedin the context pointer register, which is a special function register.

Syntax: regbankname REGBANK [register range][, …][regbankname] REGDEF register range [, …]

The REGBANK directive is used to create a new register bank. The register bankname can be assigned to a memory range located in internal RAM holding theGPR’s, specified by the register range. If the register range is missing, theassembler will automatically supply a mask of all register used in the sourcemodule.

The REGDEF directive is used to create a register bank having an optional name.The difference to REGBANK is that a register range is required. A warning isdisplayed if the actual register used in the source module are not a subset or equalto the registers given in register range.

Register banks are handled by the linker/locator like data sections with theexception that they are always located in internal RAM at addresses 0FA00H to0FDFFH.

The register range has the form ‘Rn [-Rm]’ (m,n: 0 to 15) or ‘Rn[,Rm[, …]]’.

Example:BANK1 REGBANK R0-R15 ; define a complete register bank

1 $SEGMENTED 2 3 BANK2 REGBANK R0-R15 4 5 C100 SECTION CODE PUBLIC 'ROM1' 6 INIT PROC FAR0000 E6030300 7 MOV DPP3,#PAG SYSCON0004 CC00 8 NOP0006 C6080000 R 9 SCXT CP,#BANK2 ; save & load contextpointer000A CC00 10 NOP ; pipeline delay000C E6FF3412 11 MOV R15,#1234H ; access to GPR's now valid0010 DB00 12 RET 13 INIT ENDP 14 C100 ENDS 15 16 END


3

Register banks are handled by the linker/locator like data sections with theexception that they are always located in internal RAM.

PECDEFThe 166/167 controller contains 8 Peripheral event controllers, referred to as PECchannels. Each channel has associated counter and control registers (implementedin the SFR area) and a source and destination pointer which specify the transferaddresses. The source and destination pointers are located in on-chip RAM ataddresses 0FDE0H to 0FDFFH. If the PEC channels are not used, this RAM canbe used as ordinary RAM, otherwise it must be reserved by means of thePECDEF directive which prevents the linker/locator from placing other sections inthis specific area. The PEC channels are referred to as PECC0, PECC1, …PECC7. One source module can contain only one PECDEF directive.

Syntax: PECDEF channel-range [,channel-range [, …]]

Example:PECDEF PECC0-PECC2, PECC6,PECC7PECDEF PECC0-PECC7

SSKDEFThe SSKDEF directive specifies the size of the system stack. One module maycontain only one SSKDEF directive.

Syntax: SSKDEF stack-size-number

The stack-size-number is a value in range 0 to 7. This number corresponds to thesystem stack size as follows:

NUMBER SIZE STACK ADDRESS 0 256 words 0FA00H to 0FBFFH 1 128 words 0FB00H to 0FBFFH 2 64 words 0FB80H to 0FBFFH 3 32 words 0FBC0H to 0FBFFH 4 512 words 0FBFEH to 0F800H 5 Reserved, do not use this value 6 Reserved, do not use this value 7 No limited, the whole on-chip RAM can be used as stack

Example:SSKDEF 1


3

PROC / ENDPThe PROC and ENDP directive pair is used to define a label for a sequence ofmachine instructions called a procedure. A procedure is called within the samephysical segment (near call) or from a different segment (far call). A proceduremay have either type near or type far. Unless procedures known from high levellanguages, the scope of identifiers is different in the assembly language so thatidentifiers must be unique because the visibility is module wide.

A procedure normally ends with a RET instruction. The software instruction RETwill be automatically converted to an appropriate machine return instruction, thatis,

RETS return from far procedure

RETI return from interrupt procedure

RET return from near procedure

The assembler does not check the flow of control to figure out whether a returninstruction is present or not, it is up to the user to have a return instruction coded.

Syntax: name PROC [type]name ENDP

name PROC TASK [taskname] [INTNO [ intname][= intno]]name ENDP

name PROC INTERRUPT intname = intno USING rbankname ENDP


name Is the name of the procedure.

type Specifies the type of the procedure, it may receive one of thefollowing values:

none specified: The type defaults to near regardless of theselected CPU mode segmented or non-segmented.


3

NEAR: Defines a type near procedure.FAR: Defines a type far procedure.

With this information, the assembler can automaticallygenerate the appropriate CALL and RET instructions. AnyRET instruction within PROC and ENDP will be convertedto the correct return instruction.

TASK Defines a TGROUP with name taskname if one follows.Otherwise an unnamed task is created. A task is a functionalunit consisting of one or more modules. The entry point tothe task unit is the task procedure, the exit point from the taskis a RETI instruction also contained in the task procedure. Atask can be viewed as a functional unit which is activated bya software or hardware trap which causes an interrupt andthen a branch to the task procedure using an entry in theinterrupt vector table.

taskname the TGROUP name; defines the name of theTGROUP represented by this interrupt procedure and mustbe a unique identifier. The taskname and if specified theintname and its value are GLOBAL symbols.

NOTEthe TASK is implemented for compatibility to the Siemenstool chain. TASK denotes a TGROUP and not a task of areal-time operating system. Instead of TASK use theINTERRUPT keyword.

INTNO The task procedure currently being defined can receive anabsolute or a symbolic interrupt number depending on whatfollows INTNO .

INTERRUPT Defines an interrupt procedure which can receive an absoluteor a symbolic interrupt number depending on what follows.

intname must be a unique identifier that defines a symbolicname for the interrupt of the task procedure currently beingdefined. If no assignment of a constant value follows, thenthe interrupt or vector number is relocatable and can besupplied at link/locate time. The symbolic trap numberserves the purpose to activate tasks by means of trap


3

instructions, which must have a trap number as its operand.The trap name is known automatically, system wide.

intno must be a numeric expression which evaluates to aconstant value in range 0 to 127. It represents the interruptnumber of the specified interrupt procedure. If intname isgiven, then intno is assigned to intname.

USING Defines the register bank used for the interrupt procedure.

rbank must be the name of a register bank which is definedpreviously with the REGBANK directive.

Example:LOC OBJ LINE SOURCE

1 $SEGMENTED 2 3 MyBank1 REGBANK 4 MyBank2 REGBANK 5 6 C100 SECTION CODE 7 8 int10 PROC INTERRUPT I10=10 USING MyBank2000000 F6F00000 R 9 MOV MyBank2,R0000004 C6080000 R 10 SCXT CP,#MyBank2000008 CC00 11 NOP 12 ; ...00000A FC08 13 POP CP00000C FB88 14 RET 15 int10 ENDP 16 17 proc1 PROC USING MyBank100000E F6F00000 R 18 MOV MyBank1,R0000012 C6080000 R 19 SCXT CP,#MyBank1000016 CC00 20 NOP 21 ; ...000018 FC08 22 POP CP00001A C600 23 RET 24 proc1 ENDP 25 26 C100 ENDS 27 28 C101 SECTION CODE 29 30 P101 PROC NEAR000000 DA000000 R 31 CALL P102 ; far call for P102000004 CB00 32 RET ; near return 33 P101 ENDP 34 35 P102 PROC FAR000006 BBFC 36 CALL P101 ; near call for P101000008 9B0A 37 TRAP #I10 ; call int1000000A DB00 38 RET ; far return 39 P102 ENDP


3

40 41 END

EQU

Syntax: name EQU expression

EQU creates a new symbol with the name and the value of the expression. Asymbol created by EQU cannot be redefined elsewhere. The expression can havethe following values:

� A register name like R10, RL2, or RH1.

� The name of a special function register.

� A constant value.

� An identifier.

� An expression having a prefix (PAG,POF,SEG,SOF).

The expression must not have forward references. All identifiers used in theexpression must have been previously defined.

If an EQU symbol is to be made PUBLIC or GLOBAL, the expression mustevaluate to a constant. The public and global directives are able to export a nameand a value. They are not able to export fix-up methods such as those generatedby PAG, SOF, or names of registers.

The following example shows the use of EQU and the resulting symbol listingcreated by the assembler. Note that symbols, which represent registers are notdisplayed by the assembler.

LOC OBJ LINE SOURCE

1 D100 SECTION DATA0000 2 V1 DSW 10002 3 V2 DSW 1 4 D100 ENDS 5 6 VAR1 EQU V1 7 X15 EQU R15 8 X3 EQU R3 9 X4 EQU SYSCON 10 XL3 EQU RL3 11 CON1 EQU 3 12 13 C100 SECTION CODE 14 P100 PROC NEAR0000 E136 15 MOV RL3,#CON1


3

0002 E136 16 MOV XL3,#CON1 ; same as instr. before0004 F6FF0000 R 17 MOV V1,R150008 F6FF0000 R 18 MOV VAR1,X15 ; same as instr. before000C F6F30CFF 19 MOV X4,X3 ; syscon,R30010 CB00 20 RET 21 P100 ENDP 22 C100 ENDS 23 END

SYMBOL TABLE LISTING------ ----- -------


C100 . . . . . . . ---- ---- SECTIONCON1 . . . . . . . DATA3 0003H AD100 . . . . . . . ---- ---- SECTIONP100 . . . . . . . NEAR 0000H R SEC=C100SYSCON . . . . . . WORD FF0CH A SFRV1 . . . . . . . . WORD 0000H R SEC=D100V2 . . . . . . . . WORD 0002H R SEC=D100VAR1 . . . . . . . WORD 0000H R SEC=D100X4 . . . . . . . . WORD FF0CH A SFR

SET

Syntax: name SET expression

SET creates a new symbol with name name and the value of the expression. Asymbol created by SET may be redefined. The expression can have the followingvalues:

� a constant value

� an identifier

� an expression having a prefix (PAG,POF,SEG,SOF)

The expression must not have forward references, that means all identifiers used inthe expression must have been previously defined. A SET symbol cannot be madePUBLIC or GLOBAL.


1 D100 SECTION DATA0000 2 V1 DSW 10002 3 V2 DSW 1 4 D100 ENDS 5 6 VAR1 SET V1 7 X4 SET SYSCON 8 CON1 SET 3 9 10 C100 SECTION CODE


3

11 P100 PROC NEAR0000 F2FF0000 R 12 MOV R15,V10004 F2FF0000 R 13 MOV R15,VAR1 ; same as instr. before0008 E136 14 MOV RL3,#CON1 ; CON1 = 3 15CON1 SET CON1 + 16 ; CON1 = 19000A E7F61300 16 MOV RL3,#CON1 ; gens long instr. form000E CB00 17 RET 18 P100 ENDP 19 C100 ENDS 20 END

BIT

Syntax: bit-name BIT expression

The BIT directive assigns the value of expression to the specified bit-name. Sucha bit-name cannot be redefined elsewhere in the source module. The expressionmay not contain forward references.

The BIT directive can be used to create a bit-name for an bit-addressable item

� absolute addresses in range 0FD20H-0FDFEH, example: 0FD10H.7

� system-bit, examples: DP3.13, P2.15, PSW.1. The result is an absolute bitsince SFR-names (system-names) are absolute. (The same function isperformed by the DEFB directive which is included for compatibility to other166/167 assemblers.)

� bits based on words contained in bit-addressable data sections. This results inrelocatable bits, if the bit-addressable data section is relocatable.


1 D100 SECTION DATA BITADDRESSABLE0000 2 V2 DSW 1 3 D100 ENDS 4 5 BIT1 BIT V2.7 ; relocatable word base 6 BIT2 BIT V2.14 ; relocatable word base 7 BIT3 BIT DP3.13 ; absolute system bit 8 BIT4 BIT PSW.1 ; Carry 9 BIT5 BIT 0FD10H.4 ; absolute bit 10 BIT6 BIT P3.13 ; ENABLE WR/ OUTPUT 11 12 C100 SECTION CODE 13 P100 PROC NEAR0000 7F00 R 14 BSET BIT10002 EF00 R 15 BSET BIT20004 DFE3 16 BSET BIT30006 1F88 17 BSET BIT40008 4F08 18 BSET BIT5


3

000A DFE2 19 BSET BIT6000C CB00 20 RET 21 P100 ENDP 22 C100 ENDS 23 END



BIT1 . . . . . . . BIT 00H.7 R SEC=D100 BASE=V2BIT2 . . . . . . . BIT 00H.14 R SEC=D100 BASE=V2BIT3 . . . . . . . BIT E3H.13 ABIT4 . . . . . . . BIT 88H.1 ABIT5 . . . . . . . BIT 08H.4 ABIT6 . . . . . . . BIT E2H.13 AC100 . . . . . . . ---- ---- SECTIOND100 . . . . . . . ---- ---- SECTIONDP3. . . . . . . . WORD FFC6H A SFRP100 . . . . . . . NEAR 0000H R SEC=C100P3 . . . . . . . . WORD FFC4H A SFRPSW. . . . . . . . WORD FF10H A SFRV2 . . . . . . . . WORD 0000H R SEC=D100

LABEL

Syntax: name[:] LABEL [type]

A label is a symbolic name for a particular location in that section, in which it isdefined. The label name can be followed by a colon, but it is not required. Thelabel inherits the attributes of the parent section; a label may therefore never bedefined outside of a section.

The label directive is useful to define a different name with possibly a differenttype. Example: a label of the type WORD for a location of two consecutive bytes.This is required since the assembler checks variable accesses against typemismatches.

The type is optional and can be one of the following:

none given the label receives a default type, depending on the parentsection: CODE SECTION: type NEAR DATA SECTION: type BYTE BIT SECTION: type BIT

NEAR or FAR the label receives type near or far. This implies that the labelmust have been defined within a section of type code,otherwise an error will result.


3

BYTE or WORD the label receives type byte or word. The parent section mustbe of type CODE or DATA. In case of type WORD, thelabel must have an even address (so called word address).

BIT creates a bit label. The parent section must be of type BIT.


1 D100 SECTION DATA 2 XWORD LABEL WORD0000 34 3 VB1 DB 34H0001 12 4 VB2 DB 12H 5 D100 ENDS 6 7 B100 SECTION BIT 8 BLAB LABEL BIT0000 9 BIT1 DBIT 10 B100 ENDS 11 12 D200 SECTION DATA BITADDRESSABLE 13 DLAB LABEL BYTE0000 14 WORD1 DSW 1 15 D200 ENDS 16 17 C100 SECTION CODE 18 P100 PROC NEAR0000 F2F00000 R 19 MOV R0,XWORD0004 F3FF0000 R 20 MOV RH7,DLAB 21 MOV R5,DLAB ; error, type mismatch*** _____________________________________________^*** ERROR #74, LINE #21, ILLEGAL OPERAND TYPE 22 FLAB LABEL FAR 23 YLAB: LABEL FAR 24000C CB00 25 RET 26 P100 ENDP 27 C100 ENDS 28 29 END

DEFR / DEFA / DEFB

Syntax: name DEFR sfr-address [, attribute]name DEFA on-chip-RAM-address [, attribute]name DEFB bit-address [, attribute]

These directives define SFR names (DEFR), names for absolute internal RAMaddresses (DEFA) and bit-addresses (DEFB). The optional attribute can be:

R read only access allowedW write only access allowedRW read/write access allowed (default)


3

The assembler knows the 80C166 SFR names and the associated bits. If you usea derivative, like the 167 you can define the SFR register set as follows:

� use the primary control $NOMOD166 to eliminate predefined system names.

� create a file which contains the system names and bits using DEFR andDEFB.

� use the general control $INCLUDE ( filename) to include the file with thenew definitions into the assembler.

NOTEThe ASM directory contains already several include files for most of the166/167 derivatives available.

The arguments must follow the rules for each of the three directives:

DEFR the sfr-address must be an even constant value in range0FE00H to 0FFDEH or 0F000H to 0F1DEH. This addressrange specifies the Special-Function-Register area of the166/167. The range 0F000H to 0F1DEH can only be used ifthe MOD167 control directive is specified.

DEFA the on-chip-RAM-address must be an even constant value inrange 0FA00H to 0FDFEH. This address range specifies theinternal data RAM area of the 166/167 CPU.

DEFB the bit-address must be a bit address, written as‘base.bitpos’. Base must be some bit-addressable word,bitpos must be a constant in range 0 to 15. It is the usersresponsibility to make sure, that the base address containingsome bit is really bit-addressable. Please note, that not allSFR addresses are bit-addressable.

Examples:LOC OBJ LINE SOURCE

1 CONFIG DEFR 0FF0CH,RW ; SysCon SFR 2 ZREG DEFR 0FF1CH,R ; Zeroes SFR, readonly 3 XFA00 DEFA 0FA00H ; RAM address 0FFA0H 4 P0P1 DEFB 0FF00H.1 ; Bit, Port0.1 5 BZ0 DEFB ZREG.0 ; Bit, Zeroes.0 6 ODDREG DEFR 0FF1DH ; ERROR: odd address*** __________________________________________^*** ERROR #101, LINE #6, INVALID SYSTEM ADDRESS 7 XBIT DEFB CONFIG.3


3

8 P0P2 BIT P0.2 9 END



BZ0. . . . . . . . BIT 8EH.0 ACONFIG . . . . . . WORD FF0CH A SFRODDREG . . . . . . WORD FE00H A SFRP0 . . . . . . . . WORD FF00H A SFRP0P1 . . . . . . . BIT 80H.1 AP0P2 . . . . . . . BIT 80H.2 AXBIT . . . . . . . BIT 86H.3 AXFA00. . . . . . . WORD FA00H AZREG . . . . . . . WORD FF1CH A SFR

LIT

Syntax: lit-name LIT ‘ literal string’lit-name LIT “ literal string”

The LIT directive provides a simple text substitution facility. Every time theidentifier lit-name is encountered, it will be replaced by the literal string assignedto lit-name. The lit-name follows the same rules as other identifiers, that is, aliteral name is not encountered if it not forms a separate token. If a sub-string is tobe replaced, then lit-name must be enclosed in braces: Text{lit-name}. Theassembler listing shows the expanded lines where literals are substituted.

Example, source text containing literal names before assembly:REG1 LIT 'R1'REG1H LIT 'RH1'REG1L LIT 'RL1'BCAST LIT "BYTE PTR"WCAST LIT "WORD PTR"

D100 SECTION DATA BVAR DSB 10D100 ENDS

C100 SECTION CODEP100 PROC NEAR MOV REG1L,BVAR MOV REG1,WCAST BVARLAB{REG1}: JMP LAB{REG1} RET P100 ENDP C100 ENDS END


3

Assembler listing from previous example:

1 REG1 LIT 'R1' 2 REG1H LIT 'RH1' 3 REG1L LIT 'RL1' 4 BCAST LIT "BYTE PTR" 5 WCAST LIT "WORD PTR" 6 7 D100 SECTION DATA0000 8 BVAR DSB 10 9 D100 ENDS 10 11 C100 SECTION CODE 12 P100 PROC NEAR0000 F3F20000 R 13 MOV RL1,BVAR0004 F2F10000 R 14 MOV R1,WORD PTR BVAR 15 LABR1:0008 0DFF 16 JMP LABR1000A CB00 17 RET 18 P100 ENDP 19 C100 ENDS 20 END

TYPEDEC

Syntax: TYPEDEC name : type [, name : type [, …]]

TYPEDEC is be used to define a type for a symbol. It is normally used to giveforward referenced symbols a type.

A166 ignores the TYPEDEC directive completely. Since A166 is a three passassembler, it is not required to declare forward referenced symbols. A166 uses thepass 2 to determine symbol types. The keyword TYPEDEC has been included forcompatibility with assemblers from other vendors.

ORG

Syntax: ORG expression

The ORG directive can be used to change the value of the location counter withinthe currently active section. The value of expression sets the location counter tothe desired value relative to the start address of the section. Care should be takenwhen the new location counter value indicates an offset below the previous value.In this case code or data may be overwritten which may cause runtime errors.


3

ORG may be used in absolute sections to set the location counter to an absoluteaddress.

The expressions value may not be greater than 65535, forward references are notallowed. The current value of the location counter is represented by the dollarsymbol $ and can be part of the expression. ORG cannot be used in sections ofthe type BIT.


1 D_ABS SECTION DATA AT 4000H0000 2 V1 DSW 1 3 ORG $ + 20H ; gap of 16 words0022 4 V2 DSW 1 5 D_ABS ENDS 6 7 C100 SECTION CODE 8 P100 PROC NEAR0000 0D32 9 JMP XLAB 10 ORG $ + 1000066 F2F12240 11 XLAB: MOV R1,V2006A CB00 12 RET 13 P100 ENDP 14 C100 ENDS 15 END

EVEN

Syntax: EVEN

The EVEN directive ensures that code or data following EVEN is aligned on aword boundary. The assembler creates a gap of one byte if necessary, the contentof the byte gap is left undefined. Accesses to words require even addresses,otherwise the 166/167 CPU will generate a runtime exception (trap).


1 D_ABS SECTION DATA PUBLIC 'DRAM'0000 2 V1 DSB 10001 3 V2 DSW 1 ; Warning because of oddoffset*** WARNING #48, LINE #3, INSUFFICIENT ALIGNMENT0003 4 V3 DSB 10004 5 EVEN0004 6 V4 DSW 1 7 D_ABS ENDS 8 9 D_BIT SECTION DATA BITADDRESSABLE


3

0000 10 WRD1 DSW 10002 11 BRD1 DSB 10004 12 EVEN0004 13 WRD2 DSW 1 14 D_BIT ENDS 15 16 END

EXTERN / EXTRN

Syntax: EXTERN [DPPn] name : type [, …]EXTRN [DPPn] name : type [, …]

The EXTERN directive is used to specify those symbols which will be referencedin the current source module, but are defined in other source modules. Themodule, which defines those symbols must declare them as PUBLIC or GLOBAL.The EXTERN directive specifies the name of the external symbol and its type.

Field Values:

� DPPn: is one of DPP0, DPP1, DPP2, DPP3. The DPP specified will be usedfor references to the external symbol. Note that this can become verydangerous since you have to know in what kind of section the external symbolis defined and which DPP will hold the page base of that section. In case ofDPP configuration changes within your application, this method may cause alot of changes of the DPP’s in the source files.

The following examples show a more flexible approach to solve this problem.

� name is the name of the external symbol.

� type specifies one of the following possible types: BIT a single bit BYTE a byte variable WORD a word variable BITWORD a bit-addressable word NEAR a near label FAR a far label DATA3 a 3-bit constant DATA4 a 4-bit constant DATA8 an 8-bit constant DATA16 a 16-bit constant INTNO a symbolic interrupt number (7-bit) REGBANK a register bank name


3

External symbols may be also defined inside a section. An ASSUME to thissection (necessary in segmented mode) forces externals of type BYTE, WORDand BITWORD to inherit the DPP usage of the parent section in the same way asusual variables. The advantage here is that the programmer has not to care aboutthe DPP which will hold the base page number at runtime. The only assumption isthe corresponding PUBLIC or GLOBAL variables are defined in a consistentmanner:

Module 1: $SEGMENTED ASSUME DPP2 : DSEC PUBLIC VAR1, VAR2 DSEC SECTION DATA PUBLIC VAR1 DSW1 VAR2 DSB1 DSEC ENDS

Module 2: $SEGMENTED ASSUME DPP2 : DSEC DSEC SECTION DATA PUBLIC EXTRN VAR1 : WORD EXTRN VAR2 : BYTE DSEC ENDS

The above example gives the way how to deal with PUBLICS and EXTERNALS.Note that this does not apply in non-segmented mode since the DPP registers arenot changed.


1 $SEGMENTED 2 3 ASSUME DPP2 : DSEC ; DPP2 for accesses inDSEC 4 ASSUME DPP3 : SYSTEM ; DPP3 for SFR addressing 5 6 EXTERN RBANK : REGBANK 7 EXTERN EXBIT : BIT, FPROC : FAR, NPROC : NEAR 8 EXTRN TRAPX : INTNO 9 EXTRN yvar : word 10 11 DSEC SECTION DATA PUBLIC 12 EXTERN ExtW1 : WORD, ExtB1 : BYTE0000 13 LOCV DSW 10002 14 LOCB DSB 1 15 DSEC ENDS 16 17 C100 SECTION CODE 18 P100 PROC FAR0000 E6030300 19 MOV DPP3,#PAG SYSCON; DPP3 = 30004 E6020000 R 20 MOV DPP2,#PAG DSEC ;0008 C6080000 E 21 SCXT CP,#RBANK ; switch to newRegBank000C 0E00 E 22 BCLR EXBIT ; clear external bit000E 9B00 E 23 TRAP #TRAPX ; force sw-trap0010 CA000000 E 24 CALL NPROC ; near call0014 DA000000 E 25 CALL FPROC ; far call0018 F2F10000 E 26 MOV R1,ExtW1 ; use DPP2 per ASSUME


3

001C C2F20000 E 27 MOVBZ R2,ExtB1 ; use DPP2 per ASSUME0020 0012 28 ADD R1,R20022 F6F10000 R 29 MOV LOCV,R1 ; use DPP2 for 'LOCV' 30 MOV R8,yvar ; Error: DPP notknown!*** ________________________________________^*** ERROR #77, LINE #30, MISSING 'DPP' INFORMATION002A F2F80000 E 31 MOV R8,DPP1:yvar ; ok... 32 ; hard to maintain !002E DB00 33 RET 34 P100 ENDP 35 C100 ENDS 36 END



C100 . . . . . . . ---- ---- SECTIONCP . . . . . . . . WORD FE10H A SFRDPP1 . . . . . . . WORD FE02H A SFRDPP2 . . . . . . . WORD FE04H A SFRDPP3 . . . . . . . WORD FE06H A SFRDSEC . . . . . . . ---- ---- SECTIONEXBIT. . . . . . . BIT ---- EXTEXTB1. . . . . . . BYTE ---- R EXT SEC=DSECEXTW1. . . . . . . WORD ---- R EXT SEC=DSECFPROC. . . . . . . FAR ---- EXTLOCB . . . . . . . BYTE 0002H R SEC=DSECLOCV . . . . . . . WORD 0000H R SEC=DSECNPROC. . . . . . . NEAR ---- EXTP100 . . . . . . . FAR 0000H R SEC=C100RBANK. . . . . . . RBANK ---- EXTSYSCON . . . . . . WORD FF0CH A SFRTRAPX. . . . . . . INTNO ---- EXTYVAR . . . . . . . WORD ---- EXT

PUBLIC / GLOBAL

Syntax: PUBLIC name [, name] [, …]GLOBAL name [, name] [, …]

The PUBLIC directive specifies one or more symbols that may be used by othersource modules in the same TGROUP. The GLOBAL directive specifies one ormore symbols that may be used by other modules, even from different TGROUPS.

The following type of symbols can be made PUBLIC or GLOBAL:

� variables (BYTE, WORD, BIT, BITWORD)

� labels (NEAR, FAR)

� constants defined using the EQU directive (DATA3, DATA4, DATA8,DATA16).


3

All other type of symbols are not allowed. PUBLIC and GLOBAL symbols canbe accessed by other modules if the same symbol name has been declaredEXTERN in that module.


1 $SEGMENTED 2 3 BSEC SECTION BIT PUBLIC0000 4 BIT0 DBIT0001 5 BIT1 DBIT 6 BSEC ENDS 7 8 CON3 EQU DATA3 7 9 RB1 REGBANK R0-R15 10 PUBLIC RB1,CON3,P100 11 PUBLIC BIT0, BIT1 12 13 C100 SECTION CODE 14 P100 PROC FAR0000 C6080000 R 15 SCXT CP,#RB10004 4A000000 R 16 MOV BIT1,BIT00008 E17F 17 MOV RH7,#CON3000A DB00 18 RET 19 P100 ENDP 20 C100 ENDS 21 END



BIT0 . . . . . . . BIT 00H.0 R PUB SEC=BSECBIT1 . . . . . . . BIT 00H.1 R PUB SEC=BSECBSEC . . . . . . . ---- ---- SECTIONC100 . . . . . . . ---- ---- SECTIONCON3 . . . . . . . DATA3 0007H ACP . . . . . . . . WORD FE10H A SFRP100 . . . . . . . FAR 0000H R PUB SEC=C100RB1. . . . . . . . ---- ---- PUB REGBANK


3

Defining and Initializing Variables

Syntax: [name[:]] DB init [, init ] [, …][name[:]] DW init [, init ] [, …][name[:]] DBIT [ expression][name[:]] DS expression[name[:]] DSB expression[name[:]] DSW expression

This directives allow to reserve or initialize memory. The colon may optionallyfollow the name.

The meaning of the various directives is as follows:

DB Define Byte; initialize 1 byte in memory. If init is a string ofcharacters, the characters are stored each in one byte adjacentto another. A string can be approximately 500 characters inlength (the maximum length of an input line to the assembleris 510 characters). The DB directive can be used in data orcode sections, it is not allowed in bit sections.

DW Define Word; initialize 1 word in memory. The offset in thecurrent section must be even (word alignment), otherwise awarning occurs. The offset can be aligned with the EVENdirective. The DW directive cannot be used within bitsections.

DBIT Define BIT; reserve one or more bits in memory. DBIT isallowed only within bit sections. If the optional expression ispresent, the number of bits given by the expression arereserved, otherwise only one bit is reserved. The expressionmust evaluate to a constant value with no forward references.Initialization of bits is not possible.

Examples:bit1: DBIT ; reserve one bitbit2: DBIT 10 ; reserve ten bitsbit3 DBIT 1 ; reserve one bit

DS Define Storage; reserves as many bytes of memory asspecified by the expression, the memory is not initialized. Ifthe current section is of the type BIT, the specified number of


3

bits are reserved. DS is allowed in any type of section. Apreceding name receives type BYTE.

DSB Define Storage Byte; same as DS with the exception thatDSB cannot be used within sections of type BIT.

DSW Define Storage Word; reserves as many words of memory asspecified by the expression, the memory is not initialized.DSW may not be used within sections of the type BIT.

Different init expressions are possible depending on the directive used:

CONSTANT EXPRESSIONthe expression represents a constant value. The value of the constantexpression must be in range 0 to 255 when bytes are initialized. In case ofword initialization, the value must be in range 0 to 65535. An expression maycontain a character string not longer than two characters.

DB 13,10DB “hello world”, 13,10,0, 4 * 8, -2

If you want to include a single or double quote within a string, use twoconsecutive quotes or use a single quote in a string enclosed within doublequotes or vice versa. The following example shows two equivalentinitializations using a string:

DB ‘what’’s going on’DB “what’s going on”

DW may receive a string of length one ore two characters (example: ‘a’, ‘ab’,“a” or “ab”). DB may receive a string consisting of up to about 500characters. A string of length zero is not allowed.

ADDRESS EXPRESSIONthe expression represents the address of a variable or segment or page number:

DW PAG symbolDW POF symbolDW data_symbol

The next example initializes three words with the current offset. Note that theoffset advanced (by two because of DW), therefore three different values arestored:

DW $, $, $


3

When you use a section name or group name in a DW directive, the segmentnumber for code sections or page number for data sections is stored:

DW section_symbolDW code_label ; store segment offsetDW group_symbol ; page or segment number

In SEGMENTED mode of operation it is possible to generate data addresseswhich contain the offset of some data variable and the DPP bits in one word. Thiscompares to the method of the C166 compiler when dealing with near pointers:

$SEGMENTED$ASSUME DPP1 : D100

D100 SECTION DATA v1 DW DPP3 : POF symbol v2 DW DPP2 : POF symbol v3: DW DPP1 : POF symbol v4: DW DPP0 : POF symbol symbol: dw -3D100 ENDS

C100 SECTION CODE SCXT DPP3,#PAG D100 MOV R15,-4 MOV R8,v1 ; load DPP1:v1 MOV [R8],R15 ; store -4 to 'symbol' POP DPP3C100 ENDS

In the above case, the word holds the DPP information in bits 15 and 14. Theoffset information in range 0 to 16383 is held in bits 0 to 13. Usage of suchgenerated pointers for addressing implies that the associated DPP’s are correctlyinitialized. If this is not the case, addresses which relate to a wrong pages may begenerated, depending on the current content of the DPP in use.

NOTEWhen using the special form ‘DPPn:POF symbol’, the POF operator must beused, otherwise the DPP selection bits are not merged into the page offset.


3

Defining and Initializing Pointers

Syntax: [name[:]] DSPTR init [, init ] [, …][name[:]] DPPTR init [, init ] [, …][name[:]] DBPTR init [, init ] [, …]

Pointers are memory units which contain complete physical addresses of variablesor labels. The meaning of the above directives is as follows:

DSPTR: performs segment pointer initialization. DSPTR is used tocreate pointers which refer to label or procedure names, inother words: items which are members of code sections. Forthe 167 also data pointers can be created, when the object isaccessed using the EXTS instruction. The pointer createdconsists of two words. The first word contains the segmentrelative offset of the reference symbol. The offset can havevalues in range 0 to 65535. The second word contains thephysical segment number of the 64K segment, which thereference symbol is member of. The value is in range 0 to255.

DPPTR: performs page pointer initialization. DPPTR is used to createpointers which refer to variables, which are members of datasections. The pointer created consists of two words. Thefirst word contains the page relative offset of the referencesymbol. The offset can have values in range 0 to 16383. Thesecond word contains the physical page number of the 16Kpage, which the reference symbol is member of. The value isin range 0 to 1023.

DBPTR: performs a bit pointer initialization. DBPTR can be used tocreate pointers which refer to members of bit sections or bitswhich are based on bit-addressable words. A bit-pointerconsists of three words. The first word contains the bitposition (range: 0 to 15), the second word contains the pageoffset of the bit-addressable word (range: 0 to 0DFFH) andthe third word contains the physical page number which isalways 3.


3

Examples:LOC OBJ LINE SOURCE

1 EXTERN NPROC : NEAR 2 3 BSEC SECTION BIT0000 4 BT1 DBIT0001 5 BT2 DBIT 6 BSEC ENDS 7 8 DSEC SECTION DATA0000 00000000 R 9 bp1 DBPTR BT1 ; Bit pointer ref. BT10000 03000006 00000000 R 10 bp2 DBPTR BT2 ; Bit pointer ref. BT20006 0300000C 00000000 R 11 pd1 DPPTR bp1 ; Page pointer0010 00000000 E 12 cp1 DSPTR NPROC ; Segment pointer 13 DSEC ENDS 14 15 END

NAME

Syntax: NAME module-name

The NAME directive is used to identify the current module with a module-name.The linker/locator L166 requires the name of each input module to be different.The module name may be any identifier including reserved words of the assemblerA166. If the NAME directive is missing, the module name will be set to the nameof the input file without path specification and file name extension. The input filename C:\C166\LIB\STARTUP.A66 will lead to the module name STARTUP.

Example:NAME PARSER_MODULE

END

Syntax: END

The END directive marks the end of the input file to the assembler and is alwaysrequired. If END is missing, an error occurs. Lines of text beyond END will beignored by the assembler, but not by the macro processor contained within A166.

Example:NAME X_MODULEEND ;end of input file


3


4

Chapter 4. Invocation and ControlsThis part explains how to use A166 to assemble 166/167 assembly source filesand discusses the assembler controls that may be specified on the command lineand within the source file.

Using the controls described in this part, you can specify which operations areperformed by A166. For example, you can direct A166 to generate a listing file,produce cross reference information, and control the amount of informationincluded in the object file. You can also conditionally assemble sections of codeusing the conditional assembly controls.

Running A166

The A166 assembler is invoked by typing A166 at the DOS prompt. Thecommand line must contain the name of an 166/167 assembly source file to beassembled as well as any command line controls that are required. The format forthe A166 command line is:

A166 sourcefile �� controls … ��

where

sourcefile is the name of the source program you want to assemble. A166assembler

controls are used to direct the operation of the assembler. Refer to“Assembler Controls” on page 67 for more information.

The following command line example invokes A166 and specifies the source fileSAMPLE.A66 and uses the controls DEBUG, XREF, and PAGEWIDTH .

A166 SAMPLE.A66 DEBUG XREF PAGEWIDTH(132)

A166 displays the following information upon successful invocation andassembly.

DOS MACRO ASSEMBLER A166 V3.00COPYRIGHT KEIL ELEKTRONIK GmbH 1992 - 1996

ASSEMBLY COMPLETE, NO ERRORS FOUND

66 Chapter 4. Invocation and Controls

4

Command Files

Command files are ASCII text files that contain information that you wouldnormally type on the DOS invocation line. Command files can include the nameof the source file to assemble as well as any assembler controls.

A166 allows you to specify a command file on the DOS invocation line using an atsign (@).

ExampleA166 @CMDFIL

The contents of the file CMDFIL will be interpreted as one long input commandline.

DOS ERRORLEVEL

After assembly, the number of errors and warnings detected is output to thescreen. A166 then sets the DOS ERRORLEVEL to indicate the status of theassembly. Values are listed in the following table:

Errorlevel Meaning

0 No Errors Or Warnings

1 Warnings Only

2 Errors And Possibly Also Warnings

3 Fatal Errors

You can access the ERRORLEVEL variable in DOS batch files for conditionalinquiries in order to terminate the batch processing when an error occurs. Refer toyour DOS User’s Guide for more information about ERRORLEVEL or batchfiles.


4

Output Files

A166 generates a number of output files during assembly. By default, each ofthese shares the same basename as the source file. However, each has a differentfile extension. The following table lists the files and gives a brief description ofeach.

File Extension Description

basename .LST Files with this extension are listing files that contain the formatted source textalong with any errors detected by the assembler. Listing files may optionallycontain symbols used and the generated assembly code. Refer to “PRINT /NOPRINT” on page 89 for more information.

basename .OBJ Files with this extension are object modules that contain relocatable objectcode. Object modules can be linked into an absolute object module by theL166 Linker/Locator. Refer to “OBJECT / NOOBJECT” on page 85 for moreinformation.

Assembler ControlsA166 provides a number of controls that you can use to direct the operation of theassembler. Controls are composed of one or more letters or digits and, unlessotherwise indicated, can be specified after the filename on the invocation line or ina control line within the source file. Control lines are prefixed by the dollar sign($).

ExampleA166 TESTFILE.A66 DEBUG XREF

or

$MPL$DEBUG$XREF

or

$MPL DEBUG XREF

In the above example, MPL, DEBUG, and XREF are all control commands andTESTFILE.A66 is the source file that will be assembled.

A166 has two classes of controls: primary and general. The primary controls areset in the invocation line or the primary control lines and remain in effect


4

throughout the assembly. For this reason, primary controls may be used only inthe invocation line or in the control line at the beginning of the program. Onlyother control lines (that do not contain the INCLUDE control) may precede a linecontaining a primary control. The INCLUDE control terminates of primarycontrols.

If a primary control is specified in the invocation line and in the primary controllines, the first time counts. This enables the programmer to override primarycontrols via the invocation line.

The general controls are used to control the immediate action of the assembler.Typically their status is set and modified during the assembly. Control linescontaining only general controls may be placed anywhere in your source code.

The table below lists all of the controls, their abbreviations, their default values,and a brief description of each.

Name / Abbreviation Meaning

ABSOLUTE, AB Checks the module against relocatable references.

DATE(date) / DA Places a date string in header (9 characters maximum).

CASE Enable case sensitive mode for symbol names.

COND, CO / NOCOND, NOCO Enable or disable skipped sections to appear in the listing file.

DEBUG / DB Outputs debug symbol information to object file.

EJECT / EJ ‡ Continue listing on next page.

ERRORPRINT[(file )] / EP Designates a file to receive error messages in addition to the listing.

EXPDECNUM . EDN Set the output format of the macro processor function %EVAL todecimal format.

GEN / GE ‡ Generates a full listing of macro expansions in the listing file.

NOGEN / NOGE ‡ List only the original source text in listing file.

INCLUDE(file ) / IC ‡ Designates a file to be included as part of the program.

INCDIR / ID Define up to five additional paths to be searched when a file isincluded via $INCLUDE (file).

LINK ‡ Place Linker/Locator controls in the Assembler source code.

LIST, NOLIST / LI, NOLI ‡ Print or do not print the assembler source in the listing file.

NOAMAKE Disable AMAKE information.

NOLINES Do not generate LINE number information.

NOMACRO / NOMR Disable Standard Macros

MOD166 / M166 Disable the additional 167 instructions.

NOMOD166 / NOM166 Do not recognize the predefined special function registers.

MOD167 / M167 Enable the additional 167 instructions.

NOOBLECT / NOOJ Designates that no object file will be created.

NOSYMBOLS / NOSB No symbol table is listed.


4

Name / Abbreviation Meaning

NOSYMLIST,NO SL ‡ Do not list the following symbol definitions in the symbol table.

OBJECT[( file )] / OJ Designate file to receive object code.

PAGELENGTH(n) / PL Sets maximum number of lines in each page of listing file.

PAGEWIDTH(n) / PW Sets maximum number of characters in each line of listing file.

PRINT[(file )] / PR Designates file to receive source listing.

NOPRINT / NOPR Designates that no listing file will be created.

REGUSE ‡ Defines register usage of assembler functions for the C optimizer.

RESTORE / RS ‡ Restores control setting from SAVE stack.

SAVE / SA ‡ Stores current control setting for GEN, LIST and SYMLIST.

SEGMENTED, SG /

NONSEGMENTED, NOSG

Define the mode of CPU operation.

USEDEXTONLY / UEO Prevent A166 from generating external definitions for unused externalidentifiers.

TABS(n) / TA Specifies the tab setting.

TITLE(string ) / TT Places a string in all subsequent page headers.

TYPE, TY / NOTYPE, NOTY Defines whether type information is included in object file or not.

XREF / XR Creates a cross reference listing of all symbols used in program.

‡ — General controls

NOTESome controls like EJECT and SAVE cannot be specified on the command line.The syntax for each control is the same when specified on the command line orwhen specified within the source file. A166 will generate a fatal error forcontrols that are improperly specified.


4

ABSOLUTE

Name: ABSOLUTE

Control-type: Primary

Abbreviation: AB, NOAB

Arguments: None

Default: None

µVision Control: Options—A166 Assembler—Object—Check for AbsoluteModule

Definition: checks whether an assembled module is absolute or containsrelocatable references. The module is not absolute, if externalsymbols are defined or if one section is defined without ATexpression. AT expression forces sections to be absolute.An absolute module may be directly loaded without having itprocessed by L166. If ABSOLUTE is in effect and themodule has relocatable references, then a warning is given atthe end of the module:

*** WARNING #105, LINE #nn, $ABSOLUTE: NOT AN ABSOLUTE MODULE

Example:$ABSOLUTEA166 SAMPLE.A66 ABSOLUTE


4

CASE / NOCASE

Name: CASE, NOCASE

Control Type: Primary

Abbreviation: CA, NOCA

Arguments: None

Default: NOCASE

µVision Control: Options—A166 Assembler—Object—Case sensitiveassembly

Definition: the assembler is directed to operate in case sensitive mode(CASE) or case insensitive mode. In case insensitive modethe assembler converts lower case input characters to uppercase. CASE becomes meaningful if modules generated by theassembler are combined with modules generated from the Ccompiler. Identifiers exported from C modules appear alwaysas written, the corresponding names in the assembler modulemust therefore put into the object module as written,preserving case sensitivity.

Example:$CASEA166 SAMPLE.A66 CASE


4

COND / NOCOND

Name: COND/NOCOND

Control Type: General

Abbreviation: None

Arguments: None

Default: COND

µVision Control: Options—A166 Assembler—Listing—Include conditionalcode

Definition: COND indicates that skipped parts of an IF-ELSEIF-ENDIFconstruct will be listed. The skipped lines can be recognizedby missing line numbers. NOCOND indicates thatunassembled parts will be not listed.

Examples:$ COND$ NOCOND


4

DATE

Name: DATE


Abbreviation: DA

Arguments: a string enclosed in parentheses (max. 9 characters long).

Default: Date is obtained from Operating system.

µVision Control: Options—A166 Assembler—Listing—Date

Definition: the assembler takes the character specified string and places itin the header of every page of the program listing. A fatalerror occurs if the string contains more than 9 characters.

Example:$ DATE (05/09/92)$ DA ('09-05-92')A166 SAMPLE.A66 DATE (05/09/92)


4

DEBUG / NODEBUG

Name: DEBUG, NODEBUG


Abbreviation: DB, NODB

Arguments: None

Default: NODEBUG

µVision Control: Options—A166 Assembler—Object—Include debuginformation

Definition: DEBUG directs the assembler to include symbolicinformation into the object module for symbolic debuggingpurposes. A166 also emits line number information into theobject file. This enables dScope-166 to perform source levellanguage display. If NODEBUG is active, no symbolicinformation and line numbers will be put into the object file.

Example:$ DEBUGA166 SAMPLE.A66 DEBUG


4

EJECT

Name: EJECT


Abbreviation: EJ

Arguments: None

Default: None

µVision Control: None

Definition: EJECT inserts a form feed into the listing file and generates aheader at the top of the next page. The control is ignored ifNOLIST or NOPRINT is in effect.

Example:$ EJECT


4

ERRORPRINT / NOERRORPRINT

Name: ERRORPRINT, NOERRORPRINT


Abbreviation: EP, NOEP

Arguments: an optional filename in parenthesis that complies with theDOS conventions.

Default: NOERRORPRINT


Definition: ERRORPRINT indicates that all erroneous lines of sourceand the corresponding error message shall be output to thespecified file. If no file is specified the erroneous lines aredisplayed at the console.

A fatal error occurs if the console is specified as the outputfor the list file and ERRORPRINT has no argument.

Example:$ ERRORPRINT (SAMPLE.ERR)$ NOEPA166 SAMPLE.A66 EP


4

EXPDECNUM

Name: EXPDECNUM


Abbreviation: EDN

Arguments: None

Default: expand %eval result to a hex number


Definition: The EXPDECNUM directive causes the macro preprocessorto expand the result to a decimal number. WithoutEXPDECNUM, a hex number is generated.

Example:$ EXPDECNUMA166 SETUP.A66 EXPDECNUM


4

GEN / GENONLY / NOGEN

Name: GEN, GENONLY, NOGEN


Abbreviation: GO (for GENONLY)

Arguments: None

Default: NOGEN

µVision Control: Options—A166 Assembler—Listing—Macro expansion

Definition: these directives specify the amount of intermediate expansiontext, which is output:

NOGEN: the macro call is shown along with thefinal macro expansion text.

GENONLY: the macro call is shown plus the firstlevel of intermediate macro expansion.

GEN: the complete macro expansion includingall intermediate expansions are shown.This mode can be selected for macrodebugging purposes.

These controls are processed by the macro preprocessor andare ignored by the remaining assembler phases.

Example:$ NOGEN$ GENONLYA166 SAMPLE.A66 GEN


4

INCDIR

Name: INCDIR


Abbreviation: ID

Arguments: one or more DOS conforming path names enclosed inparentheses

Default: None


Definition: With INCDIR, you can supply one or more paths to searchfor when a $INCLUDE (file) directive processed.

When an INCLUDE directive is processed, the assemblerfirst tries to find the include file in the current path. If thisfails, then the paths specified by INCDIR will be searched.The path order corresponds to the order used in the INCDIRdefinition.

Example:$ INCDIR (C:\C166\ASM)A166 STARTUP.A66 INCDIR (C:\C166\ASM,C:\C166\MYINC)


4

INCLUDE

Name: INCLUDE


Abbreviation: IC

Arguments: a DOS conforming filename enclosed in parentheses

Default: None


Definition: INCLUDE inserts the content of the specified file into theprogram immediately following the control line. INCLUDEfiles may be nested. The maximum number of nesting is nine.INCLUDE must be specified through a control line, usage inthe invocation line is not allowed.

The INCLUDE directive should not be intermixed with otherdirectives one the same control line. Directives followingINCLUDE in the same control line are ignored.

The INCLUDE directive can be used to include any text likeregister and bit definitions into the assembly process.

Example:$ INCLUDE (REG167.INC)


4

LIST / NOLIST

Name: LIST, NOLIST


Abbreviation: LI, NOLI

Arguments: None

Default: LIST


Definition: NOLIST disables the printing of subsequent source text in thelisting file. LIST causes the text to be displayed. Linescausing errors will be listed even if NOLIST is in effect.LIST and NOLIST are overridden by the NOPRINT control.

Example:$ NOLIST$ LISTA166 SAMPLE.A66 NOLIST


4

MACRO / NOMACRO

Name: MACRO/NOMACRO


Abbreviation: None

Arguments: None

Default: MACRO


Definition: MACRO indicates that macro definitions and invocations willbe recognized and processed (default). NOMACRO disablesthe macro preprocessor.

Examples:$ MACRO$ NOMACRO


4

MOD166 / NOMOD166

Name: MOD166, NOMOD16


Abbreviation: M166, NOM166

Arguments: None

Default: MOD166

µVision Control: Options—A166 Assembler—Object—Define 80C166Special Function Registers (SFRs)

Definition: MOD166 specifies that all system names described in thehardware specification for the 166/167 are known to theassembler and can be used without declaration. Assemblingwith NOMOD166 being active, only the names of the generalpurpose registers and the special function registers DPP0 -DPP3, MDL, MDH, MDC are known to the assembler.NOMOD166 should be used if a customer specific SFRdefinition file is used:

$ NOMOD166$ INCLUDE (REG167.DEF)

Example:$ NOMOD166


4

MOD167

Name: MOD167


Abbreviation: M167

Arguments: None

Default: MOD166

µVision Control: Options—A166 Assembler—Object—Enable 80C167instructions

Definition: MOD167 enables the 167 instruction set which is a supersetof the 166 instruction set. The definition file REG167.INCshould be included for definition of the SFR names and theextended set of SFR names.

Example:$ MOD167$ INCLUDE (REG167.INC)


4

OBJECT / NOOBJECT

Name: OBJECT, NOOBJECT


Abbreviation: OJ, NOOJ

Arguments: OBJECT (filename)

Default: OBJECT (input_filename.OBJ)


Definition: The OBJECT (filename) directive changes the name of theobject file to the name provided. By default, the name andpath of the source file with the extension ‘.OBJ’ is used. TheNOOBJECT option disables the generation of an object file.

Example:$ OBJECT (C:\SAMPLE.OBJ)$ NOOJ$ OJ (C:\SAMP.DIR\SAMPLE.OBJ)A166 SAMPLE.A166 OBJECT (C:\OBJS\XSAMPLE.OBJ)


4

PAGELENGTH

Name: PAGELENGTH


Abbreviation: PL

Arguments: a number between 10 and 65535 enclosed in parenthesis

Default: PAGELENGTH(69)

µVision Control: Options—A166 Assembler—Listing—Page Length

Definition: PAGELENGTH specifies the maximum number of lines perpage to be printed in the listing file. The argument must be adecimal number in range 18 to 32760.

Example:$ PAGELENGTH (132)$ PL (75)A166 SAMPLE.A66 PAGELENGTH (120)


4

PAGEWIDTH

Name: PAGEWIDTH


Abbreviation: PW

Arguments: a number between 78 and 132 enclosed in parenthesis

Default: 120 characters per line

µVision Control: Options—A166 Assembler—Listing—Page Width

Definition: the PAGEWIDTH directive specifies the maximum numberof characters on a line to be printed in the listing file. Longerlines are automatically wrapped around to the next line.

Example:$ PW (79)A166 SAMPLE.A66 PW (78)


4

PAGING / NOPAGING

Name: PAGING, NOPAGING


Abbreviation: PA, NOPA

Arguments: None

Default: PAGING


Definition: NOPAGING disables the generation of form feeds and pageheaders in the listing. PAGING enables form feeds andheaders. The length of the pages is specified byPAGELENGTH directive.

Example:$ NOPAGINGA166 SAMPLE.A66 NOPA


4

PRINT / NOPRINT

Name: PRINT, NOPRINT


Abbreviation: PR, NOPR

Arguments: PRINT (filename)

Default: PRINT (input_filename.LST)

µVision Control: Options—A166 Assembler—Listing—Generate .LST file

Definition: The assembler produces a listing of each assembled programusing the path and name of the source file with the extension‘.LST’. The name of that listing file can be redefined by useof the PRINT option. When the NOPRINT option isinvoked, no listing is produced.

Example:$ PRINT (C:\SAMPLE.LST)$ PR (:CO:)$ NOPRINTA166 SAMPLE.A166 PRINT (C:\LSTS\XSAMPLE.LST)


4

REGUSE

Name: REGUSE


Abbreviation: RU

Arguments: A PROC identifier and a register list enclosed in parenthesis

Default: None


Definition: The REGUSE control specifies the registers modified duringexecution of the function given by PROC identifier.REGUSE can be used in combination with the C166 compilerand allows global register optimization also for functionscoded in assembly language. For more information aboutglobal register optimization refer to the C166 CompilerUser’s Guide.

The registers R0, R1, … R15, MDC (designates MDL, MDHand MDC) and DPP0, DPP1, DPP2, DPP3 may be given. Aregister range is a shortcut for registers such as ‘R0-R8’ or‘DPP0-DPP3’.

The assembler does not check the actual registers used withinthe procedure. It is up to you to specify the correct set ofregisters, otherwise runtime problems may occur due tooverwritten register values.

NOTEThe PROC identifier should exactly match the identifierused in the PROC definition if $CASE is used. This means,spelling as well as lower and upper case letters shouldmatch. If $CASE is not used, then the PROC identifiershould be written using upper case letters.

Example:$ REGUSE p100 (R1-R2, R8, MDC, DPP3)

PUBLIC p100


4

ASSUME DPP3:SYSTEMC100 SECTION CODE

p100 PROC NEAR ; p100 is the PROC identifier MOV R8,R1 MOV MDC,R1 ; DPP3 used to address MDC MUL R2 MOV R1,MDL ; DPP3 used to address MDL MOV R2,MDH RETp100 ENDP

C100 ENDS

END


4

SAVE / RESTORE

Name: SAVE/RESTORE


Abbreviation: SA/RS

Arguments: None

Default: None


Definition: SAVE stores the current setting of LIST on the internalassembler stack. This stack can store up to 9 SAVE levels.RESTORE restores the most recently saved value of LIST.

Examples:$ SAVE NOLIST$ INCLUDE (REG167.INC)$ RESTORE


4

SEGMENTED / NONSEGMENTED

Name: SEGMENTED, NONSEGMENTED


Abbreviation: SG, NOSG

Arguments: None

Default: NONSEGMENTED

µVision Control: Options—A166 Assembler—Object—Segmented Mode

Definition: NONSEGMENTED specifies that A166 translates the sourcemodule using the non-segmented mode of CPU operation.The ASSUME directive and DPP-prefixes are not needed inthis mode. NONSEGMENTED specifies that the DPP’s areonce loaded and never changed, the total amount of memorythat can be addressed is 64K for both code and data.

SEGMENTED specifies that the translation is using thesegmented mode of CPU operation. DPP’s must be set withthe ASSUME directive to data sections or groups to establishand check that data can be addressed properly. The fulladdress space can be covered in SEGMENTED mode only.

Examples:$ SEGMENTED$ SGA166 SAMPLE.A66 SEGMENTED


4

SYMBOLS / NOSYMBOLS

Name: SYMBOLS/NOSYMBOLS


Abbreviation: SB/NOSB

Arguments: None

Default: SYMBOLS

µVision Control: Options—A166 Assembler—Listing—Include Symbols

Definition: SYMBOLS specifies whether a symbol table shall be listed.The SYMBOLS control is overridden by NOPRINT. TheXREF activates the SYMBOLS control.

Example:$ SYMBOLS$ NOSBA166 SAMPLE.A66 NOSYMBOLS


4

TABS

Name: TABS


Abbreviation: TA

Arguments: decimal number in range 1 to 16, enclosed in parentheses.

Default: TABS(8)

µVision Control: Options—A166 Assembler—Listing—Tabs

Definition: specifies the number of blanks that must be inserted toreplace a tab character in the list file.

Example:$ TABS (4)A166 SAMPLE.A66 TABS (4)


4

TITLE

Name: TITLE


Abbreviation: TT

Arguments: String enclosed in parentheses (max. 60 characters)

Default: Title of ‘NAME’ or source code name without an extension.

µVision Control: Options—A166 Assembler—Listing—Title

Definition: TITLE defines a title string that is printed in the page headerof the listing. If the TITLE control is omitted then the nameof the input file without path and extension is used for the titlestring.

Example:$ TITLE (Oven Controller Version 3.12)$ TT ('quote enclosed string')


4

TYPE / NOTYPE

Name: TYPE / NOTYPE


Abbreviation: TY, NOTY

Arguments: None

Default: TYPE


Definition: The TYPE directive directs A166 to put type information intothe object file. NOTYPE avoids type information in theobject file. All the symbols from the object file will betypeless.

Example:$ NOTYPE$ A166 SETUP.A66 NOTYPE


4

USEDEXTONLY

Name: USEDEXTONLY


Abbreviation: UEO

Arguments: None

Default: generate external definitions for unused external identifiers


Definition: USEDEXTONLY directs A166 to omit external definitionrecords for unused external identifiers.

Example:$ USEDEXTONLY$ A166 SETUP.A66 USEDEXTONLY


4

XREF / NOXREF

Name: XREF, NOXREF


Abbreviation: XR/NOXR

Arguments: None

Default: NOXREF

µVision Control: Options—A166 Assembler—Listing—Include crossreference

Definition: XREF indicates that a cross reference table which marks theuse of symbols, is added to the symbol table. The crossreference lists the line numbers of lines with a reference to thesymbol. A hash mark (#) following the line number indicatesthat the symbol is defined in this line. The NOPRINT controloverrides XREF.

Example:$ XREF


4

Directives for Conditional AssemblyThe directives for conditional assembly belong to the class of general controls.Conditional assembly can be used to implement different program versions ordifferent memory models with one source file. Therefore only one source modulemust be maintained to satisfy several applications.

Text blocks to be conditionally assembled are enclosed by IF, ELSEIF, ELSE andENDIF.

The SET and RESET directives may be used in the invocation line of theassembler. The remaining instructions for conditional assembly are only allowedwithin the source file and cannot be part of the assembler invocation line.

IF blocks may be nested to a maximum of ten. If a block is not translated thenested conditional blocks which are part of this block are also skipped.

The following table lists the conditional assembly control statements.

Control Meaning

IF Translate block if condition is true

ELSE Translate block if the condition of a previous IF is false.

ELSEIF Translate block if condition is true and a previous IF or ELSEIF is false.

ENDIF Marks end of a block.

RESET Set symbols checked by IF or ELSEIF to false.

SET Set symbols checked by IF or ELSEIF to true or to a specified value.


4

SET / RESET

Name: SET/RESET

Abbreviation: none

Arguments: (<variable> [,<variable> [, …]])<variable> = <num. value> [, …])(<var>, <var> = <num. value>, <var> [, …])

Default: None


Definition: SET and RESET assign a numeric value to a specifiedvariable. These variables can be used in expressionscontaining ‘IF’ and ‘ELSEIF’ directives for conditionalassembly. The variables must conform to the usualconventions and are only used to control the assembler. Thevariables are administered separately and cannot interferewith the other symbols.

The <numerical value> can be a number or an absoluteexpression. If SET is used in the invocation line, theargument to SET must be a single decimal number, otherwisean absolute expression is allowed.

$ SET (TMP, TMP1 = 55, TMP2, TMP3)

In the example above the variables TMP, TMP2 and TMP3are assigned the implicit value 0FFFFH (‘TRUE’) since noexplicit value is given. The TMP1 variable is assigned to 55decimal.

$ RESET (TMP, VAR, TMP3)

The variables above are assigned to 0000H (‘FALSE’). If avariable is unknown it is automatically assigned to 0000H.

Examples:$ SET (TEST, ITERATION = 3)$ RESET (TEST, INTERATION, DEBUG_VAR)


4

IF

Name: IF

Abbreviation: none

Arguments: <numerical expression>

Default: None


Definition: The numerical expression is computed and if the value istrue, the statements in the IF block will be executed. Controlpasses as soon as ENDIF, ELSEIF or ELSE statement on thesame nesting level is encountered. If the value is false (0)control is only passed after controls with a $ sign in front.

An error occurs if IF/ENDIF statements are not balanced.

Examples:$ IF (DEBUG_VAR = 3)Version_3: MOV R8,#TABLE_3 <other text lines>$ ENDIF


4

ELSEIF

Name: ELSEIF

Arguments: <numerical expression>

Default: None


Definition: ELSEIF introduces an alternative IF block that has control tillthe next ELSEIF, ELSE or ENDIF directive, assumed theexpression evaluates to TRUE and no previous IF or ELSEIFwas true.

Example:$ IF (SWITCH = 1) <line(s) of text>$ ELSEIF (SWITCH = 2) <line(s) of text>$ ELSEIF (SWITCH = 3) <line(s) of text>$ ENDIF


4

ELSE

Name: ELSE

Arguments: None

Default: None


Definition: The ELSE directive introduces an alternative to the IF orELSEIF block. The ELSE block is assembled till the nextENDIF directive, assumed that no previous IF- of ELSEIF-directive evaluated to TRUE.

Example:$ IF (DEBUG) ; is true, when DEBUG != 0 <line(s) of text>$ ELSEIF (TEST) <line(s) of text>$ ELSE <line(s) of text>$ ENDIF


4

ENDIF

Name: ENDIF

Arguments: None

Default: None


Definition: The ENDIF directive terminates a IF block. Control isreturned to the calling IF block if the assembler wasassembling before the IF block, then the assembly willcontinue. This is important when IF statements are nested.

An error occurs if the number of ENDIF directives is notequal to the number of IF statements.

Example:$ IF (TEST) <line(s) of text>$ ENDIF


4


5

Chapter 5. The Macro Processor

Introduction

The Macro Processing Language (MPL) of A166 is a string replacement facility.It permits you to write repeatedly used sections of code once and then insert thatcode at several places in your program. Perhaps MPL’s most valuable capabilityis conditional assembly-with all microprocessors, compact configurationdependent code is very important to good program design. Conditional assembly ofsections of code can help to achieve the most compact code possible.

Overview

The macro processor views the source file in different terms than the assembler: tothe assembler, the source file is a series of lines--control lines, and directive lines.To the macro processor, the source file is a long string of characters.

All macro processing of the source file is performed before your code isassembled. Because of this independent processing of macros and assembly ofcode, we must differentiate between macro-time and assembly-time. At macro-time, assembly language symbols and labels are unknown. SET and EQUsymbols, and the location counter are also not known. Similarly, at assembly-time,no information about macros is known.

The macro processor scans the source file looking for macro calls. A macro call isa request to the processor to replace the macro name of a built-in or user-definedmacro by some replacement text.

Creating and Calling Macros

The macro processor is a character string replacement facility. It searches thesource file for a macro call, and then replaces the call with the macro’s returnvalue. A % character signals a macro call.

The macro processor function DEFINE creates macros. Macro processorfunctions are a predefined part of the macro language, and can be called withoutdefinition. The syntax for DEFINE is:

108 Chapter 5. The Macro Processor

5

%[*]DEFINE (macro name) [parameter-list] (macro-body)

DEFINE is the most important macro processor function. Each of the symbols inthe syntax above (macro name, parameter-list, and macro-body) are described inthe following.

Creating Parameterless Macros

When you create a parameterless macro, there are two parts to a DEFINE call:

� macro name

The macro name defines the name used when the macro is called.

� macro body

The macro-body defines the return value of the call.

The syntax of a parameterless macro definition is shown below:

%*DEFINE (macro name) (macro-body)

The ‘%’ is the metacharacter that signals a macro call. The ‘*’ is the literalcharacter. The use of the literal character is described later of this chapter.

Macro names have the following conventions:

� maximum of 31 characters long

� first character must be one of ‘A’-‘Z’, ‘a’-‘z’, ‘_’, or ‘?’

� subsequent characters must be one of ‘A’-‘Z’, ‘a’-‘z’, ‘_’, ‘?’, or ‘0’-‘9’

The macro-body is usually the replacement text of the macro call. However, themacro-body may contain calls to other macros. If so, the replacement text isactually the fully expanded macro-body, including the calls to other macros. Whenyou define a macro using the syntax shown above, macro calls contained in thebody of the macro are not expanded, until you call the macro.

The syntax of DEFINE requires that left and right parentheses surround themacro-body. For this reason, you must have balanced parenthesis within themacro-body (each left parenthesis must have a succeeding right parenthesis, andeach right parenthesis must have a preceding left parenthesis). We call characterstrings that meet these requirements balanced-text.


5

To call a macro, use the metacharacter followed by the macro name for the macro.(The literal character is not needed when you call a user-defined macro.) Themacro processor will remove the call and insert the replacement text of the call. Ifthe macro- body contains any call to other macros, they will be replaced with theirreplacement text.

Once a macro has been created, it may be redefined by a second DEFINE.

Macros with Parameters

Parameters in a macro body allow to fill in values when you call the macro. Thispermits you to design a generic macro that produces code for many operations.

The term parameter refers to both the formal parameters that are specified whenthe macro is defined, and the actual parameters or arguments that are replacedwhen the macro is called.

The syntax for defining macros with parameters is:

%*DEFINE (macro-name(parameter-list)) (macro-body)

The parameter-list is a list of identifiers separated by macro delimiters. Theidentifier for each parameter must be unique.

Typically, the macro delimiters are parentheses and commas. When using thesedelimiters, you would enclose the parameter-list in parentheses and separate eachformal parameter with a comma. When you define a macro using parentheses andcommas as delimiters, you must use those same delimiters, when you call thatmacro.

The macro-body must be a balanced-text string. To indicate the locations ofparameter replacement, place the parameter’s name preceded by the metacharacterin the macro-body. The parameters may be used any number of times and in anyorder within the macro-body. If a macro has the same name as one of theparameters, the macro cannot be called within the macro-body since this wouldlead to infinite recursion.

The example below shows the definition of a macro with three dummy parameters- SOURCE, DESTINATION, and COUNT. The macro will produce code to copyany number of bytes from one part of memory to another.

%*DEFINE (BMOVE (src, dst, cnt)) LOCAL lab ( MOV R2,#%cnt


5

MOV R1,#%src MOV R0,#%dst%lab: MOVB [R0+],[R1] ADD R1,#1 CMPD1 R2,#0 JMP CC_NZ, %lab)

To call the above macro, you must use the metacharacter followed by the macro’sname similar to simple macros without parameters. However, a list of the actualparameters must follow. The actual parameters must be surrounded in the macrodefinition. The actual parameters must be balanced-text and may optionallycontain calls to other macros. A simple call to the macro defined above might be(look at line 11):

DOS MACRO ASSEMBLER A166 V3.0OBJECT MODULE PLACED IN X.OBJASSEMBLER INVOKED BY: D:\A166\A166.EXE X.A66 GENONLYLOC OBJ LINE SOURCE

1 ;%*DEFINE (BMOVE (src, dst, cnt)) LOCAL lab ( 2 ; MOV R2,#%cnt 3 ; MOV R1,#%src 4 ; MOV R0,#%dst 5 ;%lab: MOVB [R0+],[R1] 6 ; ADD R1,#1 7 ; CMPD1 R2,#0 8 ; JMP CC_NZ,%lab 9 ;) 10 11 ; invoke macro 'BMOVE' with 3 actual parameters: 12 ;%BMOVE (array1, array2,10) 13 14 MOV R2,#10 15 MOV R1,#array1 16 MOV R0,# array2 17 LAB0: MOVB [R0+],[R1] 18 ADD R1,#1 19 CMPD1 R2,#0 20 JMP CC_NZ,LAB0

The example shows an assembled file containing a macro definition in lines 1 to 9.The macro definition shows semicolons at start of each line. These semicolons areadded by the assembler to prevent assembly of the definition text which ismeaningful to the macro preprocessor, but not to the remaining assembler phases.The listing will not include macro definitions or macro calls, if the general controlNOGEN (which is the default if none is given), is used.

The macro BMOVE is called in line 12 with three actual parameters. Lines 14 to20 shows the macro expansion, which is the return value of the macro call. Thistext will be assembled.


5

The example will produce assembly errors because no section directives areincluded in the source file. The purpose here is to show macro processing, not theassembler semantics.

Local Symbols List

The JMP CC_NZ instruction in the previous example uses a local label for targetof the branch. If a fixed label name is used (for example xlab, without leading %)then activation of the macro a second time would cause assembly errors due tomultiple definitions of a single name.

The solution to this problem are local symbols. Local symbols are generated bythe macro processor as ‘local_symbol_nnn’, where local_symbol is the name ofthe local symbol and nnn is some number. Each time the macro is called, thenumber will be automatically incremented, the resulting names will be unique oneach macro call.

The macro processor increments a counter each time your program calls a macrothat uses the LOCAL construct. The counter is incremented once for each symbolin the LOCAL list. Symbols in the LOCAL list, when used in the macro-body,receive a one to five digit suffix that is the decimal value of the counter. The firsttime you call a macro that uses the LOCAL construct, the suffix is ‘0’.

The syntax for the LOCAL construct in the DEFINE functions is shown below(this is finally the complete syntax for the macro processor function DEFINE):

%*DEFINE (macro-name (parameter-list)) [LOCAL local-list] (macro-body)

The local-list is a list of valid macro identifiers separated by spaces or commas.The LOCAL construct in a macro has no affect on the syntax of a macro call.

Macro Processor FunctionsThe macro processor has several predefined macro processor functions. Thesemacro processor functions perform many useful operations that would be difficultor impossible to produce in a user-defined macro. An important differencebetween a user-defined macro and a macro processor function is that user-definedmacros may be redefined, while macro processor functions can not be redefined.


5

We have already seen one of these macro processor functions, DEFINE. DEFINEcreates user defined macros. Macro processor functions are already defined whenthe macro processor is started.

Comment Function

The macro processing language can be very subtle, and the operation of macroswritten in a straightforward manner may not be immediately obvious. Therefore,it is often necessary to comment macro definitions. The comment function has thefollowing syntax:

� %‘text’

� %‘text end-of-line

The comment function always evaluates to the null string. Two terminatingcharacters are recognized, the apostrophe and the end-of-line character. Thesecond form allows to spread macro definitions over several lines, while avoidingunwanted end-of-lines in the return value. In either form of the comment function,the text or comment is not evaluated for macro calls.

Examples:%'this is macro comment.' ; this is an assembler comment.

%'the complete line including end-of-line is a comment

Source text before macro processing:MOV R5, R15 %'the following line will be kept separate'MOV R1, %'this comment eats the newline characterR12

Resulting output text from macro processor:MOV R5, R15MOV R1, R12

Escape Function

Sometimes it is required to prevent the macro processor from processing macrotext. Two macro processor functions perform this operation:

� escape function


5

� bracket function

The escape function interrupts scanning of macro text. The syntax of the escapefunction is:

%n text-n-characters-long

The metacharacter followed by a single decimal digit specifies the number ofcharacters (maximum is 9) shall not be evaluated. The escape function is usefulfor inserting a metacharacter (normally the % character), a comma, or aparenthesis.

Examples:10%1% OF 10 = 1; expands to: 10% OF 10 = 1;ASM%0166 expands to: ASM166

Bracket Function

The other macro processor function that inhibits the processing of macro text isthe bracket function. The syntax of the bracket function is:

%(balanced-text)

The bracket function disables all macro processing of the text contained within theparentheses. However, the escape function, the comment function, and parametersubstitution are still recognized.

Since there is no restriction for the length of the text within the bracket function, itis usually easier to use than the escape function.

Examples:ASM%(166) evaluates to: ASM166%(1,2,3,4,5) evaluates to: 1,2,3,4,5

Macro definition of ‘DW’:%*DEFINE (DW (LIST, LABEL)) (%LABEL: DW %LIST)

Macro call to ‘DW’:%DW (%(120, 121, 122, 123, -1), TABLE)

return value of the macro call to ‘DW’:TABLE: DW 120, 121, 122, 123, -1


5

The macro above will add word definitions to the source file. It uses twoparameters: one for the word expression list and one for the label name. Withoutthe bracket function it would not be possible to pass more than one expression inthe list, since the first comma would be interpreted as the delimiter separating theactual parameters to the macro. The bracket function used in the macro callprevents the expression list (120, 121, 122, 123, -1) from being evaluated asseparate parameters.

METACHAR Function

The macro processor function METACHAR allows the programmer to change thecharacter that will be recognized by the macro processor as the metacharacter.The use of this function requires extreme care.

The syntax of the METACHAR function is:

%METACHAR (balanced_text)

The first character of the balanced text is taken to be the new value of themetachar. The characters @, (, ), *, blank, tab, and identifier-characters are notallowed to be the metacharacter.

Example:%METACHAR (!) ; change metacharacter to '!'!(1,2,3,4) ; bracket function invoked with !

Numbers and Expressions

Balanced text strings appearing in certain places in built-in macro processorfunctions are interpreted as numeric expressions:

� the argument to evaluate function ‘EVAL’

� the argument to the flow of control functions ‘IF’, ‘WHILE’, ‘REPEAT’, and‘SUBSTR’.

Expressions are processed as follows:

� The text of the numeric expression will be expanded in the ordinary manner ofevaluating an argument to a macro function.


5

� The resulting string is evaluated to both a numeric and characterrepresentation of the expressions result. The return value is the characterrepresentation.

The following operators are allowed (shown in order of precedence):

♦ Parenthesized Expressions

♦ HIGH, LOW

♦ *, /, MOD, SHL, SHR

♦ EQ, LT, LE, GT, GE, NE

♦ NOT

♦ AND, OR, XOR

The arithmetic is done using signed 16-bit integers. The result of the relationaloperators is either 0 (FALSE) or 1 (TRUE).

Numbers:

Numbers can be specified in hexadecimal (base 16), decimal (base 10), octal (base8) and binary (base 2). A number without an explicit base is interpreted asdecimal, this being the default representation. The first character of a number mustalways be a digit between 0 and 9. Hexadecimal numbers which do not have adigit as the first character must have a 0 placed in front of them.

Base Suffix Valid Characters Examples

Hexadecimal H,h 0-9, A-F, a-f 1234H 99H 123H 0A0F0H 0FFH

Decimal D,d 0-9 1234 65590D 20d 123

Octal O,o,Q,q 0-7 177O 7777o 25O 123o 177777O

Binary B,b 0-1 1111B 10011111B 101010101B

Hexadecimal numbers must be preceded with a 0, if the first digit is in range A to F.

Dollar ($) signs can be placed within the numbers to make them more readable.However a $ sign is not allowed to be the first or last character of a number andwill not be interpreted.

1111$0000$1010$0011B - is equivalent to - 1111000010100011B1$2$3$4 - is equivalent to -1234

Hexadecimal numbers may be also entered using the convention from the Clanguage:


5

0xFE02 0x12340X5566 0x0A

Character Strings

The macro processor allows the use of ASCII characters strings in expressions.An expression is permitted to have a string consisting of one or two charactersenclosed in single quote characters (’).

‘A’ evaluates to 0041H‘AB’ evaluates to 4142H‘a’ evaluates to 0061H‘ab’ evaluates to 6162H‘’ the null string is not valid!‘abc’ ERROR due to more than two characters

The macro processor cannot access the assembler’s symbol table. The values oflabels, SET and EQU symbols are not known during macro processing. But, theprogrammer can define macro-time symbols with the macro processor function‘SET’.

SET Function

The macro processor function SET permits you to define macro-time symbols.SET takes two arguments: a valid identifier, and a numeric expression.

The syntax of the SET function is:

%SET (identifier,expression)

SET assigns the value of the numeric expression to the identifier.

The SET function affects the macro processor symbol table only. Symbolsdefined by SET can be redefined with a second SET function call, or defined as amacro with DEFINE.

Examples of the SET function:

Source text:%SET (CNT, 3)%SET (OFS, 16)MOV R1,#%CNT+%OFS


5

%SET (OFS, %OFS + 10)OFS = %OFS

Expanded output text:MOV R1,#3+16OFS = 26

The SET symbol may be used in the expression that defines its own value:

Source text:%SET (CNT, 10) %' define variable CNT'%SET (OFS, 20) %' define variable OFS'

%' change values for CNT and OFS:'

%SET (CNT, %CNT+%OFS) %' CNT = 30'%SET (OFS, %OFS * 2) %' OFS = 40'MOV R2,#%CNT + %OFS %' 70'MOV R5,#%CNT %' 30'

Expanded output text:MOV R2,#30 + 40MOV R5,#30

EVAL Function

The macro processor function EVAL accepts an expression as an argument andreturns the decimal character representation of its result.

The syntax of the EVAL function is:

%EVAL (expression)

The expression arguments must be a legal expression with already defined macroidentifiers, if any.

Examples:

Source text:%SET (CNT, 10) %' define variable CNT'%SET (OFS, 20) %' define variable OFS'

MOV R15,#%EVAL (%CNT+1)MOV R14,#%EVAL (14+15*200)MOV R13,#%EVAL (-(%CNT + %OFS - 1))MOV RL2,#%EVAL (%OFS LE %CNT)MOV RL7,#%EVAL (%OFS GE %CNT)


5

Expanded output text:MOV R15,#11MOV R14,#3014MOV R13,#-29MOV RL2,#0MOV RL7,#1

Logical Expressions and String Comparison

The following macro processor functions compare two balanced-text stringarguments and return a logical value based on that comparison. If the functionevaluates to ‘TRUE,’ then it returns ‘1’. If the function evaluates to ‘FALSE,’then it returns ‘0’. The list of string comparison functions below shows the syntaxand describes the type of comparison made for each. Both arguments to thesefunction may contain macro calls. (This macro calls are expanded before thecomparison is made).

%EQS (arg1,arg2)True if both arguments are identical

%NES (arg1,arg2)True if arguments are different in any way

%LTS (arg1,arg2) True if first argument has a lower value than secondargument

%LES (arg1,arg2)True if first argument has a lower value than secondargument or if both arguments are identical

%GTS (arg1,arg2)True if first argument has a higher value than secondargument

%GES (arg1,arg2)True if first argument has a higher value than secondargument or if both arguments are identical

Examples:%EQS (A166, A166) 0 (FALSE), the space after the comma is part of the second argument

%LTS (A166,a166) 1 (TRUE), the lower case characters have a higher ASCII value than upper case

%GTS (10,16) 0 (FALSE), these macros compare strings not numerical values. ASCII '6' is greater than ASCII '1'

%GES (a166,a166 ) 0 (FALSE), the space at the end of the second argument makes the second argument greater


5

than the first

%*DEFINE (VAR1) (A166)%*DEFINE (VAR2) (%VAR1)%EQS (%VAR1,%VAR2) 1 (TRUE), expands to: %EQS(A166,A166)

Conditional Macro ProcessingSome macro processor functions accept logical expressions as arguments. Themacro processor uses the value 1 and 0 to determine TRUE or FALSE. If thevalue is one, then the expression is TRUE. If the value is zero, then the expressionis FALSE.

Typically, you will use either the relational operators (EQ, NE, LE, LT, GT, orGE) or the string comparison functions (EQS, NES, LES, LTS, GTS, or GES) tospecify a logical value.

IF Function

The IF macro processor function evaluates a logical expression, and based on thatexpression, expands or skips its text arguments. The syntax of the macroprocessor function IF is:

%IF (expression) THEN (balanced-text1) [ ELSE (balanced-text2)] FI

IF first evaluates the expression, if it is TRUE, then balanced-text1 is expanded; ifit is FALSE and the optional ELSE clause is included, then balanced-text2 isexpanded. If it is FALSE and the ELSE clause is not included, the IF call returnsa null string. FI must be included to terminate the call.

IF calls can be nested; when they are, the ELSE clause refers to the most recent IFcall that is still open (not terminated by FI). FI terminates the most recent IF callthat is still open.

Example:

Source text:%*DEFINE (ADDSUB (op,p1,p2)) ( %IF (%EQS (%op,ADD)) THEN ( ADD %p1,%p2 ) ELSE (%IF (%EQS (%op,SUB)) THEN ( SUB %p1,%p2 ) FI ) FI)


5

%ADDSUB (ADD,R15,R3) %' generate ADD R15,R3'%ADDSUB (SUB,R15,R9) %' generate SUB R15,R9'%ADDSUB (MUL,R15,R4) %' generates nothing !'

Expanded output text:ADD R15,R3SUB R15,R9

WHILE Function

Often you may wish to perform macro operations until a certain condition is met.The macro processor function WHILE provides this facility.

The syntax for the macro processor function WHILE is:

%WHILE (expression) (balanced-text)

WHILE first evaluates the expression. If it is TRUE, then the balanced-text isexpanded; otherwise, it is not. Once the balanced-text has been expanded, thelogical argument is re-tested and if it is still TRUE, then the balanced-text is againexpanded. This loop continues until the logical argument proves FALSE.

Since the macro continues processing until expression evaluates to FALSE, thebalanced-text should modify the expression, or the WHILE may never terminate.

A call to the macro processor function EXIT will always terminate a WHILEfunction. EXIT is described later.

Example:

Source text:%SET (count, 5) %'initialize count to 5'%WHILE (%count GT 0)( ADD R15,R15 %SET (count, %count - 1))

Expanded output text:ADD R15,R15ADD R15,R15ADD R15,R15ADD R15,R15ADD R15,R15


5

REPEAT Function

The macro processor function REPEAT expands its balanced-text a specifiednumber of times. The syntax for the macro processor function REPEAT is:

%REPEAT (expression) (balanced-test)

REPEAT uses the expression for a numerical value that specifies the number oftimes the balanced-text will be expanded. The expression is evaluated once whenthe macro is first called, then the specified number of iterations is performed.

Examples:

Source text:%REPEAT (5)( -enter any key to shut down-)

%REPEAT (5) (+%REPEAT (9) (-))+

Expanded output text: -enter any key to shut down- -enter any key to shut down- -enter any key to shut down- -enter any key to shut down- -enter any key to shut down- +---------+---------+---------+---------+---------+

EXIT Function

The EXIT macro processor function terminates expansion of the most recentlycalled REPEAT, WHILE or user-defined macro function. It is most commonlyused to avoid infinite loops (example: a WHILE that never becomes FALSE, or arecursive user-defined macro that never terminates). It allows several exit pointsin the same macro.

The syntax for the macro processor function EXIT is:

%EXIT

Example:

Source text:%SET (count, 0)

%WHILE (1)


5

(%IF (%count GT 5) THEN (%EXIT) FI DW %count, -%count%SET (count, %count + 1))

Expanded output text:DW 0, -0DW 1, -1DW 2, -2DW 3, -3DW 4, -4DW 5, -5

String Manipulation FunctionsThe purpose of the Macro Processor is to manipulate character strings. Therefore,there are several macro processor functions that perform common character stringmanipulations.

LEN Function

The macro processor function LEN returns the length of the character stringargument in hexadecimal: The character string is limited to 256 characters.

The syntax for the macro processor function LEN is:

%LEN (balanced-text)

Examples:

Source text:%LEN (A166) %' len = 4'%LEN (A166,A166) %' comma counts also'%LEN ()%LEN (ABCDEFGHIJKLMNOPQRSTUVWXYZ)%DEFINE (TEXT) (QUEEN)%DEFINE (LENGTH) (%LEN (%TEXT))LENGTH OF '%TEXT' = %LENGTH.

Expanded output text:49026LENGTH OF 'QUEEN' = 5.


5

SUBSTR Function

The macro processor function SUBSTR returns a substring of the given textargument. The function takes three arguments: a character string to be divided andtwo numeric arguments.

The syntax for the macro processor function SUBSTR is:

%SUBSTR (balanced-text,expression1,expression2)

balanced-text is any text argument, possibly containing macro calls. Expression1specifies the starting character of the substring. Expression2 specifies the numberof characters to be included in the substring.

If expression1 is zero or greater than the length of the argument string, thenSUBSTR returns the null string. The index of the first character of the balancedtext is one.

If expression2 is zero, then SUBSTR returns the null string. If expression2 isgreater than the remaining length or the string, then all characters from the startcharacter to the end of the string are included.

Examples:

Source text:%DEFINE (STRING) (abcdefgh)%SUBSTR (%string, 1, 2)%SUBSTR (%(1,2,3,4,5), 3, 20)

Expanded output text:ab2,3,4,5

MATCH Function

The macro processor function MATCH searches a character string for a delimitercharacter, and assigns the sub-strings on either side of the delimiter to theidentifiers.

The syntax for the macro processor function MATCH is:

%MATCH (identifier1 delimiter identifier2) (balanced-text)


5

Identifier1 and identifier2 must be valid macro identifiers. Delimiter is the firstcharacter to follow identifier1. Typically, a space or comma is used, but anycharacter that is not a macro identifier character may be used. Balanced-text is thetext searched by the MATCH function. It may contain macro calls.

MATCH searches the balanced-text string for the specified delimiter. When thedelimiter is found, then all characters to the left are assigned to identifier1 and allcharacters to the right are assigned to identifier2. If the delimiter is not found, theentire balanced-text string is assigned to identifier1 and the null string is assignedto identifier2.

Example:

Source text:%DEFINE (text) (-1,-2,-3,-4,-5)%MATCH (next,list) (%text)%WHILE (%LEN (%next) NE 0)( MOV R8,#%next MOV [R1+],R8 %MATCH(next,list)(%list))

Expanded output text:MOV R8,#-1MOV [R1+],R8MOV R8,#-2MOV [R1+],R8MOV R8,#-3MOV [R1+],R8MOV R8,#-4MOV [R1+],R8MOV R8,#-5MOV [R1+],R8

Console I/O FunctionsThere are two macro processor functions that perform console I/O: IN and OUT.Their names describe the function each performs. IN outputs a character ‘>‘ as aprompt, and returns the line typed at the console. OUT outputs a string to theconsole; a call to OUT is replaced by the null string.

The syntax for the macro processor functions IN an OUT is:

%IN

%OUT (balanced-text)


5

Examples:

Source text:%OUT (enter baud rate)%set (BAUD_RATE,%in)BAUD_RATE = %BAUD_RATE

Expanded output text:<19200 was entered at the console>BAUD_RATE = 19200

Advanced Macro ProcessingThe macro definition function associates an identifier with a functional string.The macro may or may not have an associated pattern consisting of parametersand/or delimiters. Also optionally present are local symbols. The syntax for amacro definition is:

%DEFINE (macro_id define_pattern) [LOCAL id_list] (balanced_text)

The define_pattern is a balanced string which is further analyzed by the macroprocessor as follows:

define_pattern = { [parm_id] [delimiter_specifier] }

Delimiter_specifier is one of the following:

� some string not containing non-literal id-continuation. logical blank orcharacter @.

� @delimiter_id

The macro call must have a call pattern which corresponds to the macro definepattern. Regardless of the type of delimiter used to define a macro, once it hasbeen defined, only delimiters used in the definition can be used in the macro call.Macros defined with parentheses and commas require parentheses and commas inthe macro call. Macros defined with spaces or any other delimiter require thatdelimiter when called.

The define pattern may have three kinds of delimiters: implied blank delimiters,identifier delimiters and literal delimiters.


5

Literal Delimiters

The delimiters used in user-defined macros (parentheses and commas) are literaldelimiters. A literal delimiter can be any character except the metacharacter.

When you define a macro using a literal delimiter, you must use exactly thatdelimiter when you call the macro. If the specified delimiter is not used as itappears in the definition, a macro error occurs.

When defining a macro, the delimiter string must be literalized, if the delimitermeets any of the following conditions:

� more than one character,

� a macro identifier character (A-Z, 0-9, _, or ?),

� a commercial at (@), a space, tab, carriage return, or linefeed.

Use the escape function (%n) or the bracket function (%()) to literalize thedelimiter string.

This is the simple form shown earlier:

Before Macro Expansion After Macro Expansion

%*DEFINE(MAC(A,B))(%A %B) null string

%MAC(4,5) 4 5

In the following example brackets are used instead of parentheses. Thecommercial at symbol separates parameters:


%*DEFINE (MOV[A%(@)B]) (MOV %A,%B) null string

%MOV[P0@P1] MOV P0,P1

In the next two examples, delimiters that could be id delimiters have been definedas literal delimiter (the differences are noted):


%*DEFINE(ADD (R10 AND B)) (ADD R10,%B) null string

%ADD (R10 AND #27H) ADD R10,#27H


5

Spaces around AND are considered part of the argument string.

Blank Delimiters

Blank delimiters are the easiest to use. Blank delimiter is one or more spaces, tabsor new lines (a carriage-return/linefeed pair) in any order. To define a macro thatuses the blank delimiter, simply place one or more spaces, tabs, or new linessurrounding the parameter list.

When the macro defined with the blank delimiter is called, each delimiter willmatch a series of spaces, tabs, or new lines. Each parameter in the call begins withthe first non-blank character, and ends when a blank character is found.

Example source text:%*DEFINE (X1 X2 X3) (P2=%X2, P3=%X3)%X1 assembler A166

Example output text:P2=assembler, P3=A166

Identifier Delimiters

Identifier delimiters are legal macro identifiers designated as delimiters. To definea macro that uses an identifier delimiter, you must prefix the delimiter with the @symbol. You must separate the identifier delimiter from the macro identifiers(formal parameters or macro name) by a blank character.

When calling a macro defined with identifier delimiters, a blank delimiter isrequired to precede the identifier delimiter, but none is required to follow theidentifier delimiter.

Example source text:%*DEFINE (ADD X1 @TO X2 @STORE X3)( MOV R1,%X1 MOV R2,%X2 ADD R1,R2 MOV %X3,R1)%ADD VAR1 TO VAR2 STORE VAR3


5

Example output text:MOV R1,VAR1MOV R2,VAR2ADD R1,R2MOV VAR3,R1

Literal and Normal Mode

In normal mode, the macro processor scans for the meta character. If it is found,parameters are substituted and macros are expanded. This is the usual operationof the macro processor.

When the literal character (*) is placed in a DEFINE function, the macroprocessor shifts to literal mode while expanding the macro. The effect is similar tosurrounding the entire call with the bracket function. Parameters to the literalizedcall are expanded, the escape, comment, and bracket functions are also expanded,but no further processing is performed. If there are any calls to other macros, theyare not expanded.

If there are no parameters in the macro being defined, the DEFINE function can becalled without literal character. If the macro uses parameters, the macro processorwill attempt to evaluate the formal parameters in the macro-body as parameterlessmacro calls.

The following example illustrates the difference between defining a macro in literalmode and normal mode:

%SET (TOM, 1)%*DEFINE (AB) (%EVAL (%TOM))%DEFINE (CD) (%EVAL (%TOM))

When AB and CD are defined, TOM is equal to 1. The macro body of AB hasnot been evaluated due to the literal character, but the macro body of CD has beencompletely evaluated, since the literal character is not used in the definition.Changing the value of TOM has no effect on CD, but it changes the value of AB:

%SET (TOM,2) -> null string%AB -> 2%CD -> 1

%*CD -> 1%*AB -> %EVAL (%TOM)


5

MACRO ErrorsThe macro processor will output error messages, if errors occur in the macroprocessing phase. The errors are displayed like other assembly errors in the listingfile which is generated by the assembler anyway. The following describes theerror messages generated by the macro processor.

Error Error Message and Description

80 PREMATURE END OF FILEThe end of the source module was reached while processing some macro call, whichrequires more input from the source file.

81 '<token>' IDENTIFIER EXPECTEDThe macro processor expected an identifier while processing some macro. None was found.The unexpected token is displayed with this error message.

82 MPL FUNCTION '<name>': '<character>' EXPECTEDThe context of the macro processor language requires a specific character from the inputgiven by <character> while processing the built-in function given by <name>.]

83 <string>: UNBALANCED PARENTHESESA balanced string requires the same number of right parentheses and left parentheses.

84 EXPECTED '<token>'The syntax requires a specific token to follow, for example THEN after the balanced textargument to IF.

85 INCOMPLETE MACRO DEFINITIONThe macro definition has not been completely processed due to premature end of input file.

86 FUNCTION 'MATCH': ILLEGAL CALL PATTERNThe built-in function MATCH was called with an illegal call pattern. The call pattern mustconsist of some formal name followed by a delimiter specification and another formal name.

87 FUNCTION 'EXIT' IN BAD CONTEXTThe built-in function EXIT is allowed only in WHILE and REPEAT constructs.

88 ILLEGAL METACHARACTER '<character>'The first character of the balanced text argument to METACHAR is taken to be the newvalue of the meta character. The characters @, (, ), *, blank, tab, and identifier-charactersare not allowed to be the meta character.

89 CALL PATTERN - DELIMITER '<delimiter>' NOT FOUNDThe call pattern of some macro does not conform to the define pattern of that macro. Thedelimiters of the macro call should be checked for conformance.

90 CALL TO UNDEFINED MACRO '<name>'The macro call specifies the name of an undefined macro.

91 INVALID MPL COMMAND '%<character>'The character following the meta character does not form a valid macro processor languagecommand.

92 INVALID DIGIT '<character>' IN NUMBERA number of an expression contains an invalid digit.

9394

UNCLOSED STRING OR CHARACTER CONSTANTINVALID STRING OR CHARACTER CONSTANTThe string representing a number in an expression is invalid. The string must be either oneor two characters long. A character constant must not be longer than one character. Stringsor character constants must be enclosed by single or double quotes.


5


95 UNKNOWN EXPRESSION IDENTIFIERThe identifier within some expression is not an operator or a number.

96 <character>: INVALID EXPRESSION TOKENThe given character does not form a valid operator or an identifier operator.

97 DIV/MOD BY ZEROA division or modulo by zero error occurred while evaluating an expression.

98 EVAL: SYNTAX ERROR IN EXPRESSIONThe expression to be evaluated contains a syntax error, for example two consecutive number,not separated by an operator.

99 CAN'T OPEN FILE '<file>'The file specified in the INCLUDE directive could not be opened.

100 '<file>' IS NOT A DISK FILEThe file name given in the INCLUDE directive does not specify a disk file. Files other thandisk files are not allowed (example: CON).

101 ERROR IN INCLUDE/INCDIR DIRECTIVEThe INCLUDE directive is ill-formed. The argument to INCLUDE must be the name of somefile, enclosed in parentheses.

102 CAN’T REDEFINE PREDEFINED MACRO ‘macroname’Predefined macros such as SET can’t be redefined.


6

Chapter 6. Error MessagesAll errors recognized by the A166 assembler cause error messages to be printed inthe listing file. A166 decides two classes for errors:

Fatal Errors:

Fatal errors are for example errors encountered on the invocation of the assembler.These errors cause a message to be issued at the console. The assembler run isthen terminated immediately.

Non-Fatal Errors:

Non-fatal errors are syntax or semantic errors in the source file. An error messageis issued in the listing file. The assembler continues assembling the source file.

Fatal ErrorsFatal errors usually occur in the invocation line. Another cause can be that thenesting of input files is greater than the maximum allowed. In this case a messagehaving one of the following formats is printed at the screen:

A166 FATAL ERROR - ACTION: <current action> FILE: <filename in which the error occurs> ERROR: <error message with description> A166 TERMINATED.

A166 FATAL ERROR - ACTION: <current action> PARAMETER: <e.g. an illegal option> ERROR: <error message with description> A166 TERMINATED.

A166 FATAL ERROR - ERROR: <error message with description> A166 TERMINATED.

ACTION can be one of the following:

� ATTACH FILE. The selected source file was not found.

� PARSING COMMAND LINE. An unknown option, or an illegal argumentwas input at the invocation line.

� PARSING ‘$’-CONTROL LINE. A control statement in the source code isunknown or an illegal argument was input.

132 Chapter 6. Error Messages

6

FILE is the file that could not be opened. The message ‘FILE’ is output if theerror occurred due to a file.

PARAMETER is an unknown option or an illegal argument for a legal option.The ‘PARAMETER’ field is output when the error occurred due to a controlstatement.

ERROR is one of the following errors:

� LIMIT EXCEEDED: LINE TOO LONG (500)An input source line contains more than 500 characters. The assembly run isaborted.

� ERRORPRINT- AND LIST-FILE CANNOT BE THE SAMEIt is illegal to direct the listing file output and the error output to the console atthe same time. The assembly run is aborted.

� NON-NULL ARGUMENT EXPECTEDIn the invocation line the name of the file to be translated or a filename to anoption was left out. The assembly run is aborted.

� CONFLICTING CONTROLAn option of the invocation line conflicts with another option. This occurs ife.g. the controls ‘NOOBJECT’ and ‘OBJECT(xxx)’ are specified in theinvocation line.

� CANNOT HAVE GENERAL CONTROL IN INVOCATIONSome controls are only allowed in the source text but not in the invocationline. Following controls are not allowed in the invocation line: INCLUDE, IF,ELSEIF, ELSE, ENDIF and EJECT.

� EXPECTED DELIMITER ‘(’ AFTER CONTROLThe argument of an option must be enclosed by a left parenthesis.

� EXPECTED DELIMITER ‘)’ AFTER ARGUMENTThe argument of an option must be enclosed by a right parenthesis.

� UNKNOWN CONTROLThe control directive is unknown and therefore illegal.

� BAD NUMERIC CONSTANTThe numerical argument to an option contains illegal characters. Numericalparameters can be specified in decimal or hexadecimal and must start with anumber between 0 and 9. Hexadecimal numbers are specified by a trailing‘H’, e.g. VAR1=0FFFEH, VAR2=55H).


6

� OUT OF RANGE NUMERIC VALUEA numerical argument to an option is out of range. This occurs e.g. when thePAGEWIDTH option has an argument lower than 78 or higher than 132.

� LIMIT EXCEEDED: SYMBOL-TABLE SPACE EXHAUSTEDThe symbol-table space has been exhausted and cannot take any moresymbols. The assembly run is aborted. The symbol table can accommodate afixed amount of 6000 symbols, independent of the length of the symbols.

� LIMIT EXCEEDED: MORE THAN 100 ‘SET’ VARIABLESThe number of $SET variables must not exceed 100.

� INVOCATION LINE TOO LONG (500)The total number of characters in the invocation line may not exceed 500characters. It is not possible under DOS to have more than 122 characters butwhen using the SHELL.

� IDENTIFIER EXPECTEDThe control directive expected some identifier but something else wasencountered.

� MEMORY SPACE EXHAUSTEDThere is no more memory available. This error may occur when allocatingspace for a symbol or when using XREF with very large modules containing alot of symbols each with a lot of uses.

� CAN’T OPEN FILEThe specified file can’t be opened for read access.

� CAN’T CREATE FILEThe specified file can’t be opened for write access.

� CAN’T CLOSE FILEThe disk file cannot be closed for some reason.

� FILE WRITE ERRORThe specified file cannot be written to, due to a probably full disk.

� ATTEMPT TO SHARE FILEAn attempt was made to open a file for both reading and writing. This occurse.g. if the name of an INCLUDE file is the same as that of the object file.

� DISK FILE REQUIREDThe specified file is not the name a disk file.

� LIMIT EXCEEDED: INCLUDE FILE NESTING (9)The nesting of include files caused a violation of the maximum depth of nine.


6

� LIMIT EXCEEDED: INPUT FILE OR MACRO STACK OVERFLOWThe nesting of input files and macros exceeded an internal limit.

� LIMIT EXCEEDED: BALANCED TEXT LENGTH (2045)The internal limit of the balanced text length of the macro preprocessor hasbeen violated. Expansions and intermediate expansions may not producestrings longer than 2045 characters.

Non-Fatal ErrorsNon-fatal errors are encountered within the source code. They are usually syntaxerrors, for example undefined symbols are used or the arguments of a particular166/167 machine instruction are illegal. The A166 assembler prints the errors inthe listing file as follows:

DOS MACRO ASSEMBLER A166 V3.0OBJECT MODULE PLACED IN X.OBJASSEMBLER INVOKED BY: D:\A166\A166.EXE X.A66

LOC OBJ LINE SOURCE 1 2 C100 SECTION CODE 3 P100 PROC NEAR 4 MOV R1,#12A0*** ____________________________________________^*** ERROR #1, LINE #4, ILLEGAL CHARACTER IN NUMERIC CONSTANT 5 MOV R0,#25 *, 10*** ______________________________________________^*** ERROR #6, LINE #5, SYNTAX ERROR 6 P100 ENDP 7 C100 ENDS*** ERROR #89, LINE #7, PREMATURE END OF FILE (NO END STATEMENT)

Most of the errors are indicated by an up arrow character to the first incorrectcharacter encountered. It is also possible that the position indicated is due to aprevious error, because a previous error has given the following arguments adifferent meaning.

If a source line contains more errors then the position indications are displayed insubsequent lines. With more than five errors in a row, the first five errors aredisplayed as usual. Additionally the following message may appears:

*** MORE ERRORS DETECTED, NOT REPORTED.


6


1 I LLEGAL CHARACTER IN NUMERIC CONSTANTNumerical constants must begin with a decimal digit. Within these digits $-signs are allowedfor easier reading. Error 1 occurs if after the $-sign no valid digit is encountered or someother invalid numeric character was found. The base of the number decides which numbersare valid:

� Base 2: 0, 1, and the base indicator B

� Base 8: 0-7 and the base indicator O or Q

� Base 10: 0-9 and the base indicator D or no indicator

� Base 16: 0-9, A-F, and the base indicator H

2 MISSING STRING TERMINATORIn a character string a the second string terminator was left out, the string was ended by acarriage return (CR).

3 I LLEGAL CHARACTERA character not contained in the set of valid A166 characters was encountered.

4 I LLEGAL USE OF A RESERVED WORDThis error occurs, if for example a reserved word is used for the name of a label.

5 SYMBOL OR LABEL REDEFINITIONA label or symbol cannot be defined more than one time in a source program.

6 SYNTAX ERRORThis error indicates that the marked token is not expected in this context.

7 RESPECIFIED PRIMARY CONTROL, LINE IGNOREDA primary control (in a $ line) was repeated or conflicted. The control was ignored. Thecontrols first specified remain valid.

8 MISPLACED PRIMARY CONTROL, LINE IGNOREDA primary control was misplaced. Primary controls may be entered in the invocation line or atthe beginning of the source file (as $ control lines). Processing of primary controls isterminated, if source lines are encountered, which contain A166 directives. An exception tothis are empty lines or pure comment lines.

9 CONFLICTING CONTROLThe given control directive conflicts to some other previously given control, e.g.SEGMENTED, and NONSEGMENTED.

10 MISPLACED CONDITIONAL CONTROLThe given control directive (ELSE, ELSEIF, ENDIF) is encountered in illegal context. Thedirectives ELSEIF, ELSE and ENDIF must be preceded by an IF directive.

11 BAD CONDITIONAL EXPRESSIONThe expression to the IF or ELSEIF directive is incorrect. These expressions must beabsolute and may not contain relocatable symbols. When using $IF and $ELSEIF, only the$SET- and $RESET symbols can be accessed.

12 UNBALANCED IF-ENDIF-CONTROLSEach IF-Block must be terminated with an ENDIF directive. This is also true on nested IFblocks since the assembler looks on these directives, even if they are skipped.

13 SAVE STACK UNDERFLOWA $RESTORE directive is valid only if a previous $SAVE directive has been performed.

14 SAVE STACK OVERFLOWThe SAVE directive me be nested up to a maximum level of 9.


6


15 EXPRESSION TOO COMPLEXThe expression is too complex due to too many operands and operators. Simplify theexpression. Typically this error occurs, if a total of more than 50 expression tokens(numbers, identifiers, operators and parentheses) are contained in an expression.

16 UNKNOWN CONTROL OR BAD ARGUMENT(S)The control directive in a control line (introduced by $) is unknown to the assembler or thearguments to the control are invalid.

17 MISPLACED ELSEIF/ELSE/ENDIF CONTROLOne of the control directives ELSEIF, ELSE or ENDIF was found in illegal context. Thesedirectives require that a previous IF section has been opened.

18 LIMIT EXCEEDED: IF-NESTING (10)The number of nested IF constructs is limited to a maximum of 10.

19 NUMERIC VALUE OUT OF RANGEThis error indicates an out of range numeric value, for example:

DSEC SECTION DATA AT 45000H ; out of address spaceDSEC ENDS

The absolute addresses for sections may not be greater than the valid address space fromthe 166/167 (256K or 0 to 3FFFFH)

20 NON NULL ARGUMENT EXPECTEDA control directive of a control line (introduced by $) expected some argument. The argumentwas missing.

21 '(' EXPECTEDAn opening parentheses was expected by context, but something other has been found.

22 ')' EXPECTEDA closing parentheses was expected by context, but something other has been found.

23 IDENTIFIER EXPECTEDAn identifier was expected by context, but something other has been found.

24 DIVISION BY ZERO ERRORA division by zero was attempted while calculating an expression. The expression isincorrect.

25 SYMBOL REDEFINITIONAn attempt was made to redefine an existing symbol. The definition was ignored.

26 MORE THAN 10 NESTED SECTIONS, SECTION IGNOREDSections may be nested up to a maximum level of 10. In case of deeper nesting, the sectionsare ignored.

27 MISPLACED DIRECTIVEThe ENDS directive was out of context. ENDS is allowed to close a previous opened sectiononly.

28 'SECTION NAME' EXPECTEDThe argument to the ENDS directive must be the name of the section previously opened.Note that sections must be closed inside out, that means, the last recent opened sectionmust be closed first.

DSEC SECTION DATA ; open DSEC XSEC SECTION DATA ; open XSEC XSEC ENDS ; close XSEC firstDSEC ENDS ; close then DSEC


6


29 UNMATCHED ENDS/ENDPA code section containing one or more procedures was closed without closing the last recentprocedure first.

30313233

REDEFINITION: 'SECTION TYPE'REDEFINITION: 'ALIGN TYPE'REDEFINITION: 'COMBINE TYPE'REDEFINITION: 'CLASS NAME'These errors will occur, if a previously defined section is reopened with different attributes.The attributes must be exactly the same or should be omitted (with the exception of 'sectiontype'). If the attributes are left out on a reopened section, then that section will automaticallyinherit the attributes from the first definition of that section.

34 ILLEGAL SECTION TYPEA member of a group has illegal section type. Code groups may contain sections of typecode only. Data groups may contain sections of type data only. Sections of type bit cannotbe member of a group.

35 'DPPn' EXPECTEDThe context indicates that the name of some data page pointer (DPP0 to DPP3) is expected,but something other was found. The situations where a DPP is required are:

� External definitions (EXTRN DPP2:var1:word)

� Assume directives (ASSUME DPP1:section_name)

The name of the DPP's are in the class of special function register names (SFR), internal tothe assembler. An error occurs, if the name of some SFR is given which is not DPP0,DPP1, DPP2 or DPP3.

36 ':' EXPECTEDA colon was expected by context, but some other token was encountered.

37 TYPE IDENTIFIER EXPECTEDThe name of a type was expected, but some other token was encountered. Type names areBIT, BYTE, WORD, DATA3 , … REGBANK .

38 'DPP': VALID ON BYTE/WORD VARIABLES ONLYAn external declaration may contain an optional DPP specification, but this is valid onexternals of type BYTE, WORD and BITWORD only.

39 ILLEGAL PUBLIC/GLOBAL SYMBOLSymbols defined by the SET directive may not receive the attribute PUBLIC or GLOBAL .The name of sections or group are also not allowed to be PUBLIC or GLOBAL .

40 USE OF '$' OUTSIDE ANY SECTIONThe use of the current location counter $ is allowed within some section only. The $ sign hasno meaning outside a section.

41 ILLEGAL STRING IN EXPRESSIONA string may be part of an expression representing a numeric value. The length of the stringmust be either one or two. Zero length strings or strings containing more than two charactersare not allowed.

42 UNDEFINED IDENTIFIERThe given identifier is undefined.

43 ILLEGAL ALIGN TYPEThe given align type of a bit section is invalid. Bit sections may have align type BIT, BYTE,WORD and DWORD. The alignment type BITADDRESSABLE is not allowed since a bitsection is always bit-addressable by definition.


6


44 NO CURRENTLY ACTIVE SECTIONSome directive (DB, DW, DSPTR, …) or an instruction line has been encountered outsideany section. Data definitions or reservations or machine instructions must always be part ofa section.

45 KEYWORD NOT ALLOWED IN CURRENT CONTEXTSome statement was encountered in an illegal context, for example: DBIT in a section otherthan a bit section or machine code in a data or bit section and so on.

46 CAN'T NEST CODE SECTIONSData sections may be nested inside data or code sections but code sections can't be nestedwithin other sections including code at all.

47 ILLEGAL TYPE FOR A LABELA label was defined using the LABEL directive and an illegal type. The valid types of labelsare BIT, BYTE, WORD, NEAR, and FAR.

48 INSUFFICIENT ALIGNMENTWord accesses are required to be on word boundaries by the 166/167 CPU. The assemblertherefore checks that the alignment requirements of word variables are ensured. In case of amis-aligned (e.g. odd addressed) word, the assembler gives a warning but does not insert abyte for alignment, this is to be done by the user.

49 MORE THAN ONE REGBANK DEFINITIONA single source module may not contain more than one REGBANK definitions.

5051

REGISTER RANGE OVERLAP'REGDEF' REGISTERS DO NOT MATCH 'USED' REGISTERSThe registers defined in a REGDEF or REGBANK directive do not match the registersactually used in the source module. The assembler recognizes all registers, which are usedin the source module. The error occurs, if the registers used in the module are a supersetfrom the registers defined per REGDEF or REGBANK .

52 INVALID REGISTER RANGEA register range specification is wrong. A register range can be specified using 'Rm-Rn'where m must be lower than n, e.g. R0 - R10. R3-R0 is illegal.

53 SECTION IS ALREADY A MEMBER OF GROUPOne section cannot be a member of different groups.

54 'ASSUME' IN NONSEGMENTED MODE IGNOREDIn NONSEGMENTED mode, DPP assumes are not required since the DPP's values are leftun-initialized or initialized once in the startup code of the application. The default values ofthe DPP's after CPU reset are: DPP0=0, DPP1=1, DPP2=2, DPP3=3. The whole applicationmust fit within the first 64K in NONSEGMENTED mode.

55 'DPP' IN NONSEGMENTED MODE IGNOREDA DPP-prefix was given to a variable in some instruction. Another cause for this error maybe a DPP specification in an external declaration. This is not necessary inNONSEGMENTED mode. See also ERROR 54 for details.

56 ILLEGAL COMPONENTThe type of section in an ASSUME directive was bit. Bit sections do not require anASSUME to take place, since the addressing method specifies the target addresses bymeans of word numbers which always map to the bit-addressable space, not using the datapage pointers at all.

57 ILLEGAL REGISTERThe register name contained in an indirect register specifier (e.g. [-R10]) is not the name of aword general purpose register R0 to R15.

58 ']' EXPECTEDThe indirect register specifier is not correct, the closing ] is missing.


6


59 '#' EXPECTEDThe indirect register specifier with an extra immediate offset is wrong. The correct form is[RWn + #immediate_value]. RWn must be one of the word registers R0 to R15.

60 ILLEGAL IDENTIFIERThe identifiers type is not allowed in the current expression context. The error occurs, if forexample the symbolic name of a LITeral string is used as argument in an expression.

61 ILLEGAL OPERAND FOR THIS OPERATORThe operand of the given operator is of incorrect type.

� HIGH/LOW:the operand must be a SFR-symbol or a bit symbol (either module internal orexternal.

� BOF:the operand must be a bit-symbol or bit-address.

An error 61 is issued if the rules above are violated.

62 VALUE TRUNCATIONThe constant operand to the operators DATA3 , DATA4 , DATA8 or DATA16 has a value toolarge to be represented by the DATAn -operator. For example DATA4 20 gives a warning,since the type DATA4 can represent values in range 0 to 15 only.

63 ILLEGAL RELOCATABLE EXPRESSIONThe expression violates the rules for relocatable expressions. The error is issued if forexample two relocatable operands are added or multiplied. Subtraction of two relocatableoperands is allowed, assumed that both operands belong to the same section whichproduces an absolute result. Addition of one relocatable operand and one absolute operandis allowed.

64 TYPE OVERRIDE HAS INVALID OPERANDThe assembler has detected an illegal operands to the type override operator. Examples tothis situation are:

� NEAR / FAR on operands which are not members of some code section.

� NEAR / FAR / BYTE / WORD on section- or group names

� BIT on non-bit operands

65 INVALID USE OF 'SHORT' OPERATORThe SHORT operator must be applied to an operand of type NEAR, which belongs to somecode section. The SHORT operator is to give the assembler a hint that some jump instructionbranches to a forward location which is guaranteed to be in range -128 / +127 words relativeto the current execution point.

66 VALUE OUT OF RANGEThe given constant value is out of range. Offsets within data sections may not be greaterthan 16383 since a data page cannot exceed 16K in length.

MOV BYTE PTR DPP3:20000,#'Z'; causes ERROR 66

67 ABSOLUTE VALUE (0-15) EXPECTED FOR BITPOSITIONThe bit-position specifier in a bit address must be an absolute value in range 0 to 15.


6


6869

INVALID BASE IN BITADDRESSNOT A BITADDRESSABLE BASEThe base in a bit address is illegal. Valid bases are as follows:

� addresses from 0FD00H to 0FDFEH

� addresses from 0FF00H to 0FFDEH

� SFRSYM.bitpos; SFRSYM must be a bit-addressable SFR

� bitaddressable_word.bitpos (word from a bit-addressable data section)

� (external bitaddressable_word).bitpos

The base of a bit address written as base.bitpos must be of type word, being located on aneven address.

70 INVALID TYPE OF EXPRESSIONThis error is issued if an addition or subtraction contains a bit operand or when a generalpurpose register is in a context where it is not allowed.

71 EXPRESSION WITH FORWARD REFERENCE NOT PERMITTEDSome directives require expressions with no forward references, that means that allcomponents of the expression must have been previously defined or must be constants.Examples to these directives are SET, EQU, and ORG.

72 ABSOLUTE EXPRESSION REQUIREDSome directives require an absolute expressions as argument. Examples of these directivesare DS, DSB, DSW, AT expression.

73 NUMBER OF OPERANDS DOES NOT MATCH INSTRUCTIONThe number of operands given to some machine instruction mnemonic does not match thenumber of operands required by that instruction.

74 ILLEGAL OPERAND TYPEThe type of the instruction does not match the requirements of that instruction, for example abit operand in a word instruction or a GPR in an expression to the DW directive.

75 CAN'T NEST PROCEDURESAn attempt was made to nest procedures. Procedure nesting is not allowed.

76 WRITE ACCESS TO 'READ ONLY' LOCATIONAn attempt was made to write to location is marked read only. An example to this is a storeto the special-function-register ZEROS, which is a read only register.

77 MISSING 'DPP' INFORMATIONAn operand of some instruction is not addressable. This occurs if in segmented mode avariable is accessed which has no corresponding data page register (DPP). Use theASSUME directive to give the assembler a hint about which DPP will hold the base of thesection which the variable is member of.

78 'FAR RETURN' IN NON FAR PROCEDUREA return instruction of type 'FAR' has been coded into a procedure of type 'NEAR' . This maycause runtime stack problems. Use the software instruction RET in order to get a return ofappropriate type.

79 'NEAR RETURN' IN NON NEAR PROCEDUREA return instruction of type 'NEAR' has been coded into a procedure of type 'FAR' . or in aninterrupt procedure (TASK) This may cause runtime stack problems. Use the softwareinstruction RET in order to get a return of appropriate type.

80 'INTERRUPT RETURN' IN NON INTERRUPT PROCEDUREA return instruction of type RETI has been coded into a non interrupt procedure. This maycause runtime stack problems and interrupt problems. Use the software instruction RET inorder to get a return of appropriate type.


6


81 ILLEGAL BRANCH TARGETThe branch target of some jump or call instruction is incorrect. For relative branches, thetarget must be of type NEAR and within the current code section. Branches of type NEARmust refer to some near label of a code section.

82 RELATIVE DISTANCE OUT OF RANGEThe branch target for relative branches (CALLR , JMPR) must be in range -128/+127 wordsrelative to the current execution point. The current execution point is the address of theinstruction following the branch.

83 'TRAP' INSTRUCTION REQUIRED TO ACTIVATE AN INTERRUPTPROCEDUREAn interrupt procedure (defined via PROC TASK ) must be activated by the TRAP instructionwhich forces a software interrupt. Activation’s by CALL are illegal and would lead to runtimestack problems.

84 NEAR REFERENCE TO FAR LOCATIONThe target of some JMP or CALL instruction of type NEAR is a label of type FAR. If this iswhat you want, use the type override (NEAR PTR, FAR PTR) to create a conforming labeltype for the instruction.

85 FAR REFERENCE TO NEAR LOCATIONThe target of some JMP or CALL instruction of type FAR is a label of type NEAR. If this iswhat you want, use the type override (NEAR PTR, FAR PTR) to create a conforming labeltype for the instruction.

86 SECTION LENGTH OVERFLOWThe actual section has exceeded its maximum length (e.g. 16K on data sections or 64K oncode sections).

87 MORE THAN ONE PECDEF/SSKDEFThe PECDEF and SSKDEF directive may be given only once in one source module.

88 ILLEGAL PEC-CHANNELThe arguments to the PEC directive must be the PEC-related identifiers PECC0 to PECC7which identify the eight PEC-channels. Other arguments are illegal.

89 PREMATURE END OF FILE (NO END STATEMENT)The source module must end with the END directive.

90 ILLEGAL ADDRESS IN NONSEGMENTED MODEThe valid 166/167 address space in NONSEGMENTED mode is 64K. The values forabsolute addresses must therefore be not greater than 0FFFFH.

91 NOT IN BITADDRESSABLE RANGE (0FD00H-0FDFFH)A bit-section or bit-addressable data section with an absolute 'AT address' is located at awrong address. The valid address range for such sections is 0FD00H to 0FDFFH. Otherareas are not bit-addressable by the 166/167 CPU.

92 ILLEGAL SIMPLE RELOCATABLE EXPRESSIONThe expression argument to an ORG directive is illegal. Such expressions must be simplerelocatable, that means it must be either absolute or may contain a relocatable symbol whichmust belong to current section.

93 NAME OF A SECTION EXPECTEDThe argument list to a GROUP directive must consist of section names or the pseudosection name SYSTEM. In case of forward references, this error will be detected in pass-2of assembly.

94 MULTIPLE DPP ASSUME FOR ONE SECTION OR GROUPIt is not allowed to ASSUME more than one DPP to one section or group.


6


95 MORE THAN ONE TASK IN ONE MODULEOne single source module may not contain more than one 'PROC TASK' definition.

96 'POF/SOF' INVALID ON GROUP NAMEThe operators POF and SOF may not be applied to group name symbols.

97 RESULT EXCEEDS BYTE PRECISIONThe result of an expression being part of a DB directive may not exceed the value 255.

98 ILLEGAL TRAP VECTORThe operand to the TRAP instruction must be of type DATA3 or DATA4 or must be aconstant in range 0 to 127.

99 RELATIVE BRANCH TO EXTERNAL PROCEDUREA relative branch cannot have an external symbol for target since the linker cannot validatethe correctness of the relative target.

100 ILLEGAL 'DPP' OPERANDThe DPP prefix used in expressions cannot have labels of type NEAR, FAR, SHORT, orINTERRUPT as its operand. The DPP prefix is valid on data variables only.

101 INVALID SYSTEM ADDRESSThe address argument in a DEFR directive must specify an even internal system address inrange 0FE00H to 0FFDEH.

102 INVALID INTERNAL RAM ADDRESSThe address argument in a DEFA directive must specify an even internal RAM address inrange 0FA00H to 0FDFEH.

103 INVALID BIT ADDRESSThe bit address given in a DEFB directive must be written in the form 'base.bitpos'. 'Base'must be a bit-addressable SFR and 'bitpos' must be a constant value in range 0 to 15.

104 DATAn-OPERATOR: INCOMPATIBLE OPERANDThis error is issued if the operand of a DATAn operator is used to modify the DATAn-type ofthe operand or is applied to a SFR-symbol. Examples:

CON1 EQU DATA4 10

MOV R10,#DATA16 CON1 ; causes error 104MOV R10,#DATA8 SYSCON ; applied to SFR

105 $ABSOLUTE: NOT AN ABSOLUTE MODULEThe control directive $ABSOLUTE was given, but the assembler encountered relocatablereferences (relocatable sections or external symbols) within the module. The assembledsource module is not absolute.

106 UNTERMINATED SECTION/PROCEDUREThe end of the source module was reached while assembling without the last recent sectionor procedure or both being closed. Add the appropriate ENDP and ENDS directives.

107 REGBANK NAME REQUIREDThe argument given to ‘USING’ is incorrect. It should be the name of a register bank.

108 80C167 INSTRUCTION REQUIRES ‘MOD167’ CONTROLA 167 instruction requires the MOD167 control to enable the extended 167 instructions.

109 Unused.

110 ACCESS TO NORMAL SFR WITHIN AN ‘EXTENDED’ SEQUENCEWithin an EXTR sequence, you can’t access extended 167 SFR’s only. Any other SFRmust not be accessed within an EXTR sequence.

111 ACCESS TO EXTENDED SFR OUTSIDE AN ‘EXTENDED’ SEQUENCEOutside an EXTR sequence, you can’t access an extended 167 SFR.


6


112 CAN’T HAVE ‘TASK’ AND ‘INTERRUPT’ IN ONE MODULEIt is not possible to have an interrupt procedure and a task procedure within one sourcemodule.

113 PUBLIC/EXTERN ON REGBANK NOT ALLOWEDA symbol define to be a REGBANK can’t have attributes PUBLIC or EXTERN.

114 REGUSE: UNKNOWN REGISTERA register to REGUSE must be R0-R15, DPP0-DPP3, MDL, MDH, or MDC. Other registernames are illegal.

115 MULTIPLE REGUSE FOR ONE SYMBOLA PROC identifier cannot have more than REGUSE attached to it.

116 REGUSE REQUIRES A ‘PROC’ SYMBOLThe identifier given to REGUSE is not the name of a PROC symbol. Check lower case /upper case spelling of the identifier.

117 STRING TOO LONGA single string constant cannot have more than 128 characters.


6


7

Chapter 7. Implementation SpecificsThis chapter describes the following implementation-specific topics.

� Implementation limits.

� The 166/167 instruction set implemented in the A166 Assembler.

� Reserved words and predefined system names.

Implementation LimitsFixed internal limits are minimal. Most of the internal data structures are limitedby available memory only. The fixed limits (some introduced by the underlyingDOS) are listed below:

Parameter Value

Level Of Invocation File Nesting 9

Length Of An Identifier 80 Characters

Maximum Length Of A Line 510 Characters

Number Of Section Definitions Limited By Available Memory

Number Of Group Definitions Limited By Available Memory

Maximum Section Nesting 10

Maximum Number Of Symbols 6000 Per Module

166/167 Instruction SetThe assembler A166 accepts all assembly language instruction mnemonics asdefined in the SIEMENS specification (basic instruction set). Additionally, anumber of software instructions are defined which allow the assembler to decideautomatically which basic instruction is to be used in a particular situation.

146 Chapter 7. Implementation Specifics

7

Basic Instruction Set

The following tables show the basic instruction set. For more details in theinstructions, consult the Microcontroller Handbook for the 166/167.

Arithmetic Instructions

Byte/Word Add ADDB ADDW

Byte/Word Add With Carry ADDC BADDC

Byte/Word Sub SUBB SUBW

Byte/Word Sub With Carry SUBCB SUBCW

Word Mul Signed/Unsigned (16x16) MUL MULU

Word Div Signed/Unsigned (16/16) DIV DIVU

32/16 Bit Signed/Unsigned Div DIVL DIVLU

Byte/Word 1’s Complement CPLB CPLW

Byte/Word 2’s Complement NEGB NEGW

Bit Manipulation Instructions

Bit Field Manipulation BFLDH BFLDL

Single Bit Set BSET

Single Bit Clear BCLR

Single Bit Move BMOV

Single Bit Move Of Negated Bit BMOVN

Single Bit AND BAND

Single Bit XOR BXOR

Single Bit OR BOR

Bit Compare BCMP

Comparison and Looping Instructions

Word Compare With Post-Increment By 1 Or 2 CMPI1 CMPI2

Word Compare With Post Decrement By 1 Or 2 CMPD1 CMPD2

Shift and Rotate Instructions

Word Right Shift SHR

Word Left Shift SHL

Word Rotate Right ROR

Word Rotate Left ROL

Arithmetic Shift Right (Signed Shift) ASHR


7

Move Instructions

Byte/Word Data Move MOVB MOVW

Byte Load & Zero Extend To Word MOVBZ

Byte Load & Sign Extend To Word MOVBS

System Stack Instructions

Push Word Onto System Stack PUSH

Pop Word From System Stack POP

Save Word And Load New Content SCXT

Logical Instructions

Byte/Word Bitwise AND ANDB ANDW

Byte/Word Bitwise XOR XORB XORW

Byte/Word Bitwise OR ORB ORW

Jump and Call Instructions

Conditional Jump To Relative Target JMPR

Conditional Jump To Near Target JMPA JMPI

Unconditional Jump Any Target (Far) JMPS

Jump On Bit Condition JBJNB

Jump On Bit And Clear/Set Bit JBC JNBS

Absolute/ Indirect Near Call CALLA CALLI

Call Near Relative Target CALLR

Call Far Target CALLS

Push Register And Call Near Target PCALL

Activate Interrupt Handler TRAP

Return Instructions

Return From Near Procedure RET

Return From Far Procedure RETS

Return From Interrupt Procedure RETI

Pop Register & Return From Procedure RETP


7

System Control Instructions

Software Reset Of The CPU SRST

Service Watchdog Timer SRVSDT

Disable Watchdog Timer DISWDT

Enter Idle Mode IDLE

Enter Power Down Mode PWRDN

Signal End Of Initialization EINIT

Miscellaneous Instructions

Determine The Number Of Shifts Required To Normalize AWord PRIOR

No Operation (Two Byte Instruction) NOP

Begin Extend Page Sequence (167) EXTP

Begin Extend Segment Sequence (167) EXTS

Begin Extended Register Sequence (167) EXTR

Software Instruction Set

The software instruction set knows all instructions of the hardware instructionsplus some additional ones for easier programming. By means of softwareinstructions, the assembler can make the decision which instruction to use basedon the operand combinations and their types. The following table gives thesoftware instructions along with the possible hardware instructions, which asoftware instruction may be translated to:

Software Mnemonic Hardware Mnemonic Operation Type

ADD ADDW, ADDB Word, Byte

ADDC ADDCW,ADDCB Word, Byte

CPL CPLW, CPLB Word, Byte

NEG NEGW, NEGB Word, Byte

SUB SUBW, SUBB Word, Byte

SUBC SUBCW, SUBCB Word, Byte

AND ANDW, ANDB, BAND Word, Byte, Bit

CMP CMPW, CMPB, BCMP Word, Byte, Bit

MOV MOVW, MOVB, BMOV Word, Byte, Bit

OR ORW, ORB, BOR Word, Byte, Bit

XOR XORW, XORB, BXOR Word, Byte, Bit

CALL CALLA Absolute


7

Software Mnemonic Hardware Mnemonic Operation Type

CALLI Indirect

CALLR Relative

CALLS Segmented (Far) Call

JMP JMPA Absolute

JMPI Indirect

JMPR Relative

JMPS Segmented (Far Jmp)

RET RET Near Return

RETI Interrupt Return

RETS Segmented Return (Far)

Reserved Words in A166The following shows the reserved words by the assembler. These words are notallowed to be used for definition of user symbols.

Reserved Words For Directives And Operator Names

ASSUME AT BIT BITADDRESSABLE BITWORD

BOF BYTE CGROUP CODE COMMON DATA

DATA16 DATA3 DATA4 DATA8 DB DBIT

DBPTR DEFA DEFB DEFR DGROUP DPPTR

DS DSB DSPTR DSW DW DWORD

END ENDP ENDS EQ EQU EVEN

EXTERN EXTRN FAR GE GLBUSRSTK GLOBAL

GT HIGH INTNO LABEL LE LIT

LOW LT MOD NAME NE NEAR

NOT NOTHING OR ORG PAG PAGE

PEC ADDRESSABLE PECDEF POF PRIVATE PROC

PTR PUBLIC R REGBANK REGDEF RW

SECTION SEG SEGMENT SET SHORT SOF

SSKDEF SYSSTACK SYSTEM TASK TYPEDEC UGE

UGT ULE ULT USRSTACK W WORD

XOR


7

Reserved General Purpose Register Names

R0 R1 R2 R3 R4 R5

R6 R7 R8 R9 R10 R11

R12 R13 R14 R15

RL0 RH0 RL1 RH1 RL2 RH2

RL3 RH3 RL4 RH4 RL5 RH5

RL6 RH6 RL7 RH7

Reserved Words Of Assembler Mnemonics And Condition Codes

ADD ADDB ADDC ADDCB ADDCW ADDW

AND ANDB ANDW ASHR BAND BCLR

BCMP BFLDH BFLDL BMOV BMOV BMOVN

BOR BSET BXOR CALL CALLA CALLI

CALLR CALLS CC_C CC_EQ CC_N CC_NC

CC_NE CC_NET CC_NN CC_NV CC_NZ CC_SGE

CC_SGT CC_SLE CC_SLT CC_UC CC_UGE CC_UGT

CC_ULE CC_ULT CC_V CC_Z CMP CMPB

CMPD1 CMPD2 CMPI1 CMPI2 CMPW CPL

CPLB CPLW DISWDT DIV DIVL DIVLU

DIVU EINIT IDLE JB JBC JMP

JMPA JMPI JMPR JMPS JNB JNBS

MOV MOVB MOVBS MOVBZ MOVW MUL

MULU NEG NEGB NEGW NOP OR

ORB ORW PCALL POP PRIOR PUSH

PWRDN RET RETI RETP RETS ROL

ROR SCXT SHL SHR SRST SRVWDT

SUB SUBB SUBC SUBCB SUBCW SUBW

TRAP XOR XORB XORW


7

Predefined SFR and Bit NamesThe assembler A166 knows most of the special function register names (SFR).These predefined names (often referred to as ‘system names’) can be turned off bymeans of the NOMOD166 directive. If NOMOD166 is given, then the user mustinclude a file containing the system name definitions for SFR’s and probably forsystem bits, as required.

Predefined SFR Names And PEC-Channels

ADCIC ADCON ADDAT ADEIC CAPREL CC0

CC0IC CC1 CC10 CC10IC CC11 CC11IC

CC12 CC12I CCC13 CC13I CCC14 CC14IC

CC15 CC15I CCC1IC CC2 CC2IC CC3

CC3IC CC4 CC4IC CC5 CC5IC CC6

CC6IC CC7 CC7IC CC8 CC8IC CC9

CC9IC CCM0 CCM1 CCM2 CCM3 CP

CRI CCSP DP0 DP1 DP2 DP3

DP4 DPP0 DPP1 DPP2 DPP3 DSTP0

DSTP1 DSTP2 DSTP3 DSTP4 DSTP5 DSTP6

DSTP7 MDC MDH MDL ONES P0

P1 P2 P3 P4 P5 PECC0

PECC1 PECC2 PECC3 PECC4 PECC5 PECC6

PECC7 PSW S0BG S0CON S0EIC S0RBUF

S0RIC S0TBUF S0TIC S1BG S1CON S1EIC

S1RBUF S1RIC S1TBUF S1TIC SP SRCP0

SRCP1 SRCP2 SRCP3 SRCP4 SRCP5 SRCP6

SRCP7 STKOV STKUN SYSCON T0 T01CON

T0IC T0REL T1 T1IC T1REL T2

T2CON T2IC T3 T3CON T3IC T4

T4CON T4IC T5 T5CON T5IC T6

T6CON T6IC TFR WDT WDTCON ZEROS


7

Predefined Bit Names

ADBSY ADCH ADCIE ADCIR ADEIE ADEIR

ADM ADST BTYP BYT DISC CC0IE

CC0IR CC10IE CC10IR CC11IE CC11IR CC12IE





CC9IR CI CLKEN CRIE CRIR E

IEN ILLBUS ILLINA ILLOPA ILVL MCTC

MDRIU MTTC MULIP N NMI PRTFLT

RDYEN ROMEN RWDC S0EIE S0EIR S0FE

S0FEN S0M S0OE S0OEN S0PE S0PEN

REN S0RIE S0RIR S0STP S0TIE S0TIR

S1EIE S1EIR S1FE S1FEN S1M S1OE

S1OEN S1PE S1PEN S1REN S1RIE S1RIR

S1STP S1TIE S1TIR SGTDIS STKOF STKUF

T0IE T0IR T0M T0R T1IE T1IR

T1M T1R T2I T2IE T2IR T2M

T2R T2UD T3I T3IE T3IR T3M

T3OE T3OTL T3R T3UD T3UDE T4I

T4IE T4IR T4M T4R T4UD T5CLR

T5I T5IE T5IR T5M T5R T5SC

T5UD T6I T6IE T6IR T6OE T6OTL

T6R T6SR T6UD UNDOPC USR0 V

WDTIN WDTR WDTREL Z


8

Chapter 8. L166 Linker/LocatorThe L166 linker/locator is used to link or join together object modules that werecreated using the A166 assembler or the C166 compiler. Object modules that arecreated by these translators are relocatable and cannot be directly executed. Theymust be converted into absolute object modules using the L166 linker/locator.

The L166 linker/locator:

� Links 166 object modules generated by the A166 assembler or the C166compiler,

� Links object files that are stored in library files generated with LIB166,

� Builds real-time applications using the RTX 166 Real-Time Executive,

Refer to the following figure for an overview of the development process and thefiles accepted by 166 Utilities and 166 tool chain.

LIB166Library Manager

166 Library

File

L166Linker/Locater

AbsoluteObject

File

OH166Object Hex Converter

HEX

File

dScopeHLL Debugger

PROM Programmer

In-CircuitEmulator

MAPFile

from KeilA166 or

C166

Object Files RTX-166Real-Time

OS166 Library

Files

154 Chapter 8. L166 Linker/Locator

8

Programs you create using the A166 assembler and the C166 C compiler must belinked using the L166 linker/locator. You cannot execute or simulate programsthat are not linked, even if they consist of only one source module.

The L166 linker/locator links one or more object modules together and resolvesreferences from one to the other. This lets you create a large program that isspread over a number of source and object modules. The L166 linker/locatorprovides the following functions:

� Combines several program modules into one module, automaticallyincorporating modules from the library files,

� Combines relocatable partial sections of the same section name into a singlesegment,

� Allocates and manipulates the necessary memory for all relocatable andabsolute sections in the application program,

� Analyzes the program structure and manipulates the data memory usingoverlay techniques,

� Resolves external and public symbols,

� Defines absolute addresses and computes the addresses of relocatable sections,

� Produces an absolute object file that contains the entire program,

� Produces a listing file that contains information about the Link/Locateprocedure, the program symbols, and the cross reference of public andexternal symbol names,

� Detects errors found in the invocation line or during the Link/Locate run.

In addition, the L166 linker/locator provides support for the following:

� RTX166 Tiny Real-Time Multitasking Operating System,

� RTX166 Full Real-Time Multitasking Operating System.

All of these operations are described in detail in the remaining sections of thischapter.

“L166 Overview” on page 155 provides you with a summary of the features andcapabilities of the L166 linker/locator. This chapter introduces the concepts ofwhat a linker is and does.


8

“Linking Programs with L166” on page 161 describes how to invoke the linkerfrom the command line. The command-line arguments are discussed, andexamples are provided.

“Command-Line Directives” on page 165 provides an alphabetized listing of all ofthe directives that you can enter on the command line, along with examples.

“Definition of the Physical Memory Layout” on page 203 explains the assignmentof the C166 class and section names to physical 166/167 memory.

“Error Messages” on page 210 lists the errors that you may encounter when youuse the L166 linker/locator.

“Application Example” on page 219 contains a program example which showshow to use the L166 linker/locator.

L166 OverviewThe L166 linker/locator takes the object files and library files you specify andgenerates an absolute object file and a map file. The absolute object file containscomplete type and debug information for HLL debuggers and emulators. The mapfile contains text information about the link process.

Absolute object files may be converted into Intel HEX files by the OH166object-HEX converter. Refer to “Appendix B. OH166 Object-Hex Converter” onpage 239 for more information.

While processing object and library files, the L166 linker/locator:

� Combines program modules,

� Combines sections,

� Locates sections,

� Overlays data memory,

� Resolves external references,

� Calculates absolute addresses,

� Generates an absolute object file,

� Generates a listing (MAP) file.


8

Each of these functions is described in the following sections.

Combining program modules

Input files are processed in the sequence given by the invocation line. Withstandard program modules, which are created by C166 or A166, the completeinput file contents are processed. With library files (processed by LIB166) onlythose specific modules that contain public symbols for currently unresolvedexternal symbols are included

For library files a module list can be stated. In this case, the specified modulesfrom the library are always linked to the application program independent ofunresolved external symbols.

Sections

Programs comprise pieces called sections, which are the basic memory units forthe link/locate process. Sections are usually related to the hardware configuration;therefore the portions of programs that are to be kept in ROM are in separatesections from the portions that will be kept in RAM or bit memory. The A166Assembler allows the programmer to name the sections of the program beingdeveloped. The C166 compiler generates predefined section names.

A section is a contiguous area of memory that is defined in the source module.The absolute memory address is assigned by L166 during the locate step. Thesection size can be changed by combining sections and by the L166 SECSIZEcontrol directive. In A166 source modules it is also possible to generate absolutesections with a fixed section size.

L166 combines all sections with the same complete (section, class and tgroup)name and same combine type (PUBLIC, COMMON, STACK, …) from all inputmodules. The way in which sections are combined depends on the sectionalignment and the combine type.

Section Alignment

A section can have one of the following alignment attributes.

� BYTE : can be located at any memory address.


8

� WORD: can be located at a memory address that is a multiple of two (0, 2,4, 6, …).

� DWORD: can be located at a memory address that is a multiple of four (0, 4,8, 12, …).

� PAGE: can be located at a page boundary; this is a start address of an 16 KBmemory page (0, 0x4000, 0x8000, 0xC000, …).

� SEGMENT: can be located at a segment boundary; this is a start address ofan 64 KB memory segment (0, 0x10000, 0x20000, 0x30000, …).

� BIT : can be located at any bit address in the bit-addressable RAM.

� PECADDRESSABLE: can be located at a memory address in segment 0(address range 0x0000-0xFFFF) that is a multiple of 2 (0, 2, 4, 6, …).

Any alignment attribute except BYTE and BIT can result in a gap betweencombined sections. For example, when two DWORD-aligned sections arecombined, there will be a gap, when the first section length is not a multiple of 4.

Combining Sections

Sections with the combine types PUBLIC and GLOBAL are combined end to end.There may be a gap between the sections if the alignment requires it. The relativeaddresses in the sections are adjusted for the new longer section.

Sections with the combine types STACK, USERSTK, GLOBUSRSTK areoverlaid but their section length are added together. The new section has thelength of all combined partial sections.

Sections with the combine type COMMON are overlaid with their low addressesat a common address. The length of the combined memory section is the length ofthe largest partial section that was combined.

To make sure that sections are combined correctly, you should always give themthe same section and class name in each module.

Classes

A class is a collection of sections. When sections are defined in A166, a classname can be specified. The sections generated by C166 have predefined class


8

names. Any number of sections can be given the same class name. The same classname can be used in different modules.

The primary purpose of classes is to collect together (in an arbitrary order)sections that share a common attribute and to manipulate this collection at locate-time by specifying only the class name.

Class names give a section a second means for locating. In a typical program withseveral modules that are to be combined, the sections containing executable codewhich is near addressed the class name NCODE can be given in each module.

All sections with the same class name are located together in the same memoryaddress space of the output module. This class collection can be overwritten byspecifying the location of sections with the L166 control directive SECTIONS.

Groups

A group is also a collection of sections. Groups define addressing rangelimitations in 166/167 object modules. The 166/167 knows two different groups:

� A group of the type CODE (CGROUP) specifies a collection of sections thatmust be located within an 64 KB range. This means that the entire group ofsections can be addressed with offsets from a single code segment. Or, inother words, the CSP register need not be changed when addressing anysection in one CODE group.

� A group of the type DATA (DGROUP) specifies a collection of sections thatmust be located within an 16 KB range. This means that the entire group ofsections can be addressed with offsets from a single data page. Or, in otherwords, the DPP register need not be changed when addressing any section inone DATA group.

Groups permit efficient addressing within the module. L166 does not manipulatesections of a group to make sure that they fall within the valid address range.However, if they do not fit the range, an error message is issued. The sectionsincluded in a group do not have to be contiguous in the 166/167 memory. Theonly requirement is that all sections defined in a group must totally fall within onecode segment or one data page.


8

Allocating 166/167 Memory

After the combination of the sections, their location in the physical 166/167memory is defined.

For allocation sequence of the physical 166/167 memory, the section type, thealignment type and the entry of the SECTIONS, CLASSES or GROUPS directivein L166 invocation are considered. L166 allocates the physical 166/167 memoryin following sequence:

1. Interrupt vectors.

2. Absolute registerbanks.

3. Absolute sections (specifies with the at attribute).

4. Sections specified in the l166 sections directive.

5. Other registerbanks.

6. Bit-addressable data sections.

7. Bit sections.

8. Classes whose range is smaller than a data page (16 kb).

9. Groups specified with the l166 groups directive.

10. Groups containing an absolute section.

11. Other groups.

12. Sections with a class name.

13. Other sections.

Resolving External References

External symbols refers to symbol values or addresses defined in other modules.A declared external symbol is resolved with a public or global symbol of the samename. Therefore a public or global symbol must exist in another module for eachexternal symbol.

L166 processes modules with public and external references. During the L166run, a table of all public and external references is build. External references areresolved with public references, if the symbol name and symbol representationcorresponds. An error occurs if the symbol representation do not correspond, or ifno public symbol is found for the external symbol reference. Absolute addresses of


8

the public symbols are calculated after the sections are located to the physical166/167 memory.

Absolute Address Calculation

After allocation of the physical 166/167 memory and the processing of externaland public symbols is completed, all relocatable and external addresses arecalculated. At the same time the symbol information (if available) in the absoluteobject file is altered to reflect the new values. This is required to allow symbolicprogram debugging with dScope or emulators.

Producing the Absolute Object File

The executable program is generated in absolute object format. This absoluteobject file may contain additional symbol information (DEBUG), for symbolicprogram debugging. The symbol information can be suppressed by L166 controldirectives. The output file is executable and can be loaded by dScope, an emulatoror be translated by OH166 into a Intel .H86 file and programmed in EPROMs.

Producing a Listing File

L166 produces a listing file that contains the following information:

� The filenames and control directives of the L166 invocation command line.

� File and module names of all processed modules.

� A list of all TGROUPS contained in the program (if available).

� A list of all interrupt procedures with interrupt vector and interrupt name.

� A table of memory allocation (MEMORY MAP) which contains start address,stop address and size of the sections, section type, alignment, tgroup index,group index, combine type, class name and section name. This table may besuppressed by the NOMAP control directive.

� The group list displays all group names with group type, classes and sectionsassigned to this group. The group list may be suppressed by the NOMAPcontrol directive.

� A table of all public symbols contained in the program. This table displaysthe symbol value, symbol name, symbol representation, tgroup index, classname and section name which is assigned to that symbol.


8

� A list of all unresolved external symbols. An external symbol is unresolved ifno corresponding public symbol exists in another input file. Each reference toan unresolved external symbol is displayed as error message at the end of thelisting file.

� A symbol table which contains the symbol information from the input files.This information contains the value, type, representation, block length, tgroupindex and symbol name. The symbol table contains the following informationwhich can be identified by the type: GLOBAL, PUBLIC, SYMBOL, LINE,BLOCK and BLOCKEND.

� An alphabetically sorted cross reference report of all PUBLIC and EXTERNsymbols which contains symbol representation, tgroup and module nameswhere a reference to that symbol exists. In the first module displayed, thePUBLIC symbol is defined. Further module names display the modules inwhich the PUBLIC symbol is used by an external reference. If no PUBLICsymbol is present, the message “** UNRESOLVED **” is displayed. Somesymbols are generated by L166, in this case “** L166 GENERATED **” isprinted. The cross reference report is produced by entering the controldirective IXREF in the invocation line.

� Errors detected during the link/locate run are displayed on the screen as wellas at the end of the listing file. A summary of L166 errors, their causes andrecoveries are described in section “Error Messages” on page 210.

Using RTX166 and RTX166 Tiny

Programs you create that utilize the RTX166 and RTX166 Tiny Real-TimeOperating Systems must be linked using the L166 linker/locator. The RTX166and RTX166TINY directives enable link-time options that are required togenerate RTX166 Full and RTX166 Tiny applications.

Linking Programs with L166To invoke the L166 linker/locator, type L166 at the DOS prompt followed byany object modules or directives and press Enter . You may include objectmodules and directives on the command line or you may specify a commandresponse file. Use one of the following command-line formats:

L166 �inputlist � �TO outputfile � �directives �

or


8

L166 @commandfile

where:

inputlist is a list of the object files, separated by commas, for thelinker/locator to include in the final absolute object module orbanked object module . The files named in the inputlist cancontain both absolute and relocatable program modules which arecombined to form the final absolute object module. Additionally,you may force modules from library files to be included byspecifying their names in parentheses immediately following thelibrary file name.

outputfile is the name of the absolute object file that the linker/locatorcreates. If no outputfile is specified on the command line, thefirst filename in the input list is used. The basename of theoutputfile is used as base for the .M66 linker MAP file.

directives are commands and parameters that control the operation of theL166 linker/locator.

commandfile is the name of a command input file that may contain aninputlist , outputfile , and directives .

The inputlist uses the following general format:

filename �( modulename �, … �) � �, … �

where

filename is the name of an object file created by the C166 compiler or theA166 assembler or a library file created by the LIB166 librarymanager. The filename must be specified with its fileextension. Object files use the extension .OBJ. Library files usethe extension .LIB .

modulename is the name of an object module in the library file. Themodulename may only be used after the name of a library file.The modulenames must be specified in parentheses after thefilename. Multiple modulenames may be separated by commas.


8

Long Command Lines

The invocation line for the L166 linker/locator may be very long due to thenumber of specified input files and directives. To enter very long command lines,type the ampersand character (‘&’) at the end of a line to indicate that you want toenter more arguments. The L166 linker/locator prompts you with a double greaterthan sign (‘>>’) to indicate that you may enter more arguments.

Command Files

In addition to using the ampersand character, you may specify all command-linearguments for the L166 linker/locator in a command file. This has the sameformat as a normal command line and may be produced by a text editor. TheL166 linker/locator interprets the first filename preceded by an at sign (‘@’) as acommand file.

Command-Line Examples

The following examples are proper command lines for the L166 linker/locator.

L166 C:\MYDIR\PROG.OBJ TO C:\MYDIR\PROG.ABS

In this example only the input file C:\MYDIR\PROG.OBJ is processed andstored in the output file C:\MYDIR\PROG.ABS . The file ..PROG.ABS islocated to absolute addresses.

L166 SAMPLE1.OBJ, SAMPLE2.OBJ, SAMPLE3.OBJ TO SAMPLE.ABS

In this example the input files SAMPLE1.OBJ, SAMPLE2.OBJ andSAMPLE3.OBJ are linked in the output file SAMPLE.ABS. The output file islocated to absolute addresses.

L166 PROG1.OBJ, PROG2.OBJ, UTILITY.LIB

In this example unresolved external symbols are resolved with the public symbolsof the library file UTILITY.LIB . The necessary modules of the library are linkedautomatically. Modules with no references are not processed.

L166 PROG1.OBJ, PROG2.OBJ, UTILITY.LIB (IN, OUT)


8

Contrary to the preceding examples the modules IN and OUT from the library fileUTILITY.LIB are linked in any case.

Output File

The output file is the name of the file to which the absolute object file is written.If no output file is entered, L166 generates the name of the output file from thefirst input file without the extension. An error message occurs if the first input filecontains no extension, as would occur in this case:

L166 PROG1

In the previous case the name of the output file is identical with that of the inputfile, and this is an error. But by entering:

L166 PROG1 TO PROG1.ABS

The output file PROG1.ABS is used and an error does not occur.

DOS Errorlevel

After linking, the L166 linker/locator sets the DOS ERRORLEVEL to indicate thestatus of the linking process. Values are listed in the following table.

Errorlevel Meaning

0 No Errors Or Warnings

1 Warnings Only

2 Errors And Possibly Also Warnings

3 Fatal Errors

You can access the ERRORLEVEL variable in DOS batch files. Refer to yourDOS User’s Guide for more information about ERRORLEVEL or batch files.

Entering Names in Lower Case

L166 converts the complete input line into upper case. Usually, all SECTION,CLASS, and GROUP names are generated in uppercase by C166. However, insome cases you may be required to enter lowercase characters in names or otheritems. L166 let you do this allows this by using a string in the command line.


8

Example: L166 myfile.obj REGBANK ('lower_regs' (0xFC40))

In this example the register bank name lower_regs is notconverted into uppercase.

Command-Line Directives

Command-line directives may be entered after the output file specification.Multiple directives must be separated by at least one space character (‘ ’). Eachdirective may be entered only once on the command line. If a directive is enteredtwice, the L166 linker/locator reports an error.

The following table lists all L166 linker/locator directives along with theirabbreviations and brief descriptions.

Directive andAbbreviation

Function

ASSIGN, AS Define a public symbol at L166 level.

CLASSES, CL Define physical class addresses and class locating order.

DPPUSE, DU Re-assign the DPP registers for C166 NCONST and NDATAgroups.

GROUPS, GR Define physical group addresses and group locating order.

INTNO, IN Define interrupt or trap vectors for interrupt functions.

IXREF, IX Produce a cross reference report.

LINKONLY, LO Suppress the locate process of L166; support for incrementallinkage.

NAME, NA Specify a module name of the output file.

NOAMAKE, NOAM Specify that AMAKE information is excluded in the output file.

NOCASE, NOCA Disable case sensitivity of L166.

NOCOMMENTS, NOCM Remove translator comments in the listing and output file.

NODEFAULTLIBRARY, NLIB C166 run-time libraries are not automatically added.

NOINIT, NOIN Disable memory zero initialization for C166 data sections.

NOLINES, NOLI Remove line numbers in the listing and output file.

NOMAP, NOMA Suppress memory map in the listing file.

NOPUBLICS, NOPU Remove public symbols in the listing and object file.

NOTYPE, NOTY Remove symbolic type information in the object file.

NOVECTAB, NOVT Remove the interrupt vector table in the output file.

OBJECTCONTROLS, OC Specify the content of the output file.

PAGELENGTH, PL Set maximum number of lines per page in the listing file

PAGEWIDTH, PW Set the maximum width of the listing file.

PRINT, PR Define the listing filename.

PRINTCONTROLS, PC Specify the content of the listing file.


8

Directive andAbbreviation

Function

PUBLICSONLY, PO Use only the PUBLIC symbols of an input module.

PURGE, PU Remove all debug information in the listing an object file.

REGBANK, RB Define physical register bank addresses and locating order.

REGFILE, RF Specify the name of the file that contains register usageinformation.

RESERVE, RS Reserve physical 80C166 memory areas.

RESERVE, RS Reserve physical 80C166 memory areas.

RTX166 Select support for the RTX166 Full Real-Time Operating System.

RTX166TINY Select support for the RTX166 Tiny Real-Time Operating System.

SECSIZE, SS Change the length of sections.

SECTIONS, SE Define physical section addresses and section locating order.

VECTAB, VT Specify a start address for the interrupt vector table.

WARNINGLEVEL, WL Disable linker warning.

The following table describes the terms used to define the L166 command linedirectives:

Term Definition

name Names may be up to 40 characters long and must start with a letter ('A' - 'Z') orwith a '?', '_' mark or a '@' sign. The further characters may contain numbers ('0' -'9'). Names are used as module or section, class or group names.

symbolname A name interpreted as symbol name.

modulename A name interpreted as module name.

sectionname A name interpreted as section name.

classname A name interpreted as class name.

groupname A name interpreted as group name.

filename A filename in the general DOS form:

[drive :][ directory \]file [.ext ]

where:

drive : is a reference to a disk drive.directory \ is a DOS subdirectory. This entry may be repeated.file is the name of the file (max. 8 characters)..ext is the extension of the filename.

value A numeric value given in decimal, hex, bit or octal notation.Examples: 1011B, 2048D (or only 2048), 0D5FFH, 0x12FFF.

In addition L166 supports bit values in the form:value .bitno whereby bitno is a number in the range 0-15.

address A value interpreted as address.


8

Term Definition

range An address range in the form:start_address [- end_address ]The start_address is the first address specified by the range.The end_address is optional an specifies the last address with is included in theaddress range.


8

ASSIGN

Syntax: ASSIGN (symbolname (value) [, …])

Abbreviation: AS

µVision Control: Options—L166 Linker—Location—Assign 1 / Assign 2

Description: ASSIGN defines a PUBLIC symbol with a numeric value atL166 level. The defined symbol matches with an unresolvedexternal symbol.

Example: L166 myfile.obj ASSIGN ('func' (0x2000), 'bitvar'(0FD20H.2))

In this example the public symbols ‘func’ and ‘bitvar’ aredefined. The value 0x2000 is given as address for ‘func’.The value 0FD20H.2 is used as bit-address for the symbol‘bitvar’.

NOTEPublic symbols defined with the ASSIGN control directiveexists only at locate time and cannot be accessed in dScopeor emulators.


8

CLASSES

Syntax: CLASSES (classname [(range [, range ])] [, …])

Abbreviation: CL

µVision Control: Options—L166 Linker—Classes—Class 1-Class 8

Description: CLASSES specifies a physical address range or the locatingorder for all sections with the classname given. TheCLASSES control provides an easy way to define thephysical 166/167 memory layout. Refer also to “Definitionof the Physical Memory Layout” on page 203.

Examples: L166 myfile.obj CLASSES (NDATA0 (0x20000 - 0x23FFF), &NDATA (0x20000 - 0x22000))

In this example all sections with the classname NDATA0are placed in the address range 0x20000-0x23FFF and allsections with the classname NDATA are placed in theaddress range 0x20000-0x22000.

Default: L166 generates the following default class settings. Theseclass specifications ensures that specific C166 class namesare located to the correct physical 166/167 address ranges.

CLASSES (NCONST (0 - 0x3FFF),NCODE (0 - 0xF9FF),NDATA (04000H - 07FFFH), NDATA0 (04000H - 07FFFH),SDATA (0C000H - 0FFFFH), SDATA0 (0C000H - 0FFFFH),IDATA (0FA00H - 0FDFFH), IDATA0 (0FA00H - 0FDFFH),BIT (0FD00H - 0FDFFH), BIT0 (0FD00H - 0FDFFH),BDATA (0FD00H - 0FDFFH), BDATA0 (0FD00H - 0FDFFH))


8

DPPUSE

Syntax: DPPUSE (dppnr = NDATA ( range), dppnr = NCONST (range))

Abbreviation: DU

µVision Control: Options—L166 Linker—Location—DPP Use 1 andDPP Use 2

Description: DPPUSE allows you to re-assign the DPP registers for theC166 groups NDATA and NCONST. With DPPUSE youcan extend the DATA and NCONST groups to a total of64KB. This allows fast variable access with 16-bitaddresses. Refer also to “Definition of the Physical MemoryLayout” on page 203. The arguments for the DPPUSEdirective are described below:

dppnr is the number of a DPP register (0 for DPP0, 1 forDPP1, 2 for DPP2, 3 for DPP3). range is the address rangewhere the NDATA or NCONST group should be place.L166 generates proper initializations for all DPP registers.The DPP registers are assigned in ascending order to theNDATA or NCONST group. L166 assigns for an addressrange always several DPP registers if the range does not fitwithin one 16KB PAGE.

Examples: L166 myfile.obj DPPUSE(0=NDATA (20000H-2BFFFH), 3=NCONST(0C000H-0EFFFH))

In this example you are using DPP0, DPP1, and DPP2 foraccessing the NDATA group. DPP0 is loaded with the value8 pointing to address 20000H. DPP1 is loaded with the value9 pointing to the address 24000H. DPP2 is loaded with thevalue 10 pointing to address 28000H. With this DPP valuesyou can access the address range 20000H - 2BFFFH withshort (16-bit) addresses rather than using a far or hugeaddress. For the NCONST group the DPP3 register is used.For efficient access to 166/167 SFR registers of the 166/167this register must be loaded with 3. This allows to access therange 0C000H - 0FFFFH.


8

L166 myfile.obj DPPUSE (1=NDATA (18000H-1BFFFH), 2=NCONST(8000H-0EFFFH))

In this example the register DPP1 is used to access theNDATA addresses. The register DPP1 is therefore loadedwith the value 6 for the address range 18000H - 1BFFFH.The DPP2 and DPP3 registers are used for accessingNCONST addresses. DPP2 is loaded with the value 2pointing to address 08000H. DPP3 is loaded with the value 3pointing to address 0C000H. This allows the address range8000H - 0EFFFH to be used for NCONST objects.

See also: GROUPS

NOTESThe DPP3 register must contain always the value 3.Whenever you are using the DPP3 register for the NDATAor NCONST group the address range must fit into PAGE 3of the 166/167 address space. (Address range 0C000H -0FFFFH).

You must always state an address range for NDATA andNCONST. It is not possible to re-assign just one group.

The DPPUSE control also ensures that correct CLASSdefinitions for NDATA and NCONST are generated.

RESTRICTIONS:If you are using DPP0 for accessing NDATA or NCONSTgroups, you need to select the MOD167 directive foraccessing far/huge/xhuge objects. In the 166 mode it is notpossible to use far/huge/xhuge addressing, since the DPP0value is overwritten.

If you are converting the address of an automatic object to afar/huge/xhuge pointer you need to specify the C166NOFIXDPP directive.

An run-time error can occur, if you are accessing an nearobject in the DPPUSE area with an far pointer, since thevariable can overlap a 16KB page boundary. Therefore it isrecommended to use huge accessing and to avoid 64KBoverlaps in the DPPUSE range of a group.


8

GROUPS

Syntax: GROUPS (groupname [(address)] [, …])

Abbreviation: GR

µVision Control: Options—L166 Linker—Add’l—enter the GROUPS controlin an additional line.

Description: GROUPS specifies a physical start address or the locatingorder for a group name. All sections which are not stated inthe SECTIONS control and which are member of thespecified group are located according the arguments in thegroup directive.

Examples: L166 myfile.obj GROUPS (NDATA (0x10000), NCONST)

All sections which are member of the group NDATA arelocated at address 0x10000. After that the group NCONSTis located.

See also: DPPUSE


8

INTNO

Syntax: INTNO ( interruptsymbol (trapnumber) [, …])

Abbreviation: IN

µVision Control: Options—L166 Linker—Add’l—enter the INTNO control inan additional line.

Description: INTNO defines an trap number for the given interruptsymbol.

Example: L166 myfile.obj INTNO (TIMER0 (20H))

This example defines the trap number 0x20 for the followinginterrupt procedure declaration in a C source file:

void intrpt (void) interrupt TIMER0 { ...


8

IXREF

Syntax: IXREF [ ( NOGENERATED, NOLIBRARIES ) ]

Abbreviation: IX

µVision Control: Options—L166 Linker—Listing—Generate Cross Reference

Description: IXREF controls the generation of the module cross referencereport. If IXREF is entered a cross reference for public andexternal symbols is produced. If IXREF is not entered nocross reference is produced.

The option NOGENERATED suppresses symbols startingwith ‘?’ . These question mark symbols are normallyproduced by the C166 compiler for calling specific Cfunctions or passing parameters.

The option NOLIBRARIES suppresses those symbols whichare defined in a library file.

Example: L166 myfile.obj IXREFL166 myfile.obj IXREF (NOGENERATED)L166 myfile.obj IXREF (NOLIBRARIES, NOGENERATED)


8

LINKONLY

Syntax: LINKONLY

Abbreviation: LO


Description: The LINKONLY directive allows incremental linkage.LINKONLY suppresses the locate process of L166. If theLINKONLY directive is used, the outputfile of the L166Linker is still relocateable and can be located in a secondLinker/Locator run.

Example: L166 myfile1.obj, myfile2.obj TO file.lnk LINKONLY


8

NAME

Syntax: NAME (modulename)

Abbreviation: NA

µVision Control: Options—L166 Linker—Add’l—enter the NAME control inan additional line.

Description: NAME defines the modulename for the output file. If noNAME directive is entered the modulename of the first inputmodule is accepted as default.

Example: L166 myfile.obj NAME (SAMPLE_PROGRAM)

In this example the modulename SAMPLE_PROGRAM isdefined for the output file.


8

NOAMAKE

Abbreviation: None

Arguments: None

µVision Control: Options—L166 Linker—Add’l—enter the NOAMAKEcontrol in an additional line.

Description: The NOAMAKE directive allows you to direct the linker toexclude AMAKE information from the generated absoluteobject file. By default, the L166 linker/locator generatesobject modules that include records containing time and dateinformation for the source files and include files used to buildspecific object modules.

Example: L166 MYPROG.OBJ TO MYPROG.ABS NOAMAKE


8

NOCASE

Syntax: NOCASE

Abbreviation: NOCA

µVision Control: Options—L166 Linker—Add’l—enter the NOCASE controlin an additional line.

Description: NOCASE directs L166 to ignore the case of all symbolicinformation which appears in the input files. If NOCASE isspecified all names contained in the input files are convertedto upper-case letters. L166 differs between lower-case anduppercase if the control directive NOCASE is not stated.

Example: L166 file1.obj,file2.obj NOCASE


8

NOCOMMENTS

Syntax: NOCOMMENTS

Abbreviation: NOCM

µVision Control: Options—L166 Linker—Listing / Linking —Comments.

Description: NOCOMMENTS removes the comment records contained inthe input files from the listing file and the output file.Comment records are added to the object module for variousreasons. A166 and C166 add a comment record identifyingthe compiler or assembler that produced it.

Example: L166 file1.obj NOCOMMENTS

See also: OBJECTCONTROL, PRINTCONTROL, PURGE


8

NODEFAULTLIBRARY

Syntax: NODEFAULTLIBRARY

Abbreviation: NLIB

µVision Control: Options—L166 Linker—Linking—Ignore Default Libraries.

Description: NODEFAULTLIBRARY switches off the automatic linkingof C Run-Time-Libraries.

Normally L166 automatically adds the necessary Run- Time-Libraries to the specified object files. In doing so the memorymodel used by C166 and the usage of float or doublearithmetic is considered.

With the DOS command SET C166LIB=drive:\path , thedrive and/or path can be defined in which the library files arestored. Thus it is unnecessary to locate library files in thesame directory as the object files. Without the C166LIBenvironment variable the library files are searched in thecurrent directory.

Depending on the C166 memory model and the usage of floator double arithmetic in the C source files, the correct librariesare automatically chosen. Which libraries are added isdetailed in the table below.

If the control directive NODEFAULTLIBRARY is entered,the C run-time libraries must be stated in the followingsequence:

L166 inputlist , C166FPS.LIB, C166S.LIB

In this example the SMALL memory model with floatarithmetic is used. If the program contains no float operationsthe C166FPS.LIB should be not stated.

Example: L166 file1.obj NODEFAULTLIBRARY


8

NOINIT

Syntax: NOINIT

Abbreviation: NOIN

µVision Control: Options—L166 Linker—Add’l—enter the NOINIT control inan additional line.

Description: NOINIT disables the memory zero initialization which isperformed for C166 data variables when the C166 #pragmaNOINIT is not stated. Depending on the section name, L166generates an address table for memory zero initialization. Thecontrol directive NOINIT suppresses this initialization table.

Example: L166 file1.obj NOINIT


8

NOLINES

Syntax: NOLINES

Abbreviation: NOLI

µVision Control: Options—L166 Linker—Listing / Linking—Line numbers.

Description: NOLINES removes the line number information contained inthe input files from the listing file and the output file. Theline number information is used by dScope or emulators todisplay the source text for assembler instructions. This lineinformation is only required for program debugging and hasno influence on the executable code.

Example: L166 file1.obj NOLINES



8

NOMAP

Syntax: NOMAP

Abbreviation: NOMA

µVision Control: Options—L166 Linker—Listing—Memory map.

Description: NOMAP removes the memory map and the group list fromthe listing file. The memory map contains information aboutthe physical 166/167 memory layout and displays the addressassignment of program sections.

Example: L166 file1.obj NOMAP


8

NOPUBLICS

Syntax: NOPUBLICS

Abbreviation: NOPU

µVision Control: Options—L166 Linker—Listing / Linking—Public symbols.

Description: NOPUBLICS removes the debug information for publicsymbols contained in the input files from the listing file andthe output file. This debug information is used by dScope oremulators to calculate and display the value of publicsymbols. The public symbol information is only required forprogram debugging and has no influence on the executablecode.

Example: L166 file1.obj NOPUBLICS



8

NOTYPE

Syntax: NOTYPE

Abbreviation: NOTY

µVision Control: Options—L166 Linker—Linking—Include type information.

Description: NOTYPE removes symbol type information for debugsymbols from the output file. The symbol type information isused by dScope or emulators to display the correct format fordebug objects. C166 generates complete symbol informationup to structure members and parameter passing values. Thesymbol type information is only required for programdebugging and has no influence on the executable code.

Example: L166 file1.obj NOTYPE



8

NOVECTAB

Syntax: NOVECTAB

Abbreviation: NOVT

µVision Control: Options—L166 Linker—Linking—Generate Interrupt VectorTable.

Description: NOVECTAB disables the generation of the interrupt vectortable. Without the NOVECTAB directive L166 generatesautomatically an interrupt vector table which addresses theentry points of the defined interrupt procedures. Therefore allinterrupt procedures must have an unique interrupt or trapnumber.

Example: L166 file1.obj NOVECTAB

See Also: VECTAB


8

OBJECTCONTROLS

Syntax: OBJECTCONTROLS ( subcontrol [, …])

Abbreviation: OC

µVision Control: Options—L166 Linker—Linking—Object DebugInformation.

Description: With the OBJECTCONTROLS directive specific debuginformation can be removed from the output file. Thesubcontrol option can be one or more of the followingparameters:

Subcontrol Information Removed

NOCOMMENTS Comment records.

NOLINES Line number information.

NOPUBLICS Public symbol information.

NOSYMBOLS Local symbol information.

PURGE Complete debug information.

Examples: L166 file1.obj OBJECTCONTROLS (PURGE)

In this example the complete debug information is removedfrom the output file. However, the debug information isprinted in the L166 listing file.

L166 file2.obj OC (NOLINES, NOSYMBOLS)

With this L166 invocation only line numbers and local debugsymbols are removed from the output file.

See also: NOCOMMENTS, NOLINES, NOPUBLICS,NOSYMBOLS, PRINTCONTROLS, PURGE


8

PAGELENGTH

Syntax: PAGELENGTH ( number)

Abbreviation: PL

µVision Control: Options—L166 Linker—Listing—Page Length.

Description: PAGELENGTH sets the maximum number of lines per pagein the listing file to <n>. The minimum page length is 10 linesper page. Specifying a number less than 10 causes an errordefault to the minimum number of 10. If no page length isspecified, the default is 68 lines per page.

Example: L166 sample.obj PAGELENGTH (55)

In this example the page length for the listing file is set to 55lines per page.


8

PAGEWIDTH

Syntax: PAGEWIDTH ( number)

Abbreviation: PW

µVision Control: Options—L166 Linker—Listing—Page Width.

Description: PAGEWIDTH defines the maximum width of a line in thelisting file. The allowable range is 72-132 columns, with thedefault being 78.

Example: L166 SAMPLE.OBJ PAGEWIDTH (132)

This L166 invocation defines a width of 132 characters perline.


8

PRINT

Syntax: PRINT (filename)

Abbreviation: PR


Description: PRINT defines the name of the listing file. If no PRINTdirective is entered the name of the listing file is built from thename of the output file with the extension .M66. The defaultis: PRINT (outputfile.M66)

Example: L166 SAMPLE1.OBJ TO MYPROG.ABS PRINT (SAMPLE.LST)

Without entering PRINT the listing file is produced with thename MYPROG.M66.


8

PRINTCONTROLS

Syntax: PRINTCONTROLS ( subcontrol [, …])

Abbreviation: PC

µVision Control: Options—L166 Linker—Linking—Listing File Contents.

Description: With PRINTCONTROLS specific debug information can beremoved from the listing file. The subcontrol option can beone or more of the following parameters:

Subcontrol Information Removed

NOCOMMENTS Comment records.

NOLINES Line number information.

NOPUBLICS Public symbol information.

NOSYMBOLS Local symbol information.

PURGE Complete debug information.

Examples: L166 file1.obj PRINTCONTROLS (PURGE)

In this example the complete debug information is removedfrom the listing file. However, the debug information iscopied to the L166 output file.

L166 file2.obj PC (NOLINES, NOSYMBOLS)

With this L166 invocation only line numbers and local debugsymbols are removed from the listing file.

See also: NOCOMMENTS, NOLINES, NOPUBLICS,NOSYMBOLS, OBJECTCONTROLS, PURGE


8

PUBLICSONLY

Syntax: PUBLICSONLY ( inputfile)

Abbreviation: PO


Description: With PUBLICSONLY only the publics symbols of a inputfile are used. SECTION/GROUPS/CLASSES the datacontent and debug symbols are removed. PUBLICSONLYcan be used to link overlays or generate memory banks in anapplication. The PUBLICSONLY directive is used in theinput file list; it is not possible to specify it in the directivespart of the L166 command line.

Example: L166 f1.obj, PUBLICSONLY (f2.obj, f3.obj)L166 PO (f1.obj), f2.obj, PO (ABC.LIB)


8

PURGE

Syntax: PURGE

Abbreviation: PU


Description: PURGE removes the complete debug information containedin the input files from the listing file and the output file.PURGE has the same effect as specifying NOCOMMENTS,NOLINES, NOPUBLICS and NOSYMBOLS. The debuginformation is only required for program debugging and hasno influence on the executable code.

Example: L166 file1.obj PURGE

See also: NOCOMMENTS, NOLINES, NOPUBLICS,NOSYMBOLS, OBJECTCONTROL,PRINTCONTROL


8

REGBANK

Abbreviation: RB

Arguments: REGBANK ( regbank_name [ (address) ][, …])REGBANK ( base_addr [, regbank_name [ (addr) ][, …]])

µVision Control: Options—L166 Linker—Sections—RegBank.

Description: The REGBANK directive defines the base address, aphysical memory address, or an order for the specifiedregister banks. Those register banks defined in theREGBANK directive are allocated sequentially. The firstregister bank is usually located at the register base address(default 0xFC00) which can be also re-defined with theREGBANK control. The user has the choice to define thestart address of one or more register banks within the locationparameter. If an address is defined the register bank islocated at that memory address. A warning message isdisplayed if this register bank overlaps other sections orregister banks.

Example: L166 MYPROG.OBJ REGBANK (0xFB00)

This example places all registers banks from address0FB00H upwards.

L166 MYPROG.OBJ REGBANK (?C_MAINREGS(0xFC80),IREGS)

This example locates the register bank ?C_MAINREGS ataddress 0xFC80 and places the register bank IREGS after?C_MAINREGS.


8

REGFILE

Abbreviation: RF

Arguments: REGFILE ( filename)

µVision Control: Options—Make—Misc—Register Optimization.

Description: The REGFILE directive lets you specify the name of theregister usage file generated by the L166 linker/locator. Theinformation in this file is used by the C166 compiler whengenerating code for each function invocation. The C166compiler uses the register usage information generated by thelinker to optimize the use of registers when passing values toand returning values from external functions. This directivefacilitates global register optimization.

Example: L166 MYPROG.OBJ,A.OBJ,B.OBJ REGFILE(PROG.REG)


8

RESERVE

Syntax: RESERVE (startaddress - endaddress [, …] )

Abbreviation: RE

µVision Control: Options—L166 Linker—Location—Reserve 1 andReserve 2.

Description: RESERVE prevents L166 from locating sections in thespecified areas of memory. L166 will not use all memoryaddresses from startaddress to endaddress inclusive.startaddress must be less than of equal to endaddress.

If an absolute section uses a reserved memory area, a warningmessage is generated.

Example: L166 file1.obj RESERVE (4H-200H)

This example reserves the memory space 0x0004-0x0200.

L166 file2.obj RESERVE (0x200-0x3FFF, 0x10000-0x1FFFF)

This example reserves the memory spaces 0x0200-0x3FFFand 0x1FFFF-0x20000.


8

RTX166

Abbreviation: None

Arguments: None

µVision Control: Options—L166 Linker—Linking—RTX166.

Description: The RTX166 directive specifies that the application shouldbe linked for use with the RTX166 Full Real-TimeMultitasking Operating System. This involves resolvingreferences within your program to RTX166 Full functionsfound in the RTX166 Full library.

See Also: RTX166TINY

Example: L166 RTX_EX1.OBJ RTX166


8

RTX166TINY

Abbreviation: None

Arguments: None

µVision Control: Options—L166 Linker—Linking—RTX166 tiny.

Description: The RTX166TINY directive specifies that the applicationshould be linked for use with the RTX166 Tiny Real-TimeMultitasking Operating System. This involves resolvingreferences within your program to RTX166 Tiny functionsfound in the RTX166 Tiny library.

See Also: RTX166

Example: L166 RTX_EX1.OBJ RTX166TINY


8

SECSIZE

Syntax: SECSIZE (sectionname[% classname] (size))

Abbreviation: SS

µVision Control: Options—L166 Linker—Sections—Secsize 1 and Secsize 2.

Description: SECSIZE allows to specify the memory space used by asection. For BIT sections the size may be specified in bitswith the “.” operator.

The sectionname and classname specifies any sectioncontaining in the input module.

The value size specifies the change of the section size. Thereare three ways of specifying this value:

� + indicates that the value should be added to the currentsection length.

� - indicates that the value should be subtracted from thecurrent section length.

� No sign indicates that the value should become the newsection length.

Example: L166 file1.obj SECSIZE (?C_USERSTACK%NDATA (+ 200H))

In this example the size of the section ?C_USERSTACK inthe class NDATA is enlarge by 0x200 bytes.


8

SECTIONS

Syntax: SECTIONS (sectionname[% classname] [(addr)] [, …])

Abbreviation: SE

µVision Control: Options—L166 Linker—Sections—Section 1-Section 5.

Description: The SECTIONS directive defines a physical memory addressor an order for the specified sections. Those sections definedin the SECTIONS directive are allocated sequentially. Thefirst section is always located at the lowest possible address(usually 0 or implicit specified by a CLASSES or GROUPSdirective), subsequent sections are always located atascending addresses.

The user has the choice to define the start address of one orall sections within the location parameter. If an address isdefined the section is located at that memory address. Awarning message is displayed if this section overlaps withother sections.

Example: L166 abc.obj SECTIONS (?PR?ABC%NCODE (0x12000))

In this example the section with the name ‘?PR?ABC’ and theclass name ‘NCODE’ is located to address 0x12000.

L166 abc.obj SECTIONS (?PR?ABC%NCODE (0x12000), &?CO?ABC%NCONST))

In addition to the example above, the section ‘?CO?ABC’with the class name ‘NCONST’ is after the section‘?PR?ABC’.

L166 abc.obj SECTIONS (?CO?ABC%NCONST (0x2000), &?BI0?ABC%BIT0 (0FD20H.5)

In this example the section ?CO?ABC with the class nameNCONST is located to address 0x2000. The section?BI?ABC with the class name BIT0 is located to bit address0FD20H.5.


8

VECTAB

Abbreviation: VT

Arguments: VECTAB ( offset)

µVision Control: Options—L166 Linker—Location—Interrupt Vector TableAddress.

Default: VECTAB (0)

Description: The VECTAB allows to specify a start address for theinterrupt vector table. The default start address for theinterrupt vector table is 0. In some applications—basicallywith Monitor-166—it is required to change the start addressof the interrupt vector table.

Example: L166 MYFILE.OBJ VECTAB (8000H)

See Also: NOVECTAB


8

WARNINGLEVEL

Abbreviation: WL

Arguments: A number between 0 and 2.

µVision Control: Options—L166 Linker—Linking—Warnings.

Default: WARNINGLEVEL (2)

Description: The WARNINGLEVEL directive lets you suppress linkerwarnings. Refer to “Warnings” on page 210 for a full list ofthe linker warnings.

Warning Level Description

0 Disables almost all linker warnings.

1 Lists only those warnings which may generateincorrect code, including information about datatype mismatches of total different types.

2 (Default) Lists all WARNING messages including warningsall data type mismatches.

Example: L166 MYFILE.OBJ WL (1)


8

Definition of the Physical Memory LayoutThe following explains the address assignment of 166/167 programs written inC166 to different physical memory layouts. Since the memory layout of an166/167 system depends on the hardware structure, no general rule can be given.Instead of that, the address assignment is explained with the following examples.

Before the program is assigned to physical memory devices, the structure of the166/167 must be defined. Unless you are using the DPPUSE directive, it shouldbe noted that a near address data area must reside in one data page (16 KBblock); a near address code are must reside in one code segment (64 KB block).The on-chip RAM (address range 0FA00H-0FFFFH) of the 166 should not beused for program code or constant values.

Example 1:

The following example assumes the following memory areas. Because of thehardware structure of an 166 system, the address 0 must be occupied by a ROM.We are also using the SMALL memory model in this example; therefore thecomplete code is located into the NCODE class.

Memory Type Address Range Used by

ROM 0x0000-0x7FFF Interrupt vectors, near addressed area for constantvalues, start-up code.

RAM 0x8000-0xFFFF Near addressed data and system page.

ROM 0x10000-0x1FFFF Near addressed executable program code.

To specify this memory layout L166 should be invoked with the followingCLASSES control directive. The example assumes that the program uses theSMALL memory model and that the memory space far is not used. The sections?C_INITSEC and ?C_MEMCLRSEC must be placed anywhere in the ROMspace. This must be specified in a separate SECTIONS directive.

L166 <input_files> . CLASSES (ICODE (0 - 0x7FFF), NCONST (0x4000 - 0x7FFF), NDATA (0x8000 - 0xBFFF), NDATA0 (0x8000 - 0xBFFF), NCODE (0x10000 - 0x1FFFF)) SECTIONS (?C_INITSEC (0x400), ?C_MEMCLRSEC)

Example 2:

In addition to the example above, the next system contains an second RAM area,which should be used for far/huge/xhuge addressed data variables. This example


8

is using the LARGE memory model; the code is placed in the FCODE class by theC166 compiler.


ROM 0x0000-0x7FFF Interrupt vectors, near addressed area for constantvalues, start-up code.

RAM 0x8000-0xFFFF Near addressed data and system page.

ROM 0x10000-0x1FFFF Near addressed executable program code.

RAM 0x30000-0x3FFFF Far/huge/xhuge addressed data area.

To specify the memory layout of example 2 the linker/locator L166 should beinvoked with the following CLASSES control directive.

L166 <input_files> . CLASSES (ICODE (0 - 0x7FFF), NCONST (0x4000 - 0x7FFF), FCONST (0 - 0x7FFF), HCONST (0 - 0x7FFF), NDATA (0x8000 - 0xBFFF), NDATA0 (0x8000 - 0xBFFF), FDATA (0x30000 - 0x3FFFF), FDATA0 (0x30000 - 0x3FFFF), HDATA (0x30000 - 0x3FFFF), HDATA0 (0x30000 - 0x3FFFF), XDATA (0x30000 - 0x3FFFF), XDATA0 (0x30000 - 0x3FFFF), FCODE (0 - 0x7FFF, 0x10000 - 0x1FFFF)) SECTIONS (?C_INITSEC (0x400), ?C_MEMCLRSEC)

Example 3:

The following example assumes a system with battery back-up RAM (NVRAM).If the size of the NVRAM is not critical, it should be also used for initialized nearaddressed data objects. C166 provide with the #pragma NOINIT an easy way toprevent certain objects from zero initialization as required for systems withNVRAM.


ROM 0x00000-0x1FFFF Interrupt vectors, near addressed area for constantvalues, start-up code, executable program code.

RAM 0x20000-0x27FFF Far/huge/xhuge data RAM.

NVRAM 0x28000-0x2FFFF Non-volatile data RAM, near addressed data, 'far'addressed NVRAM data.


8

To specify the memory layout of example 3 the linker/locator L166 should beinvoked with the following CLASSES control directive.

L166 <input_files> . CLASSES (ICODE (0 - 0x7FFF), NCONST (0x4000 - 0x7FFF), FCODE (0 - 0xEFFF, 0x10000 - 0x1FFFF)) FCONST (0 - 0xEFFF, 0x10000 - 0x1FFFF), HCONST (0 - 0xEFFF, 0x10000 - 0x1FFFF), XCONST (0 - 0xEFFF, 0x10000 - 0x1FFFF), FDATA (0x28000 - 0x2FFFF), FDATA0 (0x20000 - 0x27FFF), HDATA (0x28000 - 0x2FFFF), HDATA0 (0x20000 - 0x27FFF), XDATA (0x28000 - 0x2FFFF), XDATA0 (0x20000 - 0x27FFF), NDATA (0x28000 - 0x2BFFF), NDATA0 (0x28000 - 0x2BFFF), SECTIONS (?C_INITSEC (0x400), ?C_MEMCLRSEC)

NOTEThe classname specified in the CLASSES directive overwrite the default settingsof this control. Other default settings for example for IDATA, BIT or SDATAclasses are still valid and are not changed as long as not other address range isgiven. Therefore, only those class names are entered where the default addressrange does not fit to the memory layout used in the actual 166/167 hardware.

It is also not required to specify a range for CLASS which you are not using inyour application. For example, if you are not using xhuge objects you need notto specify ranges for the XDATA, XDATA0 and XCONST class.

See Also: C166 Compiler User’s Guide, Chapter 6. AdvancedProgramming Techniques, “Section, Group and Class Names”.

Advanced Techniques

The following example shows the memory definition for a very complex systemwith the C167CR device. The C166 HLARGE memory model is used for thisapplication. We are using both huge and xhuge variables, but no far objects inthis application. The additional on-chip XBUS RAM of the C167CR is used forsdata variables.

The DPPUSE directive is used to define a 48KB NDATA area and a 8KBNCONST area in page 3 of the memory. The on-chip RAM is accessed with idatavariables. The C167CR CAN Module is access with the CAN167.H definitionfile.


8

The following figure shows the memory layout of this C167CR system.

0x4BFFF

DPP2 = 0x48000

DPP1 = 0x44000DPP0 = 0x40000

This example uses 256KBROM space for far codeand constants starting @0.

0x10000

48 KB near data space

0

DPP3 = 0xC000

NCONST space

256 KB ROM area 0 ..0x3FFFF

256 KB RAM starts in thisexample at 0x40000.

you place elements withhuge or xhuge dependingon the object size. At thebeginning of the RAM 48KB near space for 16-bitaccesses is available.

0xE000

0xE7FFOn-chip sdata XRAM

0xEFFFCAN Module

0xF600

0xFDFFInternal RAM

To specify the memory layout for this example, the L166 linker is invoked withthe following control directives.

L166 <input_files> . DPPUSE (3 = NCONST (0xC000 - 0xDFFF), 0 = NDATA (0x40000 - 0x4BFFF) SECTIONS (?C_INITSEC (0x10000), ?C_MEMCLRSEC) RESERVE (0xE7FF - 0xEFFF) /* for CAN Module */ CLASSES (ICODE (0 - 0xDFFF), FCODE (0 - 0xDFFF, 0x10000 - 0x3FFFF) HCONST (0x10000 - 0x3FFFF), XCONST (0x10000 - 0x3FFFF), HDATA (0x4C000 - 0x7FFFF), HDATA0 (0x4c000 - 0x7FFFF), XDATA (0x4C000 - 0x2FFFF), XDATA0 (0x4C000 - 0x7FFFF), SDATA (0xE000 - 0xE7FF), IDATA (0xF800 - 0xFDFF))


8

TGROUPS (Siemens Task Concept)With TGROUPS L166 supports also the so-called ‘SIEMENS TASKCONCEPT’. Whereas the Siemens Task Concept limits also the number ofinterrupt procedures within a “Siemens Task”, L166 uses TGROUPS only forisolating symbols, sections and groups from different TGROUPS.

TGROUPS at L166 level are like using blocks on C source level. TGROUPSperform a block structure for PUBLIC symbols, sections and groups onlinker/locator level. This concept is similar to the isolation of automatic symbols ina C source.

Example:

C Program: L166 Invocation:

func1 () { int i; for (i = 1; i < 100; i++);}

main () { int i;

for (i = 1; i < 100; i++) func ();}

In this C program the variable ‘i’ in‘func’ has a different location asvariable ‘i’ in ‘main’. The scope ofautomatic variables is limited to thefunction containing the variabledefinition.

L166 & { file1.obj }, { file2.obj }

We assume that both modules ‘file1.obj’and ‘file2.obj’ have a PUBLIC symbolwith the name ‘i’. By using the ‘{’ and‘}’ this PUBLIC symbols are isolatedfrom each other. This means that thePUBLIC symbol ‘i’ from ‘file1.obj’cannot be accessed from ‘file2.obj’. Thescope of PUBLIC symbols, sections andgroups is limited to the TGROUPcontaining the definitions.

The general format of the L166 invocation with TGROUPS is:

L166 [ taskname1 ] { inputlist [ tgroupcontrols ]}, [taskname2] {input_list [ tgroupcontrols ]} { , ... } inputlist [ TO outputfile ] [ directives ]

where

taskname is a TGROUP identifier used in dScope or emulators.

inputlist is a list of object file names as described in section “LinkingPrograms with L166” on page 161.


8

tgroupcontrols is one of the following L166 control directives which refers toPUBLIC symbols, sections or groups contained within object filesin this TGROUP: ASSIGN, GROUPS, INTNO, SECSIZE andSECTIONS.

outputfile is the name of an output file as described in section “LinkingPrograms with L166” on page 161.

directives contains L166 control directives as described in section “LinkingPrograms with L166” on page 161.

PUBLIC symbols which should be accessed from all TGROUPS must be definedas GLOBAL symbol (only possible with A166). A second way is to state themodule containing the PUBLIC symbol outside of the TGROUP braces.

Example:

L166 { module1.obj }, { module2.obj }, printf.obj

In this example the PUBLIC symbols contained in the file ‘printf.obj’ can beaccessed from object files of both TGROUPS ‘module1.obj’ and ‘module2.obj’.

TGROUPS isolate symbols, sections, interrupt names and group names from othermodules. Therefore in is required that the L166 controls ASSIGN, GROUPS,INTNO, SECSIZE and SECTIONS can be applied also to the same section namein different TGROUPS. This controls can be stated inside the TGROUP braces(‘{’ and ‘}’) and refer in this case only to sections defined inside this TGROUP.

Compatibility to Siemens Tools

TGROUPS provide compatibility to programs which are initial developed withSiemens Tools. To convert an existing Siemens program from Siemens LNK166and LOC166 to the L166 invocation format the command lines must be modifiedas follows:

Siemens LNK166, LOC166 Invocation Lines:

LNK166 MOD_TSK1,MODA_TSK1,MODB_TSK1 TO MOD_TSK1

LNK166 MOD_TSK2,MODA_TSK2,MODB_TSK2 TO MOD_TSK2

LOC166 @DEMO.ILO


8

Content of DEMO.ILO: TASK INTNO intno_tsk1 = 22H MOD_TSK1 ADDRESSES (GROUPS (ram_grp_0(200H)) TASK INTNO intno_tsk2 = 23H MOD_TSK2 ADDRESSES (GROUPS (ram_grp_3 (3C000H)) CLASSES ('rom_tsk1' (10000H - 1FFFFH), 'rom_tsk2' (20000H - 2FFFFH))

L166 Invocation Line with the same effect:

L166 @DEMO.L66

Content of DEMO.L66:{ MOD_TSK1.OBJ, MODA_TSK1.OBJ, MODA_TSK1.OBJ INTNO (intno_tsk1 (22H)) GROUPS (ram_grp_0 (200H)) }, { MOD_TSK2.OBJ, MODA_TSK2.OBJ, MODA_TSK2.OBJ INTNO (intno_tsk2 (23H)) GROUPS (ram_grp_3 (3C000H)) } CLASSES (rom_tsk1 (10000H - 1FFFFH), rom_tsk2 (20000H - 2FFFFH))

Using TGROUPS with Emulators

TGROUPS are implemented for compatibility to Siemens tools and should only beused when required. Currently not all emulators support TGROUPS. Thereforedebugging can become complex if TGROUPS are used in a 166/167 program.Contact your emulator vendor for more information about debugging 166/167programs with TGROUPS.


8

Error MessagesL166 error messages describe warnings, non fatal errors and fatal errors. Awarning is a message that may or may not have been intended by the user. In thiscase the listing file can be very useful. Warnings and errors do not abort theLinker/Locator operation. However an error may result in an output module thatcannot be used. A fatal error aborts the L166 operation.

Error messages are displayed in the listing file and on the screen.

This section lists all L166 Linker/Locator error messages, together with theircauses and any recovery actions.

Warnings

Warning Warning Message and Description

1 UNRESOLVED EXTERNAL SYMBOLS DURING LINK PROCESSSYMBOL: external-nameMODULE: filename (modulename)The specified external symbol, requested in the specified module, has nocorresponding PUBLIC symbol in any of the input files. If you are using theLINKONLY directive, this symbols can be resolved in a sub-sequent link/locate run.

3 ASSIGNED ADDRESS NOT COMPATIBLE WITH ALIGNMENTSECTION: section-nameCLASS: class-nameThe address specified for the section is not compatible with the alignment of thesection declaration.

4 MEMORY SPACE OVERLAPFROM: byte.bit addressTO: byte.bit addressThe specified memory area is occupied by more than one section or is reserved by theRESERVE directive of L166. Please verify the memory MAP of the 166/167 program.

5 SECTION LOCATED OUTSIDE CLASS AREASECTION: section-nameCLASS: class-nameThe specified section is not located within the class address range specified for theclass name.

7 MODULE NAME NOT UNIQUEMODULE: filename (modulename)The specified module name is used for more than one module. The specified modulename is not processed.

8 MODULE NAME EXPLICITLY REQUESTED FROM ANOTHER FILEMODULE: filename (modulename)The specified module name is requested in the invocation line of another file that hasnot yet been processed. The specified module name is not processed.


8


10 EXISTING SYSTEM STACK DEFINITION EXPANDEDThe program contains more than one SSKDEF definition, therefore the SSKDEFdefinition with the largest system stack definition is used. L166 reports multipleSSKDEF directives with this warning.

11 SECTION SIZE UNDERFLOW: OLD SIZE + CHANGE < 0SECTION: section-nameCLASS: class-nameThe size change specified in the SECSIZE control directive causes the section size tobe less than zero.

12 EMPTY SECTIONS ENCOUNTEREDThe 166/167 program contains sections with size 0. This sections are not located.Verify the memory MAP in the listing file.

13 DECREASING SIZE OF SECTIONSECTION: section-nameCLASS: class-nameThe size specified in the SECSIZE control has caused L166 to decrease the size ofthe specified section.

14 INCOMPATIBLE MEMORY MODELMODULE: filename (modulename)MODEL: memory modelThe specified module is not translated in the same memory model as the former L166input modules. The memory model of the invalid module is displayed. The memorymodel of other input modules is displayed in the L166 listing file.

15 INCOMPATIBLE CPU MODEMODULE: filename (modulename)MODE: cpu modeThe specified module is not translated with the same 166/167 CPU mode as theformer L166 input modules. The CPU mode of the invalid module is displayed. TheCPU mode of other input modules is displayed in the L166 listing file.

16 UNSUPPORTED SYSDEF VALUEMODULE: filename (modulename)The specified module contains a SYSDEF value which is not supported by L166.

17 NO SYSTEM STACK ALLOCATED; EXISTING SYSDEF VALIGNOREDYou are using the value 7 for the system stack definition. In this case you must ensurethat the system stack is allocated with other methods.

18 NONSEGMENTED CPU MODE SUPPORTS ONLY 64KB MEMORYIn the NONSEGMENT mode you cannot access memory above 0x10000.

19 DPP REASSIGNED, USE C166 WITH NOFIXDPP CONTROLMODULE: filename (modulename)This module must be re-translated with the C166 NOFIXDPP directive, since you areusing the L166 DPPUSE directive to re-assign the DPP values.

20 DATA TYPES DIFFERENTSYMBOL: symbol-nameMODULE: module-nameThe definition of the specified symbol in the specified module is not identical with thepublic definition of that symbol. The module which contains the public symbol can bedetermined with the IXREF listing. This warning is disabled with WARNINGLEVEL(0) directive.


8


21 DATA TYPES SLIGHTLY DIFFERENTSYMBOL: symbol-nameMODULE: module-nameThe definition of the specified symbol in the specified module is not 100% identicalwith the public definition of that symbol. This warning is the result when unsignedsigned mismatches occur, i.e. unsigned char does not match char. The module whichcontains the public symbol can be determined with the IXREF listing. This warning isdisabled with WARNINGLEVEL (1) directive.

Non Fatal Errors


101 SECTION COMBINATION ERRORSECTION: section-nameCLASS: class-nameMODULE: filename (modulename)The attributes of the specified partial section in the specified module cannot becombined with the attributes of the previous defined partial sections with the samesection and class name. The partial section is ignored.

102 EXTERNAL ATTRIBUTE MISMATCHSYMBOL: external-nameMODULE: filename (modulename)The attributes of the specified external symbol in the specified module do not matchthe attributes of the previously defined external symbols. The specified symbol isignored.

103 EXTERNAL ATTRIBUTE DO NOT MATCH PUBLICSYMBOL: public-nameMODULE: filename (modulename)The attributes of the specified public symbols in the specified module do not match theattributes of the previous defined external symbols. The specified symbol is ignored.

104 MULTIPLE PUBLIC DEFINITIONSSYMBOL: public-nameMODULE: filename (modulename)The specified public symbol in the specified module has already been defined in apreviously processed file.

105 PUBLIC REFERS TO IGNORED SECTIONSYMBOL: public-nameSECTION: section-nameCLASS: class-nameThe specified public symbol is defined in the specified segment. It cannot beprocessed on account of an error. The public symbol is therefore ignored.

106 SECTION OVERFLOWSECTION: section-nameCLASS: class-nameThe specified segment is longer than 64 Kbyte and cannot be processed.


8


110 CANNOT FIND SECTIONSECTION: section-nameThe specified section is contained in the invocation line but cannot be found in an inputmodule. The specified section is ignored.

112 SECTION DOES NOT FIT WITHIN GROUP RANGESECTION: section-nameCLASS: class-nameThe specified section is not located within the group range assigned to this section.

113 SECTION IN LOCATING CONTROL IS ALREADY ABSOLUTESECTION: section-nameCLASS: class-nameThe specified section is already absolute and cannot be relocated with a L166directive.

114 SECTION DOES NOT FIT WITHIN SEGMENT BOUNDARYSECTION: section-nameCLASS: class-nameThe specified section is not located within a physical 166/167 segment (64 KB block).

115 SIZE OF DGROUP EXCEEDS 16KGROUP: group-name (GRP number)All of the sections that belong to the specified data group do not fit within a data page(16 KB block).

116 SIZE OF CGROUP EXCEEDS 64KGROUP: group-name (GRP number)All of the sections that belong to the specified code group do not fit within a codesegment (64 KB block).

117 GROUP HAS NO CONSTITUENT SECTIONSGROUP: group-name (GRP number)The specified group has no sections and is not placed in the output file.

118 REFERENCE MADE TO ERRONEOUS EXTERNALSYMBOL: symbol-nameMODULE: filename (modulename)ADDRESS: code-addressThe specified external symbol that was erroneously processed, is referenced at thespecified code address.

119 REFERENCE MADE TO ERRONEOUS SECTIONSECTION: section-nameCLASS: class-nameMODULE: filename (modulename)ADDRESS: code-addressThe specified section processed with an error, is referenced in the specified codeaddress.

120 CONTENT BELONGS TO ERRONEOUS SECTIONSECTION: section-nameCLASS: class-nameMODULE: filename (modulename)A specified section that was erroneously processed has a code or data content. Thissection contents are not available.


8


121 IMPROPER FIXUPMODULE: filename (modulename)SECTION: section-nameCLASS: class-nameOFFSET: section-addressAfter evaluation of absolute fixups, an address is not accessible. The improperaddress along with the specific module name, partial section, and section offsetaddress are displayed. The fixup is not processed.

122 CANNOT FIND MODULEMODULE: filename (modulename)The module specified in the invocation line cannot be found in the input file.

123 REGISTERBANK DOES NOT FITREGBANK: registerbank_nameThe specified register bank does not fit into physical 166/167 memory.

124 INTERRUPT NUMBER ALREADY USEDOne interrupt or trap number is assigned to several interrupt procedures. The usageof the interrupt numbers can be verified in the L166 listing file.

125 INTERRUPT NUMBER NOT DEFINEDFor an interrupt procedure is an interrupt or trap number not defined. The usage of theinterrupt numbers can be verified in the L166 listing file.

126 GROUP CONTAINS ERRONEOUS SECTIONSGROUP: group-name (GRP number)The specified group contains a section which is processed with an error.

127 UNRESOLVED EXTERNAL SYMBOLSYMBOL: external-nameMODULE: filename (modulename)The specified external symbol, requested in the specified module, has nocorresponding PUBLIC symbol in any of the input files.

128 REFERENCE MADE TO UNRESOLVED EXTERNALSYMBOL: external-nameMODULE: filename (modulname)ADDRESS: code-addressThe specified unresolved external symbol is referenced at the specified code address.

129 SECTION DOES NOT FIT WITHIN PAGE BOUNDARYSECTION: section-nameCLASS: class-nameThe specified section in not located within one data page (16 KB block).

130 DUPLICATE TASK NUMBERTASK1: task-nameTASK2: task-nameTASKID: task-id-numberTwo RTX166 tasks are assigned to the same task_id_number. This is not legal.

131 ILLEGAL PRIORITY FOR TASKTASK: task-nameTASKID: task-id-numberThe priority for the specified task is not legal.


8


132 ILLEGAL TASKID: RTX166 TINY SUPPORTS ONLY 32 TASKSTASK: task-nameTASKID: task-id-numberYou have assigned a task_id_number in an RTX166 Tiny application which is higherthan 32.

133 MULTIPLE TGROUP DEFINITIONS WITH SAME NAMEMODULE: filename (modulname)TGROUP: tgroup-nameThere are two input files with the same tgroup name in this application.

Fatal Errors


201 INVALID COMMAND LINE SYNTAXpartial command lineA syntax error is detected in the command line. The command line is displayed up toand including the point of error.

202 INVALID COMMAND LINE, TOKEN TOO LONGpartial command lineThe command line contains a token that is too long. The command line is displayedup to and including the point of error.

203 EXPECTED ITEM MISSINGpartial command lineAn expected item is missing in the command line. The command line is displayed upto and including the point of error.

204 INVALID KEYWORDpartial command lineThe invocation line contains an invalid keyword. The command line is displayed up toand including the point of error.

205 CONSTANT TOO LARGEpartial command lineA constant in the invocation line is larger than 0FFFFH. The command line isdisplayed up to and including the point of error.

206 INVALID CONSTANTpartial command lineA constant in the invocation line is invalid (example a hexadecimal number with aleading letter). The command line is displayed up to and including the point of error.

207 INVALID NAMEpartial command lineA module, section, class or group name is invalid. The command line is displayed upto and including the point of error.

208 INVALID FILENAMEpartial command lineA filename is invalid. The command line is displayed up to and including the point oferror.


8


209 FILE USED IN CONFLICTING CONTEXTSFILE: filenameA specified filename is used for multiple files or used as an input as well as an outputfile.

210 I/O ERROR ON INPUT FILE:system error messageFILE: filenameAn I/O error is detected by accessing an input file. A detailed error description of theEXCEPTION messages is described afterwards.

211 I/O ERROR ON OUTPUT FILE:system error messageFILE: filenameAn I/O error is detected by accessing an output file. A detailed error description of theEXCEPTION messages is described afterwards.

212 I/O ERROR ON LISTING FILE:system error messageFILE: filenameAn I/O error is detected by accessing a listing file. A detailed error description of theEXCEPTION messages is described afterwards.

213 I/O ERROR ON REGFILE:system error messageFILE: filenameAn I/O error is detected by accessing the register definition file. A detailed errordescription of the EXCEPTION messages is described afterwards.

214 INPUT PHASE ERRORMODULE: filename (modulename)This error occurs when L166 encounters different data during pass two. This errorcould be the result of an assembly error.

215 CHECK SUM ERRORMODULE: filename (modulename)The check sum does not correspond to the contents of the file.

216 INSUFFICIENT MEMORYThe memory available for the execution of L166 is used up.

217 NO MODULE TO BE PROCESSEDNo module to be processed is found in the invocation line.

218 NOT AN OBJECT FILEFILE: filenameThe specified file is not an object file.

219 NOT AN 80166 OBJECT FILEFILE: filenameThe specified file is not a valid 166/167 object file.

220 INVALID INPUT MODULEFILE: filenameThe specified input module is invalid. This error could be the result of an assemblererror.

221 MODULE SPECIFIED MORE THAN ONCEpartial command lineThe invocation line contains the specified module more than once. The command lineis displayed up to and including the point of error.


8


222 SECTION/CLASS/GROUP SPECIFIED MORE THAN ONCEpartial command lineThe invocation line contains a section, class or group name more than once. Thecommand line is displayed up to and including the point of error.

224 DUPLICATE KEYWORD OR CONFLICTING CONTROLpartial command lineThe same keyword is contained in the invocation line more than once or contradictswith other keywords. The command line is displayed up to and including the point oferror.

225 ADDRESS ARE NOT IN ASCENDING ORDERpartial command lineThe base addresses for the sections or groups are not stated in ascending orderduring the L166 control directive. The command line is displayed up to and includingthe point of error.

226 SEGMENT ADDRESS INVALID FOR CONTROLpartial command lineThe base addresses for the segments are invalid for the location control. Thecommand line is displayed up to and including the point of error.

227 PARAMETER OUT OF RANGEpartial command lineThe specified value for the PAGEWIDTH or PAGELENGTH parameter is out of theacceptable range. The command line is displayed up to and including the point oferror.

228 MORE THAN 255 TGROUPSpartial command lineThe L166 invocation line contains more than 255 TGROUP braces '{', '}'. Thecommand line is displayed up to and including the point of error.

229 INTERNAL PROCESS ERRORL166 detects an internal processing error. Please contact your distributor.

230 SYMBOL SPECIFIED MORE THAN ONCEpartial command lineThe invocation line contains more than one start address for unnamed segment group.The command is displayed up to and including the point of error.

232 CANNOT PROCESS OBJECT FILES WITH TGROUPSFILE: filenameThe specified input file contains already TGROUPS and cannot be processedanymore by L166.

235 USE RTX166 SWITCHThe application uses RTX166 task definitions. This requires to specify the RTX166 orRTX166TINY directive.

236 TGROUPS AND REGFILE NOT ALLOWED IN COMBINATIONYou cannot use TGROUPS and the REGFILE in the same time application.

237 DPP3 MUST POINT TO PAGE 3partial command lineThe DPP3 register is not assigned to PAGE 3 with the DPPUSE directive. The DPP3must always point to page 3 to allow SFR access.

238 DPP ALREADY LOADED WITH A DIFFERENT PAGE VALUEpartial command lineA DPP register is already loaded with a different value due to the previous rangespecification in the DPP directive.


8


239 DPPUSE MUST BE GIVEN FOR NDATA & NCONST GROUPpartial command lineThe DPPUSE directive contains only a specification for NDATA or NCONST; howeveryou must always specify both group ranges.

250 CODE SIZE LIMIT IN RESTRICTED VERSION EXCEEDEDYou have reached the code size limit of the C166 Lite or Evaluation Version.

251 RESTRICTED MODULE IN LIBRARY NOT SUPPORTEDA library contains a module which is translated with a code size restricted version ofA166 or C166.

252 LINKONLY NOT SUPPORTED IN RESTRICTED VERSIONThe LINKONLY directive cannot be used with a code size restricted version.

Exception Messages

With some L166 error messages the exact reason of the error is additionallydisplayed with the EXCEPTION message. The EXCEPTION messages refer tothe cause of the errors, recognized by the operating system. These possible L166EXCEPTION messages are listed below:

Exception Exception Message and Description

0021H PATH OR FILE NOT FOUNDThe specified path or filename is missing.

0026H ILLEGAL FILE ACCESSAn attempt was made to write to or delete a write-protected file.

0029H ACCESS TO FILE DENIEDThe file indicated is a directory.

002AH I/O-ERRORThe drive being written to is either full or the drive was not ready.

0101H ILLEGAL CONTEXTAn attempt was made to access a file in an illegal context. Example the printer (:LP:)was opened for reading.


8

Application ExampleThis section describes a short 166/167 program, developed with C166 Compiler,A166 Assembler and L166 Linker/Locator. With this program the principle ofmodular program development and use of the L166 is explained.

The program, that should only indicate the possible techniques of programdevelopment, calculates the sum of two input numbers (which are read with thelibrary function ‘getchar’) and displays the result via the C function ‘printf’. Itconsists of three modules which should be translated by using the followinginvocations:

C166 CSAMPLE1.C DEBUGC166 CSAMPLE2.C DEBUGA166 CSAMPLE3.A66 DEBUG

The parameter DEBUG allows the complete symbol information from parts of theprogram, to be included in the object file. Additionally the files are processed bythe L166 Linker/Locator. The invocation for the Linker/Locator is:

L166 @CSAMPLE.L66

The L166 input line is read from the file CSAMPLE.L66. The content of this fileis:

CSAMPLE1.OBJ, CSAMPLE2.OBJ, CSAMPLE3.OBJ CLASSES (NCODE (1000H - 3FFFH)) RESERVE (8H - 0BH, 088H - 08BH, 0B8H - 0BBH) IXREF

The executable 166 program is stored with in the file CSAMPLE1. This file maybe immediately loaded and processed by dScope and/or after transfer with OH166burned into an EPROM.

The directive CLASSES directs the program code to the address range1000H-3FFFH. The RESERVE directive reserves the interrupt vectors requiredby Monitor-166.

The directive IXREF generates a symbol cross reference report of all public andexternal symbols in the listing file of the Linker/Locator (SAMPLE1.M66).

The following displays the listing files of the C166 Compiler and of the L166Linker/Locator.


8

This sample program can also be generated by using the BATCH fileCSAMPLE.BAT.

CSAMPLE1.C

C166 COMPILER V1.00, CSAMPLE1 06/05/92 14:05:15 PAGE 1

DOS C166 COMPILER V1.00, COMPILATION OF MODULE CSAMPLE1OBJECT MODULE PLACED IN CSAMPLE1.OBJCOMPILER INVOKED BY: E:\C166P\BIN\C166.EXE CSAMPLE1.C DEBUG

stmt level source

1 /* CSAMPLE1.C: C166 COMPILER Sample Program */ 2 /* Copyright KEIL ELEKTRONIK GmbH, 1992 */ 3 4 #include <stdio.h> /* define I/O functions*/ 5 6 extern int getnumber (); 7 extern output (int); 8 extern void serinit (void); 9 10 main () { /* main program */ 11 1 int number1, number2, result; /* operation registers */ 12 1 bit operation; /* define operation */ 13 1 14 1 serinit (); /* serial port control */ 15 1 16 1 printf ("\n\nC166 COMPILER demostartion program\n\n"); 17 1 18 1 while (1) { /* repeat forever */ 19 2 number1 = getnumber (); /* read number1 */ 20 2 number2 = getnumber (); /* read number2 */ 21 2 printf ("Input operation: '+' (ADD) or '-' (SUB) ? "); 22 2 operation = (getchar () == '+'); /* get operation */ 23 2 output (operation ? (number1 + number2) /* perform operation*/ 24 2 : (number1 - number2) ); 25 2 } 26 1 }

MODULE INFORMATION: INITIALIZED UNINITIALIZED CODE SIZE = 78 ------ NEAR-CONST SIZE = 82 ------ FAR-CONST SIZE = ------ ------ NEAR-DATA SIZE = ------ ------ FAR-DATA SIZE = ------ ------ IDATA-DATA SIZE = ------ ------ SDATA-DATA SIZE = ------ ------ BDATA-DATA SIZE = ------ ------ BIT SIZE = ------ ------ INIT'L SIZE = ------ ------END OF MODULE INFORMATION.

C166 COMPILATION COMPLETE. 0 WARNING(S), 0 ERROR(S)


8

CSAMPLE2.C

C166 COMPILER V1.00, CSAMPLE2 06/05/92 14:05:17 PAGE 1

DOS C166 COMPILER V1.00, COMPILATION OF MODULE CSAMPLE2OBJECT MODULE PLACED IN CSAMPLE2.OBJCOMPILER INVOKED BY: E:\C166P\BIN\C166.EXE CSAMPLE2.C DEBUG

stmt level source

1 /* CSAMPLE2.C: C166 COMPILER Sample Program */ 2 /* Copyright KEIL ELEKTRONIK GmbH, 1992 */ 3 4 #include <stdio.h> /* define I/O functions */ 5 6 getline (char *line) { 7 1 while ((*line++ = getchar()) != '\n'); 8 1 } 9 10 int atoi (char *line) { 11 1 bit sign; 12 1 int number; 13 1 14 1 /* skip white space */ 15 1 for ( ; *line == ' ' || *line == '\n' || *line == '\t'; line++); 16 1 17 1 /* establish sign */ 18 1 sign = 1; 19 1 if (*line == '+' || *line == '-') sign = (*line++ == '+'); 20 1 21 1 /* compute decimal value */ 22 1 for (number=0; *line >= '0' && *line <= '9'; line++) 23 1 number = (number * 10) + (*line - '0'); 24 1 25 1 return (sign ? number : -number); 26 1 } 27 28 unsigned int getnumber () { 29 1 char line [40]; 30 1 31 1 printf ("Input Number ? "); 32 1 getline (line); 33 1 return (atoi (line)); 34 1 } 35 36 37 output (int number) { 38 1 printf ("\nresult: %d\n\n", number); 39 1 }

MODULE INFORMATION: INITIALIZED UNINITIALIZED CODE SIZE = 186 ------ NEAR-CONST SIZE = 30 ------ FAR-CONST SIZE = ------ ------ NEAR-DATA SIZE = ------ ------ FAR-DATA SIZE = ------ ------ IDATA-DATA SIZE = ------ ------ SDATA-DATA SIZE = ------ ------ BDATA-DATA SIZE = ------ ------ BIT SIZE = ------ ------ INIT'L SIZE = ------ ------END OF MODULE INFORMATION.


8

CSAMPLE3.A66

A166 MACRO ASSEMBLER CSAMPLE3 06/05/92 14:05:20 PAGE 1

DOS MACRO ASSEMBLER A166 V1.00OBJECT MODULE PLACED IN CSAMPLE3.OBJASSEMBLER INVOKED BY:E:\C166P\BIN\A166.EXE CSAMPLE3.A66 DEBUG

LOC OBJ LINE SOURCE

1 ; CSAMPLE3.A66: A166 ASSEMBLER Sample Program 2 ; Copyright KEIL ELEKTRONIK GmbH, 1992 3 4 5 $SEGMENTED 6 $CASE 7 8 PUBLIC serinit 9 ASSUME DPP3:SYSTEM 10 11 ?PR?SERINIT section code 'NCODE' 12 13 serinit proc near 14 15 ;******************************* 16 ;*** INIT SERIAL INTERFACE 0 *** 17 ;******************************* 180000 AFE2 19 BSET P3.10 ; PORT 3.10 OUTPUT LATCH (TXD)0002 AFE3 20 BSET DP3.10 ; PORT 3.10 DIRECTION CONTROL(TXD OUTPUT)0004 BEE3 21 BCLR DP3.11 ; PORT 3.11 DIRECTION CONTROL(RXD INPUT)0006 E7B68000 22 MOVB S0TIC,#080H ; SET TRANSMIT INTERRUPT FLAG000A E7B70000 23 MOVB S0RIC,#000H ; DELETE RECEIVE INTERRUPT FLAG000E E65A4000 24 MOV S0BG ,#0040H ; SET BAUDRATE TO 9600 BAUD0012 E6D81180 25 MOV S0CON,#8011H ; SET SERIAL MODE0016 CB00 26 RET 27 28 serinit endp 29 30 ?PR?SERINIT ENDS 31 32 end



?PR?SERINIT. . . . ---- ---- SECTIONDP3. . . . . . . . WORD FFC6H A SFRDPP3 . . . . . . . WORD FE06H A SFRP3 . . . . . . . . WORD FFC4H A SFRS0BG . . . . . . . WORD FEB4H A SFRS0CON. . . . . . . WORD FFB0H A SFRS0RIC. . . . . . . WORD FF6EH A SFRS0TIC. . . . . . . WORD FF6CH A SFRserinit. . . . . . NEAR 0000H R PUB SEC=?PR?SERINIT



8

Linking the Sample Program

L166 LINKER/LOCATOR V1.0 06/05/92 14:05:21 PAGE 1

DOS L166 LINKER/LOCATOR V1.0, INVOKED BY:E:\C166P\BIN\L166.EXE CSAMPLE1.OBJ, CSAMPLE2.OBJ, CSAMPLE3.OBJ CLASSES (NCODE(1000H-3FFFH))>> RESERVE (8H-0BH, 088H-08BH, 0B8H-0BBH) IXREF

CPU MODE: SEGMENTEDMEMORY MODEL: SMALL

INPUT MODULES INCLUDED: CSAMPLE1.OBJ (CSAMPLE1) COMMENT TYPE 128: C166 V1.00 CSAMPLE2.OBJ (CSAMPLE2) COMMENT TYPE 128: C166 V1.00 CSAMPLE3.OBJ (CSAMPLE3) COMMENT TYPE 128: A166 V1.00 C:\CL166\C166S.LIB (?C_STARTUP) COMMENT TYPE 128: A166 V1.00 C:\CL166\C166S.LIB (PRINTF) COMMENT TYPE 128: A166 V1.00 C:\CL166\C166S.LIB (GETCHAR) COMMENT TYPE 128: C166 V1.00 C:\CL166\C166S.LIB (PUTCHAR) COMMENT TYPE 128: A166 V1.00 C:\CL166\C166S.LIB (GETKEY) COMMENT TYPE 128: C166 V1.00

INTERRUPT PROCEDURES OF MODULE: CSAMPLE1 (CSAMPLE1)

INTERRUPT PROCEDURE INT INTERRUPT NAME=====================================================C_STARTUP 0 RESET

MEMORY MAP OF MODULE: CSAMPLE1 (CSAMPLE1)

START STOP LENGHT TYPE ALIGN TGR GRP COMB CLASS SECTION NAME===============================================================================00000H 00003H 00004H --- --- --- --- --- * INTVECTOR TABLE *00004H 00005H 00002H CONST WORD --- --- GLOB --- ?C_INITSEC00008H 0000AH 00003H --- --- --- --- --- * RESERVED MEMORY *0000BH 0005CH 00052H DATA BYTE --- 2 PUBL NCONST ?NC?CSAMPLE10005DH 0007AH 0001EH DATA BYTE --- 2 PUBL NCONST ?NC?CSAMPLE20007CH 00086H 0000BH DATA WORD --- 2 PRIV NCONST ?NC?PRINTF00088H 0008AH 00003H --- --- --- --- --- * RESERVED MEMORY *0008CH 00091H 00006H CONST WORD --- --- PRIV --- ?C_CLRMEMSEC000B8H 000BAH 00003H --- --- --- --- --- * RESERVED MEMORY *000BCH 00185H 000CAH CODE WORD --- --- PRIV ICODE ?C_STARTUP_CODE01000H 0104DH 0004EH CODE WORD --- 1 PUBL NCODE ?PR?CSAMPLE10104EH 01107H 000BAH CODE WORD --- 1 PUBL NCODE ?PR?CSAMPLE201108H 014D1H 003CAH CODE WORD --- 1 PRIV NCODE ?PR?printf014D2H 01501H 00030H CODE WORD --- 1 PUBL NCODE ?PR?GETCHAR01502H 01533H 00032H CODE WORD --- 1 PRIV NCODE ?PR?putchar01534H 01543H 00010H CODE WORD --- 1 PUBL NCODE ?PR?GETKEY01544H 0155BH 00018H CODE WORD --- --- PRIV NCODE ?PR?SERINIT04000H 04FFFH 01000H DATA WORD --- 3 PRIV NDATA ?C_USERSTACK


8

05000H 05000H 00001H DATA BYTE --- 3 PUBL NDATA0 ?ND0?GETCHAR0FA00H 0FBFFH 00200H --- --- --- --- --- * SYSTEM STACK *0FC00H 0FC1FH 00020H DATA WORD --- --- --- *REG* ?C_MAINREGISTERS

GROUP LIST OF MODULE: CSAMPLE1 (CSAMPLE1)

GROUP NAME TYPE TGR GRP CLASS SECTION NAME=============================================================NCODE CODE --- 1 NCODE ?PR?CSAMPLE1 NCODE ?PR?CSAMPLE2 NCODE ?PR?printf NCODE ?PR?GETCHAR NCODE ?PR?putchar NCODE ?PR?GETKEY

NCONST DATA --- 2 NCONST ?NC?CSAMPLE1 NCONST ?NC?CSAMPLE2 NCONST ?NC?PRINTF

NDATA DATA --- 3 NDATA ?C_USERSTACK NDATA0 ?ND0?GETCHAR

PUBLIC SYMBOLS OF MODULE: CSAMPLE1 (CSAMPLE1)

VALUE PUBLIC SYMBOL NAME REP TGR CLASS SECTION NAME===============================================================================0008CH ?C_CLRMEMSECSTART VAR --- --- ---00004H ?C_INITSECSTART VAR --- --- ---00000H ?C_PAGEDPP1 CONST --- --- ---00001H ?C_PAGEDPP2 CONST --- --- ---000BCH ?C_STARTUP LABEL --- ICODE ?C_STARTUP_CODE00000H RESET INTNO --- --- ---01534H _getkey LABEL --- NCODE ?PR?GETKEY05000H _ungetchar_ VAR --- NDATA0 ?ND0?GETCHAR01066H atoi LABEL --- NCODE ?PR?CSAMPLE2014D2H getchar LABEL --- NCODE ?PR?GETCHAR0104EH getline LABEL --- NCODE ?PR?CSAMPLE2010E2H getnumber LABEL --- NCODE ?PR?CSAMPLE201000H main LABEL --- NCODE ?PR?CSAMPLE1010FCH output LABEL --- NCODE ?PR?CSAMPLE20118EH printf LABEL --- NCODE ?PR?printf01502H putchar LABEL --- NCODE ?PR?putchar01544H serinit LABEL --- NCODE ?PR?SERINIT01176H sprintf LABEL --- NCODE ?PR?printf

SYMBOL TABLE OF MODULE: CSAMPLE1 (CSAMPLE1)

VALUE TYPE REP LENGTH TGR SYMBOL NAME=================================================01000H GLOBAL LABEL --- --- main

01000H BLOCK LVL=0 004EH --- main01002H BLOCK LVL=1 0048H ---0000EH SYMBOL REG --- --- number10000DH SYMBOL REG --- --- number200000H SYMBOL AUTO --- --- resultR15.00 SYMBOL BIT --- --- operation--- BLOCKEND LVL=1 --- ---01000H LINE --- --- --- #1001002H LINE --- --- --- #1401006H LINE --- --- --- #160100EH LINE --- --- --- #180100EH LINE --- --- --- #1901014H LINE --- --- --- #200101AH LINE --- --- --- #21


8

01022H LINE --- --- --- #2201036H LINE --- --- --- #2301048H LINE --- --- --- #2501048H LINE --- --- --- #180104AH LINE --- --- --- #26--- BLOCKEND LVL=0 --- ---0104EH PUBLIC LABEL --- --- getline010E2H PUBLIC LABEL --- --- getnumber010FCH PUBLIC LABEL --- --- output01066H PUBLIC LABEL --- --- atoi

0104EH BLOCK LVL=0 0018H --- getline0000DH SYMBOL REG --- --- line0104EH LINE --- --- --- #601052H LINE --- --- --- #701062H LINE --- --- --- #8--- BLOCKEND LVL=0 --- ---

01066H BLOCK LVL=0 007CH --- atoi00008H SYMBOL REG --- --- line01068H BLOCK LVL=1 0076H ---R15.00 SYMBOL BIT --- --- sign00006H SYMBOL REG --- --- number--- BLOCKEND LVL=1 --- ---01066H LINE --- --- --- #100106CH LINE --- --- --- #1501084H LINE --- --- --- #1801086H LINE --- --- --- #19010A6H LINE --- --- --- #22010AAH LINE --- --- --- #23010D4H LINE --- --- --- #25010DEH LINE --- --- --- #26--- BLOCKEND LVL=0 --- ---

010E2H BLOCK LVL=0 001AH --- getnumber010E6H BLOCK LVL=1 0010H ---00000H SYMBOL AUTO --- --- line--- BLOCKEND LVL=1 --- ---010E2H LINE --- --- --- #28010E6H LINE --- --- --- #31010EEH LINE --- --- --- #32010F2H LINE --- --- --- #33010F6H LINE --- --- --- #34--- BLOCKEND LVL=0 --- ---

010FCH BLOCK LVL=0 000CH --- output00008H SYMBOL REG --- --- number010FCH LINE --- --- --- #37010FCH LINE --- --- --- #3801106H LINE --- --- --- #39--- BLOCKEND LVL=0 --- ---01544H PUBLIC LABEL --- --- serinit

01544H BLOCK LVL=0 0018H --- serinit01544H LINE --- --- --- #1901546H LINE --- --- --- #2001548H LINE --- --- --- #210154AH LINE --- --- --- #220154EH LINE --- --- --- #2301552H LINE --- --- --- #2401556H LINE --- --- --- #250155AH LINE --- --- --- #2601544H SYMBOL LABEL --- --- serinit--- BLOCKEND LVL=0 --- --- : : : : : : : : : : : : : : : : : : : : : : : :


8

: : : : : :

INTER-MODULE CROSS-REFERENCE LISTING

NAME . . . . . . . REP TGR MODULE NAMES=========================================

?C_CLRMEMSECSTART. VAR --- ** L166 GENERATED ** ?C_STARTUP?C_INITSECSTART. . VAR --- ** L166 GENERATED ** ?C_STARTUP?C_PAGEDPP1. . . . CONST --- ** L166 GENERATED ** ?C_STARTUP?C_PAGEDPP2. . . . CONST --- ** L166 GENERATED ** ?C_STARTUP?C_STARTUP . . . . LABEL --- ?C_STARTUP CSAMPLE1RESET. . . . . . . INTNO --- ?C_STARTUP_getkey. . . . . . LABEL --- GETKEY GETCHAR_ungetchar_. . . . VAR --- GETCHARatoi . . . . . . . LABEL --- CSAMPLE2getchar. . . . . . LABEL --- GETCHAR CSAMPLE1 CSAMPLE2getline. . . . . . LABEL --- CSAMPLE2getnumber. . . . . LABEL --- CSAMPLE2 CSAMPLE1main . . . . . . . LABEL --- CSAMPLE1 ?C_STARTUPoutput . . . . . . LABEL --- CSAMPLE2 CSAMPLE1printf . . . . . . LABEL --- PRINTF CSAMPLE1 CSAMPLE2putchar. . . . . . LABEL --- PUTCHAR GETCHAR PRINTFserinit. . . . . . LABEL --- CSAMPLE3 CSAMPLE1sprintf. . . . . . LABEL --- PRINTF

L166 RUN COMPLETE. 0 WARNING(S), 0 ERROR(S)


8


AAppendix A. LIB166 Library Manager

The LIB166 library manager lets you create and maintain library files. A libraryfile is a formatted collection of one or more object files. Library files provide aconvenient method of referencing a large number of object files and can be used bythe L166 linker/locator.

The LIB166 library manager lets you create library files, add object modules,remove object modules, and list library file contents. The LIB166 library managercan be controlled interactively or from the command line.

Using LIB166To invoke the LIB166 library manager from the DOS prompt, type LIB166 alongwith an optional library manager command. The command line must be enteredaccording to the following format:

LIB166 �command�

where command may be a single library manager command. To enter more thanone command, append the ampersand character (‘&’) to the end of the LIB166library manager command line.

Interactive ModeIf no command is entered on the command line, or if the ampersand character isincluded at the end of the line, the LIB166 library manager enters interactivemode. The LIB166 library manager displays an asterisk character (‘*’) to signalthat it is in interactive mode and is waiting for input.

Any of the LIB166 library manager commands may be entered on the commandline or after the * prompt when in interactive mode.

Type EXIT to leave the LIB166 library manager interactive mode.

230 Appendix A. LIB166 Library Manager

ACommand SummaryThe following table lists the commands that are available for the LIB166 librarymanager. All of these commands are described in detail in the sections that follow.

Command Abbreviation Description

ADD A Adds an object module to the library file.

CREATE C Creates a new library file.

DELETE D Removes an object module from a library file.

EXIT E Exits the interactive mode of the LIB166 library manager.

HELP H Displays help information for the LIB166 library manager.

LIST L Displays module and public symbol information stored in alibrary file.


ACreating a Library

The CREATE command directs the LIB166 library manager to create a new,empty library file. The CREATE command may be entered on the command line,or at the * prompt in interactive mode, and must have the following format:

CREATE libfile

where libfile is the name of the library file to create. The name of the library filemust include the file extension. Usually, .LIB is the extension that is used forlibrary files.

Example:LIB166 CREATE MYFILE.LIB

* CREATE FASTMATH.LIB


AAdding Object Modules

The ADD command instructs the LIB166 library manager to add one or moreobject modules to a specified library file. The ADD command must be entered inthe following format:

ADD filename �( modulename , …) � �, … � TO libfile

where

filename is the name of an object file or library file. You may specifyseveral files for each ADD command. Each file must beseparated by a comma.

modulename is the name of a module in a library file. If you do not want toadd the entire contents of a library, you may select the modulesthat you want to add. Module names are specified immediatelyfollowing the filename , must be enclosed in parentheses, andmust be separated by commas.

libfile is the name of an existing library file. The specified objectmodules are added to this library.

The ADD command may be entered on the command line or after the * prompt ininteractive mode as shown in the following example.

LIB166 ADD MOD1.OBJ, UTIL.LIB(FPMUL, FPDIV) TO NEW.LIB

* ADD FPMOD.OBJ TO NEW.LIB


ARemoving Object Modules

The DELETE command removes object modules from a library file. Thiscommand must be entered in the following format:

DELETE libfile ( modulename �, modulename …�)

where

libfile is the name of an existing library file. The specified objectmodules are removed from this library.

modulename is the name of a module in the library file that you want toremove. Module names are entered in parentheses and areseparated by commas.

The DELETE command may be entered on the command line or after the *prompt in interactive mode as shown in the following example.

LIB166 DELETE NEW.LIB (MODUL1)

* DELETE NEW.LIB (FPMULT, FPDIV)


AListing Library Contents

Use the LIST command to direct the LIB166 library manager to generate a listingof the object modules that are stored in a library file. LIST may be specified onthe command line or after the * prompt in interactive mode. This command hasthe following format:

LIST libfile �TO listfile � �PUBLICS�

where

libfile is the library file from which a module list is generated.

listfile is the file where listing information is written. If no listfile isspecified, the listing information is displayed on the screen.

PUBLICS specifies that public symbols are included in the listing.Normally, only module names are listed.

Example:*LIST UNI.LIB TO UNI.LST <cr>

>LIB166 L UNI.LIB PUBLICS <cr>

Example of the LIB166 output:LIBRARY: UNI.LIB SIMPLE SUBTRACTION ADDITION FPMUL MULTIPLICATION FPDIV DIVISION


AHelp Information

The HELP command directs the LIB166 library manager to display the availablelibrary manager commands. This command may be entered on the command lineor at the * prompt in interactive mode. The LIB166 library manager respondswith the following text:

ADD {file[(module[,...])]} [,...] TO library_fileCREATE library_fileDELETE library_file(module[,...])EXITHELPLIST library_file [TO file] [PUBLICS]


ALIB166 Error MessagesThis chapter lists the fatal and non-fatal errors that may be generated by theLIB166 library manager during execution. Each section includes a briefdescription of the message, as well as corrective actions you can take to eliminatethe error or warning condition.

Fatal Errors

Fatal errors cause immediate termination of the LIB166 library manager. Theseerrors normally occur as the result of a corrupt library or object file, or as a resultof a specification problem involving library or object files.


215 CHECK SUM ERRORFILE: filenameThe checksum for filename is incorrect. This usually indicates a corrupt file.

216 INSUFFICIENT MEMORYThere is not enough memory for the LIB166 library manager to successfully completethe requested operation.

217 NOT A LIBRARYFILE: filenameThe filename that was specified is not a library file.

219 NOT AN 80C166 OBJECT FILEFILE: filenameThe filename that was specified is not a valid 80C166 object file.

222 MODULE SPECIFIED MORE THAN ONCEMODULE: filename (modulename)The specified modulename is included on the command line more than once.


AErrors

The following errors cause immediate termination of the LIB166 library manager.These errors usually involve invalid command line syntax or I/O errors.


201 INVALID COMMAND LINE SYNTAXA syntax error was detected in the command. The command line is displayed up toand including the point of error.

202 INVALID COMMAND LINE, TOKEN TOO LONGThe command line contains a token that is too long for the LIB166 library manager toprocess.

203 EXPECTED ITEM MISSINGThe command line is incomplete. An expected item is missing.

205 FILE ALREADY EXISTSFILE: filenameThe filename that was specified already exists. This error is usually generated whenattempting to create a library file that already exists. Erase the file or use a differentfilename.

208 MISSING OR INVALID FILENAMEA filename is missing or invalid.

209 UNRECOGNIZED COMMANDA command is unrecognized by the LIB166 library manager. Make sure you correctlyspecified the command name.

210 I/O ERROR ON INPUT FILE:system error messageFILE: filenameAn I/O error was detected when accessing one of the input files. A detailed errordescription of the EXCEPTION messages is described in chapter 1.

211 I/O ERROR ON LIBRARY FILE:system error messageFILE: filenameAn I/O error was detected when accessing a library file. A detailed error description ofthe EXCEPTION messages is described in chapter 1.

212 I/O ERROR ON LISTING FILE:system error messageFILE: filenameAn I/O error was detected when accessing a listing file. A detailed error description ofthe EXCEPTION messages is described in chapter 1.

213 I/O ERROR ON TEMPORARY FILE:system error messageFILE: filenameAn I/O error was detected when a temporary file was being accessed. A detailed errordescription of the EXCEPTION messages is described in chapter 1.

220 INVALID INPUT MODULEFILE: filenameThe specified input module is invalid. This error could be the result of an assemblererror or could indicate that the input object file is corrupt.


AError Error Message and Description

221 FILE SPECIFIED MORE THAN ONCEFILE: filenameThe filename specified was included on the command line more than once.

223 CANNOT FIND MODULEMODULE: filename (modulename)The modulename specified on the command line was not located in the object orlibrary file.

224 ATTEMPT TO ADD DUPLICATE MODULEMODULE: filename (modulename)The specified modulename already exists in the library file and cannot be added.

225 ATTEMPT TO ADD DUPLICATE PUBLIC SYMBOLMODULE: filename (modulename)PUBLIC: symbolnameThe specified public symbolname in modulename already exists in the library file andcannot be added.


B

Appendix B. OH166 Object-HexConverter

The OH166 Object-HEX Converter creates an Intel HEX file from an absoluteobject file. Program code stored in the absolute object file is converted intohexadecimal values and is output to a file in Intel HEX file format. The IntelHEX file may then be used by an EPROM programmer or emulator.

Using OH166To invoke the OH166 object-HEX converter from the DOS prompt, type OH166

along with the name of the absolute object file. The OH166 command line mustbe entered in the following format:

OH166 abs_file �H167��RANGE(start–end ) ��OFFSET(offset ) ��FLASH(fill_byte ) �

where:

abs_file is the name of the absolute object file that the L166 linker/locatorgenerated.

H167 specifies Intel HEX-386 format for the Intel HEX file. Thedefault format of OH166 is Intel HEX-86 format.

RANGE specifies the address range of data in the abs_file to convertand store in the HEX file. The default range is 0-0xFFFFFF.

start is the starting address of the address range. This address must beentered in C hexadecimal notation, for example: 0x10000.

end is the end address of the address range. This address must beentered in C hexadecimal notation, for example: 0x1FFFF.

OFFSET specifies an offset which is added to the address stored in theabs_file.

FLASH The HEX file is sorted in ascending order. Unused bytes in theRANGE are filled with the fill_byte specified with theFLASH directive. The sorted HEX file can be downloaded to166/167 flash devices.

240 Appendix B. OH166 Object-Hex Converter

B

OH166 Error MessagesThis section lists the errors and warnings you may encounter when using theOH166 Object-HEX Converter. Each error and warning lists the message and abrief description as well as corrective actions you can take to eliminate the error orwarning condition.

*** ERROR: ‘<filename>’ - DISK FILE REQUIRED

The specified file is not a disk file. The object file must exist on either a harddisk or diskette. The console CON:, COM1: or similar devices are not allowedas input files.

*** ERROR: ADDRESS SPACE OUTSIDE INTEL-H86 RANGE, USE ‘H167’SWITCH

The object file contains addresses above 1MB; in this case the H167 optionmust be selected to generate Intel Hex 386 files.

*** ERROR: CAN’T CREATE FILE ‘<filename>’

The specified file can not be created. This may be a case where a disk or harddisk is full or if the file already exists and is write protected.

*** ERROR: CAN’T OPEN FILE ‘<filename>’

OH166 failed to find or open the selected object file.

*** ERROR: ILLEGAL OMF166 RECORD <record-type>

The absolute object file contains an invalid record type.

*** I/O-ERROR ON FILE <filename>*** OH166 ABORTED

While reading from a object file or writing to a HEX file an error occurred.

*** WARNING: UNRESOLVED EXTERNAL(S)

The absolute object file still contains unresolved external definitions. Probablythe file has not yet been processed by L166 without error messages. Thereforethe H86 file can be invalid.

*** WARNING: UNRESOLVED REFERENCE(S)

The absolute object file still contains unresolved references definitions.Probably the file has not yet been processed by L166 without error messages.Therefore the H86 file can be invalid.


B

Intel HEX File FormatThe Intel HEX file is an ASCII text file with lines of text that follow the IntelHEX file format. Each line in an Intel HEX file contains one HEX record. Theserecords are made up of hexadecimal numbers that represent machine languagecode and/or constant data. Intel HEX files are often used to transfer the programand data that would be stored in a ROM or EPROM. Most EPROMprogrammers or emulators can use Intel HEX files.

Record Format

An Intel HEX file is composed of any number of HEX records. Each record ismade up of five fields that are arranged in the following format:

:llaaaatt �dd... �cc

Each group of letters corresponds to a different field, and each letter represents asingle hexadecimal digit. Each field is composed of at least two hexadecimaldigits—which make up a byte—as described below:

: is the colon that starts every Intel HEX record.

ll is the record-length field that represents the number of data bytes(dd) in the record.

aaaa is the address field that represents the starting address forsubsequent data in the record.

tt is the field that represents the HEX record type, which may beone of the following:

00 data record01 end-of-file record02 8086 segment address record04 extended linear address record.

dd is a data field that represents one byte of data. A record mayhave multiple data bytes. The number of data bytes in the recordmust match the number specified by the ll field.

cc is the checksum field that represents the checksum of the record.The checksum is calculated by summing the values of all


B

hexadecimal digit pairs in the record modulo 256 and taking thetwo’s complement.

Data Record

The Intel HEX file is made up of any number of data records that are terminatedwith a carriage return and a linefeed. Data records appear as follows:

:10246200464C5549442050524F46494C4500464C33

where:

10 is the number of data bytes in the record.

2462 is the address where the data are to be located in memory.

00 is the record type 00 (a data record).

464C...464C is the data.

33 is the checksum of the record.

End-of-File (EOF) Record

An Intel HEX file must end with an end-of-file (EOF) record. This record musthave the value 01 in the record type field. An EOF record always appears asfollows:

:00000001FF

where:


0000 is the address where the data are to be located in memory. Theaddress in end-of-file records is meaningless and is ignored. Anaddress of 0000h is typical.

01 is the record type 01 (an end-of-file record).

FF is the checksum of the record and is calculated as01h + NOT(00h + 00h + 00h + 01h) .


B

8086 Segment Address Record

The Intel HEX file contains 8086 segment address records to specify a paragraphnumber (one paragraph is 16 Bytes). This record type is replaced by an extendedlinear address record if you are using the H167 directive. The paragraph numberis used as offset for all subsequent data records in the HEX file. 8086 segmentaddress records appear as follows:

:020000021000EC

where:


0000 is always 0 in a extended 8086 segment record.

02 is the record type 02 (an extended linear address record).

1000 is the paragraph number (address: 0x10000).

EC is the checksum of the record.

Extended Linear Address Record

The Intel HEX file contains extended linear address records when the H167directive is used. This record specifies the two most significant bytes (bits 16-31)of the absolute address. This address offset is used for all subsequent data recordsin the HEX file. Extended linear address records appear as follows:

:0200000400FFFB

where:


0000 is always 0 in a extended 8086 segment record.

04 is the record type 04 (an extended linear address record).

00FF is the high word of the address offset (0x00FF0000).

FB is the checksum of the record.


B

Example Intel HEX File

Following is an example of a complete Intel HEX file:

:020000021000EC:10C20000E0A5E6F6FDFFE0AEE00FE6FCFDFFE6FD93:10C21000FFFFF6F50EFE4B66F2FA0CFEF2F40EFE90:10C22000F04EF05FF06CF07DCA0050C2F086F097DF:10C23000F04AF054BCF5204830592D02E018BB03F9:020000020000FC:04000000FA00000200:00000001FF


C

Appendix C. RTX166 TINYThis appendix describes the functions and the usage of the RTX166 Tiny real-timeoperating system.

RTX166 is a multitasking real-time operating system for the 166/167 family.RTX166 simplifies system and software design of complex and time-criticalprojects. RTX166 is a powerful tool to manage several jobs (tasks) on a singleCPU.

RTX166 is available in two versions:

RTX166 Allows round-robin and preemptive task switching with 128task priorities and can be operated with interrupt functions inparallel. RTX166 supports signal passing; message passingwith a mailbox system and semaphores. The os_waitfunction of RTX166 can wait for the following events:interrupt; timeout; signal from task or interrupt; messagefrom task or interrupt; semaphore.

RTX166 Tiny Is a subset of RTX166 and can be implemented on a single-chip system without off-chip memory. However, programusing RTX166 Tiny can access off-chip memory. RTX166Tiny allows round-robin task switching, supports signalpassing and can be operated with interrupt functions inparallel. The os_wait function of RTX166 Tiny can wait forthe following events: timeout; interval; signal from task orinterrupt.

This documentation only describes the options of RTX166 Tiny.

IntroductionMany microcontroller applications require simultaneous execution of several jobs(tasks). RTX166 Tiny offers a flexible method to allocate the available processortime to several tasks and can be implemented on all 166/167 derivatives.

A standard C program starts its execution with the function main. This mainfunction is usually an endless loop in an 166/167 application.

246 Appendix C. RTX166 TINY

C

Simple 80C166 Program Written in C.int counter;

main () { while (1) { counter++; }}

This endless loop can be considered as a single task which is executedcontinuously.

Round-Robin Task Switching

RTX166 Tiny allows a quasi-parallel, simultaneous execution of several tasks.Each task is executed for a predefined timeout period. A timeout suspends theexecution of a task and causes another task to be started. The following exampleuses this round-robin task switching technique.

Simple C Program using RTX166#include <rtx166t.h> /* Definitions for RTX166 Tiny */int counter0;int counter1;

job0 () _task_ 0 {

os_create_task (1); /* Mark task 1 as "ready" */

while (1) { /* Endless loop */ counter0++; /* Increment counter 0 */ }}

job1 () _task_ 1 { while (1) { /* Endless loop */ counter1++; /* Increment counter 1 */ }}

RTX166 starts the program with task 0 (assigned to job0). The functionos_create_task marks task 1 (assigned to job1) as ready for execution. These twofunctions are simple count loops. After the timeout period has been completed,RTX166 interrupts job0 and begins execution of job1. This function even reachesthe timeout and the system continues with job0.


C

The os_wait Function

The os_wait function provides a more efficient way to allocate the availableprocessor time to several tasks. os_wait interrupts the execution of the currenttask and waits for the specified event. During the time in which a task waits foran event, other tasks can be executed.

Wait for Timeout

RTX166 uses an 166/167 timer in order to generate cyclic interrupts (timer ticks).The simplest event argument for os_wait is a timeout, where the currentlyexecuting task is interrupted for the specified number of timer ticks. Thefollowing uses timeouts for the time delay.

Program with os_wait Function#include <rtx166t.h> /* Definitions for RTX166 Tiny */

int counter0;int counter1;

job0 () _task_ 0 {

os_create_task (1);

while (1) { counter0++; /* Increment counter 0 */ os_wait (K_TMO, 3, 0); /* Wait 3 timer ticks */ }}

job1 () _task_ 1 { while (1) { counter1++; /* Increment counter 1 */ os_wait (K_TMO, 5, 0); /* Wait 5 timer ticks */ }}

This program is similar to the previous example with the exception that job0 isinterrupted with os_wait after counter0 has been incremented. RTX166 waitsthree timer ticks until job0 is ready for execution again. During this time, job1 isexecuted. This function also calls os_wait with a timeout of 5 ticks. The result:counter0 is incremented every three ticks and counter1 is incremented every fivetimer ticks.


C

Wait for Signal

Another event for os_wait is a signal. Signals are used for task coordination: if atask waits with os_wait until another task issues a signal. If a signal waspreviously sent, the task is immediately continued.

Program with Wait for Signal.#include <rtx166t.h> /* Definitions for RTX166 Tiny */

int counter0;int counter1;

job0 () _task_ 0 {

os_create_task (1);

while (1) { if (++counter0 == 0) { /* On counter 0 overflow */ os_send_signal (1); /* Send signal to task 1 */ } }}

job1 () _task_ 1 { while (1) { os_wait (K_SIG, 0, 0); /* Wait for signal; no timeout */ counter1++; /* Increment counter 1 */ }}

In this example, task 1 waits for a signal from task 0 and therefore processes theoverflow from counter0.

Preemptive Task Switching

The full version of RTX166 provides preemptive task switching. This feature isnot included in RTX166 Tiny. It is explained here to provide a complete overviewof multitasking concepts.

In the previous example, task 1 is not immediately started after a signal hasarrived, but only after a timeout occurs for task 0. If task 1 is defined with ahigher priority than task 0, by means of preemptive task switching, task 1 isstarted immediately after the signal has arrived. The priority is specified in thetask definition (priority 0 is the default value).


C

Generating RTX166 Applications

RTX166 Tiny is completely integrated in C166. For this reason, the generation ofexecutable RTX166 applications is relatively easy. All examples listed arecomplete programs; assembler instructions must not be created. L166 selects theRTX166 used, checks the system consistency and produces task tables.

Generation Example:C166 EXAMPLE1.CL166 EXAMPLE1.OBJ RTX166TINY


C

RTX166 Tiny Technical Data� Max. 32 tasks can be defined. All tasks can be simultaneously active.

� Round-robin task switching (timeout can be configured).

� Wait function allows (all events can be combined):

� Wait for timeout.

� Wait for interval.

� Wait for signal from task or interrupt.

� Memory and hardware requirements:CODE memory: 1500 bytesDATA memory: 8 + 4 * number_of_tasks BytesTimer 0-6 as system clock (Timer 0 is default)

� Task switching time: 400-4000 states (depending on stack load)

� System clock (ticks): more than 5000 states (can be defined)

� Interrupt latency: 20 statesNote: timing is based on external ROM with no waitstates.1 state = 100ns @ 20MHz

RTX166 Tiny Functions

The following table illustrates all functions of RTX166 Tiny.

Function Meaning

isr_send_signal Send a signal to a task (call from interrupt).

os_clear_signal Delete a sent signal.

os_create_task Move a task to execution queue.

os_delay_task Wait for timeout.

os_delete_task Remove a task from execution queue.

os_running_task_id Return task ID of currently running task.

os_send_signal Send a signal to a task (call from tasks).

os_wait Wait for event.

os_wait_signal Wait for signal.


C

RTX166 Full Technical DataThe RTX166 Full technical data has been summarized for comparison purposes.However, RTX166 Full is not part of this package.

� Max. 256 tasks with task priority 0-127 can be defined and active.

� Preemptive and round-robin task switching (timeout can be configured).

� Wait function allows (all events can be combined):

� Wait for timeout.

� Wait for interrupt.

� Wait for signal from task or interrupt.

� Wait for message from task or interrupt.

� Wait for token (semaphore).

� Memory/hardware requirement:CODE memory: 6-35 KBytes (scaleable).DATA memory: 2-3 KBytes.

� Task switching time: < 400 states.

� Semaphores: Max. 256 semaphores.

� Mailbox system: 256 mailboxes (up to 16KB message size).

� CAN Interface: comes with CAN driver for C167C.

RTX166 Full Functions

The following table illustrates all functions of RTX166.

Function Meaning

isr_clear_signal Clear a signal to a task (called from interrupt functions).

isr_get_token Receive a token from a semaphore (called from interrupt).

isr_recv_message Receive a message from a mailbox (called from interrupt).

isr_reset_mailbox Delete a messages in a mailbox (called from interrupt).

isr_send_message Send a message to a mailbox (called from interrupt).

isr_send_signal Send a signal to a task (called from interrupt functions).

isr_send_token Send a token to a semaphore (called from interrupt).

isr_urgent_message Send an ‘urgent’ message to a mailbox (called from intrpt).


C

Function Meaning

os_attach_interrupt Assign task to interrupt source.

os_change_prio Change priority of running task.

os_check_mailbox Check free space for messages in a mailbox

os_check_pool Check free space in a memory pool.

os_check_timeout Check if timeout period is over.

os_clear_signal Clear a sent signal.

os_create_mailbox Create a mailbox

os_create_pool Define a memory pool.

os_create_semaphore Create and initialize a semaphore.

os_create_task Move a task to the execution queue (tasks becomes ready).

os_delay_task Wait for a specified number of ticks (timeout).

os_delete_mailbox Delete a mailbox

os_delete_semaphore Delete a semaphore.

os_delete_task Delete a task from the execution queue.

os_detach_interrupt Remove interrupt source assignment.

os_disable_isr Disable 166/167 hardware interrupts.

os_enable_isr Enable 166/167 hardware interrupts.

os_free_block Free a block from a memory pool.

os_get_block Get a block from a memory pool.

os_pass_task Suspend task (perform a task switch).

os_reset_mailbox Delete all messages in a mailbox.

os_running_task_id Return task ID of current running task.

os_running_task_prio Return task priority of current running task.

os_send_message Send a message to a mailbox.

os_send_signal Send a signal to a task (called from tasks).

os_send_token Send a token to a semaphore.

os_set_error_handler Define an alternative error handler function.

os_set_slice Define RTX clock frequency (ticks).

os_set_timeout Set a timeout period.

os_start_system Initialize and start RTX166.

os_urgent_message Send an ‘urgent’ message to a mailbox.

os_wait Generic RTX166 wait function.

os_wait_interrupt Wait for an interrupt.

os_wait_message Wait for a message in a mailbox.

os_wait_signal Wait for a signal.

os_wait_token Wait for a token from a semaphore.


C

Software RequirementsThe following software products are required to operate RTX166 Tiny:

� C166 Compiler Version 1.30 or later.

� L166 Linker/Locator Version 1.30 or later.

� A166 Macro Assembler Version 1.30 or later.

The RTX166 Tiny Library files (RTX166TT.LIB, RTX166TS.LIB,RTX166TL.LIB) must be stored in directory C166\LIB; the path for the C166runtime libraries must be set.

File RTX166T.H must be stored in directory C166\INC; the path for the C166INCLUDE files must be set.

Task ManagementEach RTX166 Tiny task is in one of the following task states.

State Description

DELETED Tasks which are not started are in the DELETED state.

READY Tasks which are waiting for execution are in the READYstate. After the currently running task has finishedprocessing, RTX166 Tiny starts the next task in theREADY state.

RUNNING The task currently being executed is in the RUNNINGstate. Only one task is in the RUNNING state at a time.

TIMEOUT Tasks which were interrupted by a round-robin timeoutare in the TIMEOUT state. This state is equivalent toREADY; however, a round-robin task switch is markeddue to internal operating procedures.

WAITING Tasks which are waiting for an event are in the WAITINGstate. If the event occurs which the task is waiting for,this task then enters the READY state.

A task may be waiting for one or more of the following types of events.


C

Event Description

INTERVAL Timeout interval which is started by the os_wait function.A wait time is also specified in this case in timer ticks. Incomparison to a timeout, the timer is not reset, however;the event “interval” therefore functions with a constantrunning timer. An interval can be used if the task is to beexecuted in synchronous intervals (i.e., in the case of aclock)).

SIGNAL Bit for task communication. A signal can be set orcleared. The os_wait function can wait for a signal.

TIMEOUT Time interval which is started by the os_wait function.The duration of the timeout is specified in timer ticks.RTX166 resets a timer internally. After completion of thetimer ticks, the task is ready for execution (READY)again.

Task Switching

The system section of RTX166 Tiny which assigns the processor a task is calledthe scheduler. The scheduler of RTX166 Tiny functions according to thefollowing rules:

1. A running task is interrupted if:

� The task calls the function os_wait and the specified event has not arrivedyet.

� The task is longer than the defined timeout in the state RUNNING . Whenthis happens, a round-robin task switch occurs.

2. Another task is started if:

� No other running (RUNNING) task exists.

� The task to be started is in the READY or TIMEOUT state.

The RTX166 Tiny scheduler continuously checks all tasks. The first availabletask in the READY or TIMEOUT state is started.

Example:

Task 1 and task 6 have the state “READY”. Task 3 is in the “RUNNING” state.If task 3 is interrupted, task 6 is executed next, since RTX166 Tiny begins thesearch for executable tasks beginning with task 4.


C

Task Declaration

C166 contains an extended function declaration for defining tasks. A task forRTX166 Tiny is declared as follows:

void function (void) _task_ <task_id>

� Tasks cannot return a function value (return type “void”).

� No parameters can be passed to tasks (“void” in parameter list).

� <task_id> is number assigned by the user (Task_ID) in the area 0-15. Eachtask must be assigned a unique non-recurring task_id. This task_id is requiredin diverse system functions for identifying the task.

NOTETo minimize the memory requirements of RTX166 Tiny, number your taskssequentially starting with 0.

Example:void example_1 (void) _task_ 8

C166 Specific SupportAlthough the generation of RTX166 Tiny applications is completely automated,note the following points when creating programs:

� Similar to other 80C166 programs, interrupts can be enabled and disabled.Timer 0 interrupt and the global interrupt enable flag must not be disabled.

� All C166 memory models can be used.

� All C166 standard library functions including floating point library can beused in all tasks without any restrictions.


C

Interrupt Handling

RTX166 Tiny can operate parallel with interrupt functions. In the case ofRTX166, the interrupts of the 80C166 derivative can also be managed by the real-time operating system. This is not possible with RTX166 Tiny.

Handling 166/167 Interrupt Control Registers

Similar to other 166/167 applications, the interrupt source must be enabled in thecontrol register in order to trigger an interrupt. RTX166 Tiny does not contain anymanagement for interrupts; for this reason, the interrupt enable is sufficient toprocess the interrupt.

NOTERTX166 Tiny already uses Timer 0 and enables the Timer 0 interrupt withILVL = 1 and GLVL = 0. Therefore, no other interrupt source should use thisinterrupt and group level. Disabling the Timer 0 interrupt or the all interrupts(via IEN ) is not permitted in RTX166 Tiny.

C166 Memory Models

A RTX166 Tiny application can essentially use all memory models supported byC166 (TINY, SMALL, COMPACT, MEDIUM and LARGE). The selectedmemory model only influences, however, the location of the application objects.The RTX166 Tiny system variables are always stored in registers or in the NEARmemory (NDATA class). Typical RTX166 Tiny application are normallyimplemented in the SMALL model.

Use of the C166 Run-Time Library

All C166 standard library functions including floating point operations can beused in all tasks without any restrictions.


C

RTX166 Tiny System FunctionsRTX166 Tiny functions can be directly called from C166. RTX166 Tinyprovides functions for task management, task communication, and other services.

This section contains an extensive description of all RTX166 Tiny systemfunctions. Each of the following descriptions includes the following points:

� Functional description

� Declaration in C166 (as contained in RTX166T.H)

� Parameter explanation

� Return value explanation

� Call example

� Cross reference to other calls

Name Assignment

The prefix of the system function name describes its application:

� System functions whose name starts with “os_” may be used exclusively bytasks.

� System functions whose name starts with “isr_” may be used exclusively byC166 interrupt procedures.

Return Values

Most system functions return a status as a function result. The status indicateswhether the function is executed successfully.

The description of the system functions explains the status information and itsmeaning. Zero is returned in most cases if the function executed successfully.

Include Files

The declaration of the RTX166 Tiny system functions and all constantdeclarations are contained in the h-file RTX166T.H. This h-file must be specified


C

in an INCLUDE statement at the start if the source program (#include<rtx166t.h>).


C

Function Overview

Task Management:

� os_create_task (task_id)

� os_delete_task (task_id)

� os_running_task_id ()

Signal Functions:

� os_send_signal (task_id)

� os_clear_signal (task_id)

� isr_send_signal (task_id)

Wait Functions:

� os_delay_task (timeout)

� os_wait (event_selector, timeout, 0)

� os_wait_signal ()


C

os_clear_signal

The os_clear_signal function clears the signal flag of a specified task. Thisfunction can be used to ensure defined start conditions of a task.

Prototype: int os_clear_signal (int task_id);

Parameter: task_id is the number of the task for which the signal flag isto be cleared.

Return value: 0: Signal flag was already cleared.1: Signal flag was set and is now successfully cleared.-1: The specified task does not exist.

See also: os_wait, os_send_signal, isr_send_signal

Example:void xyz_task (void) _task_ 8 { /* task code */

/* clear signal flag from task 5 */ os_clear_signal (5);

}


C

os_create_task

The os_create_task function starts a function defined with the C166 attribute_task_ as an RTX166 Tiny task function. The task is marked as ready forexecution (READY). The task is executed according to the rules described fortask switching.

Prototype: int os_create_task (int task_id);

Parameter: task_id identifies the task to be started. The same number asin the task declaration must be used (0-31).

Return value: 0: Task started successfully (no error).-1: Task could not be started; no task was declared with thisnumber (wrong number).

See also: os_delete_task

Example:void count_task (void) _task_ 2 { /* task code */}a

void first_task (void) _task_ 0{ /* Function 'count_task' is to be started */

if (os_create_task (2)) { /* error handling */ }

/* task code */}


C

os_delay_task

The os_delay_task function is a shorthand of the os_wait function where theevent specification is fixed to timeout (K_TMO ). During the time in which a taskis waiting for the timeout, other tasks can be executed. If the time period is over,the calling task gets the state ready for execution.

Prototype: int os_delay_task (unsigned int timer_ticks);

Parameter: timer_ticks determines the number of timer ticks which mustcomplete when waiting for timeout or interval. Thisparameter is insignificant if wait for timeout (K_TMO ) orwait for interval (K_IVL ) were not specified. The range ofpermissible values for timer_ticks is 0-65535.

Return value: TMO_EVENT: A timeout or interval has completed.

See also: os_wait

Example:void first_task (void) _task_ 0 { /* task code */

/* delay task for 100 timer ticks */ os_delay_task (100);

/* task code */}


C

os_delete_task

The os_delete_task function stops a task and sets the task to state “DELETED”.The task is deleted from the list of the executable tasks.

Prototype: int os_delete_task (int task_id);

Parameter: task_id identifies the task to be deleted. The same number asin the task declaration must be used. Only tasks that werepreviously started with os_create_task (exception: task 0 isstarted after reset), can be deleted with os_delete_task. Therunning task can also delete itself.

Return value: 0: Task was stopped successfully.-1: The specified task was not active or is not defined.

See also: os_create_task

NOTEIf a task deletes itself, a task switching subsequently isexecuted.

Example:void first_task (void) _task_ 0 { /* task code */

/* task stopped itself */ if (os_delete_task (0)) { /* error handling */ }}


C

os_running_task_id

Returns the Task_ID of the currently running task and the number which was usedin the task declaration. Using this system function, a C166 function can, forexample, determine the task from which it was called.

Prototype: int os_running_task_id (void);

Parameter: ---

Return value: 0-31; the task_ID of the task currently being executed by theprocessor is returned.

See also: os_create_task

Example:void xyz_task (void) _task_ 3 { unsigned char task_id;

/* task code */

/* check task_id of running task */ task_id = os_running_task_id (); /* task_id is set to 3 */

}


C

os_send_signal / isr_send_signal

Sends a signal to another task. If this task is already waiting for a signal, thiscauses it to be ready for execution again. Otherwise, the signal is stored in thesignal flag of the addressed task. If the signal flag of a task is already set whenthe os_wait function is called, the task is immediately continued whenevent_selector = K_SIG is given.

Prototypes: int os_send_signal (int task_id);int isr_send_signal (int task_id);

Parameter: task_id is the number of the task to which a signal is to besent.

Return value: 0: Signal was sent successfully.1: The signal flag was already set.-1: The specified task does not exist.

See also: os_wait, os_clear_signal, os_wait_signal

NOTEThe function os_send_signal may only be called from taskfunctions. The function isr_send_signal may only be calledfrom interrupt procedures.

Examples:void xyz_task (void) _task_ 8 { /* task code */

/* send signal to task 5 */ os_send_signal (5);

}

void timer2 (void) interrupt 5 { /* interrupt code */

/* send signal to task 8 */ os_send_signal (8);

}


C

os_wait

The os_wait function can be used to wait for one or more of the following events:an interval, a timeout, or a signal from another task or interrupt. During the timein which a task is waiting for an event, other tasks can be executed. If one of thespecified events occurs, the task that invoked the os_wait function gets the stateready for execution.

Prototype: int os_wait (int event_selector,unsigned int timer_ticks,int dummy);

Parameter: event_selector specifies the events which are to be waitedfor. The event_selector is formed by addition of the desiredevents. File RTX166T.H defines the possible events:

K_IVL Wait for intervalK_SIG Wait for signalK_TMO Wait for timeout

Example 1: Wait for interval: event_selector = K_IVL.

Example 2: Wait for timeout or signal:event_selector = K_TMO + K_SIG.

timer_ticks determines the number of timer ticks which mustcomplete when waiting for timeout or interval. Thisparameter is insignificant if wait for timeout (K_TMO) orwait for interval (K_IVL) were not specified. The range ofpermissible values for timer_ticks is 0-65535.

The parameter dummy is necessary for compatibility toRTX166. The value is irrelevant for RTX166 Tiny.

Return value: SIG_EVENT: A signal was received.TMO_EVENT: A timeout or interval has completed.NOT_OK: The value for the event_selector isillegal.

See also: os_send_signal, os_clear_signal, isr_send_signal,os_delay_task, os_wait_signal.


C

Example:void count_task (void) _task_ 2 {

while (1) { /* endless loop */ /* wait for signal or timeout */ switch (os_wait (K_SIG + K_TMO, 10, 0) { case TMO_EVENT: { /* If no signal occurs within 10 timer ticks, a timeout occurs and this part of the program is executed. */ break;

case SIG_EVENT: /* If a signal occurs, this part of the program is executed. */ break;

default: /* error handling */ } }}


C

os_wait_signal

The os_wait_signal function is a shorthand of the os_wait function where theevent specification is fixed to a signal (K_SIG). During the time where a task iswaiting for a signal, other tasks can be executed. If the signal is sent by anothertask or an interrupt routine with os_send_signal or isr_send_signal, the callingtask gets the state ready for execution.

Prototype: int os_wait_signal (void);

Parameter: none

Return value: SIG_EVENT: A signal was received.

See also: os_send_signal, os_clear_signal, isr_send_signal, os_wait.

Example:void task_xyz (void) _task_ 5 { /* task code */

/* wait for a signal */ os_wait_signal (100);

/* task code */}


C

ConfigurationThe configuration file CONF_TNY.A66 can be used to adapt RTX166 Tiny toapplication-specific requirements. If you want to use a different CPU timer forRTX166 you can change the timer in the CPUTIMER.INC file and recreate theRTX166 Tiny Libraries using the GENRTX batch file. All the RTX166 Tinyfiles can be found in the directory RTX_TINY.

The following system values can be configured:

� Interval for the system timer (timer ticks).

� Timeout and enable for round-robin task switching.

� The CPU timer used by RTX166 Tiny

CONF_TNY.A66

The file CONF_TNY.A66 contains some EQU directives for the configuration ofthe system values. The function of the EQU directives is described below:

INT_CLOCK defines the interval for the system clock. The system clock ofRTX166 Tiny generates an interrupt in this interval. Thedefined number specifies the value “timer ticks” in 166 CPUcycles. Timer ticks = 2500 is the default value. Values250-65535 are allowed for INT_CLOCK.

TIMESHARING defines the timeout for the round-robin task switching. Thevalue indicates the number of timer ticks which a task isallocated by the CPU. After completion of the timer ticks, atimeout occurs and subsequently a round-robin switching. Ifthe value 0 is defined for TIMESHARING, the round-robintask switching is disabled. Default value is 5. Values1-65535 are allowed for TIMESHARING. Zero disables theround-robin task switching.

CPUTIMER.INC

The file CPUTIMER.INC contains a SET TIMER_NUMBER statement whichdefines the CPU timer used by RTX166 Tiny. You can select the CPU timer 0-6in this file. Note that some 166/167 derivatives do not have the Timer 0 which is


C

use by default from RTX166 Tiny. Refer to the 166/167 hardware manual for thedescription of the hardware timers.

If you have modified the TIMER_NUMBER value you must generate a newversion of the RTX166 Tiny libraries using the GENRTX.BAT file provided inthe RTX_TINY directory.

Stack Management

RTX166 Tiny reserves for each task an own system and user stack area. Due tothe design of RTX166 Tiny the complete stack (user and system) can be located tothe on-chip memory of the 166/167. To allocate the maximum available memoryas stack area the stack of other (not running) tasks is moved in such a way that theentire free memory can be used as stack area by the current running task. Thefollowing figures illustrate the stack assignment of the individual tasks.

STACKTOP STACKTOP STACKTOP

Stack Areafor Task 1









STACKBOT STACKBOT STACKBOT

Stack Assignment forTask0 = Running Task



The figure illustrates that RTX166 Tiny reserves always the entire free memory asa stack area for the currently running task. The memory used for the stack beginswith USRSTKBOT (for user stack) or SYSSTKBOT (for system stack). The endof the memory area is market as USRSTKTOP (for user stack) or asSYSSTKTOP (for system stack).


C

Optimizing RTX166 Tiny Applications

The following notes should be considered in order to create a more efficientapplication with RTX166 Tiny:

� When possible, do not use round-robin task switching.Tasks which use round-robin task switching require 13 bytes stack area inorder to store the context of the task. This context storage is omitted if thetask switching is triggered by the os_wait function. Moreover, the os_waitfunction usually produces a considerably improved system reaction time sincea task which is waiting for execution (READY) must not wait for the timeoutof the currently running (RUNNING) task.

� Do not select the time of the timer interrupts (timer ticks) too small.In order to achieve a possibly low system overhead, the value of TIMER_INTshould not be selected too small. The timer interrupt function processing lastsapproximately 100-300 CPU states depending on the number of defined tasks.

System Debugging

A RTX166 Tiny application can be tested using the dScope source-level debugger.A debug function is available to display the system state of RTX166 Tiny. Theuse of this debug function is subsequently explained.

The debug function is defined in dScope with and include file. The RTX166 Tinyapplication must be loaded prior to defining this debug function.

Example:>DS166*LOAD TRAFFIC /* The RTX166 Tiny application program */*INCLUDE DBG_TINY.INC /* The include file with the Debug Function */Click Toolbox button <Task State>


C

TaskID Start State Wait forEvent

Sig Timer USRSP SYSSP

0 00B0H DELETED 0 -82 906EH FC00H

1 01B2H TIMEOUT SIGNAL 0 -82 9068H FC00H

2 00D8H WAITING TIMEOUT 0 918 9042H FBECH

3 03BEH DELETED 0 -82 903CH FBEAH

4 03FAH WAITING TIMEOUT 0 423 903CH FBEAH

5 048CH WAITING TIMEOUT 0 3 9036H FBE8H

6 0198H DELETED 0 -82 806EH FA00H

Interpretation of the outputs of the debug function:

TaskID Indicates the number which was used in the task definition.

Start Indicates the start address of the task function.

State Indicates the state of the task (see task state).

Wait for Event Indicates which events the task is currently waiting for.

Signal Indicates the state of the signal flag.

Timer the number of timer ticks which are to succeed until a timeoutoccurs.

USRSP start address (stack top) of the local task stack (user stack).

SYSSP Indicates the start address (stack top) of the local task stack(system stack).


C

Application Examples

RTX_EX1: The first RTX166 Program

The program RTX_EX1.C demonstrates round-robin task switching usingRTX166 tiny. Refer to “Round-Robin Task Switching” on page 246 for moreinformation about task switching.

RTX_EX1.C

1 /*********************************************************************/ 2 /* */ 3 /* RTX_EX1.C: The first RTX166 Program */ 4 /* */ 5 /*********************************************************************/ 6 7 #pragma CODE DEBUG 8 9 #include <rtx166t.h> /* RTX166 tiny functions & defines */ 10 11 int counter0; /* counter for task 0 */ 12 int counter1; /* counter for task 1 */ 13 int counter2; /* counter for task 2 */ 14 15 /*********************************************************************/ 16 /* Task 0 'job0': RTX166 tiny starts execution with task 0 */ 17 /*********************************************************************/ 18 job0 () _task_ 0 { 19 1 os_create_task (1); /* start task 1 */ 20 1 os_create_task (2); /* start task 2 */ 21 1 22 1 while (1) { /* endless loop */ 23 2 counter0++; /* increment counter 0 */ 24 2 } 25 1 } 26 27 /************************************************************************/ 28 /* Task 1 'job1': RTX166 tiny starts this task with os_create_task (1) */ 29 /************************************************************************/ 30 job1 () _task_ 1 { 31 1 while (1) { /* endless loop */ 32 2 counter1++; /* increment counter 1 */ 33 2 } 34 1 } 35 36 /*************************************************************************/ 37 /* Task 2 'job2': RTX166 tiny starts this task with os_create_task (2) */ 38 /*************************************************************************/ 39 job2 () _task_ 2 { 40 1 while (1) { /* endless loop */ 41 2 counter2++; /* increment counter 2 */ 42 2 } 43 1 }


C

Running RTX_EX1

The program RTX_EX1 is stored in the directory C166\EXAMPLES\RTX_EX1.

To select this directory type:

CD \C166\EXAMPLES\RTX_EX1

To translate the C source file type:

C166 RTX_EX1.C

To link and generate the RTX166 tiny application type:

L166 RTX_EX1.OBJ RTX166TINY

You can generate the application also under µVision with the RTX_EX1.PRJproject file. Within µVision you can test the application using dScope. Selectfrom the Run menu dScope Debugger…

We have included a dScope init file (DSCOPE.INI) which loads the applicationprogram and a test function for RTX166 tiny.

Define watch variables and start program execution:

>WS counter0>WS counter1>WS counter2>G

The result of the program is simple: counter0, counter1 and counter2 areincremented quasi-parallel. In the EXE window each task switch is reported.

To display the task status of the application type:

Ctrl+CClick Toolbox button <Task State>

To quit dScope type:

>EXIT


C

RTX_EX2: A simple RTX166 Application

The application program RTX_EX2.C demonstrates the usage of the os_waitfunction and signal passing. These functions are described in chapter“Introduction”.

RTX_EX2.C

1 /*********************************************************************/ 2 /* */ 3 /* RTX_EX2.C: A RTX166 Application */ 4 /* */ 5 /*********************************************************************/ 6 7 #pragma CODE DEBUG 8 9 #include <rtx166t.h> /* RTX166 tiny functions & defines */ 10 11 int counter0; /* counter for task 0 */ 12 int counter1; /* counter for task 1 */ 13 int counter2; /* counter for task 2 */ 14 int counter3; /* counter for task 2 */ 15 16 /*********************************************************************/ 17 /* Task 0 'job0': RTX166 tiny starts execution with task 0 */ 18 /*********************************************************************/ 19 job0 () _task_ 0 { 20 1 os_create_task (1); /* start task 1 */ 21 1 os_create_task (2); /* start task 2 */ 22 1 os_create_task (3); /* start task 3 */ 23 1 24 1 while (1) { /* endless loop */ 25 2 counter0++; /* increment counter 0 */ 26 2 os_wait (K_TMO, 5, 0); /* wait for timeout: 5 ticks */ 27 2 } 28 1 } 29 30 /*************************************************************************/ 31 /* Task 1 'job1': RTX166 tiny starts this task with os_create_task (1) */ 32 /*************************************************************************/ 33 job1 () _task_ 1 { 34 1 while (1) { /* endless loop */ 35 2 counter1++; /* increment counter 1 */ 36 2 os_wait (K_TMO, 10, 0); /* wait for timeout: 10 ticks */ 37 2 } 38 1 } 39 40 /*************************************************************************/ 41 /* Task 2 'job2': RTX166 tiny starts this task with os_create_task (2) */ 42 /*************************************************************************/ 43 job2 () _task_ 2 { 44 1 while (1) { /* endless loop */ 45 2 counter2++; /* increment counter 2 */ 46 2 if (counter2 == 0) { /* signal overflow of counter 2 */ 47 3 os_send_signal (3); /* to task 3 */ 48 3 } 49 2 } 50 1 } 51 52 /************************************************************************/ 53 /* Task 3 'job3': RTX166 tiny starts this task with os_create_task (3) */ 54 /************************************************************************/ 55 job3 () _task_ 3 {


C

56 1 while (1) { /* endless loop */ 57 2 os_wait (K_SIG, 0, 0); /* wait for signal */ 58 2 counter3++; /* process overflow from counter 2 */ 59 2 } 60 1 }

Running RTX_EX2

The program RTX_EX2 is stored in the directory C166\EXAMPLES\RTX_EX2.


CD \C166\EXAMPLES\RTX_EX2

To translate the C source file type:

C166 RTX_EX2.C

To link and generate the RTX166 tiny application type:

L166 RTX_EX2.OBJ RTX166TINY

You can generate the application also under µVision with the RTX_EX2.PRJproject file. Within µVision you can test the application using dScope. Selectfrom the Run menu dScope Debugger…


Define watch variables and start program execution:

>WS counter0>WS counter1>WS counter2>WS counter3>G

The result of the application program RTX_EX2:

� counter0 is incremented every 5 RTX166 timer ticks.

� counter1 is incremented every 10 RTX166 timer ticks.

� counter2 is incremented as fast as possible. This task gets most of theavailable CPU time.

� counter3 processes the overflow of counter2.


C

To display the task status of the application type:

Ctrl+CClick Toolbox button <Task State>

To quit dScope type:

>EXIT

Traffic: Pedestrian Traffic Light Controller

The both preceding examples show basic features of RTX166 tiny. Even withoutRTX166, this examples can be coded easily. The following application “Traffic”cannot be simply implemented without a multitasking Real Time OperatingSystem like RTX166. Although the traffic light controller is much to simple to berealize with an 166/167 microcontroller, it shows with an easy example theprinciples of programming an RTX166 application.

“Traffic” is a time-controlled Pedestrian Traffic Light Controller. Between anuser-defined clock time interval the traffic light is operating. Outside this timeinterval the yellow light is blinking. If a pedestrian pushes the request button thetraffic light goes immediately into the ‘walk’ state. Otherwise the traffic lightworks continuously.

Commands to the Traffic Light Controller

To control the clock time and the time interval we have implemented a commandprocessor which operates via the serial interface. The following commands aresupported:

Display Display clock, start and end time.Example: D <cr>

Time Set the current time in 24-hour format.Example: T 12:25:40 <cr>

Start Set the start time in 24-hour format. The traffic light operateswhen the clock time is between start time and end time.Example: S 7:15:00 <cr>

End Set the end time in 24-hour format.Example: E 22:30:00 <cr>


C

Software for the Traffic Light Controller

The whole application is coded in three modules which are described below:

SERIAL.C This module implements an interrupt driven serial interfaceand contains the functions putchar () and getkey (). The high-level I/O functions printf () and getline () are calling this basicI/O routines. Our application operates also without thismodule, but with lower performance.

GETLINE.C This module is the command line editor of the traffic lightcontroller.

TRAFFIC.C This module contains the traffic light controller and is dividedinto the following tasks:

� Task 0 “Initialize”: initialize the serial interface and startall other tasks. Task 0 deletes its self, since initializationis only needed once.

� Task 1 “Command”: is the command processor of ourtraffic light controller. This task controls and processesall commands received via the serial interface.

� Task 2 “Clock”: controls the clock time.

� Task 3 “Blinking”: yellow light is blinking when theclock time is outside the active time range.

� Task 4 “Lights”: controls the traffic light phases whilethe clock time is between start time and end time (thetraffic light is active).

� Task 5 “Keyread”: read the pedestrian push button andsend signal to Task “Lights”.

� Task 6 “Get_ESC”: if an ESC character is input, thedisplay command is terminated. This task is only active iftask Command processes the display command.

Translation

The program Traffic is stored in the directory C166\EXAMPLES\TRAFFIC.



C

CD \C166\EXAMPLES\TRAFFIC

To translate the C source files type:

C166 TRAFFIC.CC166 SERIAL.CC166 GETLINE.C

To link the modules type:

L166 TRAFFIC.OBJ, SERIAL.OBJ, GETLINE.OBJ RTX166TINY

We have also included the project file TRAFFIC.PRJ for µVision with translatesand links the whole application. Within µVision you can test the application usingdScope. Select from the Run menu dScope Debugger…


The following shows the listing files of the TRAFFIC application.

TRAFFIC.C

stmt level source

1 /*********************************************************************/ 2 /* */ 3 /* TRAFFIC.C: Traffic Light Controller using the C166 COMPILER */ 4 /* */ 5 /*********************************************************************/ 6 7 #pragma CODE DEBUG 8 9 const char menu[] = 10 "\n" 11 "+**** TRAFFIC LIGHT CONTROLLER using C166 and RTX166 tiny ***+\n" 12 "| This program is a simple Traffic Light Controller. Between |\n" 13 "| start time and end time the system controls a traffic light |\n" 14 "| with pedestrian self-service. Outside of this time range |\n" 15 "| the yellow caution lamp is blinking. |\n" 16 "+ command -+ syntax -----+ function --------------------------+\n" 17 "| Display | D | display times |\n" 18 "| Time | T hh:mm:ss | set clock time |\n" 19 "| Start | S hh:mm:ss | set start time |\n" 20 "| End | E hh:mm:ss | set end time |\n" 21 "+----------+-------------+------------------------------------+\n"; 22 23 24 #include <reg166.h> /* special function registers 80C166 */ 25 #include <rtx166t.h> /* RTX166 tiny functions & defines */ 26 #include <stdio.h> /* standard I/O .h-file */ 27 #include <ctype.h> /* character functions */ 28 #include <string.h> /* string and memory functions */ 29 30 extern getline (char *, char); /* external function: input line */ 31 extern serial_init (); /* external function: init serial UART */ 32


C

33 #define INIT 0 /* task number of task: init */ 34 #define COMMAND 1 /* task number of task: command */ 35 #define CLOCK 2 /* task number of task: clock */ 36 #define BLINKING 3 /* task number of task: blinking */ 37 #define LIGHTS 4 /* task number of task: signal */ 38 #define KEYREAD 5 /* task number of task: keyread */ 39 #define GET_ESC 6 /* task number of task: get_escape */ 40 41 struct time { /* structure of the time record */ 42 unsigned char hour; /* hour */ 43 unsigned char min; /* minute */ 44 unsigned char sec; /* second */ 45 }; 46 47 struct time ctime = { 12, 0, 0 }; /* storage for clock time values */ 48 struct time start = { 7, 30, 0 }; /* storage for start time values */ 49 struct time end = { 18, 30, 0 }; /* storage for end time values */ 50 51 sbit red = P2^1; /* I/O Pin: red lamp output */ 52 sbit yellow = P2^5; /* I/O Pin: yellow lamp output */ 53 sbit green = P2^11; /* I/O Pin: green lamp output */ 54 sbit stop = P2^2; /* I/O Pin: stop lamp output */ 55 sbit walk = P2^8; /* I/O Pin: walk lamp output */ 56 sbit key = P3^0; /* I/O Pin: self-service key input */ 57 58 char inline[16]; /* storage for command input line */ 59 60 61 /*********************************************************************/ 62 /* Task 0 'init': Initialize */ 63 /*********************************************************************/ 64 init () _task_ INIT { /* program execution starts here */ 65 1 DP2 = 0xFFFF; /* data direction register */ 66 1 serial_init (); /* initialize the serial interface */ 67 1 os_create_task (CLOCK); /* start clock task */ 68 1 os_create_task (COMMAND); /* start command task */ 69 1 os_create_task (LIGHTS); /* start lights task */ 70 1 os_create_task (KEYREAD); /* start keyread task */ 71 1 os_delete_task (INIT); /* stop init task (no longer needed) */ 72 1 } 73 74 75 bit display_time = 0; /* flag: signal cmd state display_time */ 76 77 /*********************************************************************/ 78 /* Task 2 'clock' */ 79 /*********************************************************************/ 80 clock () _task_ CLOCK { 81 1 while (1) { /* clock is an endless loop */ 82 2 if (++ctime.sec == 60) { /* calculate the second */ 83 3 ctime.sec = 0; 84 3 if (++ctime.min == 60) { /* calculate the minute */ 85 4 ctime.min = 0; 86 4 if (++ctime.hour == 24) { /* calculate the hour */ 87 5 ctime.hour = 0; 88 5 } 89 4 } 90 3 } 91 2 if (display_time) { /* if command_status == display_time */ 92 3 os_send_signal (COMMAND); /*signal to task command:time changed*/ 93 3 } 94 2 os_wait (K_IVL, 1000, 0); /* wait interval: 1 second */ 95 2 } 96 1 } 97 98 99 struct time rtime; /* temporary storage for entry time */ 100 101 /*********************************************************************/ 102 /* readtime: convert line input to time values & store in rtime */


C

103 /*********************************************************************/ 104 bit readtime (char *buffer) { 105 1 unsigned char args; /* number of arguments */ 106 1 107 1 rtime.sec = 0; /* preset second */ 108 1 args = sscanf (buffer, "%hd:%hd:%hd", /* scan input line for */ 109 1 &rtime.hour, /* hour, minute and second */ 110 1 &rtime.min, 111 1 &rtime.sec); 112 1 113 1 if (rtime.hour > 23 || rtime.min > 59 || /*check for valid inputs*/ 114 1 rtime.sec > 59 || args < 2 || args == EOF) { 115 2 printf ("\n*** ERROR: INVALID TIME FORMAT\n"); 116 2 return (0); 117 2 } 118 1 return (1); 119 1 } 120 121 122 123 #define ESC 0x1B /* ESCAPE character code */ 124 125 bit escape; /* flag: mark ESCAPE character entered */ 126 127 /*********************************************************************/ 128 /* Task 6 'get_escape': check if ESC (escape character) was entered */ 129 /*********************************************************************/ 130 get_escape () _task_ GET_ESC { 131 1 while (1) { /* endless loop */ 132 2 if (_getkey () == ESC) escape = 1; /* set flag if ESC entered */ 133 2 if (escape) { /* if escape flag send signal */ 134 3 os_send_signal (COMMAND); /* to task 'command' */ 135 3 } 136 2 } 137 1 } 138 139 140 /*********************************************************************/ 141 /* Task 1 'command': command processor */ 142 /*********************************************************************/ 143 command () _task_ COMMAND { 144 1 unsigned char i; 145 1 146 1 printf (menu); /* display command menu */ 147 1 while (1) { /* endless loop */ 148 2 printf ("\nCommand: "); /* display prompt */ 149 2 getline (&inline, sizeof (inline)); /* get command line input */ 150 2 151 2 for (i = 0; inline[i] != 0; i++) { /* convert to uppercase */ 152 3 inline[i] = toupper(inline[i]); 153 3 } 154 2 155 2 for (i = 0; inline[i] == ' '; i++); /* skip blanks */ 156 2 157 2 switch (inline[i]) { /* proceed to command function */ 158 3 case 'D': /* Display Time Command */ 159 3 printf ("Start Time: %02d:%02d:%02d " 160 3 "End Time: %02d:%02d:%02d\n", 161 3 start.hour, start.min, start.sec, 162 3 end.hour, end.min, end.sec); 163 3 printf (" type ESC to abort\r"); 164 3 165 3 os_create_task (GET_ESC); /* ESC check in display loop */ 166 3 escape = 0; /* clear escape flag */ 167 3 display_time = 1; /* set display time flag */ 168 3 os_clear_signal (COMMAND); /* clear pending signals */ 169 3 170 3 while (!escape) { /* while no ESC entered */ 171 4 printf ("Clock Time: %02d:%02d:%02d\r", /* display time */ 172 4 ctime.hour, ctime.min, ctime.sec);


C

173 4 os_wait (K_SIG, 0, 0); /* wait for time change or ESC */ 174 4 } 175 3 176 3 os_delete_task (GET_ESC); /* ESC check not longer needed */ 177 3 display_time = 0; /* clear display time flag */ 178 3 printf ("\n\n"); 179 3 break; 180 3 181 3 case 'T': /* Set Time Command */ 182 3 if (readtime (&inline[i+1])) { /* read time input and */ 183 4 ctime.hour = rtime.hour; /* store in 'ctime' */ 184 4 ctime.min = rtime.min; 185 4 ctime.sec = rtime.sec; 186 4 } 187 3 break; 188 3 189 3 case 'E': /* Set End Time Command */ 190 3 if (readtime (&inline[i+1])) { /* read time input and */ 191 4 end.hour = rtime.hour; /* store in 'end' */ 192 4 end.min = rtime.min; 193 4 end.sec = rtime.sec; 194 4 } 195 3 break; 196 3 197 3 case 'S': /* Set Start Time Command */ 198 3 if (readtime (&inline[i+1])) { /* read time input and */ 199 4 start.hour = rtime.hour; /* store in 'start' */ 200 4 start.min = rtime.min; 201 4 start.sec = rtime.sec; 202 4 } 203 3 break; 204 3 205 3 default: /* Error Handling */ 206 3 printf (menu); /* display command menu */ 207 3 break; 208 3 } 209 2 } 210 1 } 211 212 213 /*********************************************************************/ 214 /* signalon: check if clock time is between start and end */ 215 /*********************************************************************/ 216 bit signalon () { 217 1 if (memcmp (&start, &end, sizeof (struct time)) < 0) { 218 2 if (memcmp (&start, &ctime, sizeof (struct time)) < 0 && 219 2 memcmp (&ctime, &end, sizeof (struct time)) < 0) return (1); 220 2 } 221 1 222 1 else { 223 2 if (memcmp (&end, &ctime, sizeof (start)) > 0 && 224 2 memcmp (&ctime, &start, sizeof (start)) > 0) return (1); 225 2 } 226 1 return (0); /* signal off, blinking on */ 227 1 } 228 229 230 /*********************************************************************/ 231 /* Task 3 'blinking':runs if current time is outside start & end time*/ 232 /*********************************************************************/ 233 blinking () _task_ BLINKING { /* blink yellow light */ 234 1 red = 0; /* all lights off */ 235 1 yellow = 0; 236 1 green = 0; 237 1 stop = 0; 238 1 walk = 0; 239 1 240 1 while (1) { /* endless loop */ 241 2 yellow = 1; /* yellow light on */ 242 2 os_wait (K_TMO, 300, 0); /* wait for timeout: 300 ticks */


C

243 2 yellow = 0; /* yellow light off */ 244 2 os_wait (K_TMO, 300, 0); /* wait for timeout: 300 ticks */ 245 2 if (signalon ()) { /* if blinking time over */ 246 3 os_create_task (LIGHTS); /* start lights */ 247 3 os_delete_task (BLINKING); /* and stop blinking */ 248 3 } 249 2 } 250 1 } 251 252 253 /*********************************************************************/ 254 /*Task 4'lights':executes if current time is between start & end time*/ 255 /*********************************************************************/ 256 lights () _task_ LIGHTS { /* traffic light operation */ 257 1 red = 1; /* red & stop lights on */ 258 1 yellow = 0; 259 1 green = 0; 260 1 stop = 1; 261 1 walk = 0; 262 1 while (1) { /* endless loop */ 263 2 os_wait (K_TMO, 500, 0); /* wait for timeout: 500 ticks */ 264 2 if (!signalon ()) { /* if traffic signal time over */ 265 3 os_create_task (BLINKING); /* start blinking */ 266 3 os_delete_task (LIGHTS); /* stop lights */ 267 3 } 268 2 yellow = 1; 269 2 os_wait (K_TMO, 500, 0); /* wait for timeout: 500 ticks */ 270 2 red = 0; /* green light for cars */ 271 2 yellow = 0; 272 2 green = 1; 273 2 os_clear_signal (LIGHTS); 274 2 os_wait (K_TMO, 500, 0); /* wait for timeout: 500 ticks */ 275 2 os_wait (K_TMO + K_SIG, 7500, 0); /* wait for timeout & signal */ 276 2 yellow = 1; 277 2 green = 0; 278 2 os_wait (K_TMO, 500, 0); /* wait for timeout: 500 ticks */ 279 2 red = 1; /* red light for cars */ 280 2 yellow = 0; 281 2 os_wait (K_TMO, 500, 0); /* wait for timeout: 500 ticks */ 282 2 stop = 0; /* green light for walkers */ 283 2 walk = 1; 284 2 os_wait (K_TMO, 2500, 0); /* wait for timeout: 2500 ticks*/ 285 2 stop = 1; /* red light for walkers */ 286 2 walk = 0; 287 2 } 288 1 } 289 290 291 /*********************************************************************/ 292 /* Task 5 'keyread': process key stroke from pedestrian push button */ 293 /*********************************************************************/ 294 keyread () _task_ KEYREAD { 295 1 while (1) { /* endless loop */ 296 2 if (key) { /* if key pressed */ 297 3 os_send_signal (LIGHTS); /* send signal to task lights */ 298 3 } 299 2 os_wait (K_TMO, 20, 0); /* wait for timeout: 20 ticks */ 300 2 } 301 1 }


C

SERIAL.C

stmt level source

1 /*********************************************************************/ 2 /* */ 3 /* SERIAL.C: Interrupt Controlled Serial Interface for RTX166 tiny */ 4 /* */ 5 /*********************************************************************/ 6 7 #pragma CODE DEBUG 8 9 #include <reg166.h> /* special function register 80C166 */ 10 #include <rtx166t.h> /* RTX166 tiny functions & defines */ 11 #include <intrins.h> /* C166 intrinsic functions */ 12 13 #define OLEN 8 /* size of serial transmission buffer */ 14 unsigned char ostart; /* transmission buffer start index */ 15 unsigned char oend; /* transmission buffer end index */ 16 char outbuf[OLEN]; /* storage for transmission buffer */ 17 int otask = -1; /* task number of output task */ 18 19 #define ILEN 8 /* size of serial receiving buffer */ 20 unsigned char istart; /* receiving buffer start index */ 21 unsigned char iend; /* receiving buffer end index */ 22 char inbuf[ILEN]; /* storage for receiving buffer */ 23 int itask = -1; /* task number of output task */ 24 25 #define CTRL_Q 0x11 /* Control+Q character code */ 26 #define CTRL_S 0x13 /* Control+S character code */ 27 28 bit sendfull; /* flag: marks transmit buffer full */ 29 bit sendactive; /* flag: marks transmitter active */ 30 bit sendstop; /* flag: marks XOFF character */ 31 32 /*********************************************************************/ 33 /* putbuf: write a character to SBUF or transmission buffer */ 34 /*********************************************************************/ 35 void putbuf (char c) { 36 1 if (!sendfull) { /* transmit only if buffer not full */ 37 2 if (!sendactive && !sendstop) { /* if transmitter not active: */ 38 3 sendactive = 1; /* transfer the first character direct */ 39 3 S0TBUF = c; /* to S0TBUF to start transmission */ 40 3 } 41 2 else { /* otherwize: */ 42 3 outbuf[oend++ & (OLEN-1)] = c; /* transfer char to transmission buffer */ 43 3 if (((oend ^ ostart) & (OLEN-1)) == 0) sendfull = 1; 44 3 } /* set flag if buffer is full */ 45 2 } 46 1 } 47 48 49 /*********************************************************************/ 50 /* putchar: interrupt controlled putchar function */ 51 /*********************************************************************/ 52 int putchar (char c) { 53 1 if (c == '\n') { /* expand new line character: */ 54 2 while (sendfull) { /* wait for transmission buffer empty */ 55 3 otask = os_running_task_id (); /* set output task number */ 56 3 os_wait (K_SIG, 0, 0); /* RTX166 call: wait for signal */ 57 3 otask = -1; /* clear output task number */ 58 3 } 59 2 putbuf (0x0D); /* send CR before LF for <new line> */ 60 2 } 61 1 while (sendfull) { /* wait for transmission buffer empty */ 62 2 otask = os_running_task_id (); /* set output task number */ 63 2 os_wait (K_SIG, 0, 0); /* RTX166 call: wait for signal */ 64 2 otask = -1; /* clear output task number */


C

65 2 } 66 1 putbuf (c); /* send character */ 67 1 return (c); /* return character: ANSI requirement */ 68 1 } 69 70 71 /*********************************************************************/ 72 /* _getkey: interrupt controlled _getkey */ 73 /*********************************************************************/ 74 char _getkey (void) { 75 1 while (iend == istart) { 76 2 itask = os_running_task_id (); /* set input task number */ 77 2 os_wait (K_SIG, 0, 0); /* RTX166 call: wait for signal */ 78 2 itask = -1; /* clear input task number */ 79 2 } 80 1 return (inbuf[istart++ & (ILEN-1)]); 81 1 } 82 83 84 /*********************************************************************/ 85 /* serial_receive: serial receive interrupt */ 86 /*********************************************************************/ 87 void serial_receive (void) interrupt SERIAL_RECEIVE0 = 0x2B using S_RBANK { 88 1 unsigned char c; 89 1 90 1 c = S0RBUF; /* read character */ 91 1 switch (c) { /* process character */ 92 2 case CTRL_S: 93 2 sendstop = 1; /* if Control+S stop transmission */ 94 2 break; 95 2 96 2 case CTRL_Q: 97 2 if (_testclear_ (sendstop)) {/*if Control+Q start transmission */ 98 3 S0TIR = 1; /* by setting the interrupt request bit */ 99 3 } 100 2 break; 101 2 102 2 default: /* read all other characters into inbuf */ 103 2 if (istart + ILEN != iend) { 104 3 inbuf[iend++ & (ILEN-1)] = c; 105 3 } 106 2 /* if task waiting: signal ready */ 107 2 if (itask != -1) isr_send_signal (itask); 108 2 break; 109 2 } 110 1 } 111 112 113 /*********************************************************************/ 114 /* serial_transmit: serial transmitter interrupt */ 115 /*********************************************************************/ 116 void serial_transmit (void) interrupt STRANS0 = 0x2A using S_RBANK { 117 1 if (ostart != oend) { /* if characters in buffer and */ 118 2 if (!sendstop) { /* if not Control+S received */ 119 3 S0TBUF = outbuf[ostart++ & (OLEN-1)]; /* transmit character */ 120 3 sendfull = 0; /* clear 'sendfull' flag */ 121 3 /* if task waiting: signal ready */ 122 3 if (otask != -1) isr_send_signal (otask); 123 3 } 124 2 } 125 1 else sendactive = 0; /* if all transmitted clear 'sendactive' */ 126 1 } 127 128 /*********************************************************************/ 129 /* serial_init: initialize serial interface */ 130 /*********************************************************************/ 131 void serial_init (void) { 132 1 P3 |= 0x0400; /* set PORT 3.10 output latch (TXD) */ 133 1 DP3 |= 0x0400; /* set PORT 3.10 direction control (TXD output) */ 134 1 DP3 &= 0xF7FF; /* reset PORT 3.11 direction control (RXD input) */


C

135 1 S0TIC = 0x45; /* transmit interrupt enable; ILVL = 1; GLVL = 1 */ 136 1 S0RIC = 0x46; /* receive interrupt enable; ILVL = 1; GLVL = 2 */ 137 1 S0BG = 0x0A; /* set baudrate to 57600 BAUD */ 138 1 S0CON = 0x8011; /* set serial mode */ 139 1 }

GETLINE.C

stmt level source

1 /*********************************************************************/ 2 /* */ 3 /* GETLINE.C: Line Edited Character Input */ 4 /* */ 5 /*********************************************************************/ 6 7 #include <stdio.h> 8 9 #define CNTLQ 0x11 10 #define CNTLS 0x13 11 #define DEL 0x7F 12 #define BACKSPACE 0x08 13 #define CR 0x0D 14 #define LF 0x0A 15 16 /***************/ 17 /* Line Editor */ 18 /***************/ 19 void getline (char *line, unsigned char n) { 20 1 unsigned char cnt = 0; 21 1 char c; 22 1 23 1 do { 24 2 if ((c = _getkey ()) == CR) c = LF; /* read character */ 25 2 if (c == BACKSPACE || c == DEL) { /* process backspace */ 26 3 if (cnt != 0) { 27 4 cnt--; /* decrement count */ 28 4 line--; /* and line pointer */ 29 4 putchar (0x08); /* echo backspace */ 30 4 putchar (' '); 31 4 putchar (0x08); 32 4 } 33 3 } 34 2 else if (c != CNTLQ && c != CNTLS) { /* ignore Control S/Q */ 35 3 putchar (*line = c); /* echo and store character */ 36 3 line++; /* increment line pointer */ 37 3 cnt++; /* and count */ 38 3 } 39 2 } while (cnt < n - 1 && c != LF); /* check limit and line feed */ 40 1 *line = 0; /* mark end of string */ 41 1 }


C


D

Appendix D. Monitor-166Monitor-166 operates on a 166/167 microcomputer board and performs thecommunication with the PC system via the serial interface. The Monitor-166 canbe operated with dScope using the MON166.DLL. For the DOS environment youcan use the program MON166.EXE which supports the following commands:

� Display memory contents in hexadecimal and ASCII format.

� Change memory contents interactively.

� Display and change CPU registers and Special Function Register contents.

� Initialize the 166/167 memory with a constant value.

� Disassemble memory contents in 166/167 mnemonics.

� In-line Assembler.

� Real-Time Go with up to 16 fixed and 1 temporary break point.

� Control commands for up to 16 fixed break points.

� Single step execution with the option to execute a subroutine as one step.

� Down-Load and Up-Load for Intel HEX and Object files.

� Command menu (help).

Hardware and Software RequirementsThe following requirements must be met for Monitor-166 to operate correctly:

� Siemens 166/167/165/163 CPU or ST10

� 5 Kbyte EPROM starting at address 0 (loaded with Monitor-166 software)

� Serial interface for communication with the PC.

Monitor-166 requires following hardware components of the 166/167 system:

� Serial interface.

� Software trap used for breakpoints (usually NMI trap).

� Additional 10 words stack space in the user program to be tested.

� 256 bytes external data memory (ram).

290 Appendix D. Monitor-166

D

� 5 Kbyte external code memory (EPROM).

All other hardware components can be used by the application.

MON166.EXE: DOS Monitor Driver

MON166 is invoked by entering its name: MON166. The communication withthe serial interface is performed with the hardware interrupt. Various parameterscan be stated in the invocation line. These parameters change the working methodof MON166.

NOTEBefore you operate Monitor-166 with the dScope MON166.DLL you shouldcheck if the MON166.EXE program works with your target board. MON166 iseasy to operate and you can check if your target board works with Monitor-166.

The general syntax of the MON166 invocation is as follows:

MON166 [ parameter ] <cr>

where:

MON166 is the program name.

parameter is one or more of the following:

COM1: use serial interface COM1: (default). Abbreviation: 1.

COM2: use serial interface COM2:. Abbreviation: 2.



INT14 the serial interface is called through the BIOS software interrupt14H. No hardware interrupt is performed. The abbreviation ofINT14 is I .

NOINT the serial interface is polled. No hardware interrupt system isnecessary. The abbreviation of NOINT is N.

BAUDRATE (bps ) allows the setting of the transfer baudrate. If this optionis omitted, 9600 bps is used. bps specifies the baudrate. Possiblevalues are: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400 and57600. The abbreviation of BAUDRATE is BR.


D

All MON166 invocation parameters can also be specified in the DOS environmentvariable MON166=, which can be defined with the DOS SET command. If noparameters are stated in the invocation line, MON166 automatically operates withthe parameters of this system variable. MON166 outputs the following message ifthe parameters of the system variable “MON166=” are used:

ENVIRONMENT STRING: MON166=<parameters>

Examples:MON166MON166 COM2: INT14MON166 2MON166 BAUDRATE (1200)SET MON166=COM2: BAUDRATE (4800)MON166

After invocation, MON166 displays the message:

MS-DOS MON166

INSTALLED FOR PC/XT/AT (COM Line 1) USING HARDWARE INTERRUPT SERVICEBAUDRATE: 9600 (DEFAULT)

*** MONITOR MODE *** or *** TERMINAL MODE ***

MON166 checks at start-up time if the Monitor-166 is active on the target board.If this is the case, MON166 switches to the Monitor Mode and the commandsdescribed under “MON166.EXE Commands” on page 295 can be entered.Otherwise, it is assumed that a user program is already running on the board. Inthis case, the Terminal Mode is started which allows data input or output via theserial interface.


D

MON166.EXE Control Keys

Command lines can be manipulated using the following control keys:

Control Key Function

Enter Execute entire entry line.

<-- Backspace Delete character in front of the cursor.

DEL, Ctrl+D Delete character below the cursor.

Ctrl+A Delete all characters to the right of the cursor.

Ctrl+X Delete all characters to the left of the cursor.

Ctrl+Z Delete entire entry line.

Escape, Ctrl+C Abort entry and start new entry line.

Home Position cursor at the beginning of the entry line.

End Position cursor at the end of the entry line.

Insert Toggle between insert/overwrite mode.

<-- Cursor left Move cursor a position to the left.

--> Cursor right Move cursor a position to the right.

Cursor up Assume an prior entry line in the line editor.

Cursor down Assume a later entry line in the line editor.

The following control the output on the console:

Control Key Function

Ctrl+S Stops output to the console and suspends the executionof the current command.

Ctrl+Q Cancels the effect of CTRL+S. Output to the consoleresumes.

Ctrl+C, ESC Terminates the execution of a command and returns tothe command line interpreter. MON166 produces thefollowing console message:

*** TERMINATED ***#


D

MON166.EXE Terminal Control Codes

List of all MON166 Terminal Control Codes:

Screen control codes Function

00H null

07H bell

08H backspace

09H tab

0AH line feed

0BH cursor up

0CH cursor right

0DH carriage return

14H cursor right

17H erase to end of screen

18H erase to end of line

1AH clear screen and home

1BH 28H (ESC '(' ) highlight on

1BH 29H (ESC ')' ) highlight off

1BH 30H (ESC '0' ) underline

1BH 31H (ESC '1' ) underline off

1BH 32H (ESC '2' ) cursor on

1BH 33H (ESC '3' ) cursor off

1BH 3DH (ESC '=' ) set cursor position (ADM-3A Modus)

1BH 41H (ESC 'A' ) cursor up

1BH 42H (ESC 'B' ) cursor down

1BH 43H (ESC 'C' ) cursor right

1BH 44H (ESC 'D' ) cursor left

1BH 45H (ESC 'E' ) clear screen and home

1BH 48H (ESC 'H' ) cursor home

1BH 4AH (ESC 'J' ) erase to end of screen

1BH 4BH (ESC 'K' ) erase to end of line

1BH 4CH (ESC 'L' ) insert line

1BH 4DH (ESC 'M' ) delete line

1BH 59H (ESC 'Y' ) set cursor position (VT-52 Modus)

1BH 62H (ESC 'b' ) erase to beginning of screen

1BH 6AH (ESC 'j' ) save cursor position

1BH 6BH (ESC 'k' ) restore cursor position

1BH 6CH (ESC 'l' ) delete line

1BH 6FH (ESC 'o' ) erase to beginning of line

1BH 70H (ESC 'p' ) reverse on


D

Screen control codes Function

1BH 71H (ESC 'q' ) reverse off

1BH 76H (ESC 'v' ) scroll on

1BH 77H (ESC 'w' ) scroll off

1BH 7AH (ESC 'z' ) reset terminal

1CH cursor down

1DH cursor home

1EH cursor up

1FH cursor left

Serial Transmission Line

Monitor-166 requires only the signals TRANSMIT DATA, RECEIVE DATA andSIGNAL GROUND from the RS232 or V.24 line. However, in most cases, someadditional connections are necessary in the serial connectors, to enable transmitand receive data.

PIN connections of various computer systems

25-pin Connector

Signal Name Pin Description

RxD 3 receive data

TxD 2 transmit data

Gnd 7 signal ground

9-pin Connector

Signal Name Pin Description

RxD 2 receive data

TxD 3 transmit data

Gnd 5 signal ground

In addition to the above pins, connect pin 7 to pin 8 and pin 1 to pin 4 and pin 6.


D

MON166.EXE Commands

MON166 requires parameters always in hexadecimal form (allowed characters0-9, A-F). If more than one parameter is required by a command the parameterscan be separated by blank (‘ ’) or comma (‘,’).

Example:#FILL 2000, 4000, 0 <cr>

or

#FILL 2000 4000 0 <cr>

In the command description and in the help menu of the Monitor-166 the followingterms are used:

Term Meaning

address The memory address value can be between 0 and 3FFFFH

bp number of a break point. The bp can be between 0 and 0FH.

breakadd temporary break point (address) in the code memory. The temporary break point isonly valid for the current active Go command.

count specifies the number of instructions executed by a Trace or Procedure-Stepcommand. The count can be between 0 and FFFF.

range Two address values which are interpreted as address range. The range includesthe first and the last specified address. The two numbers are separated with blank(' ') or comma (','). Example: 1F,29 or 1F 29 specifies the range from 1FH up toand including 29H.

value The content of a memory location. The values allowed depend on the specifieddata type.Byte:0 . . 0FFWord:0 . . 0FFFFDouble-Word:0-0FFFFFFFF:

F1: Terminate MON166 and Return to DOS

After the entry of the key F1 or ALT+1 MON166 response with the question

EXIT MON166 (y or [n])

MON166 is terminated if ‘y’ or ‘Y’ is pressed, otherwise the EXIT command willbe ignored.


D

F2: Transmit the Content of a File

After the entry of the key F2 or ALT+2 MON166 response with the question:

Input File:

The user can enter a file name. The content of this file is interpreted as MON166command input. If the file transfer should be stopped, the user can enter the keyCtrl+C during the running file transfer.

Example:Input File: INIT.CMD <cr>

F3: Protocol the Screen Output

After the entry of the key F3 or ALT+3 MON166 response with the question:

Output File:

The user can enter a file name. Each character which is displayed on the screenwill be copied into this file.

Example:Output File: DEBUG.PRN <cr>

The Screen Output is copied additionally into the file DEBUG.PRN. If theprotocol function should be stopped the user enters the key F3 or ALT+3. Theprogram MON166 displays the question:

Quit output to file (y or [n])?

The answer ‘y’ or ‘Y’ terminates the protocol function. Otherwise the fileprotocol is continued.

If a file with the entered name already exists, the question:

Overwrite existing file (y or [n])?

is displayed. The answer ‘y’ or ‘Y’ deletes this file and creates a new file with thisname. Otherwise the function F3 is aborted.


D

Help Commands

Help: Display Command Menu

Syntax Meaning

HELP list a brief description of all MON166 commands

Comments (‘;’)

Syntax Meaning

; comment insert line of comment

Comments can be inserted with a semi-colon. MON166 ignores any text after thesemi-colon. This is useful when a session is switched to a protocol file.

Example:#; this is a comment

Exit: Exit MON166 and Return to DOS

Syntax Meaning

EXIT Exit MON166 and return to DOS


D

Displaying and Changing Memory

The following commands let you change memory and display memory areas of the166.

DISPLAY: Display Memory

Syntax Meaning

DB[startaddr [,endaddr]] Display memory in byte format

DW[startaddr [,endaddr]] Display memory in word format

DD[startaddr [,endaddr]] Display memory in double word format

D[startaddr [,endaddr]] Display memory in last used format

The second letter in the Display command specifies the format to be displayed. Ifno start address is entered the last address used by the display command is used.If no end address is entered 4 lines are displayed.

Examples:#DB 1000,2000 ; display bytes from 1000 to 2000#DW ,2100 ; display words (from 2000) to 2100#DD ; display 4 lines double words (from 2100)

ENTER: Change Memory Interactively

Syntax Meaning

EB [address] change contents of memory in byte format

EW [address] change contents of memory in word format

ED [address] change contents of memory in double word format

The second character of the E command specifies the input format to be used. Theaddress parameter can be omitted. If it is omitted the last address used when theenter command was aborted is used. The address and the current value aredisplayed after the command is entered. The following options are available:

� RETURN: the current content remains unchanged.

� PERIOD (‘.’) : the Enter command is terminated.

� VALUE : after RETURN the new value is written into the memory.


D

FILL: Fill Memory

Syntax Meaning

FILL startaddr, endaddr, value fill memory range with value

The FILL command writes a constant value to the specified memory area. Do notfill the SFR space or the DATA memory of Monitor-166.

Examples:#FILL 0, 3FFF, 23 fill memory area from 0 to 3FFF with value 23#FILL 0, 18000, 00 command is not allow because SFRs are cleared

Unassemble: Display Assembler Mnemonics

Syntax Meaning

U [startaddr [,endaddr]] Disassemble Memory

Unassemble displays the memory contents as 166/167 assembler mnemonics.The start and end address is optional and if not specified the last address used byprevious Unassemble command will be assumed. The disassembly includes alsoSFR registers if enough information is present.

Examples:#U#U 100#U 1000, 1100

Assemble: Load 166/167 Instructions into Memory

Syntax Meaning

A [address] Load 166/167 instructions into memory

Assemble allows in-line assembly language to be inserted into the memory. Thisenables code patches or the test of assembler instructions without writing anassembler source files. The instruction parameters can be absolute addresses orsymbols of the SFR register set. The address can be omitted. In this case, theaddress used by a previous Assemble command will be assumed. After theassemble instruction is entered the instruction at the current code address isdisplayed.


D

The following options can be used:

� RETURN: the current memory contents are not changed.

� PERIOD(‘.’) : the command is terminated.

� INSTRUCTION : The previous 166/167 instruction is replaced by thepresent instruction. An error message is issued if the instruction is invalid.

Example:#A 4000 <cr>04000H ADD R15,R10 MOV R15,#4000 <cr>04004H JMPR CC_SLE,04004H JMPS 0,2000 <cr>04008H XOR R14,#1234 NOP <cr>0400AH BSET R15.15 <cr> ; take over instruction0400CH BSET R15.13 MOV P0,[R15] <cr>04010H ADD DPP3:3FFFH,9EH MOV R1,T01CON <cr>04014H RETI . <cr> ; terminate#

eXamine: Display and Change Processor Registers

Syntax Meaning

X display register contents

X <register name> change register contents

The X command without any parameter displays the current register contents inthe following format:

R0 R1 R2 R3 R4 R5 R6 R7 R8 R9 R10 R11 R12 R13 R14 R15xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxxxxxx SP CP CSP IP MDH MDL DPP0 DPP1 DPP2 DPP3 PSW ILVL IEN FLAGSxxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xx x umezvcn

The register names used in the display are the same that can be used as symbols:

Name Definition

R0-R15 Standard register bank (work register)

SP Stack Pointer

CP Context Pointer (start address of register bank)

CSP Code Segment Pointer

IP Instruction Pointer

MDH Multiply/Divide Register High

MDL Multiply/Divide Register Low

DPP0-DPP3 Data Page Pointer


D

Name Definition

PSW Program status word

xx, xxxx the current contents in hexadecimal format

The current interrupt level (ILVL), the interrupt enable flag (IEN) and the flagsare part of the Processor Status Word (PSW). Flags are displayed by a lettercorresponding to their name: Usr0, Mulip, End of table, Zero, oVerflow, Carry,Negative. When this letter is displayed in uppercase the bit is set.

R0-R15, SP, CP, CSP, IP, MDH, MDL, DPP0-DPP3 and PSW can be used asregister names in conjunction with the X command. Also the SFR register set canbe used. The current register content is displayed and a new value can be assignedto the register.

Examples:#X DPP00FE00: 0000H 02 <cr>#X SP0FE12: FC00H FC10 <cr>#X T0REL0FE54: 0000H 0100 <cr>


D

Breakpoint Commands

Sometimes it is necessary to stop the program execution to check the system andto correct any errors. MON166 has the following break point commands:

� BS BREAKPOINT SET define a break point.

� BK BREAKPOINT KILL kill break point(s).

� BL BREAKPOINT LIST list break points.

� BE BREAKPOINT ENABLE activate break point(s).

� BD BREAKPOINT DISABLE temporarily deactivate break point(s).

To perform a breakpoint Monitor-166 writes a TRAP instruction into the userprogram. The advantage is, that no additional hardware is required for the breaklogic. But you can set breakpoints only in RAM memory. Also the trap vectorcannot be used by the application program. Usually the NMI trap is used forbreakpoints. Therefore the 4 memory bytes from 8H-0BH cannot be used by theapplication program. On the other hand, a high to low transition at the NMI# pinforces a program stop.

BreakSet: Define Breakpoint

Syntax Meaning

BS break address define break point

BreakSet sets a break point. The program (‘GO’ command) stops when theinstruction at the break point is reached. An error occurs if:

� An attempt is made to define more than 16 break points.

� The break address is already defined.

� The break address is illegal (odd address).

NOTEBreak addresses must be op code addresses! This means that a breakpoint mustbe the address of the first op code byte of an instruction.


D

Examples:#BS 8100 <cr>#BS 39234 <cr>

BreakKill: Kill Breakpoint

Syntax Meaning

BK ALL Delete all break points

BK bp [, …] Delete specified break points

Breakpoints can be deleted using BreakKill . The ALL option deletes all definedbreakpoints. If single break points are to be deleted the breakpoint number (notthe address) must be entered. Several break points can be specified by separatingthem with commas. The breakpoint number is listed with BreakList .

Examples:#BK ALL <cr>#BK 2 <cr>#BK 0,2,6,9 <cr>

BreakList: Display Breakpoints

Syntax Meaning

BL List all break points

BreakList lists all the current breakpoints with the following components:

� Break point number. Each break point is assigned a number between 0 and15. This number is used in the BreakEnable, BreakDisable and BreakKillcommand.

� Break point status. A break point is either ENAbled or DISabled. A disabledbreak point is not active during program execution.

� Break address.

BreakDisable: Disable Breakpoint

Syntax Meaning

BD ALL Disable all break points


D

Syntax Meaning

BD bp [, …] Disable break points individually

BreakDisable disables breakpoints that are not currently required. The definitionsare not altered. The ALL option disables all defined breakpoints. Singlebreakpoints can be disabled by specifying their breakpoint numbers (notaddresses). Several breakpoints can be disabled by separating the numbers withcommas. The breakpoint numbers can be listed using BreakList .

Examples:#BD ALL#BD 2#BD 0,2,6,9,15

BreakEnable: Enable Breakpoint

Syntax Meaning

BE ALL enable all break points

BE bp [, …] enable named break points

BreakEnable enables breakpoints. The ALL option enables all breakpoints. Asingle breakpoint can be enabled by specifying the breakpoint number (notaddress). Several break points can be specified by separating each breakpointnumber with a comma. BreakList displays the defined breakpoint numbers.

Examples:#BE ALL#BE 2#BE 0,2,6,9


D

Test Commands

The commands for user program execution and program single stepping are:

� Go Execute an 166/167 program in real-time.

� Trace Single step through an 166/167 program.

� Procedure Single step over a subroutine (CALL) as one step.

Go: Real-time Program Execution

Syntax Meaning

G [startaddr [, breakaddr]] start program execution

Go starts program execution from the current program counter (CSP/IP) or fromthe optional startaddr. The breakaddr is also optional. If the break address is notspecified, program execution stops at a breakpoint defined with BreakSet. If nobreak points are defined program execution has to be stopped by a hardware reset.The breakaddr defines a temporary breakpoint and not a permanent breakpoint.

If a defined breakpoint is equal to the program start address, a single step isperformed first. If a breakpoint is reached the following message is displayed:

PROCESSING TERMINATED AT xxxxx

Examples:#G <cr>#G8100 <cr>#G,8200 <cr>#G8000,8010 <cr>

Trace: Single Step Program Execution

Syntax Meaning

T [count] start single step execution

Trace starts program execution in single step mode. The count of steps can bebetween 1 and FFFF. 1 step is assumed if no count is specified. Breakpoints donot affect program execution in single step mode. Trace can be stopped byentering Ctrl+C. You can single step only program parts which reside in RAM.


D

Examples:#T <cr> execute a single step.#T5 <cr> execute five steps.

The following is an example of the display following a step. It is important to notethat an instruction is first executed and then the display is issued. The IP and thedisassembled instruction refers the next instruction to be executed!

R0 R1 R2 R3 R4 R5 R6 R7 R8 R9 R10 R11 R12 R13 R14 R15xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxxxxxx SP CP CSP IP MDH MDL DPP0 DPP1 DPP2 DPP3 PSW ILVL IEN FLAGSxxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xx x umezvcn08344 MOV R14,#1234#

Procedure: Single Step over Procedure

Syntax Meaning

P [count] single step over CALLS or procedures

Procedure starts program execution like Trace in single step mode. Thedifference is, that a subroutine (CALL instruction) executes as one single step.The count of steps can be between 1 and FFFF. 1 step is assumed if no count isspecified. Breakpoints do not affect program execution while in procedure singlestep mode. The P command can be stopped by entering Ctrl+C .

Examples:#P <cr> execute one step.#P8 <cr> execute eight steps.


D

Load and Save

MON166 implements functions for loading and saving program files:

� LOAD Load an Intel HEX-86 or object formatted program.

� SAVE Save a program in the Intel HEX format.

LOAD: Load a program

Syntax Meaning

LOAD filename load the content of the file into 166/167 memory

Load a program in Intel HEX-86 or OMF-166 object format. The correct formatis automatically detected. The data is transferred to the 166/167 target memory.

Example:#LOAD TESTPROG <cr> load an object program#LOAD MYPROG.H86 <cr> load an Intel HEX-86 program

SAVE: Save Program in Intel HEX-86 Format

Syntax Meaning

SAVE filename, startaddr, endaddr The address range is stored in Intel HEX format in thefile.

Save is the opposite of Load. The memory address range specified is stored as anIntel HEX-86 file. The data are transferred from the target board to the PC.

Example:#SAVE MYPROG.H86 8000, 83FF <cr>


D

Predefined Special Function Registers

MON166 defines the SFR registers of the 80C166 as listed in the following table.

SFR Address

ADCIC 0FF98H

ADCON 0FFA0H

ADDAT 0FEA0H

ADDRS 0FE18H

ADEIC 0FF9AH

BUSCON 0FF14H

CAPREL 0FE4AH

CC0 0FE80H

CC0IC 0FF78H

CC1 0FE82H

CC10 0FE94H

CC10IC 0FF8CH

CC11 0FE96H

CC11IC 0FF8EH

CC12 0FE98H

CC12IC 0FF90H

CC13 0FE9AH

CC13IC 0FF92H

CC14 0FE9CH

CC14IC 0FF94H

CC15 0FE9EH

CC15IC 0FF96H

CC1IC 0FF7AH

CC2 0FE84H

CC2IC 0FF7CH

CC3 0FE86H

CC3IC 0FF7EH

CC4 0FE88H

CC4IC 0FF80H

CC5 0FE8AH

SFR Address

CC5IC 0FF82H

CC6 0FE8CH

CC6IC 0FF84H

CC7 0FE8EH

CC7IC 0FF86H

CC8 0FE90H

CC8IC 0FF88H

CC9 0FE92H

CC9IC 0FF8AH

CCM0 0FF52H

CCM1 0FF54H

CCM2 0FF56H

CCM3 0FF58H

CP 0FE10H

CRIC 0FF6AH

CSP 0FE08H

DP0 0FF02H

DP1 0FF06H

DP2 0FFC2H

DP3 0FFC6H

DP4 0FF0AH

DPP0 0FE00H

DPP1 0FE02H

DPP2 0FE04H

DPP3 0FE06H

MDC 0FF0EH

MDH 0FE0CH

MDL 0FE0EH

ONES 0FF1EH

P0 0FF00H

SFR Address

P1 0FF04H

P2 0FFC0H

P3 0FFC4H

P4 0FF08H

P5 0FFA2H

PECC0 0FEC0H

PECC1 0FEC2H

PECC2 0FEC4H

PECC3 0FEC6H

PECC4 0FEC8H

PECC5 0FECAH

PECC6 0FECCH

PECC7 0FECEH

PSW 0FF10H

S0BG 0FEB4H

S0CON 0FFB0H

S0EIC 0FF70H

S0RBUF 0FEB2H

S0RIC 0FF6EH

S0TBUF 0FEB0H

S0TIC 0FF6CH

S1BG 0FEBCH

S1CON 0FFB8H

S1EIC 0FF76H

S1RBUF 0FEBAH

S1RIC 0FF74H

S1TBUF 0FEB8H

S1TIC 0FF72H

SP 0FE12H

STKOV 0FE14H

SFR Address

STKUN 0FE16H

SYSCON 0FF0CH

T0 0FE50H

T01CON 0FF50H

T0IC 0FF9CH

T0REL 0FE54H

T1 0FE52H

T1IC 0FF9EH

T1REL 0FE56H

T2 0FE40H

T2CON 0FF40H

T2IC 0FF60H

T3 0FE42H

T3CON 0FF42H

T3IC 0FF62H

T4 0FE44H

T4CON 0FF44H

T4IC 0FF64H

T5 0FE46H

T5CON 0FF46H

T5IC 0FF66H

T6 0FE48H

T6CON 0FF48H

T6IC 0FF68H

TFR 0FFACH

WDT 0FEAEH

WDTCON 0FFAEH

ZEROS 0FF1CH


D

MON166 Error Messages

During the work with MON166 some error conditions can arise, which are due towrong parameters respectively. The possible error conditions are listed in thefollowing:

*** ERROR 1: FILE NOT FOUND

The specified file or path does not exist.

*** ERROR 3: CAN’T CREATE FILE

The specified file cannot be saved. A file with the same name possibly alreadyexists without access rights for writing.

*** ERROR 4: ERROR WHILE WRITING FILE

An error occurred during the writing of a file; i.e. no more room on the memorystorage medium.

*** ERROR 5: CAN’T OPEN READ-ONLY-FILE FOR WRITE ACCESS

An attempt was made to write to or erase a write-protected file.

*** ERROR 6: ACCESS TO FILE DENIED

The name mentioned is not the name of a file but that of a directory.

*** ERROR 10: MISSING PARAMETER

A required parameter is missing.

*** ERROR 11: BAD DIGIT

The number entered contains illegal characters for a number.

*** ERROR 12: TOO MANY PARAMETERS

Too many parameters were passed to a MON166 command.

*** ERROR 13: BAD COMMAND

The command entered is unknown.

*** ERROR 14: BAD SERIAL TRANSMISSION

An incorrect check sum was encountered during the serial data transmission.The transmitted data could be erroneous. Please check the serial cable to the166/167 board.

*** ERROR 15: BAD HEX RECORD! ABORT LOADING

The loaded hex file contains illegal data or check sum.

*** ERROR 16: INVALID OR CORRUPTED OBJECT FILE

The loaded object file contains illegal data or check sum.


D

*** ERROR 18 IN LINE xx: INVALID MEMORY TYPE

The symbol file specified in the LS command contains a memory type otherthan DATA or BIT in the line specified.

*** ERROR 19 IN LINE xx: HEX VALUE EXPECTED

The symbol file in the LS command contains an invalid HEX number in theline specified.

*** ERROR 20: WRONG REGISTER

The register is in appropriate for the instruction.

*** ERROR 21: NO RAM AT ADDRESS: xxxx

Data cannot be stored into memory at the specified address.

*** ERROR 22: NO BREAKPOINT AVAILABLE

An attempt was made to define more than 16 break points.

*** ERROR 23: BREAKPOINT DOES NOT EXIST

The specified break point does not exist.Note: The argument for BD, BE or BK commands must be the break pointnumber, not the address. The break point number is a value from 0 to 0F Hex.

*** ERROR 24: CANNOT WRITE BREAKPOINT

A break point must be set to a RAM memory area since a TRAP instruction isinserted to the application program to perform a break point.

*** ERROR 26: BREAKPOINT ALREADY DEFINED

This break point is already defined. Use the BL command to display all definedbreak points.

*** ERROR 27: CANNOT WRITE BREAKPOINT VECTOR

MONITOR-166 could not write a new break point vector. Usually the NMItrap at address 08H-0BH is used for break points. If the MONITOR-166EPROM is installed at address 0 then this vector is already defined.

*** ERROR 28: INVALID OPCODE

It is not possible to perform a single- or procedure step on an invalid opcode.Use the Unassemble command to see where invalid opcodes are.

*** ERROR 29: ILLEGAL OR UNINSTALLED COM LINE

The specified serial interface line is not installed in your computer system.Note: COM3 or COM4 must be operated with the setting NOINT or INT14since no standard hardware interrupts exist for these serial interfaces.

*** ERROR 30: ILLEGAL DIGIT IN NUMBER

An octal number cannot contain a digit larger than 7. A hex number can onlycontain digits from 0 to 9 or A to F.


D

*** ERROR 31: SYNTAX ERROR

One parameter in the invocation line is unknown.

*** ERROR 32: NUMERIC CONSTANT EXPECTED

During inline assembly a numeric value is missing.

*** ERROR 33: CONSTANT VALUE OUT OF RANGE

The given constant value is out of range. Bit positions may not be greater than15.

*** ERROR 34: INVALID BITADDRESS

Specification of the word base of a bit address must be: - in the area 0FD00 to 0FDFF - in the area 0FF00 to 0FFDF - in the current context (word register).

*** ERROR 35: WORD-REGISTER (RWn) EXPECTED

A word register is expected for this instruction.

*** ERROR 36: ‘]’ EXPECTED

The indirect register specifier is not correct, the closing ‘]’ is missing.

*** ERROR 37: ‘#’ EXPECTED

The indirect register specifier with an extra immediate offset is wrong. Thecorrect form is [RWn + #immediate_value]. RWn must be one of the wordregisters R0 to R15.

*** ERROR 38: UNKNOWN IDENTIFIER

The given identifier is undefined.

*** ERROR 39: ILLEGAL OPERAND TYPE

The type of the instruction does not match the requirements of that instruction,for example a bit operand in word instruction or a word in a byte instruction.

*** ERROR 40: ILLEGAL REGISTER COMBINATION

This instruction requires a 2 bit short GPR address (R0-R3) and not theregisters R4-R15.

*** ERROR 41: NUMBER OF OPERANDS DOES NOT MATCH INSTRUCTION

The number of operands of the assembler instruction does not correspond tothe required number of operands.

*** ERROR 42: TARGET OUT OF RANGE

The specified destination of a conditional jump command does not lie in thememory area from -255 to +256 of the current address.

*** ERROR 41: ILLEGAL OR UNINSTALLED COM LINE

The specified serial interface line is not installed in your computer system.


D

Note: COM3 or COM4 must be operated with the setting NOINT or INT14since no standard hardware interrupts exist for these serial interfaces.

MON166.DLL: dScope Monitor DriverdScope can also interface to target systems by the use of this MON166.DLLdriver. The serial interface parameters such as COM port and baudrate areselected in the configuration dialog. When starting the MON166.DLL it tries tocommunicate with the target system using the previous settings. If it fails, adialog is automatically opened where you can select new COM port parameters.When an bootstrap loader is detected in the target system, Monitor-166 isdownloaded automatically.

NOTEBefore you operate Monitor-166 with the dScope MON166.DLL you shouldcheck if the MON166.EXE program works with your target board.MON166.EXE is easy to operate and you can check failures of the target boardor the Monitor-166 installation.

MON166.DLL Configuration Dialog

The MON166.DLL configuration dialog allows to select the Monitor-166 options.You enter this dialog with the Config option in the Peripherals menu.


D

� Port: selects the serial PC interface which is used for communication with thetarget system. A new setting becomes active only when you press the Applybutton.

� Baudrate: allows the selection of the baudrate. A new setting becomes activeonly when you press the Apply button.

� Peripheral DLL: the selected DLL file is automatically loaded with theMON166.DLL. Since the MON166.DLL only provides the basiccommunication functions to the target system it needs an additional DLL tosupport derivative specific peripheral dialogs. A new selection will only takeeffect the next time MON166.DLL is loaded.

� Cache Enable: to speed up the screen output, a data cache is implemented.This cache memory is only updated when a Single-Step or Go is executed. Ifyou want to view the actual value of port pins, timers or memory mappedexternal peripherals you can switch these options off. For performancereasons you should enable the cache. The check box SFR enables or disablesthe cache memory in the area 0F000H-0FFFFH. The check box othermemory enables or disables the cache memory of the complete 16 MByte areaexcept the above mentioned SFR area.

� Use serial interrupt: when this option is enabled, Monitor-166 allows toterminate a running application program with the Ctrl+C or ESC key. Tosupport this interrupt feature, the serial interface is not longer available for theuser program. In addition, it is not allowed to reset the global InterruptEnable Flag IE (bit in PSW) in your application. A high to low transition atthe NMI# pin also terminates a running application program.

Restrictions of dScope with MON166.DLL

Map CommandThe memory mapping of a CPU board with Monitor-166 is selected with hardwarecomponents. It is not possible to display or change this memory mapping with thedScope MAP command. The MAP command is therefore not supported.

Performance analyzer / Call stack analyzer / Code coverage.These features are not available with Monitor-166.

Breakpoint OptionsMonitor-166 itself handles the breakpoints. When a access or conditionalbreakpoint is set, the application is executed in single steps and not in real time.Single step execution is at least 1000 times slower.


D

Resources used by Monitor-166

Monitor-166 normally uses the NMI trap for break points and one of the serialinterface traps. Therefore it is necessary to reserve these areas when linking theapplication program.

Example:L166 MYPROG.OBJ RESERVE (8H - 0BH, 0ACH - 0AFH, 0B8H - 0BBH)

Monitor-166 ConfigurationThe Monitor-166 software can be adapted to different hardware configurationsusing the INSTALL batch utility. Parameters for INSTALL are listed below:

INSTALL CpuType SerialType datastart codestart [PROMCHECK | BOOTSTRAP]

� CpuType selects predefined configuration files suitable for various 166/167boards. It is recommended to use a predefined configuration wheneverpossible. The CpuType selects a set of configuration files (e.g. CpuType :=KEI7 selects the INSTKEI7.A66, BOOTKEI7.A66 and CONFKEI7.A66files):

CpuType: = 166 for generic 80C166 board= 167 for generic 167/165 boardPredefined configurations:= KEI7 for KEIL MCB167 board= PHY6 for PHYTEC MC 80C166 board= ERT6 for ERTEC EVA166 board= ERT7 for ERTEC EVA167 board= FOR6 for FORTH\MIKRAP ModuNORM 80C166 board= FOR7 for FORTH\MIKRAP ModuNORM 80C167 board= TEC7 for Techne 167 board

The default baudrate is 9600 bps at 20 MHz CPU clock. The baudrate can bechanged by modifying the reload value of the serial baudrate generator in theINSTxxxx.A66 file. Please refer to the README.TXT file in the MON166directory for a detailed description of various board configurations and furthernotes.

� SerialType specifies the serial interface to be used by Monitor-166:serialtype := 0 using serial interface 0


D

serialtype := 1 using serial interface 1serialtype := 2 using simulated serial interface

The default baudrate is set to 9600 bps at 20 Mhz CPU clock. The baudratecan be changed by modifying the reload value of the serial baudrate generatorin the INSTxxxx.A66 file. Please see the notes in the README.TXT file inthe MON166 directory for using the simulated serial interface.

� datastart is used to specify the page number of the data memory area whichthe Monitor-166 uses for internal management (length = 512 bytes).

� codestart is used to specify the page number of the code memory area used bythe Monitor-166 program (about 5 KByte).

� If PROMCHECK is specified, Monitor-166 checks after reset whether aPROM or a RAM is present at address 0. If a PROM was found, its programis automatically started at address 0. Otherwise, Monitor-166 takes controlover the board. This option cannot be used when Monitor-166 is installed atcode address 0!

� If BOOTSTRAP is specified, the Monitor-166 is generated for using the builtin bootstrap loader of a 166/167/165. In this case, the file BOOT andMONITOR will be generated instead of an HEX file. These two files arecopied to the BIN directory automatically in order to use them with MON166,dScope. With this option it is not allowed to use SerialType = 1 or 2.

Example:INSTALL KEI7 0 3E9 3EB BOOTSTRAP

In this example, Monitor-166 uses serial interface 0. Monitor-166 occupies thecode area from 3EB00H to 3FFFFH and the data area from 3E900H to 3EAFFH.The Monitor-166 is configured for using the bootstrap loader of the 167. Thebootstrap mode must be enabled by hardware (see jumper settings).

The resulting files (MONITOR and BOOT) are automatically copied into the BINdirectory to be used by MON166 or dScope. No HEX file will be generated.


D


E

Appendix E.AMAKE Project Management Utility

This chapter describes the functions and operation of the AMAKE automaticmake utility. AMAKE generates the project dependency list directly form theobject files. AMAKE requires no user created make input file. It automaticallylogs all information about the project generation.

Using AMAKEThe Keil C166 toolset saves the file dependencies of a project in the object files.AMAKE uses this information for project management. Project management withAMAKE requires that you initially create the project manually, compiling andassembling all source files and linking all object files. Then, once the project hasbeen created, you may use AMAKE to update your target whenever you change aC module, assembly source file, or header or include file. AMAKE uses the filedependency list stored in the object file and re-translates only those files whichwhere modified.

AMAKE performs the following operations:

� Re-translates object files.

� Re-creates linker output file, where only the modified modules arere-translated.

� Performs application-wide register optimization also known as applicationregister coloring. AMAKE accomplishes this by re-translating the sourcemodules.

� Lists file dependencies and information about the project generation.

� Creates a batch file for generating the complete project.

� Strips AMAKE information from object files so they may be used with olderversions of the 166/167 tool set or other third party tools.

AMAKE consists of the batch file AMAKE.BAT and the executable programAMK.EXE . AMAKE.BAT activates AMK.EXE which in turn verifies the filedependencies and creates the batch file AUTOMAKE.BAT. AUTOMAKE.BATcontains the command lines required to rebuild the project. AMAKE.BAT startsAUTOMAKE.BAT which re-creates the project.

318 Appendix E. AMAKE Project Management Utility

E

Re-translating an Object FileThe following example shows how to re-translate a single object file which wasinitially translated by the following command line.

C166 HELLO.C CODE DEBUG SMALL REGFILE (HELLO.REG)

This command translates the source file HELLO.C and generates the output fileHELLO.OBJ . HELLO.OBJ is the input file for AMAKE. It contains thefollowing additional information:

� The command line used to create the object file, in this case:C166 HELLO.C CODE DEBUG SMALL REGFILE(HELLO.REG)

� Time and date stamps of all files used to generate HELLO.OBJ. Thisincludes the source file HELLO.C and all include files used within HELLO.C.

� The register usage of public functions in HELLO.C.

� The known or assumed register usage of the external functions. The registerusage of an external function is known to the compiler if the file project.REGlists this function name along with the register usage. The file project.REG iscreated by the linker/locator. The register usage is used to performapplication wide register optimization.

Once the object file has been created, the recreation of HELLO.OBJ can beperformed by the following command:

AMAKE HELLO.OBJ

AMAKE extracts the information how to generate HELLO.OBJ and createsAUTOMAKE.BAT which contains only the compiler invocation.

If AMAKE does not detect changes to any of the source or include files whichwere used to generate HELLO.OBJ, AUTOMAKE.BAT is not created. A filemodification is detected if one of the following conditions are met:

� The path of the source file or of an include file has changed.

� The time or date stamp of the source file or of an include file has changed.AMAKE checks for an exact time and date match.

If the source file contains syntax errors, the compiler does not create an object file.In this case, the AUTOMAKE.BAT file can be used to recreate the object file.


E

Re-creating a Linker Output FileProjects consisting of several object files are created and processed similar to asingle object file. The following example shows the creation of the projectMEASURE which is delivered with the compiler packages.

The project MEASURE consists of three source files: MEASURE.C,MCOMMAND.C , and GETLINE.C .

To create the project, compile the source files with the following three commands:

C166 MEASURE.C CODE DEBUG REGFILE (MEASURE.REG)C166 MCOMMAND.C CODE DEBUG REGFILE (MEASURE.REG)C166 GETLINE.C CODE DEBUG REGFILE (MEASURE.REG)

Next, link the resulting object files to create the linker output file MEASURE,which contains the executable code. A command file named MEASURE.LIN isused for linker input and contains the object file list and the linker controldirectives.

MEASURE.OBJ, MCOMMAND.OBJ, GETLINE.OBJRESERVE (8H-0BH, 88H-8BH, 0ACH-0AFH, 0B8H-0BBH)IXREF REGFILE (MEASURE.REG)

Link the project with the following command.

L166 @MEASURE.LIN

This completes the initial creation step of the project. If one or more of the sourcefiles are changed, the project can be re-created with AMAKE by typing:

AMAKE MEASURE

AMAKE generates only those commands which are required to update the linkeroutput file. If just the source file MEASURE.C is modified, only the C compilerinvocation for this source file and the linker invocation are created by AMAKE.

Application-wide Register Optimization

If the file project.REG is used with the compiler and linker invocation commands,AMAKE performs application-wide register optimization. When optimizingregister usage for a whole program, AMAKE may take more than one pass tocreate a project. The AMAKE batch driver AMAKE.BAT attempts up to three


E

passes to optimize the register usage of an project. If the register usage is toooptimistic further re-translations can occur.

List Project InformationAMAKE creates the log file which displays the file dependency and informationabout the project generation. The log file shows each target file along with theinput files, which it depends from. The input files are shown with path name, dateand time stamp used when the project was created the last time. Each outdatedcomponent is marked as <Needs retranslation>. If AMAKE detects changes tothe project, the recreation commands are listed at the end of the log file.

An example log file of the project MEASURE is listed in the following:

AMAKE V1.0 09/17/93 09:43:11 PAGE 1

DOS AMAKE V1.0COMMANDS PLACED IN AUTOMAKE.BATAMAKE INVOKED BY: E:\TMP\AMK.EXE MEASURE

PROCESSING 166-OBJECT FILE 'MEASURE'USING TEMPLATE 'AMAKE.INI' FOR CREATION OF 'AUTOMAKE.BAT'

COMPONENTS:-----------

Target: MEASURE.OBJ (17/09/93 09:42:36)Source: MEASURE.C (16/09/93 08:32:46)Include(s): C:\C166P\INC\STDIO.H (07/02/92 10:45:16) C:\C166P\INC\STDLIB.H (14/05/93 08:02:02) C:\C166P\INC\REG166.H (12/02/92 17:43:10) C:\C166P\INC\CTYPE.H (14/04/92 07:41:40)Created by: C166 MEASURE.C CODE DEBUG REGFILE(MEASURE.REG)<Needs retranslation>

Target: MCOMMAND.OBJ (17/09/93 09:38:42)Source: MCOMMAND.C (15/09/93 07:48:04)Include(s): C:\C166P\INC\STDIO.H (07/02/92 10:45:16) C:\C166P\INC\REG166.H (12/02/92 17:43:10)Created by: C166 MCOMMAND.C CODE DEBUG REGFILE(MEASURE.REG)

Target: GETLINE.OBJ (17/09/93 09:42:54)Source: GETLINE.C (17/09/93 09:42:44)Include(s): C:\C166P\INC\STDIO.H (07/02/92 10:45:16)Created by: C166 GETLINE.C CODE DEBUG REGFILE(MEASURE.REG)

Target: MEASURE (17/09/93 09:42:54)Link command: MEASURE.LIN (16/09/93 10:56:50)Link input files: MEASURE.OBJ (17/09/93 09:42:36) MCOMMAND.OBJ (17/09/93 09:38:42) GETLINE.OBJ (17/09/93 09:42:54) C:\CL166\C166FPS.LIB (09/09/93 14:04:14) C:\CL166\C166S.LIB (09/09/93 14:04:08)


E

Created by: L166 @MEASURE.LIN<Needs retranslation>

RECREATION COMMANDS:--------------------

C166 MEASURE.C CODE DEBUG REGFILE(MEASURE.REG) L166 @MEASURE.LIN

Create a Batch FileAMAKE creates a batch file with the default name AUTOMAKE.BAT. Thisbatch file contains all commands to build the project. The translation commandsare extracted from the object file. Additional commands which typically handlethe translator exit status information are inserted from the template file. AMAKEuses AMAKE.INI as default template file.

The following shows the content of a batch command file:

@echo onC166 MEASURE.C CODE DEBUG REGFILE (MEASURE.REG)@ECHO OFFIF ERRORLEVEL 1 GOTO EXIT@ECHO ONC166 MCOMMAND.C CODE DEBUG REGFILE (MEASURE.REG)@ECHO OFFIF ERRORLEVEL 1 GOTO EXIT@ECHO ONC166 GETLINE.C CODE DEBUG REGFILE (MEASURE.REG)@ECHO OFFIF ERRORLEVEL 1 GOTO EXIT@ECHO ONL166 @MEASURE.LIN@ECHO OFFIF ERRORLEVEL 1 GOTO EXIT@ECHO ONGOTO FINISH:EXIT@ECHO OFFECHO.ECHO *** ERROR(S) FOUND.:FINISH

With AMAKE you can also create a batch file for the initial project generation.Such batch files are useful when just the source code of a project is available.Example for the creation of a batch file for complete project generation:

AMAKE MEASURE RECREATE CMDFILE (MEASURE.BAT)


E

AMAKE Template FileAMAKE uses a template file to insert additional commands to the batch file. Ifnot template file is specified by the AMAKE control TEMPLATE, the defaulttemplate file AMAKE.INI is used. The AMAKE.INI file is first searched in thecurrent directory. If it does not exists the directory of the AMK.EXE program isscanned; this is usually the BIN directory of the toolset.

The template files contains section entries for each tool used in the AMAKEprocess. A section entry is followed by commands which are copied to the batchfile after a translation command:

AMAKE creates a batch file in the following way:

� From the template file the section [start] is searched for and if found, thecommands belonging to the start section are copied to the batch file.

� The command line of the object file to be retranslated is copied to the batchfile. Example: C166 MEASURE.C CODE DEBUG

�� The translator name (C166 in our example) is searched for a section entry inthe template file. A section entry has the format [translator name] , forexample [C166] . If the translator section entry is found, the commandsbelonging to that section are copied to the batch file. In our example, theseare the command lines

@ECHO OFFIF ERRORLEVEL 1 GOTO EXIT@ECHO ON

� The previous two steps are repeated for each object file to be rebuilt.

� From the template file, the section [exit] is searched for and if found thecommands belonging to the exit section are copied to the batch file. The exitsection will be executed if creation of the project fails for some reason.

The following shows parts of the default template file AMAKE.INI .

[c166] The section entry for the C166 compiler@ECHO OFF the commands after the section entry areIF ERRORLEVEL 1 GOTO EXIT copied to the batch file.@ECHO ON

[a166] The next section entry.@ECHO OFFIF ERRORLEVEL 1 GOTO EXIT@ECHO ON..


E

.[start] The 'start' section.@echo on

[exit] The 'exit' section.@ECHO OFFECHO.ECHO *** ERROR(S) FOUND.

The template file enables the user to fine tune exit status analysis after atranslation command. If warnings in compilations are tolerated while creating theproject, the appropriate ‘IF ERRORLEVEL 1’ command would have to bechanged to ‘IF ERRORLEVEL 2’ to continue project creation on warnings, butnot on errors. The command belonging to the [L166] section checks for errorlevel2, since a warning is created when using the incremental linking feature of L166due to probably undefined external references.

The section [start] is intended to contain project set-up commands such asenvironment settings.

The section [exit] is intended to contain commands which probably clean upcommands from the [start] section. The commands of this section are executed ifAMAKE fails to create the project.

The template file may be modified by the user to suit the specific requirements.

Removing AMAKE InformationAMAKE can be used to purge the project information from a object file. This isachieved by specifying the PURGE control. Stripped files may be required bythird party tools such as emulators or PROM programmers. These tools willeventually not process the special project information records used by AMAKE.A stripped file cannot be used as input file for AMAKE.

AMAKE creates a new file which contains all records except the projectinformation records. In the following example, AMAKE creates the stripped fileMEASURE.O from the project file MEASURE. AMAKE Invocation:

AMAKE MEASURE PURGE

AMAKE creates a log file containing the following information:

DOS AMAKE V1.0COMMANDS PLACED IN AUTOMAKE.BATAMAKE INVOKED BY: E:\TMP\AMK.EXE MEASURE PURGE


E

Creating stripped file 'MEASURE.O' from file 'MEASURE'

AMAKE uses the extension .O as default. The PURGE control may have anadditional argument which specifies the name of the stripped file:

AMAKE MEASURE PURGE (MEASURE.PRG)

AMAKE InvocationYou invoke AMAKE by entering AMAKE at the DOS command line. The generalcommand format is:

AMAKE inputfile �controls �

where:

inputfile is the name of a object file to be re-created.

controls one or more AMAKE control parameters.

The following table lists the AMAKE controls along with abbreviations anddescriptions.

Control Abbr. Description

CMDFILE (filename ) CF Directs AMAKE to create a command file using the specifiedfilename. If CMDFILE is not specified the command file is giventhe name AUTOMAKE.BAT. Note that changing the name of thecommand file also requires changes to the file AMAKE.BAT inorder to run correctly.

LOG (filename ) LG Creates a log file with information about the project generation. Ifthe LOG control is not specified, the base name of the input fileand a the extension .LOG is use as name for the log file.

NOCMDFILE NOCF Directs AMAKE not to create a command file. AMAKE will createthe logfile (unless otherwise specified) but does not cause re-translations to take place.

NOEXECUTE NOE Directs AMAKE not to execute the command fileAUTOMAKE.BAT. In this case, the command fileAUTOMAKE.BAT must be activated manually.

NOLOG NOLG Prevents AMAKE from creating a log file.

NOREGOPTIMIZE NORO Directs AMAKE not to perform global register optimizations.

NOTEMPLATE NOTP Directs AMAKE not to use any template file.

PAGELENGTH(number )

PL Specifies the number of lines per page of the log file. Thenumber must be in range 18 to 32760, the default is 69 lines perpage.


E

Control Abbr. Description

PAGEWIDTH (number ) PW Specifies the pagewidth used when creating log file. The numbermust be in range 72 to 132, the default is 132 characters per line.

PURGE [ (filename ) ] PU Specifies that the AMAKE information contained in the project fileshould be removed. AMAKE creates a new file with either thebase name of the project file and a file extension of .o or thespecified name. The new file contains anything but not theAMAKE information from the project file.

RECREATE RC Directs AMAKE to re-create all object files of a project. Thismeans that the project is re-built by translating and linking allmodules regardless of whether they are valid or not.

REGOPTIMIZE RO Directs AMAKE to perform global register optimizations. This isthe default setting if REGOPTIMIZE is not specified.

Register optimization opportunities in a project may result fromchanges in a function of some source file, which may cause theregister load from that function to be different from the loadknown to functions in other modules. This type of information istransferred via a .REG file generated by the translators andlinkers. With the REGOPTIMIZE command, AMAKE creates thecommand file if the overall register loads of the project can beoptimized, otherwise no command file is created. If the projectmust be re-built due to register loads which are too optimisticthen the command file is generated anyway.

TEMPLATE ( filename ) TP Directs AMAKE to use the specified file as template for creatingthe command file. If the TEMPLATE control is not specified, thefile AMAKE.INI is used as template file.

Invocation Examples

Following are a few examples for AMAKE command lines:

AMAKE MEASURE LOG (MS.LOG)

In this example, the object file MEASURE is processed and the log output isdirected to the file MS.LOG .

AMAKE MEASURE PURGE (MEASURE.PRG)

In this example, the stripped object file MEASURE.PRG is created from theobject file MEASURE, which is left unchanged.

AMAKE MEASURE PAGEWIDTH (80)

In this example, the object file MEASURE is processed and the log output isdirected to the file MEASURE.LOG . The pagewidth used in the log file is 80characters.


E

AMAKE MEASURE CMDFILE (GENALL.BAT) RECREATE

In this example, AMAKE generates the batch file GENALL.BAT from the objectfile MEASURE which can be used for initial project creation.

AMAKE Error MessagesThe following errors may be generated by AMAKE. Each message listed belowincludes a brief description as well as corrective actions you may take to eliminatethe error condition. AMAKE error messages display using the following format:

AMAKE FATAL-ERROR:

LINE: <bad command line> ERROR: <error message>AMAKE ABORTED.

Fatal Errors

BAD OR CORRUPTED INPUTFILE

The AMAKE input file is a corrupted object file. Check the versions of yourtools to make sure they are the latest revision. Refer to “Using AMAKE” onpage 317 for more information on required software versions.

CAN’T CREATE FILE

AMAKE cannot create an output file. This may be caused by an invalid filename argument (invalid file name or directory name).

CAN’T OPEN FILE

The command line specifies a non existing file.

CONFLICTING CONTROL

The invocation line contains a control which contradicts with other controls,for example LOG and NOLOG may not be specified together. The commandline is displayed up to and including the point of error.

*** ERROR IN OBJECT FILE ‘filename’:NO AMAKE-INFORMATION AVAILABLEAMAKE ABORTED.

AMAKE was given a object file which does not contain project information.

FILE WRITE ERROR ON <file name>

The file cannot be written to. This may be caused by insufficient disk space.


E

FILENAME SHARING

The name of an output file shares the name of an input file. This is not allowedsince the input file will be overwritten while processing it.

ILLEGAL INPUTFILE

The AMAKE input file is not a valid object file. AutoMAKE can be used toprocess object files generated by Keil translators only.

INVALID DIGIT IN NUMBER

A numerical argument contains a non decimal digit.

INVOCATION LINE TOO LONG

The invocation line contains one or more tokens that are too long.

MISSING ‘(’

A control requires an additional argument enclosed in parenthesis, for examplePW(80). The open parenthesis was missing.

MISSING ‘)’

The closing parenthesis to an argument was missing.

MISSING ARGUMENT

The invocation line contains an incomplete control, for example PAGEWIDTHwithout the required numerical argument.

NOT A DISK-FILE

The invocation line contains a file name which does not specify a disk file. Aninput file to AMAKE must be a disk file.

OUT OF MEMORY

AMAKE has not enough memory to operate.

UNKNOWN CONTROL

The invocation line to AMAKE contains an unknown control. The commandline is displayed up to and including the point of error.

VALUE OUT OF RANGE

A numerical argument to a control was out of range, for example PW(500).


E


Glossary

A166The command used to assemble programs using the A166 Macro Assembler.

aggregate typesArrays, structures, and unions.

argumentThe value that is passed to macro or function.

arithmetic typesData types that are integral, floating-point, or enumerations.

arrayA set of elements all of the same data type.

ASCIIAmerican Standard Code for Information Interchange. This is a set of 256codes used by computers to represent digits, characters, punctuation, and otherspecial symbols. The first 128 characters are standardized. The remaining128 are defined by the implementation.

basenameThe part of the file name that excludes the drive letter, directory name, and fileextension. For example, the basename for the file C:\SAMPLE\SIO.A66 isSIO.

batch fileA text file that contains MS-DOS commands and programs that can be invokedfrom the command line.

C166The command used to compile programs using the 166/167 Optimizing CCross Compiler.

code bankingSee bank switching.

constant expressionAny expression that evaluates to a constant non-variable value. Constants mayinclude character, integer, enumeration, and floating-point constant values.

330 Glossary

declarationA C construct that associates the attributes of a variable, type, or function witha name.

definitionA C construct that specifies the name, formal parameters, body, and returntype of a function or that initializes and allocates storage for a variable.

directiveAn instruction to the C preprocessor or a control switch to the compiler,assembler or linker.

DPPThe Data Page Pointer registers of the 166/167 CPU. There are four DPPregisters: DPP0-DPP3 available. The DPP registers hold the most significantfor near addresses. The actual DPP register used for a near address isspecified by the bit 14 and bit 15 of the address. The physical address iscalculated using the following formula:

Physical Address = (DPPn * 0x4000L) + (bit0-bit13 of the near address)

DSW166The command used to load and execute the 166/167 Simulator/Debugger.

environment tableThe memory area used by MS-DOS to store environment variables and theirvalues.

environment variableA variable stored in the environment table. These variables provide MS-DOSprograms with information like where to find include files and library files.

escape sequenceA backslash (‘\’) character followed by a single letter or a combination ofdigits that specifies a particular character value in strings and characterconstants.

expressionA combination of any number of operators and operands that produces aconstant value.

functionA combination of declarations and statements that can be called by name thatperform an operation and/or return a value.


function callAn expression that invokes and possibly passes arguments to a function.

in-circuit emulator (ICE)A hardware device that aids in debugging embedded software by providinghardware-level single-steping, tracing, and break-pointing. Some ICEs providea trace buffer that stores the most recent CPU events.

include fileA text file that is incorporated into a source file using the #includepreprocessor directive.

keywordA reserved word with a predefined meaning for the compiler.

L166The command used to link object files and libraries using the 166/167Linker/Locator.

LIB166The command used to manipulate 166/167 library files using the 166/167Library Manager.

libraryA file that stores a number of possibly related object modules. The linker canextract modules from the library to use in building a target object file.

macroAn identifier that represents a series of keystrokes that is defined using the#define preprocessor directive.

manifest constantA macro that is defined to have a constant value.

memory modelAny of the models that specifies which memory areas are used for functionarguments and local variables.

newline characterThe character used to mark the end of a line in a text file or the escapesequence (‘\n’ ) used to represent the newline character.

null characterThe ASCII character with the value 0 represented as the escape sequence(‘\0’ ).

332 Glossary

null pointerA pointer that references nothing and has an offset of 0000h. A null pointerhas the integer value 0.

objectAn area of memory that can be examined. Usually used when referring to thememory area associated with a variable or function.

object fileA file, created by the compiler, that contains the program segment informationand relocatable machine code.

OH166The command used to convert absolute object files into other hexadecimal fileformats using the Object File Converter.

operandA variable or constant that is used in an expression.

operatorA symbol that specifies how to manipulate the operands of an expression; e.g.,+, -, *, /.

parameterThe value that is passed to a macro or function.

pointersA variable that contains the address of another variable, function, or memoryarea.

pragmaA statement that passes an instruction to the compiler at compile time.

relocatableAble to be moved or relocated. Not containing absolute or fixed addresses.

RTX166 FullAn 166/167 Real-Time Executive that provides a multitasking operatingsystem kernel and library of routines for its use.

RTX166 TinyA limited version of RTX166.

scalar typesInteger, enumerated, floating-point, and pointer types.


scopeThe sections or a program where an item (function or variable) can bereferenced by name. The scope of an item may be limited to file, function, orblock.

source fileA text file containing assembly program code.

stackAn area of memory, indirectly accessed by a stack pointer, that shrinks andexpands dynamically as items are pushed onto the stack and popped off of thestack. Items in the stack are removed on a LIFO (last-in, first-out) basis.

staticA storage class that, when used with a variable declaration in a function,causes variables to retain their value after exiting the block or function inwhich they are declared.

stringAn array of characters that is terminated with a null character (‘\0’ ).

string literalA string of characters enclosed within double quotes (“ ” ).

tokenA fundamental symbol that represents a name or entity in a programminglanguage.

two’s complementA binary notation that is used to represent both positive and negative numbers.Negative values are created by complementing all bits of a positive value andadding 1.

typeA description of the range of values associated with a variable. For example,an int type can have any value within its specified range (-32768 to 32767).

whitespace characterCharacters that are used as delimiters in C programs such as space, tab,newline, etc.

wild cardOne of the MS-DOS characters (? or *) that can be used in place of charactersin a filename.

334 Glossary


Index

__task_.............................................255

AA166, defined.................................329ABSOLUTE..............................70, 160absolute

Operands .................................... 19Absolute Object File........................160Absolute object files........................155ABSOLUTE, control........................ 70Additional items, notational

conventions.................................... ivAddress

Expression.................................. 60Operand ..................................... 25

aggregate types, defined..................329alignment......................................... 54align-type......................................... 33Allocating Memory.........................159

Internal Data Area.....................159AMAKE

Error messages ..........................326Invocation.................................324Invocation examples..................325Linker command files................319Projects......................................319Reg file......................................319Removing AMAKE

Information.............................323Template file.....................321, 322Using.........................................317

AMAKE Project ManagementUtility ...........................................317

AMAKE.INI ...................................322Application Example ......................219argument, defined ...........................329arithmetic types, defined.................329array, defined..................................329ASCII, defined................................329Assembler Controls.......................... 67

ASSUME....................................38, 56AT expression.................................. 35at sign.............................................. 66

Bbalanced text...................................108basename, defined...........................329basic instructions ............................146batch file, defined............................329bit section........................................ 32bitaddressable.............................32, 33bit-addressable................................. 62bit-pointer........................................ 62Bitword............................................ 21blank-delimiter ...............................127bold capital text, use of...................... ivboundary.......................................... 54braces, use of..................................... iv

CC166 Memory Models.....................256C166 Run-Time Library..................256C166 Support..................................255C166, defined..................................329call-pattern......................................125CASE.............................................. 71CASE, control.................................. 71CGROUP......................................... 37character string ...............................116Choices, notational conventions........ ivClasses............................................157class-name....................................... 35code banking, defined.....................329code section..................................... 32Combining program modules ..........156Combining Sections........................157Command Files...............................163Command line ................................. 65Command-Line Directives..............165Command-Line Examples...............163comment.......................................... 11COMMON....................................... 34

336 Index

Compatibility to Siemens Tools......208COND..............................................72COND, control.................................72condition code..................................12conditional assembly.......................100CONF_TNY.A66...........................269Constant

Expression..................................60constant expression, defined...........329context pointer..................................41Controls

ABSOLUTE................................70CASE..........................................71COND.........................................72DATE .........................................73DEBUG......................................74EJECT ........................................75ELSE........................................104ELSEIF.....................................103ENDIF......................................105ERRORPRINT............................76EXPDECNUM............................77GEN/GENONLY/NOGEN..........78IF..............................................102INCDIR ......................................79INCLUDE...................................80LIST ...........................................81MACRO......................................82MOD166.....................................83MOD167.....................................84NOCASE....................................71NOCOND...................................72NODEBUG.................................74NOERRORPRINT.......................76NOLIST......................................81NOMACRO................................82NOMOD166...............................83NONSEGMENTED....................93NOOBJECT................................85NOPAGING................................88NOPRINT...................................89NOSYMBOLS............................94NOTYPE....................................97NOXREF....................................99OBJECT.....................................85PAGELENGTH..........................86

PAGEWIDTH.............................87PAGING.....................................88PRINT........................................89REGUSE.....................................90RESET......................................101RESTORE...................................92SAVE .........................................92SEGMENTED............................93SET...........................................101SYMBOLS..................................94TABS..........................................95TITLE.........................................96TYPE..........................................97USEDEXTONLY........................98XREF..........................................99

courier typeface, use of......................ivCPUTIMER.INC............................269Cross reference listing........................9

Ddata section.......................................32DATE...............................................73DATE, control..................................73DB....................................................59DBIT ................................................59DBPTR.............................................62DEBUG............................................74DEBUG, control...............................74declaration, defined ........................330DEFA...............................................50DEFB...............................................50define.............................................107Define Bit.........................................59Define Byte.......................................59Define Storage..................................59Define Storage Byte..........................60Define Storage Word........................60Define Word.....................................59define-pattern .................................125definition, defined...........................330DEFR...............................................50DGROUP.........................................37Directive

ASSUME....................................38BIT .............................................48DB ..............................................59


DBIT .......................................... 59DBPTR....................................... 62DEFA......................................... 50DEFB......................................... 50DEFR......................................... 50DPPTR....................................... 62DS.............................................. 59DSB ........................................... 59DSPTR....................................... 62DSW .......................................... 59DW ............................................ 59END........................................... 63ENDP......................................... 43ENDS......................................... 32EQU........................................... 46EVEN......................................... 54EXTERN.................................... 55EXTRN...................................... 55GLOBAL.................................... 57GROUP...................................... 37LABEL....................................... 49LIT............................................. 52NAME........................................ 63ORG........................................... 53PROC......................................... 43PUBLIC ..................................... 57SECTION................................... 32SET............................................ 47SSKDEF..................................... 42TYPEDEC.................................. 53

directive, defined.............................330Directives......................................... 31

defb............................................ 48pecdef......................................... 42regbank ...................................... 41regdef......................................... 41

Directivesassume........................................ 22

Displayed text, notationalconventions.................................... iv

Document Conventions..................... ivdollar sign........................................ 16

Numbers..................................... 13double brackets, use of...................... ivDPP, defined...................................330DPPTR............................................ 62

DS ................................................... 59DSB................................................. 59dScope............................................312DSPTR............................................ 62DSW................................................ 59DSW166, defined............................330DW.................................................. 59

EEJECT ............................................. 75EJECT, control ................................ 75ellipses, use of................................... ivellipses, vertical, use of..................... ivELSE..............................................104ELSE, control.................................104ELSEIF...........................................103ELSEIF, control..............................103END ................................................ 63ENDIF............................................105ENDIF, control...............................105ENDP.............................................. 43ENDS.............................................. 32environment table, defined..............330environment variable, defined .........330EOF record.....................................242Error messages................................131

action........................................131fatal ...........................................131non-fatal............................131, 134of L166......................................210

ERRORLEVEL.........................66, 164ERRORPRINT................................. 76ERRORPRINT, control.................... 76escape sequence, defined.................330EVEN.............................................. 54Exception Messages........................218EXPDECNUM................................. 77EXPDECNUM, control.................... 77Expression......................................114

Numbers..................................... 13Strings........................................ 13

expression, defined..........................330EXPRESSIONS............................... 16EXTERN......................................... 55external constant.............................. 17external symbol................................ 56

338 Index

EXTRN............................................55

Ffar.....................................................44Filename, notational

conventions.....................................ivFiles generated by A166....................67fix-up................................................46forward.............................................24forward reference..............................46function call, defined......................331function, defined.............................330Functions

bracket......................................113comment...................................112CONSOLE................................124EQS ..........................................118escape.......................................112EVAL .......................................117EXIT.........................................121GES ..........................................118GTS ..........................................118IF..............................................119IN .............................................124LEN..........................................122LES...........................................118LTSs.........................................118MATCH....................................123METACHAR ............................114NES ..........................................118OUT..........................................124REPEAT...................................121SET...........................................116SUBSTR...................................123WHILE .....................................120

GGEN.................................................78GEN/GENONLY/NOGEN,

control...........................................78general purpose register....................16GENONLY.......................................78GLBUSRSTACK..............................35GLOBAL.................................... 34, 57GROUP............................................37

group name.......................................17Groups............................................158

HHash mark (#) in listing......................9

IICE, defined...................................331identifier-delimiter..........................127IF ...................................................102IF, control.......................................102Immediate data .................................25Implementation specifics................145

limits.........................................145INCDIR............................................79INCDIR, control...............................79in-circuit emulator, defined.............331INCLUDE ........................................80include file, defined........................331INCLUDE, control...........................80initialize memory..............................59instruction set .................................145Intel HEX

8086 segment address record.....243Data record ...............................242End-of-file record......................242EOF record...............................242Example file..............................244Extended linear address

record.....................................243Record format...........................241

Intel HEX file format......................241Intel HEX files........................ 155, 239internal RAM ...................................42INTERRUPT....................................44Interrupt Handling..........................256Interrupt Vector..............................201interrupt vector number ....................12INTNO.............................................44Invoking A166..................................65isr_send_signal...............................265italicized text, use of..........................iv


KKey names, notational

conventions.................................... ivkeyword, defined.............................331

LL166...............................................153

Error Messages..........................210Exception Messages...................218Fatal Errors ...............................215invocation with TGROUPS........207Library Files..............................156Listing File................................160Non Fatal Errors........................212Output File................................164Warning detection .....................202Warnings...................................210

L166 DirectivesASSIGN....................................168CLASSES..................................169DPPUSE....................................170GROUPS...................................172INTNO......................................173IXREF.......................................174LINKONLY ..............................175NAME.......................................176NOAMAKE ..............................177NOCASE...................................178NOCOMMENTS.......................179NODEFAULTLIBRARY...........180NOINIT.....................................181NOLINES..................................182NOMAP....................................183NOPUBLICS.............................184NOTYPE...................................185NOVEVTAB .............................186OBJECTCONTROLS................187PAGELENGTH.........................188PAGEWIDTH...........................189PRINT.......................................190PRINTCONTROLS...................191PUBLICSONLY........................192PURGE.....................................193REGBANK................................194REGFILE..................................195

RESERVE.................................196RTX166....................................197RTX166TINY ...........................198SECSIZE...................................199SECTIONS................................200VECTAB...................................201WARNINGLEVEL....................202

L166 linker/locator .........................153L166 MAP file................................160L166, defined..................................331label............................................11, 15LIB166 ...........................................229

ADD..........................................230Adding Object Modules.............232Command line...........................229Commands ................................230CREATE...................................230Creating a Library .....................231DELETE...................................230Error Messages..........................236EXIT .........................................230HELP........................................230Help Information.......................235Interactive mode........................229LIST..........................................230Listing Library Contents............234Removing Object Modules.........233

LIB166, defined..............................331Library Manager .............................229library, defined................................331Linking Programs with L166 ..........161LIST ................................................ 81LIST, control................................... 81LIT .................................................. 52LIT Directive..................................... 9literal mode.....................................128literal-character...............................109literal-delimiter...............................126literalize..........................................128local-symbols..................................111Long Command Lines.....................163LST files.......................................... 67

Mmachine instruction.......................... 11Macro.............................................. 82

340 Index

Body.........................................108Delimiters .................................109Error .........................................129Parameter..................................109Processor............................. 63, 107

MACRO, control..............................82macro, defined................................331manifest constant, defined ..............331MAP file.........................................160Memory allocation..........................159memory model, defined..................331metacharacter .................................108mnemonic.........................................11MOD166..........................................83MOD166, control.............................83MOD167..........................................84MOD167, control.............................84module name....................................63MON166

Command Line .........................292Control Keys.............................292Error Messages.........................309Invocation.................................290Program Test.............................305Terminal Control Codes ............293

MON166 commandAssemble...................................299BreakDisable.............................303BreakEnable..............................304BreakKill ..................................303BreakList..................................303Breakpoints...............................302BreakSet...................................302Display......................................298Enter .........................................298eXamine....................................300Exit ...........................................297F1 Exit ......................................295F2 Transmit File .......................296F3 Protocol Output....................296Fill ............................................299Go.............................................305Load Program...........................307Procedure..................................306Save Program............................307Unassemble...............................299

MON166.DLL........................ 289, 312MON166.EXE................................289Monitor-166...................................289

Comments.................................297Configuration............................314Console Output.........................292Serial Transmission Line...........294Trace.........................................305

MPL...............................................107

NNAME..............................................63Name Assignment ..........................257near ..................................................44newline character, defined ..............331NOCASE..........................................71NOCASE, control.............................71NOCOND.........................................72NOCOND, control............................72NODEBUG......................................74NODEBUG, control..........................74NOERRORPRINT............................76NOERRORPRINT, control...............76NOGEN.................................... 78, 110NOLIST ...........................................81NOLIST, control...............................81NOMACRO......................................82NOMACRO, control.........................82NOMOD166.....................................83NOMOD166, control........................83NONSEGMENTED..........................93non-segmented........................... 32, 56NONSEGMENTED, control.............93NOOBJECT.....................................85NOOBJECT, control.........................85NOPAGING.....................................88NOPAGING, control........................88NOPRINT........................................89NOPRINT, control............................89normal mode ..................................128NOSYMBOLS..................................94NOSYMBOLS, control.....................94NOTHING........................................39NOTYPE..........................................97NOTYPE, control.............................97NOXREF..........................................99


NOXREF, control............................ 99null character, defined.....................331null pointer, defined........................332Numbers...................................13, 115

OOBJ files.......................................... 67OBJECT.....................................67, 85object file, defined...........................332OBJECT, control............................. 85object, defined.................................332OH166....................................155, 239

Command line...........................239Error messages ..........................240

OH166, defined...............................332Omitted text, notational

conventions.................................... ivoperand, defined.............................332Operands

data page pointer (DPP).............. 22immediate expression................. 23linear address ............................. 26page number............................... 25regbank ...................................... 25special function register

(SFR)....................................... 25system names (SFR)................... 25

Operands and Expressions ............... 11operator, defined.............................332Operators......................................... 17Operators

Addition ..................................... 18BOF ........................................... 27DATAn ...................................... 23Division...................................... 19DOT........................................... 21HIGH ......................................... 21logical ........................................ 20LOW .......................................... 21Modulo....................................... 19Multiplication............................. 19PAG ........................................... 25page override.............................. 22POF............................................ 26PTR............................................ 22relational .................................... 20

SEG............................................ 25shift ............................................ 20short ........................................... 24sign ............................................ 19SOF............................................ 26Subtraction................................. 18

Optional items, notationalconventions.................................... iv

ORG ................................................ 53os_clear_signal...............................260os_create_task.................................261os_delay_task..................................262os_delete_task.................................263os_running_task_id.........................264os_send_signal................................265os_wait...........................................266os_wait_signal................................268os-wait............................................247Output files...................................... 67overlap............................................. 34

Ppage override................................... 38page relative..................................... 62PAGELENGTH............................... 86PAGELENGTH, control.................. 86PAGEWIDTH.................................. 87PAGEWIDTH, control..................... 87PAGING.......................................... 88PAGING, control............................. 88parameter, defined ..........................332parameterless macro........................108PEC channels................................... 26PECADDRESSABLE...................... 33PECDEF.......................................... 42Physical Memory Layout.................203pointers, defined.............................332pragma, defined ..............................332predefined names............................151predefined symbols

reserved words............................ 15Preemptive Task Switching.............248PRINT........................................67, 89PRINT, control................................ 89Printed text, notational

conventions.................................... iv

342 Index

Priority of Operators.........................17PRIVATE.........................................34PROC...............................................43PUBLIC...................................... 34, 57

RREGBANK.......................................41REGDEF..........................................41REGUSE..........................................90REGUSE, control.............................90relative offset....................................12relocatable..........................................9Relocatable

Expression..................................16Operands.....................................19Section........................................16

relocatable, defined.........................332replacement-text.............................109reserve memory................................59reserved words................................149RESET...........................................101RESET, control..............................101Resolving External References........159RESTORE........................................92RESTORE, control...........................92Round-Robin..................................246RTX166.................................. 161, 245

Functions..................................251Optimizing................................271Technical Data..........................251

RTX166 Applications.....................249RTX166 Example

RTX_EX1.C.............................273RTX_EX2.C.............................275TRAFFIC.C..............................277

RTX166 Full, defined.....................332RTX166 Tiny......................... 161, 245

Application Examples ...............273Configuration............................269Functions.......................... 250, 257Introduction ..............................245Software Requirements..............253Stack Management....................270System Debugging....................271Technical Data..........................250

RTX166 Tiny, defined....................332

RTX166T.H....................................257Running A166..................................65runtime stack....................................34

Ssans serif typeface, use of...................ivSAVE...............................................92SAVE, control..................................92scalar types, defined........................332scope, defined.................................333SECTION................................... 31, 32

multiple definition.......................35nested..........................................36

Section Alignment..........................156Sections..........................................156segment relative................................62segmented................................... 32, 93SEGMENTED, control.....................93SET................................................101SET, control ...................................101Siemens

LNK166....................................208LOC166....................................208

Siemens Task Concept....................207Siemens Tools

Compatibility to ~.....................208Software instructions................ 43, 148source file, defined..........................333SSKDEF...........................................42stack size..........................................42stack, defined..................................333static, defined.................................333string literal, defined ......................333string, defined.................................333Strings..............................................13Symbol.........................................8, 14

changeable..................................15Scope..........................................15Section........................................15Table.............................................8Type............................................14Value..........................................15

Symbolspecial assembly ~.......................16

symbolic debugging..........................11symbolic label...................................11


SYMBOLS...................................... 94SYMBOLS, control.......................... 94SYSSTACK..................................... 34SYSTEM....................................37, 39

TTABS............................................... 95TABS, control.................................. 95TASK .............................................. 44Task Concept..................................207Task Declaration.............................255Task Management...........................253Task Switching ...............................254TGROUP......................................... 35TGROUPS......................................207

using with Emulators.................209three pass....................................24, 53TITLE.............................................. 96TITLE, control................................. 96token, defined.................................333two’s complement, defined..............333TYPE............................................... 97type mismatch.................................. 49TYPE, control.................................. 97type, defined...................................333TYPEDEC....................................... 53

UUSEDEXTONLY............................ 98USING............................................. 45USRSTACK..................................... 34

VVariables, notational

conventions.................................... ivvertical bar, use of............................. iv

WWait for Signal ...............................248Wait for Timeout............................247Warnings

of L166......................................210whitespace character, defined..........333wild card, defined...........................333word alignment................................ 59

XXREF............................................... 99XREF, control.................................. 99

166/167 assembler and utilitiesee192/sp05/documents/... · 2004-04-06 · 166/167 assembler and...

Documents