| 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> |
