H MACRO-64_Assembler_for_OpenVMS_AXP_Systems__________$ Reference Manual- Order Number: AA-PT9KA-TE! November 1992A This document describes the MACRO-64 assembly language.G Revision/Update Information: This is a new manual.H Software Version: MACRO-64 Assembler forE OpenVMS AXP Systems= Version 1.0I Operating System and Version: OpenVMS AXP Version 1.01 Digital Equipment Corporation* Maynard, Massachusetts  N ________________________________________________________________ November 1992C The information in this document is subject to changeH without notice and should not be construed as a commitmentA by Digital Equipment Corporation. Digital EquipmentG Corporation assumes no responsibility for any errors that* may appear in this document.H The software described in this document is furnished underI a license and may be used or copied only in accordance with( the terms of such license.E No responsibility is assumed for the use or reliabilityF of software on equipment that is not supplied by Digital@ Equipment Corporation or its affiliated companies.3 © Digital Equipment Corporation 1992." All Rights Reserved.E The postpaid Reader's Comments forms at the end of thisD document request your critical evaluation to assist in- preparing future documentation.? The following are trademarks of Digital EquipmentB Corporation: Alpha AXP, AXP, DEC, DEC 4000, DECchip,A DECwindows, Digital, OpenVMS, OpenVMS AXP, VAX, VAX@ DOCUMENT, VMS, the AXP logo, and the DIGITAL logo.7 The following are third-party trademarks:F Ada[R] is a registered trademark of the U.S. Government,' Ada Joint Program Office.I This document was prepared using VAX DOCUMENT, Version 2.1.  F _________________________________________________________________F ContentsF Preface................................................... xi 1 IntroductionF 1.1 Language Features................................ 1-1F 1.1.1 Alpha AXP Native Mode Instructions ............ 1-1F 1.1.2 Direct Assignment Statements .................. 1-2F 1.1.3 Assembler Directives .......................... 1-2F 1.1.3.1 General Assembler Directives................ 1-2F 1.1.3.2 Macro Directives............................ 1-2F 1.2 Invoking MACRO-64 on OpenVMS Systems............. 1-3F 1.2.1 Command Line Qualifiers ....................... 1-30 2 Components of MACRO-64 Source StatementsF 2.1 Source Statement Format.......................... 2-1F 2.1.1 Label Field ................................... 2-3F 2.1.2 Operator Field ................................ 2-4F 2.1.3 Operand Field ................................. 2-4F 2.1.4 Comment Field ................................. 2-5F 2.2 Character Set.................................... 2-5F 2.3 Numbers.......................................... 2-8F 2.3.1 Integers ...................................... 2-9F 2.3.2 Floating-Point Numbers ........................ 2-9F 2.4 Quoted Literals.................................. 2-10F 2.5 Symbols.......................................... 2-11F 2.5.1 Permanent Symbols ............................. 2-11F 2.5.2 User-Defined Symbols and Macro Names .......... 2-12F 2.5.3 Determining Symbol Values ..................... 2-13F 2.5.3.1 Using Symbols in the Operator Field......... 2-14F 2.5.3.2 Using Symbols in the Operand Field.......... 2-14F 2.6 Temporary Labels Within Source Code.............. 2-15F 2.7 Label Addresses ................................. 2-17F iii  : 2.7.1 Label Addresses, Optimization, and CodeI Alignment...................................... 2-18? 2.7.2 Label Addresses and Automatic Data AlignmentI ............................................... 2-19I 2.8 Terms and Expressions............................ 2-22I 2.9 Unary Operators for Terms and Expressions........ 2-25I 2.9.1 Radix Control Operators ....................... 2-26I 2.9.2 Numeric Complement Operator ................... 2-27I 2.10 Binary Operators................................. 2-28I 2.10.1 Arithmetic Shift Operator ..................... 2-29I 2.10.2 Logical AND Operator .......................... 2-29I 2.10.3 Logical Inclusive OR Operator ................. 2-29I 2.10.4 Logical Exclusive OR Operator ................. 2-29I 2.11 Direct Assignment Statements..................... 2-30I 2.12 Current Location Counter......................... 2-31$ 3 MACRO-64 Lexical OperatorI 3.1 Processing with Lexical Operators................ 3-1I 3.2 Lexical Operator Syntax.......................... 3-1I 3.3 Numeric Symbols and Lexical String Symbols....... 3-4I 3.4 Lexical Substitution Operator.................... 3-4I 3.5 Lexical Escape Operator.......................... 3-5I 3.6 Using Lexical Operators.......................... 3-7I 3.7 Lexical Operators................................ 3-11I %EDIT............................................ 3-12I %ELEMENT......................................... 3-14I %EXTRACT......................................... 3-15I %INTEGER......................................... 3-16I %LENGTH.......................................... 3-17I %LOCATE.......................................... 3-18I %REPEAT.......................................... 3-19I %STRING.......................................... 3-20I %TIME............................................ 3-21I %TYPE............................................ 3-22 iv   4 Macro ArgumentsI 4.1 Using Macro Arguments............................ 4-2I 4.2 Using Default Values............................. 4-3I 4.3 Using Keyword Arguments.......................... 4-3I 4.4 Using String Arguments........................... 4-5I 4.5 Argument Concatenation........................... 4-9I 4.6 Passing Numeric Values of Symbols................ 4-9I 4.7 Using Created Temporary Labels................... 4-10( 5 MACRO-64 Assembler DirectivesI 5.1 Program Sections (Psects)........................ 5-1I 5.2 Automatic Data Alignment......................... 5-3I 5.3 Directives....................................... 5-4I .ADDRESS......................................... 5-9I .ALIGN........................................... 5-10I .ASCIC........................................... 5-13I .ASCID........................................... 5-14I .ASCII........................................... 5-16I .ASCIZ........................................... 5-17I .BASE............................................ 5-18I .BEGIN_EXACT..................................... 5-22I .BLKx............................................ 5-24I .BYTE............................................ 5-27I .CODE_ADDRESS.................................... 5-28I .D_FLOATING...................................... 5-29I .DISABLE......................................... 5-31I .ELSE............................................ 5-32I .ENABLE.......................................... 5-34I .END............................................. 5-44I .ENDC............................................ 5-46I .ENDM............................................ 5-47I .ENDR............................................ 5-48I .END_EXACT....................................... 5-49I .ERROR........................................... 5-50I .EVEN............................................ 5-51I .EXTERNAL........................................ 5-52I .F_FLOATING...................................... 5-53I .G_FLOATING...................................... 5-55I v  I .IDENT........................................... 5-56I .IF.............................................. 5-57I .IF_x............................................ 5-63I .IIF............................................. 5-67I .INCLUDE......................................... 5-69I .INSTRUCTION..................................... 5-70I .IRP............................................. 5-72I .IRPC............................................ 5-75I .LIBRARY......................................... 5-78I .LINKAGE_PAIR.................................... 5-80I .LIST............................................ 5-82I .LOCAL_CODE_ADDRESS.............................. 5-83I .LOCAL_LINKAGE_PAIR.............................. 5-84I .LOCAL_PROCEDURE_DESCRIPTOR...................... 5-85I .LONG............................................ 5-87I .MACRO........................................... 5-88I .MCALL........................................... 5-92I .MDELETE......................................... 5-93I .MEXIT........................................... 5-94I .NARG............................................ 5-97I .NCHR............................................ 5-99I .NLIST........................................... 5-101I .NOSHOW.......................................... 5-102I .OCTA............................................ 5-103I .ODD............................................. 5-105I .PACKED.......................................... 5-106I .PAGE............................................ 5-107I .PRINT........................................... 5-108I .PROCEDURE_DESCRIPTOR............................ 5-109I .PSECT........................................... 5-111I .QUAD............................................ 5-118I .REPEAT.......................................... 5-119I .RESTORE_PSECT................................... 5-122I .SAVE_PSECT...................................... 5-124I .S_FLOATING...................................... 5-125I .SHOW............................................ 5-126I .SIGNED_BYTE..................................... 5-129 vi  I .SIGNED_WORD..................................... 5-130I .SUBTITLE........................................ 5-131I .T_FLOATING...................................... 5-132I .TITLE........................................... 5-133I .WARN............................................ 5-135I .WEAK............................................ 5-136I .WORD............................................ 5-138# 6 MACRO-64 Supplied MacrosI 6.1 MACRO-64 Supplied Library........................ 6-1I 6.2 Routines and Lexical Scope....................... 6-2I 6.2.1 Routines and Program Sections ................. 6-2I 6.3 Using Macros to Control Program Sections......... 6-3I 6.3.1 Defining Program Sections ..................... 6-3I 6.3.2 Using Macro Specific Symbols .................. 6-4I 6.3.3 Defining Procedure Type ....................... 6-5I 6.3.4 Using Macros in Prologue Sections ............. 6-5I 6.3.5 Using Macros in Epilogue Sections ............. 6-6I 6.4 Programming Examples Using Supplied Macros....... 6-6I 6.5 Using the $CALL Macro............................ 6-8I 6.5.1 Using $CALL in Source Code .................... 6-9I 6.6 Programming Considerations....................... 6-11I 6.6.1 Making Multiple Calls From the Same Routine ... 6-11I 6.6.2 Non-Standard Linkage .......................... 6-11I 6.6.3 Routine Restrictions .......................... 6-11I 6.7 Macro Descriptions............................... 6-12I 6.7.1 Syntax Rules .................................. 6-12I $BEGIN_EPILOGUE.................................. 6-13I $CALL............................................ 6-15I $CODE_SECTION ................................... 6-22I $DATA_SECTION.................................... 6-23I $END_EPILOGUE.................................... 6-24I $END_PROLOGUE.................................... 6-26I $END_ROUTINE..................................... 6-27I $LINKAGE_PAIR.................................... 6-28I $LINKAGE_SECTION................................. 6-30I $OPDEF........................................... 6-31I .PACKED.......................................... 6-37I $PROCEDURE_DESCRIPTOR............................ 6-40I vii  I $RETURN.......................................... 6-41I $ROUTINE......................................... 6-42: A MACRO-64 Alpha AXP Architecture Quick ReferenceI A.1 Register Usage Conventions....................... A-3I A.2 Instruction Operand Notation..................... A-4PI A.3 Instruction Qualifier Notation................... A-5 I A.4 F-P Control Register (FPCR) Format............... A-5 I A.5 Decodable Pseudo-Operations...................... A-7 I A.6 Common Architecture Opcodes in Numerical Order... A-9oI A.7 OpenVMS PALcode Instruction Summary.............. A-16 I A.8 PALcode Opcodes in Numerical Order............... A-20 I A.9 Common Architecture Instructions................. A-23 $ B Programming with MACRO-64I B.1 OpenVMS Calling Standard......................... B-1 I B.2 Accessing Memory with Base Registers............. B-2tI B.3 Data Structures.................................. B-6_I B.3.1 Procedure Descriptor .......................... B-6hI B.3.2 Signature Block ............................... B-7 I B.3.3 Linkage Pair .................................. B-7lI B.4 Types of Routines................................ B-9eI B.4.1 Routine Capabilities .......................... B-10dI B.4.2 Entry Prologue and Exit Epilogue Sequences .... B-11hI B.5 Example Program.................................. B-12nI B.6 Establishing Self-Addressability................. B-13oI B.7 Optimization and Automatic Alignment............. B-15 I B.7.1 Automatic Data Alignment ...................... B-15rI B.7.1.1 Controlling Data Alignment.................. B-16pI B.7.1.2 Directives for Automatic Data Alignment..... B-16oI B.7.2 Automatic Code Label Alignment ................ B-18rI B.7.3 Scheduling Optimization ....................... B-18eI B.7.4 Peephole Optimization ......................... B-18qI B.7.5 Using MACRO-64 for Performance ................ B-19,I B.7.6 Viewing Optimization Results .................. B-20 viii l ," C Using LSE with MACRO-64I C.1 Invoking LSE..................................... C-1eI C.2 Running Diagnostics.............................. C-1 % D Differences from VAX MACROiI D.1 Assembler Features in MACRO-64................... D-1_I D.2 VAX MACRO Features Not Present in MACRO-64....... D-6  E Error Messages Index  Examples8 3-1 Lexical Processing Without the EscapeI Operator....................................... 3-6.I 3-2 Lexical Processing With Escape Operator ....... 3-6oI 3-3 Using Lexical Operators ....................... 3-7.I 3-4 Source Statements After Macro Expansion ....... 3-10.I 6-1 Program Using Supplied Macros ................. 6-6 I 6-2 Program Using $CALL ........................... 6-10I B-1 Routine Without Linkage Pairs ................. B-8 I B-2 Routine With Linkage Pairs .................... B-9oI B-3 Establishing a Base Address ................... B-14aI B-4 Enabling and Disabling Data Alignment ......... B-16. Figures.I A-1 Data Structures ............................... A-12I A-2 Instruction Formats ........................... A-2 I ix2  r TablesI 2-1 Using Tab Stops in Statement Fields ........... 2-2.6 2-2 Special Characters Used in MACRO-64I Statements..................................... 2-7.I 2-3 Summary of Unary Operators .................... 2-25.I 2-4 Summary of Binary Operators ................... 2-28.I 3-1 Summary of MACRO-64 Lexicals .................. 3-11.I 3-2 %TYPE Attributes .............................. 3-22-I 5-1 Summary of General Assembler Directives ....... 5-4 I 5-2 Summary of Macro Directives ................... 5-7 I 5-3 .ENABLE and .DISABLE Symbolic Arguments ....... 5-34 ; 5-4 Condition Tests for Conditional Assembly I Directives..................................... 5-58 I 5-5 Program Section Attributes .................... 5-112I 5-6 Default Program Section Attributes ............ 5-115 I 5-7 .SHOW and .NOSHOW Symbolic Arguments .......... 5-1262I 6-1 ARGS Arguments ................................ 6-17.I A-1 Register Usage Conventions for OpenVMS AXP .... A-3 I A-2 Instruction Operand Notation .................. A-4tI A-3 Instruction Qualifier Notation ................ A-5rI A-4 F-P Control Register (FPCR) Format ............ A-5lI A-5 Decodable Pseudo-Operations ................... A-7.; A-6 Common Architecture Opcodes in NumericaliI Order.......................................... A-9gI A-7 OpenVMS Unprivileged PALcode Instructions ..... A-16cI A-8 OpenVMS Privileged PALcode Instructions ....... A-17lI A-9 PALcode Opcodes in Numerical Order ............ A-20gI A-10 Common Architecture Instructions .............. A-23iI B-1 Frame Attributes .............................. B-11pI B-2 Directives Using Automatic Alignment .......... B-16 x   2I _________________________________________________________________eI PrefaceeC This manual describes the MACRO-64 assembly language.. Intended Audience H This manual is intended for all programmers writing MACRO-D 64 programs. Before reading this manual, you should beH familiar with assembly language programming, the Alpha AXPH architecture and instruction set, and the operating system( in use on your AXP system. Document StructureI This manual contains the following chapters and appendices:.B o Chapter 1 introduces the features of the MACRO-64 language.F o Chapter 2 describes the format of the MACRO-64 source statements.G o Chapter 3 describes the MACRO-64 lexical operators. It H also discusses differences and similarities between theB VAX MACRO string operators and those of MACRO-64.D o Chapter 4 describes the arguments used with macros.C o Chapter 5 describes the MACRO-64 general assembler C directives and the directives used in defining and" expanding macros.H o Chapter 6 describes macros provided with the (MACRO-64) Assembler..G o Appendix A provides a quick reference to the Alpha AXP.G architecture as it relates to the MACRO-64 programming.C language. For more information, refer to the Alpha.' Architecture Handbook. I xis b G o Appendix B provides information on how to program more: effectively using the MACRO-64 assembler.F o Appendix C explains how to invoke the LSE editor with' the MACRO-64 language.DG o Appendix D describes the differences between VAX MACROA' and MACRO-64 features..H o Appendix E describes the error messages produced by the$ MACRO-64 assembler. Related Manuals.I For more information on MACRO-64, see the following manuals.( in this documentation set:H o MACRO-64 Assembler for OpenVMS AXP Systems Installation GuideI o MACRO-64 Assembler for OpenVMS AXP Systems Release Notes.I For more information on the Alpha AXP architecture, see the. following:4 o Alpha Architecture Reference Manual, o Alpha Architecture Handbook< o Alpha AXP Achitecture Quick Reference Guide) o OpenVMS Calling Standard. Conventions.F In this manual, every use of Alpha VMS means the OpenVMSB AXP operating system, every use of VAX VMS means theF OpenVMS VAX operating system, and every use of VMS meansG both the OpenVMS AXP operating system and the OpenVMS VAX. operating system.4@ The following conventions are used in this manual:G Ctrl/x A sequence such as Ctrl/x indicates that.F you must hold down the key labeled CtrlH while you press another key or a pointing- device button.R xii. . .F PF1 x A sequence such as PF1 x indicates thatC you must first press and release the.F key labeled PF1, then press and releaseG another key or a pointing device button..D In examples, a key name enclosed in aD box indicates that you press a key onH the keyboard. (In text, a key name is not2 enclosed in a box.)@ . . . A horizontal ellipsis in examples= indicates one of the following.- possibilities:D o Additional optional arguments in a> statement have been omitted.D o The preceding item or items can be= repeated one or more times..I o Additional parameters, values, or other.= information can be entered.NI A vertical ellipsis indicates the omissionSF . of items from a code example or commandD . format; the items are omitted becauseH . they are not important to the topic being) discussed..B ( ) In format descriptions, parenthesesE indicate that, if you choose more than.G one option, you must enclose the choices.. in parentheses.H [ ] In format descriptions, brackets indicateE optional elements. You can choose one, E none, or all of the options. (Brackets.@ are not optional, however, in theB syntax of a directory name in a VMSF file specification, or in the syntax ofI a substring specification in an assignment.* statement.)F { } In format descriptions, braces surroundE a required choice of options; you must @ choose one of the options listed.I xiii. . .H boldface text Boldface text represents the introductionH of a new term or the name of an argument,9 an attribute, or a reason..F Boldface text is also used to show userF input in online versions of the manual.? italic text Italic text emphasizes important.D information, indicates variables, andD indicates complete titles of manuals.F Italic text also represents informationD that can vary in system messages (forG example, Internal error number), command.G lines (for example, /PRODUCER=name), and.: command parameters in text.F UPPERCASE TEXT Uppercase text indicates a command, theH name of a routine, the name of a file, orG the abbreviation for a system privilege. G - A hyphen in code examples indicates that F additional arguments to the request areA provided on the line that follows.pA numbers All numbers in text are assumed tonB be decimal, unless otherwise noted.C Nondecimal radixes-binary, octal, or D hexadecimal-are explicitly indicated.D mouse The term mouse refers to any pointingD device, such as a mouse, a puck, or a& stylus.G MB1, MB2, MB3 MB1 indicates the left mouse button, MB2 E indicates the middle mouse button, andcI MB3 indicates the right mouse button. (The E buttons can be redefined by the user.)hI PB1, PB2, PB3, PB1, PB2, PB3, and PB4 indicate buttons on$( PB4 the puck.H SB, SB SB and SB indicate buttons on the stylus.F VMS, OpenVMS, The terms VMS, OpenVMS, and OpenVMS AXPB OpenVMS AXP refer to the same operating system.H MACRO-64 MACRO-64 refers to MACRO-64 Assembler for3 OpenVMS AXP Systems.. xiv. . .I 1 I _________________________________________________________________I IntroductionG MACRO-64 Assembler for OpenVMS AXP Systems is an assemblyB language for programming Alpha AXP computers. SourceI programs written in MACRO-64 are translated into object (or G binary) code by the MACRO-64 assembler, which produces an.I object module and, optionally, a listing file. The features.H of the language are introduced in this chapter, as well as3 instructions to invoke the assembler.N 1.1 Language Features F MACRO-64 source programs consist of a sequence of sourceC statements. These source statements may be any of the. following:3 o Alpha AXP native-mode instructions.- o Direct assignment statements % o Assembler directivesi0 1.1.1 Alpha AXP Native Mode InstructionsG Instructions manipulate data. They perform such functionsED as addition, data conversion, and transfer of control.G Instructions are usually followed in the source statementaG by operands, which can be any kind of data needed for theoC operation of the instruction. For a brief descriptiontF of the Alpha instruction set, see Appendix A. For a moreG detailed description of the Alpha native mode instruction5E set, see the Alpha Architecture Reference Manual or the * Alpha Architecture Handbook.I 1-1.  1 Introduction 1.1 Language Features.* 1.1.2 Direct Assignment StatementsD Direct assignment statements equate symbols to values.G For more information on direct assignment statements, see. Section 2.11. " 1.1.3 Assembler DirectivesI Directives guide the assembly process and provide tools for.G using the instructions. For more information on assembler.( directives, see Chapter 5.D There are two classes of assembler directives: general8 assembler directives and macro directives., 1.1.3.1 General Assembler DirectivesE General assembler directives can be used to perform thee# following operations:> o Store data or reserve memory for data storageH o Control the alignment of parts of the program in memoryH o Specify the methods of accessing the sections of memory4 in which the program will be stored3 o Specify a procedure in the programmD o Specify the way in which symbols will be referencedF o Specify that a part of the program is to be assembled. only under certain conditions> o Display informational and diagnostic messagesI o Control the assembler options that are used to interpret.# the source programP 1.1.3.2 Macro DirectivesC Macro directives are used to define macros and repeat.C blocks. They allow you to repeat identical or similartI sequences of source statements throughout a program withoutH rewriting those sequences. Use of macros and repeat blocksG helps minimize programmer errors and speeds the debuggingo process. 1-2   I IntroductionAI 1.2 Invoking MACRO-64 on OpenVMS SystemsP0 1.2 Invoking MACRO-64 on OpenVMS SystemsF To invoke MACRO-64, use the following MACRO command with4 the /ALPHA_AXP command line qualifier:2 MACRO/ALPHA_AXP file-spec[, . . . ]D Note that you must specify the /ALPHA_AXP command lineA qualifier before any other command line parameters,.1 qualifiers, or file specifications.t! file-spec[, . . . ].F If you do not specify a file type for an input file, the; assembler uses the default file type of .M64..G You can specify one or more source files to be assembled.P? To assemble files individually, separate the file E specifications with commas. To concatenate and assembleiA the files as a single input file, separate the file 1 specifications with plus signs (+). H Command line qualifiers control special assembler options.G Assembler options can apply to the entire MACRO/ALPHA_AXP.F command line, or to the individual file being assembled.E When the qualifier follows the MACRO/ALPHA_AXP command, E it applies to all files listed. For more information on.9 command line qualifiers, see Section 1.2.1.i% 1.2.1 Command Line Qualifiers.I This section describes the command qualifiers used with the & MACRO/ALPHA_AXP command.# /[NO]ALIGNMENT=optioniI Controls the alignment of code and data. Valid options are:AI ___________________________________________________________uI Option____Function_________________________________________ B code Alignment of certain branch target labels.I data______Natural_alignment_of_data_items._________________NB If you omit the qualifier from the command line, theG default option is /NOALIGNMENT=(code, data). If more thaniI 1-3m c n Introduction0 1.2 Invoking MACRO-64 on OpenVMS SystemsF one option is specified, the options must be enclosed in3 parentheses and separated by a comma. $ /[NO]DEBUG[=(options)]9 Specifies DEBUG support. Valid options are:gI ___________________________________________________________OI Option____Function_________________________________________n; symbol Generates debug symbol information. 8 traceback Generates traceback information.> all Generates all above debug information.I none______Generates_no_debug_information.__________________ H The default qualifier is /NODEBUG. The default when /DEBUG: is specified with no keywords is /DEBUG=all.) /[NO]DIAGNOSTIC[=file-spec]PD Controls whether diagnostics are created and stored inE the specified optional file. If a file specification is C not supplied, the assembler creates a diagnostic file B using the same name as the source file. For example,C if you use a source file named XXX.M64, the assembler F creates a diagnostic file named XXX.DIA. You can use theE the diagnostic file with other Digital layered products C including, but not limited to, the Language-Sensitive Editor (LSE).c5 The default qualifier is /NODIAGNOSTIC.d$ /ENVIRONMENT=[NO]FLOATE Controls whether the assembler generates floating-point.I instructions when optimizing code and performing code-labele alignment.I Currently, the only floating-point instruction generated bytH the assembler during optimization and alignment processingC is FNOP, the floating-point no-operation instruction. E If you specify /ENVIRONMENT=NOFLOAT, the assembler doesoE not generate any floating-point instructions as part of2C optimization and alignment processing. Floating-pointe 1-4   I IntroductioniI 1.2 Invoking MACRO-64 on OpenVMS SystemsOF instructions that you specify in your source program are unaffected.h /LIBRARY> Searches macro libraries in the following order:B 1. The library designated by the /LIBRARY qualifier.) 2. The .LIBRARY directives.CH 3. The MACRO64.MLB library. The assembler searches for theF MACRO64.MLB macro library in the following locations:I MACRO64$LIBRARY, ALPHA$LIBRARY, and finally SYS$LIBRARY.rD 4. The STARLET.MLB library. The assembler searches forC the the STARLET.MLB macro library in the following G locations: MACRO64$LIBRARY, ALPHA$LIBRARY, and finally SYS$LIBRARY.iF In addition, you can place the macro library definitionsE in the listing file by using the command line qualifieri /SHOW=LIBRARY.# /[NO]LIST[=file-spec]aB Controls whether a listing is created and optionallyI provides an output file specification for the listing file. H Do not use wildcard characters in this file specification.E If you issue the MACRO/ALPHA_AXP command interactively,eG /NOLIST is the default. The assembler sends output to theiI current output device rather than to a listing file. If you G execute the MACRO/ALPHA_AXP command in a batch job, /LIST  is the default.mG If you do not specify a file specification, the assemblerhF creates a listing file using the same name as the sourceH file. For example, if you use a source file named XXX.M64,A the assembler creates a listing file named XXX.LIS.I 1-5  t  Introduction0 1.2 Invoking MACRO-64 on OpenVMS Systems /[NO]MACHINE_CODEeE Produces a binary machine code listing after the sourceA text if a listing file is requested. The default is  /NOMACHINE_CODE. /NAMES=case_optionF Specifies the alphabetic casing of identifiers in source1 code statements. Valid options are: I ___________________________________________________________ I Option____Function_________________________________________ D upper_ Converts all identifiers to upper alphabetic case case.qD lower_ Converts all identifiers to lower alphabetic case case..I as_is Causes all identifiers to remain in the case used I __________in_source_statements.____________________________ F If you use the /NAMES option in a command line, you mustF supply a case_option. If you omit the qualifier from theD command line, the default option is /NAMES=upper_case.% /[NO]OBJECT[=file-spec]xG Controls whether an object file is created and optionally @ provides a file specification. Do not use wildcard4 characters in this file specification.G If you do not specify a file specification, the assembler F creates an object file using the same name as the sourceH file. For example, if you use a source file named XXX.M64,A the assembler creates an object file named XXX.OBJ. / The default qualifier is /OBJECT. + /[NO]OPTIMIZE[=(option-list)]e 1-6   I Introduction I 1.2 Invoking MACRO-64 on OpenVMS Systems H Specifies optional assembler optimizations. Valid items in" the option-list are:I ___________________________________________________________ I Option____Function_________________________________________d9 schedule Specifies instruction scheduling. I peephole__Specifies_peepholing.____________________________ A Specifying /OPTIMIZE with no options is the same asp7 specifying /OPTIMIZE=(peephole,schedule).oG The default qualifier is /NOOPTIMIZE. See Section B.7 for,+ information on optimizations. " /[NO]SHOW=(item,...)A Modifies the output listing file. This qualifier isyG meaningful only when /LIST is specified. Valid items are:tI ___________________________________________________________aI Option___________Function__________________________________ 6 expansions Shows macro expansions.C conditionals Shows sections of code conditionally ' skipped.t8 include Shows all .INCLUDE files.I library__________Shows_macro_library_modules.______________o5 The default item is /SHOW=conditionals.) /[NO]WARNINGS=(option-list)oF Controls the severity level of messages and diagnostics. Valid options are:I ___________________________________________________________ I Option______Function_______________________________________ 4 warnings Display/suppress warnings.: informationaDisplay/suppress informationals.F all Display/suppress warnings and informational.I none________Display/suppress_nothing.______________________ I 1-7   a Introduction0 1.2 Invoking MACRO-64 on OpenVMS Systems The defaultnG qualifier is /WARNINGS=(warnings,informationals). If more G than one option is specified, options must be enclosed in / parentheses separated by a comma.o 1-8   I 2tI _________________________________________________________________ I Components of MACRO-64 Source Statementse? A source program consists of a sequence of source I statements that the assembler interprets and processes, one H at a time, generating object code or performing a specificF assembly-time process. A source statement can occupy oneB source line or can extend onto several source lines.G This chapter describes the format of the source statement + and the following components:B o Character set o Numbers o Symbols o Local labelse& o Terms and expressions+ o Unary and binary operatorse- o Direct assignment statementsB) o Current location counter # 2.1 Source Statement Format C MACRO-64 source statements can have a maximum of four! fields, as follows:tA o Label field-Symbolically defines a location in af program.sD o Operator field-Specifies the action to be performedF by the statement; can be an instruction, an assembler, directive, or a macro call.G o Operand field-Contains the instruction operands or the_F assembler directive arguments or the macro arguments.I 2-1   0 Components of MACRO-64 Source Statements# 2.1 Source Statement FormatoC o Comment field-Contains a comment that explains theAB meaning of the statement; does not affect program execution.cD Although statement fields can be separated by either aE space or a tab stop, Digital recommends that you formatsC statements with the Tab key to insure consistency andl% clarity. See Table 2-1.I Table_2-1_Using_Tab_Stops_in_Statement_Fields______________ " Column in Which FieldI Field______Begins_____Tab_Stops_to_Reach_Column____________i% Label 1 0s% Operator 9 1 % Operand 17 2 I Comment____41_________5____________________________________ E The following example shows a typical source statement.tS EXP: .BLKL 50 ; Table stores expected valuesh0 Rules for Coding Source StatementsE The following rules apply for coding source statements: E o You can continue a single statement on several lineseE by using a hyphen (-) as the last nonblank character F before the comment field, or at the end of line (when& there is no comment).C o In most cases, a statement can be continued at any-C point. If a symbol name is continued and the first.B character on the second line is a tab or a blank,E the symbol name is terminated at that character. For ? information on using symbols, see Section 2.5. E o Blank lines are legal, but they have no significance C in the source program except that they terminate a continued line.C The following sections describe each of the statement. fields in detail.l 2-2l d cI Components of MACRO-64 Source Statements I 2.1 Source Statement Formati 2.1.1 Label Field I A label is a user-defined symbol that identifies a locationrE in the program. The symbol is assigned a value equal totH the location counter where the label occurs. The followingD rules apply when coding source statements with labels:F o If a statement contains a label, the label must be in- the first field on the line. H o The user-defined symbol name can be up to 31 charactersI long and can contain any alphanumeric character, as wellH as the underscore (_), dollar sign ($), and period (.) characters.E o If a label extends past column 7, Digital recommendsPG you place it on a line by itself so that the followingeG operator field can start in column 9 of the next line.tG o A label is terminated by a colon (:) or a double colons (::).I In the following source statement, EXP: is the label field.cS EXP: .BLKL 50 ; Table stores expected values B See Section 2.5.2 for a description of the rules for0 forming user-defined symbol names.. There are three types of labels:H o Global labels-Can be referenced by other object modules; and are defined using a double colon (::).RG o Local labels-Can be referenced only within the current A module and are defined using a single colon (:).eC o Temporary labels-Can be referenced only within thefF bounds of either two local labels, two global labels,@ two psects, or within the bounds of a temporaryC label scope, as defined by .ENABLE LOCAL_BLOCK andtC .DISABLE LOCAL_BLOCK. Temporary labels are defined D using one to five digits, followed by a dollar signE and a single colon ($:). See Section 2.6 for further  information.oI 2-3  e e0 Components of MACRO-64 Source Statements# 2.1 Source Statement Format S EXP: .BLKL 50 ; EXP is a local label used topZ ; identify a 50-word block of storageU DATA:: .BLKW 25 ; DATA is a global label used toZ ; identify a 25-word block of storageW 10$: .BLKW 5 ; 10$ is a temporary label used to T ; identify a five word block of? ; storage. 2.1.2 Operator FieldH The operator field specifies the action to be performed byF the statement. This field can contain an instruction, anG assembler directive, or a macro call. If the operator is: G o An instruction, MACRO-64 generates the binary code foruH that instruction in the object module. The instructions* are listed in Appendix A.G o A directive, MACRO-64 performs certain control actionsI or processing operations during source program assembly.E The assembler directives are described in Chapter 5.eF o A macro call, MACRO-64 expands the macro. Macro callsD are described in Chapter 4 and in Chapter 5 (.MACROH directive). Macros supplied with MACRO-64 are described in Chapter 6.H Use either a space or a tab stop to terminate the operatorH field; however, Digital recommends you use the tab stop to+ terminate the operator field.bF In the following source statement, .BLKL is the operator field.S EXP: .BLKL 50 ; Table stores expected valuesd 2.1.3 Operand Field_H The operand field can contain operands for instructions orG arguments for either assembler directives or macro calls. H Operands for instructions identify the memory locations orG the registers that are used by the machine operation. ThelG operand field for a specific instruction must contain the G number and type of operands required by that instruction.cI Arguments for a directive must meet the format requirementshG of that directive. Chapter 5 describes the directives andc, the format of their arguments. 2-4t l rI Components of MACRO-64 Source StatementsI 2.1 Source Statement FormatOG Operands for a macro must meet the requirements specifiedsH in the macro definition. See the description of the .MACRO% directive in Chapter 5.cC Use a comma (,) to separate operands for instructionslB and directives. (See Section 2.8 for a discussion of expressions.)lH The semicolon that starts the comment field terminates theI operand field. If a line does not have a comment field, thelA operand field is terminated by the end of the line.sB In the following source statement example, 50 is theA operand field supplied to the operand field, .BLKL. S EXP: .BLKL 50 ; Table stores expected values2 2.1.4 Comment FieldyH The comment field contains text that explains the function@ of the statement. You can use comments to describeC algorithms, reasons for selecting particular methods, G and parameters passed to routines. Comments do not affect 7 assembly processing or program execution.MG The comment field must be preceded by a semicolon (;) and4I can contain any printable ASCII character. It is terminatedB% by the end of the line.BI A comment can appear on a line by itself. If a comment doesrG not fit on one line, it can be continued on the next, but E the continuation must be preceded by another semicolon.F In the following source statement example, "Table storesC expected values", is the comment field. Note that theu4 comment field begins with a semicolon.S EXP: .BLKL 50 ; Table stores expected valuess 2.2 Character SetyD When coding source statements, you need to be aware ofF what characters are acceptable to the assembler, and howF the assembler interprets them. The following numbers and7 characters are accepted by the assembler.bC o The letters of the alphabet, A to Z, uppercase andaB lowercase. By default, the assembler converts allI 2-5   f0 Components of MACRO-64 Source Statements 2.2 Character SetiH lowercase letters to uppercase. This means it considersC lowercase letters equivalent to uppercase letters. D The assembler can operate in a case-sensitive mode.G In case sensitive mode, the assembler does not convert G lowercase letters to uppercase letters. On OpenVMS and I OpenVMS AXP systems, case sensitive mode can be selectedeG from the command line with the /NAMES=as_is qualifier.s# o The digits 0 to 9.M< o The special characters listed in Table 2-2. 2-6e a eI Components of MACRO-64 Source Statements_I 2.2 Character Set_I Table_2-2_Special_Characters_Used_in_MACRO-64_Statements___e" CharacterI ___CharacteName________Function____________________________t? _ Underscore Character in symbol names.s? $ Dollar Character in symbol names._ sign_G . Period Character in symbol names, currentmI location counter, and decimal point.l< : Colon Local label terminator.= :: Double Global label terminator. colonI = Equal sign Local direct assignment operator andfG macro keyword argument terminator.fG == Double Global direct assignment operator.s# equal signj6 Tab Field terminator.6 Space Field terminator.= # Number Literal value indicator.J sign ? @ At sign Arithmetic shift operator.)H , Comma Field, operand, and item separator.= ; Semicolon Comment field indicator. H + Plus sign Unary plus operator, and arithmetic7 addition operator. E - Minus sign Unary minus operator, arithmetic_C or subtraction operator, and line_< hyphen continuation indicator.H * Asterisk Arithmetic multiplication operator.B / Slash Arithmetic division operator.: & Ampersand Logical AND operator.I ! Exclamation Logical inclusive OR operator point./ pointI (continued on next page)eI 2-7  0 Components of MACRO-64 Source Statements 2.2 Character Set_C Table 2-2 (Cont.) Special Characters Used in MACRO-64 I __________________Statements_______________________________ " CharacterI ___CharacteName________Function____________________________ E \ Backslash Logical exclusive OR and numeric B conversion indicator in macro/ arguments. G ^ Circumflex Unary operators and macro argumentG/ delimiter.vD ( ) Parentheses Displacement and register fieldI delimiter in an instruction operand._D Argument delimiter to a lexical. operator.D <> Angle Argument or expression grouping0 brackets delimiters.E ? Question Created local label indicator inp5 mark macro arguments. A ' Apostrophe Macro argument concatenation/ indicator.C> " Double Quoted literal delimiter. quoteH % Percent Delimits the beginning of a lexical. sign operator.G (space) Space or Separates source statement fields.B tab Spaces within expressions are7 (tab) otherwise ignored. A , Comma Separates symbolic arguments_G within the operand field. MultipleCE expressions in the operand fieldoI _______________________must_be_separated_by_commas.________s 2.3 NumberspD Numbers can be integers or floating-point numbers. TheA following sections describe these types of numbers.t 2-8y e I Components of MACRO-64 Source Statements I 2.3 Numbersn 2.3.1 Integers? Integers can be used in any expression, including > expressions in operands and in direct assignment= statements. For information on expressions, seed Section 2.8. Format snn  seG An optional sign: plus sign (+) for positive numbers (the ? default), or minus sign (-) for negative numbers.  nnB A string of numeric characters that is legal for the specified radix.G MACRO-64 interprets all integers in the source program asmF decimal unless the number is preceded by a radix controlH operator. For more information on radix control operators, see Section 2.9.1.I Integers must be in the range of -263 to +263-1 for signed D data or in the range of 0 to 264-1 for unsigned data.G Negative numbers must be preceded by a minus sign; MACRO-mG 64 translates such numbers into two's complement form. Inf: positive numbers, the plus sign is optional.$ 2.3.2 Floating-Point NumbersI A floating-point number can be used in the .DOUBLE, .FLOAT,fE .F_FLOATING, .D_FLOATING, .G_FLOATING, .S_FLOATING, andDI .T_FLOATING directives. For more information on directives,eF see Chapter 5. A floating-point number cannot be used inI an expression or with a unary or binary operator except theF unary plus and unary minus. For information on unary and= binary operators, Section 2.9 and Section 2.10._I A floating-point number can be specified with or without an  exponent.rI 2-9  o n0 Components of MACRO-64 Source Statements 2.3 Numberso Format5 Floating-point number without exponent:  snn  snn.nn snn.2 Floating-point number with exponent: snnEsnn  snn.nnEsnn snn.Esnn si An optional sign.  nn@ A string of decimal digits in the range of 0 to 9.G The decimal point can appear anywhere to the right of the I first digit. Note that a floating-point number cannot start I with a decimal point because MACRO-64 will treat the numbernG as a user-defined symbol. For information on user-definedb) symbols, see Section 2.5.2.a 2.4 Quoted LiteralstD A quoted literal is a string of characters enclosed inD double quotes (" "). Use the following guidelines when8 specifying characters in a quoted literal:E o Any character except null, carriage return, and form 3 feed can appear within the string. H o To include a double quote or backslash in a string, you6 must precede it with a backslash (\).C o To specify an arbitrary character, you can specifytE "\xhh", where each h represents a single hexadecimalu0 digit. For example, the string:! "AB\\CD\"EF\x47"l3 contains the following characters:i AB\CD"EFGG Also note that the assembler does not convert the case of < alphabetic characters within a quoted literal. 2-10 b nI Components of MACRO-64 Source StatementsiI 2.4 Quoted LiteralsoF Quoted literals can be continued over several lines. UseC the hyphen (-) as the line continuation character and.A delimit the string with double quotes. For example:m@ .ASCII "Strings are delimited with double-quotes."< .ASCII "The backslash is an escape character."S .ASCII "Use two backslashes (\\) to represent the back-slash itself."aV .ASCII "Hexidecimal escape sequences use lower or upper X: \x00 or \X00"W .ASCII "Precede a double quote with a backslash (\") to embed the quote."bD .ASCII "Strings can be continued onto multiple lines -& just as any other line." 2.5 SymbolssH You use symbols in MACRO-64 source statements to representG an instruction, directive, register name, or value. Three G types of symbols can be used in MACRO-64 source programs:cG permanent symbols, user-defined symbols, and macro names.d 2.5.1 Permanent SymbolscH Permanent symbols consist of instruction mnemonics, MACRO-C 64 directives, and register names. You do not need tolI define directives before you use them in the operator fieldD of an MACRO-64 source statement. Also, you do not needG to define instruction mnemonics and register names before 7 using them in the instruction statements.aA You can express the 32 general registers and the 32 F floating point registers of the Alpha AXP processor in a( source program as follows:I ___________________________________________________________  RegisterI Name____Description________________________________________o) R0 General register 0. ) R1 General register 1.r . .  . .  . .aI 2-11; e f0 Components of MACRO-64 Source Statements 2.5 Symbols I ___________________________________________________________  RegisterI Name____Description________________________________________ F R29 or General register 29 or frame pointer. If you useI FP R29 as a framer pointer, Digital recommends you usenH the name FP. If you use R29 as a general register,> Digital recommends you use the name R29.F R30 or General register 30 or stack pointer. If you useI SP R30 as a stack pointer, the name SP is recommended;aH if you use R30 as a general register, the name R30% is recommended. * R31 General register 31.0 F0 Floating point register 0. . .a . .  . .aI F31_____Floating_point_register_31.________________________nB Registers are reserved names which cannot be used or' redefined in any context.i2 2.5.2 User-Defined Symbols and Macro NamesE You can use symbols to define labels, or you can equate H them to a specific value by a direct assignment statement.C (See Section 2.11.) These symbols can also be used inhC expressions. For more information on expressions, see  Section 2.8.E Use the following rules to create user-defined symbols:hE o Use alphanumeric characters, underscores (_), dollarrA signs ($), and periods (.). Any other character ' terminates the symbol.tD o The first character of a symbol cannot be a number.G o The symbol must be no more than 31 characters long andc must be unique.8 o The symbol must not be a register name. 2-12  uI Components of MACRO-64 Source StatementsiI 2.5 SymbolsoI o The symbol cannot be one of the following conditional or " macro directives:8 .ELSE .ENDC .ENDMC .ENDR .IF .IF_FALSE (.IFF)e7 .IF_TRUE (.IFT) .IF_TRUE_FALSE .IIFd) (.IFTF)O8 .INCLUDE .IRP .IRPC9 .LIBRARY .MACRO .MCALL 8 .MDELETE .MEXIT .NARG) .NCHAR .REPEAT 1 In addition, by Digital convention:sE o The dollar sign ($) is reserved for names defined bydE Digital. This convention ensures that a user-definedeA name (that does not have a dollar sign) will notsE conflict with a Digital-defined name (that does have a dollar sign).D o Do not use the period (.) in any global symbol nameF because many languages, such as FORTRAN, do not allow) periods in symbol names.aB Macro names follow the same rules and conventions asE user-defined symbols. See the description of the .MACROpI directive in Chapter 5 for more information on macro names.nH User-defined symbols and macro names do not conflict; thatI is, the same name can be used for a user-defined symbol andh a macro.' 2.5.3 Determining Symbol ValuesF The value of a symbol depends on its use in the program.I MACRO-64 uses a different method to determine the values of I symbols in the operator field than it uses to determine the5 values of symbols in the operand field.,I 2-13  u 0 Components of MACRO-64 Source Statements 2.5 SymbolsB3 2.5.3.1 Using Symbols in the Operator FieldeF A symbol in the operator field can be either a permanentD symbol or a macro name. MACRO-64 searches for a symbol0 definition in the following order: 1. Register names: R0-R31 FP SP F0-F312 2. Macro and conditional directives:4 .ELSE .ENDC .ENDM? .ENDR .IF .IF_FALSE (.IFF) 3 .IF_TRUE .IF_TRUE_FALSE .IIF4$ (.IFT) (.IFTF)4 .INCLUDE .IRP .IRPC5 .LIBRARY .MACRO .MCALLe4 .MDELETE .MEXIT .NARG$ .NCHAR .REPEAT/ 3. Previously defined macro namesiF 4. Permanent symbols (instructions and other directives)E This search order allows most permanent symbols, exceptsH registers, conditional directives and macro directives, toF be redefined as macro names. If a symbol in the operatorH field is not defined as a macro or a permanent symbol, the2 assembler displays an error message.2 2.5.3.2 Using Symbols in the Operand FieldI A symbol in the operand field must be either a user-defined : numeric symbol, a label, or a register name.I User-defined numeric symbols and labels can be either localsF (internal) symbols or global (external) symbols. WhetherG numeric symbols and labels are local or global depends on . their use in the source program.D A local numeric symbol or label can be referenced onlyD in the module in which it is defined. If local numericB symbols or labels with the same names are defined inF different modules, the symbols and labels are completely 2-14 i oI Components of MACRO-64 Source Statements I 2.5 SymbolsiG independent. The definition of a global numeric symbol ormF label, however, can be referenced from any module in the program.I MACRO-64 treats all user-defined numeric symbols and labelseI as local unless you explicitly declare them to be global by) doing one of the following:lH o Use the double colon (::) in defining a label. For more: information on labels, see Section 2.1.1.F o Use the double equal sign (==) in a direct assignmentE statement. For more information on direct assignment+. statements, see Section 2.11.E o Use the .WEAK directive. For more information on the , .WEAK directive, see .WEAK.G User-defined lexical string symbols can only be used withoC the lexical string operators. For more information onaE lexical string operators, see Chapter 3. You can defineoG a macro using the same name as a previously defined localaH numeric symbol, global numeric symbol, or a lexical stringH symbol. However, you cannot define a lexical string symbol7 and a numeric symbol using the same name. H In addition, you cannot use the same name for both a localH and global numeric symbol. Nor can you use the same symbolD name for both a numeric symbol (local or global) and a& label (local or global)./ 2.6 Temporary Labels Within Source Code_G Use temporary labels to identify addresses within a block  of source code.  Format nnnnn$:_ nnnnn ; A decimal integer in the range of 1 to 65535. I In most cases, you can use temporary labels in the same way F you use other labels that you define; however, there are some differences:oH o Temporary labels cannot be referenced outside the block; of source code in which they are declared. I 2-15   0 Components of MACRO-64 Source Statements/ 2.6 Temporary Labels Within Source CodeG o Temporary labels can be redeclared in another block of  source code.lD o Temporary labels that occur within a psect with theF MIX or NOMIX attribute, do not appear in the debuggerI symbol table and thus cannot be accessed by the symbolic I debugger. For more information on psects, see Chapter 5. ? o Temporary labels cannot be used in the .END or G .PROCEDURE_DESCRIPTOR directives. For more information 6 on the .END directive, see Chapter 5.A By convention, temporary labels are positioned like B statement labels: left-justified in the source text.D Although temporary labels can appear in the program inI any order, by convention, the temporary labels in any block C of source code should be in increasing numeric order. B Temporary labels are useful as branch addresses whenD you use the address only within the block. You can useH temporary labels to distinguish between addresses that areI referenced only in a small block of code and addresses thattG are referenced elsewhere in the module. A disadvantage oftI temporary labels is that their numeric names do not provide G any indication of their purpose. Consequently, you should G not use temporary labels to label sequences of statementsrG that are logically unrelated; user-defined symbols shouldo be used instead.C Digital recommends that users create temporary labels E only in the range of 0$ to 29999$ because the assembler D automatically creates temporary labels in the range ofI 30000$ to 65535$ for use in macros. For more information oni0 temporary labels, see Section 4.7.E The temporary label block in which a temporary label is = valid is delimited by the following statements:p7 o A user-defined label: global or local.eG o A .PSECT directive. For more information on the .PSECT* directive, see Chapter 5.D An example showing the correct and incorrect use of* temporary labels follows: 2-16 e mI Components of MACRO-64 Source StatementssI 2.6 Temporary Labels Within Source Codes& A: ADDQ R1, R2, R37 BEQ R3, 2$ ; correct use & MULQ R2, R3, R4I 2$: ADDQ R1, R4, R5 ; definition of temporary label 3 B: BNE R5, 2$ ; illegali& C: SUBQ R2, R4, R6E In this example, 2$ is a temporary label, defined inrF the block between A: and B:. The forward reference inF the second instruction is properly resolved. The lineC labeled B: also references 2$, but the label B hastE already closed the range. The temporary label 2$ canF be used later in the program, but its definition must; appear within the same block as the label.tH o The .ENABLE and .DISABLE directives, which can extend aH local label block beyond user-defined labels and .PSECTD directives. For more information on the .ENABLE and4 .DISABLE directives, see Chapter 5.G A temporary label block is usually delimited by two user-oH defined labels. However, the .ENABLE LOCAL_BLOCK directiveC starts a local block that is terminated by one of thea following:7 o A second .ENABLE LOCAL_BLOCK directiveuE o A .DISABLE LOCAL_BLOCK directive followed by a user-i4 defined label or a .PSECT directive@ Temporary labels can be preserved with the context> of the program section in which they are defined? for future reference. For more information on the F .SAVE_PSECT [LOCAL_BLOCK] and .RESTORE_PSECT directives, see Chapter 5. 2.7 Label Addresses ? In the absence of optimization and automatic data H alignment, label addresses are defined to be the psect andG offset of the current location counter (see Section 2.11)cB at the point where the label is defined. When eitherG optimization or automatic data alignment are enabled, theeH following additional considerations apply. See Section B.7G for information on optimizations and automatic alignment. I 2-17o t h0 Components of MACRO-64 Source Statements 2.7 Label Addressesi? 2.7.1 Label Addresses, Optimization, and Code Alignment F Optimization and code alignment can affect the addressesD assigned to labels defined in psects that have the EXEG and NOMIX attributes. Optimization and code alignment are H disabled by default, and can be enabled with the /OPTIMIZEH and /ALIGNMENT command-line qualifiers (see Section 1.2.1)G and the .ENABLE directive (see Section 5.1) . In general,"G the assembler assigns the psect and offset of the currentkD location counter prior to optimization or alignment ofD code labels. However, the assembler adjusts referencesD to labels in branch instructions to the address of theI label after optimization and code alignment processing. ThetF assembler does not adjust references to labels where theH label reference occurs in an expression with more than one; term. The following example illustrates this.e- .psect CODE, exe, nomixsU BSR R0, 10$ ; R0 -> 10$ (post-optimization)eT 10$: LDA R1, 20$-10$(R0) ; R1 -> 20$ (pre-optimization)" JMP (R1) [...]  20$:D In the example above, the assembler adjusts the targetF address of the BSR instruction to be the location of 10$E after optimization and code alignment have taken place.uE Thus, the branch to 10$ functions as expected. However, I when processing the LDA instruction, the assembler computeslF the offset between 20$ and 10$ prior to optimization andH code alignment. Thus, the address of 20$ that is stored inI R1 is the address prior to optimization and code alignment. G Depending on the sequence of instructions between 10$ and_E 20$, the address before optimization and code alignment E may differ from the address after optimization and code H alignment and the JMP instruction may not transfer control& to the expected address.> Note also that the assembler only performs post-G optimization adjustment of label addresses when the label_> is the only term in the expression. For example: 2-18 c tI Components of MACRO-64 Source StatementsiH 2.7 Label Addresses- .psect CODE, exe, nomix ' .base R27,LINKAGEa0 LDQ R26, ROUTINE1_ADDR( JSR R26, (R26)0 LDQ R26, ROUTINE2_ADDR( JSR R26, (R26)! RET R28r NOP  NOP  ROUTINE1:R# RET (R26)d ROUTINE2: # RET (R26) + .psect LINKAGE, noexe  LINKAGE: ROUTINE1_ADDR:' .address ROUTINE1_ ROUTINE2_ADDR:) .address ROUTINE2+0 E In the example above, the assembler adjusts the addressiH stored with the .ADDRESS ROUTINE1 directive to the addressF of label ROUTINE1 after optimization and code alignment.F However, since the expression in the .ADDRESS ROUTINE2+0D directive is not a single term, the assembler adds theH offset 0 and the address of ROUTINE2 prior to optimizationI and code alignment and stores the result. Since the addresseB stored is the address prior to optimization and codeD alignment, the second JSR instruction may not transfer6 control to the address that is expected.: 2.7.2 Label Addresses and Automatic Data Alignment? Automatic data alignment can affect the addressesoE assigned to labels in psects that have the NOEXE or MIXB attributes. Automatic data alignment is enabled withE the .ENABLE ALIGN_DATA directive or the /ALIGNMENT=dataOD command line option. For more information on automaticE alignment, see Section 5.2. For more information on the 1 .ENABLE directive, see Section 5.3. I 2-19  0 Components of MACRO-64 Source Statements 2.7 Label AddressesFC A label that occurs in a statment with a data storage.G directive is assigned the psect and offset of the storage B allocated by the data storage directive. If the dataI storage directive requires automatic alignment, the address A is assigned to the label after automatic alignment.nD The same is true of labels that occur in statements byE themselves and that are followed by a data directive iniC a subsequent statement. However, if a label occurs inoC a statement by itself and is followed by an assemblerhE directive that is not a data storage directive, a macrohA directive, or a conditional directive, the label isnC assigned the psect and offset of the current locationi7 counter prior to any automatic alignment.sF Note that the assembler only assigns addresses to labelsB after alignment under the conditions described aboveE and only with automatic alignment. If you place a labelaH before a .ALIGN directive that manually aligns the currentD location counter, the assembler assigns the address ofE the label prior to performing the manual alignment. ThemD following example illustrates the interaction of label> address assignment and automatic data alignment:& .enable align_data% .psect data,noexe X .byte 1 ; The byte is stored in psect data at offset 0U A: .print "Not aligned" ; Any non-macro, non-conditional statement, T ; including this .PRINT directive preventsA ; A from being automatically aligned -- A is = ; assigned offset 1bR B: ; B is automatically aligned to offset 4R C: .long 2 ; C is automatically aligned to offset 4] D: .align 0 ; The .ALIGN global directive prevents D from being \ ; automatically aligned -- D is assigned offset 8S E: .octa 3 ; E is automatically aligned to offset 16 C Automatic data alignment and label-address assignment D can be an important consideration when calculating theF difference between two labels. For example, consider theG following macro, which stores a string preceded by a word0 that contains the string's length: 2-20  I Components of MACRO-64 Source Statements H 2.7 Label Addresses; .macro VARYING_STRING STRING ?L1, ?L2 ) .word L2-L1p- L1: .ASCII "STRING"i L2: * .ENDM VARYING_STRINGI If an invocation of the VARYING_STRING macro is followed byeI a data storage directive that requires automatic alignment, H the VARYING_STRING macro will not store the correct string" length. For example:. .psect DATA, noexe, octa( .enable align_dataK VARYING_STRING