MACLNKUM.DOC MACREL/LINK User's Manual Order No. AA-5664B-TA DISCLAIMER This document file was created by scanning the original document and then editing the scanned text. As much as possible, the original text format was restored. Some format changes were made to insure this document would print on current laser printers using 60 lines per page. The original spelling and grammar has been preserved. 1-Mar-1997 MACREL/LINK User's Manual Order No. AA-5664B-TA January 1979 This document is the user's manual for MACREL/LINK, a PDP-8 macro assembly language and linking loader. The manual completely describes all operating instructions, language elements, directives and options. Examples and demonstration programs are contained throughout the manual. SUPERSESSION/UPDATE INFORMATION: This document completely supersedes its predecessor AA-5664A-TA. OPERATING SYSTEM AND VERSION: OS/8 V3D and subsequent versions. SOFTWARE AND VERSION: MACREL Version 2D LINK Version 2B CREF Version 2A OVRDRV Version 2A --------------------------------------------------------------------- | To order additional copies of this manual, contact the Software | | Distribution Center, Digital Equipment Corporation, Maynard, | | Massachusetts 01754 | --------------------------------------------------------------------- digital equipment corporation - maynard. massachusetts First Printing, October 1977 Revised: January 1979 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by DIGITAL or its affiliated companies. Copyright (c) 1977, 1979 by Digital Equipment Corporation The postage-prepaid READER'S COMMENTS form on the last page of this document requests the user's critical evaluation to assist us in pre- paring future documentation. The following are trademarks of Digital Equipment Corporation: DIGITAL DECsystem-10 MASSBUS DEC DECtape OMNIBUS PDP DIBOL OS/8 DECUS EDUSYSTEM PHA UNIBUS FLIP CHIP RSTS COMPUTER LABS FOCAL RSX COMTEX INDAC TYPESET-8 DDT LAB-8 TYPESET-11 DECCOMM DECSYSTEM-20 TMS-11 ASSIST-11 RTS-8 ITPS-10 VAX VMS SBI DECnet IAS CONTENTS Page PREFACE xi CHAPTER 1 INTRODUCTION 1-1 1.1 MACREL FEATURES 1-1 1.1.1 Relocation 1-1 1.1.2 Macros 1-2 1.1.3 Directives 1-3 1.2 OVERVIEW OF ASSEMBLY AND RELOCATABLE LOADING 1-3 1.2.1 Assembling with MACREL 1-3 1.2.2 Linking with LINK 1-4 1.3 COMPATIBILITY OF MACREL WITH PAL8 1-4 1.3.1 MACREL: Differences from PAL8 1-5 1.3.1.1 Dollar Sign ($) 1-5 1.3.1.2 DTORG 1-5 1.3.1.3 MACREL and Literals 1-5 1.3.1.4 PAUSE 1-5 1.3.1.5 Closing Literal Expressions 1-5 1.3.1.6 Terminal Support 1-6 1.3.1.7 PAL8 Run-Time Options 1-6 1.4 ASSEMBLING EXISTING PAL8 PROGRAMS WITH MACREL 1-6 1.5 INTRODUCTION TO MACREL RELOCATION 1-7 1.5.1 Source Modules 1-7 1.5.2 Program Sections 1-7 1.5.3 Fundamentals of Relocatable Programming 1-10 1.5.4 Example of Communication Between Program Sections 1-13 1.5.4.1 A Sample Program 1-13 1.5.4.2 Program Operation 1-16 1.5.4.3 Effects of Relocation on the Program 1-17 1.5.4.4 The Symbol Table 1-18 1.5.5 Relocation Type 1-18 1.5.5.1 Absolute Expressions 1-19 1.5.5.2 Simple Relocation Expressions 1-19 1.5.5.3 CDF/CIF Relocation Expressions 1-19 1.5.5.4 .FSECT Relocation Expressions 1-19 1.5.5.5 Complex Relocation Expressions 1-19 1.6 THE ASSEMBLY PROCESS 1-20 1.6.1 Pass One -- Symbol Definition Pass 1-20 1.6.2 Pass Two -- Binary Code Generation Pass 1-21 1.6.3 Pass Three -- Listing Pass 1-21 1.6.4 Pass Four -- Cross-Reference (KREF) Listing Pass 1-21 1.7 THE LINKING PROCESS 1-22 1.7.1 Pass One -- Linking 1-22 1.7.2 Pass Two -- Loading 1-22 iii CONTENTS (Cont.) Page CHAPTER 2 MACREL SOURCE PROGRAM FORMAT 2-1 2.1 MACREL STATEMENTS 2-1 2.1.1 Labels 2-1 2.1.2 Instructions, Directives or Data 2-1 2.1.3 Comments 2-2 2.2 FORMAT EFFECTORS 2-2 2.2.1 Form Feed 2-2 2.2.2 Tabulations 2-2 2.2.3 Statement Terminators 2-2 CHAPTER 3 THE PDP-8 MACHINE INSTRUCTION SET 3-1 3.1 MEMORY REFERENCE INSTRUCTIONS 3-1 3.1.1 Addressing Modes 3-2 3.2 MICROINSTRUCTIONS 3-3 3.2.1 Operate Microinstructions 3-3 3.2.2 Input/Output Transfer Microinstructions 3-5 3.3 AUTOINDEXING 3-5 3.4 STANDARD INSTRUCTION SET 3-6 3.5 CONSTANTS 3-10 CHAPTER 4 EXPRESSIONS AND THEIR COMPONENTS 4-1 4.1 MACREL CHARACTER SET 4-1 4.1.1 Alphanumeric Characters 4-1 4.1.2 Special Characters and Operators 4-1 4.2 SYMBOLS 4-2 4.2.1 Permanent Symbols 4-3 4.2.2 Program-Defined Symbols 4-4 4.2.3 Labels 4-4 4.2.4 Local Symbols 4-6 4.2.5 Backslash (\) Special Operator 4-7 4.2.6 Symbols and Relocation 4-9 4.3 DIRECT ASSIGNMENT STATEMENT 4-9 4.4 CURRENT LOCATION COUNTER 4-11 4.5 LITERALS 4-11 4.5.1 Current Page Literals 4-11 4.5.2 Page Zero Literals 4-14 4.6 NUMBER REPRESENTATION 4-15 4.6.1 Uparrow B (^B) -- Binary Representation 4-15 4.6.2 Uparrow D (^D) -- Decimal Representation 4-16 4.6.3 Uparrow O (^O) -- Octal Representation 4-16 4.6.4 Period (.) -- Decimal Representation 4-16 4.7 ASCII DATA REPRESENTATION 4-16 4.7.1 Double Quote (") -- ASCII Representation 4-17 4.7.2 Single Quote (') -- ASCII Pair 4-17 4.7.3 Uparrow Double Quote (^") -- Control Character Representation 4-18 4.8 MACREL ARITHMETIC OPERATORS 4-18 4.8.1 Plus Sign (+) -- Addition 4-18 iv CONTENTS (Cont.) Page 4.8.2 Minus Sign (-) -- Subtraction 4-19 4.8.3 Uparrow (^) -- Multiplication 4-19 4.8.4 Percent Sign (%) -- Division 4-19 4.8.5 Ampersand (&) -- Boolean AND 4-20 4.8.6 Exclamation Point (') -- Inclusive OR (or Shift) 4-20 4.8.7 Space ( ) and Tab -- Inclusive OR 4-20 4.9 SPECIAL OPERATORS 4-21 4.9.1 Memory Reference Instructions 4-22 4.9.2 I -- Indirect Addressing 4-23 4.9.3 Z -- Page Zero Addressing 4-24 4.9.4 CIF and CDF Instructions 4-24 4.9.5 EDF -- Evaluate Data Field 4-25 4.9.6 .FLD 4-26 4.9.7 XEDF 4-26 4.9.8 .LEVEL 4-27 4.10 EXPRESSION EVALUATION AND SYNTAX 4-27 4.10.1 Operator Precedence and Order of Evaluation 4-28 4.11 USES OF EXPRESSIONS 4-29 4.12 EXPRESSIONS AND RELOCATION 4-30 CHAPTER 5 MACREL DIRECTIVES 5-1 5.1 ASSEMBLY LISTING AND BINARY OUTPUT CONTROL DIRECTIVES 5-1 5.1.1 Assembly Listing Control Directives 5-2 5.1.1.1 .LIST and .NOLIST 5-2 5.1.1.2 .TITLE 5-3 5.1.1.3 .SBTTL 5-4 5.1.1.4 .LISTWD Special Variable 5-4 5.1.2 Other PAL8 Directives 5-5 5.1.2.1 XLIST 5-5 5.1.2.2 EJECT 5-5 5.1.2.3 NOPUNCH and ENPUNCH 5-6 5.2 RADIX CONTROL DIRECTIVES 5-6 5.2.1 .RADIX 5-6 5.2.2 Other PAL8 Directives 5-7 5.3 DATA STORAGE DIRECTIVES 5-7 5.3.1 ZBLOCK 5-7 5.3.2 TEXT 5-8 5.3.2.1 Simple Form of the TEXT Directive 5-8 5.3.2.2 Complex Form of the TEXT 5-10 5.3.2.3 TEXT Options 5-11 5.4 CODE LOCATION DIRECTIVES 5-13 5.4.1 Asterisk (*) 5-14 5.4.2 PAGE 5-16 5.4.3 FIELD 5-17 5.4.3.1 FIELD Directive in Named Program Sections 5-17 5.4.3.2 FIELD Directive in Unnamed Program Sections 5-18 5.4.4 RELOC 5-19 5.5 CONDITIONAL ASSEMBLY DIRECTIVE 5-20 v CONTENTS (Cont.) Page 5.5.1 Nested Conditional Assembly Directives 5-23 5.5.2 Other PAL8 Conditional Assembly Directives 5-24 5.6 ASSEMBLY CHAINING DIRECTIVES 5-24 5.6.1 .INCLUDE 5-24 5.6.2 .CHAIN 5-25 5.7 USER SERVICE ROUTINE (USR) COMMUNICATION DIRECTIVES 5-26 5.7.1 DEVICE 5-26 5.7.2 FILENAME 5-26 5.8 LOADING INFORMATION DIRECTIVES 5-27 5.8.1 .START 5-27 5.8.2 .JSW 5-28 5.8.3 .VERSION 5-29 5.9 SYMBOL TABLE MODIFICATION DIRECTIVES 5-29 5.9.1 EXPUNGE 5-29 5.9.2 FIXMRI 5-31 5.9.3 FIXTAB 5-32 5.10 STACK MANIPULATION DIRECTIVES 5-33 5.10.1 .PUSH 5-33 5.10.2 .POP 5-34 5.11 ASSEMBLY OPTIONS DIRECTIVES 5-34 5.11.1 .ENABLE 5-35 5.11.2 .DISABL 5-37 5.11.3 .ENABWD Special Variable 5-37 CHAPTER 6 MACRO AND REPEAT DIRECTIVES 6-1 6.1 MACRO DEFINITIONS 6-3 6.1.1 .MACRO and .ENDM Directives 6-3 6.2 MACRO CALLS 6-6 6.3 MACRO ARGUMENTS 6-7 6.3.1 Actual Arguments 6-7 6.3.2 Substrings of the Argument 6-9 6.3.2.1 .NCHAR Special Operator 6-10 6.3.3 Symbols and Names in Macros 6-11 6.3.4 Apostrophe (') Special Operator 6-12 6.4 NESTED MACROS 6-13 6.4.1 Nested Macro Definitions 6-13 6.4.2 Nested Macro Calls 6-14 6.4.3 .MEXIT Directive 6-15 6.4.4 Concatenation in Nested Macros 6-16 6.5 CONDITIONAL ASSEMBLY DIRECTIVES IN MACROS 6-16 6.5.1 Nested Conditional Source Code in Macros 6-17 6.5.2 .NARGS Special Operator 6-19 6.6 DEFINING AND CALLING REPEAT BLOCKS 6-19 6.6.1 .REPT and .ENDR Directives 6-20 6.6.2 Nested Repeats 6-20 CHAPTER 7 RELOCATION 7-1 7.1 THE PROGRAM SECTION DIRECTIVES 7-2 vi CONTENTS (Cont.) Page 7.1.1 Unnamed Program Sections 7-4 7.1.2 .ASECT 7-4 7.1.3 .RSECT 7-5 7.1.4 .ZSECT 7-6 7.1.5 .XSECT 7-7 7.1.6 .DSECT 7-9 7.1.7 .FSECT 7-10 7.1.8 Summary of Relocation Performed by LINK 7-12 7.1.9 .SECT * Directive 7-13 7.2 INTER-MODULE COMMUNICATION DIRECTIVES AND SPECIAL OPERATORS 7-14 7.2.1 .EXTERNAL 7-14 7.2.2 .ZTERNAL 7-15 7.2.3 .GLOBAL and == 7-16 7.2.4 .SECREF 7-17 7.2.5 .ENTRY 7-17 7.2.6 CDF Special Operator 7-18 7.2.7 CIF Special Operator 7-19 7.3 HOW TO WRITE RELOCATABLE CODE 7-21 CHAPTER 8 USING MACREL AND KREF 8-1 8.1 RUNNING MACREL 8-1 8.1.1 MACREL Command String 8-1 8.1.2 MACREL Command String Examples 8-4 8.1.3 MACREL Terminal Error Messages 8-5 8.1.3.1 Run-Time Control Commands 8-5 8.1.3.2 Default Terminal Conditions 8-6 8.1.3.3 Terminal Message Format 8-6 8.1.4 Listing Error Messages 8-7 8.1.5 Program Listing Format 8-7 8.1.5.1 Line Number Column 8-8 8.1.5.2 Current Location Counter Value Column 8-8 8.1.5.3 Absolute Assembled Value Column 8-9 8.1.6 Symbol Table Format 8-10 8.1.7 Example Program Listing 8-11 8.1.7.1 Assembly Listing 8-11 8.1.8 Symbol Table Listing 8-14 8.2 RUNNING KREF 8-15 8.2.1 KREF Command String 8-15 8.2.2 Description and Example of KREF Listing 8-15 CHAPTER 9 USING LINK 9-1 9.1 RUNNING LINK 9-1 9.1.1 LINK Command String 9-1 9.1.2 LINK Command String Example 9-3 9.2 RULES FOR USING OVERLAY OPTIONS 9-3 9.3 LINK LIBRARIES 9-6 9.4 LINK ERROR MESSAGES 9-7 9.5 LINK LOAD MAP DESCRIPTION AND EXAMPLE 9-11 vii CONTENTS (Cont.) Page CHAPTER 10 ADVANCED TECHNICAL TOPICS 10-1 10.1 MACREL SYMBOL TABLE SIZE 10-1 10.2 RELOCATABLE BINARY OBJECT MODULE FORMAT 10-2 10.2.1 LSD Preface 10-2 10.2.2 LSD Description 10-3 10.2.3 Text Description 10-4 10.2.3.1 Flag Field Meaning 10-5 10.2.3.2 Loader Codes Generated by MACREL 10-5 10.3 LINK PERFORMANCE 10-8 10.3.1 LINK Processing of Program Section Definitions 10-8 10.4 LINK LIBRARY 10-8 10.5 WRITING AND USING OVERLAYS 10-9 10.5.1 Writing Overlay Code 10-10 10.5.2 How Overlays Work 10-13 10.5.3 Overlay Driver 10-14 10.6 SAVE FILE FORMAT 10-14 10.7 MACRO LIBRARY 10-17 10.8 SETTING THE CURRENT LOCATION COUNTER TO AN UNKNOWN VALUE 10-18 APPENDIX A ASCII CHARACTER SET A-1 APPENDIX B MACREL-PAL8 COMPATIBILITY SUMMARY B-1 APPENDIX C MACREL PERMANENT SYMBOL TABLE C-1 APPENDIX D MACREL DIAGNOSTIC ERROR MESSAGES D-1 INDEX Index-1 FIGURES FIGURE 1-1 Program Sections and Modules 1-10 1-2 Example of Communication Between Program Sections 1-13 3-1 Memory Reference Instruction Bit Assignments 3-2 3-2 Group 1 Operate Microinstruction Bit Assignments 3-3 3-3 Group 2 Operate Microinstruction Bit Assignments 3-4 3-4 Group 3 Operate Microinstruction Bit Assignments 3-4 3-5 Extended Memory Bit Mapping for CDF and CIF Instructions 3-10 4-1 Extended Memory Field Bit Layout for XEDF 4-27 viii CONTENTS (Cont.) Page FIGURES (Cont.) 4-2 BIT Assignments for .LEVEL Special Operator 4-27 5-1 Example of TEXT Option Processing 5-12 6-1 Macro Definition and Storage 6-5 6-2 Macro Expansion 6-7 6-3 Example of Nested Conditional Source Code in Macros 6-18 6-4 Example of a Nested Repeat Block 6-22 6-5 Example of the Expansion of a Nested Repeat Block 6-23 8-1 Example Program Listing 8-11 8-2 Example of Symbol Table Listing 8-14 8-3 Example of KREF Listing 8-16 9-1 Example of LINK Load Map 9-12 10-1 Object Module Format 10-2 10-2 LSD Entry Format 10-4 10-3 Flag Words 10-4 10-4 Loader Code 10-5 10-5 Library File Format 10-9 10-6 MACREL/LINK Overlay Structure (numbers in octal) 10-11 10-7 Permissible JMS's Between MAIN and Overlays 10-12 10-8 Transfer Vector Table 10-13 10-9 Memory Control Block 10-15 10-10 Memory Segment Double Words 10-16 10-11 Overlay Storage 10-16 TABLES TABLE 1-1 Types of Sections 1-8 4-1 Special Characters and Operators 4-2 4-2 Processing of CDF/CIF Expressions 4-25 4-3 Relocation Types Resulting from Addition and Subtraction Operations 4-30 4-4 Relocation Types Resulting from Other Arithmetic Operations 4-31 5-1 .LIST and .NOLIST Options 5-2 5-2 .LISTWD Bit Assignments 5-5 5-3 FIELD Directive Processing for Named Program Sections 5-18 5-4 Conditions for the .IF Conditional Assembly Directive 5-22 5-5 .ENABLE Directive Options 5-36 5-6 .DISABL Directive Options 5-37 5-7 .ENABWD Bit Assignments 5-39 7-1 Types of Program Sections 7-3 7-2 Summary of Program Section Relocation 7-12 ix CONTENTS (Cont.) Page TABLES (Cont.) 8-1 MACREL Command String Options 8-2 8-2 Terminal/Control Commands 8-6 8-3 MACREL Error Codes 8-8 8-4 Symbol Table Descriptor Codes 8-10 9-1 LINK Control Options 9-4 9-2 LINK Error Messages 9-7 9-3 LINK-Detected System Errors 9-9 10-1 MACREL Symbol Table Size 10-1 10-2 LSD Preface 10-3 10-3 MACREL/LINK Loader Codes 10-5 10-4 Extended MACREL/LINK Loader Codes 10-7 10-5 LINK Symbol Table Size 10-8 A-1 ASCII Character Set A-1 x PREFACE ASSUMPTIONS REGARDING READER KNOWLEDGE To use this manual effectively, you must be familiar both with PDP/8 computer hardware and with assembly-language programming. You should also be familiar with OS/8 system operation, and its vocabulary. The manual provides some tutorial information, but assumes you have a general background in the above areas. If necessary, refer to the following documents for more information on any of these topics. DOCUMENTS REFERENCED IN THE TEXT The following documents are referenced in the text: PDP-8/A Minicomputer Handbook _____________________________ PDP-8/E, PDP 8/M & PDP 8/F Small Computer Handbook __________________________________________________ OS/8 Handbook _____________ OS/8 Software Support Manual ________________________________ OS/78 Handbook ______________ ABOUT THIS MANUAL The MACREL/LINK User's Manual describes the MACREL assembler and the _________________________ linking loader LINK and discusses how to write programs using MACREL and how to link the resulting object modules together with LINK. If you are an inexperienced PDP8 programmer, read the manual sequentially, beginning with Chapter 1. For the experienced PAL8 assembly language programmer, the manual also explains the differences between MACREL and older PDP/8 assemblers. Read the manual straight through, and skip over any material that is obvious (discussion of literals, etc.). In particular, begin with the Introduction, which outlines the new features of MACREL and provides an introduction to relocation. This introduction is necessary to understand the rest of the manual. Chapter 2, Source Program Format, describes the rules for formatting a MACREL source program, and shows some new features in MACREL assembly listings. Chapter 3, the Instruction Set, may be skipped. Chapter 4, Symbols and Expressions, contains some new MACREL features plus a discussion of how relocation affects symbols, the current location counter, direct assignment xi statements, and expressions. Chapter 5, Directives, describes the general assembler directives (referred to as pseudo-operators in PAL8). Chapter 6 describes macros and how to use them. Chapter 7, Relocation, describes the relocation features and how to write relocatable programs. Chapters 8 and 9 explain how to run MACREL and LINK, respectively. Chapter 10 discusses certain advanced programming techniques. For the Inexperienced PDP-8 Assembly Language Programmer If you are unfamiliar with assembly languages, read the book "Introduction to Programming" first. If you are not experienced in PAL8 programming, read the manual in two passes. First become familiar with assembly language programming in absolute (non-relocatable) program sections, and then reread the manual to become familiar with relocation. You can skim over the relocation sections of the introduction (though some of the information is required to understand the rest of the manual), and read Chapters 2 through 5 carefully, writing sample programs to test out the features mentioned. Skip over the chapters on the macros and relocation and read the chapters on running MACREL and LINK so you can get your programs running. Then you can read the manual again to learn about relocation and macros. USE OF KEY TERMS Some terms are used throughout the manual in a precise, technical sense. These words include program section, program, page, field, source module, source file, relocatable binary module, linking, absolute, simply relocatable, and complex relocatable. Many of these are covered in the introduction. In particular, notice the distinctions among the terms program, program section, and module. The word "segment" is also sometimes used, but in a generic, nontechnical way (that is, a segment of code, meaning a block or group of code). DOCUMENT CONVENTIONS Examples consist of actual computer output wherever possible. Any responses that you must enter are printed in red ink to distinguish them from computer output. The symbols defined below are used throughout this manual. Symbol Definition ______ __________ [] Brackets indicate that the enclosed argument is optional. || Vertical bars indicate that a single choice must be made from a list of arguments. xii ... Ellipsis indicates optional continuation of an argument list in the form of the last specified argument. UPPER-CASE Upper-case characters indicate elements of the language CHARACTERS that must be used exactly as shown. lower-case Lower-case characters indicate elements of the language characters that are supplied by the programmer. In some instances the symbol (n) is used following a number to indicate the radix. For example, 100(8) indicates that 100 is an octal value, while 100(10) indicates a decimal value. (RET) Indicates that you must enter a carriage return. xiii CHAPTER 1 INTRODUCTION MACREL (MACro-RELocatable) is a PDP/8 based assembler that allows you to write a program using macro coding and relocatable program sections. Macros are generalized instruction sequences that can, if desired, be modified by arguments (data) when the macro is used. Relocatable program sections allow you the freedom of writing programs without regard to the location of the assembled code in PDP/8 memory. The MACREL assembler offers a number of new features to you as a PDP/8 programmer. These are outlined below. The use of these features in assembly-language programming requires some reorientation of thinking. You should read this chapter carefully. 1.1 MACREL FEATURES The main features of MACREL are relocation, macros, and supporting directives and operators. 1.1.1 Relocation Relocation refers to the automatic adjustment of memory addresses at program loading time rather than at program assembly time. This allows you to write programs without consideration of actual memory addresses. Relocation occurs in two stages: first, MACREL assembles your source file into a relocatable binary file, second, LINK converts your relocatable binary file into an executable memory image file. Normally, sections of code begin on page boundaries. MACREL/LINK may relocate these sections to some other page, but generally will not relocate them to a different place on the page. You must still write code with respect to page boundaries. Relocation provides several advantages particularly when working with large programs. You can correct, edit, assemble and list small files rather than having to perform all these functions with large, unwieldy files. Then, when you have assembled all the program modules with MACREL, you can link them together using LINK, the linking loader. By observing the simple programming techniques described in this manual, you do not have to know the location of programs in memory. In addition, by splitting the program into discrete sections that perform specific functions, you produce programs that are faster to debug and easier to understand. Finally, relocation makes it easier to construct libraries of routines that you can incorporate into your program. 1-1 INTRODUCTION In practice, you code your programs in much the same way as you always have. If, however, you specify that a given program segment is relocatable using, for example, the .RSECT directive, LINK will add a fixed number to the addresses shown in the listing causing the program to load at a different set of locations in memory. LINK also automatically handles any reference from one program section or module to another. One additional feature that MACREL and LINK provide is a system of overlays. This allows you to segment large programs so they can run in a small amount of memory. In practice, the whole overlay procedure is almost invisible. For example, if your program does a branch (JMS) to a location that is not in memory, the overlay driver, which is part of the MACREL/LINK software package, brings in the appropriate section of code, and the instruction performs as if the code had always been in memory. Except for your defining the files as overlays, MACREL and LINK automatically handle this entire procedure. 1.1.2 Macros The macro feature of MACREL allows you to predefine a generalized set of code and insert this code anywhere in a program simply by using the name of the macro. In addition, the coding inserted can be varied according to the arguments supplied. The following is a simple example of a macro definition: .MACRO SUB A, B /Subtract A from B CLA TAD A CIA TAD B .ENDM SUB The .MACRO and .ENDM directives tell MACREL that this is a macro definition. In order to call this macro, you merely need to use its name in a statement followed by the two numbers that you want to use. For example, if you want to subtract the contents of N1 from the contents of CNTR, you write the following: SUB N1, CNTR Then, when the program is assembled, the macro code appears as follows: CLA TAB N1 CIA TAB CNTR Note that the arguments shown in the definition have been replaced by the arguments specified in the macro call. 1-2 INTRODUCTION Each time you call this macro, all four instructions will be inserted into the code (the calling line does not produce any object code). Thus, use of a macro will not necessarily result in reduced program size as does, for example, a subroutine that is called repeatedly. Rather, the advantages of macros are that they allow you to predefine commonly used sequences of code, perform complicated text manipulation, and write generalized program sections that assemble in different ways according to the needs of a particular program. 1.1.3 Directives In addition to relocation and macro processing, MACREL provides you with a comprehensive set of directives (called pseudo-operators in PAL8). These directives provide for: o Repeating portions of code or data (.REPT) o Including one source file in the assembly of another (.INCLUDE) o Conditionally assembling code (.IF) o Formatting listing files (.LIST) o Printing titles and subtitles (.TITLE,.SBTTL) o Manipulating an assembly time stack (.PUSH,.POP) o Controlling data storage and expression evaluation (.ENABLE) 1.2 OVERVIEW OF ASSEMBLY AND RELOCATABLE LOADING The complete MACREL/LINK cycle consists of the following steps: o Assembly o Linking o Run These steps are discussed in the next two sections. 1.2.1 Assembling with MACREL MACREL assembles the source code into the appropriate machine-language instructions and their corresponding addresses. If the code is specified as absolute, the addresses are the actual memory addresses where the instructions are to be loaded. If the code is relocatable, 1-3 INTRODUCTION the addresses are relative to the beginning of the program section. LINK alters these addresses by adding a fixed number to each address to determine the actual memory address into which to load the code. In addition to processing instruction codes, MACREL provides a number of directives. These are instructions to the assembler itself. They specify special assembly processing, such as interpreting numbers in octal or decimal format, formatting assembly listings appropriately, or, in some cases, sending special instructions to LINK that allow it to load the code correctly. Several of the directives pertain to the creation of macros. A macro allows you to predefine a frequently used sequence of code and to include this sequence anywhere in the program by using the name of the macro (with appropriate arguments). When MACREL processes a macro, it inserts the predefined code into the assembled program in place of the macro call. Thus, the effect of macro processing is to create source code that is ready to be assembled. The macro feature behaves as if there is a separate program that you run to process the macros prior to assembly. (In actuality, it's done in one combined operation.) This allows for complex manipulation of text and data. Another group of directives pertain to relocation and program modules. They provide information to LINK that allows it to load program sections and modules correctly. Some of these directives tell the assembler how to handle the assembled code and where to load it. Other directives allow for communication between different modules of assembled code. 1.2.2 Linking with LINK The output of the MACREL assembler is a relocatable binary file. It contains the binary machine-language instructions with their relative loading addresses, information about where to load the program sections, and a list of unresolved symbols (undefined symbols declared to be .EXTERNAL). LINK, in turn, takes the relocatable binary files from one or more assembly runs, and creates a memory-image file ready to load. This memory-image file is, in essence, an exact copy of memory itself. You can load and run your program either by using LINK's /G command string option or by using the OS/8 Keyboard Monitor's R command. In order to create the memory-image file, LINK resolves all unresolved symbols first. Then, LINK determines where to load the various program sections, depending upon whether they are absolute or relocatable, and creates the memory-image file. 1.3 COMPATIBILITY OF MACREL WITH PAL8 With few exceptions, MACREL is compatible with PAL8. That is, a 1-4 INTRODUCTION program that can be assembled correctly by PAL8 can also be assembled correctly by MACREL. MACREL, however, provides a number of new features (new directives, relocation, macros, new operators, etc.), and programs using these features cannot be assembled by PAL8. The remainder of this section is devoted to a discussion of the differences between MACREL and PAL8. 1.3.1 MACREL: Differences from PAL8 The following PAL8 features either are not available in MACREL or are handled somewhat differently. They are summarized in Appendix B. 1.3.1.1 Dollar Sign ($) - In PAL8, a dollar sign ($) anywhere (except in a comment or a text string) terminates the assembly. Since $ is a legal element of a symbol name in MACREL, this feature is not implemented in MACREL. However, to retain PAL8 compatibility, MACREL treats a symbol that consists only of one or more dollar signs as an end-of-program signal. 1.3.1.2 DTORG - The PAL8 pseudo-operator DTORG is not implemented in MACREL. Its sole function is to output a special code to a piece of typesetting hardware. It has no other function. 1.3.1.3 MACREL and Literals - When a PAL8 program changes the current location counter to return to a previous page, PAL8 remembers the number of literals on that page and does not overwrite them. MACREL, on the other hand will overwrite literals (except on page zero) any time you set the current location counter to a previous page. For this reason, you should code straight through. (See Section 4.4.) 1.3.1.4 PAUSE - MACREL ignores the PAL8 pseudo-operator PAUSE (i.e., no undefined symbol error is generated). PAUSE is used by PAL8 and is included in MACREL for compatibility. 1.3.1.5 Closing Literal Expressions - PAL8 ignores the right parenthesis ()) or right square bracket (]) in a literal expression. Therefore, the literal expression includes all code to the right of the parenthesis or bracket. In MACREL, the right parenthesis or bracket terminates a literal. This difference is a problem only when you code a literal expression incorrectly. 1-5 INTRODUCTION 1.3.1.6 Terminal Support - In PAL8, if the terminal in use does not support horizontal tab and line feed, the assembler simulates them whenever a listing is output to that terminal. MACREL does not perform these functions. Either the terminal in use supports tabs and line feed, or the OS/8 TTY handler simulates them. 1.3.1.7 PAL8 Run-Time Options - There are a number of differences between PAL8 run-time options and MACREL run-time options. Only two of these directly affect program code generation and are discussed here. The remainder are listed in Appendix B. In PAL8, the /B command-string option makes the exclamation point operator (!) a 6-bit left shift instead of an inclusive OR. In MACREL, the .ENABLE SHIFT directive replaces this option. In PAL8, the /F command-string option disables the extra zero fill in TEXT pseudo-ops. In MACREL, the .DISABLE FILL directive replaces this option. 1.4 ASSEMBLING EXISTING PAL8 PROGRAMS WITH MACREL Except for the few minor incompatibilities mentioned above, PAL8 programs will assemble under MACREL as unnamed absolute sections. However, we do recommend that you name them explicitly as absolute program sections by inserting a line in the following form at the beginning of the program. .ASECT name The directive .ASECT indicates that this is an absolute section, and name is the name you supply for the section. MACREL assumes loading address of 200 in field zero by default. There are four types of files associated with MACREL: Relocatable Binary File (default extension .RB) - the output file used as input to LINK. Listing File (default extension .LS) - the output file which contains the assembly listing. KREF File (default extension .KF) - the file used by KREF, MACREL's cross-reference listing program. Source File 1, Source File 2, etc. (default extension .MA) - your file(s) that contain the ASCII source code to be assembled. 1-6 INTRODUCTION 1.5 INTRODUCTION TO MACREL RELOCATION The remainder of this chapter provides a somewhat more detailed explanation of MACREL/LINK operation. If you are new to PDP-8 assembly language programming you may wish to read Chapters 2 through 4 before reading this section. 1.5.1 Source Modules A source module is a continuous file taken as a whole. To illustrate, recall from Section 1.4 that the input file string (Source File 1), (Source File 2), ... (Source File n) defined a continuous sequence of code to MACREL. That is, after the last character of the last line of source file 1, the first character of the first line of source file 2 was read without a break. The assembler treats this sequence of files as one continuous file. In addition, any file may call other files internally if the .INCLUDE or .CHAIN directives have been specified. Again, the result is one continuous file. This continuous file, or source module, is the input to one assembly operation. The result of the assembly is a relocatable binary module (the relocatable binary file used as input to LINK) plus the listing and KREF files. To summarize (and it is important that these terms be clearly understood), the input to an assembly is a source module and the output is a relocatable binary module (plus the listing and KREF files). Note that these modules may not comprise the entire program. The program may consist of a large number of source modules that communicate among themselves through symbols that have been defined by the .EXTERNAL, .GLOBAL, .ENTRY, and various program section directives. MACREL assembles each source module separately and produces a corresponding relocatable binary module that contains information for LINK about symbols that are defined as .GLOBAL, .EXTERNAL, etc. LINK resolves all these inter-module references and determines where to load the program sections. 1.5.2 Program Sections A program section is a segment of code that begins with a program section (.SECT) directive. It is loaded by LINK into a contiguous set of memory locations. LINK may arbitrarily load different program sections into discontinuous areas of memory. Thus, if two program sections follow each other in the source module, there is no guarantee that LINK will load them into consecutive areas of memory. For PAL8 compatibility, if a sequence of code has no program section directive or name, MACREL defines it as an absolute program section (.ASECT) that loads into the absolute locations indicated on the program listing. Relocatable program sections, such as .RSECTs, are relocated by LINK at link time. The assembler handles all communication among 1-7 INTRODUCTION the various sections of a source module. If, for example, you code a JMS I (SUBR), where SUBR is a label in another section, the assembler generates information to LINK identifying (SUBR) as a literal in another section, and the program executes perfectly even though neither you nor the assembler knows at assembly time where in memory the sections will actually load. There are six types of program sections described in Table 1-1. Programs typically are coded as any combination of .ASECTs and .RSECTs. You can use .ASECT for programs that make reference to absolute memory locations and .RSECT for programs or sections of programs that will be relocated. The remaining four section types are more specialized. If you wish to use page zero locations, you may define a .ZSECT that contains the page zero table (or other code) referenced. If you want to use the autoindex registers (locations 10-17), define an .XSECT with the appropriate labels. If you have a block of data (containing no instructions) that can be located anywhere, place it in a .DSECT. Finally, if you have a number of small subroutines that you wish to load together on a page, define each subroutine as an .FSECT. Such an .FSECT must be shorter than one memory page and LINK may load it anywhere on the page. Table 1-1 Types of Sections ---------------------------------------------------------------------- | Type of Section | Description | |---------------------|----------------------------------------------| | .ASECT | ABSOLUTE SECTION - loaded into memory | | or | starting at the absolute address given. | | .SECT name, A | | |---------------------|----------------------------------------------| | .RSECT | RELOCATABLE SECTION - may be located | | or | anywhere except page 0, and is loaded | | .SECT name, R | starting at the beginning of a page. | |---------------------|----------------------------------------------| | .ZSECT | PAGE ZERO SECTION - will be loaded into | | or | page zero (locations 20-177). | | .SECT name, Z | | |---------------------|----------------------------------------------| | .XSECT | AUTOINDEX SECTION - will be loaded into | | or | locations 10-17 on page zero. | | .SECT name, X | | |---------------------|----------------------------------------------| | .DSECT | DATA SECTION - contains data and may be | | or | relocated anywhere, not necessarily | | .SECT name, D | starting on a page boundary. The section | | | may flow across pages but not across | | | fields. | ---------------------------------------------------------------------- (continued on next page) 1-8 INTRODUCTION Table 1-1 (Cont.) Types of Sections ---------------------------------------------------------------------- | Type of Section | Description | |---------------------|----------------------------------------------| | .FSECT | FLOATING SECTION - contains instructions | | or | and may be relocated anywhere (not | | .SECT name, F | necessarily beginning on a page boundary). | | | It must, however, be wholly contained | | | within a page. Several floating sections | | | may occupy one page. (It is generally used | | | for miscellaneous small subroutines.) | ---------------------------------------------------------------------- LINK can load any program section into any field, but you can specify the memory field where a program section is to be loaded by using a FIELD directive. A program section may not cross field boundaries, and may not contain more than 4095 words of data. You can define a program section using either of two syntaxes: .SECT BPROC. R This line defines a relocatable program section named BPROC. Another example is: .ASECT MAIN This uses the alternative form .ASECT rather than .SECT NAME,A and defines an absolute section named MAIN. You can explicitly specify the loading address of a program section by setting the current location counter with the asterisk directive. *300 This sets the current location counter to 300. MACREL assumes a default loading address of 200 for absolute programs, and 0 (relative to the beginning of the program section) for relocatable program sections. Note that source files, source modules, and program sections are completely different entities. Figure 1-1 shows the relationship of these terms. A given program may consist of a number of source modules, each of which is associated with one assembly operation. A module may consist of one or more program sections, each of which is a logical unit at link time: that is, it loads into a contiguous set of memory locations and is identified by an entry in a load map. Physically, a source module may consist of any number of files. One file might terminate in the middle of a program section and the next one complete that program section and go on to others. This is of no concern to the assembler, however, because it treats all source files as one continuous input stream. 1-9 INTRODUCTION ----------- A program contains | Final | one or more | Program | modules. ----------- ^ | -----------------|................. | | . ------------ ------------ ------------ A module contains | Module 1 | | Module 2 |.....| Module P | one or more ------------ ------------ ------------ sections. ^ | -----------------|................. | | . ------------- ------------ ------------- A section contains | Section 1 | | Section 2 |....| Section M | one or more memory ------------- ------------- ------------- locations. ^ | -----------------|................. | | . -------------- -------------- -------------- Memory locations | Location 1 | | Location 2 |...| Location N | contain the source -------------- -------------- -------------- code. Figure 1-1 Program Sections and Modules MACREL handles communication among program sections of one source module and in general does not require special coding. A JMS I (SUBR), where SUBR is a subroutine in another section, executes correctly without any special effort on your part. Communication between program sections in different source modules, however, requires that all references to a symbol in another module be identified by the directives .EXTERNAL, .GLOBAL, .ENTRY, or their equivalent. These directives are necessary because the other module is assembled at a different time and hence its symbols are not known to MACREL at this assembly time. For example, a TAD I (B, where B is a label in another source module, results in an undefined symbol error message, unless the symbol B is identified in a statement of the form .EXTERNAL B. Chapter 7 describes these module communication directives. 1.5.3 Fundamentals of Relocatable Programming In general, the techniques for programming a relocatable program section are the same as those for programming individual pages of an absolute program section. Since an .RSECT always loads starting at page boundaries, the effect of relocation is merely to move the whole section as a unit by some multiple of 200 (octal) memory locations. 1-10 INTRODUCTION Consider the following sequence of code: *200 CLA TAD B TAD I BPOINT JMS .+3 B, 7 BPOINT, B This would assemble (in an absolute section) as: 1 0200 *200 2 00200 7200 CLA 3 00201 1204 TAD B 4 00202 1605 TAD I BPOINT 5 00203 5206 JMP .+3 6 00204 0007 B, 7 7 00205 0204 BPOINT, B SYMBOL TABLE B 0204 BPOINT 0205 Note that the program ends by adding the value contained at location B twice (once through a direct TAD and once through an indirect TAD). It then jumps to some code following this, at location 206. If this entire piece of code is relocated to start at location *400, it results in the following: 1 0400 *400 2 00400 7200 CIA 3 00401 1204 TAD B 4 00402 1605 TAD I BPOINT 5 00403 5206 JMP .+3 6 00404 0007 B, 7 7 00405 0404 BPOINT, B Note that in the code column to the right of the address column only one line of code has changed from the previous example, namely, the indirect address pointer BPOINT. Everything else is the same. For example, TAD B still has a code value of 1204 (i.e. two's complement add the contents of location 4 on the current page). The indirect address pointer BPOINT has been incremented by octal 200, the amount of the relocation factor. In general, during relocation, instructions and ordinary data are unchanged. Twelve-bit addresses and values that are computed from them are altered by adding to them the address to which they are relocated. 1-11 INTRODUCTION For example, if this segment of code is made into an .RSECT named FLOAT, the code (including the symbol table) looks like this: 1 0000 .RSECT FLOAT 2 ?0000 7200 CLA 3 ?0001 1204 TAD B 4 ?0002 1605 TAD I BPOINT 5 ?0003 5206 JMP .+3 6 ?0004 0007 B, 7 7 ?0005 0004 + BPOINT, B SYMBOL TABLE B 0004+ FLOAT BPOINT 0005+ FLOAT FLOAT 0006 RSECT Compare this example with the one that loads at absolute address 200 and notice the following changes: 1. A question mark (?) replaces the field column of the address to show that LINK may load the program into any field. 2. The address of the first line of code is now shown as 0000 rather than 200, which is relative to the start of the program section. 3. Each succeeding address is relative in the same way. The same idea also applies to the 12-bit address stored in BPOINT, which is now 004 rather than 204, because it will be relocated at link time. 4. The plus sign (+) to the right of the code indicates that this relocation takes place. In the symbol table, FLOAT shows up as the name of this relocatable program section and has an address of zero relative to the beginning of the section. All other labels in the section, then, are defined relative to FLOAT. thus, BPOINT is 5+FLOAT. This means that, at link time, the label BPOINT will be evaluated by taking 5 and adding the value of FLOAT, the memory address of the start of the section. BPOINT consists of an absolute part of 5 and a relocatable part FLOAT. The value of BPOINT, therefore, is the sum of the two parts. The absolute part does not change, but the relocatable part is unknown at assembly time and is determined by LINK after memory is allocated. These effects of relocation are generally not of major concern to you because MACREL and LINK automatically handle them. However, it is helpful to understand what is happening, and how it affects the program listing. 1-12 INTRODUCTION 1.5.4 Example of Communication Between Program Sections In general, communication between program sections is the same as communication between different pages of an absolute program section. For example, in an absolute section, a TAD I (B) executed on one page where B is a label on another page, generates an on-page literal containing the address of B on the other page. In the same way, a TAD I (B) in a relocatable section, where B is a label in another relocatable section, generates an on-page literal pointer, and after linking, that pointer contains the actual address of B in the other section. 1.5.4.1 A Sample Program - The example program SKIFOC shown in Figure 1-2 illustrates communication between program sections. The program obtains a character stored in a buffer, tests the character to see if it is an octal digit, and then prints the result of the test. The program consists of three program sections: .RSECT TESTP, .RSECT SUBS and .DSECT DATA. .RSECT TESTP is the main section of the program. It first calls a subroutine SKIFOC in the .RSECT SUBS and then calls PRINT, the second subroutine in SUBS. When both subroutines are complete, TESTP increments a pointer to the buffer in .DSECT DATA and then checks to see if all the characters in the buffer have been tested. .RSECT SUBS has two subroutines: SKIFOC and PRINT. SKIFOC tests a character from the buffer and then returns to the calling program, TESTP, at either of two locations. PRINT then prints on the terminal, either an "N" or an "S" as a result of the test in SKIFOC. The .DSECT DATA contains the buffer that stores the characters being tested. In this example there are four characters: /, 0, 7, and 8. The final location in the buffer contains null (binary zero), which is used to terminate the test. This example is the listing file of the relocatable binary module produced by MACREL. The assembler adds three columns to the source module during assembly. The first column is the source module line number, the second is the relative address in the section and the third and final column is the code. Items in the code column that are marked by an asterisk (*) will be altered at link time. 1 0000 .RSECT TESTP /TEST SKIFOC ROUTINE 2 0000 FIELD 0 /LOAD IN FIELD 0 3 4 5 00000 4777 START, JMS I (SKIFOC) /CALL SKIFOC,IS IT AN OCTAL DIGIT Figure 1-2 Example of Communication Between Program Sections 1-13 INTRODUCTION 6 00001 1376 TAD ("N-"S) /NO,SET TO PRINT AN ASCII "N" 7 00002 1375 TAD ("S) /YES,GET AN ASCII "S" 8 00003 4774 JMS I (PRINT) /CALL SUB ROUTINE "PRINT" 9 00004 2211 ISZ BLOC /INCREMENT BUFFER POINTER 10 00005 1611 TAD I BLOC /GET NEXT CHARACTER 11 00006 7640 SZA CLA /IS IT ZERO 12 00007 5200 JMP START /NO, TEST IT 13 00010 5773 JMP I (7605) /YES,RETURN TO KEYBOARD MONITOR 14 15 00011 0000 * BLOC, BUFFER /STORAGE FOR LOCAL DATA 16 17 18 19 ----- 00173 7605 00174 0021 * 00175 0323 00176 7773 00177 0004 * 20 0000 .RSECT SUBS /SECTION OF SUB ROUTINES ,SKIFOC & PRINT 21 0000 FIELD 0 /ALSO IN FIELD 0 22 23 24 /STORE LOCAL DATA FOR THIS SECTION 25 26 00000 7520 NEG0, -"0 /MINUS ASCII 0 27 00001 7511 NEG7, -"7 /MINUS ASCII 7 28 00002 0011 * BLOCAD, BLOC /THE ADDRESS OF "BLOC" 29 00003 0000 VBLOC, 0 /ON PAGE STORAGE FOR "BLOC" 30 31 32 33 00004 0000 SKIFOC, 0 /ROUTINE TO TEST THE CHARACTER IN BUFFER 34 /IF IT IS AN OCTAL DIGIT SKIP NEXT 35 /INSTRUCTION (LINE 6) IN THE CALLING 36 /PROGRAM 37 00005 7200 CLA /CLEAR ACCUMULATOR Figure 1-2 (Cont.) Example of Communication Between Program Sections 1-14 INTRODUCTION 38 00006 1602 TAD I BLOCAD /GET ADDRESS OF BUFFER 39 00007 3203 DCA VBLOC /STORE IT ON PAGE 40 00010 1603 TAD I VBLOC /GET CHARACTER AT THIS ADDRESS 41 00011 1200 TAD NEG0 /SUBTRACT ASCII 0 42 00012 7710 SPA CLA /IS IT > OR =TO 0 43 00013 5604 JMP I SKIFOC /NO, RETURN TO CALLING PROGRAM 44 00014 1603 TAD I VBLOC /YES, GET CHARACTER AND TEST AGAIN 45 00015 1201 TAD NEG7 /SUBTRACT ASCII 7 46 00016 7750 SPA SNA CLA /IS IT < OR= TO 7 47 00017 2204 ISZ SKIFOC /YES, INCREMENT RETURN ADDRESS OF 48 /CALLING PROGRAM 49 00020 5604 JMP I SKIFOC /NO, RETURN TO CALLING PROGRAM 50 .RSECT TESTP /TEST SKIFOC PAGE 1-1 FILE 1 51 52 00021 0000 PRINT, 0 /A ROUTINE TO PRINT ONE ASCII CHARACTER 53 54 00022 6046 TLS /PRINT THE CHARACTER 55 00023 6041 TSF /TEST AND SKIP ON FLAG 56 00024 5223 JMP .-1 /STILL PRINTING ,TRY / AGAIN 57 00025 7200 CLA 58 00026 5621 JMP I PRINT /RETURN TO CALLING PROGRAM 59 60 61 62 0000 .DSECT DATA /DATA SECTION TO STORE THE TEST 63 /CHARACTERS ,TWO OCTAL DIGITS AND 64 /TWO THAT ARE NOT OCTAL 65 0000 FIELD 0 /THIS SECTION IS ALSO IN FIELD 0 66 67 00000 0257 BUFFER, "/ /NOT-OCTAL 68 00001 0260 "0 /OCTAL 69 00002 0267 "7 /OCTAL 70 00003 0270 "8 /NOT-OCTAL 71 00004 0000 0 /THE .RSECT TESTP TESTS EACH Figure 1-2 (Cont.) Example of Communication Between Program Sections 1-15 INTRODUCTION 72 /EACH CHARACTER ,WHEN IT FINDS THE ZERO 73 /IN THE BUFFER ,IT STOPS TESTING AND 74 /RETURNS TO MONITOR. (SEE LINES 11 & 13 /ABOVE) Figure 1-2 (Cont.) Example of Communication Between Program Sections 1.5.4.2 Program Operation - Program operation is described below. All references are to the line numbers in the listing. Because TESTP calls two subroutines, program execution begins at line 5, jumps to line 33, continues through line 49, and then returns to TESTP. After the return from the first subroutine, execution jumps to line 52, proceeds through line 58, and again returns to the calling program TESTP. The second return is to line 9 and the program continues through lines 10, 11, 12 and 13. Line 5 is the start of the program and calls the subroutine SKIFOC. Execution then continues on line 33 which stores the return address for SKIFOC. The subroutine is complete in lines 37 through 48. SKIFOC gets the address of the buffer (TAD I BLOCAD, line 38), stores it at VBLOC (line 39) then gets the contents of that address (line 40 and again line 44) and checks to see if the character (contents of VBLOC) is in the range ASCII 260 to ASCII 267 (lines 41 and 42 and again lines 45 and 46). If the character is in this range SKIFOC increments the return address stored at line 33 and returns to TESTP at line 7. If the character is out of range (i.e., not octal), SKIFOC does a normal return to TESTP at line 6. If the return to TESTP is to line 6, the accumulator is loaded with the literal at relative location 00176 (-5, the difference between ASCII N and ASCII S) and then summed with line 7 (ASCII S) to produce the ASCII code for N. If the return is to line 7 the accumulator is loaded with only the literal at location 175, the ASCII value of S. TESTP now jumps to the subroutine PRINT. PRINT is located at the 21st address in the .RSECT SUBS (line 52). This address is stored as a literal at address 00174 and marked with an asterisk to show that it will be relocated at link time. PRINT sends the contents of the accumulator to the terminal and then returns to the calling program. TESTP now increments the pointer to the buffer (line 9), obtains the contents of the buffer (line 10), and checks for zero (line 11). If the buffer now has a zero value (end of test) TESTP exits to the monitor (line 13), if the buffer has another character, TESTP starts over again (at line 5) with the JMP START instruction on line 12. 1-16 INTRODUCTION When run, the program produces the following output: NSSN . This indicates that the first and last characters are not octal digits, while the middle two are. The period is printed by the OS/8 Keyboard Monitor upon completion. 1.5.4.3 Effects of Relocation on the Program - Although this sample program consists of three sections, its construction is identical to a program that is located in three pages of one absolute section. In fact, you could replace the three sets of program directives and field statements by three PAGE directives and program operation would be virtually identical. The following is a brief review of the program in terms of communication between program sections. (You can compare this description with interpage communication within a single absolute program section.) On line 5, there is an indirect JMS to an address (SKIFOC) in another section. This is handled by the literal at address 00177 (below line 19). This literal shows up in the listing as 0004. The actual memory address of SKIFOC is entered into this location at LINK time. Because SKIFOC is at relative address 4 in the section SUBS, the actual value of the literal will be computed as 4 (its place in SUBS) plus SUBS (the loading address of the beginning of the section). The same principle applies to line 8, JMS I (PRINT, where PRINT is another subroutine in SUBS. Here the literal is stored in address 174, and has the value of 0021*. This means that the actual value will be altered to 21 (it's the 21st entry in SUBS) plus SUBS (the loading address of the beginning of the section). The location BLOC (line 15) contains a pointer to BUFFER in the DATA section. Again, it contains the address of the beginning of the DATA section at link time. When TESTP jumps to SKIFOC and PRINT, it stores the appropriate return address in the entry word of each routine. The return to the calling program (even though it's in another section) is handled normally by the hardware; the program uses the usual indirect JMP to the entry. On line 28, the section SUBS has a pointer to BLOC in TESTP. The code shows a 0011*. Again, this is modified at link time by adding 11 (its position in TESTP) to the value of TESTP. Once the address of BLOC is known, the actual communication between the sections is easily initiated. Note that although we used only JMS and TAD instructions to communicate between sections in this sample program, the same 1-17 INTRODUCTION principles apply to any memory reference instructions used between sections. 1.5.4.4 The Symbol Table - The symbol table for this example contains two types of entries: section names and labels. The numbers next to the section names (DATA, SUBS, and TESTP) indicate the size of the sections. Notice that although TESTP contains fewer lines of code than SUBS, TESTP shows up as a larger section (octal 200 as opposed to octal 27) because it uses literals, which load from the end of the page. Thus the entire page is effectively used. (LINK will not load one section into a gap in another.) The remaining entries in the symbol table are labels, and in each case, the entry consists of an octal number that shows the relative location in the section, a plus sign, and the name of the section in which they appear. / A PROGRAM TO TEST "SKIFOC" SYMBOL TABLE BLOC 0011+ TESTP BLOCAD 0002+ SUBS BUFFER 0000+ DATA DATA 0006 DSECT NEG0 0000+ SUBS NEG7 0001+ SUBS PRINT 0021+ SUBS SKIFOC 0004+ SUBS START 0000+ TESTP SUBS 0027 RSECT TESTP 0200 RSECT VBLOC 0003+ SUBS The symbolic name of the section has a value equal to the amount of its relocation offset calculated at LINK time. Thus, if TESTP loads into location 200, its value at link time will be 200, and BLOC (shown as 0011+ TESTP) will have a value of 11 + TESTP, or 211. That is, the location BLOC has an actual memory address of 211. The same principle applies to all other labels in the symbol table. 1.5.5 Relocation Type Absolute program sections may only contain expression and symbol values that are known at assembly time. Relocatable program sections may contain expression and symbol values that are known either at assembly time or at LINK time. There are five types of relocation associated with them: o Absolute 1-18 INTRODUCTION o Simple Relocation o CDF/CIF Relocation o .FSECT Relocation o Complex Relocation 1.5.5.1 Absolute Expressions - An absolute expression is evaluated as a fixed 12-bit number during assembly. For example, the expression N= "A+1 causes "A+1 to be evaluated and the result assigned to N. N, then, has a value of 301 (ASCII A) + 1 or an absolute value of 302. 1.5.5.2 Simple Relocation Expressions - A simple relocation expression consists of an absolute part plus one relocatable part that must be evaluated at link time. A label in an .RSECT is a good example. If the following example is part of a relocatable section: .RSECT ANA CLA TAD B TAD C LOOP, TAD A . . . ANA has an absolute part of zero and a relocatable part to be evaluated at link time. LOOP has an absolute part of 3 (location 0003 in .RSECT ANA) and a relocatable part of ANA. Thus LOOP appears in the symbol table as 0003 + ANA. 1.5.5.3 CDF/CIF Relocation Expressions - An expression is considered CDF/CIF relocatable whenever it uses a value that results from using either the CDF or CIF special operators (see Section 4.9.4). 1.5.5.4 .FSECT Relocation Expressions - An expression is considered .FSECT relocatable whenever it uses a value that results from a relocatable expression residing in an .FSECT, .XSECT, or .ZSECT program section (see Section 7.1). 1.5.5.5 Complex Relocation Expressions - An expression is complex relocatable when it cannot be reduced during assembly to one of the relocation types described in the preceding sections. For example, 1-19 INTRODUCTION continuing with the previous program segment, suppose the code LOOP %4 appeared as follows: .RSECT ANA CLA TAD B TAD C LOOP, TAD A . . . A, LOOP %4 . . . The expression at location A is complex relocatable because its value is 0003 + ANA divided by 4, which MACREL cannot reduce to a simple relocation expression at assembly time. The entire expression, LOOP %4 is passed on intact for LINK to evaluate. An expression need not look complicated to be complex relocatable. For example, B=LOOP+ANA is a complex relocatable expression because it cannot be evaluated at assembly time to an absolute portion and one relocatable part. Here, B would evaluate to 3+<2^ANA> (i.e., 3+ANA+ANA) and twice ANA is not one relocatable part. On the other hand, B=LOOP-ANA is not a complex relocatable expression; in fact, B evaluates to the absolute quantity 3 (3+ANA-ANA). In general, complex CDF/CIF and .FSECT relocatable expressions should be of little concern unless you have unusual code constructions. Relocation is covered in greater detail in Chapter 7. 1.6 THE ASSEMBLY PROCESS The MACREL assembler performs a maximum of four passes through the source module. The number of passes is determined by the number of output files in the file-specification line. (Pass one is always run -- providing an input file is specified.) See Section 1.4 for a list of the file types. 1.6.1 Pass One -- Symbol Definition Pass On its first pass, MACREL constructs the symbol table. The symbol table contains both permanent symbols and program-defined symbols. Each symbol stored is identified according to type, whether or not it is defined, and (if defined) its value. Additional codes indicate whether it has been declared as .EXTERNAL, .GLOBAL, .ENTRY, etc. If the symbol is a macro name, the entire text of the macro is stored in the symbol table area as well. Because source code lines are read and 1-20 INTRODUCTION immediately processed (i.e., not retained in memory), the symbol table requires a large number of memory locations. Thus, a large program being assembled on a machine with insufficient memory could exceed the available symbol table space. In addition to creating the symbol table, the assembler performs its normal algorithm of processing expressions, directives, etc. Thus, most error messages of a syntax nature are generated on pass one. However, no undefined symbol error messages are printed on pass one since the symbol table is not complete until the end of the pass. 1.6.2 Pass Two -- Binary Code Generation Pass If you specify an output file (relocatable binary file, default extension .RB), the assembler starts generating binary code. MACREL reads a line of source code, looks up any symbols in the symbol table, evaluates expressions, and writes the resultant code into the output file. In the case of directives, it performs the action specified by the directive. If you do not specify any output files, the assembler performs error checking on pass one, and then returns to the OS/8 Keyboard Monitor. On this second pass, all symbols must be defined; any undefined or illegally redefined symbol produces an error message. At the end of the pass, all symbols that have been defined by a declaration such as .ENTRY, .EXTERNAL, .GLOBAL and the like, or that are the names of sections are written out in a block of code. This block of code, called the Loader Symbol Dictionary (LSD), is used by LINK to define all global symbols. In addition to global symbols, the LSD contains the size of each section in the module, which LINK uses to determine loading addresses. 1.6.3 Pass Three -- Listing Pass If you specify the second output file (the listing file, default extension .LS), MACREL performs pass three. This pass is essentially the same as pass two but instead of writing binary code, MACREL produces the listing file. At the end of the listing file, the assembler outputs the symbol table as part of the listing. 1.6.4 Pass Four -- Cross-Reference (KREF) Listing Pass If you specify the third output file (the KREF file, default extension .KF), MACREL makes a fourth pass to create the KREF file (cross-reference listing). Note that this is different from PAL8's CREF file. The KREF listing tabulates program-defined symbols 1-21 INTRODUCTION alphabetically and, after each symbol, the line numbers of every line that references that symbol. 1.7 THE LINKING PROCESS The output of one assembly operation is a relocatable binary module in file form. LINK takes up to 128 such files, combines them, and prepares a memory-image file that is ready to load into memory. If desired, LINK also loads the file into memory and starts it. LINK performs this operation in two passes. 1.7.1 Pass One -- Linking On the first pass, LINK creates a Global Symbol Table (GST), which is a combination of all the Loader Symbol Dictionaries (LSDs). In particular, LINK searches through the LSDs of the input files looking for unresolved references. For every symbol in a source module that is defined by an .EXTERNAL or .ZTERNAL directive, LINK searches other modules for .GLOBAL or .ENTRY declarations of the same symbol. As each match is made, the symbol is defined and the reference is satisfied. This process is called linking. LINK continues this process until all .EXTERNAL or .ZTERNAL references are resolved. Normally, this will occur by the end of pass one. If, however, reference is made to programs on a library file, several passes may be required to resolve all references. This is because LINK is more selective when referring to a library file. It selects only modules from the file that are actually referenced, rather than loading everything. However, one library program may reference another one, and so on in turn, and a number of passes may be required to resolve all references. At the end of this process (logical pass one) LINK will have resolved all references unless there is an error. The resulting Global Symbol Table (GST) is then used for pass two. 1.7.2 Pass Two -- Loading Having defined all symbols, LINK allocates memory. All of the section references in the table are sorted, primarily by the size of the program section. Memory is allocated, working from the beginning of the table (largest section) to the end. LINK performs an algorithm that ensures that sections are allocated correctly. In some cases, this may mean a considerable change from the original "largest first" order. The result is that, at the end of this operation, all sections have been allocated memory space. In particular, the actual loading addresses of section names are determined. For example, up until now, 1-22 INTRODUCTION in the section .RSECT MAIN, MAIN had a value (address) of 0+MAIN. Now, MAIN will be given an actual numerical value. Having allocated memory, LINK writes the memory-image file (default extension .SV). LINK also reads the relocatable binary modules again, but this time, as each undefined symbol in the file is referenced, it looks up the symbol in the Global Symbol Table, adds the absolute part, and inserts the correct value. This is the relocation function of LINK. For example: .RSECT MAIN MPTR, NUM1 . . . TAD I MPTR . . . .RSECT MATH CLA TAD A JMP .+4 NUM1, 0 . . . The line MPTR, NUM1 in the .RSECT MAIN contains a 12-bit pointer to NUM1 in .RSECT MATH. Prior to this time, this pointer word contained the simply-relocatable value MATH+3. Now, if the section MATH has been determined to load at location 4200 (i.e., MATH=4200), when LINK reads the MATH+3 reference in the relocatable binary module, it looks up MATH in the table, adds 3, and stores the value 4203 into the memory-image file. LINK continues in this way until the entire file has been written. The memory-image file contains both addresses and the code to be loaded into those addresses. You can load the memory-image file into memory using either the OS/8 Keyboard Monitor's R command, or LINK's /G command string option. 1-23 CHAPTER 2 MACREL SOURCE PROGRAM FORMAT 2.1 MACREL STATEMENTS Source programs are usually prepared on the console terminal (using an OS/8 editor) as a sequence of statements. Each statement is written on a single line and is terminated by typing the RETURN key. The MACREL line buffer can store 128 characters including the carriage return. There are three types of elements in a MACREL statement line that are identified by the order of their appearance in the statement and by the separating (or delimiting) character following or preceding the element. These are: 1. Label, 2. Instruction, directive, or data 3. Comment A statement must contain at least one of these elements and may contain some combination of them. Any combination must be in the order given and they may be separated from each other by any number of spaces or tabs. The assembler interprets and processes the statements, generating one or more binary instructions or data words, or performing an assembly process. 2.1.1 Labels A label is the symbolic name created to identify the location of a statement in the program. If present, the label is written first in a statement. It must be a legal symbol name and be terminated by a comma or colon. Furthermore, there must be no intervening spaces between any of the characters and the comma, or colon. 2.1.2 Instructions, Directives or Data An instruction may be one or more of the mnemonic machine instructions explained in Chapter 3. Directives are direct instructions to the MACREL assembler to perform certain functions. Since directives are instructions to the assembler itself they generally do not create code. 2-1 MACREL SOURCE PROGRAM FORMAT If this element of the statement contains only an expression, it is evaluated by MACREL and stored in memory as data. 2.1.3 Comments You may add notes or comments to a statement by separating these from the remainder of the line with a forward slash (/). Such comments do not affect assembly processing or program execution but are useful in the program listing for later analysis or debugging. The assembler ignores everything from the slash to the next carriage return. It is also possible to have only a carriage return on a line. This causes a blank line in the assembly listing. No error message is given. 2.2 FORMAT EFFECTORS You can use the characters described below to control the format of an assembly listing. They allow a neat readable listing to be produced by providing a means of spacing through the program. 2.2.1 Form Feed The form feed code causes the assembler to output blank lines in order to skip to a new page in the output listing; this is useful in creating a page-by-page listing. The form feed is generated by typing a CTRL/L on the console terminal. 2.2.2 Tabulations Tabulations are used in the body of a source program to separate fields into columns. For example, a line written: GO,TAD TOTAL/MAIN LOOP is much easier to read if tabs are inserted to form: GO, TAD TOTAL /MAIN LOOP 2.2.3 Statement Terminators You can use the RETURN key to terminate a statement and to cause a carriage return/line feed combination to occur in the listing. The semicolon (;) may also be used as a statement terminator and is 2-2 MACREL SOURCE PROGRAM FORMAT considered identical to a carriage return except that it will not terminate a comment. For example in the following line: TAD A /THIS IS A COMMENT; TAD B the entire expression between the slash and the carriage return is considered a comment. Thus, in this case the assembler ignores the TAD B. 2-3 CHAPTER 3 THE PDP-8 MACHINE INSTRUCTION SET This chapter describes the three general classes of computer instructions and the way in which they are used in programs. The first class of instruction operates upon data that is stored in some memory location and must tell the computer where the data is located in memory so that the computer can find it. This type of instruction is said to reference a location in memory; therefore, it is called a memory reference instruction (MRI). When speaking of memory locations, it is very important that you make a clear distinction between the address of a location and the contents of that location. A memory reference instruction refers to a location via a 12-bit address. The instruction causes the computer to act on the contents of that location. However, although the address of a specific location in memory remains the same, the contents of the location are subject to change. In summary, a memory reference instruction uses a 12-bit address value to refer to a memory location, and it operates on the 12-bit binary number stored in the referenced memory location. The second class of instruction consists of the operate microinstructions, which perform a variety of program operations without any need for reference to a memory location. Instructions of this type are used to perform the following operations: clear the accumulator, test for negative accumulator, halt program execution, etc.. Many of these operate microinstructions can be combined (microprogrammed) to increase the operating efficiency of the computer. The third class of instruction consists of the input/output transfer (IOT) instructions. These instructions perform or aid in the transfer of information between a peripheral device and the computer memory. 3.1 MEMORY REFERENCE INSTRUCTIONS Memory reference instructions take the form shown in Figure 3-1. Bits 0 through 2 contain the operation code of the instruction to be performed. Bit 3 tells the computer if the addressing mode is direct or indirect. Bit 4 tells the computer if the instruction is referencing the current page or page zero. This leaves bits 5 through 11 (seven bits) to specify an address. In these seven bits, 200 octal (128 decimal) locations can be specified; the page bit increases 3-1 THE PDP-8 MACHINE INSTRUCTION SET accessible locations to 400 octal or 256 decimal. A list of the memory reference instructions and their codes is given at the end of the chapter. 0 1 2 3 4 5 6 7 8 9 10 11 ------------------------------------------------- | OPERATION | | | | | CODE 7 | | | ADDRESS | | | | | | ----|---|---|---|---|---|---|---|---|---|---|---| ^ ^ INDIRECT ADDRESSING -| | MEMORY PAGE -------------| Figure 3-1 Memory Reference Instruction Bit Assignments In MACREL a memory reference instruction must be followed by a space(s) or tab(s), an optional I or Z designation, and any valid expression. 3.1.1 Addressing Modes The PDP-8 has two addressing modes, direct and indirect. Consider the following: TAD 40 This is a direct address statement, where 40 is interpreted as the location on page zero containing the quantity to be added to the accumulator. References to locations on the current page and page zero may be done directly. For compatibility with older paper-tape assemblers the symbol Z is also accepted as a way of indicating a page zero reference, as follows: TAD Z 40 This is an optional notation, not differing in effect from the previous example. Thus, if location 40 contains 0432, then 0432 is added to the accumulator. When the symbol I appears in a statement between a memory reference instruction and an operand, the operand is interpreted as the address (or location) containing the address of the operand to be used in the current statement. Now consider the following: TAD I 40 This is an indirect address statement, where the contents 40 is used as the address of the location containing the quantity to be added to the accumulator. Thus, if location 40 contains 0432, and location 432 contains 0456, then 456 is added to the accumulator. 3-2 THE PDP-8 MACHINE INSTRUCTION SET NOTE Because the letters I and Z indicate indirect addressing, and a page zero reference respectively, you cannot use them to name a variable. 3.2 MICROINSTRUCTIONS Microinstructions are divided into two groups: operate and Input/Output Transfer (IOT) microinstructions. Operate microinstructions are further subdivided into three groups: Group 1 Group 2, and Group 3. Instructions in these groups cannot be intermixed. 3.2.1 Operate Microinstructions Group 1 microinstructions perform clear, complement, rotate and increment operations, and are designated by the presence of a 0 in bit 3 of the machine instruction word, as shown in Figure 3-2. 0 1 2 3 4 5 6 7 8 9 10 11 ------------------------------------------------- | | | | | | | | | | | | 1 1 1 | 0 |CLA|CLL|CMA|CML| | |BSW|IAC| | | | | | | | | | | | ----|---|---|---|---|---|---|---|---|---|---|---| ^ ^ ^ ROTATE AC AND L RIGHT -------------------| | | ROTATE AC AND L LEFT ------------------------| | ROTATE 1 POSITION IF A 0, 2 POSITIONS IF A 1 ----| (BSW IF BITS 8, 9 ARE 0) LOGICAL SEQUENCE: 1 - CLA, CLL 2 - CMA, CML 3 - IAC 4 - RAR, RAL, RTR, RTL, BSW Figure 3-2 Group 1 Operate Microinstruction Bit Assignments Group 2 microinstructions check the contents of the accumulator and link and, based on the check, continue on to or skip the next instruction. Group 2 microinstructions are identified by the presence of a 1 in bit 3 and a 0 in bit 11 of the machine instruction word. See Figure 3-3. 3-3 THE PDP-8 MACHINE INSTRUCTION SET 0 1 2 3 4 5 6 7 8 9 10 11 ------------------------------------------------- | | | | | | | | | | | | 1 1 1 | 1 |CLA|SMA|SZA|SNL| |OSR|HLT| 0 | | | | | | | | | | | | ----|---|---|---|---|---|---|---|---|---|---|---| ^ REVERSE SKIP SENSING OF BITS 5, 6, 7 IF SET-| LOGICAL SEQUENCE: 1 (BIT 8 IS 0) - SMA OR SZA OR SNL (BIT 8 IS 1) - SPA AND SNA AND SZL 2 - CLA 3 - OSR, HLT Figure 3-3 Group 2 Operate Microinstruction Bit Assignments Group 3 microinstructions reference the multiplier quotient (MQ) register. They are differentiated from Group 2 instructions by the presence of a 1 in bits 3 and 11; the other bits are part of a hardware arithmetic option. Figure 3-4 shows these bit assignments. 0 1 2 3 4 5 6 7 8 9 10 11 ------------------------------------------------- | OPERATION | | | | | | | | | CODE 7 | |CLA|MQA| |MQL| | | | | | | | | | | | ----|---|---|---|---|---|---|---|---|---|---|---| ^ \_/ \_________/ ^ CONTAINS 1 TO | \_________________/ | SPECIFY GROUP 3 -----| ^ | KE8-E EXTENDED ARITHMETIC ELEMENT -------| | CONTAINS A 1 TO SPECIFY GROUP 3 ---------------------| Figure 3-4 Group 3 Operate Microinstruction Bit Assignments You cannot combine Group 1 and Group 2 microinstructions because bit 3 determines either one or the other. Within Group 2, there are two groups of skip instructions, the OR group and the AND group. OR Group AND Group ________ _________ SMA SPA SZA SNA SNL SZL The OR group is designated by a 0 in bit 8 and the AND group by a 1 in bit 8. You cannot combine OR and AND group instructions because bit 8 determines either one or the other. If you combine legal skip instructions, it is important to note the conditions under which a skip may occur. 3-4 THE PDP-8 MACHINE INSTRUCTION SET 1. OR Group-If you combine these skips in a statement, the inclusive OR of the conditions determines the skip. For example: SZA SNL The next statement is skipped if the accumulator contains 0000 or the link is a 1 or both. 2. AND Group-If you combine these skips in a statement, the logical AND of the conditions determines the skip. For example: SNA SZL The next statement is skipped only if the accumulator differs from 0000 and if the link is 0. NOTE If you specify an illegal combination of microinstructions, the assembler will simply perform an inclusive OR between them. For example, CLL SKP is interpreted as SPA because MACREL ORs 7100 (CLL) with 7410 (SKP) to produce 7510 (SPA). 3.2.2 Input/Output Transfer Microinstructions These microinstructions initiate operation of peripheral equipment and effect an information transfer between the central processor and the Input/Output device. (See Standard Instruction Set, Section 3.4.) 3.3 AUTOINDEXING Interpage references are often necessary for obtaining operands when processing large amounts of data. The PDP-8 computers have facilities to ease the addressing of this data. When you indirectly address one of the absolute locations from 10 to 17 (octal) the contents of the location is incremented before it is used as an address, and the incremented number is left in the location. This allows you to address consecutive memory locations using a minimum number of statements. It must be remembered that initially these locations (10 to 17 on page 0) must be set to one less than the first desired address. Because of their characteristics, these locations are called autoindex registers. No incrementation takes place when locations 10 to 17 are addressed directly. For example, if the instruction to be executed next is in location 300 and the data to be referenced is on 3-5 THE PDP-8 MACHINE INSTRUCTION SET the page starting at location 5000, you can use autoindex register 10 to address the data as follows: 0276 1377 TAD C4777 /=5000-1 0277 3010 DCA 10 /SET UP AUTO INDEX 0300 1410 TAD I10 /INCREMENT TO 5000 . . . /BEFORE USE AS AN . . . ADDRESS . . . 0377 4777 C4777,4777 When the instruction in location 300 is executed, the contents of location 10 will be incremented to 5000 and the contents of location 5000 added to the contents of the accumulator. When the instruction TAD I 10 is executed again, the contents of location 5001 will be added to the accumulator and so on. 3.4 STANDARD INSTRUCTION SET The following are the most commonly used elements of the PDP-8 instruction set and are found in the permanent symbol table within the PAL8 Assembler. For additional information on these instructions and for a description of the symbols used when programming other optional devices, see The Small Computer Handbook, or the PDP-8A Miniprocessor ___________________________ _____________________ User's Manual (available from the DIGITAL Software Distribution ______________ Center). ---------------------------------------------------------------------- | Mnemonic Code Operation Cycles | | | | Memory Reference Instructions | | | | AND 0000 Logical AND 2 | | TAD 1000 Two's complement add 2 | | ISZ 2000 Increment and skip if zero 2 | | DCA 3000 Deposit and clear AC 2 | | JMS 4000 Jump to subroutine 2 | | JMP 5000 Jump 1 | | IOT 6000 In/Out transfer - | | OPR 7000 Operate 1 | ---------------------------------------------------------------------- 3-6 THE PDP-8 MACHINE INSTRUCTION SET ---------------------------------------------------------------------- | Mnemonic Code Operation SEQUENCE | | | | Group 1 Operate Microinstructions (1 cycle) | | | | NOP 7000 No operation - | | IAC 7001 Increment AC 3 | | *BSW 7002 Byte swap 4 | | RAL 7004 Rotate AC and link left one 4 | | RTL 7006 Rotate AC and link left two 4 | | RAR 7010 Rotate AC and link right one 4 | | RTR 7012 Rotate AC and link right two 4 | | CML 7020 Complement the link 2 | | CMA 7040 Complement the AC 2 | | CLL 7100 Clear link 1 | | CLA 7200 Clear AC 1 | ---------------------------------------------------------------------- * PDP-8/A,E,F,M and VT78 only ---------------------------------------------------------------------- | Mnemonic Code Operation SEQUENCE | | | | Group 2 Operate Microinstructions (1 cycle) | | | | HLT 7402 Halts the computer 3 | | OSR 7404 Inclusive OR SR with AC 3 | | SKP 7410 Skip unconditionally 1 | | SNL 7420 Skip on non zero link 1 | | SZL 7430 Skip on zero link 1 | | SZA 7440 Skip on zero AC 1 | | SNA 7450 Skip on non zero AC 1 | | SMA 7500 Skip on minus AC 1 | | SPA 7510 Skip on positive AC (zero is 1 | | positive) | | | | *Group 3 Operate Microinstructions | | | | MQA 7501 Multiplier Quotient OR into AC 2 | | MQL 7421 Load Multiplier Quotient 2 | | SWP 7521 Swap AC and Multiplier Quotient 3 | | CLA 7601 Clear AC 1 | | NOP 7401 No operation - | | CAM 7621 Clear AC and MQ 3 | | SWP 7521 Swap AC and MQ 3 | | ACL 7701 Load MQ into AC 3 | | CLA SWP 7721 Load MQ into AC and clear MQ 3 | ---------------------------------------------------------------------- * If MQ is available in hardware. 3-7 THE PDP-8 MACHINE INSTRUCTION SET ---------------------------------------------------------------------- | Mnemonic Code Operation | | | | Combined Operate Microinstructions | | | | CIA 7041 Complement and increment AC | | STL 7120 Set link to 1 | | GLK 7204 Get link (put link in AC, bit 11) | | STA 7240 Set AC to -1 | | LAS 7604 Load AC with SR | | | | Internal IOT Microinstructions | | | | SKON 6000 Skip with interrupts on and turn | | them off | | ION 6001 Turn interrupt processor on | | IOF 6002 Turn interrupt processor off | | GTF 6004 Get flags | | RTF 6005 Restore flag, ION | | SGT 6006 Skip if "Greater Than" flag is set | | CAF 6007 Clear all flags | | | | Keyboard/Reader (1 cycle) | | | | KCF 6030 Clear keyboard flags | | KSF 6031 Skip on keyboard/reader flag | | KCC 6032 Clear keyboard/reader flag and | | AC; set reader run | | KRS 6034 Read keyboard/reader buffer | | (static) | | KIE 6035 Set/clear interrupt enable | | KRB 6036 Clear AC, read keyboard buffer | | (dynamic), clear keyboard flags | | | | Teleprinter/Punch (1 cycle) | | | | TFL 6040 Set teleprinter flag | | TSF 6041 Skip on teleprinter/punch flag | | TCF 6042 Clear teleprinter/punch flag | | TPC 6044 Load teleprinter/punch and print | | TSK 6045 Skip on keyboard or teleprinter flag | | TLS 6046 Load teleprinter/punch, print, | | and clear teleprinter/punch flag | ---------------------------------------------------------------------- 3-8 THE PDP-8 MACHINE INSTRUCTION SET ---------------------------------------------------------------------- | Mnemonic Code Operation | | | | High Speed Perforated Tape Reader | | | | RPE 6010 Set Reader/Punch interrupt enable | | RSF 6011 Skip if reader flag=1 | | RRB 6012 Read reader buffer and clear flag | | RFC 6014 Clear flag and buffer and fetch | | character | | | | High Speed Perforated Tape Punch | | | | PCE 6020 Clear Reader/Punch interrupt enable | | PSF 6021 Skip if punch flag=1 | | PCF 6022 Clear flag and buffer | | PPC 6024 Load buffer and punch character | | PLS 6026 Clear flag and buffer, load buffer | | and punch character | | | | Memory Extension | | | | *CDF 62nl Change to Data Field n (n=00 to 07) | | 62n5 Change to Data field n (n=10 to 17) | | 63nl Change to Data Field n (n=20 to 27) | | 63n5 Change to Data Field n (n=30 to 37) | | *CIF 62n2 Change to Instruction Field n | | (n=00 to 07) | | 62n6 Change to Instruction Field n | | (n=10 to 17) | | 63n2 Change to Instruction Field n | | (n=20 to 27) | | 63n6 Change to Instruction Field n | | (n=30 to 37) | | *CDI 62n3 Change to Data and Instruction Fields n | | (n=00 to 07) | | 62n7 Change to Data and Instruction Fields n | | (n=10 to 17) | | 63n3 Change to Data and Instruction Fields n | | (n=20 to 27) | | 63n7 Change to Data and Instruction Fields n | | (n=30 to 37) | | RDF 6214 Read Data Field | | RIF 6224 Read Instruction Field | | RIB 6234 Read Interrupt Buffer | | RMF 6244 Restore Memory Field | ---------------------------------------------------------------------- * See Figure 3-5 for mapping of extended memory bits into the instruction word. 3-9 THE PDP-8 MACHINE INSTRUCTION SET Field Number (0-37) = abcde bit 0 bit 11 CDF | 110 | 01a | cde | b01 | ------------------------- CIF | 110 | 01a | cde | b10 | ------------------------- CDF CIF | 110 | 01a | cde | b11 | ------------------------- Figure 3-5 Extended Memory Bit Mapping for CDF and CIF Instructions 3.5 CONSTANTS Occasionally you may find it convenient to load the accumulator with a constant produced by combinations of microinstructions, or to produce a combination of microinstructions by loading a constant. Some common examples follow: Constant Instruction ________ ___________ 0 CLA 1 CLA IAC 2 CLA CLL CML RTL 3* CLA CLL CML IAC RAL 4* CLA CLL IAC RTL 6* CLA CLL CML IAC RTL 100* CLA IAC BSW 2000 CLA CLL CML RTR 3777 CLA CLL CMA RAR 4000 CLA CLL CML RAR 5777 CLA CLL CMA RTR 6000* CLA CLL CML IAC RTR 7775 CLA CLL CMA RTL 7776 CLA CLL CMA RAL 7777 STA (=CLA CMA) * Do not use these instructions in software that runs on old (non-Omnibus) PDP-8 computers. 3-10 CHAPTER 4 EXPRESSIONS AND THEIR COMPONENTS This chapter discusses MACREL expressions and their symbolic components. Some parts of this chapter refer to symbols or expressions in relocatable code. You should, therefore, be familiar with Chapter 1 before proceeding with this chapter. Often a major element of a MACREL statement is an expression. An expression may be composed from one or more of the following components: o Symbols o Operators o Special Operators o Numbers Naturally, there are specific rules for the combination of the elements of statements and expressions. This chapter describes these elements and the rules for their valid combination. 4.1 MACREL CHARACTER SET 4.1.1 Alphanumeric Characters MACREL accepts as input all of the upper case alphabetic characters A through Z, the numeric characters 0 through 9, and the characters dollar sign ($) and period (.). Lower case alphabetic characters are permitted within a symbol and are treated as the corresponding upper case character. The first character of a symbol may not be a digit, and only the first 6 characters (not counting an initial $) of a symbol are significant. 4.1.2 Special Characters and Operators MACREL also accepts as input certain special characters and operators, which are listed alphabetically in Table 4-1 below. All of the special characters and operators are explained and their use illustrated in various sections of this manual. 4-1 EXPRESSIONS AND THEIR COMPONENTS Table 4-1 Special Characters and Operators ---------------------------------------------------------------------- | Name | Symbol | Name | Symbol | |--------------------------------------------------------------------| | Angle Brackets | < > | I | I | | Ampersand | & | Left Right Parenthesis | () | | Apostrophe | ' | Left/Right Square Brackets | [] | | Asterisk | * | Minus Sign | - | | Back Slash | \ | Percent Sign | % | | Colon | : | Period | . | | Comma | , | Plus Sign | + | | Dollar Sign | $ | Semicolon | ; | | Double Quotes | " | Up Arrow | ^ | | Exclamation Point | ! | Up Arrow Double Quote | ^" | | Equal Sign | = | Z | Z | | Forward Slash | / | | | ---------------------------------------------------------------------- Both the space and tab are legal input to MACREL also and their use is described in Chapter 2. 4.2 SYMBOLS A symbol in MACREL is a valid combination of letters, digits, and the characters period (.) and dollar sign ($). The symbol must begin with either a letter, a period, or a dollar sign. If it begins with a dollar sign the second character must not be a digit. A symbol may consist of any number of characters, but only the first six are significant. (If the first character is a dollar sign, a total of seven characters are significant.) The remaining characters are merely scanned for valid characters and ignored. Thus, the symbol NEW.VALUE is exactly equivalent to NEW.VA. If the last character in a symbol is a dollar sign, that symbol is considered to be a local symbol (see Section 4.2.4). A symbol is terminated by any character other than those mentioned. Thus, in the expression NEW+1, the plus sign (+) terminates the symbol NEW. Normally symbols in MACREL are unique. A macro name, for example, may not be used as an ordinary symbol. The one exception is local symbols, which need not be unique, in different local symbol blocks. The following are valid symbol names: DATA1 $POINTR .LONGER only .LONGE is significant .A.... NEW.VL .A.1.3 4-2 EXPRESSIONS AND THEIR COMPONENTS GET$ local symbol HYPOTENUSE only HYPOTE is significant The following are not valid symbol names: NU MER symbols cannot contain embedded spaces 1STNUM symbols cannot begin with a digit $3BUF a digit may not follow an initial dollar sign R:03 invalid character NOTE Though legal, you should avoid using symbols starting with period (.) or global symbols that begin with dollar sign ($), as they may be used by future system software released by DIGITAL EQUIPMENT CORP. Internally, symbol definitions are stored in the assembler's symbol table. Thus, with the exception of a few symbols defined by directives, symbols are evaluated during the assembly process and converted to 12-bit values. LINK completes this process of evaluation, especially in the case of relocatable symbols. 4.2.1 Permanent Symbols A number of symbols are reserved for use as machine-instruction mnemonics, directives, and special operators. These symbols are maintained in the permanent symbol table. If you attempt to redefine any of these through use of a comma (,), colon (:), or equals sign (=), an error message is produced. For example, the statement AND=7000 will produce an error message. For compatibility with PAL8, the old pseudo-op PAUSE is reserved as a permanent symbol, but is otherwise ignored. Assembler command string options allow you to add or delete the PDP-8/E symbols and the extended arithmetic instruction mnemonics. Another run-time option deletes certain redundant PAL8 pseudo-ops from the symbol table. The entire permanent symbol table, including those symbols altered by command string options, is listed in Appendix C. You can also alter the permanent symbol table by using the EXPUNGE, FIXMRI, and FIXTAB directives (see Section 5.9). 4-3 EXPRESSIONS AND THEIR COMPONENTS 4.2.2 Program-Defined Symbols You must define any symbol that is not a permanent symbol by entering the symbol name as the first item (excluding any spaces or tabs) on a line, followed immediately by a comma (,), colon (:), or equals sign (=). If you refer to a symbol that is not defined in this way, and is not declared as .EXTERNAL, an undefined symbol error message is printed. For example, the code DCA ALPHA+5 causes an error message if ALPHA is not defined. A symbol defined with a comma or a colon is a label and a symbol defined by the equal sign is a directly assigned symbol. Both labels and directly assigned symbols are discussed below. In addition to these familiar ways of defining symbols, there are three other special ways of defining symbols. The first is by a program section name. The name of a program section is defined when you use it following some form of program section directive. For example: .RSECT GVALUE or .SECT DATA1, D define sections with names of GVALUE and DATA1 respectively. You can use these symbols in expressions, but they cannot be redefined. Two other ways of defining symbols relate to macros. A macro name is a symbol that stands for a sequence of code, and use of the name causes that sequence of code to be inserted into the program. Thus, a macro name is an entirely different entity from an ordinary symbol. However, the use of symbols as dummy arguments in a macro definition does not define them. Both of these special cases are discussed in detail in Chapter 6. 4.2.3 Labels A label is a program-defined symbol terminated by a comma or optionally, by a colon (for local symbol blocks). The comma or colon must immediately follow the symbol name. The label must be the first entry on a line (excluding spaces and tabs, and except for another label) and generally is placed at the left margin. A label is used to identify an address in memory. It is assigned the value of the current location counter. The following two lines of code: *400 STRT, TAD 20 are equivalent to: 4-4 EXPRESSIONS AND THEIR COMPONENTS *400 STRT =. TAD 20 Both examples create an entry in the symbol table with the name of STRT and a value of 400 relative to the beginning of the current program section. Further, they both result in a line of code with a relative location of 400 and value of 1020. (See Sections 4.4 and 4.3.) Since a label is a symbol and has as its value an address, it is also called a symbolic address. In programming it is important to distinguish the address from the contents of that address. Although for expediency you might write a line of code and a comment in the form: TAD BUFSZE /ADD BUFSZE, THE LENGTH /OF THE BUFFER. remember that you are not actually adding BUFSZE (since that is an address) but rather the contents of BUFSZE. This distinction is especially important in expressions involving indirect addressing, literals, and computed addresses. You cannot use a label to redefine a symbol; you must use a direct assignment statement instead. In the following code: *600 INIT, TAD B . . . INIT, NOP the second use of INIT will result in a redefined symbol error message. The same error message results if you attempt to use a label to redefine a symbol already defined through a direct assignment statement. More than one label, however, may have the same value. Thus, the code: *300 NAME1, NAME2, NAME3, 0 is perfectly legal, and results in NAME1, NAME2, and NAME3 all having a value of 300. The following line: NAME1, NAME2, NAME3, 0 is also legal, and also results in the three labels having a value of 300. 4-5 EXPRESSIONS AND THEIR COMPONENTS 4.2.4 Local Symbols The local symbol feature of MACREL allows you to use a convenient symbol name in one segment of a program, and then, without conflict, use the same symbol name in another segment. You designate a local symbol by using a dollar sign ($) as the last character. Thus, DATA$ is a local symbol. Local symbols are defined only within a local symbol block. A local symbol block extends from one label defined with a comma to the next label defined with a comma, or as far as the next program section directive, or PAGE directive, or as far as the end of the program, whichever comes first. Any labels inside the local symbol block must be defined using a colon (:) rather than a comma. A colon is equivalent to a comma, except that it does not cause termination of the local symbol block. The following is an example of a local symbol block (the code is hypothetical): . . . INR, DCA NEW TAD COUNT$ CIA LOOP$: TAD OFFSET ISZ BCNT$ JMP LOOP$ JMP : NEXT /DATA BCNT$: 0 COUNT$: 0 NEXT, 0 Notice that the local symbol block starts with the first use of a label with a comma (INR,) and terminates with the next use of a label with a comma (NEXT,). All labels inside the local symbol block must be defined with a colon. If you refer to a local symbol outside its block and fail to define it as a local symbol in a new local symbol block, the assembler prints an undefined-symbol error message. Local symbols do not appear in the symbol table but can be included in the cross-reference listing. In effect, they are invisible to the program outside their own local symbol block. You can also define local symbols with a direct assignment statement. The equals sign of the direct assignment statement does not terminate the local symbol block; only a label with a comma or a new .SECT Directive or the end of the program delimit the local symbol block. 4-6 EXPRESSIONS AND THEIR COMPONENTS A local symbol may also consist of one to four decimal digits followed by a dollar sign. For example, 3$ or 1234$, are both local symbols. The value of the digits must be less than 4096 (decimal) and may include leading zeros which are not significant. The value may be an expression enclosed in angle brackets. Thus, if A=3 then $ represents the symbol 6$. 4.2.5 Backslash (\) Special Operator You can insert numeric characters that represent the value of an expression into a symbol name by using the backslash (\) special operator. If MACREL encounters a backslash within a symbol name, it evaluates the term to the right of the backslash and inserts its value into the symbol name. For example: DATA\NUMB If the value of the symbol NUMB is 2, this construction generates a symbol DATA2 that is exactly identical to a symbol DATA2 written in the program source. Moreover it can be referenced as DATA2 by other segments of programs. Similarly, if NUMB has a value of 12, the symbol will be DATAl2. The following code: AP=0 N\AP, AP+"0 AP=AP+1 N\AP, AP+"0 AP=AP+1 N\AP, AP+"0 produces three labels with the following contents: N0, which contains ASCII 0; N1, which contains ASCII 1; and N2, which contains ASCII 2. In evaluating symbols with a backslash, the assembler uses the current radix. If the radix is changed to 2, as in the following example: N=7 .RADIX 2 TAD B\N . . . B1, 0 B10, 0 B11, 0 B100, 0 B101, 0 4-7 EXPRESSIONS AND THEIR COMPONENTS B110, 0 B111, 0 the assembler will evaluate the symbol N in TAD B\N as a binary value (.RADIX 2), and the instruction causes the program to load the current contents of Blll. In evaluating the number following the backslash, leading zeros are ignored. Thus, N\0001 is evaluated as N1. Also, if the number to the right of the backslash contains more than six significant digits, only the least significant (rightmost) six are used. This situation might occur, for example, if the current radix were 2 (binary). You may use the backslash construction anywhere in a program and should find it particularly valuable in creating symbols within macros. Notice that all evaluation of the backslash construction occurs at assembly time. In the example shown above, the value of N must be absolute. The backslash must be within the symbol and must be followed by a term. An expression can be used after the backslash if it is enclosed in angle brackets. Thus, A\B+C is not a legal symbol whereas, A\ is. The expression B+C could also be assigned a name by a direct assignment. Thus, N=B+C A\N produces a legal symbol. The backslash may be embedded in a symbol. Thus if C=3 then the following code AB\D represents the symbol AB5D. The backslash may be nested without limit. For example, A\B\C is identical to: A\. 4-8 EXPRESSIONS AND THEIR COMPONENTS 4.2.6 Symbols and Relocation One function that MACREL and LINK perform (as a unit) is the reduction of symbols to 12-bit (or in the case of addresses, 17-bit) numeric values. Although the function of the assembler is to reduce symbols to numerical values, at the end of the assembly operation many symbols are not yet evaluated. In fact, the assembler cannot evaluate symbols that are to be relocated, because the amount by which they will be relocated is determined by the loading address of the beginning of the program section. This address cannot be known until LINK runs. For this reason, the assembler stores symbols as an absolute part and a relocatable part. The complete value of the symbol is not known at assembly time. MACREL passes any expression that is more complicated than this to LINK for resolution. For example, a symbol that requires two relocatable parts to evaluate is complex relocatable. Symbols can be classified into five groups: absolute (relocatable part is zero), relocatable (absolute plus one relocatable part), complex relocatable (neither of the above), CDF/CIF Relocatable and .FSECT Relocatable. Up to now, the examples in this chapter have assumed that the program is one absolute section, and the symbols are all absolute. Any label, however, that is defined in a relocatable section will be simply relocatable. If the example used in Section 4.2.3 appeared in a relocatable section named RELOK, as: .RSECT RELOK *400 STRT, TAD 20 then the label STRT will have an absolute value of 400 and a relocatable part of RELOK. STRT will appear in the symbol table as 00400+RELOK. (Note that the assembler directive RELOC cannot be used as a program section name.) In practice, you will adjust to this difference quickly and there will be little change in the way that you write code. 4.3 DIRECT ASSIGNMENT STATEMENT A direct assignment statement assigns a value to a symbol. The statement has two forms. The first form is: Symbol=Expression There must not be any space between the symbol and the equal sign. The direct assignment statement defines the symbol as having the value of the expression on the right. For example, DATA=7 causes DATA to be assigned a value of 7. Notice that this is different from a label, which defines the symbol as having the value of the current address. 4-9 EXPRESSIONS AND THEIR COMPONENTS The second form of the direct assignment is: Global Symbol==Expression Here, the double equals sign must immediately follow the symbol, and there must be no space between the two equal signs. This form of the direct assignment statement is the same as that of the single equal sign, but in addition it defines the symbol as being a global symbol. Thus, BUFSZE==100 is exactly the same as: .GLOBAL BUFSZE BUFSZE=100 Use of the .GLOBAL directive is discussed in Chapter 7. When used in any program section, the expression to the right of a direct assignment statement can be any legal expression that is either simply relocatable or absolute. Thus, XVALUE=2^-2 is a perfectly legal statement provided that BCNT is defined in the current source module and is absolute. One forward reference to an undefined symbol is allowed, but more than one is illegal. For example, A=B . . . B=3 is a legal sequence of code, because although B is unknown when the assembler reaches A=B, it is known when the assembler reaches B=3. This is one forward reference. However, A=B . . . B=C . . . C=3 is not a legal sequence of code because there are two forward references: A cannot be known until B is known, and B cannot be known until C is known. This structure may cause your program to assemble incorrectly. 4-10 EXPRESSIONS AND THEIR COMPONENTS You can use a direct assignment statement to redefine a previously defined symbol, but not to redefine a macro name, a directive, a machine-instruction mnemonic, or any other permanent symbol. Use of a direct assignment statement to redefine any of these results in an error message. In relocatable program sections, some care is required in the use of direct assignment statements. For example, XVALUE=2^-2 will produce a COMPLEX-RELOCATABLE ERROR message if BCNT is a label in a relocatable section, because the value of the expression containing BCNT cannot be determined until link time, though XVALUE needs a value at assembly time. A direct assignment statement assigns to the symbol to the left of the equals sign all the characteristics of the expression on the right: its absolute part and its relocatable part. An assembly error results if the expression to the right of the equal sign is not simply relocatable, and the symbol to the left of the equal sign is not a global or external symbol. 4.4 CURRENT LOCATION COUNTER The assembler maintains an internal register called the current location counter, which contains the address of the next available location. As each instruction or data word is assigned, the counter, is increased by one. To set this counter, use the asterisk (*) directive (see Section 5.5). To obtain the value of the current location counter, use the period (.) operator. You can use this permanent symbol in expressions in the same way as any other symbol. Because it is a symbol, you cannot use it next to another symbol (including an instruction mnemonic); a space or other character must intervene. For example, in the statement DCA.+3, the assembler would assume you are referring to a symbol DCA., and are trying to add 3 to it. The period always has the value of the current location counter. Like other permanent symbols, it cannot be redefined by a direct assignment statement. Because it has the value of the current location counter, the period itself is often called the current location counter. One of its common uses is demonstrated by a statement of the form: JMP .+3 This means, jump to the current location plus three. This statement implies that you will not at some time insert additional code between JMP .+3 and the location jumped to. If future insertion is a possibility, it is better to jump to a local symbol. 4-11 EXPRESSIONS AND THEIR COMPONENTS 4.5 LITERALS Literals are expressions, which are defined by parentheses (current page literals), or square brackets (page zero literals). They are evaluated and assigned locations by the assembler. 4.5.1 Current Page Literals Parentheses () define a current page literal. The assembler assigns them a location beginning at the highest location on the current page and works downward. For example, in an absolute section the following code, *400 TAD (-4) JMS I (DECODE) . . . results in two literals being generated, and if DECODE is a label at address 600, the assembly listing appears as, 1 0400 *400 2 00400 1377 TAD (-4) 3 00401 4776 JMS I (DECODE) ----- 00576 0600 00577 7774 The literals are listed after the five hyphens in a program listing. The TAD (-4) line results in generating a literal at address 577 (the top of the page) that contains a minus four (7774). The TAD instruction addresses this location. The JMS I (DECODE) line generates a pointer (stored at location 576) to DECODE (which has an address 0600). The JMS instruction uses location 576 as an indirect pointer to location 0600. In evaluating a literal, the assembler first evaluates the expression contained within the parentheses and then stores this value in the location that it allocates. The right parenthesis is optional, and, if omitted, the assembler evaluates the entire line as far as the carriage return or semicolon, and assigns that expression to the literal. The assembler then refers to the literal in terms of its address. Thus, the left parenthesis of a literal can be thought of as meaning "the address where the following expression is stored". For example, the TAD (-4) in the previous example means: "Perform a two's complement add of the contents of the address where a -4 is stored". Literals may also be nested. In evaluating nested literals, the assembler first evaluates the expression in the innermost parentheses and assigns it a storage location. It then evaluates the next 4-12 EXPRESSIONS AND THEIR COMPONENTS innermost parenthesis and assigns it a location. It proceeds in this manner until all the literals have been evaluated. Thus, the assembler will generate a number of storage words equal to the number of left parentheses. The following is an example of nested literals and the resulting code: 1 0200 *200 2 00200 0000 A1, 0 3 00201 1376 ENTRY, TAD (DCA (A1)) ----- 00376 3377 00377 0200 The top literal (address 377) contains the evaluation of the innermost parentheses, the address of A1. The next literal (address 376) contains the value of the code generated by DCA (A1). The TAD then addresses this value. When computing literals, the assembler keeps track of the values stored on the current page and does not store more than one literal with the same value. The assembler works on the assumption that the values stored in literal locations are unchangeable. For example, the DCA (7 line of code in the following example: CLA DCA (7) TAD (7) will overwrite the 7 stored in the literal location, so that the TAD (7) line will no longer load the AC with a 7, as was intended. The assembler will not create two literals with the same value. For example: 1 2 00200 1377 A, TAD (3+5) 3 00201 1376 B, TAB (4000) 4 00202 0377 C, AND (10) ----- 00376 4000 00377 0010 The assembler refers both literals (3+5) and (10) to location 377. This is called literal sharing. This literal sharing takes place for simple relocation literals only if both the absolute part and the relocatable part are the same. Literals that to the assembler are different cannot be shared, even if after evaluation by LINK they prove to have the same value. Literals cannot be complex relocatable and should not appear in .XSECTs or .DSECTs. In a named program section you should use page zero for literals rather than the current page. 4-13 EXPRESSIONS AND THEIR COMPONENTS The literal pool cannot contain more than 100(8) literals. MACREL stores literals in memory as follows: o In an unnamed absolute program section (.ASECT), MACREL assigns current page literals to locations in descending order beginning at the end of the page. It assigns page zero literals to locations in page zero in descending order beginning at location 177. o In a named absolute program section (.ASECT) or relocatable program section (.RSECT), MACREL assigns current page literals to locations in descending order beginning at the end of the page. It assigns page zero literals to locations in a special page zero (.ZSECT) literal program section in increasing order starting at the beginning of the program section. (MACREL creates names for these literal page zero program sections by using the name of the program section where a literal is first referenced prefixed with a dollar sign ($).) o In a floating program section (.FSECT), MACREL assigns current page literals to locations in ascending order beginning at the end of the .FSECT. It assigns page zero .FSECT literals in the same way that it assigns page zero .RSECT literals. If you put too many words of code in a memory page containing literals, the code will begin to overwrite the existing literals. The assembler will print an appropriate error message for each such occurrence. CAUTION One situation where the assembler overwrites literals without printing error messages is when you reset the current location counter to a previous page containing literals by using the Asterisk (*), PAGE or FIELD directives. The assembler does not retain the number of literals stored on the previously assembled page and it begins storing any new literals at the top of the page, thus overwriting any previous literals. To avoid this problem, you should code straight through, rather than return to a previous page. 4.5.2 Page Zero Literals Page zero literals are defined by square brackets ([]). The right square bracket is optional in the same way as the right parenthesis. Moreover, the assembler treats page zero literals in the same way as 4-14 EXPRESSIONS AND THEIR COMPONENTS current page literals, except that it stores them on page zero, thus making them available to all pages in the current field. The following two lines of code, TAD (4) TAD [4] each generates a literal, one on the current page and one on page zero. It may be to your advantage to use page zero literals (if there is room on page zero) when certain literals are used frequently on many pages. Like other literals, the assembler does not keep track of page zero literals when you leave the current program section, or the current field in an unnamed program section. Therefore, it is possible to overwrite page zero literals if you leave the current program section and then return to it. 4.6 NUMBER REPRESENTATION Numbers are handled in 12-bit, two's complement arithmetic. If the current radix is octal, -1 and 7777 both define the same number. A sequence of digits delimited by a nondigit character forms a number. A plus or minus sign may precede the number. Numbers are initially treated as octal, but you can change this with the .RADIX directive (see Section 5.2.1). You can also enter a single number in a radix other than the current radix by using the following temporary radix control operators. o Uparrow B (^B) o Uparrow D (^D) o Uparrow O (^O) o Period (.) These operators temporarily supersede or override the radix currently in effect. 4.6.1 Uparrow B (^B) -- Binary Representation NOTE Some terminals substitute the circumflex (^) for the uparrow (^). | Uparrow B (^B) defines a following sequence of digits as binary. For example, ^B101111001110 4-15 EXPRESSIONS AND THEIR COMPONENTS defines the number 5716 (octal). No space is allowed after the uparrow or after the B. 4.6.2 Uparrow D (^D) -- Decimal Representation Uparrow D (^D) defines a following sequence of digits as decimal. For example, TAD (-^D40 causes the assembler to generate a literal with the decimal value of -40 stored in it, and then to TAD the literal. Note that the notation TAD (^D-40 is illegal since the uparrow must be immediately followed by a sequence of digits. 4.6.3 Uparrow O (^O) -- Octal Representation Uparrow O (^O) defines a following sequence of digits as octal. This would be used if the current radix had been changed from its original setting of octal to some other radix. The following code line, ^O5555 causes the octal number 5555 to be loaded into memory regardless of the current radix in effect. The digits 8 and 9 are of course, illegal within the digit string. 4.6.4 Period (.) -- Decimal Representation A period at the end of a sequence of digits is another way of defining the digits as decimal. There must be no space between the digits and the period. For example, 913. defines the number 913 (decimal). The period must be the last character of the number - it cannot be embedded in a number. It is illegal to use the period if any other temporary radix control operator precedes the digit string. Thus, ^0345. is illegal. 4.7 ASCII DATA REPRESENTATION There are a number of ways to enter ASCII codes in a program. The simplest is to enter the octal number value of the code itself. For example, in 8-bit ASCII, 215 represents a carriage return. (See Appendix E for a complete chart of ASCII codes.) 4-16 EXPRESSIONS AND THEIR COMPONENTS Another way is to use the TEXT directive discussed in Section 5.3.2. For example, TEXT "ERR: IMPROPER SYNTAX" causes the assembler to generate and to store the ASCII characters for this error message. The following ASCII conversion operators allow you three additional ways of specifying ASCII characters: o Double quote (") o Single quote (') o Uparrow double quote (^") 4.7.1 Double Quote (") -- ASCII Representation The double quote operator causes the character that follows it to be interpreted as an ASCII character and converts it to a 12-bit expression value. The .ENABLE directive's text options determine whether the character is converted to a 7-bit or 8-bit value (see Section 5.11.1). Only one character may follow the double quote. For example, a "A will generate a code of 301. You should use this form of ASCII representation only for printing characters. For control characters, use the uparrow double quote (^") construction described in Section 4.7.3. You can enter other nonprinting characters as their numeric values. The following characters are not allowed and will result in an error message: o Carriage Return -- indicates end of line o Line Feed -- also indicates end of line o Form Feed o Control Z -- indicates end of file o Null 4.7.2 Single Quote (') -- ASCII Pair The single quote operator causes the next two characters to be interpreted as 6-bit ASCII codes, and combined into one 12-bit value. Thus: 'AZ causes the assembler to generate the 6-bit code for A (01) and combine it with the 6-bit code for Z (32), giving 0132 (octal). The 6-bit code for a character is the low order 6 bits of the character's ASCII code. 4-17 EXPRESSIONS AND THEIR COMPONENTS 4.7.3 Uparrow Double Quote (^") -- Control Character Representation The use of the double quote operator to convert control characters presents some problems. First since these are nonprinting characters, it is impossible from looking at the program listing to determine what the character is. Second, it is impossible to enter several of the control characters into the file, since they have special meaning to OS/8 programs. For example, CTRL/C means return to the Keyboard Monitor, and its use in a file causes an exit from the file and a return to the monitor. The uparrow double quote operator generates ASCII codes for control characters. The .ENABLE directive's text options determine whether the character is converted to a 7-bit or 8-bit value (see Section 5.11.1). For example, ^"C This construction generates the ASCII code for a control C (203). 4.8 MACREL ARITHMETIC OPERATORS An arithmetic operator is a symbol or code that indicates that an action or operation is to be performed on a term or terms in an arithmetic expression. There are seven arithmetic operators in MACREL: + Addition - Subtraction or negation ^ Multiplication % Division ! Boolean Inclusive OR & Boolean AND Space or Tab Inclusive OR (except in MRI instructions) The operators + and - are used as unary operators to act on a single term, and are also used as binary operators to act on more than one term. The remaining five characters in the above list are binary operators. Binary operators perform operations involving two numbers or symbols. They combine an expression to the left of the operator with a term to the right of the operator. All operations are performed in 12-bit, two's complement arithmetic, which is explained in detail in Chapter 1 of Introduction To Programming. ___________________________ 4.8.1 Plus Sign (+) -- Addition The term A+B causes B to be added to A in two's complement arithmetic. No check is made for arithmetic overflow; thus (in octal), 4-18 EXPRESSIONS AND THEIR COMPONENTS 7755+33 will yield a result of 10. The plus sign may be used freely before a term. Its use as a unary operator does not change the sign of the term. For instance "+-1" is valid and evaluates as 7777 (octal). 4.8.2 Minus Sign (-) -- Subtraction The term A-B causes B to be subtracted from A in two's complement arithmetic. Again, no check is made for arithmetic overflow. As a unary operator, the minus sign negates any term that follows it. Both the plus and minus signs act as unary operators before any binary operations are done, and both may be used in any combination before a term. For example, --+-4 is valid and evaluates as -4 or 7774 octal. If an expression precedes a sequence of plus and minus signs, the first sign is a binary operator and the remaining signs are unary operators. Thus A---B is the same as A-B. NOTE Extra spaces before unary operator are interpreted as inclusive OR's and are not permitted. Thus, A -B means A!-B and is not the same as A-B. 4.8.3 Uparrow (^) -- Multiplication The expression A^B causes A to be multiplied by B through repeated addition. All 12 bits are treated as magnitude and no check is made for overflow. For example (in octal), 1234^10 produces a result of 2340. Also, -1^2 produces a result of 7776. 4.8.4 Percent Sign (%) -- Division The term A%B causes A to be divided by B through repeated subtraction. The number of full subtractions that were able to be performed is the quotient. The remainder is not saved. All 12 bits of each number are 4-19 EXPRESSIONS AND THEIR COMPONENTS considered as magnitude. Division by zero causes an error message, the result arbitrarily to be considered zero. For example: 723%10 yields 72. Also (in decimal), .RADIX 10 -10%10 gives 408 (603 octal) because -10 would be treated as decimal 4086 (7766 octal). 4.8.5 Ampersand (&) -- Boolean AND The term A&B causes the assembler to perform a bit-by-bit Boolean AND between A and B. For example (in octal), 7436&1743 produces a result of 1402. 4.8.6 Exclamation Point (!) -- Inclusive OR (or Shift) The term A!B causes the assembler to perform a bit-by-bit Boolean inclusive OR between A and B. For example (in octal), 1234!4444 produces 5674. If you use the SHIFT option of the .ENABLE directive it changes the meaning of its exclamation point operator. The expression A!B now means, shift A six bits to the left and inclusive OR the result with B. The left six bits of A are lost. For example (in octal), 7711!2077 produces a result of (1100 OR 2077), or 3177. This option is useful for manipulating 6-bit values. For example, If A=21 and B=47, then A!B=2147 (SHIFT enabled). 4.8.7 Space ( ) and Tab -- Inclusive OR The space (or optionally, tab) provides another way of indicating an inclusive OR between two symbols or numbers. The primary use of this form of the inclusive OR is in specifying microprogrammed instructions 4-20 EXPRESSIONS AND THEIR COMPONENTS though you may, in fact, use it for any valid OR expression. The following is an example of its use for microprogrammed instructions: CLA CLL IAC Here, the spaces cause the assembler to perform an inclusive OR between the permanent symbols CLA (7200), CLL (7100), and IAC (7001). The result is 7301 (all numbers in octal). The assembler thus produces a code word of 7301, which when executed clears the accumulator, clears the link, and increments the accumulator. In other words, the instruction clears the link and sets the accumulator to 0001. It is your responsibility to ensure that the instruction codes that you OR together are compatible. For example, MACREL will OR the codes SNA(7450),CLA(7200) and CLL(7100) to produce 7750, which is SPA SNA CLA and not the intended instruction. You must also be careful when embedding spaces near other operators. For example in the code TAD (3+6 a space inadvertently placed before the plus sign yields a result of octal 7 instead of the intended octal 11. NOTE Since space and tab are operators, you cannot use them as format effectors within a term to improve readability. The current programming convention is that you use the exclamation point construction of the inclusive OR for actual logical operations, and the space construction for loading the various components of a word of code. If the SHIFT option of the .ENABLE directive is not in force (the default condition) space and ! are normally equivalent with one exception: You must use the exclamation point (!) form of the OR operator if a left angle bracket (<) immediately follows it. This prevents an ambiguous condition with certain conditional assembly directives. 4.9 SPECIAL OPERATORS In addition to unary and binary operators, there are a number of special operators. Special operators are permanent symbols that return values. They may appear anywhere in an expression. Other special operators that pertain to macros are discussed in Chapter 6. 4-21 EXPRESSIONS AND THEIR COMPONENTS 4.9.1 Memory Reference Instructions The assembler processes the memory reference instruction mnemonics AND, TAD, ISZ, DCA, JMP, and JMS differently from the other machine instructions. The assembler treats an expression that follows other machine-instructions mnemonics as a value to be ORed with the value of the particular instruction. It treats the expression that follows a memory reference instruction mnemonic as an address. It then performs the necessary computations for the address. Specifically if the assembler recognizes a symbol as being a memory reference instruction that is followed by an expression (N), the assembler evaluates the expression N and does the following (all numbers in octal): 1. If N is absolute and addresses page 0, the assembler OR's the value of the memory reference instruction (MRI) with N. For example, TAD 10 will produce 1010. (TAD has a value of 1000.) The result is absolute. If N is relative to a .ZSECT in the same source module (or includes a Z component) then N is added to the MRI. The relocatable part of the result is then the same as the relocatable part of N. 2. If N addresses the current page (other than page 0), the assembler sets the current page bit and OR's the MRI with bits 5 through 11 of the absolute part of N. An instruction DCA P, where P has a value of 4013 on the current page, generates the code 3213. The 3 indicates a DCA instruction, the 2 shows that the current page bit is set, and the 13 is the address on the current page. If the current program section is an .FSECT, .XSECT, or .ZSECT, the result is .FSECT relocatable (see 7.1.7). Otherwise the result is absolute. 3. If N addresses some other page than the current page in the same program section, or page zero, the assembler generates an on-page reference to the address of N. Specifically, it treats MRI N as if it were MRI I (N) by setting the indirect bit and creating an on-page reference much like a literal. If the current program section is an .FSECT, .XSECT, or .ZSECT, the result is .FSECT relocatable (see 7.1.7). Otherwise, the result is absolute. If N already contains an I component, then an illegal reference is generated. NOTE In the last example, the assembler indicates that it has created an on-page reference (link), by including an apostrophe (') to the right of the code column in the listing. You might want to consider this linkage as an error and use MRI I (N), the literal construction; this implies that N is off-page, and does not leave it as an assembler decision. If error print-out is 4-22 EXPRESSIONS AND THEIR COMPONENTS specified as a control option (see Chapter 8) the assembler will treat the linkage as an error, print an error message, and continue the assembly. In evaluating a memory reference instruction, the assembler looks for an expression following the instruction to represent the address. For example, TAD DATA+1^2 SYM will cause the assembler to add 1 to DATA, multiply by 2, OR the result with SYM, and take this result as the address of the TAD. To modify the result of the MR instruction in some way, rearrange the order of the expression, or use angle brackets. For example, +N will cause the assembler to first evaluate TAD B and then add the value of N to it. For example, TAD DCA A AND B means: TAD > In addition to the six memory reference instructions AND, TAD, ISZ, DCA, JMP and JMS, you can define your own memory reference instructions by using the FIXMRI directive (see Section 5.9). 4.9.2 I -- Indirect Addressing The special operator I indicates indirect addressing. It is always specified with a memory reference instruction in the form: MRI I n where: n is some expression I indicates that n is not the address of the operand, but is the location whose contents are the address of the operand. When n is indirectly addressed it must be on the current page or page 0. If it is not, the assembler prints an error message. The assembler sets the indirect address bit when creating an off page reference, but in this case the bit has already been set by the I in the instruction. 4-23 EXPRESSIONS AND THEIR COMPONENTS Although placing the I immediately after the memory reference instruction is the preferred format, the I may actually appear anywhere in an expression following the memory reference instruction. For example, DCA B+2 I will have the same effect as the following: DCA I B+2 I is a permanent symbol and cannot be used as a program symbol. 4.9.3 Z -- Page Zero Addressing In a memory reference instruction of the following format: MRI Z n where: n is an expression Z indicates page zero addressing. In effect, the Z is ignored because the value of n determines the actual address. However, if n is an absolute address other than on page zero the assembler will print an error message Z INCORRECTLY SPECIFIED. Thus, use of the Z makes it obvious that a page zero reference is intended, and should an error be made (for example, if you change the value of a variable and forgot that it was a page zero reference), MACREL generates an error message. If n is external, then this instruction acts as if n had been declared .ZTERNAL. 4.9.4 CIF and CDF Instructions The assembler treats the CIF and CDF instruction mnemonics as special operators when not used in absolute program sections. Both have the same format and MACREL processes them identically. The format is, CIF n or CDF n where: n is a term. The relocation type of n that results, depends on the relocation type of the arguments in the term. 4-24 EXPRESSIONS AND THEIR COMPONENTS Table 4-2 lists the relocation type and gives the assembly process for each type. Table 4-2 Processing of CDF/CIF Expressions ---------------------------------------------------------------------- | CDF/CIF | Operation | | Relocation Type | (values are octal) | |--------------------------|-----------------------------------------| | Absolute | OR the value of the symbol with CIF | | | (6202). For example, "CIF 30" will | | | produce 6232. | | | | | | OR the value of the symbol with CDF | | | (6201). For example, "CDF 30" will | | | produce 6231. | | | | | Relocatable | Instruct LINK to find the field of the | | | symbol N and map it into bits 5-9 of | | | CIF (6202). See Figure 3-5. | | | | | | Instruct LINK to find the field of the | | | symbol N and map it into bits 5-9 of | | | CDF (6201). See Figure 3-5. | ---------------------------------------------------------------------- CDF and CIF can be combined in a line of the form: CDF CIF N The order of CDF and CIF is not significant. The result is the same as in Table 4-2 except that the value 6203 (rather than 6201 or 6202) is used. If N is not absolute, then the result is complex relocatable (actually CDF-relocatable). This is because the result is of the form: constant + field of section. 4.9.5 EDF -- Evaluate Data Field The EDF (evaluate data field) special operator allows you to obtain the field of any symbol. The format is: EDF sym where: sym is a relocatable symbol. This instruction causes LINK to determine the field of the symbol and to map it into bits 5-9 of the current location value (see Figure 3-4). For example, if LPOINT is a symbol in a section that LINK loads into field 7, 4-25 EXPRESSIONS AND THEIR COMPONENTS EDF LPOINT will store 0070 (octal) in memory at the current location. You can use EDF in any expression. If the relocation type of the argument is either absolute or CDF/CIF relocatable, then EDF N has the same value as N. If relocation type of the argument is complex or .FSECT relocatable, the result is complex relocatable. You can evaluate the field that the current (relocatable) section has been loaded into by using the following construction: EDF . You can use this construction because the current location counter in a relocatable section is always relative to the current program section. If the current section is not known to be relocatable, EDF .FLD evaluates to the current field in bits 5-9. The .FLD special operator is discussed in Section 4.9.6. 4.9.6 .FLD The .FLD special operator returns a 12-bit expression value in which bits 5-9 specify the number of the current field. Figure 3-5 shows the mapping of these bits. If .FLD occurs in an absolute program section, the result is absolute. Otherwise, the result is CDF/CIF relocatable with a zero absolute part (see Section 4.9.4). 4.9.7 XEDF XEDF is a special operator that you can use when forming an RTS/8 Device Handler Function Control Word (see RTS/8 User's Manual). It ___________________ returns a 12-bit expression value that is the number of the memory field where a symbol resides. The form is: XEDF sym where: sym is a relocatable symbol The field value is mapped into bits 6-10 as shown in Figure 4-1. The result of this expression is complex relocatable. 4-26 EXPRESSIONS AND THEIR COMPONENTS Field Number (0-37) = abcde bit 0 bit 11 | 000 | 000 | cde | ba0 | ------------------------- Figure 4-1 Extended Memory Field Bit Layout for XEDF 4.9.8 .LEVEL The .LEVEL special operator returns a 12-bit expression value at LINK time that contains the overlay and level numbers of the current program section. You can use this operator in an expression or as an argument to a global symbol assignment statement. Figure 4-2 shows the bit assignments. The value of this special operator is complex relocatable at assembly time. |0------>| LEVEL | OVERLAY | |--------|-------|---------| 0 4 5 7 8 11 Figure 4-2 BIT Assignments for .LEVEL Special Operator Example: TAD LVL . . . LVL, .LEVEL At program execution time the code in this example causes the overlay and level values of the current program section to be added to the AC. 4.10 EXPRESSION EVALUATION AND SYNTAX Expressions consist of valid combinations of terms and operators. Terms may include numbers, ASCII codes, symbols, machine instruction mnemonics, the current location counter, literals, other expressions enclosed in angle brackets (<>), and special operators or some combination of the above. Note that expressions consist of terms separated by binary operators (the final separating operator is the space). Any unary operators are assumed to belong to the term to which they apply, and any special operators that take an entire expression (such as memory reference instructions) are shown as terms. The following expression illustrates this: 4-27 EXPRESSIONS AND THEIR COMPONENTS DATA-.+(ALPHA+1)%10.! TAD I DATA+6 This expression evaluates as: -<.>+<(ALPHA+1)>%<10.>!! That is, the terms in angle brackets are evaluated first, and then the binary operations performed from left to right. Note that the parentheses denote the address of a literal. 4.10.1 Operator Precedence and Order of Evaluation MACREL uses the following sequence to evaluate expressions: 1. Evaluate any special radix control and ASCII conversion operators. 2. Evaluate any unary operators. 3. Evaluate terms that require further processing. 4. Perform binary operations between terms, evaluating them from left to right. For example, the following expression, M-+TAD I M N contains four terms: MACREL evaluates each term separately before performing the binary operations. If, however, the initial set of angle brackets is removed, as follows: ISZ M-+ then the resulting expression contains only one term, because the memory reference instruction ISZ takes as its argument an expression that goes to the end of the line. In other words, the entire line is an argument to ISZ. In the expression, A-+B+--C+^B1101+89.+"A 4-28 EXPRESSIONS AND THEIR COMPONENTS the terms are as follows: <+B> <--C> <^B1101> <89.> <"A> Note the special operators in this example that indicate binary (^B), decimal (.), and ASCII (") are not unary operators, but are an integral part of the term they modify. The + before the and the -- before the , however, are unary operators. MACREL uses the three rules stated at the beginning of this section to evaluate each term in sequence, until it reduces each term to a 12-bit number. There is no precedence among the binary operators. You can use angle brackets freely to indicate order of operations. For example, A ^ will cause MACREL to compute the sum of B+C first, then multiply A by this result. In other words, the angle brackets alter the normal left to right evaluation of A^B+C. 4.11 USES OF EXPRESSIONS An expression may consist of only a single number or symbol, or it may be a complex construction. After evaluation, if the expression is the only element on the line (except for a label or comments), the 12-bit value is loaded into the current location, and the current location counter is incremented by one. Notice that the assembler does not distinguish machine instruction mnemonics (except for memory reference instructions, CIF, and CDF) from other symbols. A CLA, for example, is a permanent symbol that has a value of 7200. The assembler loads the next expression regardless of whether it is an instruction or a data item. In addition to this loading function, expressions may be used in direct assignment statements and in certain directives. In the following direct assignment statement, SYM=EXPR MACREL evaluates the expression EXPR and assigns this value to the symbol SYM. This operation is performed at assembly time; no code is generated. 4-29 EXPRESSIONS AND THEIR COMPONENTS Expressions used in directives are discussed under the appropriate directives. 4.12 EXPRESSIONS AND RELOCATION In an absolute program all expressions are absolute. That is, they evaluate to a 12-bit number. However, in a program with relocatable sections, expressions may be simply relocatable, complex relocatable CDF/CIF relocatable, or .FSECT relocatable (see Section 1.5.5). A number of MACREL directives take an expression value as an argument. For some of these directives, there are restrictions on the relocation types allowed for these expressions. Tables 4-3 and 4-4 show you the relocation types that result when using the arithmetic operators described in Section 4.8. Table 4-3 Relocation Types Resulting from Addition and Subtraction Operations -------------------------------------------------------------------- / | Right Operand | / |------------------------------------------------------| | Left | Absolute | Simple | Complex | CDF/CIF | .FSECT | | Operand | |Relocation|Relocation|Relocation|Relocation| |-------------|----------|----------|----------|----------|----------| | Absolute | Absolute | Simple | Complex | Complex | .FSECT | | | | | | | | | Simple | Simple | Complex | Complex | Complex | Complex | | Relocation | |(see note)| | | | | | | | | | | | Complex | Complex | Complex | Complex | Complex | Complex | | Relocation | | | | | | | | | | | | | | CDF/CIF | Complex | Complex | Complex | Complex | Complex | | Relocation | | | | | | | | | | | | | | .FSECT | .FSECT | Complex | Complex | Complex | Complex | | Relocation | | | | | | ---------------------------------------------------------------------- Note: If the relocatable part of each operand value is the same, the result is absolute. 4-30 EXPRESSIONS AND THEIR COMPONENTS Table 4-4 Relocation Types Resulting from Other Arithmetic Operations ------------------------------------------------------ / | Right Operand | / |----------------------------------| / | | Simple, Complex | | Left | Absolute | CDF/CIF, .FSECT | | Operand | | Relocation | |--------------------|--------------|-------------------| | Absolute | Absolute | Complex | |--------------------|--------------|-------------------| | Simple | | | | Complex, | | | | CDF/CIF, | Complex | Complex | | .FSECT | | | | Relocation | | | --------------------------------------------------------- 4-31 CHAPTER 5 MACREL DIRECTIVES Directives are direct instructions to the MACREL assembler to perform certain functions. Because directives are instructions to the assembler itself, in general they do not create code. In PAL8, directives are called pseudo-operators. Do not confuse operators, expressions and directives. Expressions consist of terms and operators. Any number of terms and operators may be present in an expression. The special operator EDF, for example, can appear anywhere in the expression, as in the following: TAD EDF DATA+OFS+5. Directives, on the other hand, may not be embedded in expressions; they must be the only entry on the line, with the exception of a label, a comment, or with some directives, a following expression. Although labels are permitted with directives, in most cases they do not make sense, as for example: "STRT, .RADIX 10". Note that a period (.) generally precedes the names of MACREL directives but not the older PAL8 pseudo-operators. The two forms are not interchangeable. The directives are grouped according to their function in the assembly or linking process. Each group, and the directives within the group, is discussed in a separate section in this chapter. 5.1 ASSEMBLY LISTING AND BINARY OUTPUT CONTROL DIRECTIVES The following seven directives control the assembly listing or the binary output: o .NOLIST o .LIST o .TITLE o .SBTTL o XLIST o EJECT o NOPUNCH and ENPUNCH 5-1 MACREL DIRECTIVES 5.1.1 Assembly Listing Control Directives 5.1.1.1 .LIST and .NOLIST - These directives enable (.LIST) and disable (.NOLIST) the printing of portions of an assembly listing. The form of the directive is: .LIST [option,...] .NOLIST where: option is one of the options shown in Table 5-1. If you do not specify any options, the directives enable or disable listing output. Table 5-1 .LIST and .NOLIST Options --------------------------------------------------------- | Option | Description | |---------|---------------------------------------------| | BE | Binary expansion lines | | CND | Unsatisfied conditionals | | LN | Count unlisted line numbers | | MC | Macro calls | | ME | Macro expansions (all lines) | | MEB | Macro expansions (lines that generate code) | | ST | Symbol table | | TOC | Table of contents | --------------------------------------------------------- You can dynamically alter listing conditions at assembly time by changing the value of the .LISTWD special variable (see Section 5.1.1.4). .LIST followed by any sequence of these options turns them on. .NOLIST followed by any sequence of the options turns them off. At the beginning of each assembly pass the following default listing options are in effect: BE - on CND - on MC - on ME - off MEB - off ST - on TOC - on 5-2 MACREL DIRECTIVES For example: .NOLIST CND, ME at the beginning of a program prevents any unsatisfied conditionals and macro expansions from being listed. If you use a .LIST or .NOLIST directive in the middle of a program, it will enable or disable the options specified from that point of the code on until MACREL encounters the next .LIST or .NOLIST directive. For example, if you specify .NOLIST ME for a certain section of a program, that section will have no macro expansions listed. You can use the directives without arguments to eliminate repetitious sections of code from a listing. For example, if you have a long series of text items that you do not wish to print, code them as follows: . . . JMP NEND .NOLIST TABLE, TEXT "CLA" TEXT "NOP" . . . TEXT "BSW" .LIST N1, CLA . . . None of the TEXT items will print on the listing. Note that if you turn on the listing of macro expansions (ME) all lines inside macro expansions will be listed regardless of the state of the MEB list option. If you turn on the listing of macro expansion binaries (MEB) only, then only lines inside macro expansions that generate binary will be listed. In the case of lines containing multiple statements (separated by semicolons), the line will be listed if and only if the first statement on the line satisfies all listing requirements. 5.1.1.2 .TITLE - The .TITLE directive defines a title for a program. The title prints as the top line of every page of the listing after it is used at the beginning of a program section. If it is also the 5-3 MACREL DIRECTIVES first line of a physical page, it appears as the heading of that page. No page ejection (execution of a form feed) takes place. The form of the directive is: .TITLE text where: text is a sequence of up to 40 ASCII characters including a single space that must follow the directive. Additional characters are ignored. Tabs should be voided in the text. An example of the directive is: .TITLE FLOATING-POINT ARITHMETIC PACKAGE 5.1.1.3 .SBTTL - The .SBTTL directive defines a subtitle to appear as the second line of the header for each page. The subtitle appears on the first page following each use of the directive. The form of the directive is: .SBTTL text where: text is a sequence of up to 40 ASCII characters including the single space that must follow the directive. Additional characters are ignored. You should avoid using tabs in the text (but they may precede it). An example of the directive is: .SBTTL MULTIPLY The following heading illustrates the use of both .TITLE and .SBTTL directives: FLOATING-POINT ARITHMETIC PACKAGE MULTIPLY 5.1.1.4 .LISTWD Special Variable - .LISTWD is an assembler-maintained variable that you can examine and modify to alter the options of the .LIST and .NOLIST directives at assembly time. The variable contains a 12-bit number the bits of which control these options (see Table 5-2). The following is an example of how you can use .LISTWD: 5-4 MACREL DIRECTIVES . . . TEMP = .LISTWD /SAVE CURRENT LISTING OPTIONS .LISTWD = NEW /SET NEW LISTING OPTIONS . . . .LISTWD = TEMP /RESTORE OLD LISTING OPTIONS Table 5-2 .LISTWD Bit Assignments ---------------------------------------------------------------- | Bit | Meaning when set to 1 | |----------|---------------------------------------------------| | 0 | Disable listing output | | 1 | Do not list unsatisfied conditional code | | 2 | Do not list binary extensions | | 3 | Do not list macro expansions | | 4 | Do not list macro expansions that generate binary | | 5 | Do not list macro calls | | 6 | Do not list macro definitions | ---------------------------------------------------------------- 5.1.2 Other PAL8 Directives Four PAL8 directives are maintained in MACREL, to keep the assemblers compatible. These are XLIST, EJECT, ENPUNCH, and NOPUNCH. 5.1.2.1 XLIST - The directive XLIST turns off the listing on its first use, and turns it back on on its second use. XLIST may also be used with an expression in the form: XLIST exp where: exp is an expression. The expression must be absolute. If the expression evaluates to 0, the listing will be turned off; otherwise it will be turned on. The XLIST directive itself does not appear in the listing. 5.1.2.2 EJECT - The EJECT directive causes the listing to jump to the next page. Additionally, if a string of characters follows the EJECT, the first 40 (decimal) characters will be placed in the top line (the .TITLE line) of the heading. 5-5 MACREL DIRECTIVES 5.1.2.3 NOPUNCH and ENPUNCH - The directive NOPUNCH causes the assembler to cease binary output, but continue assembling code. It is ignored except during the second assembly pass through the source module. ENPUNCH causes the assembler to resume binary output after NOPUNCH, and is ignored except during pass 2. Use these two directives when several programs share the same data on page 0. This avoids loading page 0 more than once. The same result is achieved with the PNCH option of the .ENABL and .DISABL directives. 5.2 RADIX CONTROL DIRECTIVES MACREL maintains a current radix according to which numbers are interpreted. Unless the radix is changed, MACREL assumes it to be octal. To change the radix use the .RADIX directive. 5.2.1 .RADIX The .RADIX directive alters the current radix. The form of the directive is: .RADIX exp where: exp is any valid expression that specifies the radix. The expression exp must be absolute, and must have a value between 2 and 10, inclusive. Any constants appearing in exp are evaluated in the decimal radix. For example: .RADIX 10 sets the current radix to 10 regardless of the previous radix. In addition to the current radix, you may temporarily set a radix for an individual number by using the temporary radix control operators described in Section 4.6. If you wish to determine the current radix simply write the characters 10 in your program. For example, to equate the symbol R with the current radix, write: R=10 Thus, if the current radix is decimal, the number 10 would be input as a decimal number and R would be assigned a value of decimal 10. 5-6 MACREL DIRECTIVES Remember that numbers are always stored internally in binary form. The effect of a .RADIX directive is to interpret a sequence of digits in the source module. 5.2.2 Other PAL8 Directives PAL8 provides two directives: DECIMAL and OCTAL, which in MACREL are replaced by the .RADIX directive. Both directives are still acceptable to MACREL, but for simplicity, it is recommended that you replace them with the .RADIX directive. This is accomplished as follows: PAL8 Directive MACREL Equivalent ______________ _________________ DECIMAL .RADIX 10 OCTAL .RADIX 8 Unlike .RADIX, OCTAL and DECIMAL do not take an expression. 5.3 DATA STORAGE DIRECTIVES MACREL provides four directives to control data storage. These are: o .REPT o .ENDR o ZBLOCK o TEXT .REPT and .ENDR are macro directives and are discussed in Section 6.6. ZBLOCK and TEXT are discussed in this section. Because options of the .ENABL and DISABL directives affect TEXT additional details on the TEXT directive are included in Section 5.11.1 and 5.11.2. 5.3.1 ZBLOCK ZBLOCK stores a specified value in a selected block of memory. The form of the directive is: ZBLOCK n,m where: n is an absolute expression value that specifies the number of words in the block. The value of this expression must be known on pass 1. 5-7 MACREL DIRECTIVES m is an expression value that specifies the value to store in each word. The expression cannot be complex relocatable. Examples: *300 ZBLOCK 7, HLT In this example, seven words, each containing HLT (7402) will be stored in locations 300 through 306, inclusive. In this example, if DATA is defined as being .EXTERNAL to the present module (.EXTERNAL DATA), the directive: ZBLOCK 5, DATA causes MACREL to generate five words of code, each of which contains a reference to DATA in the other module. LINK fills in the correct addresses at link time. CAUTION Avoid having assembly passes one and two generate different lengths of code. This results in an assembly error. For example, the following code: ZBLOCK N N=N+10 causes such an error, because N initially has a value of 0 which is changed by the "N=N+10" statement. However, N=1 ZBLOCK N N=N+10 assembles correctly because N gets reset to 1 on each pass. 5.3.2 TEXT There are two forms of the TEXT directive; a simple form and a complex form. 5.3.2.1 Simple Form of the TEXT Directive - The simple form of the TEXT directive is: 5-8 MACREL DIRECTIVES TEXT "text string" where: text string is a sequence of graphic characters including the space character. You must enclose the string within a pair of graphic characters such as double quotes (""). The directive is followed first by a printing character as a delimiter, then the text string, and finally the same delimiter. The double quote (") is recommended as a delimiter. Left or right angle brackets (<>) and nonprinting characters may not be used as the delimiter. If you have to use double quote (") as part of the text string, use the construction "". Thus, two double quotes in a row signify one double quote in the text string. No other delimiter has this characteristic. When you use the directive in this form, the assembler converts the characters to their 6-bit ASCII codes and packs them two characters to a word (i.e., six bits per character) and adds at least one character code of zero at the end. For example, if the text string contains an odd number of characters, the assembler adds a character code of zero to the binary code produced, and if the text string has an even number of characters, a full word of zeros is stored. Thus, *300 TEXT "ERR" causes the following binary code to be generated: 00300 0522 (E R) 00301 2200 (R zero-fill) Similarly, the TEXT message: *300 TEXT "USER""S NO." contains an even number of characters (since the two consecutive double quotes signify one double quote (") character) that results in the following code: 00300 2523 (U S) 00301 0522 (E R) 00302 4223 (" S) 00303 4016 (Space N) 00304 1756 (O .) 00305 0000 (Zero-fill word) Certain options of the .ENABLE directive (see Section 5.1.1) affect the way that MACREL processes text strings. The ASCII packing option causes TEXT to generate one 8-bit ASCII character per word. Additionally, if the 7BIT option is specified in addition to the ASCII 5-9 MACREL DIRECTIVES option, the TEXT directive generates one 7-bit ASCII code per word. The OS/8 packing option causes TEXT to generate OS/8 packing (three characters in two words). Also, the FILL option of the .DISABL directive inhibits TEXT from producing an extra all-zero word, if the number of characters is even. You should include only printing characters in text strings. This avoids editing problems and confusion when the listing is read. At any rate, the following characters are illegal within text strings and cause error messages: o Carriage Return o Line Feed o Form Feed o Control Z o Null But while these characters are not allowed in text strings, you can include their functions in text strings by using the format shown below. 5.3.2.2 Complex Form of the TEXT - The TEXT directive also allows you to enter special codes such as line feed and carriage return as part of the text string by using the ASCII value rather than the ASCII character. For example, the following statements, .ENABLE ASCII TEXT "ID" <215> <212> cause the assembler to use ASCII packing (one 8-bit code per word), and to generate five words, as follows: 0311 I 0304 D 0215 Carriage return 0212 Line feed 0000 Zero-fill word The general form of the TEXT directive is: TEXT item ... where: item is either a text string with delimiters or an expression contained within angle brackets. Spaces are optional between items. Any left angle bracket must ultimately be followed by its corresponding right angle bracket. Expressions within angle brackets must be absolute. Processing is as follows: 5-10 MACREL DIRECTIVES o The expression is evaluated. o MACREL takes the low order seven bits and constructs the proper code. o MACREL checks for .ENABLE directive options. o For the 8BIT option, MACREL sets the high order bit to 1. NOTE If the SIXBIT option of the .ENABLE directive (default) is in effect. MACREL cannot construct the proper code for nonprinting characters, which are undefined in 6-bit ASCII. 5.3.2.3 TEXT Options - In evaluating a sequence of text strings the assembler treats the sequence as if it were one continuous text string. For example, under the SIXBIT option of the .ENABLE directive, the statement, TEXT "A" "B" causes the A and B to be packed in the same word. When the FILL option is in effect, the assembler evaluates the entire sequence and then, at the end, adds a zero fill if one is not present. That is, the zero fill is not added to each item in the sequence. Figure 5-1 shows examples of how MACREL processes text under the various options of the TEXT directive. The example uses the source line: TEXT "VER" <212> "NO. " <260+VDIGIT> "." with the five option combinations shown. You might employ this statement to store data that your program would use to print the following message: VER NO. 3. In the example, VDIGIT contains the one-digit version number. C has a value (7015) that will generate the code for a carriage return. (This is to demonstrate the expression evaluation described above.) Note that the first three .ENABLE lines establish the default conditions (i.e., initial) MACREL conditions. The expression <212> prints a line feed. Notice also that the first example does not produce the desired result because the carriage return and line feed have been changed to the 6-bit codes for M and J respectively. 5-11 MACREL DIRECTIVES NOTE You can use the forward slash character (/) as a string delimiter for the first item of the text directive. This is the only place it is not treated as the beginning of a comment. VDIGIT=3 C=7015 .ENABLE 8BIT .ENABLE SIXBIT .ENABLE: FILL TEXT "VER" <212> "NO. " <260+VDIGIT> "." .ENABLE ASCII TEXT "VER" <212> "NO. " <260+VDIGIT> "." .ENABLE ASCII .ENABLE 7BIT TEXT "VER" <212> "NO. " <260+VDIGIT> "." .ENABLE OS8 TEXT "VER" <212> "NO. " <260+VDIGIT> "." .ENABLE OS8 .ENABLE 8BIT .DISABLE FILL TEXT "VER" <212> "NO. " <260+VDIGIT> "." MACREL-V2D THU 10-JAN-79 FILE # 1 1 / QTEXTK ---FIX 2 0003 VDIGIT=3 3 7015 C=7015 4 .ENABLE 8BIT 5 .ENABLE SIXBIT 6 .ENABLE FILL 7 00200 2605 TEXT "VER" <212> "NO. " <260+VDIGIT> "." 00201 2215 00202 1216 00203 1756 00204 4063 00205 5600 .FILL 8 .ENABLE ASCII 9 00206 0326 TEXT "VER" <212> "NO. " <260+VDIGIT> "." 00207 0305 00210 0322 00211 0215 00212 0212 00213 0316 00214 0317 00215 0256 00216 0240 00217 0263 Figure 5-1 Example of TEXT Option Processing 5-12 MACREL DIRECTIVES 00220 0256 00221 0000 10 .ENABLE ASCII 11 .ENABLE 7BIT 12 00222 0126 TEXT "VER" <212> "NO. " <260+VDIGIT> "." 00223 0105 00224 0122 00225 0015 00226 0012 00227 0116 00230 0117 00231 0056 00232 0040 00233 0063 00234 0056 00235 0000 13 .ENABLE OS8 14 00236 2526 TEXT "VER" <212> "NO. " <260+VDIGIT> "." 00237 1105 00240 2015 00241 7012 00242 1117 00243 0056 00244 0063 00245 0056 00246 0000 00247 0000 15 .ENABLE OS8 16 .ENABLE 8BIT 17 .DISABLE FILL 18 00250 6726 TEXT "VER" <212> "NO. " <260+VDIGIT> "." 00251 1305 00252 6215 00253 7212 00254 5317 00255 0256 00256 0263 00257 0256 Figure 5-1 (Cont.) Example of TEXT Option Processing 5.4 CODE LOCATION DIRECTIVES The following directives affect the location of code: o Asterisk (*) o PAGE o FIELD o RELOC 5-13 MACREL DIRECTIVES NOTE See also the program section directives described in Section 7.1. 5.4.1 Asterisk (*) The asterisk (*) directive sets the current location counter. The form of the directive is: *exp where: exp is an expression. In an absolute program section, the expression exp must be absolute and any symbols must have been previously defined within the current source module. The current location counter then is set to the value of the expression. For example (in octal), N=7 *N^200 CLA sets the current location counter to 1600, and therefore, the CLA (7200) will load at address 1600. In relocatable program section, the expression (exp) should be an absolute or a simple relocation expression. For example, .RSECT WPROC *400 sets the current location counter to 400 plus WPROC where WPROC is the address of the beginning of the program section. Thus, the assembler skips the first 400 words in the program section. CAUTION It is legal to set the current location counter to an unknown value (i.e., complex relocatable expression or external symbol). This can be dangerous and requires care in use (see Section 10.8). It is illegal to set the current location counter out of the current program section. 5-14 MACREL DIRECTIVES You can use the asterisk directive to skip over the next five words by using the construction: *.+5 Note that you can set the current location counter downward, but this may produce unsatisfactory results. For example: *.-20 is a valid statement provided the value in the current location counter is 20 or greater. But this statement causes the next 20 instructions to overwrite 20 previously assembled instructions. In addition, if this statement sets the current location counter to a previous page, any address literals on that page may be overwritten. You can also change the current location through the PAGE directive and through the FIELD directive (see Sections 5.4.2 and 5.4.3 respectively). In absolute programs, the current location counter (.) has as its value a 12-bit absolute number. In relocatable sections, it has an absolute part and a relocatable part. The relocatable part is relative to the beginning of the section. NOTE Because the asterisk is a directive, it cannot be embedded in an expression. To see the results of using the current location counter in relocatable expressions, study the following example: .RSECT LEW .+3 A, .-LEW .+A This source program segment generates the following code: 1. The line .+3 evaluates (at assembly time) as the current location (0 plus LEW) plus 3, or 3 plus LEW. (LEW is the loading address of the beginning of this section, to be determined by LINK). 2. The label A in the third line is defined as 1 plus LEW. (It is the first location after zero.) The current location counter also has this value, so subtracting LEW results in <1+LEW>-<0+LEW>, or absolute 1. 5-15 MACREL DIRECTIVES 3. The fourth line .+A evaluates as the current location (2+LEW) plus A (1+LEW), or 3+2^LEW. This is a complex relocatable expression and is passed on as global arithmetic for LINK. CAUTION Avoid having assembly pass one generate a different origin for code from assembly pass two. This will happen if the expression following the asterisk evaluates to different values on the different passes and causes an assembly error. 5.4.2 PAGE The PAGE directive followed by an argument is used to set the current location counter to the beginning of the specified page. If the PAGE directive is used without an argument, it causes the program counter to skip to the beginning of the next page. If the current location is already the beginning of a memory page, MACREL ignores the directive and does not skip to the next page. The form of the directive is: PAGE exp where: exp is an expression. The expression must be in the range 0 to 37, inclusive. When PAGE is used with an expression, the current location counter is set to the beginning of the page indicated. For example, if the radix is octal, the following two directives perform a similar function: PAGE E *200^E If E=4, either expression will set the current location counter to 1000 (octal). In a relocatable program section, the directive sets the absolute part of the location counter as just described. The relocatable part is relative to the beginning of the program section. The value of exp must be known on pass 1. The PAGE directive, when used without arguments, provides a convenient means of defining pages in the program; namely if code is inserted 5-16 MACREL DIRECTIVES into an earlier part of the program section, you need not alter all succeeding PAGE or Asterisk directives in that program section. CAUTION Avoid having assembly pass one generate a different origin for code from assembly pass two. This will happen if the expression following the asterisk evaluates to different values on the different passes and causes an assembly error. You will find the directive useful at the end of a page to make MACREL list the current page literals on the same physical listing page as the code. 5.4.3 FIELD The FIELD directive restricts the field into which the current program section is to be loaded. The FIELD directive acts somewhat differently in named and unnamed program sections. You should name all sections, to maintain a consistent approach to coding your programs. 5.4.3.1 FIELD Directive in Named Program Sections - The FIELD directive is specified in the form: FIELD exp where: exp is an expression. The processing depends on the relocation type of expression as described in Table 5-3. You can use the FIELD directive anywhere in the program section to which it applies. It does not change the current location counter. When the expression (exp) is absolute the field digits (0-37) appear in the field column of the assembly listing. When exp is a simple relocation expression, the directive instructs LINK to load the program section into the same field (whatever it might be) as exp. The field column of the listing has a question mark (?) to show that the value is unknown at assembly time. 5-17 MACREL DIRECTIVES Table 5-3 FIELD Directive Processing for Named Program Sections ---------------------------------------------------------------------- | Relocation | | | Type of Ex- | Processing | | pression | | |----------------|---------------------------------------------------| | Absolute | Restricts this program section to load in field | | | exp. (exp must have a value between 0 and 37, | | | inclusive; otherwise, an error message is | | | produced.) | |----------------|---------------------------------------------------| | Simple | Restricts this program section to load in the | | Relocatable | same field as the field of the relocatable part | | | of the expression. For example, FIELD SUBR, | | | where SUBR is a symbol in a relocatable section, | | | causes the current program section to be loaded | | | to the same field as the program section that | | | contains SUBR. | |----------------|---------------------------------------------------| | Complex- | Not allowed. | | Relocatable | | |----------------|---------------------------------------------------| | .CDF/CIF | Not allowed. | |----------------|---------------------------------------------------| | .FSECT | Not allowed. | ---------------------------------------------------------------------| 5.4.3.2 FIELD Directive in Unnamed Program Sections - To maintain PAL8 compatibility, MACREL treats unnamed program sections as absolute program sections (see Section 7.1.1). (This means that no program section directives have appeared prior to this in the program.) It processes the FIELD directive the same way that PAL8 does. The form of the directive is: FIELD exp where: exp is an expression. The expression must be absolute and in the range 0 to 37 inclusive. The directive creates a new unnamed program section, causes it to be loaded into field specified by exp and sets the current location counter to 200. Thus, any code that follows will be loaded into that field starting at location 200. Note that, since FIELD sets the current location counter to 200, any asterisk directives should follow FIELD rather than precede it. For example, if you want to set the current location counter to 400, the construction, 5-18 MACREL DIRECTIVES *400 FIELD 1 does not produce the desired result (the current location counter will be set to 200). A program with no program section directives and no FIELD directives loads into field 0. 5.4.4 RELOC The RELOC directive allows you to create a segment of code that executes in a set of memory locations that are different from the set of memory locations where LINK loads them. The form of the directive is: RELOC exp code . . . RELOC where: exp is an expression that specifies the beginning address of the area in memory where the code will be executed. All symbols in the expression must be defined previously in the source module. In an absolute program section, the expression must be absolute. In a relocatable section, the expression must be relative to the current program section. The expression may not be complex relocatable. Thus, in a relocatable section OVR, the directive: RELOC 4000 would be interpreted as RELOC 4000+OVR. code is one or more lines of code to be relocated. RELOC terminates the relocation sequence and restores MACREL to its ordinary mode of address calculation. It is your program's responsibility to dynamically move the code affected by this directive to the area of memory that begins with the address specified by the value of the expression (exp). The following example illustrates the use of the RELOC directive. 5-19 MACREL DIRECTIVES 0400 *400 2000 RELOC 2000 02000* 1377 CODE, TAD (CODE 02001* 3005 DCA 5 02177* 2000 PAGE 0600 RELOC The location marked CODE is loaded into location 400, but the assembler treats it as if it were loading into location 2000. The asterisks after the location values indicate that the virtual and the actual location counters differ for that line of code. RELOC on the last line sets the virtual location counter equal to the actual location counter and terminates the relocation section. CAUTION Be sure that all literals that apply to the RELOC segment reside within that segment. 5.5 CONDITIONAL ASSEMBLY DIRECTIVE This section describes the .IF conditional assembly directive and the logical conditions that complete the directive. The .IF directive replaces the conditional assembly pseudo-operators of the PAL8 assembler. The .IF conditional assembly directive allows you to create different binary object modules depending on the conditions of certain variables. For example, the code, .IF EQ LRGMEM causes the two lines TAD MEM and DCA MEMP to be assembled if the variable LRGMEM equals 0, and ignored if LRGMEM does not equal 0. The use of conditional code is particularly useful in writing general-purpose programs that are to be assembled in different ways depending on local parameters. CAUTION Do not write a program so that conditional code assembles differently on each pass. This may result in an assembly error. For example, in the previous code, if you define LRGMEM after this point in the program, the conditional might expand differently on 5-20 MACREL DIRECTIVES the second pass than on the first. In general, you must perform calculations that alter symbol definitions before the symbol is used as the argument of a conditional. The form of the directive is: .IF cond exp where: cond is one of the logical condition codes shown in Table 5-4. exp is an expression suitable to the condition. is any number of lines of source code enclosed within angle brackets (<>). The left angle bracket (<) must be on the same line as the directive itself. NOTES 1. When you specify one of the condition codes in Table 5-4, only the first two characters are significant, except for REL, which requires three characters. Two letters may be used, or (when appropriate) the full word. Additional letters or numbers after the significant ones are ignored. Thus, EQUAL may be used instead of EQ. For BL only, the letter B may be used alone. 2. The BL (blank) condition is normally used to test for the presence of one of the actual arguments of a macro to see if it is used in a given macro call (see Chapter 6). For example, the macro: .MACRO ADDNBS A, B, C, D CLA TAD A .IF NB B .IF NB C .IF NB D .ENDM 5-21 MACREL DIRECTIVES Table 5-4 Conditions for the .IF Conditional Assembly Directive (Grouped in Complementary Pairs) ---------------------------------------------------------------------- | Condition | | | | Code | Argument Type | Assemble If: | |-----------|---------------|----------------------------------------| | EQ | Expression | Expression=0 | | NE | Expression | Expression 0 | |-----------|---------------|----------------------------------------| | LT | Expression | Expression<0 | | GE | Expression | Expression 0 | |-----------|---------------|----------------------------------------| | GT | expression | Expression>0 | | LE | Expression | Expression 0 | |-----------|---------------|----------------------------------------| | DF | Symbol | Symbol is defined with a value | | NDF | Symbol | Symbol is not defined | |-----------|---------------|----------------------------------------| | BL | STRING | Argument is blank (null) (see text) | | NB | STRING | Argument is not blank (see text) | |-----------|---------------|----------------------------------------| | ABS | Expression | Expression is absolute | | REL | Expression | Expression is relocatable (includ- | | | | ing complex-relocatable) | |-----------|---------------|----------------------------------------| | IDN | STRING,STRING | Two strings are identical | | DIF | STRING,STRING | Two strings are different. | ---------------------------------------------------------------------- can be used to add between one and four values. The .IF directive with the condition NB (not blank) is used to see if a given argument is specified in a particular macro call. If the argument B, for example, was not used in a specific call, it will have a value of null inside the macro. Then the conditional code TAD B will not be assembled. 3. Note that BL and NB refer to the logical condition of being. They do not refer to the ASCII space character. 4. The ABS condition means that the expression has no relocatable part. For example, the statement: .IF ABS . causes the TAD A to assemble if it is used in an .ASECT and to be ignored if it is used in an .RSECT, because the current location counter always has the attributes of the current section. 5-22 MACREL DIRECTIVES 5. The IDN and DIF condition options allow you to perform a character by character comparison of two ASCII text strings. The left argument string cannot contain a comma (,). The right argument string cannot contain a left angle bracket (<). All other ASCII characters including space can be used. The following example shows a block of conditionally assembled code: MUSER=0 .IF NDF MUSER The condition used here is NDF (not defined). Because the symbol MUSER is, in fact, defined, the condition is false; therefore the code enclosed within angle brackets is not assembled. A symbol is defined by being used as a label, in a direct assignment statement, or as a program section or macro name. All permanent symbols are, of course, defined. For the purpose of this condition, an .EXTERNAL symbol is undefined, because it is not known at the time of assembly of this source module. 5.5.1 Nested Conditional Assembly Directives Conditional assembly directives may also be nested. A maximum of 4095 levels is allowed. The general form of nested conditional statements is: .IF cond.1 arg.l > The angle brackets are treated as pairs. If the condition in the first .IF is true, all of the code contained within the outside set of angle brackets, including a test of the second .IF directive, is assembled. If it is false all code within the outer set of angle brackets is ignored, regardless of the condition of the inner conditional. If the first conditional is true, the assembler then checks the condition of the second conditional statement. If the second conditional is false, the code contained within the inner set of angle brackets is ignored, but all other code is assembled. The code in the following example determines if the symbol NEWAVG has been defined, and if it is different from the symbol OLDAVG. .IF DF NEWAVG <.IF NE NEWAVG-OLDAVG> This statement first checks whether NEWAVG has been defined. If NEWAVG is defined, the code contained in the outer angle brackets is assembled. The code within the outer brackets is the second .IF 5-23 MACREL DIRECTIVES directive, IF NE NEWAVG-OLDAVG. If NEWAVG and OLDAVG are different, the condition is true and the code contained in the inner brackets is assembled. This inner code deposits the value of NEWAVG in the location formerly occupied by the value of OLDAVG. 5.5.2 Other PAL8 Conditional Assembly Directives For compatibility with PAL8, MACREL allows you to use the PAL8 conditional pseudo-operators. Each is equivalent to the .IF directive plus the suitable condition. The PAL8 directives behave in all ways like the equivalent .IF directives. The following are the PAL8 directives and their exact equivalents using the .IF directive: PAL8 Pseudo-Operator Equivalent MACREL .IF Directive ____________________ _______________________________ IFDEF .IF DF IFNDEF .IF NDF IFZERO .IF EQ IFNZRO .IF NE 5.6 ASSEMBLY CHAINING DIRECTIVES MACREL allows a source file to include another source file without specifying the file in the assembler's command string. This feature is particularly useful for referencing subroutine or macro libraries. There are two directives for this function. .INCLUDE and .CHAIN. 5.6.1 .INCLUDE The .INCLUDE directive includes another source file in the source code stream. After executing an .INCLUDE directive, MACREL takes the next statement to be assembled from the file specified in the directive, assembles all the statements in that file, then returns to the current file and continues with the assembly. The form of the directive is: .INCLUDE file specification where: file specification is the file specification of the source file that you wish to assemble. The file cannot reside on a non-file structured device. The 5-24 MACREL DIRECTIVES default device is DSK:. The default file name extension is .MA or if not found, null. Refer the OS/8 Handbook for a discussion of file ______________ specifications. For example, the statement, .INCLUDE DTA1:LIBRAR.MA includes the entire source file LIBRAR.MA located on DECtape 1. Similarly, .INCLUDE SUBR.PA includes all of the file SUBR.PA located on DSK:. .INCLUDE directives may be nested. One file may include another file which may, in turn, include a third file, and so on. Nesting results in control eventually passing back to the original source file. 5.6.2 .CHAIN The .CHAIN directive causes the assembler to close the present source code file and to continue assembling from the source file specified in the directive. Unlike the .INCLUDE directive, the assembler does not return to the old source file, during this assembly pass. The form of the directive is: .CHAIN file specification where: file specification is the file specification of the source file that you wish to assemble. The file cannot reside on a non-file structured device. The default device is DSK:. The default file name extension is .MA, or if not found, null. Refer to the OS/8 Handbook for a discussion of file ______________ specifications. Assuming that DSK is a file oriented device, the directive: .CHAIN NPART2.MA causes the assembler to disregard the remainder (if any) of the present source file and to start assembling from the file NPART2.MA on DSK. 5-25 MACREL DIRECTIVES One file may ".CHAIN" to another file which may, in turn, ".CHAIN" to a third file. In this case, assembly will terminate with the end of the last file. .CHAIN directives and .INCLUDE directives can be intermixed. 5.7 USER SERVICE ROUTINE (USR) COMMUNICATION DIRECTIVES The User Service Routine (USR), is an OS/8 system routine that opens and closes files, loads device handlers, chains programs and calls the Command Decoder. Several of the USR functions take device names or file names as arguments. To simplify the task of generating these arguments, MACREL incorporates the DEVICE and FILENAME directives to create the 6-bit ASCII characters for the device name or the file name. You can use these character strings as part of the coding for a call to the USR or for any other coding that requires a 6-bit packed device or file name. Note that these directives do not perform any other function (call the USR, etc.). They merely insert the 6-bit text for device and file name at the current location. The assembler checks to make sure that all characters are letters or numbers. The OS/8 Software Support Manual describes how to use the DEVICE and ____________________________ FILENAME directives in calls to the User Service Routine. 5.7.1 DEVICE The DEVICE directive creates the 6-bit ASCII codes for a 4-character OS/8 device name and packs them into two words. The form of the directive is: DEVICE dev where: dev is the device name. You can specify from one to four alphanumeric characters; other characters are illegal. The directive always generates two 12-bit words of data regardless of the number of characters in its argument. If the argument contains fewer than four characters, the remaining character positions are packed with binary zeroes. 5.7.2 FILENAME 5-26 MACREL DIRECTIVES The FILENAME directive creates the 6-bit ASCII codes for the characters of an OS/8 file name and extension. The form of the directive is: FILENAME filename.ex where: file name is the name of the file. You can specify from one to six characters. .ex is the file name extension. This consists of a period followed by two characters. The directive always generates four 12-bit words: three for the file name and one for the extension (the period for the extension is implied). If the file name contains less than six characters, the remaining character positions are packed with binary zeros. If the extension is missing, the extension word is packed with binary zeros. 5.8 LOADING INFORMATION DIRECTIVES MACREL provides following directives that supply information directly to LINK. These are: o .START o .JSW o .VERSION 5.8.1 .START The .START directive specifies the program's starting address in the relocatable binary module rather than at LINK time. LINK, in turn, inserts this starting address into the memory image file (.SV extension). You can specify the .START directive in one of two forms: with two arguments or with only one argument. Each is interpreted differently. The 2-argument form of the directive is: .START m, n where: m is an absolute expression value in the range 0-7777 (octal) that specifies the starting address within a memory field. 5-27 MACREL DIRECTIVES n is an absolute expression value in the range 0-37 (octal) that specifies the memory field. For example, the coding, .START 2000, 4 specifies that the program is to start in field 4 at address 2000. The 1-argument form of the directive is: .START m where: m is an expression. The expression may be absolute or relocatable. If m is absolute, it defines the starting address, and the field is the same field as the current program section. If m is relocatable, the absolute part of the expression defines the starting address, and the field is the same as the field of the relocatable part of the symbol. For example, the coding, .RSECT MAIN .START 200 causes the program to start at address 200 in the same field that section MAIN loads into. Similarly, if WPROC is the name of another relocatable program section, the coding, .RSECT SUBR .START WPROC+4000 causes the program to start at address 4000 plus the value of WPROC in the same field that WPROC loads into. 5.8.2 .JSW The .JSW directive sets the Job Status Word (JSW) in the relocatable binary module. LINK, in turn, inserts this word into the memory image file (.SV extension) which it creates. The form of the directive is: .JSW n where: n is an absolute expression. 5-28 MACREL DIRECTIVES The JSW is a 12-bit word, in which different bits represent different instructions to the system program that loads the program into memory. For example if bit 0 is set, this indicates that no part of the program loads into locations 00000 to 01777. Refer to the OS/8 Software Support Manual for more information on the Job Status ____________________________ Word and its bit assignments. 5.8.3 .VERSION The .VERSION directive inserts a version number in the range 0 to 7777 (octal) into the relocatable binary module. The form of the directive is: .VERSION n where: n is an absolute expression. At present this information is not used, but it may be referenced by a user program, or by future DIGITAL EQUIPMENT CORPORATION software. 5.9 SYMBOL TABLE MODIFICATION DIRECTIVES MACREL provides the following directives that modify the symbol table. They are: o EXPUNGE o FIXMRI o FIXTAB With these directives you can eliminate unneeded symbols, add certain standard symbols, or define your own special symbols. NOTE Certain MACREL command string options affect the Permanent Symbol Table (see Table 8.1). 5.9.1 EXPUNGE The EXPUNGE directive deletes certain symbols and macro names from the symbol table. The directive has two forms: without arguments and with arguments. 5-29 MACREL DIRECTIVES The form of the directive without arguments is: EXPUNGE This form is generally used at the beginning of the program. EXPUNGE causes all regular permanent and program-defined symbols to be deleted from the symbol table. Macro names, directive keywords and keyword arguments, program section names, special symbols, and symbols that have been named by a declaration directive are not deleted. The deletion occurs at the current point in the assembly. After an EXPUNGE, symbols may then be selectively redefined. The directive functions only on assembly pass one. The form of the directive with arguments is: EXPUNGE symbol,... where: symbol is a symbol name. The directive causes MACREL to delete each symbol that you specify from the symbol table at the current point in the assembly. For example, EXPUNGE RSF, RRB, RFC deletes the machine instruction mnemonics for the high-speed reader from the permanent symbol table. You can use the EXPUNGE directive to delete program symbols, permanent symbols, or macro names. It does not delete a directive name, special symbol, or a symbol named with a declaration directive. An attempt to delete these causes an error message. It is legal, incidentally, to include a nonexistent symbol in the list. Use this feature if you are uncertain whether the symbol exists. You can also use the EXPUNGE directive with a list to delete a macro name and its associated text from the symbol table area. This space is reclaimed, allowing more space in the symbol table area for other functions. There are three general reasons to perform an EXPUNGE with a permanent or program-defined symbol: 1. To delete a symbol to gain space in the symbol table. 2. To redefine a symbol (EXPUNGE should occur before the first use of the symbol). 3. To use the symbol, delete it, and then redefine it (perhaps several times). For example, you might have a subroutine in another file that happens to use the same symbol or label that the main program uses. 5-30 MACREL DIRECTIVES The EXPUNGE without arguments works only on pass one. This prevents deleting symbols that you have redefined. The purpose of the first pass is to create the symbol table; if the assembler performed a general EXPUNGE at the beginning of the second pass, it is effectively set back to pass one again. The assembler normally performs the EXPUNGE with arguments directive on assembly pass 1 only. To have the EXPUNGE with arguments act on all passes, use the EXPUNGE option of the .ENABLE directive in the form: .ENABLE EXPUNGE Note that the EXPUNGE option of the .ENABLE directive is different from the EXPUNGE directive. The option allows you to use the EXPUNGE directive with arguments in much the same way as EXPUNGE without arguments. For example, in the code, EXPUNGE HLT . . . TAD HLT . . . HLT, 7000 the pass-one-only EXPUNGE allows the symbol HLT to be used before it is defined. NOTE If the all-pass EXPUNGE were used, an undefined symbol error would occur on pass 2. Use the .DISABL directive in the form: .DISABL EXPUNGE to return the EXPUNGE with arguments to its former status. 5.9.2 FIXMRI The FIXMRI directive defines a symbol as a memory reference instruction. The form of the directive is: FIXMRI sym=exp 5-31 MACREL DIRECTIVES where: sym is a symbol name exp is an absolute expression. For example, FIXMRI TAD=1000 redefines TAD to its normal value. Use the directive to respecify the memory reference instructions after deleting the Permanent Symbol Table. 5.9.3 FIXTAB The FIXTAB directive defines permanent symbols. It has two forms: without arguments and with arguments. The form of the directive without arguments is: FIXTAB It causes all previously defined symbols to be marked as permanent symbols. Use the FIXTAB directive to redefine permanent symbols that have been removed with the EXPUNGE directive. An example of such a redefinition would be to create a file named PERMSY.MA that contains the desired symbols, CLA=7200 NOP=7000 HLT=7402 SNA=7450 . . . FIXMRI AND=0000 FIXMRI TAD=1000 FIXMRI ISZ=2000 . . . then insert the following code at the beginning of the source file: EXPUNGE .INCLUDE PERMSY.MA FIXTAB This deletes the old permanent symbols and establishes the symbols in the file as the new permanent symbols. 5-32 MACREL DIRECTIVES The form of the directive with arguments is: FIXTAB symbol,... where: symbol is a symbol name. The directive causes the symbols named in the argument to be marked as permanent symbols. Thus, SET1= CLA IAC /SET AC=1 SGT0= SPA SNA /SKIP IF AC GREATER THAN 0 FIXTAB SET1, SGT0 defines SET1 and SGT0 as permanent symbols having the values shown. Using FIXTAB this way prevents SET1 and SGT0 from being accidentally redefined. NOTE You can also define macro names as permanent symbols. 5.10 STACK MANIPULATION DIRECTIVES The stack manipulation directives, .PUSH and .POP, insert one or more numbers into a pushdown stack (.PUSH) and retrieve them on a last in, first out basis (.POP). Thus the first number pushed onto the stack is the last number popped off the stack. The stack has a capacity of about 25 numbers. The stack is used at assembly time and is not available to the program at execution time. 5.10.1 .PUSH The .PUSH directive inserts one or more symbol values into the stack. The form of the directive is: .PUSH sym,... where: sym is a symbol name the value of which may be either absolute or simply relocatable. 5-33 MACREL DIRECTIVES For example, if the current radix is octal, *300 LOC, N=1O .PUSH N .PUSH LOC causes the following numbers to be inserted into the stack (bottom first): 10, 300. If the stack size is exceeded (too many numbers are pushed), MACREL prints a STACK OVERFLOW error message. 5.10.2 .POP The .POP directive retrieves one or more numbers from the stack. The form of the directive is: .POP sym,... where: sym is the name of the symbol whose value you wish to retrieve. Note that you must specify a list of arguments in the reverse order from that specified by the .PUSH directive, because MACREL retrieves the numbers in last in, first out order. Thus, if the statement .POP DATA, Q, were to follow the statement shown in Section 5.10.1, the following values would result: DATA 300 Q 10 If you .POP more values than you .PUSH, an error message results. 5.11 ASSEMBLY OPTIONS DIRECTIVES The assembly options directives allow you to enable and disable a variety of assembly features. (Some of these features are handled in PAL8 as run-time options.) 5-34 MACREL DIRECTIVES 5.11.1 .ENABLE The .ENABLE directive activates the options described in Table 5.5. The form of the directive is: .ENABLE option, ... where: option is one or more nonconflicting options listed in Table 5-5. NOTE You can dynamically alter these options at assembly time by changing the value of the .ENABWD special variable (see Section 5.11.3). If you specify the FILL option, the TEXT directive will always generate at least one character consisting of all zeros. In ASCII packing, this means always adding a word of all zeros. In SIXBIT packing, this means adding a word of all zeros if the number of characters is even. In OS8 packing, this means adding a word of all zeros if the number of characters is evenly divisible by 3. The unused character positions for both SIXBIT and OS8 options are padded with binary zeros. For more information about the TEXT directive, see Section 5.3.2. For more information about the SHIFT and OR options, see Section 4.8.6. For more information about the EXPUNGE option, see Section 5.9.1. (Notice that the option and the directive are different.) The PUNCH option causes the assembler to resume binary output if it has been discontinued by either a .DISABLE PUNCH directive or a NOPUNCH directive. CAUTION MACREL binary should not be directly output to paper tape since it will create an output file that is in a form that LINK cannot use. This is because MACREL expects that the output device is a random access device and does not build the file sequentially. 5-35 MACREL DIRECTIVES Table 5-5 .ENABLE Directive Options ---------------------------------------------------------------------- | Option | Action | |----------|---------------------------------------------------------| | ASCII | Causes the TEXT directive to generate one character per | | | word. (The bit length depends on whether the 7BIT or | | | the 8BIT option is in effect.) | | | | | * SIXBIT | Causes the TEXT directive to generate two characters | | | per word (six bits each) using the sixbit ASCII code. | | | | | OS8 | Causes the TEXT directive to generate three characters | | | in two words. Always produces an even number of words. | | | (The bit length depends on whether the 7BIT or the 8BIT | | | option is in effect.) | | | | | COS | Causes the TEXT directive to generate two 6-bit | | | characters per word packed according to the excess 237 | | | encoding scheme. (Refer to the COS-310 User's Manual.) | | | | | 7BIT | Causes double quote ("), uparrow double quote (^"), and | | | TEXT directive (unless SIXBIT packing is in effect) to | | | produce 7-bit ASCII codes. | | | | | * 8BIT | Causes double quote ("), uparrow double quote (^"), and | | | TEXT directive (unless SIXBIT packing is in effect) to | | | produce 8-bit ASCII codes (high-order bit is always 1). | | | | | * EXPUNGE| Causes the EXPUNGE directive with no arguments to work | | | on all assembly passes. | | | | | * FILL | Causes the TEXT directive to generate at least one | | | character containing all zeros at the end of the text | | | string. | | | | | * OR | Causes the exclamation point (!) operator to perform a | | | logical OR. | | | | | PERM | Causes the cross-reference program (KREF) and the | | | symbol table to include all permanent symbols. | | | | | PUNCH | Causes the assembler to resume output of the relocatable| | | binary file, if it has been discontinued. Acts only on | | | pass two. | | | | | SHIFT | Causes the exclamation point (!) operator to mean shift | | | six bits to the left then perform a logical OR. | ---------------------------------------------------------------------- * = Default condition. The following example illustrates OS8 packing. The 8-bit ASCII codes for A, B, C (i.e., 301, 302, 303) are represented as follows: 5-36 MACREL DIRECTIVES First Word 110 0 11 000 001 Left half ASCII A of ASCII C Second Word 001 1 11 000 010 Right half ASCII B of ASCII C The first word in octal is 6301 and the second word is 1702. 5.11.2 .DISABL The .DISABL directive disables the options shown in Table 5-6 that were enabled by the .ENABLE directive, or were the default conditions of the assembler. The form of the directive is: .DISABL option,... where: option,... is one or more options shown in Table 5-6 below. Table 5-6 .DISABL Directive Options ---------------------------------------------------------------------- | Option | Action (with .DISABL Directive) | |-----------|--------------------------------------------------------| | FILL | Disables the zero-fill action of the TEXT directive. | | | TEXT will then not add any extra words of zero. | |-----------|--------------------------------------------------------| | EXPUNGE | Causes the EXPUNGE directive with arguments to work | | | only on assembly pass 1. | |-----------|--------------------------------------------------------| | PERM | Disables the listing of permanent symbols in the | | | symbol table and cross-reference listing. | |-----------|--------------------------------------------------------| | PUNCH | Causes the assembler to cease output of relocatable | | | binary file only, MACREL continues the assembly. | | | Acts only on assembly pass 2. | ---------------------------------------------------------------------- 5.11.3 .ENABWD Special Variable .ENABWD is an assembler-maintained variable that you can examine and modify to alter the options of the .ENABLE directive at assembly time. The variable contains a 12-bit number the bits of which control these 5-37 MACREL DIRECTIVES options (see Table 5-7). The following example shows how you can use .ENABWD in a macro to create a table of 8-bit ASCII characters padded with spaces. .MACRO ENTRY ARG .DSECT TABLE .PUSH .ENABWD .ENABLE ASCII, 8-BIT .DISABLE FILL TEXT L=8-.NCHARS ARG .IF LT L <.ERROR "TOO MANY CHARS" .IF NE L < .REPT 240 .ENDR > .POP .ENABWD .SECT * .ENDM ENTRY 5-38 MACREL DIRECTIVES Table 5-7 .ENABWD Bit Assignments ---------------------------------------------------------------------- | Bit | Value | Meaning | |---------|----------|-----------------------------------------------| | | 0 | Enable zero fill. | | 0 |----------|-----------------------------------------------| | | 1 | Disable zero fill. | |---------|----------|-----------------------------------------------| | | 0 | Interpret ! operator as OR. | | 1 |----------|-----------------------------------------------| | | 1 | Interpret ! operator as 6- bit left shift, | | | | then OR. | |---------|----------|-----------------------------------------------| | | 0 | Do EXPUNGE (with arguments) on pass 1 only. | | 2 |----------|-----------------------------------------------| | | 1 | Do EXPUNGE (with arguments) on all passes. | |---------|----------|-----------------------------------------------| | | 0 | Do not cross-reference (KREF) permanent | | | | symbols. | | 3 |----------|-----------------------------------------------| | | 1 | Do cross-reference (KREF) permanent | | | | symbols. | |---------|----------|-----------------------------------------------| | | 0 | Enable 8-bit ASCII. | | 4 |----------|-----------------------------------------------| | | 1 | Enable 7-bit ASCII. | |---------|----------|-----------------------------------------------| | | 00 | Enable SIXBIT packing. | | |----------|-----------------------------------------------| | | 01 | Enable ASCII packing. | | 10,11 |----------|-----------------------------------------------| | | 10 | Enable OS/8 packing. | | |----------|-----------------------------------------------| | | 11 | Enable COS packing. | ---------------------------------------------------------------------- 5-39 CHAPTER 6 MACRO AND REPEAT DIRECTIVES Macros are a programming tool that allow you to simplify and customize assembly language programs. They allow you to define generalized code sequences, data structures, listing conventions, program structures, assembly controls and so on, and then customize each of these as required. For instance, you can use a single symbol to represent any sequence of assembly language statements. This allows you to replace similar (not necessarily identical) code sequences by a macro definition. You can call the macro wherever desired in the program to insert the code. For example, Suppose your program includes many code sequences of the form: CDF 10 MRI CDF 00 (Where MRI is a memory reference instruction.) The macro definition, .MACRO INST A CDF 10 A CDF 00 .ENDM INST can be called with any MRI, anywhere in the program. Thus, INST "TAD I DATALOC" expands to: CDF 10 TAD I DATALOC CDF 00 while INST "ISZ COUNT" expands to: 6-1 MACRO AND REPEAT DIRECTIVES CDF 10 ISZ COUNT CDF 00 As another example of macro utility consider the difficulty of passing data to the following subroutine: (Main Program) *400 SONG, CLA CLL TAD SWEHRT DCA .+3 TAD CHI JMS I 30 0000 DCA VERSE . . . VERSE, 0000 SWEHRT, 40 CHI, 26 *30; 6000 (Subroutine) *6000 CHORD, 0000 CIA DCA SIGMA TAD I CHORD ISZ SIGMA JMP .-2 ISZ CHORD JMP I CHORD SIGMA, 0000 Note that in using this subroutine, the main program includes almost as many instructions to initialize the subroutine as there are in the subroutine itself. The example at the end of Section 6.1.1 shows a macro definition that simplifies and customizes this subroutine. Much of the flexibility of MACREL derives from the many features of macros, which include: o Multiple arguments (maximum of 8) o Nesting of macro definitions o Null arguments o Repeat ranges o Nested repeats 6-2 MACRO AND REPEAT DIRECTIVES o Nested macro calls o Conditional macros o Argument substring selection Since macros expand to the complete text sequence when called, you can include all MACREL directives in the body of the macro text to control assembly of program sections. 6.1 MACRO DEFINITIONS Define a macro by following the .MACRO directive with the name of the macro, any dummy arguments that are needed, the text, and a terminator. The text is the source code that you want MACREL to assemble at the point in the program where you insert the macro call. You can include dummy arguments in the macro to indicate that you want to pass actual arguments at calling time. 6.1.1 .MACRO and .ENDM Directives The .MACRO directive is the first item in the macro definition and always begins the first line of the macro. The second line of the definition, and as many lines thereafter as are needed, is the text, or body, of the macro. The final line of the macro definition is the macro terminator. The form of the macro definition is: .MACRO name [arg,...] [/comments] text text . . . text .ENDM name where: .MACRO is the macro directive name is the name you choose to identify the macro. Any unique legal symbol up to six printing characters (excluding permanent symbols) may be used. The macro name is separated from the dummy arguments, if any are used, by any sequence of spaces or tabs. 6-3 MACRO AND REPEAT DIRECTIVES arg, is a dummy argument. You can use from zero to eight legal symbols as dummy arguments to be replaced at call time with the actual arguments passed with the call. These symbols can appear elsewhere in the program without conflict of definition. If you use more than one dummy argument in the definition you must separate them with a legal separator, such as a comma, space, or tab. The dummy arguments are optional; many small macros will not require them. /comments is a string of text that you can include as comments after the last dummy argument. Always start a comment with a slash (/). text is the text that will be assembled in the text program each time the macro expands. The . macro expands whenever you call it by name. . . text .ENDM [name] The .ENDM directive terminates the definition. The assembler continues processing the code following this terminator. Using the macro name after the .ENDM directive is optional but is recommended to help you keep track of which macro is being terminated. The name you use must be the name you used in the .MACRO directive that begins the definition. Each macro definition must precede any use (call) of the macro in the source module. It is usually good practice to group all macro definitions at the start of the source module in which they are used. The following is an example of a macro definition. It uses the routine that multiplies two numbers (used at the beginning of this chapter). .MACRO CHORD A,B CLA CLL TAD A CIA DCA SIGMA TAD B ISZ SIGMA JMP .-2 DCA VERSE .ENDM CHORD 6-4 MACRO AND REPEAT DIRECTIVES The name of this macro is CHORD and its dummy arguments are A and B. When CHORD is called, it expands as shown in Figure 6-2. Figure 6-1 illustrates macro definition and storage. It shows a simplified line diagram of the process used by the MACREL assembler, when the macro is defined. The macro is defined at the start of each assembly pass. This scanning is indicated in the figure by the top block in the source module column. The assembler scans each line and defines symbols. When the .MACRO directive is the first item in a statement line, the assembler defines the macro name in the symbol table and then transfers control to the macro processor, a software component of the complete MACREL assembler. The macro processor now stores the text following the directive in macro space, which is a section of resident memory reserved for the storage of current assembly macro definitions. In the above example, the macro processor stores all the text after the name CHORD up to the .ENDM terminator. When the macro processor scans the .ENDM directive, control returns to the MACREL assembler and macro storage ceases. The .ENDM directive instructs the assembler to return to scanning statement lines and continue the assembly. The body of the macro stored in the macro space is still text at this time; that is, it is unassembled ASCII characters. The text will not be interpreted as instructions or data until the macro is called. ---------------------------------------------------------------------- | ASSEMBLER | | SCAN (Pass One) | __________ | | | | -----------------|--- | | | SOURCE V | | | | | MODULE | | | | | | | | | | | | | | | V | | | | |----------------|--| ................... | | | MACRO |--------------->| | | | | DEFINITION | | Definition | | | | | | stored in MACRO | | | | | | SPACE for use | | | | | | at call time | | | | |<---------------| | | | |-------------------| |.................| | | | MODULE V | | | | | CONTINUES | | | | | | | | | | | | | | | V | | | | --------------------- | | | ---------------------------------------------------------------------- Figure 6-1 Macro Definition and Storage 6-5 MACRO AND REPEAT DIRECTIVES 6.2 MACRO CALLS You can call a macro by entering the name of the macro along with the actual arguments to be used at the point in the program where you want MACREL to expand the code. The form of the macro call is: name [argl,...,arg8] where: name is the name that you assign to the macro when defining it. argl,...,arg8 are the actual arguments that replace the dummy arguments used in the definition. These are the arguments that are evaluated in the macro when the macro code is assembled. If, in the previous example, the number 40 is to be multiplied by 26, the call to the macro would be: CHORD (26, (40 CHORD is the name of the macro, and the two actual arguments are (26 and (40. During assembly, MACREL recognizes the call and expands the macro. The assembler scans each statement line and, while continuing to define symbols, looks up already defined symbols in the symbol table, interprets the statements, and generates the object code. When the assembler reads a macro call, control transfers to the macro processor which then suspends assembly, reads the macro text into the main line of the program section, and assembles the text to generate object code. This transfer is shown in the simplified line diagram in Figure 6-2 in which the macro call CHORD with the arguments (26 and (40 is read by the assembler, processed by the macro processor, and expanded into the complete macro as defined. Note that the actual arguments (26 and (40 replace the dummy arguments A and B and that the expanded macro, with all of its instructions, is placed in the source module at the point of the call. The locations following the call (labeled SIGMA and VERSE) now follow the expanded macro. This expansion takes place each time the macro is called and if, each time it is called, the real (or actual) arguments are new, the macro expands with new arguments replacing the dummy arguments in each call. 6-6 MACRO AND REPEAT DIRECTIVES ---------------------------------------------------------------------- | source module | | original as seen by MACREL | | assembler | | source . | | . | | module . | | . -------------------- | | . | CLA CLL | | | . | | | | . | TAD (26 | | | . | | | | . | CIA | | | . | | | | . | DCA SIGMA | | | .................. | | | | | CHORD (26, (40 |--- macro processor --->| TAD (40 | | | .................. | | | | SIGMA, 0000 | ISZ SIGMA | | | | | | | VERSE, 0000 | JMP .-2 | | | | | | | | DCA VERSE | | | -------------------- | | SIGMA, 0000 | | | | VERSE, 0000 | ---------------------------------------------------------------------- Figure 6-2 Macro Expansion 6.3 MACRO ARGUMENTS A macro definition may contain from zero to eight dummy arguments. The call to a macro may pass up to eight associated actual arguments. There is a strict positional relationship between the dummy arguments and the actual arguments. The first actual argument replaces the first dummy argument, the second replaces the second and so on. This positional relationship continues for all of the actual arguments passed to the macro. If, when calling the macro, you wish to pass fewer actual arguments than the definition requires, the macro processor will interpret as null arguments any comma that occupies the position of a dummy argument in the definition. 6.3.1 Actual Arguments From zero to eight actual arguments may be passed to a macro. These actual arguments are text strings that are separated from each other by either, (1) tabs and/or spaces or (2) a comma. The comma may be surrounded by spaces or tabs. 6-7 MACRO AND REPEAT DIRECTIVES The first actual argument is separated from the macro name by any number of spaces or tabs. For example, MACNAM A,B,C,D or to improve readability, MACNAM A , B , C , D or you can eliminate the commas to give the appearance of a machine instruction with operands. For example, DSZ I A might be a call to a macro with two arguments. Each actual argument is pure text and may contain any character except comma or space. For example, BAR NONE, A, > is a macro call with three arguments, NONE , A , and >. If you use a macro call to end a conditional statement, the terminating right angle bracket of the conditional statement must appear on the next line. For example, .IF DF X < BAR NONE,A> includes a macro call with the actual arguments "NONE" and "A>" But .IF .DF X < BAR NONE A > has the two actual arguments NONE and A. If spaces, tabs, or commas are to appear in a actual argument, you must enclose them in double quotes ("). For example, STAN A,B is a macro call with the two arguments A and B, whereas, STAN "A,B" has only one actual argument, the three character string (A,B). If you want to use a double quote as part of the actual argument, insert two double quotes. Thus, TYPE "HE SAID ""HELLO"" TO THE MAN." 6-8 MACRO AND REPEAT DIRECTIVES has as its actual argument the character string: HE SAID "HELLO" TO THE MAN. You can also use a pair of angle brackets to enclose an actual argument. For example: TYPE An actual argument that begins with a left angle bracket extends to the matching right angle bracket. If angle brackets are used within the text string they must be paired. An actual argument may begin with a backslash (\). The term following the backslash is evaluated by MACREL and the representation of the resulting value (in the current radix, and without leading zeros) becomes the actual argument. For example in the call: MACIN A, \CLA , B the second argument is the four-character string 7200. If there are more actual arguments than are specified by dummy arguments, the excess actual arguments are ignored. If there are fewer actual arguments than dummy arguments, MACREL assumes that each unspecified actual argument that remains is a null string. 6.3.2 Substrings of the Argument You can define macros that use substrings of the actual arguments passed. The form is: dummy argument [low:high] where: dummy argument is the name of the dummy argument in the macro definition for which you wish to use a substring of the actual argument. [ delimits the beginning of the range specification. low is an expression value that specifies the ordinal position of the first character that you want in the substring. : separates the low value from the high value. high is an expression value that specifies the ordinal position of the last character that you want in 6-9 MACRO AND REPEAT DIRECTIVES the substring. If the value is zero, all characters to the end of the argument string will be accepted. If you do not specify a value for high, the value of low is assumed. ] delimits the end of the range specification. Both high and low may be either variables or expressions. MACREL evaluates variables when the macro expands. It evaluates expressions at macro definition time. To allow MACREL to differentiate between the two, you must begin an expression with a digit. For example: DARG[0+FOO-BAR:0+BAR-FOO] In a macro with A as a dummy argument, any occurrence of A in the definition expands to the actual argument when the macro is called. But if, in the text of the definition, the dummy argument is followed by a left square bracket, only selected characters in the actual argument are used. For example, A[3] expands with only the third character of the actual argument; A[3:6] expands with the third through the sixth characters of the actual argument. For example: .MACRO CLEAR R,E,G .IF IDN R[1],$ .ENDM CLEAR The macro expands when called. If the first character in the actual argument passed is a dollar sign ($), the code CLA CLL is assembled. The following example illustrates the utility of substring specification. .MACRO PRINT V TEXT " THEE LOVES V[1:N]" .ENDM PRINT In this example, you supply a value to N inside the brackets, and call the macro N=4 PRINT HEROS The result is that four of the five characters (i.e. HERO) are accepted as the actual argument. 6.3.2.1 .NCHAR Special Operator - The .NCHAR special operator returns a 12-bit expression value that is the number of characters in the string identified by its argument. .NCHAR must always be the last element in the expression. The form of the operator is: 6-10 MACRO AND REPEAT DIRECTIVES .NCHAR erg where: erg is any text string. You can define a macro to use a substring of the argument depending on the number of characters passed in the actual argument. For example: .MACRO PRINT A L=.NCHAR A IF EQ L-4< .DISABL FILL TEXT "THEE LOVES A[1:4] .ENABLE FILL > .ENDM PRINT 6.3.3 Symbols and Names in Macros You must exercise care when choosing macro names, dummy arguments, and actual arguments. In most situations common sense and a knowledge of assembly language are reliable guides. For example: .MACRO INSTR X,Y X!Y .ENDM INSTR The call to the macro is: INSTR CLA,CLL In this call, machine instructions are passed as actual arguments. While using a macro may not be an efficient way to clear the link and accumulator there is nothing wrong with the call. However, if some other instructions, say TAD and JMP, are used in the call, something else will happen. For example: INSTR TAD,JMP Now, because of the exclamation point (!) operator in the macro definition, MACREL does an inclusive OR of the instructions, and the object code that results makes no sense. Macros expand with actual arguments exactly replacing the dummy argument. It is your responsibility to assure that the actual arguments, when expanded, are legal within the sense of the definition. Actual arguments may include any printing character except comma, space, and tab. They can be included in quoted arguments (see Section 6.3.4). 6-11 MACRO AND REPEAT DIRECTIVES Dummy arguments are replaced when the macro expands so you can use any legal symbol as a dummy argument. Each macro is itself unique, therefore, the repeated use of the same symbol as a dummy argument in other macros creates no conflict. When choosing names for macros you cannot use any symbol in the permanent symbol table as a macro name. For example: .MACRO JMP K,L,H ISZ K JMP L JMP H .ENDM JMP Conceptually, the name JMP is appropriate as the name of a macro that jumps to some selected location. When the macro is called: JMP A+1,FOX,TABLE MACREL does not know if the word JMP is a machine instruction or a macro call. The Permanent symbol JMP could be expunged first or the macro could be named JUMP and be defined in the same way. The call then becomes: JUMP A+1,FOX,TABLE and without conflict, the macro expands to: ISZ A+1 JMP FOX JMP TABLE This call retains the descriptive macro name but prevents assembly errors. Long or complex macro definitions sometime require labels, or tags, to identify specific locations within them. You can use the same labels in different macros, so long as you create unique labels for each expansion (see Section 4.2.4). 6.3.4 Apostrophe (') Special Operator The apostrophe is a special operator in the macro definition. When you use it between two or more dummy arguments in the body of a macro, the apostrophe causes the concatenation of the arguments. Thus the apostrophe combines the two dummy arguments and their actual argument replacements into a single character string. The macro is written in the standard manner, with the directive, the name, and the dummy arguments. Concatenation is indicated in the body of the macro. For example: 6-12 MACRO AND REPEAT DIRECTIVES .MACRO CONCAT A,B /defines a macro which concatenates A'B /the two symbols A and B into one .ENDM CONCAT /symbol AB The macro definition, .MACRO ZEB TABLE,SUB TAD TABLE'SUB .ENDM . ZED . . . when called, ZED DATA, X expands to, TAD, DATAX which at run time adds to the accumulator the data located at address DATAX. Use the apostrophe (') only inside a macro definition immediately following a symbol name. (A'B is legal even if A is not a dummy argument.) When used in this manner the apostrophe is not stored in macro space. Any other use of the apostrophe inside a macro will not cause concatenation and it is stored in macro space as an apostrophe. Thus, if a macro includes the code, TAD ('PQ) the apostrophe does not concatenate (it does not follow a symbol) and it is stored in macro space for creation of a two character, 6-bit literal at expansion time. 6.4 NESTED MACROS This section discusses nesting of macro definitions and macro calls. It also covers the .MEXIT directive and concatenation in nested macros. 6.4.1 Nested Macro Definitions You can nest macro definitions to no more than eight levels. The actual level is determined by the complexity of the macros. Macros defined with the .INCLUDE or .CHAIN directives as part of the definition restrict the depth to which the macros may be nested. Because the .INCLUDE directive can itself be nested, the depth is 6-13 MACRO AND REPEAT DIRECTIVES further restricted by each level of nesting in the .INCLUDE directive. If, for instance, you nest one macro definition containing the .INCLUDE directive, and it contains another nested .INCLUDE, the total depth is three nests. The first nest for the macro, the second nest for the first .INCLUDE and the third for the nested .INCLUDE. Most of the macro definitions you write will not be complex enough, or contain enough nests to exceed the capacity of macro space or of the macro nesting stack. For example: .MACRO SETCLA /define a macro SETCLA with no argument .MACRO INSTR /define a second macro INSTR nested /within, SETCLA CLA /the single instruction CLA which is /the complete definition of the macro /named INSTR .ENDM INSTR /end second Level macro INSTR .ENDM SETCLA /end first level macro, SETCLA The macro call, SETCLA expands to: .MACRO INSTR CLA .ENDM INSTR which is the expansion of the first level macro In other words, the program now includes a macro definition with the name INSTR. When you call the macro, INSTR it expands to the single instruction: CLA which is the expansion of the second level macro. 6.4.2 Nested Macro Calls You can nest macro calls in a way that is similar to the nesting of macro definitions. For example: .MACRO TOP RED BOTTOM RED .ENDM TOP . . . 6-14 MACRO AND REPEAT DIRECTIVES .MACRO BOTTOM HED TEXT "HED" .ENDM BOTTOM The macro TOP contains a call to the macro BOTTOM; when TOP is called: TOP STRING This is the macro call with the actual argument STRING. It expands to: BOTTOM STRING The actual argument STRING replaces the dummy argument RED in the top macro but the word BOTTOM is, itself, a macro call. It now has the actual argument STRING and it expands to: TEXT "STRING" The expansion with the actual argument STRING replacing the dummy argument HED of the bottom macro. The macro definitions written so far are terminated with the .ENDM directive, but the .MEXIT directive, described below, is also useful in some macros using the conditional assembly directives. 6.4.3 .MEXIT Directive The example of nested macro definitions diagrammed in Section 6.4.1 had each macro terminated explicitly with the .ENDM directive and the name of the macro. The .ENDM directive is a MACREL assembler instruction that terminates macro storage and returns MACREL to the previous assembly. In nested macros, .ENDM still terminates macro storage, but the previous assembly is another macro definition. Therefore, MACREL first stops and then returns to storing macros. The .MEXIT directive is an assembler directive that instructs MACREL to stop assembling the macro - not to stop storing it. The form of the directive is: .MEXIT The directive resides in macro storage space along with the rest of the macro text. When you call the macro, MACREL reads the directive as it assembles code. When .MEXIT is read, MACREL stops assembly of the current macro and returns to assembling the previous code, which could be a macro at a higher nesting level. 6-15 MACRO AND REPEAT DIRECTIVES The following is an example of .MEXIT in conditional code: .MACRO JUMP A,B MESG B TAD (MESG'A) DCA ADDR$ SKP ADDR$, 0 TYPE MONIT, JMP I (7605) .ENDM JUMP .MACRO MESG B .IF BL B <.MEXIT> TEXT / B / .ENDM MESG In the case of nested macros, the final level of the macro is always terminated with the .ENDM directive. You can use the macro name optionally with the .ENDM directive. 6.4.4 Concatenation in Nested Macros When you use the apostrophe (') concatenation operator in nested macros, the concatenation of the symbols differs from that described in Section 6.3.4. Each level of nested macro requires an extra apostrophe. For example, you might wish to use TAD ALPHA'BETA in a nested macro named VALUE. If VALUE is nested to the third level, three apostrophes are needed, ALPHA'''BETA. MACREL interprets one apostrophe for each level. A second level nested macro would require two apostrophes to concatenate symbols, a third level nest requires three apostrophes, a fourth level requires four, and so on. 6.5 CONDITIONAL ASSEMBLY DIRECTIVES IN MACROS The conditional assembly directives were discussed in Section 5.5. In Section 6.3 conditional assembly was shown as part of the example illustrating selected substrings of arguments. From these examples, you can understand that any .IF directive can be used in a macro definition. Two of the .IF directives (.IF BL and .IF NB) are normally used only within macro definitions. You can use them to test the macro call for actual non-null arguments. A conditional block of source code with the .IF BL directive is assembled if a specified argument is not passed with the call. The .IF NB directive allows assembly if a specified argument is passed. 6-16 MACRO AND REPEAT DIRECTIVES In the following example, a macro named CHANGE calls another macro named JUMP with different actual arguments being passed, depending on whether or not a non-null argument has been passed to CHANGE. .MACRO CHANGE XYZ .IF BL XYZ .IF NB XYZ .ENDM CHANGE Only the two directives .IF BL and .IF NB are used in this example, but all of the other conditionals are legal. For example, if you have to determine if the symbol NEWAVG is defined, you could use the following: .IF DF NEWAVG <.......> or, if you wanted to determine if NEWAVG is both defined and equal to some other value, you could use the following: .IF BD NEWAVG <.IF EQ NEWAVG-OLDAVG<......>> The next example shows how you can write both of the conditionals as a macro: .MACRO SCRTCH .IF DF NEWAVG< .IF EQ NEWAVG-OLDAVG> .TAD OLDAVG .ENDM SCRTCH When you use a conditional statement in a macro definition, the first left angle bracket (<) that encloses the conditional code must be on the same line as the .IF directive. The right angle bracket (>) must be on the last line that contains conditional code. This is shown in the example above. 6.5.1 Nested Conditional Source Code in Macros Nesting conditional statements in macros simplifies the coding of complex program sections. The macro CHANGE shown above is rewritten in Figure 6-3 to show how you can use nested conditional macros to determine if arguments have been passed to it and if so, how many. The example uses the special operator .NARGS described in Section 6-17 MACRO AND REPEAT DIRECTIVES 6.5.2, which returns the number of arguments passed with the macro call. .MACRO CHANGE A,B,C X=.NARGS /FIND OUT HOW MANY ARGUMENTS PASSED .IF EQ X /FIRST MESSAGE .IF NE X> /MESSAGE AND EXIT X=X-1 /TRY AGAIN .IF EQ X X=X-1 /AND AGAIN .IF EQ X .IF NE X /PRINT DUMMY MESSAGE .ENDM CHANGE /AND EXIT .MACRO MESG B TEXT "B" .ENDM MESG .MACRO JUMP A /THIS MACRO CONCATENATES THE ACTUAL ARGUMENT /WITH MESG STORES THE ADDRESS OF MESG AND /THEN CALLS THE MACRO TYPE TO COMPLETE THE /ROUTINE. TAD (MESG'A) DCA ADDR$ SKP ADDR$: 0 TYPE / THE CALL TO THE MACRO TYPE MONIT, JMP I (7605) .ENDM JUMP /THIS IS A MACRO TO TYPE A STRING OF CHARACTERS ON A SINGLE LINE AT /THE TERMINAL.THE ACCUMULATOR HOLDS THE ADDRESS OF THE CHARACTER /STRING (FROM DCA ADDR$ IN THE MACRO JUMP) WHICH MUST BE IN THE /CURRENT FIELD.AT THE COMPLETION OF THE MACRO THE ACCUMULATOR EQUALS /0000.THE STRING FORMAT IS 6-BIT ASCII CHARACTERS TERMINATED BY NULL /(00) WHERE THE FIRST CHARACTER IS THE LEFT HALF OF A 12-BIT WORD. /*** NOTE *** WILL NOT PRINT CR OR LF CHARACTERS *** Figure 6-3 Example of Nested Conditional Source Code in Macros 6-18 MACRO AND REPEAT DIRECTIVES .MACRO TYPE CLL /START WITH LEFT HALF LOOP$: TAD I ADDR$ /GET WORD FROM STRING SNL /LINK INDICATES HALF BSW /LEFT HALF AND (77) /MASK SIX BIT BYTE 0-37 40-77 SNA /IS IT NULL JMP MONIT /YES/ RETURN TO MONITOR TAD (240) /NO -CONVERT TO ASCII 240-277 300-337 AND (77) 40-77 0-37 TAD (240) 300-337 240-277 TLS /SEND TO TERMINAL TSF /WAIT UNTIL PRINTED JMP .-1 CML /SWITCH TO OTHER HALF SNL CLA /IS IT LEFT HALF ISZ ADDR$ /YES-NEXT WORD JMP LOOP$ /NO-SAME WORD .ENDM TYPE .RSECT CONDIT .LIST ME CHANGE .DSECT ERRMSG MESG0, MESG "NO ARGUMENTS PASSED" MESG1, MESG "ONE ARGUMENT PASSED" MESG2, MESG "TWO ARGUMENTS PASSED" MESG3, MESG "THREE ARGUMENTS PASSED" MESG4, MESG "TOO MANY ARGUMENTS PASSED ,DUMMY" Figure 6-3 (cont.) Example of Nested Conditional Source Code in Macros 6.5.2 .NARGS Special Operator The .NARGS special operator returns a 12-bit value that is the number of actual arguments passed in a macro call. This operator is legal only when used in a macro definition. In Figure 6-3, the symbol X is directly assigned the quantity returned by .NARGS, that is, the number of arguments passed. This count includes specified null actual arguments. 6.6 DEFINING AND CALLING REPEAT BLOCKS MACREL provides a special directive that lets you repeat the same sequence of code a number of times. The repeat block defined with the .REPT directive expands immediately and the code is repeated as many times as called for by the argument of the directive. 6-19 MACRO AND REPEAT DIRECTIVES 6.6.1 .REPT and .ENDR Directives The general form of the repeat directive includes the directive, the argument to the macro, and, on the next line, the body (or text) of the directive. The repeat block is terminated with the .ENDR directive. The form of the directives is: .REPT argument text . . . . text .ENDR where: .REPT is an assembly directive informing the assembler that the following code is to be repeated. argument is the number of times the code is to be repeated. The argument may be any expression value in the range of 0 to 7777 (octal). text . is the body of the macro that is to be repeated, this . is stored as text in the symbol table and is . expanded as written. . text .ENDR is the terminating directive of the repeat macro. It halts the storage of text in the symbol table. Processing of the program continues with the statement line following the .ENDR directive. All repeat blocks must be terminated with the .ENDR directive. For example: A=3 TAD COUNT CIA .REPT A IAC .ENDR 6-20 MACRO AND REPEAT DIRECTIVES DCA NOACC When MACREL expands this macro, it repeats the instruction IAC as many times as specified by the current value of A. If the value of A is 3, IAC will occur three times as shown below: TAD COUNT CIA IAC IAC IAC DCA NOACC Upon execution of the expanded and assembled code, the value of COUNT is brought into the accumulator, complemented, and incremented and then incremented three more times before being deposited in NOACC. Neither the .REPT nor the .ENDR directive appears in the expanded macro text. The text of the repeat is stored in macro space temporarily and is deleted from these after assembly. 6.6.2 Nested Repeats You can nest repeat blocks to any level. The only limit is the capacity of the assembler's internal stack. The example in Figure 6-4 shows a repeat block with a range of three nested inside a repeat block with a range of two. Figure 6-5 shows how MACREL expands the nested repeat block. 6-21 MACRO AND REPEAT DIRECTIVES ------------------------------------ | .REPT 2 | | | | RAR | OUTER NEST | | | IAC | | | | -------------------- | | | .REPT 3 | INNER | | | | NEST | | | RAL | | | | | | | | RTL | | | | | | | | .ENDR | | | -------------------- | | IAC | | | | .ENDR | ------------------------------------ Figure 6-4 Example of a Nested Repeat Block 6-22 MACRO AND REPEAT DIRECTIVES ------------------------------------ | RAR | | | 1st repeat of | IAC | outer nest | | | ----------- | | | RAL | 1st repeat | | | | of inner | | | RTL | nest | | ----------- | | ----------- | | | RAL | 2nd repeat | | | | of inner | | | RTL | nest | | ----------- | | ----------- | | | RAL | 3rd repeat | | | | of inner | | | RTL | nest | | ----------- | | IAC | ------------------------------------ ------------------------------------ | RAR | | | 2nd repeat of | IAC | outer nest | | | ----------- | | | RAL | 1st repeat | | | | of inner | | | RTL | nest | | ----------- | | ----------- | | | RAL | 2nd repeat | | | | of inner | | | RTL | nest | | ----------- | | ----------- | | | RAL | 3rd repeat | | | | of inner | | | RTL | nest | | ----------- | | IAC | ------------------------------------ Figure 6-5 Example of the Expansion of a Nested Repeat Block The .MEXIT directive treats the body of a repeat range as if it were a macro body. 6-23 CHAPTER 7 RELOCATION NOTE This chapter is a logical continuation of "Introduction to MACREL Relocation," Section 1.5 in Chapter 1. Although that section was presented earlier in order to facilitate understanding the rest of the manual, it may be considered as the first section of this chapter. You may find it helpful to review that section before continuing with this chapter. In addition, reviewing "The MACREL Assembler," Section 1.6 and "LINK, the Linking Loader," Section 1.7 will be helpful in understanding relocation as discussed in this Chapter. You can use the relocation features that MACREL and LINK provide at two levels. On the first level, you can write a relocatable program that is wholly contained in one source module. The advantages of writing a relocatable rather than an absolute program at this level are as follows: 1. LINK performs the job of allocating memory. 2. Programs are loaded more efficiently. For example, LINK automatically groups .DSECTS and .FSECTS in an efficient way. 3. If desired, LINK provides an output of a load map, showing where each section is loaded. This can speed up debugging. 4. The use of segmentation (grouping code that performs one function in one program section) makes for clearer, better designed programs which may be easily modified, if necessary. 5. Programs sometimes become larger than expected, and coding programs as relocatable from the beginning allows them to be easily broken into modules later on. Also, you may wish to employ a routine from a different module later on. On a second level, you may wish to write code that employs two or more modules that communicate with each other. The additional advantages of using this approach are the following: 7-1 RELOCATION 1. You can work with smaller blocks of code so that you can perform the whole process of coding, debugging, editing, reassembling, and listing with files of manageable size. 2. LINK performs all operations of linking the two modules, therefore eliminating another difficult and time-consuming affair. 3. You can create libraries of commonly used subroutines and include them as part of the current program by specifying their file name in the list of input files to LINK. This eliminates copying subroutines into the source program and makes for smaller source listings. It also simplifies the problems of program development as more and more subroutines become written. 4. Overlays may be defined at link time. 5. The added structural advantage of defining specific entry points that are used in communication between modules makes for more logical design of programs. The remainder of this chapter discusses the following subjects: o Program section directives o Inter-module communication o Relocatable code o Overlays 7.1 THE PROGRAM SECTION DIRECTIVES The program section directives allow you to divide your program into absolute and relocatable parts. If you do not put any program section directives in a program, MACREL treats the program as an unnamed absolute program section (.ASECT) that begins at location 200. Every FIELD directive in a program like this implicitly defines a new unnamed absolute program section. MACREL assigns a default name to each unnamed program section. The types of program sections are summarized in Table 7-1, and are described in more detail in the paragraphs that follow. No program section may extend across field boundaries (this limits a section to no more than 4095 locations). A program section extends until it reaches the end of the field, until a new program section is defined, or until the source module ends. 7-2 RELOCATION Table 7-1 Types of Program Sections ---------------------------------------------------------------------- | Section | Description | Loading Restriction | |----------|----------------------------|----------------------------| | .ASECT | ABSOLUTE SECTION- | Extends from its lowest | | | Where code or data | address to its highest | | | must be located at | address, inclusive. | | | specific addresses. | | | | | If no field statement | | | | is specified, loads | | | | into field 0, but can | | | | not use location 7777. | |----------|----------------------------|----------------------------| | .RSECT | RELOCATABLE SECTION- | May be loaded anywhere | | | General programming | in memory, except page 0. | | | use. | Starts to load on the | | | | beginning of a page. | |----------|----------------------------|----------------------------| | .ZSECT | PAGE ZERO SECTION- | May be loaded anywhere | | | Used for any page zero | inside page zero, | | | code. Generally field | locations 20-177. | | | restricted to the same | | | | field as the .RSECT to | | | | which it relates or | | | | vice versa. | | |----------|----------------------------|----------------------------| | .XSECT | AUTOINDEX SECTION- | May be loaded anywhere | | | Used for code that | inside locations 10-17, | | | employs the autoindex | the autoindex registers. | | | registers. Generally | | | | field restricted to | | | | the same field as the | | | | RSECT to which it | | | | relates or vice versa. | | |----------|----------------------------|----------------------------| | .DSECT | DATA SECTION- Contains | May be loaded anywhere | | | relocatable data. (May | in memory. May flow | | | not be used for | across pages. | | | instructions). | | |----------|----------------------------|----------------------------| | .FSECT | FLOATING SECTION- | May be loaded anywhere | | | Contains instructions. | in memory (not | | | Generally used for | necessarily beginning on | | | short subroutines, so | page boundary), but must | | | that several may be | be wholly located within | | | loaded onto the same | one page. | | | page. | | ---------------------------------------------------------------------- 7-3 RELOCATION 7.1.1 Unnamed Program Sections MACREL treats all source program statements, up to the first program section directive that it finds, as an unnamed absolute program section (.ASECT). This allows you to assemble PAL8 programs without inserting program section directives. MACREL also assumes that all statements up to the first FIELD directive that it finds will be loaded starting at location 200 of field zero. Upon finding a FIELD directive, it terminates assembly in the current unnamed program section and begins assembling the code into another unnamed program section. MACREL assigns a special default name to each unnamed absolute program section and inserts this name into the symbol table. These names have the form: FLD:n where: n is either the number of the field specified in a FIELD directive argument, or zero, if no FIELD directive was specified. MACREL loads page zero literals that occur in an unnamed program section in descending order beginning at location 177. 7.1.2 .ASECT The .ASECT directive defines an absolute (nonrelocatable) program section that is very similar to a PAL8 program. Inside an .ASECT, you can define code that loads into the autoindex registers, or anywhere in memory. The form directive is: .ASECT name or .SECT name, A where: name is a legal symbol that identifies this program section. For example, an .ASECT named MAIN is specified in the form: .ASECT MAIN *600 . 600 indicates the address at which the program loads. 7-4 RELOCATION If you do not set the current location counter with the asterisk (*) directive, loading will begin at location 200. 7.1.3 .RSECT The .RSECT directive defines a general relocatable program section. LINK will load a program section defined by this directive anywhere in memory except page zero. You can specify additional loading restrictions by using the FIELD directive and the PAGE and LOC keywords. The form of the directive is: .RSECT name or [,PAGE n] [,LOC=n] [,LEVEL=n] [,OVERLAY=n] [,ROOT] .SECT name R where: name is the name of a legal symbol that identifies this program section. PAGE=n specifies the memory page where loading begins. The expression value n must be in the range 1-37 and may not be complex relocatable. LOC=n specifies the memory location where loading begins. The expression value n may not be complex relocatable. LEVEL=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay level and must be in the range 0-7. This option allows you to avoid specifying an overlay level at LINK execution time (see Section 9.1). OVERLAY=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay number and must be in the range 0-17(octal). This option allows you to avoid specifying an overlay/number at LINK execution time (see Section 9.1). ROOT specifies that this program section is the main (nonoverlay) part of the program (identical to LEVEL=0). NOTE Do not use the LOC or PAGE options if you use the FIELD directive. 7-5 RELOCATION 7.1.4 .ZSECT The .ZSECT directive defines a special relocatable program section. LINK will load a program section defined by a .ZSECT in locations 20-177 of page zero in any memory field. You can specify additional loading restrictions by using the LOC keyword or the FIELD directive. The form of the .ZSECT directive is: .ZSECT name or [,LOC=n] [,LEVEL=n] [,OVERLAY=n] [,ROOT] .SECT name, Z where: name is a legal symbol that identifies this program section. LOC=n specifies the memory location within page zero where loading begins. The expression value n must be in the range: 20-177, and may not be complex relocatable. Do not use this option if you use a FIELD directive. LEVEL=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay level and must be in the range 0-7. This option allows you to avoid specifying an overlay level at LINK execution time (see Section 9.1). OVERLAY=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay number and must be in the range 0-17(octal). This option allows you to avoid specifying an overlay/number at LINK execution time (see Section 9.1). ROOT specifies that this program section is the main (nonoverlay) part of the program (identical to LEVEL=0). Since more than one program section may load into page zero, if you define the loading address of each as the same value, they will overlay each other. If you define the loading address of each as different values, they will load into consecutive locations. If there is insufficient space, LINK will generate an error message. All values in a .ZSECT are .FSECT relocatable (see Section 7.1.6). Normally, .ZSECTs are used in conjunction with the .RSECTs to which they are related. If only one .RSECT uses a .ZSECT, you may wish to give them both the same name with a Z appended to the .ZSECT's name. You would normally restrict them to the same field by using a FIELD directive. If you know the field they will be loaded, you can use a statement in both program sections of the form: FIELD PFIELD 7-6 RELOCATION PFIELD must be a variable that is defined in the program. Alternatively you could code it as: .ZSECT SORTZ FIELD SORT BUFADD, 0 NEWV, 0 LAST, 0 / .RSECT SORT STRT, CLA TAD Z LAST DCA Z NEWV Here, .RSECT SORT is not field restricted; it can be loaded into any field. However, the .ZSECT it references is restricted to load into the same field as SORT. Other sections can reference this page zero section as well. Again, you will want either to restrict them to the same field, or to set up the necessary CDF construction to access the .ZSECTs field. If you have used many locations on page zero, it may be better to restrict the .RSECT, to the field of the .ZSECT. Except for naming the .RSECTs and .ZSECTs and performing the necessary field restrictions, the techniques for programming page zero references are the same as those in PAL8. MACREL automatically creates a special .ZSECT for any program section that includes page zero literals. MACREL assigns a special name to this literal .ZSECT that is the name of the program section with the page zero literals prefixed by a dollar sign ($). For instance an .RSECT named SPEC has an associated literal .ZSECT, restricted to the same field, named $SPEC. MACREL adds the dollar sign to identify a literal .ZSECT. Within the literal .ZSECT, the literals are allocated from the bottom location upward. The first page zero literal in .RSECT SPEC is located at location zero relative to $SPEC; the second page zero literal is at $SPEC+1 and so on. This normal allocation for literal .ZSECTs is reversed for unnamed .ASECTs only. This retains compatibility of the literal allocations between MACREL and the PAL8 assembler. 7.1.5 .XSECT The .XSECT directive defines a special relocatable program section. LINK will load a program section defined by an .XSECT into the autoindex registers at locations 10-17 in page zero of any memory field. You can specify additional loading restrictions by using the FIELD directive or the LOC keyword. The form of the directive is: 7-7 RELOCATION .XSECT name or [,LOC=n] [,LEVEL=n] [,OVERLAY=n] [,ROOT] .SECT name, X where: name is a legal symbol that identifies this program section. LOC=n specifies the memory location within page zero where loading begins. The expression value n must be in the range: 10-17, and may not be complex relocatable. You cannot use this option if you use the FIELD directive. LEVEL=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay level and must be in the range 0-7. This option allows you to avoid specifying an overlay level at LINK execution time (see Section 9.1). OVERLAY=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay number and must be in the range 0-17(octal). This option allows you to avoid specifying an overlay/number at LINK execution time (see Section 9.1). ROOT specifies that this program section is the main (nonoverlay) part of the program (identical to LEVEL=0). All values in an .XSECT are .FSECT relocatable (see Section 7.1.6). The following example shows how two .RSECTs reference two one-word .XSECTs: .XSECT XA1 FIELD 0 XA1, 0 / .RSECT INIT FIELD 0 FIRST, TAD (BUFFER) DCA XA1 . . . .XSECT XA2 FIELD 0 XA2, 0 / .RSECT MOVE FIELD 0 . . 7-8 RELOCATION . TAD I XA2 SNA JMP DONE DCA I XA1 JMP .-4 . . . The routine moves data from one location to another, and when it reads a zero, jumps out of the loop. The two .XSECTs could also be combined into a single one. Both .XSECTs load somewhere between 10 and 17, inclusive, in field zero as determined by LINK. 7.1.6 .DSECT The .DSECT directive defines a relocatable program data section. .DSECTs are used to store data. They cannot be used to store instructions, because LINK does not necessarily relocate them to begin on page boundaries, and this would alter the code in unpredictable ways. Although .DSECTs may flow across page boundaries, they may not flow across field boundaries. You can specify additional loading restrictions by using the FIELD directive or the PAGE or LOC keywords. The form of the directive is: .DSECT name or [,PAGE=n] [,LOC=n] [,LEVEL=n] [,OVERLAY=n] [,ROOT] .SECT name, D where: name is a legal symbol that identifies the program section. PAGE=n specifies the memory page where loading begins. The expression value n must be in the range 0-37 and must not be complex relocatable. LOC=n specifies the memory where loading begins. LEVEL=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay level and must be in the range 0-7. This option allows you to avoid specifying an overlay level at LINK execution time (see Section 9.1). OVERLAY=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay number and must be in the range 0-17(octal). This option allows you to avoid 7-9 RELOCATION specifying an overlay/number at LINK execution time (see Section 9.1). ROOT specifies that this program section is the main (nonoverlay) part of the program (identical to LEVEL=0). NOTE Do not use the LOC or PAGE options if you use the FIELD directive. By defining blocks of data as .DSECTs, you allow LINK to combine the program sections in an efficient way. Thus, if you change the size of a table, and it no longer fits in its former location, LINK automatically finds a new spot of the right size. The following sample of code shows how you can use a .DSECT in a program: .RSECT ERROR FIELD 2 . . . TAD COUNT /Get the item number in table TAD (TABLE) /Get the table starting address DCA TPOINT /Store it in a pointer TAD I TPOINT /Now set the value at that address .DSECT FIELD 2 TABLE, ZBLOCK 100 The .DSECT can be loaded anywhere in the field without affecting its capability to store data. 7.1.7 .FSECT The .FSECT directive defines a special relocatable program section. LINK will load a program section defined by an .FSECT anywhere in memory except page 0. You can specify additional loading restrictions by using the FIELD directive or the PAGE or LOC keywords. An .FSECT may load anywhere in memory, but must be wholly contained within the page in which it loads. Thus, if a loading address is specified, it must not cause the section to flow across page boundaries. The form of the directive is: 7-10 RELOCATION .FSECT name or [,PAGE=n] [,LEVEL=n] [,OVERLAY=n] [,ROOT] .SECT name, F where: name is a legal symbol that identifies this program section. PAGE=n specifies the memory page where loading begins. The expression value n must be in the range: 0-37, and must not be complex relocatable. If n is relocatable, the program section must load into the same page as the relocatable part of n. LEVEL=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay level and must be in the range 0-7. This option allows you to avoid specifying an overlay level at LINK execution time (see Section 9.1). OVERLAY=n declares that this program section is in an overlay (see Section 10.5). The value of the expression n specifies the overlay number and must be in the range 0-17(octal). This option allows you to avoid specifying an overlay/number at LINK execution time (see Section 9.1). ROOT specifies that this program section is the main (nonoverlay) part of the program (identical to LEVEL=0). NOTE Do not use the LOC or PAGE options if you use the FIELD directive. .FSECTs contain instructions and are generally used for short subroutines or macros. Unlike .RSECTs, .FSECTs need not be loaded at the beginning of a page thus LINK will combine them onto the same page or insert them into available spaces in memory. .FSECTs are used primarily to create libraries of short subroutines. If, for example, you define each routine in a floating point math package library as an .FSECT, and then reference them in a program, LINK automatically loads only the subroutines referenced. It does not load the entire math package. This saves memory space. .FSECTs employ a special type of relocation, known as .FSECT relocation. The following example illustrates this: 7-11 RELOCATION .FSECT FPTST 0 PTST, 0 1 CLA 2 TAD A 3 SZA 4 JMP PASS1 5 JMP PASS2 6 A, 0 . . . If this program section happened to load at the beginning of a page, the TAD A instruction on line 2 would be assembled as 1206; i.e., two's complement add relative location 06 (the A) on the current page. But if the .FSECT did not load at the beginning of the page and instead loaded at location 20 on the current page, location 06 is incorrect. The address bits of the TAD A must be changed, because 1206 would address a location entirely outside the .FSECT. Consequently, in relocating an .FSECT, LINK adjusts the 7-bit address portion of a memory reference instruction by the amount of the relocation relative to the beginning of the page, 20 in this example. Thus, the TAD A would be loaded as 1226. This process is .FSECT relocation. 7.1.8 Summary of Relocation Performed by LINK Table 7-2 summarizes the relocation of different sections. Table 7-2 Summary of Program Section Relocation ------------------------------------------------------------------ | Source Code Line | ASECT | RSECT | ZSECT | |----------------------|-------------|-------------|-------------| | Absolute expression | none | none | none | | (e.g., 7777 or HLT) | | | | | | | | | | Memory reference | none | none | "FSECT" | | instruction: | | | relocation | | TAD A, where A | | | | | is on page | | | | | | | | | | 12-bit address, | abs. part + | abs. part + | abs. part + | | pointer | reloc. part | reloc. part | reloc. part | | | | | | | Simply-relocatable | abs. part + | abs. part + | abs. part + | | expression reloc. | part reloc. | part reloc. | part reloc. | ------------------------------------------------------------------ 7-12 RELOCATION Table 7-2 (Cont.) Summary of Program Section Relocation ------------------------------------------------------------------ | Source Code Line | XSECT | DSECT | FSECT | |----------------------|-------------|-------------|-------------| | Absolute expression | none | none | none | | (e.g., 7777 or HLT) | | | | | | | | | | Memory reference | "FSECT" | none | "FSECT" | | instruction: | relocation | | relocation | | TAD A, where A | | | | | is on page | | | | | | | | | | 12-bit address, | abs. part + | abs. part + | abs. part + | | pointer | reloc. part | reloc. part | reloc. part | | | | | | | Simply-relocatable | abs. part + | abs. part + | abs. part + | | expression reloc. | part reloc. | part reloc. | part reloc. | ------------------------------------------------------------------ 7.1.9 .SECT * Directive The .SECT * directive returns program assembly control to the previous program section. The directive is used in the body of a macro definition. Two SECT * directives in succession are not allowed. The form of the directive is: .SECT * This directive is particularly useful in macros that change program sections to set up data tables. For example: .MACRO DATA A,B,C .DSECT DATUM *A B TEXT "C" .SECT * .ENDM DATA When the macro expands, it changes program section to the .DSECT DATUM and then sets the current location counter to the value of A (*A). The macro stores B and the text string C and then returns to the program section (.SECT *) in which the macro was called. The program section that called the macro could be an .RSECT, as shown below. 7-13 RELOCATION .RSECT CODE TAD (20) DCA TEMP DATA 100,-5, "GOOD" HLT Note that the HLT instruction resides in relative location 2 of the .RSECT CODE, not in .DSECT DATUM. 7.2 INTER-MODULE COMMUNICATION DIRECTIVES AND SPECIAL OPERATORS The preceding sections have discussed relocatable programs that consist of only one source module. This section describes programs that contain more than one source module. When a program consists of more than one source module, you can use the following directives and special operators to control intermodule communication: o .EXTERNAL o .ZTERNAL o .GLOBAL o .SECREF o .ENTRY o CDF and CIF 7.2.1 .EXTERNAL The .EXTERNAL directive declares a symbol as being defined outside the current module. The form of the directive is: .EXTERNAL sym,... where: sym is a symbol name. If you do not explicitly declare an external symbol, MACREL generates an error message. The following examples show how you can use the .EXTERNAL directive. 7-14 RELOCATION .EXTERNAL EVAL, WPROC . . . TAD TEMP SNA JMS EVAL JMP WPROC In this example, the directive causes the program to jump to addresses EVAL and WPROC in another module. EVAL and WPROC must be labels and be declared with a .ENTRY directive, in the other module. You can also use the .EXTERNAL directive to declare a symbol referenced by an AND, TAD, ISZ, DCA, JMS or JMP instruction. For example: .EXTERNAL BUFSZE TAD I (BUFSZE) MACREL generates a current-page literal that, after linking, contains the actual memory address of the location BUFSZE (assuming you define BUFSZE and declare it as .GLOBAL in another source module). Hence, except for declaring .EXTERNAL, treat externally defined symbols the same way as symbols inside the current module. You must handle any differences in field between the two modules by using a CDF instruction or by field restricting the current section. For example: .EXTERNAL BUFSZE FIELD BUFSZE TAD I (BUFSZE) 7.2.2 .ZTERNAL The .ZTERNAL directive defines a symbol as being external and located on page zero. The form of the directive is: .ZTERNAL sym,... where: sym is a symbol name. .ZTERN is best understood when compared with the .EXTERNAL directive. For example: .EXTERNAL B TAD B 7-15 RELOCATION Here the assembler assumes that B is on a page other than zero and generates a pointer to B. NOTE This pointer is called a link. This is an on-page pointer to an off-page location, it has nothing to do with the linking function of MACREL/LINK. However, if you have a data item on page zero, do not generate a link and eliminate the advantage of having the data item on page zero. Consequently, you should use, .ZTERNAL B TAD B This instructs the assembler that B, in addition to being external, is located on page zero, so it does not generate a link unnecessarily. Again, like .EXTERNAL, the symbol must be declared as .GLOBAL and defined in another source module. Additionally, if the symbol, when defined, is not located on page zero, LINK generates an error message. An alternative way of eliminating the extraneous link is to use the following construction: .EXTERNAL B TAD Z B In this example, the special operator Z instructs MACREL that this is a page zero reference. This code performs the same function as .ZTERNAL. The .EXTERNAL directive, however, must be used, since the special operator Z itself does not declare the symbol to be external. 7.2.3 .GLOBAL and == The .GLOBAL directive declares to MACREL and LINK that a symbol defined in the current module may be referenced by other modules. The form of the directive is: .GLOBAL sym,... where: sym is a symbol name. For example: 7-16 RELOCATION .GLOBAL A1, B1 A1, 0 B1=20 The code declares A1 and B1 as global symbols and defines them as well, A1 through a label, and B1 through a direct assignment statement. You can use the double equal signs (==) as an alternate way to declare a global symbol and assign it a value. For example: CSIZE== 7 This is equivalent to the code: .GLOBAL CSIZE CSIZE=7 Only one symbol per line may be declared and assigned in this way. Declaring a symbol as .GLOBAL when it is not used in another program is permissible. (When coding the program, you might not know whether a given symbol will be used by another module or not.) If a symbol is declared as .GLOBAL, however, and is not defined in the current source module, MACREL generates an error message. In general, labels that you define as .GLOBAL should not be used as operands for JMS or JMP instructions from another module. You should use the directive .ENTRY to define these symbols. 7.2.4 .SECREF The .SECREF (secondary reference) directive defines a symbol in the same way as the .EXTERNAL directive, except that the symbol can be undefined at LINK time without causing a library search to resolve it. If LINK encounters a second reference to the symbol, it will then perform a library search for the symbol. The form of the directive is: .SECREF sym,... where: sym is a symbol name. 7.2.5 .ENTRY The .ENTRY directive defines an entry point into the current module from another module. The directive specifies the symbolic addresses 7-17 RELOCATION to which other modules can transfer program control via a JMP or JMS. The form of the directive is: .ENTRY sym,... where: sym is a symbol name. For example: .RSECT GETVAL .FIELD 0 .ENTRY GETVAL, STVAL GETVAL, 0 CLA TAD OFFSET SZA JMP I GETVAL STVAL, DCA VAL TAD (-10) . . . Here, GETVAL is an entry point for a JMS and STVAL is an entry point for a JMP. GETVAL and STVAL must be declared .EXTERNAL in the source module containing the JMP and JMS. All symbols that have been declared as .ENTRY will appear as an entry in the load map listing produced by LINK (see Section 9.5). Internally, MACREL processes .GLOBAL and .ENTRY declarations almost identically. In fact, you can use .GLOBAL declarations instead of .ENTRY declarations. However, a JMS or JMP to an overlay may not behave correctly if you use the .GLOBAL declaration. In practice, use .ENTRY for all JMS and JMP entries, and .GLOBAL for all others. 7.2.6 CDF Special Operator The CDF special operator described in Section 4.9.4 changes the data field. In programming inter-module communication, not knowing the field into which LINK will load the current section and not knowing the field of the referenced modules are often problems. You can find the field of the current section with RDF (Read Data Field) or RIF (Read Instruction Field) instructions. You can find the field of a referenced module with the CDF instruction. For instance: If you need to get data from a section named DATA1 in an unknown field use CDF DATA1 to change the data-field register to the field of that section as shown in the following example: 7-18 RELOCATION .EXTERNAL DATAl, DATA7 CDF DATA1 TAD I (DATA7) DCA TEMP CDF .FLD Here, the CDF DATA1 changes the data field to the field of DATA1 TAD I (DATA7) gets the value stored in DATA7 (a label inside the program section DATA1), DCA TEMP stores it on the current page in the current field. The CDF .FLD (change data field to the field of the current program section) returns the program to the current field. LINK performs the evaluation of the CDF. When LINK processes a program section containing CDF N where N is a simple relocatable expression, it takes the field of N and OR's it into bits 5-9 of the absolute part 6201 already generated by MACREL. 7.2.7 CIF Special Operator MACREL and LINK handle the CIF special operator in the same way that they handle the CDF special operator, except that the field of the relocatable part is ORed with 6202 instead of 6201. CDF and CIF may be combined in one expression CIF CDF N, in which case the field of N will be ORed with 6203. You can JMS to an unknown field by using a CIF. For example: .EXTERNAL IN CDF .FLD CIF IN JMS I (IN) . . . Here .EXTERNAL defines IN as being in another module. CDF .FLD sets the data field to the current field and provides a return path for the subroutine IN in the other module. CIF IN sets the instruction field to the same field as IN. (The CIF instruction is effective on the first jump instruction that follows it.) The line JMS I (IN) calls the subroutine IN with a 17-bit address (the 12-bit address plus the five field bits). The subroutine IN in another module might look like this: .RSECT ALPHA .ENTRY IN IN, 0 DCA ACTEMP TAD (CIF CDF) RDF 7-19 RELOCATION DCA EXIT CDF .FLD /Optional. See text. . /Subroutine Performs its Processing . . . EXIT, 0 JMP I IN .RSECT ALPHA names the program section and .ENTRY IN declares IN as an entry point. IN, 0 contains the return address for the JMS. DCA ACTEMP saves the value of the accumulator. TAD (CIF CDF) and the next instruction RDF load the accumulator with 6203 (combined CIF CDF), then OR's the field bits of the calling program into bits 5-9. This complete instruction sequence is deposited at location EXIT by the next line of code DCA EXIT. In this location the combined instruction is the last instruction before the subroutine returns to the calling program. The instruction CDF .FLD is necessary only if the subroutine performs some indirect AND, TAD, ISZ, or DCA instruction into its own field. The subroutine, having done all its bookkeeping, now performs its intended processing. When this is complete, it JMPs to EXIT. This sets the data field and instruction field to that of the calling program. The last instruction, JMP I IN, acts like a 17-bit jump to the location following the original call. If you wish to pass an argument to the subroutine (e.g., the address of data in a different field) add two words to the call so that the instruction sequence becomes: .EXTERNAL IN, DATA CDF.FLD CIF IN JMS I (IN) CDF DATA DATA . . . Here, the CDF DATA stores a preformed CDF instruction, with the field of DATA. The next line stores the 12-bit address of DATA. Somewhere in the subroutine, you might execute the following code to access the data: . . . TAD I IN DCA DATAF ISZ IN TAD I IN 7-20 RELOCATION DCA DATAP ISZ IN DATAF, 0 TAD I DATAP . . . DATAP, 0 . . . In this routine, the optional CDF .FLD used previously should be omitted because this code requires that the data field register be set to the field of the calling program. The TAD I IN gets the preformed CDF instruction from the calling program. DCA DATAF stores it in DATAF, where it will be executed shortly. ISZ IN increments IN to point to the next argument. TAD I IN and DCA DATAP get the next argument, the location of DATA, and store it as a pointer. ISZ IN increments IN to the correct return address when the subroutine is exited. The program then executes the preformed CDF at DATAF, thus changing the data field to that of DATA. The TAD I DATAP gets the contents of the first word of data, and processing continues. 7.3 HOW TO WRITE RELOCATABLE CODE In general, all the elements of relocatable programs have been defined. The rest is a matter of developing the effective techniques. You should first create a logical design for the program. Segments of code that perform a discrete function should reside in the same program section, or be coded as a separate source module. If you choose the latter, you should determine which symbols are to be known by more than one source module. You should define these symbols as .GLOBAL, .ENTRY, .EXTERNAL, or .ZTERNAL. Most source code typically consists of .RSECTs. If page zero code is desired, you must specify the necessary .ZSECTs and .XSECTs. Blocks of data may be defined as .DSECTs. Small subroutines should either be grouped together as .RSECTs, or specified individually as .FSECTs. If you have to reference an absolute memory location, make that reference to a label defined inside an .ASECT. In writing the actual code, make no assumptions about where LINK will load a program section. Instead specifically define any necessary linkage for fields. If one program section references another, either restrict them to the same field, or provide the necessary field change linkage (see Sections 7.2.5 and 7.2.6). If you reference page zero extensively, you should restrict .XSECTs and .ZSECTs to load into the same field as the associated .RSECT, or 7-21 RELOCATION you should restrict the .RSECT to load into the .XSECT's or .ZSECT's field. In general, use customary assembly language programming techniques with relocation. Do avoid using any construction that addresses as an absolute location, unless that location is contained within an .ASECT. Remember, LINK does not load a program section into a gap in another program section. It also does not load a program section so that it extends across field boundaries. Therefore, no program section may be larger than a field. 7-22 CHAPTER 8 USING MACREL AND KREF This chapter describes the operating procedures for the MACREL assembler and the KREF cross-reference utility program. Before running these programs, be sure that you are using OS/8 Version 3D (or a later version), and that the files MACREL.SV, MACOVR.SV, MACERR.SV, and KREF.SV reside on the system device (SYS:). If you are unfamiliar with OS/8 file specifications, refer to the appropriate section of the OS/8 Handbook. _____________ 8.1 RUNNING MACREL 8.1.1 MACREL Command String You can use either the OS/8 Keyboard Monitor R command or the OS/8 CCL command MAC (described in the OS/8 Handbook) to run the MACREL ______________ assembler. Enter the following command immediately to the right of the Keyboard Monitor's period (.) prompting symbol to begin MACREL operation: .R MACREL (RET) OS/8 responds by invoking the Command Decoder which in turn displays its asterisk (*) prompting symbol at the left margin of the terminal. Respond to the asterisk by entering a MACREL I/O specification string in the form: [binary] [,listing] [,kref]| LSD | TEXT | -------------- ANY ONE PIECE Figure 10-5 Library File Format Library files must be specified to LINK explicitly. LINK searches them for missing global symbols and entry names. LINK searches the default library LNKLIB.RB (if it exists) last to resolve any undefined symbols that remain. These files are processed after all non-library modules and then only if there are undefined symbols. Library files are searched as follows: 1. If no undefined symbols remain to be defined, LINK terminates the library. 2. LINK reads the next LSD from the library file and searches it for undefined symbols. If it can resolve any, it adds the LSD to the Global Symbol Table. 3. Because backward references are allowed, LINK searches the library file repeatedly. LINK terminates the search when a pass through the library fails to resolve any undefined symbols. This search method allows modules to appear in any order in the library file. You can significantly shorten LINK execution time if your modules have no backward references. 10.5 WRITING AND USING OVERLAYS Overlays are pieces of the program module that reside on a file structured device such as disk or DECtape. The overlay driver reads them into memory for execution as they are needed. The previous contents, of the memory where the overlay is loaded, are lost. An existing overlay is not copied back onto the device when a new overlay 10-9 ADVANCED TECHNICAL TOPICS is brought in. Thus, the overlay is always brought into memory in the same condition in which it was assembled and linked. Overlays are defined either by command string options to LINK or by MACREL's LEVEL and OVERLAY options to the program section directives. Once you have defined them, they are relatively invisible. Assuming SUBR resides in an overlay, the code: .EXTERNAL SUBR CIF SUBR JMS I (SUBR causes the program to bring in the overlay and perform the JMS to it. This is handled automatically by the overlay driver, which is a program section loaded by LINK to swap overlays in and out of the main program (see Section 10.5.3). The JMS, of course, stores the correct return address of the calling program in the entry point of the overlay. Figure 10-6 shows the overlay structure of MACREL/LINK. When using overlays, memory is divided into a main (or root) program segment (MAIN), which is always in memory, and up to seven different areas called levels. The different levels are loaded into consecutive memory areas (barring user-established loading restrictions) with MAIN starting at an address supplied by you. Thus, Level 7 (if any) normally occupies the highest area in memory. The levels are not associated with fields, and are not fixed in size. Main (implied level 0) and the other levels may be of any size. The size of each level, except MAIN, is the size of the largest overlay for that level, but cannot be larger than one field. For each level, you can define up to 16 (decimal) overlays. Only one of these overlays may be in memory at a given time. Notice that a given overlay has both a level number and an overlay number. A given overlay will only be used at the level for which it is defined. Thus, a Level 3 overlay will not be used in a Level 4 memory area. The code however, may be loaded twice, once as Level 3 and once as Level 4, as long as there are no conflicting GLOBAL or ENTRY addresses. Further, if you are going to use LINK's command string options to do this, two copies of the code must exist and be in separate modules. If instead you use the OVERLAY and LEVEL options of the program section directives, the separate copies and modules are not necessary. 10.5.1 Writing Overlay Code In writing overlays, you must define all entry points in the called overlay as .ENTRY and in the calling overlay (or main program) as .EXTERNAL. You should use the CIF/CDF instruction (see Sections 7.2.5 and 7.2.6) to change the fields of the calling and called overlays. 10-10 ADVANCED TECHNICAL TOPICS ---------------- | OVERLAY 17 | ---------------- | | OVERLAY 17 | | ---------------- | | | OVERLAY 17 | | | ---------------- | | | | OVERLAY 17 | | | | ---------------- | | | | | OVERLAY 17 | | | | | ---------------- | | | | | | OVERLAY 17 | | | | | | ---------------- | | | | | | | OVERLAY 17 | | | | | | | |--------------| | | | | | | | OVERLAY 16 | | | | | | | |--------------| | | | | | | | OVERLAY 15 | | | | | | | |--------------| | | | | | | | . | | | | | | | | . | | | | | | | | . | | | | | | | |--------------| | | | | | | | OVERLAY 10 | | | | | | | ----------------- |--------------| | | | | | | | LEVEL 7 | HIGH MEMORY | OVERLAY 7 | | | | | | | |---------------| |--------------| | | | | | | | LEVEL 6 | | OVERLAY 6 | | | | | | | LEVEL 7 |---------------| |--------------| | | | | |-- | LEVEL 5 | | OVERLAY 5 | | | | | | LEVEL 6 |---------------| |--------------| | | | |-- | LEVEL 4 | | OVERLAY 4 | | | | | LEVEL 5 |---------------| |--------------| | | |-- | LEVEL 3 | | OVERLAY 3 | | | | LEVEL 4 |---------------| |--------------| | |-- | LEVEL 2 | | OVERLAY 2 | | | LEVEL 3 |---------------| |--------------| |-- | LEVEL 1 | | OVERLAY 1 | | LEVEL 2 |---------------| |--------------|-- | MAIN | LOW MEMORY | OVERLAY 0 | LEVEL 1 ----------------- ---------------- INTERNAL MEMORY EXTERNAL STORAGE Figure 10-6 MACREL/LINK Overlay Structure (numbers in octal) The restrictions on calling overlays are illustrated in Figure 10-7. JMS's are allowed in either direction between MAIN and any overlay. Any overlay may call any other overlay having a higher level number. However, an overlay may not call an overlay with a lower level number. For example, an overlay at Level 7 cannot call any other overlay, it can only call the main program. 10-11 ADVANCED TECHNICAL TOPICS ALLOWED NOT ALLOWED ------------------- | LEVEL 7 | |-----------------| --------| |---- | --->| LEVEL 6 | | | | |-----------------| | | | | LEVEL 5 |<--- | | |-----------------| | ----| | | --->| LEVEL 4 |---- | | |-----------------| | | ----| LEVEL 3 | | | |-----------------| | | --->| LEVEL 2 | | | | |-----------------| | | | | LEVEL 1 |<--- | | |-----------------| | ----| | ------->| MAIN | ------------------- Figure 10-7 Permissible JMS's Between MAIN and Overlays These restrictions protect the return path to the calling level. If any overlay could call any other overlay, there is a strong likelihood that some of the return locations would be overwritten producing erratic results when the program is run. Since you may not know the memory field or level of a particular routine in an overlay structure, you should adhere to the following rules for communicating between overlays. 1. Do not use CDF, TAD, ISZ, DCA, or AND with a symbolic argument that is defined as an entry point (.ENTRY directive). 2. Do use CDF, TAD, ISZ, DCA, and AND only with a symbolic argument, that is, a program section name or a global symbol (.GLOBAL directive). 3. Do use CIF, JMP, or JMS only with a symbolic argument that is defined as an entry point. Do not use program section names or global symbols. The following example shows a generalized coding sequence that guarantees access to an overlay that is not in memory. 10-12 ADVANCED TECHNICAL TOPICS "MAIN" or Other Overlay Overlay 5, Level 3 .EXTERNAL SUBR .ENTRY SUBR CDF .FLD SUBR 0 CIF SUBR . JMS I (SUBR . . . . . other code JMP I SUBR . . . . CDF TABLE accesses a . TAD I (TABLE table once TABLE, val1 overlay is val2 in memory. val3 . . You should fully debug your code as MAIN before placing it in an overlay. This is because the OS/8 octal debugging program (ODT) does not allow you to put breakpoints in overlays, thus making debugging in an overlay system very difficult. Other than these restrictions, there is no difference between writing overlays and writing other subroutines. 10.5.2 How Overlays Work When you perform a JMS to an entry point in a module that has been defined as an overlay, the JMS is not to the module directly but to a table called the transfer vector table in the overlay driver. Each transfer vector in the table (corresponding to one entry in one overlay) consists of four words, as shown in Figure 10-8. ------------------------------------- WORD 1 | ISZ "FLAG" | |-----------------------------------| WORD 2 | JMS I "POINTER" | |-----------------------------------| | |2 4|5 8|9 11| |-----------------------------------| WORD 3 | | LEVEL | OVERLAY NO. | FIELD | |-----------------------------------| WORD 4 | MEMORY ADDRESS FOR THAT ENTRY | ------------------------------------- Figure 10-8 Transfer Vector Table For example, if you code a JMS to an entry labelled IN in another module, the actual JMS will be to word 1 of the transfer vector for 10-13 ADVANCED TECHNICAL TOPICS that particular entry. This stores the return address in word one and performs the following instruction: JMS I 'POINTER'. This instruction causes the program to jump to the overlay driver. The driver picks up the following word containing the overlay level, overlay number, and field and checks to see if that overlay is in core. If it is not, the overlay driver brings it in. The overlay driver then stores the correct return address at the entry point and performs a JMP to the entry point plus one. The exit from the overlay is made, without going through the transfer vector again. If you write a JMP, the ISZ 'FLAG' instruction is executed. This sets a flag that tells the overlay driver to perform a JMP instead of a JMS. Control then returns to the address of the entry point, instead of the entry point address plus one. In practice, this is handled automatically and is invisible to you. You code JMS I (IN) and execution begins at the code starting at IN as if the module had always been in memory. 10.5.3 Overlay Driver The overlay driver module (OVRDRV.MA Version 2A) is a program that you must LINK into your program, if you are using LINK's overlay feature. It is supplied as source module so that, if desired, you can modify the size of the transfer vector table (designated TRANVC in the module). There will be a 4-word entry in the table for every .ENTRY specified in your program that is not in level 0. Initially the TRANVC table is set up to hold 24 (decimal) vectors but you can increase the table size to hold 511 (decimal) vectors which is the maximum supported by LINK. If your program requires more than twenty-four vectors, LINK will automatically increase the size of the table (up to 511) as required. 10.6 SAVE FILE FORMAT The save file (.SV extension) is LINK's primary output file. It begins with the Memory Control Block illustrated in Figure 10-9. 10-14 ADVANCED TECHNICAL TOPICS Location Contents Notes MEMORY CONTROL BLOCK --------------------------------------- 0 | MINUS THE NUMBER OF MEMORY SEGMENTS | |-------------------------------------| 62N3 WHERE N IS THE 1 | CDF CIF (STARTING FIELD) |<-- STARTING FIELD |-------------------------------------| 2 | STARTING ADDRESS | |-------------------------------------| 3 | JOB STATUS WORD | |-------------------------------------|--- 4 | | | MEMORY SEGMENT |-------------------------------------| |CONTROL DOUBLE WORDS 95 | | | |-------------------------------------|--- 96 | | OVERLAY STORAGE | | INFORMATION |-------------------------------------| 127 | | ~ ~ REMAINDER OF BLOCK 377 | | IS UNUSED (8) --------------------------------------- Figure 10-9 Memory Control Block The Memory Control Block consists of 256 words and has the following format: Word Contents ____ ________ 0 Two's complement number of memory segments 1 Starting Field 2 Starting Address 3 Job Status Word 4- 95 Memory Segment Control Double Words 96-127 Overlay storage information 128-255 Empty The format of the Job Status Word (word 3) is as follows: Bit Condition Meaning _____________ _______ Bit 0 = 1 File does not load into locations 0 to 1777 in field 0. Bit 1 = 1 File does not load into locations 0 to 1777 in field 1. Bit 2 = 1 Program must be reloaded before it can be restarted. Bit 3 = 1 Program never uses above 8K. This is used when BATCH processing is active. Bit 4 = 1 Program contains overlays created by LINK. 10-15 ADVANCED TECHNICAL TOPICS Bit 10 = 1 Locations 0 to 1777 in field 0 need not be preserved when the Command Decoder is called. Bit 11 = 1 Locations 0 to 1777 in field 1 need not be preserved when the USR is called. If the object module is overlayed, LINK will automatically set bit 4 (0200) of the object module's Job Status Word to indicate the presence of overlays to system software. The Memory Segment Doublewords (words 4-95) control the reading and writing of the associated areas of memory. The format of each entry is shown in Figure 10-10: Location Contents Notes ------------------------------------------- 1 | MEMORY ORIGIN | MULTIPLE OF 400(8) |-----------------------------------------| | | NUMBER OF PAGES | FIELD | | BITS 0 AND 9-11 2 | | TO LOAD | TO LOAD | | ARE ZERO ------------------------------------------- 0 1 5 6 8 9 11 Figure 10-10 Memory Segment Double Words The memory loading address must be a multiple of 400 (octal). The Memory Segment Control Doublewords are sorted within the header block in order of decreasing field and increasing origin within the same field. There can be no more than 31 (decimal) Memory Segment Control Doublewords in any Memory Control Block. The Memory Control Block for the program at the time it is loaded into memory is always saved in words 200 (octal) through 377 (octal) of block 37 (octal) (one of the system scratch blocks) on the system device. There are no memory segment double words for overlays, because they are loaded at run time not load time. The overlay storage information (words 96-127) has a 4 word entry for each level including level 0 (MAIN). The format is shown in Figure 10-11: ---------------------------------- WORD 1 | NO. OF OVERLAYS IN LEVEL | |--------------------------------| 2 |0 4| |6 8| | | ADDRESS | | FLD | | |--------------------------------| 3 | RELATIVE STARTING BLOCK | |--------------------------------| 4 | LENGTH (IN PAGES) | ---------------------------------- Figure 10-11 Overlay Storage 10-16 ADVANCED TECHNICAL TOPICS 10.7 MACRO LIBRARY Commonly used macros may be called by any source module if their definitions reside in a macro library file on DSK:. The following paragraphs describe how you can create this library file. Create a file on DSK:, called MACLIB.MA, with the following code. .IF NDF .MCALL < .MACRO .MCALL A,B,C,D,E,F,G,H XLIST .IF NB A <$A=1> /conditional assembly that concatenates a .IF NB B <$B=1> /dollar sign($) with the name of your macro .IF NB C <$C=l> /passed as an actual argument to .MCALL. Your .IF NB D <$D=1> /macro name passed with the call to .MCALL is .IF NB E <$E=1> /thus defined and satisfies the conditional .IF NB F <$F=1> /assembly (.IF DF) which is Part of Your .IF NB G <$G=1> /macro definition, .IF NB H <$H=1> .INCLUDE MACLIB.MA XLIST .ENDM .MCALL > . . . .IF DF $YOUR0< .MACRO YOUR0 A,B,...H . . . .ENDM YOUR0 /YOUR0 through YOURnn, are the names of the EXPUNGE $YOUR0> /macro YOU define. UP to eight macros can be .IF DF $YOUR1< /defined with each .MCALL .MACRO YOUR1 A,B,...H . . . .ENDM YOUR1 EXPUNGE $YOUR1> . . . .IF DF $YOURnn< .MACRO YOURnn A,B,...H . . . .ENDM YOURnn EXPUNGE $YOURnn > 10-17 ADVANCED TECHNICAL TOPICS The source module, which is to use one or more of the macros in the library, must include the following code near its beginning: .NOLIST LN /do not list xlisted lines XLIST /turn listing off .INCLUDE MACLIB.MA /define the macro .MCALL which is /contained in MACLIB.MA XLIST /turn listing back on .MCALL YOUR0,YOUR1....YOUR7 /call .MCALL and selectively define /macros in MACLIB.MA The .INCLUDE MACLIB.MA causes the file MACLIB.MA to be read. Because .MCALL is, at this point undefined, the macro is processed and .MCALL is now defined. To define macros in the library, call the macro .MCALL with the names of your macros as arguments. For each macro named, .MCALL creates a symbol with the macro name preceded by a dollar sign ($). Thus, .MCALL YOUR creates the symbol $YOUR. Each macro definition in MACLIB.MA is surrounded by a conditional test that determines whether a symbol (the concatenation of $ and YOUR) is defined. If defined, the condition is satisfied, and the macro is defined, then the created symbol is expunged from the symbol table. 10.8 SETTING THE CURRENT LOCATION COUNTER TO AN UNKNOWN VALUE The Asterisk (*) directive (described in Section 5.4.1), unlike its counterpart in the PAL8 assembler, allows you to set the current location counter to a value that is not known at assembly time. This can be a value that is either an external symbol or a complex relocatable expression. This feature permits you to modify data values in a table that exists in another assembly module. You must specify any symbol (external or internal), whether used by itself or in a complex relocatable expression, as an absolute offset from the beginning of the program section in which it resides. There are two ways to do this: 1. Specify the symbol as a global symbol with an absolute value. For example: Module 1 Module 2 TAB1==10 .EXTERNAL TAB1 .DSECT TABLE .DSECT TABLE TAB, ZBLOCK 10 *TAB1 ZBLOCK 20 . . . . . 2. Specify the symbol as a relocatable value and calculate the absolute offset of the symbol from the beginning of the 10-18 ADVANCED TECHNICAL TOPICS program section by subtracting the relocatable part of the symbol from its absolute part. For example: Module 1 Module 2 .DSECT TABLE .EXTERNAL TAB1 .GLOBAL TAB1 .DSECT TABLE TAB, ZBLOCK 10 *TAB1-TABLE TAB1, ZBLOCK 20 . . . . . During pass 1 LINK resolves all relocatable symbols to their absolute values. During pass 2, LINK creates the save image and loads the code. In the first example, if LINK begins the .DSECT TABLE at 2000, it assigns TABLE the value 2000. TAB1 already has the value 10 that was calculated by MACREL. When LINK encounters *TAB1, it calculates the absolute address of TAB1 by adding the value of TAB1 (10) to the value of TABLE (2000), giving the result 2010. In the second example, if LINK begins the .DSECT TABLE at 2000, it assigns TABLE the value 2000 and TAB1 the value 2010 (2000 plus the offset 10). When LINK encounters the expression *TAB1-TABLE during pass 2, it calculates the absolute value of TAB1 as follows: 1. It subtracts the value of TABLE (2000) from TAB1 (2010) to obtain the absolute offset of TAB1 (10) from the beginning of the program section. 2. It then adds the calculated absolute offset value of TAB1 (10) to the value of TABLE (2000) to obtain the absolute value of TAB1 (2010). Note that if the example did not use the expression TAB1-TABLE, LINK would calculate the value of TAB1 incorrectly as 4010 (that is, value of TAB1 (2010) plus TABLE (2000)). Program sections that use the Asterisk (*) directive in this way must not contain memory reference instructions, labels, or the period (.) special operator. MACREL performs the following operations: 1. MACREL generates codes to LINK that instruct it to begin loading at the address specified by the directive. 2. It proceeds with assembly using this value until it finds another Asterisk directive that has a known value for an argument. For each unknown value, MACREL prints ???? in the current location counter value column of the assembly listing. 3. MACREL outputs codes to LINK that instruct it to compute where the subsequent data items are to be loaded. 10-19 ADVANCED TECHNICAL TOPICS You must specify the actual length of the program section at LINK execution time by including an identically named program section definition that specifies the actual length of all the pieces of the entire section as shown in the previous examples (Module 1). 10-20 APPENDIX A ASCII CHARACTER SET Table A-1 ASCII Character Set ---------------------------------------------------------------------- | 7-bit | | | | Octal | | | | Code | Character | Remarks | |--------------------------------------------------------------------| | 000 | NUL | Null, tape feed, CONTROL/SHIFT/P. | | 001 | SOH | Start of heading; also SOM, start | | | | of message, CONTROL/A. | | 002 | STX | Start of text; also EOA, end of | | | | address, CONTROL/B. | | 003 | ETX | End of text; also EOM, end of | | | | message, CONTROL/C. | | 004 | EOT | End of transmission (END); shuts | | | | off TWX machines, CONTROL/D. | | 005 | ENQ | Enquiry (ENQRY); also WRU, | | | | CONTROL/E. | | 006 | ACK | Acknowledge; also RU, CONTROL/F. | | 007 | BEL | Rings the bell. CONTROL/G. | | 010 | BS | Backspace; also FEO, format | | | | effector; backspaces some | | | | machines, CONTROL/H. | | 011 | HT | Horizontal tab. CONTROL/I. | | 012 | LF | Line feed or Line space (new line); | | | | advances paper to next line, | | | | duplicated by CONTROL/J. | | 013 | VT | Vertical tab (VTAB). CONTROL/K. | | 014 | FF | Form Feed to top of next page | | | | (PAGE). CONTROL/L. | | 015 | CR | Carriage return to beginning of | | | | line; duplicated by CONTROL/M. | | 016 | SO | Shift out; changes ribbon color to | | | | red. CONTROL/N. | | 017 | SI | Shift in; changes ribbon color to | | | | black. CONTROL/D. | | 020 | DLE | Data link escape. CONTROL/B (DC0). | | 021 | DC1 | Device control 1, turns transmitter | | | | (READER) on, CONTROL/Q (X ON). | | 022 | DC2 | Device control 2, turns punch or | | | | auxiliary on. CONTROL/R (TAPE, AUX | | | | ON). | ---------------------------------------------------------------------- (continued on next page) A-1 ASCII CHARACTER SET Table A-1 (Cont.) ASCII Character Set ---------------------------------------------------------------------- | 7-bit | | | | Octal | | | | Code | Character | Remarks | |--------------------------------------------------------------------| | 023 | DC3 | Device control 3, turns transmitter | | | | (READER) off, CONTROL/S (X OFF). | | 024 | DC4 | Device control 4, turns punch or | | | | auxiliary off. CONTROL/T (AUX | | | | OFF). | | 025 | NAK | Negative acknowledge; also ERR, | | | | ERROR. CONTROL/U. | | 026 | SYN | Synchronous file (SYNC). CONTROL/V. | | 027 | ETB | End of transmission block; also | | | | LEM, logical end of medium. | | | | CONTROL/W. | | 030 | CAN | Cancel (CANCL). CONTROL/X. | | 031 | EM | End of medium. CONTROL/Y. | | 032 | SUB | Substitute. CONTROL/Z. | | 033 | ESC | Escape. CONTROL/SHIFT/K. | | 034 | FS | File separator. CONTROL/SHIFT/L. | | 035 | GS | Group separator. CONTROL/SHIFT/M. | | 036 | RS | Record separator. CONTROL/SHIFT/N. | | 037 | US | Unit separator. CONTROL/SHIFT/O. | | 040 | SP | Space. | | 041 | ! | | | 042 | " | | | 043 | # | | | 044 | $ | | | 045 | % | | | 046 | & | | | 047 | ' | Accent acute or apostrophe. | | 050 | ( | | | 051 | ) | | | 052 | * | | | 053 | + | | | 054 | , | | | 055 | - | | | 056 | . | | | 057 | / | | | 060 | 0 | | | 061 | 1 | | | 062 | 2 | | | 063 | 3 | | | 064 | 4 | | | 065 | 5 | | | 066 | 6 | | | 067 | 7 | | | 070 | 8 | | ---------------------------------------------------------------------- (continued on next page) A-2 ASCII CHARACTER SET Table A-1 (Cont.) ASCII Character Set ---------------------------------------------------------------------- | 7-bit | | | | Octal | | | | Code | Character | Remarks | |--------------------------------------------------------------------| | 071 | 9 | | | 072 | : | | | 073 | ; | | | 074 | < | | | 075 | = | | | 076 | > | | | 077 | ? | | | 100 | @ | | | 101 | A | | | 102 | B | | | 103 | C | | | 104 | D | | | 105 | E | | | 106 | F | | | 107 | G | | | 110 | H | | | 111 | I | | | 112 | J | | | 113 | K | | | 114 | L | | | 115 | M | | | 116 | N | | | 117 | O | | | 120 | P | | | 121 | Q | | | 122 | R | | | 123 | S | | | 124 | T | | | 125 | U | | | 126 | V | | | 127 | W | | | 130 | X | | | 131 | Y | | | 132 | Z | | | 133 | [ | SHIFT/K. | | 134 | \ | SHIFT/L. | | 135 | ] | SHIFT/M. | | 136 | ^ | * | | 137 | _ | ** | | 140 | ` | Accent grave. | | 141 | a | | | 142 | b | | | 143 | c | | | 144 | d | | ---------------------------------------------------------------------- (continued on next page) A-3 ASCII CHARACTER SET Table A-1 (Cont.) ASCII Character Set ---------------------------------------------------------------------- | 7-bit | | | | Octal | | | | Code | Character | Remarks | |--------------------------------------------------------------------| | 145 | e | | | 146 | f | | | 147 | g | | | 150 | h | | | 151 | i | | | 152 | j | | | 153 | k | | | 154 | l | | | 155 | m | | | 156 | n | | | 157 | o | | | 160 | P | | | 161 | q | | | 162 | r | | | 163 | s | | | 164 | t | | | 165 | u | | | 166 | v | | | 167 | w | | | 170 | x | | | 171 | y | | | 172 | z | | | 173 | { | | | 174 | | | | | 175 | } | This code generated by ALTMODE | | 176 | ~ | This code generated by PREFIX key if present | | | | | | 177 | DEL | DELETE, RUBOUT. | ---------------------------------------------------------------------- * ^ appears as +on some machines. ** _ (underscore) appears as <- on some machines. A-4 APPENDIX B MACREL-PAL8 COMPATIBILITY SUMMARY PAL8 Features Incompatible with MACREL: o Dollar Sign ($) is treated differently. o DTORG is not implemented. o MACREL does not remember current page literals if you set the current location counter to an off page address and back. o No special terminal support (listing assumes output device supports tab and form feed). o Right parenthesis ()) is not ignored. This ends current page literal. o Right square bracket (]) is not ignored. This ends page zero literal. o No /B or /F switches. These are replaced by .ENABLE conditions. o No /D switch. o No /H switch. o No /X switch (unnecessary). o No /T switch. o CIF and CDF will behave differently if used in unusual circumstances; for example, CDF+A or TAD CDF may assemble differently under MACREL. o A program section cannot contain 4096 words of code. B-1 MACREL-PAL8 COMPATIBILITY SUMMARY MACREL Features Incompatible with PAL8: The following directives are incompatible with PAL8. .ASECT .LEVEL .CHAIN .LIST .DISABL .LISTWD .DSECT .MACRO EDF .MEXIT .ENABLE .NARGS .ENABWD .NCHAR .ENDM .NOLIST .ENDR .POP .ENTRY .PUSH EXPUNGE .RADIX .EXTERNAL .REPT .FLD .RSECT .FSECT .SBTTL .GLOBAL .SECT .IF .SECT * .INCLUDE .START .JSW .TITLE .VERSION .ZSECT .XSECT .ZTERNAL The following features are incompatible with PAL8. Local Symbols Dot (as radix override) Uparrow B Dot and dollar sign in symbols Uparrow D Keyword PAGE and LOC Uparrow O Double equal sign KREF The following control options are incompatible with PAL8. /A /M /Q /X /B /O /R = nnn /L /P /Z Overlays, LINK libraries, and all LINK control options are incompatible with PAL8 and ABSLDR. B-2 APPENDIX C MACREL PERMANENT SYMBOL TABLE Mnemonic Octal Symbol Code Operation ________ _____ _________ Memory Reference Instructions AND Y 0000 Logical AND between Y and AC TAD Y 1000 Two's complement Add Y to AC ISZ Y 2000 Increment Y and skip if zero DCA Y 3000 Deposit at Y and clear AC JMS Y 4000 Jump to subroutine at Y JMP Y 5000 Jump to Y Operate Microinstructions NOP 7000 No operation. Causes a 1 cycle program delay. IAC 7001 Increment AC. The content of the AC is incremented by one in two's complement arithmetic. RAL 7004 Rotate AC and L left. The con- tent of the AC and the L are rotated left one place. RTL 7006 Rotate two places to the left. Equivalent to two successive RAL operations. RAR 7010 Rotate AC and L right. The con- tent of the AC and L are rotated right one place. RTR 7012 Rotate two places to the right. Equivalent to two successive RAR operations. CML 7020 Complement L. C-1 MACREL PERMANENT SYMBOL TABLE Mnemonic Octal Symbol Code Operation ________ _____ _________ CMA 7040 Complement AC. The content of the AC is set to the one's com- plement of its current content. CIA 7041 Complement and increment ac- cumulator. Used to form two's complement. CLL 7100 Clear L. STL 7120 Set link. The L is set to contain a binary 1. CLA 7200 Clear AC. To be used alone or in OPR 1 combinations. STA 7240 Set AC to -1 (7777) HLT 7402 Halt. Stops the program after completion of the cycle in process. If this instruction is com- bined with others in the OPR 2 group, the other operations are completed before the end of the cycle. OSR 7404 OR with switch register. The OR function is performed between the content of the SR and the content of the AC, with the re- sult left in the AC. SKP 7410 Skip, unconditional. The next in- struction is skipped. SNL 7420 Skip if L is not = 0. SZL 7430 Skip if L = 0. SZA 7440 Skip if AC = 0. SNA 7450 Skip if AC is not = 0. SMA 7500 Skip on minus AC. If the content of the AC is a negative number, the next instruction is skipped. SPA 7510 Skip on positive AC. If the con- tent of the AC is a positive num- ber, including zero, the next in- struction is skipped. C-2 MACREL PERMANENT SYMBOL TABLE Mnemonic Octal Symbol Code Operation ________ _____ _________ LAS 7604 Load AC with SR. Programmed Data Transfer Instructions ION 6001 Turn on interrupt. IOF 6002 Turn off interrupt. Teletype Keyboard/Reader KSF 6031 Skip on keyboard flag. KCC 6032 Clear keyboard flag, and AC, advance reader. KRS 6034 Read keyboard buffer static. KRB 6036 Read keyboard buffer, clear flag. Teletype Teleprinter/Punch TSF 6041 Skip on teleprinter flag. TCF 6042 Clear teleprinter flag. TPC 6044 Load teleprinter and print. TLS 6046 Load teleprinter flag. Memory Extension CDF 62N1 Change to data field n (n=0 to 7). CIF 62N2 Change to instruction field N (N=0 to 7). RDF 6214 Read data field. RIF 6224 Read instruction field. RIB 6234 Read interrupt buffer. RMF 6244 Restore memory field. Extended Arithmetic Element SCA 7441 Step counter "OR" with AC. SCL 7403 Step counter load from memory. MUY 7405 Multiply. C-3 MACREL PERMANENT SYMBOL TABLE Mnemonic Octal Symbol Code Operation ________ _____ _________ DVI 7407 Divide. NMI 7411 Normalize. SHL 7413 Shift left. ASR 7415 Arithmetic shift right. LSR 7417 Logical shift right. The eight permanent symbols used with the EAE are added to MACREL's Permanent Symbol Table by the /Q command string option. Permanent symbols shown below are included in MACREL's Permanent Symbol Table. All of these permanent symbols are used in newer models of the PDP8 including PDP8/A, /E, /F, /M. For older models of the PDP8, they can be deleted from the Permanent Symbol Table by the /A command string option. Additional Microinstructions BSW 7002 Byte swap. MQL 7421 Load multiplier quotient. MQA 7501 Multiplier quotient OR into accumulator. SWP 7521 Swap accumulator and multiplier quotient. CAM 7621 Clear accumulator and multiplier quotient (CLA MQL). ACL 7701 Clear accumulator, load multiplier. Programmed Data Transfer Instructions SKON 6000 Skip if interrupt on, IOF. SRQ 6003 Skip if interrupt request. GTF 6004 Get flags. RTF 6005 Restore flag, ION. SGT 6006 Skip if "greater than" flag is set. CAF 6007 Clear all flags. C-4 MACREL PERMANENT SYMBOL TABLE Mnemonic Octal Symbol Code Operation ________ _____ _________ Reader/Punch Instructions RPE 6010 Set reader/punch interrupt enable. RSF 6011 Skip on reader flag. RRB 6012 Read reader buffer. RFC 6014 Reader fetch character. PCE 6020 Clear reader/punch interrupt enable. PSF 6021 Skip on punch flag. PCF 6022 Clear punch flag. PPC 6024 Load punch buffer and punch character. PLS 6026 Load punch buffer sequence. Teletype Keyboard/Reader Instructions KCF 6030 Clear keyboard flag. KIE 6035 Set/clear interrupt enable. Teletype Teleprinter/Punch Instructions TFL 6040 Set teleprinter flag. TSK 6045 Skip on printer or keyboard flag. SPF 6040 Set teleprinter flag. SPI 6045 Skip on printer or keyboard flag. All of the MACREL directives are included in the Permanent Symbol Table. These directives are listed below. .CHAIN .LISTWD DEVICE .MACRO .DISABLE .MEXIT EDF .NARGS EJECT .NCHAR .ENABLE .NOLIST .ENABWD PAGE .ENTRY .POP EXPUNGE .PUSH .EXTERNAL .RADIX FIELD .RELOC C-5 MACREL PERMANENT SYMBOL TABLE Mnemonic Octal Symbol Code Operation ________ _____ _________ FILENAME .REPT FIXMRI .SBTTL FIXTAB .SECT .FLD .TITLE .GLOBAL TEXT I XLIST .IF Z .INCLUDE ZBLOCK .LEVEL .ZTERNAL There are 19 MACREL directives that you can eliminate from the Symbol Table with the /R command string option. The use of this option restricts the flexibility of MACREL but does not eliminate its MACRO features. These redundant symbols are listed below. .ASECT DECIMA .DSECT ENPUNCH .FSECT IFDEF IFNDEF IFNZRO IFZERO .JSW .LIST NOPUNCH OCTAL PAUSE .RSECT .START .VERSION .XSECT .ZSECT The following additional symbols are deleted by the /R option: GLK 7204 IOT 6000 OPR 7000 C-6 APPENDIX D MACREL DIAGNOSTIC ERROR MESSAGES BE - INTERNAL STACK OVERFLOW (passes 1 and 2) BE - INTERNAL STACK UNDERFLOW (passes 1 and 2) DF - NO ROOM FOR OUTPUT Meaning: The output device became filled up. (passes 1 and 2) Action: The output file is closed. Assembly continues as if end of input file was encountered. DV - DIVIDE BY 0 FA - FATAL MACRO ERROR (passes 1 and 2) IC - BAD CHARACTER WHILE LOOKING FOR TASK NAME (pass 1) IC - BAD CHAR, "x", AFTER ^ Meaning: An invalid character occurred after an up-arrow. The only characters which may follow an up-arrow in an expression are ", O, D, and R. (pass 1) Action: The up-arrow is ignored. IC - BAD SUBSTRING? IC - CAN'T PERFORM INCLUDE CHARACTER ? AFTER LOGICAL END OF PSEUDO-OP IC - CHARACTER "x" AFTER LOGICAL END OF DIRECTIVE Meaning: The assembler found a legal directive on this line. After the assembler found the directive to be completed, it encountered the extraneous character "x" on the line. (pass 1) Action: The extra character is ignored. IC - EXTRA CHARS AFTER INCLUDE D-1 MACREL DIAGNOSTIC ERROR MESSAGES IC - EXTRA RIGHT ANGLE BRACKET IGNORED Meaning: A right angle bracket (>) was encountered with no matching left angle bracket (<). (pass 1) Action: The right angle bracket character is ignored and the assembly continues. IC - EXTRANEOUS CHARACTER ? AFTER END OF MACRO DIRECTIVE, MACRO # IC - ILLEGAL CHARACTER IC - ILLEGAL CHARACTER IN EXPUNGE IC - ILLEGAL CHARACTER IN FIXTAB IC - ILLEGAL CHARACTER ? IN .PUSH IC - ILLEGAL CHARACTER "x" AFTER INCLUDE Meaning: One or more characters (x) occurred after an .INCLUDE directive but before the end of that statement. (pass 1) Action: The offending characters are ignored. IC - MISSING ANGLE BRACKET IN TEXT Meaning: Within a TEXT directive, a sub-item was begun that started with a left angle bracket (<), however, no matching right angle bracket (>) was found. (pass 1) Action: The directive is aborted. IC - MISSING = AFTER FIXMRI Meaning: No equal sign was found after the symbol following the word FIXMRI in a FIXMRI directive. The FIXMRI directive must have the form: FIXMRI symbol=expression There may be spaces or tabs separating the 4 parts of this directive. (pass 1) Action: The character which was not an equal sign is ignored, and the scan continues to look for an equal sign. IC - MISSING = AFTER KEYWORD IC - NO DIGIT AFTER D, ^O, OR ^B D-2 MACREL DIAGNOSTIC ERROR MESSAGES IC - NO MATCHING CLOSE ANGLE BRACKET (ONE ASSUMED) Meaning: While parsing an expression, a subexpression was encountered that began with a left angle bracket (<). The expression scan ended upon encountering a character that is not legal within an expression and this character was not a right (close) angle bracket (>). (pass 1) Action: MACREL assumes that a right angle bracket was omitted and the parse continues. IC - NO MATCHING > IC - NON-ALPHABETIC WHILE LOOKING FOR SYMBOL Meaning: A non-alphabetic character was encountered after a FIXMRI directive. The argument to the FIXMRI directive must begin with a valid symbol. (pass 1) Action: The directive is aborted. IC - UNEXPECTED CHARACTER "x" WHILE LOOKING FOR EXPRESSION Meaning: The character "x" was encountered while the assembler was looking for an expression. This is not a legal character which can appear at this place in the expression. (pass 1) Action: The character is ignored. IC - UNPRINTABLE CHARACTER BOUNDING TEXT MESSAGE Meaning: A non-printing character (other than space or tab) was encountered as the delimiting character within a TEXT directive. The octal ASCII representation for this character is nnnn. (pass 1) Action: The character is ignored and the scan continues to look for a proper delimiter. IC - $ NOT ALLOWED IN DEVICE OR FILENAME Meaning: A dollar sign ($) character appeared within the name argument or a DEVICE or FILENAME directive. (pass 1) Action: The character is ignored. ID - MACRO name ALREADY IN USE Meaning: The name of a macro in a .MACRO directive already exists, but not as macro. If this is desired, the previous name should have first been EXPUNGEd. (pass 1) Action: The symbol is redefined to be a macro. Unpredictable results may occur. D-3 MACREL DIAGNOSTIC ERROR MESSAGES ID - REDEFINED TAG, name Meaning: A symbol was defined by using it as a tag (label) and it had a prior value that is different from the current value. (pass 1) Action: The symbol is given the new value and assembly continues. IO - CAN'T DO INCLUDE FROM NON-FILE-STRUCTURED DEVICE IO - CHAIN ERROR (passes 1 and 2) IO - DEVICE # DOES NOT EXIST IO - ENTER ERROR (passes 1 and 2) IO - ERROR CLOSING FILE (passes 1 and 2) IO - ERROR FETCHING HANDLER (passes 1 and 2) IO - ERROR LOADING HANDLER (passes 1 and 2) IO - ERROR READING FILE (passes 1 and 2) IO - INPUT ERROR (passes 1 and 2) IO - OUTPUT ERROR (passes 1 and 2) IO - OVERLAY BAD Meaning: MACREL attempted to read in an overlay and either an I/O error was encountered while trying to read the file, or the file was successfully read but contained bad contents, i.e. was an invalid core image. (passes 1 and 2) Action: The pass is aborted. D-4 MACREL DIAGNOSTIC ERROR MESSAGES IP - BAD TYPE OF SYMBOL Meaning: A symbol was encountered in an expression which had an erroneous type. For example, it was a macro name or the name of a system directive. (pass 1) Example: TAD PAGE Action: The value of the symbol is treated as an absolute 0. IR - ILLEGAL REFERENCE LG - LINK GENERATED Meaning: The user specified that the assembler is not to generate links. (pass 1) Action: A link is generated anyhow. The program will probably run. ME - MEXIT WHILE NOT IN MACRO NE - BAD DIGIT, "n", IN NUMBER FOR CURRENT RADIX Meaning: The digit specified is greater than or equal to the current radix. For example, the digit "8" would produce this error if the current radix were octal. (pass 1) Action: The digit is allowed. For example, the string 473 in base 5 would assemble as 4 times 25 plus 7 times 5 plus 3. NE - CONFLICTING RADIX OVERRIDE Meaning: A number was proceeded by a temporary radix control operator (^P, ^D, or ^B) and also was followed by the period (.) decimal radix operator. For example: TAD ^O345.+1. (pass 1) Action: The number is interpreted in the decimal radix. NE - NO DIGIT AFTER ^D, ^O, OR ^B Meaning: Within an expression, one of the local radix operators, ^D, ^O, or ^B occurred but was not followed immediately by a digit. These operators must be followed by a number. Intermediate spaces or tabs are not permitted. (pass 1) Action: The character which was not a digit is ignored. The scan continues to look for the number associated with the local radix override. D-5 MACREL DIAGNOSTIC ERROR MESSAGES NE - RADIX OUT OF RANGE Meaning: The (decimal) value of the expression following a .RADIX command was negative, 0, 1, or greater than 10. These values are not permitted. The specified radix must be between 2 and 10 inclusive. (pass 1) Action: The argument to the .RADIX directive is assumed to be 8, i.e. the current radix is set to octal. NF - FILE # NOT FOUND OR DEVICE WRITE ONLY (passes 1 and 2) NI - NOT YET IMPLEMENTED Meaning: The user attempted to use some feature that is not yet working in this release of MACREL. (pass 1) Action: The current statement is skipped. NI - UNIMPLEMENTED DIRECTIVE (pass 1) NI - UNIMPLEMENTED PSEUDO-OP PE - TOO MANY LITERALS (pass 2) PH - END OF FILE REACHED BEFORE END OF .REPT Meaning: The end of the input file was found and no .ENDR directive was encountered to close the repeat sequence (.REPT directive). Action: The pass is aborted. PH - MACRO # DOES NOT TERMINATE (.ENDM ASSUMED) PH - NO TEXT AFTER MACRO DIRECTIVE, MACRO # PH - NO TEXT AFTER .REPT PH - PHASE ERROR Meaning: The end of the input file was encountered when it was not expected. The assembler was still in the middle of a conditional or macro definition which had not terminated. (passes 1 and 2) Action: The assembly concludes normally, assuming the conditional or macro definition had ended. D-6 MACREL DIAGNOSTIC ERROR MESSAGES RD - GLOBAL REDEFINED TO NON-GLOBAL Meaning: A global symbol or entry point was redefined in a direct assignment expression that used a single equal sign. (pass 1) Action: The new value for the symbol is retained and the symbol remains a global. RD - REDEFINITION OF SECT NAME name Meaning: A program section directive was encountered whose name was already the name of another program section of a different type. Action: ^^The new section type is used. This will cause errors to be generated in the relocatable binary file. RD - REDEFINITION OF SYMBOL, name Meaning: A known symbol was given a new type in a .GLOBAL, .EXTERNAL, .ENTRY, or .ZTERN directive. (pass 1) Action: The new type is accepted. The relocatable binary will probably be bad. RD - SYMBOL # BEING REDEFINED TO MACRO NAME RE - RELOCATION ERROR Meaning: An illegal operation was specified such that the result was not simply relocatable. (pass 1) Action: The result of the expression is assumed to be absolute 0. SE - NO ROOM IN FREESPACE FOR MACRO name (passes 1 and 2) SE - RAN OUT OF ROOM IN FREESPACE Meaning: The assembler ran out of free room. This is probably because there were too many symbols used in the source program and the symbol table got filled up. It could also mean that the user had too much text in macro definitions and that this filled up freespace. (passes 1 and 2) Solution: Reduce the number of symbols in the program, shorten the length of the macros, or break up the program into several source modules. Action: The pass is aborted. SE - TOO MANY LEVELS OF MACRO (OR REPT) D-7 MACREL DIAGNOSTIC ERROR MESSAGES SE - TOO MANY LSD ENTRIES (passes 1 and 2) SY - A DIGIT MAY NOT FOLLOW A DOLLAR IN A SYMBOL Meaning: A symbol (identifier) was encountered that began with a dollar sign and was followed by a digit. This is not permitted. If a symbol begins with a dollar sign, the next character must be a letter or period or a dollar sign. (pass 1) Action: An erroneous symbol name is generated. SY - BAD ARGUMENT TO DIRECTIVE Meaning: The argument to a PAGE directive was not absolute or relative to the current SECT or it had an absolute part which was greater than 37 octal. (pass 1) Action: The low order 5 bits of the absolute part of the argument are used. SY - BAD DEVICE NAME name Meaning: Device name greater than 4 characters or no name specified in the DEVICE directive. This error will also be generated if an extension was erroneously specified, e.g. DEVICE FILE.XX. (pass 1) Action: If extra characters were specified, or if an extension was specified, these characters are lost. If no name was specified, two words of 0 will be assembled. SY - BAD MACRO NAME Meaning: The character after a .MACRO directive (excluding spaces and tabs) was not alphabetic. A valid symbol must occur at this place. (pass 1) Action: The invalid character is ignored, and the assembler continues to search the line for the macro name. SY - BAD SECT NAME SY - BAD TERM AFTER SY - CAN'T RESTRICT A-SECT D-8 MACREL DIAGNOSTIC ERROR MESSAGES SY - DANGLING OPERATOR Meaning: An expression ended with an operator (other than space or tab). (pass 1) Action: The operator is ignored and the value of the expression is determined solely by the portion of the expression that occurred prior to the operator causing the error. (pass 1) SY - DEVICE NAME name TOO LARGE Meaning: The device mnemonic specified in a .INCLUDE or .CHAIN directive consisted of more than 4 characters. (pass 1) Action: Characters following the fourth character are ignored. SY - END OF LINE ENCOUNTERED BEFORE END OF ' OR " OPERATOR Meaning: The " operator must be followed by a legal ASCII character before the end of the line is encountered. The ' operator must be followed by two legal SIXBIT characters before the end of the line is encountered. Similarly for the ^" command. This error can also occur if no character at all follows an up-arrow. (pass 1) Action: The statement is aborted. Invalid binary will be generated. SY - EXTRA RIGHT ANGLE BRACKET IGNORED SY - IFDEF NOT FOLLOWED BY A SYMBOL Meaning: The IFDEF or .IF DF directive was not immediately followed by a symbol. (Such a symbol would begin with an alphabetic character.) The same error message is generated for the IFNDEF and .IF ND directives. (pass 1) Action: The directive is aborted. SY - ILLEGAL ARGUMENT erg SY - IMPROPER EXTENSION Meaning: The file name specified in a FILENAME directive began with a period, or contained two periods. A period indicates that an extension follows. A file name may have only one extension. The name (preceding the extension) may not be omitted. (pass 1) Action: MACREL generates an erroneous file name. D-9 MACREL DIAGNOSTIC ERROR MESSAGES SY - IMPROPER LOCAL SYMBOL Meaning: 1. A symbol was found that ended with a dollar sign ($), but this $ was past character 6 in the symbol. 2. A symbol ending with a $ was encountered before the first occurrence of a tag (terminated by a comma) within a SECT. (pass 1) Action: An unpredictable name is generated and the assembly continues. SY - INVALID ARG # .PUSH OR .POP SY - MISSING DEVICE OR FILENAME Meaning: No name appeared after a DEVICE or FILENAME directive. The name must start with a letter. (pass 1) Action: The directive is aborted. SY - MISSING NUMERIC ARGUMENT Meaning: A statement ended with one of the temporary radix control operators, O, D, ^B. (pass 1) Action: The statement is aborted. SY - MISSING SECT NAME Meaning: No name was specified in a program section directive. (pass 1) Action: The character after the .SECT directive (which was not an alphabetic character) is ignored and the assembler continues to scan for the section name. SY - MISSING TEXT ITEM Action: The directive is aborted. (pass 1) SY - NAME OF FILE OR DEVICE TOO LONG Meaning: The filename specified with the FILENAME directive had more than 6 characters, or the extension had more than 2 characters, or the device name specified with the DEVICE directive contained more than 4 characters. (pass 1) Action: The extra characters are ignored. SY - NAME # ON .ENDM DOES NOT MATCH NAME ON .MACRO D-10 MACREL DIAGNOSTIC ERROR MESSAGES SY - NO COMMA AFTER SECT NAME SY - NO COMMA OR SYMBOL AFTER DECLARATION Meaning: 1. No symbol was specified as an argument to a directive (.EXTERN, .ZTERN, .ENTRY, .GLOBAL). 2. The character after a comma within a declaration list was not a letter (after ignoring spaces and tabs). (pass 1) Action: The character found is ignored, and the assembler continues to look for a proper identifier. SY - NO PREVIOUS SECT SY - QUOTED ARGUMENT MISSING FINAL " SY - SECT name HAS UNKNOWN TYPE "x" SY - TASK NAME HAS IMPROPER TYPE (pass 1) SY - UNKNOWN ENABLE CONDITION Meaning: The keyword following a .ENABLE directive was not one of the permissible names. (pass 1) Action: The directive is aborted. SY - UNKNOWN IF CONDITION SY - UNKNOWN LIST CONDITION SY - UNKNOWN TYPE OF SECT Meaning: In a .SECT directive, the character after the comma following the SECT keyword was not a legal section type. The permissible types are A, F, D, R, X, and Z. This error may also occur if no section type is specified after the comma. (pass 1) Action: The SECT is assumed by default to be an .RSECT. SY - VACUOUS EXPRESSION Meaning: An expression was required in the current context, but none was found. (pass 1) Action: Assembly continues assuming an expression was found whose value was 0 (absolute). D-11 MACREL DIAGNOSTIC ERROR MESSAGES SY - Z IMPROPERLY SPECIFIED Meaning: The Z operator occurred within a memory reference instruction whose direct operand did not refer to page 0. (pass 1) Action: The Z is ignored. SY - 4096 OPEN ANGLE BRACKETS Meaning: A directive or expression contained more than 4095 left angle brackets (<). (pass 1) Action: The statement is aborted. SY - 4096 NESTED TRUE CONDITIONALS Meaning: More than 4095 conditionals were nested within side of each other and all the conditions were true. Action: The pass is aborted. The user must revise the program to use fewer nested conditional expressions. (pass 1) UO - BAD ORIGIN Meaning: The expression after an asterisk directive was not absolute or relative to the current SECT. (pass 1) Action: Assembly continues assuming the current location counter value referred to the absolute part of the specified expression (within the current SECT). The relocatable portion of that expression is ignored. US - SYMBOL NOT FOUND (pass 2) XX - UNKNOWN ERROR %0 - ZERO DIVIDE D-12 INDEX /0-9 LINK command string option, Assembly, 1-3, 1-20 9-5 chaining directives, 5-24 7BIT .ENABLE directive option, format effectors, 2-2 5-36 listing control directives, 5-2 8BIT .ENABLE directive option, listing format, 8-7 5-36 MACREL passes 1 thru 4, 1-20, 1-22 option directives, 5-34 operating procedures, 8-1 /A MACREL command string option, PAL8 programs, 1-4, 1-6 8-2 Assigning symbol values, 4-6, 4-9 ABS .IF directive condition, 5-22 Asterisk (*), 4-1 ABSLDR binary file, 9-2 directive, 1-9, 4-11, 5-14, Absolute assembled value (program 10-18 listing), 8-9 symbol in program listing, 8-9 Absolute expressions, 1-19 Autoindex register, 3-5 Absolute program section, 1-8, program section, 1-8, 7-4 asterisk directive in, 5-14 default name, 7-4 literals, 4-14 /B, named, 4-14 LINK command string option, 9-4 unnamed, 4-14 MACREL command string option, Absolute relocation, 1-19 8-2 Absolute symbols, 4-9 PAL8 command string option, 1-6 Actual macro arguments, 6-7 Backslash (\) special operator, Addition operator (+), 4-18 4-1, 4-7 ALTMODE (ESC) command terminator, Bars, vertical (metasymbol), xii 9-2 BATCH, 8-3 Ampersand (&) operator, 4-1, 4-20 BE .LIST directive option, 5-2 AND Boolean operator (&), 4-20 Binary code generation, 1-21 Angle brackets (<>), Binary expression operations, in conditional macros, 6-17 4-28 in expressions, 4-1, 4-27 Binary file, Apostrophe, 4-1 ABSLDR, 9-2 program listing, 8-99 relocatable, 1-4, 1-6, 8-1 concatenation operator, 6-12 Binary radix control, 4-15 Arguments, BL .IF directive condition, 5-22 macro, 6-7 .BN filename extension, 9-2 substrings in macros, 6-9 Boolean operators, 4-20 Arithmetic operators, 4-18 Brackets, relocation types for, 4-31 angle (<>), 4-1, 4-27, 6-17 ASCII, square, character set, A-1 enclosing literals, 4-1, data representation, 4-16 4-12, 1-5 .ENABLE directive option, 5-36 metasymbol, xii .ASECT directive, 1-8, 7-4 in named and unnamed program sections, 4-14 in PAL8 programs, 1-6 Index-1 INDEX (Cont.) /C, Conditional source code in LINK command string option, 9-4 macros, 6-16 MACREL command string option, Constants generated by micro- 8-2 instruction combinations, 3-10 Calls, Control character representation, macro, 6-6 4-18 repeat blocks, 6-20 Control commands for MACREL CDF instruction, 3-10 error messages, 8-5 (special operator), 4-24, Control options (LINK), 9-4 7-18 COS .ENABLE directive option, 5-36 in expressions, 1-19 CREF file PAL8, 1-21 in overlays, 10-10 Cross-reference (KREF program), relocation, 1-19 1-21, 8-15 CDF/CIF, CTRL/C control character, 8-6 relocatable symbols, 4-9 CTRL/L control character, 2-2 relocation expressions, 1-19, CTRL/O control character, 8-6 1-19 CTRL/S control character, 8-6 .CHAIN directive, 5-25 Current location counter, 4-11, Change Data Field - see CDF 5-14, 10-15 Change Instruction Field - in expressions, 4-27 see CIF PAGE directive, 5-16 Character set, 4-1, A-1 program listing, 8-9 Characters, setting to unknown values, 5-14 in symbols, 4-2 Current page literals, 4-12, 4-12 in text strings, 4-16, 5-10 special, 4-1 uppercase/lowercase (metasymbol), xii Data, CIF instructions, 3-10 program section, 1-8, 7-9 (special operator), 4-24, statement format, 2-1 7-19 storage directives, 5-7 in overlays, 10-10 Decimal radix control, 4-16 CND .LIST directive option, 5-2 DECIMAL PAL8 directive, 5-7 Code Location Directives, 5-13 Default filename extensions, 1-6, Coding procedures, 7-21 8-1, 8-15, 9-2 Colon, 4-1, 4-4, 4-6 Default terminal conditions Comma, 4-1, 4-3 (MACREL), 8-6 Command string, DEVICE directive, 5-26 KREF, 8-15 Devices, LINK, 9-1 KREF default, 8-15 MACREL, 8-1 LINK default, 9-2 PAL8 /B and /F options, 1-6 MACREL default, 8-1 Comment statement format, 2-1 DF .IF directive condition, 5-22 Communicating between modules, Diagnostic messages (MACREL), D-1 1-7, 7-14 DIF .IF directive condition, 5-22 Complex relocation 1-19 Direct assignment statement, 4-6, Concatenating, 4-9 in nested macros, 6-16 Directives, 1-3, 2-1, 5-1 macro arguments, 6-12 .ASECT, 1-6, 7-4 Conditional Assembly Directives, Asterisk (*), 1-9, 4-11, 5-14, 5-20 10-15 in macros, 6-16 .CHAIN, 5-25 nested, 5-23 DECIMAL, 5-7 Index-2 INDEX (Cont.) Directives (cont.) Double equal sign (==), 4-9 DEVICE, 5-26 Double quote ("), 4-1 .DISABL, 5-36 ASCII conversion operator, 4-16 .DSECT, 7-9 TEXT directive, 5-8 EJECT, 5-5 .DSECT directive, 1-8, 7-9 .ENABLE, 5-35 DTORG PAL8 pseudo-operator, 1-5 .ENDM, 6-3 Dummy arguments in macros, 6-3 .ENDR, 6-20 Dynamic code relocation, 5-19 ENPUNCH, 5-6 .ENTRY, 7-17 EXPUNGE, 5-6 .EXTERNAL, 7-14 E MACREL terminal control command, FIELD, 5-17 8-6 FILENAME, 5-26 /E MACREL command string option, FIXMRI, 5-31 8-3 FIXTAB, 5-32 EDF special operator, 4-25 .FSECT, 7-10 EJECT PAL8 directive, 5-5 .GLOBAL, 7-16 Ellipsis (metasymbol), xii .IF, 5-20 .ENABLE directive, 5-35 IFDEF, 5-24 and TEXT directive, 5-10 IFNDEF, 5-24 .ENABWD special variable, 5-37 IFNZRO, 5-24 .ENDM directive, 6-3 IFZERO, 5-24 .ENDR directive, 6-20 .INCLUDE, 5-24 ENPUNCH PAL8 directive, 5-6 .JSW, 5-28 Entry point definition, 7-17 .MACRO, 6-3 .ENTRY directive, 7-17 .MEXIT, 6-15 EQ .IF directive condition, 5-22 NOPUNCH, 5-6 Equal sign (=), 4-1 OCTAL, 5-7 direct assignment statement, 4-9 PAGE, 5-16 LINK command string option, 9-4 .POP, 5-34 Error messages, .PUSH, 5-33 assembly, 1-20 .RADIX, 5-6 diagnostic, D-1 RELOC, 5-19 format, 8-6 .REPT, 6-20 LINK, 9-7 .RSECT, 7-5 MACREL runtime control, 8-5, 8-8 .SECREF, 7-17 ESC (ALTMODE) LINK command .SECT, 1-7 terminator, 9-2 .SECT *, 7-13 Evaluate Data Field - see EDF .START, 5-27 Evaluation - see expression TEXT, 5-8 to 5-13 evaluation .VERSION, 5-29 Exclamation point operator (!), XLIST, 5-5 4-1, 4-20 .XSECT, 7-7 Expressions, 4-1 ZBLOCK, 5-7 absolute, 1-19 .ZSECT, 7-6 evaluation, 4-27 .ZTERNAL, 4-24, 7-15 .FSECT relocation, 1-19 .DISABL directive, 5-37 literal, 4-12, 4-12 Division operator (%), 4-19 Memory Reference Instructions, Document conventions, xii 3-6, 4-22 Dollar sign ($), operator precedence, 4-28 in local symbols, 4-6 relocation, 1-19, 4-30 PAL8 terminator, 1-5, 4-1 simple relocation, 1-19 Index-3 INDEX (Cont.) Expressions (cont.) .FSECT directive, 1-9, 7-10 terms, 4-27 literals, 4-14 uses of, 4-30 relocatable symbols, 4-9 EXPUNGE directive, 5-29 relocation, 7-11 EXPUNGE, expressions, 1-19 .ENABLE directive option, 5-36 /FY MACREL command string 5-28 .DISABL directive option, 5-37 option, 8-3 .EXTERNAL directive, 7-14 /G, LINK command string option, 9-4 /F, MACREL command string option, LINK command string option, 9-4 8-2 PAL8 command string option 1-6 GE .IF directive condition, 5-22 Field - see memory field .GLOBAL directive, 7-16 FIELD directive, 5-17 Global symbol assignment, 4-10 in unnamed absolute program Global Symbol Table, 1-22, 9-6 sections, 7-4 GST - see Global Symbol Table File, GT .IF directive condition, 5-22 binary, 8-2 KREF, 1-6, 8-2 listing, 1-6, 8-1 load map, 9-2 /H LINK command string option, 9-4 macro library, 10-17 Horizontal tab, 2-2 memory-image, 1-23, 9-2 in expressions, 4-21 relocatable binary, 1-4, 1-6, inclusive OR operator, 4-20 8-1, 10-2 PAL8 use, 1-6 save, 1-23, 9-2, 10-2 source, 1-7, 1-9, 8-2 FILENAME directive, 5-26 Filename default extensions, 1-6, I special operator, 4-1, 4-23 8-1, 8-15, 9-2 IDN .IF directive condition, 5-22 FILL, .IF directive, 5-20 .ENABLE directive option, 5-36 in macros, 6-16 .DISABL directive option, 5-37 IFDEF PAL8 directive, 5-24 FIXMRI directive, 5-31 IFNDEF PAL8 directive, 5-24 FIXTAB directive, 5-32 IFNZRO PAL8 directive, 5-24 .FLD special operator, 4-26, 7-19 IFZERO PAL8 directive, 5-24 FLD:n default program section .INCLUDE directive, 5-25 name, 7-4 Inclusive OR operator, 4-20 Floating program section, 1-9, Indirect addressing, 4-23 7-10 Input/Output Transfer literals, 4-14 Instructions, 3-1, 3-5 Form feed format effector, 2-2 internal, 3-8 Format of, keyboard/reader, 3-8 Memory Control Block, 10-16 memory extension, 3-9 PDP8 machine instructions, 3-1 paper tape reader/punch, 3-9 program listing, 8-7 teleprinter/punch, 3-8 relocatable binary (.RB) file, Instruction set, PDP/8, 3-1 10-2 statement format, 2-1 save (.SV) file, 10-14 Intermodule communication, 1-7 Symbol Table, 8-10 directives, 7-14 Forward slash (/) symbol, 4-1, 2-2 in overlays, 10-10 Index-4 INDEX (Cont.) IOT - see Input/Output Transfer LINK (cont.), Instructions loader codes, 10-5 operating procedures, 9-1 overlay option rules, 9-3 pass 1, 1-22 /J, pass 2, 1-22 LINK command string option, 9-4 symbol resolution, 1-22 MACREL command string option, system files, 9-1 8-2 LINK.SV system file, 9-1 .JSW (Job Status Word) directive, Linking, 1-4, 1-22 .LIST directive, 5-2 Listing file, 1-6 MACREL, 8-1 /K, KREF, 8-15 LINK command string option, 9-4 LINK, 9-2 MACREL command string option, pass 3, 1-21 8-2 .LISTWD special variable, 5-4 .KF filename extension, 1-6, 8-2, Literals, 4-12 8-15 closing PAL8 expressions, 1-5 KREF, current page, 4-12 command string, 8-15 evaluation, 4-12 example listing, 8-16 pool size, 4-14 file, 1-6, 8-2 page zero, 7-4 listing example, 8-16 overwriting, 1-5, 4-14 operating procedures, 8-15 storage of, 4-13 KREF.SV system file, 8-1 LN .LIST directive option, 5-2 KREF.TM default filename, 8-2 Load map, 9-11 file, 9-2 Loading address (program section), 1-9, 10-16 L MACREL terminal control command, Loading Information Directives, 8-5 5-27 /L MACREL command string option, Loading (LINK pass 2), 1-22 8-3 LOC keyword, 7-5 to 7-11 Labels, 2-1, 4-4 Local symbols, 4-6 LE .IF directive condition, 5-22 Location counter, 4-11, 5-14, Left shift operator (!), 4-20 10-15 LEVEL keyword, 7-5 to 7-11, 10-10 PAGE directive, 5-16 .LEVEL special operator, 4-27 program listing, 8-9 Levels (overlay), 10-9 setting to unknown values, 5-14 Library file, Lowercase characters, LINK, 1-22, 9-6, 10-8 in symbols, 4-1 macro, 10-17 metasymbology, xii Line buffer size(MACREL), 2-1 .LS filename extension, 1-6, 8-2 Line feed character, (PAL8), 1-5 LSD - see Loader Symbol Dictionary Line number (program listing), 8-8 LST - see Loader Symbol Table LINK, LT .IF directive condition, 5-22 command string, 9-1 .LT filename extension, 8-15 example, 9-2 options, 9-3 error messages, 9-7 features, 1-2 library file, 1-22, 9-6, 10-8 load map, 9-11 Index-5 INDEX (Cont.) /M, Macros (cont.) LINK, command string option, names, 6-10 9-4 nesting, 6-14 MACREL command string option, symbols in, 6-10 8-3 .MACRO directive, 6-3 .MA filename extension, 1-6, MC .LIST directive option, 5-2 8-2, 9-2 ME .LIST directive option, 5-2 MACERR.SV system file, 8-1 MEB .LIST directive option, 5-2 Machine instruction set, 3-6 Memory, MACOVR.SV system file, 8-1 allocation (LINK pass 2), 1-22 MACREL, field loading restrictions, arithmetic operators, 4-18 5-17 assembly of PAL8 programs, 1-6 loading address, 10-16 character set, 4-1 symbol table requirements, 10-1 command string 8-1 virtual size option, 9-4 comments, 2-1, 2-2 Memory Control Block format, compatibility with PAL8, 1-4 10-16 data, 2-1 Memory extension, 3-9 diagnostic messages, D-1 Memory image file, 1-23, 9-2 directives, 2-1, 5-1 Memory Reference Instructions, error messages, 8-5 3-1, 3-6, 4-22 features, 1-1 Memory Segment Doublewords, 10-16 instructions, 2-1 Messages - see error and labels, 2-1 diagnostic messages line buffer size, 2-1 Metasymbology, xii listing example, 8-11 .MEXIT directive, 6-15 literals, 1-5 Microinstructions, loader codes, 10-5 generating constants from, 3-10 operating procedures, 8-1 operate, 3-1, 3-3 PAL8 compatability summary, B-1 Minus sign (-), 4-1 passes 1 thru 4, 1-20 subtraction operator, 4-19 Permanent Symbol Table, C-1 program listing, 8-9 relocation, 1-1 Modules, source program format, 2-1 source, 1-7, 1-9 statement format, 2-1 MRI - see Memory Reference symbol table sizes, 10-1 Instruction system files, 8-1 Multiplication operator (^), 4-19 terminal message codes, 8-8 MACREL.SV system file, 8-1 Macros, 1-2 argument substrings, 6-9 /N, argument concatenation, 6-12 LINK command string option, arguments, 6-3, 6-7 9-4, 9-5 calls, 6-6 MACREL command string option, concatenation in nested, 6-16 8-3 conditional assembly directives Named absolute program section, in, 6-16 4-14 conditional source code in, FIELD directive in, 5-18 6-16 .NARGS special operator, 6-17, definitions, 6-3 6-19 directives, 6-1 NB .IF directive condition, 5-22 expansion, 6-6, 6-10 .NCHAR special operator, 6-10 library file, 10-17 NDF .IF directive condition, 5-22 name deletion, 5-30 NE .IF directive condition, 5-22 Index-6 INDEX (Cont.) Nesting, PAGE keyword, 7-5 to 7-11 literals, 4-12 Page zero, macros, 6-14 addressing special operator concatenation in, 6-16 (Z), 4-24 repeat blocks, 6-21 literals, 4-12 .NOLIST directive, 5-2 program section, 1-7, 7-5 NOPUNCH PAL8 directive, 5-6 PAL8, Number representation, 4-15 .ASECT directive in programs, Numeric characters in symbols, 1-5 4-6 /B command string option, 1-6 closing literal expressions, 1-5 compatibility with MACREL, 1-4, /O, B-1 LINK command string option, 9-4 CREF file, 1-21 MACREL command string option, DECIMAL directive, 5-7 8-3 dollar sign ($) terminator, 1-5 Object module, 1-23, 9-2, 10-2 DTORG pseudo-operator, 1-5 OCTAL PAL8 directive, 5-7 EJECT directive, 5-5 Octal radix control, 4-16 ENPUNCH directive, 5-6 Operate microinstructions, 3-1, /F command string option, 1-6 3-3, 3-7 horizontal tab use, 1-6 Operating procedures, IFDEF directive, 5-24 KREF, 8-15 IFNDEF directive, 5-24 LINK, 9-1 IFNZRO directive, 5-24 MACREL, 8-1 IFZERO directive, 5-24 Operators, line feed support, 1-6 arithmetic, 4-18 literals, 1-5 Boolean, 4-20 NOPUNCH directive, 5-6 expression precedence, 4-28 OCTAL directive, 5-7 special, 4-1, 4-21 PAUSE pseudo-operator, 1-5, 4-3 options - see run time, command program assembly, 7-4 string, run time options, 1-6 LINK, MACREL, KREF, etc. terminal support, 1-6 OR Boolean operator, 4-20 XLIST directive, 5-5 OR .ENABLE directive option, 5-36 Parenthesis ( () ), 4-1 OS/8, current page literals 4-12 .ENABLE directive option, 5-36 right, 1-5 Keyboard Monitor R command, PAUSE PAL8 pseudo-operator, 1-5, 1-23, 8-1, 9-1 4-3 Overlay driver, 10-14 PDP-8 machine instruction set, OVERLAY keyword, 7-5 to 7-11, 3-1, 3-6 10-10 Percent sign (%) division Overlays, operator, 4-1, 4-19 introduction, 1-2, Period (.), rules for creating, 9-3, 10-9 current location counter, 4-11 OVRDRV.MA system file, 9-3, 10-14 decimal radix control, 4-16 OVRDRV.RB system file, 9-1 in directive names, 5-1 special operator, 4-1, 4-11 PERM, .ENABLE directive option, 5-36 /P MACREL command string option, .DISABL directive option, 5-37 8-3 Permanent Symbol Table, 4-3, PAGE directive, 5-16 6-10, A-1 Index-7 INDEX (Cont.) PIP (library file creation), 9-6 Relocatable (cont.) Plus sign (+), program section, 1-7, 7-5 to addition operator, 4-1, 4-18 7-11 in program listing, 8-9 symbols, 4-9 .POP directive, 5-34 Relocation, 1-1, 1-6, 7-1 Program, arithmetic expressions, 4-30 design, 7-21 dynamic, 5-19 listing, format, 8-7 CDF and CIF instructions, 4-24 format effectors, 2-2 FIELD directive, 5-18 subtitle, 5-4 .FSECT, 7-10 title, 5-3 programming, 1-10 Program section, 1-7 summary of types, 7-12 absolute, 4-14 symbol, 4-9 communication, 1-13 types, 1-18 directives, 7-1 Repeat directives, 6-1 loading address, 1-9 Repeat blocks, size, 1-9, 7-2 defining and calling, 6-20 Programming fundamentals, 1-10 nested, 6-21 PUNCH, .REPT directive, 6-20 .ENABLE directive option, 5-36 RET (carriage return), xii .DISABL directive option, 5-37 RETURN key, 2-1 .PUSH directive, 5-33 Right parenthesis ()), 1-5 Right square bracket, 1-5 ROOT keyword, 7-5 to 7-11 /Q MACREL command string option, Root segment, 10-9 8-3 .RSECT directive, 1-8, 7-5 Question mark (?) in program RTS/8 device handler function listings, 8-9 control word, 4-26 Quote, Run time options (PAL8), 1-6 double ("), 4-17, 5-8 single ('), 4-17 /S, LINK command string option, 9-4 R OS/8 Keyboard Monitor command, MACREL command string option, 1-23, 8-1, 9-1 8-3 /R, Save file, 9-2 LINK command string option, 9-4 format, 10-14 MACREL command string option, .SBTTL directive, 5-4 8-3 Secondary reference to symbols, Radix control, 7-17 directives, 5-6 .SECREF directive, 7-17 operators, 4-15 .SECT directive, 1-7, 7-2 .RB, .SECT * directive, 7-13 file format, 10-2 Semicolon (;), 4-1 filename extension, 1-6, 8-2, statement terminator, 2-2 10-8 SHIFT .ENABLE directive option, Redefining symbols, 4-10 5-36 REL .IF directive condition, 5-22 Simple relocation, 1-19 RELOC directive, 5-19 Single equal sign (=), 4-9 Relocatable, Single quote (') ASCII conversion binary file, 1-4, 1-6, 8-1, operator, 4-17 10-2 SIXBIT .ENABLE directive option, coding procedures, 7-21 5-36 Index-8 INDEX (Cont.) Size of program sections, 1-9 ST .LIST directive option, 5-2 Slash symbol, Stack Manipulation Directives, back (\), 4-7 5-33 forward (/), 2-2 .START directive, 5-27 Source files and modules, 1-7, Statement, 1-9 direct assignment, 4-9 Source program format, 2-1 format, 2-1 Space, labels, 4-4 in expressions, 4-20 Substrings of macro arguments, in program listing, 8-9 6-9 inclusive OR operator, 4-20 Subtitle directive, 5-4 Special characters and operators, Subtraction operator (-), 4-19 4-1 .SV file, 1-23 Ampersand (&), 4-1, 4-20 .SV filename extension, 9-2 Apostrophe ('), 6-12 Symbol conventions in this Backslash (\), 4-7 manual, xii CIF and CDF, 4-24, 7-19 Symbol definition (assembly Dollar sign ($), 1-5, 4-1, 4-6 pass 1), 1-20 Double equal sign (==), 4-9 Symbol Dictionary, 10-2 Double quote ("), 4-1, 4-17, Symbol table, 1-22 5-8 descriptor codes, 8-10 EDF, 4-25 format, 8-10 Exclamation point operator (!) modification directives, 5-29 4-1, 4-20 permanent, 4-3, 6-10, A-1 Equal sign (=), 4-1, 4-9 sizes, 10-1 .FLD, 4-26, 7-19 Symbols, 4-2 Forward slash (/), 2-2 assigning values to, 4-6, 4-9 I, 4-23 characters in, 4-1 .LEVEL, 4-27 defining, 4-3 Memory Reference Instructions, deleting, 4-1, 5-30 3-6, 4-22 external, 7-14, 7-15 Minus sign (-), 4-1, 4-19 global, 4-10, 7-16 .NARGS, 6-17, 6-19 in macros, 6-10 .NCHAR, 6-10 legal characters, 4-2 Percent sign (%), 4-1, 4-19 LINK resolution of, 1-22 Period (.), 4-1, 4-11, 4-16, local, 4-6 5-1 name modification, 4-6 Plus sign (+), 4-1, 4-18, 8-9 permanent, 4-3 Single quote ('), 4-17 redifinition, 4-10 Uparrow (^), 4-1, 4-19 relocation, 4-9 Uparrow B (^B), 4-15 secondary reference, 7-17 Uparrow D (^D), 4-16 Syntax (expression), 4-27 Uparrow double quote (^"), 4-1, System files, 8-1, 9-1, 9-3 4-18 Uparrow O (^O), 4-16 XEDF, 4-26 Z, 4-1, 4-24 /T LINK command string option, Special variables, 9-5 .ENABWD, 5-37 Tab - see horizontal tab or .LISTWD, 5-4 vertical tab Square brackets, Terminal conditions (MACREL in literals, 4-1, 4-12 default), 8-6 metasymbol, xii right, 1-5 Index-9 INDEX (Cont.) Terminator, /W LINK command string option, MACREL statements, 2-2 9-5 macros, 6-3 Terms (expression), 4-27 TEXT directive, 5-8 to 5-13 .TITLE directive, 5-3 /X, TOC .LIST directive option, 5-2 LINK command string option, 9-5 MACREL command string option, 8-3 Unnamed program sections, 4-14, XEDF special operator, 4-26 7-2 XLIST PAL8 directive, 5-5 default name, 7-4 .XSECT directive, 1-8, 7-7 FIELD directive in, 5-18 Uparrow, 4-1 Uparrow (^) multiplication operator, 4-1, 4-19 /Y LINK command string option, Uparrow B (^B) binary radix 9-5 control operator, 4-15 Uparrow D (^D) decimal radix control operator, 4-16 Uparrow double quote (^n) control Z special operator, 4-1, 4-24 character representation, 4-1, /Z MACREL command string option, 4-18 8-3 Uparrow O (^O) octal radix ZBLOCK directive, 5-7 control operator, 4-16 .ZSECT directive, 1-8, 7-6 Uppercase character .ZTERNAL directive, 4-24, 7-15 as metasymbols, xii in symbols, 4-1 User Service Routine (USR) Communication Directives, 5-26 /V LINK command string option, 9-5 .VERSION directive, 5-29 Vertical bars, xii Virtual memory size option, 9-4 Index-10 : MACREL/LINK : Release Notes : AA-5663B-TA : : : READER'S COMMENTS : : : : NOTE: This form is for document comments only. DIGITAL will : use comments submitted on this form at the company's : discretion. If you require a written reply and are : eligible to receive one under Software Performance : Report (SPR) service, submit your comments on an SPR : form. : : : Did you find this manual understandable, usable, and well-organized? : Please make suggestions for improvement. : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : : Did you find errors in this manual? If so, specify the error and the : page number. : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : ___________________________________________________________________ : : Please indicate the type of reader that you most nearly represent. : : [] Assembly language programmer : [] Higher-level language programmer : [] Occasional programmer (experienced) : [] User with little programming experience : [] Student programmer : [] Other (please specify)___________________________________ : : : Name____________________________________ Date______________________ : : Organization_______________________________________________________ : : Street_____________________________________________________________ : : City_________________________ State__________ Zip Code_____________ : or : Country ----------------------------- Fold Here ------------------------------ ----------------- Do Not Tear - Fold Here and Staple ----------------- ------------------ | FIRST CLASS | | PERMIT NO. 33 | | MAYNARD, MASS. | ------------------ BUSINESS REPLY MAIL ========== NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES ========== ====================================================================== Postage will be paid by: ========== ========== --------------- ========== |D|I|G|I|T|A|L| ========== --------------- ========== ========== Software Documentation ========== 146 Main Street ML5-5/E39 ========== Maynard, Massachusetts 01754 ==========