MACRO-64_Assembler_for_OpenVMS_AXP_Systems__________ Reference Manual Order Number: AA-PT9KB-TE November 1993 This manual describes the MACRO-64 assembly language. Revision/Update Information: This manual supersedes the MACRO-64 Assembler for OpenVMS AXP Systems Reference Manual (Order Number AA-PT9KA-TE). Software Version: MACRO-64 Assembler for OpenVMS AXP Systems Version 1.1 Operating System and Version: OpenVMS AXP Version 1.5 or higher Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ First printing, November 1992 Revised, November 1993 Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. © Digital Equipment Corporation 1992, 1993. All Rights Reserved. The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: Alpha AXP, AXP, DEC, DECmigrate, DECwindows, Digital, OpenVMS, VAX, VAX MACRO, VMS, and the DIGITAL logo. The following is a third-party trademark: OSF/1 is a registered trademark of the Open Software Foundation, Inc. ZK6338 This document is available on CD-ROM. This document was prepared using VAX DOCUMENT Version 2.1. _________________________________________________________________ Contents Preface................................................... xi 1 Introduction 1.1 Language Features............................. 1-1 1.1.1 Alpha AXP Native-Mode Instructions........ 1-1 1.1.2 Direct Assignment Statements.............. 1-2 1.1.3 Assembler Directives...................... 1-2 1.1.3.1 General Assembler Directives............ 1-2 1.1.3.2 Macro Directives........................ 1-2 1.2 Invoking MACRO-64 on OpenVMS Systems.......... 1-3 1.2.1 Command-Line Qualifiers................... 1-3 2 Components of MACRO-64 Source Statements 2.1 Source Statement Format....................... 2-1 2.1.1 Label Field............................... 2-3 2.1.2 Operator Field............................ 2-4 2.1.3 Operand Field............................. 2-5 2.1.4 Comment Field............................. 2-5 2.2 Character Set................................. 2-6 2.3 Numbers....................................... 2-8 2.3.1 Integers.................................. 2-8 2.3.2 Floating-Point Numbers.................... 2-9 2.4 Quoted Literals............................... 2-10 2.5 Symbols....................................... 2-11 2.5.1 Permanent Symbols......................... 2-11 2.5.2 Predefined Symbols........................ 2-11 2.5.3 User-Defined Symbols and Macro Names...... 2-13 2.5.4 Determining Symbol Values................. 2-14 2.5.4.1 Using Symbols in the Operator Field..... 2-14 2.5.4.2 Using Symbols in the Operand Field...... 2-15 2.6 Temporary Labels Within Source Code........... 2-16 iii 2.7 Label Addresses .............................. 2-18 2.7.1 Label Addresses, Optimization, and Code Alignment................................. 2-18 2.7.2 Label Addresses and Automatic Data Alignment ................................ 2-20 2.8 Terms and Expressions......................... 2-22 2.9 Unary Operators for Terms and Expressions..... 2-25 2.9.1 Radix Control Operators................... 2-26 2.9.2 Numeric Complement Operator............... 2-27 2.10 Binary Operators.............................. 2-28 2.10.1 Arithmetic Shift Operator................. 2-29 2.10.2 Logical AND Operator...................... 2-29 2.10.3 Logical Inclusive OR Operator............. 2-29 2.10.4 Logical Exclusive OR Operator............. 2-29 2.11 Direct Assignment Statements.................. 2-30 2.12 Current Location Counter...................... 2-31 3 MACRO-64 Lexical Operators 3.1 Processing with Lexical Operators............. 3-1 3.2 Lexical Operator Syntax....................... 3-1 3.3 Numeric Symbols and Lexical String Symbols.... 3-4 3.4 Lexical Substitution Operator................. 3-4 3.5 Lexical Escape Operator....................... 3-5 3.6 Using Lexical Operators....................... 3-7 3.7 Lexical Operators............................. 3-10 %EDIT............................................... 3-11 %ELEMENT............................................ 3-13 %EXTRACT............................................ 3-14 %FREG............................................... 3-15 %INTEGER............................................ 3-16 %IREG............................................... 3-17 %LENGTH............................................. 3-18 %LOCATE............................................. 3-19 iv %REPEAT............................................. 3-20 %STRING............................................. 3-21 %TIME............................................... 3-22 %TYPE............................................... 3-23 4 Macro Arguments 4.1 Using Macro Arguments......................... 4-2 4.2 Using Default Values.......................... 4-3 4.3 Using Keyword Arguments....................... 4-3 4.4 Using String Arguments........................ 4-5 4.5 Argument Concatenation........................ 4-9 4.6 Passing Numeric Values of Symbols............. 4-9 4.7 Using Created Temporary Labels................ 4-10 5 MACRO-64 Assembler Directives 5.1 Program Sections.............................. 5-1 5.2 Automatic Data Alignment...................... 5-3 5.3 Directives.................................... 5-4 .ADDRESS............................................ 5-9 .ALIGN.............................................. 5-10 .ASCIC.............................................. 5-13 .ASCID.............................................. 5-14 .ASCII.............................................. 5-16 .ASCIZ.............................................. 5-17 .BASE............................................... 5-18 .BEGIN_EXACT........................................ 5-22 .BLKx............................................... 5-24 .BYTE............................................... 5-27 .CODE_ADDRESS....................................... 5-28 .D_FLOATING......................................... 5-29 .DEFINE_FREG........................................ 5-31 v .DEFINE_IREG........................................ 5-34 .DISABLE............................................ 5-36 .ELSE............................................... 5-37 .ENABLE............................................. 5-39 .END................................................ 5-51 .ENDC............................................... 5-53 .ENDM............................................... 5-54 .ENDR............................................... 5-55 .END_EXACT.......................................... 5-56 .ERROR.............................................. 5-57 .EVEN............................................... 5-58 .EXTERNAL........................................... 5-59 .F_FLOATING......................................... 5-60 .G_FLOATING......................................... 5-62 .IDENT.............................................. 5-63 .IF................................................. 5-64 .IF_x............................................... 5-71 .IIF................................................ 5-75 .INCLUDE............................................ 5-77 .INSTRUCTION........................................ 5-78 .IRP................................................ 5-80 .IRPC............................................... 5-83 .LIBRARY............................................ 5-86 .LINKAGE_PAIR....................................... 5-88 .LIST............................................... 5-90 .LOCAL_CODE_ADDRESS................................. 5-91 .LOCAL_LINKAGE_PAIR................................. 5-92 .LOCAL_PROCEDURE_DESCRIPTOR......................... 5-93 .LONG............................................... 5-95 .MACRO.............................................. 5-96 vi .MCALL.............................................. 5-100 .MDELETE............................................ 5-101 .MEXIT.............................................. 5-102 .NARG............................................... 5-105 .NCHR............................................... 5-107 .NLIST.............................................. 5-109 .NOSHOW............................................. 5-110 .OCTA............................................... 5-111 .ODD................................................ 5-113 .PACKED............................................. 5-114 .PAGE............................................... 5-115 .PRINT.............................................. 5-116 .PROCEDURE_DESCRIPTOR............................... 5-117 .PSECT.............................................. 5-119 .QUAD............................................... 5-126 .REPEAT............................................. 5-127 .RESTORE_PSECT...................................... 5-130 .SAVE_PSECT......................................... 5-132 .S_FLOATING......................................... 5-133 .SHOW............................................... 5-134 .SIGNED_BYTE........................................ 5-137 .SIGNED_WORD........................................ 5-138 .SUBTITLE........................................... 5-139 .T_FLOATING......................................... 5-140 .TITLE.............................................. 5-141 .UNDEFINE_REG....................................... 5-143 .WARN............................................... 5-144 .WEAK............................................... 5-145 .WORD............................................... 5-147 6 MACRO-64 Supplied Macros 6.1 MACRO-64 Supplied Library..................... 6-1 6.2 Routines and Lexical Scope.................... 6-2 6.2.1 Routines and Program Sections............. 6-2 6.3 Using Macros to Control Program Sections...... 6-3 6.3.1 Defining Program Sections................. 6-3 6.3.2 Using Macro-Defined Symbols............... 6-4 6.3.3 Defining Procedure Type................... 6-5 vii 6.3.4 Using Macros in Prologue Sections......... 6-6 6.3.5 Using Macros in Epilogue Sections......... 6-6 6.4 Programming Examples Using Supplied Macros.... 6-7 6.5 Using the $CALL Macro......................... 6-8 6.5.1 Using $CALL in Source Code................ 6-10 6.6 Programming Considerations.................... 6-11 6.6.1 Making Multiple Calls From the Same Routine................................... 6-11 6.6.2 Nonstandard Linkage....................... 6-11 6.6.3 Routine Restrictions...................... 6-12 6.7 Macro Descriptions and Syntax Rules........... 6-12 $BEGIN_EPILOGUE..................................... 6-13 $CALL............................................... 6-15 $CODE_SECTION ...................................... 6-23 $DATA_SECTION....................................... 6-24 $END_EPILOGUE....................................... 6-25 $END_PROLOGUE....................................... 6-27 $END_ROUTINE........................................ 6-28 $LINKAGE_PAIR....................................... 6-29 $LINKAGE_SECTION.................................... 6-31 $OPDEF.............................................. 6-32 .PACKED............................................. 6-38 $PROCEDURE_DESCRIPTOR............................... 6-41 $RESET_LP_LIST...................................... 6-42 $RETURN............................................. 6-44 $ROUTINE............................................ 6-45 A MACRO-64 Alpha AXP Architecture Quick Reference A.1 Register Usage Conventions.................... A-3 A.2 Instruction Operand Notation.................. A-3 A.3 Instruction Qualifier Notation................ A-4 A.4 F-P Control Register (FPCR) Format............ A-5 A.5 Decodable Pseudo-Operations................... A-6 A.6 Common Architecture Opcodes in Numerical Order......................................... A-7 A.7 OpenVMS PALcode Instruction Summary........... A-14 A.8 PALcode Opcodes in Numerical Order............ A-17 A.9 Common Architecture Instructions.............. A-19 viii B Programming with MACRO-64 B.1 MACRO-64 Programming Hints.................... B-1 B.1.1 STARLET.MLB Migration Macros.............. B-2 B.1.2 Integer Division.......................... B-3 B.1.3 User-Defined Register Symbols and Macros.................................... B-3 B.2 The OpenVMS Calling Standard.................. B-3 B.2.1 Effects on Assembly-Time when Using Calling-Standard Macros................... B-4 B.3 Accessing Memory with Base Registers.......... B-5 B.4 Types of Data Structures...................... B-9 B.4.1 Procedure Descriptor...................... B-10 B.4.2 Signature Block........................... B-11 B.4.3 Linkage Pair.............................. B-11 B.5 Types of Routines............................. B-13 B.5.1 Routine Capabilities...................... B-14 B.5.2 Entry Prologue and Exit Epilogue Sequences................................. B-15 B.6 Establishing Self-Addressability.............. B-16 B.7 Optimization and Automatic Alignment.......... B-18 B.7.1 Automatic Data Alignment.................. B-18 B.7.1.1 Controlling Data Alignment.............. B-19 B.7.1.2 Directives for Automatic Data Alignment............................... B-19 B.7.2 Automatic Code Label Alignment............ B-21 B.7.3 Scheduling Optimization................... B-21 B.7.4 Peephole Optimization..................... B-22 B.7.5 Using MACRO-64 for Performance............ B-22 B.7.6 Viewing Optimization Results.............. B-23 C Using LSE with MACRO-64 C.1 Invoking LSE.................................. C-1 C.2 Running Diagnostics........................... C-2 D Differences from VAX MACRO D.1 Assembler Features in MACRO-64................ D-1 D.2 VAX MACRO Features Not Present in MACRO-64.... D-6 ix E Error Messages F MACRO-64 Listing Format Index Examples 3-1 Lexical Processing Without the Escape Operator.................................. 3-6 3-2 Lexical Processing with Escape Operator... 3-6 3-3 Using Lexical Operators................... 3-7 3-4 Source Statements After Macro Expansion... 3-9 6-1 Program Using Supplied Macros............. 6-7 6-2 Program Using $CALL....................... 6-10 B-1 Routine Call Example...................... B-5 B-2 Routine Without Linkage Pairs............. B-11 B-3 Routine With Linkage Pairs................ B-12 B-4 Establishing a Base Address............... B-17 B-5 Enabling and Disabling Data Alignment..... B-19 F-1 Main Source File.......................... F-1 F-2 Include Source File....................... F-2 F-3 Example Listing Output.................... F-2 Figures A-1 Data Structures........................... A-1 A-2 Instruction Formats....................... A-2 Tables 2-1 Using Tab Stops in Statement Fields....... 2-2 2-2 Special Characters Used in MACRO-64 Statements................................ 2-7 2-3 Summary of Unary Operators................ 2-26 2-4 Summary of Binary Operators............... 2-28 3-1 Summary of MACRO-64 Lexicals.............. 3-10 3-2 %TYPE Attributes.......................... 3-23 x 5-1 Summary of General Assembler Directives... 5-4 5-2 Summary of Macro Directives............... 5-7 5-3 .ENABLE and .DISABLE Symbolic Arguments... 5-39 5-4 Condition Tests for Conditional Assembly Directives................................ 5-65 5-5 Program Section Attributes................ 5-120 5-6 Default Program Section Attributes........ 5-123 5-7 .SHOW and .NOSHOW Symbolic Arguments...... 5-134 6-1 ARGS Arguments............................ 6-17 A-1 Register Usage Conventions for OpenVMS AXP....................................... A-3 A-2 Instruction Operand Notation.............. A-4 A-3 Instruction Qualifier Notation............ A-5 A-4 F-P Control Register (FPCR) Format........ A-5 A-5 Decodable Pseudo-Operations............... A-6 A-6 Common Architecture Opcodes in Numerical Order..................................... A-7 A-7 OpenVMS Unprivileged PALcode Instructions.............................. A-14 A-8 OpenVMS Privileged PALcode Instructions... A-15 A-9 PALcode Opcodes in Numerical Order........ A-17 A-10 Common Architecture Instructions.......... A-20 B-1 Frame Attributes.......................... B-15 B-2 Directives Using Automatic Alignment...... B-19 xi _________________________________________________________________ Preface This manual describes the MACRO-64 assembly language. Intended Audience This manual is intended for all programmers writing MACRO- 64 programs. Before reading this manual, you should be familiar with assembly language programming, the Alpha AXP architecture and instruction set, and the operating system in use on your AXP system. Document Structure This manual contains the following chapters and appendices: o Chapter 1 introduces the features of the MACRO-64 language. o Chapter 2 describes the format of the MACRO-64 source statements. o Chapter 3 describes the MACRO-64 lexical operators. It also discusses differences and similarities between the VAX MACRO string operators and those of MACRO-64. o Chapter 4 describes the arguments used with macros. o Chapter 5 describes the MACRO-64 general assembler directives and the directives used in defining and expanding macros. o Chapter 6 describes the macros provided with the MACRO- 64 assembler. o Appendix A provides a quick reference to the Alpha AXP architecture as it relates to the MACRO-64 programming language. For more information, see the Alpha Architecture Handbook. xi o Appendix B provides information on how to program more effectively using the MACRO-64 assembler. o Appendix C explains how to invoke the DEC Language- Sensitive Editor (LSE) with the MACRO-64 language. o Appendix D describes the differences between VAX MACRO and MACRO-64 features. o Appendix E describes the error messages produced by the MACRO-64 assembler. o Appendix F provides a MACRO-64 binary listing format example. Associated Documents For more information on MACRO-64, see the following guide in this documentation set: o MACRO-64 Assembler for OpenVMS AXP Systems Installation Guide For more information on the Alpha AXP architecture, see the following: o Alpha Architecture Reference Manual o Alpha Architecture Handbook o Alpha AXP Achitecture Quick Reference Guide o OpenVMS Calling Standard Conventions In this manual, every use of Alpha VMS means the OpenVMS AXP operating system, every use of VAX VMS means the OpenVMS VAX operating system, and every use of VMS means both the OpenVMS AXP operating system and the OpenVMS VAX operating system. The following conventions are used in this manual: Ctrl/x A sequence such as Ctrl/x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button. xii PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1, then press and release another key or a pointing device button. In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) . . . A horizontal ellipsis in examples indicates one of the following possibilities: o Additional optional arguments in a statement have been omitted. o The preceding item or items can be repeated one or more times. o Additional parameters, values, or other information can be entered. . A vertical ellipsis indicates the omission . of items from a code example or command . format; the items are omitted because they are not important to the topic being discussed. ( ) In format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses. [ ] In format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in a VMS file specification, or in the syntax of a substring specification in an assignment statement.) { } In format descriptions, braces surround a required choice of options; you must choose one of the options listed. xiii boldface text Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason. italic text Italic text emphasizes important information, indicates variables, and indicates complete titles of manuals. Italic text also represents information that can vary in system messages (for example, Internal error number), command lines (for example, /PRODUCER=name), and command parameters in text. UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. - A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows. numbers All numbers in text are assumed to be decimal, unless otherwise noted. Nondecimal radixes-binary, octal, or hexadecimal-are explicitly indicated. mouse The term mouse refers to any pointing device, such as a mouse, a puck, or a stylus. MB1, MB2, MB3 MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The buttons can be redefined by the user.) PB1, PB2, PB3, PB1, PB2, PB3, and PB4 indicate buttons on PB4 the puck. SB, SB SB and SB indicate buttons on the stylus. MACRO-64 MACRO-64 refers to MACRO-64 Assembler for OpenVMS AXP Systems. xiv 1 _________________________________________________________________ Introduction MACRO-64 Assembler for OpenVMS AXP Systems is an assembly language for programming Alpha AXP computers. Source programs written in MACRO-64 are translated into object (or binary) code by the MACRO-64 assembler, which produces an object module and, optionally, a listing file. The features of the language are introduced in this chapter, as well as instructions to invoke the assembler. 1.1 Language Features MACRO-64 source programs consist of a sequence of source statements. These source statements may be any of the following: o Alpha AXP native-mode instructions o Direct assignment statements o Assembler directives 1.1.1 Alpha AXP Native-Mode Instructions Instructions manipulate data. They perform such functions as addition, data conversion, and transfer of control. Instructions are usually followed in the source statement by operands, which can be any kind of data needed for the operation of the instruction. For a brief description of the Alpha instruction set, see Appendix A. For a more detailed description of the Alpha native-mode instruction set, see the Alpha Architecture Reference Manual or the Alpha Architecture Handbook. Introduction 1-1 1.1.2 Direct Assignment Statements Direct assignment statements equate symbols to values. For more information on direct assignment statements, see Section 2.11. 1.1.3 Assembler Directives Assembler directives guide the assembly process and provide tools for using the instructions. For more information on assembler directives, see Chapter 5. There are two classes of assembler directives: general assembler directives and macro directives. 1.1.3.1 General Assembler Directives You can use general assembler directives to perform the following operations: o Store data or reserve memory for data storage o Control the alignment of parts of the program in memory o Specify the methods of accessing the sections of memory in which the program will be stored o Specify a procedure in the program o Specify the way in which symbols will be referenced o Specify that a part of the program is to be assembled only under certain conditions o Display informational and diagnostic messages o Control the assembler options that are used to interpret the source program 1.1.3.2 Macro Directives Macro directives are used to define macros and repeat blocks. They allow you to repeat identical or similar sequences of source statements throughout a program without rewriting those sequences. Use of macros and repeat blocks helps minimize programmer errors and speeds the debugging process. 1-2 Introduction 1.2 Invoking MACRO-64 on OpenVMS Systems To invoke MACRO-64, enter the MACRO command and the /Alpha_ AXP command-line qualifier, using the following syntax: MACRO/Alpha_AXP file-spec[, . . . ] You must specify the /Alpha_AXP command-line qualifier before any other command-line parameters, qualifiers, or file specifications. file-spec[, . . . ] If you do not specify a file type for an input file, the assembler uses the default file type of .M64. You can specify one or more source files to be assembled. To assemble files individually, separate the file specifications with commas. To concatenate and assemble the files as a single input file, separate the file specifications with plus signs (+). Command-line qualifiers control special assembler options. Assembler options can apply to the entire MACRO/Alpha_AXP command-line, or to the individual file being assembled. When the qualifier follows the MACRO/Alpha_AXP command, it applies to all files listed. For more information on command-line qualifiers, see Section 1.2.1. 1.2.1 Command-Line Qualifiers This section describes the command qualifiers used with the MACRO/Alpha_AXP command. /[NO]ALIGNMENT=option Controls the alignment of code and data. Valid options are: ___________________________________________________________ Option____Function_________________________________________ CODE Alignment of certain branch target labels. DATA______Natural_alignment_of_data_items._________________ If you omit the qualifier from the command line, the default options are /NOALIGNMENT=(CODE, DATA). If more Introduction 1-3 than one option is specified, the options must be enclosed in parentheses and separated by a comma. /[NO]DEBUG[=(options)] Specifies DEBUG support. Valid options are: ___________________________________________________________ Option____Function_________________________________________ SYMBOL Generates debug symbol information. TRACEBACK Generates traceback information. ALL Generates all previous debug information. NONE______Generates_no_debug_information.__________________ The default qualifier is /NODEBUG. When you specify /DEBUG with no options, the default option is /DEBUG=ALL. /[NO]DEFINE=(symbol [=[=]value],...) Performs the same function as direct symbol assignment in your source program. That is, the /DEFINE qualifier defines a numeric symbol. For additional information, see Section 2.11. The Digital Command Language (DCL) converts all input to uppercase unless you enclose it within quotation marks. Use a single equal sign between the symbol and the value to define a local symbol. Use two equal signs between the symbol and the value to define a global symbol. The final value of a global symbol is output to the object module and is available during the linking process. A local symbol is only available during the assembly process. You cannot define a lexical string symbol with /DEFINE. The value you specify for a symbol must be an integer literal. You can specify this value using a binary, octal, decimal, or hexadecimal radix. The default radix is decimal. To specify an alternate radix, use the format described in Section 2.9.1. If you specify an alternate radix, you must use MACRO-64 radix syntax, not DCL radix syntax. If you do not specify a value for the symbol, it defaults to 1. 1-4 Introduction The simplest form of a /DEFINE definition is as follows: /DEFINE=TRUE This definition is equivalent to the following definition: TRUE=1 You can also specify more than one symbol definition as with the following command: /DEFINE=(CHIP==21064,UNROLL=4) This definition is equivalent to the following definitions: CHIP==21064 UNROLL=4 When more than one /DEFINE qualifier is present on the MACRO command line or in a single assembly unit, the assembler uses only the last one. The default qualifier is /NODEFINE. /[NO]DIAGNOSTIC[=file-spec] Controls whether diagnostics are created and stored in the specified optional file. If a file specification is not supplied, the assembler creates a diagnostic file using the same name as the source file. For example, if you use a source file named XXX.M64, the assembler creates a diagnostic file named XXX.DIA. You can use the diagnostic file with other Digital layered products including, but not limited to, the DEC Language-Sensitive Editor (LSE). The default qualifier is /NODIAGNOSTIC. /ENVIRONMENT=[NO]FLOAT Controls whether the assembler generates floating-point instructions when optimizing code and performing code-label alignment. Currently, the only floating-point instruction generated by the assembler during optimization and alignment processing is FNOP, the floating-point no-operation instruction. If you specify /ENVIRONMENT=NOFLOAT, the assembler does not generate any floating-point instructions as part of Introduction 1-5 optimization and alignment processing. Floating-point instructions that you specify in your source program are unaffected. /LIBRARY Searches macro libraries in the following order: 1. The library designated by the /LIBRARY qualifier. 2. The .LIBRARY directives. 3. The MACRO64.MLB library. The assembler searches for the MACRO64.MLB macro library in the following locations: MACRO64$LIBRARY, ALPHA$LIBRARY, and finally SYS$LIBRARY. 4. The STARLET.MLB library. The assembler searches for the STARLET.MLB macro library in the following locations: MACRO64$LIBRARY, ALPHA$LIBRARY, and finally SYS$LIBRARY. In addition, you can place the macro library definitions in the listing file by using the command-line qualifier /SHOW=LIBRARY. /[NO]LIST[=file-spec] Controls whether a listing is created and optionally provides an output file specification for the listing file. Do not use wildcard characters in this file specification. If you enter the MACRO/Alpha_AXP command interactively, the default qualifier is /NOLIST. The assembler sends output to the current output device rather than to a listing file. If you execute the MACRO/Alpha_AXP command in a batch job, the default qualifier is /LIST. If you do not specify a file specification, the assembler creates a listing file using the same name as the source file. For example, if you use a source file named XXX.M64, the assembler creates a listing file named XXX.LIS. 1-6 Introduction /[NO]MACHINE_CODE Produces a binary machine code listing after the source text if a listing file is requested. The default qualifier is /NOMACHINE_CODE. /NAMES=case_option Specifies the alphabetic casing of identifiers in source code statements. Valid options are: ___________________________________________________________ Option____Function_________________________________________ UPPER_ Converts all identifiers to upper alphabetic CASE case. LOWER_ Converts all identifiers to lower alphabetic CASE case. AS_IS Causes all identifiers to remain in the case used __________in_source_statements.____________________________ If you use the /NAMES qualifier in a command line, you must supply a case_option. If you omit the qualifier from the command line, the default option is /NAMES=UPPER_CASE. /[NO]OBJECT[=file-spec] Controls whether an object file is created and optionally provides a file specification. Do not use wildcard characters in this file specification. If you do not specify a file specification, the assembler creates an object file using the same name as the source file. For example, if you use a source file named XXX.M64, the assembler creates an object file named XXX.OBJ. The default qualifier is /OBJECT. /[NO]OPTIMIZE[=(option-list)] Introduction 1-7 Specifies optional assembler optimizations. Valid items in the option-list are: ___________________________________________________________ Option____Function_________________________________________ SCHEDULE Specifies instruction scheduling. PEEPHOLE__Specifies_peepholing.____________________________ Specifying /OPTIMIZE with no options is the same as specifying /OPTIMIZE=(PEEPHOLE,SCHEDULE). The default qualifier is /NOOPTIMIZE. See Section B.7 for information on optimizations. /PREPROCESSOR_ONLY [=filespec] Causes the assembler to output a source file that is the result of the input source file after preprocessing. Suppresses diagnostic messages and does not produce diagnostic (.ANA) or object (.OBJ) files. The default option, /NOPREPROCESSOR_ONLY-MACRO-64, assembles your source files normally. If you specify /PREPROCESSOR_ONLY without a file specification argument, the output file name defaults to the name of the primary source input file. The output file type defaults to .ASM. The following MACRO-64 directives are executed by the preprocessor and screened from the preprocessor output file: .DISABLE PREPROCESSOR_OUTPUT .ENABLE PREPROCESSOR_OUTPUT .IF .ELSE .ENDC .IIF .IF_FALSE .IF_TRUE .IF_TRUE_FALSE .INCLUDE .LIBRARY .IRP 1-8 Introduction .IRPC .REPEAT .ENDR .MACRO .ENDM .MCALL .MDELETE .MEXIT .NARG .NCHR Include files are inserted in place of the .INCLUDE directive into the preprocessor output file. Macro definitions and repeat block definitions are screened from the preprocessor output file. Macro expansion lines and repeat block expansion lines are inserted in place of the macro invocation line or repeat block, respectively, into the preprocessor output file. Lexical string-symbol assignment statements are screened from the preprocessor output file. Lines containing lexical operators are replaced with their equivalents after lexical operator processing. Lexical line continuations are processed into a single, uncontinued line. All other language elements, including directives not previously listed, label definitions, direct numeric-symbol assignments, and so forth are passed through unchanged to the preprocessor output file. For more information, see the description of the PREPROCESSOR_OUTPUT option with the .ENABLE directive in Chapter 5. /[NO]SHOW=(item,...) Modifies the output listing file. This qualifier is meaningful only when /LIST is specified. Valid items are: Introduction 1-9 ___________________________________________________________ Option___________Function__________________________________ BINARY Lists macro expansions that generate binary code. BINARY is a subset of EXPANSIONS. CONDITIONALS Shows sections of code conditionally skipped. EXPANSIONS Shows macro expansions. INCLUDE Shows all .INCLUDE files. LIBRARY__________Shows_macro_library_modules.______________ The default option is /SHOW=CONDITIONALS. /[NO]WARNINGS=(option-list) Controls the severity level of messages and diagnostics. Valid options are: ___________________________________________________________ Option____________Function_________________________________ WARNINGS Display/suppress warnings. INFORMATIONALS Display/suppress informationals. ALL Display/suppress warnings and informationals. NONE______________Display/suppress_nothing.________________ The default options are /WARNINGS=(WARNINGS,INFORMATIONALS). If more than one option is specified, options must be enclosed in parentheses separated by a comma. 1-10 Introduction 2 _________________________________________________________________ Components of MACRO-64 Source Statements A source program consists of a sequence of source statements that the assembler interprets and processes, one at a time, generating object code or performing a specific assembly-time process. A source statement can occupy one source line or can extend onto several source lines. This chapter describes the format of the source statement and the following components: o Character set (Section 2.2) o Numbers (Section 2.3) o Quoted literals (Section 2.4) o Symbols (Section 2.5) o Temporary labels (Section 2.6) o Label addresses (Section 2.7) o Terms and expressions (Section 2.8) o Unary operators (Section 2.9) o Binary operators (Section 2.10) o Direct assignment statements (Section 2.11) o Current location counter (Section 2.12) 2.1 Source Statement Format MACRO-64 source statements can have a maximum of four fields, as follows: o Label field-Symbolically defines a location in a program. Components of MACRO-64 Source Statements 2-1 o Operator field-Specifies the action to be performed by the statement; this can be an instruction, an assembler directive, or a macro call. o Operand field-Contains the instruction operands or the assembler directive arguments or the macro arguments. o Comment field-Contains a comment that explains the meaning of the statement; this does not affect program execution. You can separate statement fields by either a space or a tab stop, but Digital recommends that you format statements with the Tab key to ensure consistency and clarity. See Table 2-1. Table_2-1_Using_Tab_Stops_in_Statement_Fields______________ Column in Which Field Field______Begins_____Tab_Stops_to_Reach_Column____________ Label 1 0 Operator 9 1 Operand 17 2 Comment____41_________5____________________________________ The following example shows a typical source statement: EXP: .BLKL 50 ; Table stores expected values Rules for Coding Source Statements The following rules apply for coding source statements: o You can continue a single statement on several lines by using a hyphen (-) as the last nonblank character before the comment field, or at the end of line (when there is no comment). o In most cases, you can continue a statement at any point. If a symbol name is continued and the first character on the second line is a tab or a blank, the symbol name is terminated at that character. For information on using symbols, see Section 2.5. 2-2 Components of MACRO-64 Source Statements o Blank lines are legal, but they have no significance in the source program except that they terminate a continued line. The following sections describe each of the statement fields in detail. 2.1.1 Label Field A label is a user-defined symbol that identifies a location in the program. The symbol is assigned a value equal to the location counter where the label occurs. The following rules apply when coding source statements with labels: o If a statement contains a label, the label must be in the first field on the line. o The user-defined symbol name can be up to 31 characters long and can contain any alphanumeric character, as well as the underscore (_), dollar sign ($), and period (.) characters. o If a label extends past column 7, Digital recommends you place it on a line by itself so that the following operator field can start in column 9 of the next line. o A label is terminated by a colon (:) or a double colon (::). In the following source statement, EXP: is the label field: EXP: .BLKL 50 ; Table stores expected values See Section 2.5.3 for a description of the rules for forming user-defined symbol names. There are three types of labels: o Global labels-Can be referenced by other object modules and are defined using a double colon (::). o Local labels-Can be referenced only within the current module and are defined using a single colon (:). o Temporary labels-Can be referenced only within the bounds of either two local labels, two global labels, two psects (program sections), or within the bounds of a temporary label scope, as defined by .ENABLE LOCAL_BLOCK and .DISABLE LOCAL_BLOCK. Temporary labels are defined using one to five digits followed by a dollar sign Components of MACRO-64 Source Statements 2-3 and a single colon ($:). See Section 2.6 for further information. The following example shows how these labels appear in use: EXP: .BLKL 50 ; EXP is a local label used to ; identify a 50-word block of storage DATA:: .BLKW 25 ; DATA is a global label used to ; identify a 25-word block of storage 10$: .BLKW 5 ; 10$ is a temporary label used to ; identify a five word block of ; storage. 2.1.2 Operator Field The operator field specifies the action to be performed by the statement. This field can contain an instruction, an assembler directive, or a macro call. If the operator is: o An instruction, MACRO-64 generates the binary code for that instruction in the object module. The instructions are listed in Appendix A. o A directive, MACRO-64 performs certain control actions or processing operations during source program assembly. The assembler directives are described in Chapter 5. o A macro call, MACRO-64 expands the macro. Macro calls are described in Chapter 4 and in Chapter 5 (.MACRO directive). Macros supplied with MACRO-64 are described in Chapter 6. Use either a space or a tab stop to terminate the operator field; however, Digital recommends that you use the tab stop to terminate the operator field. In the following source statement, .BLKL is the operator field: EXP: .BLKL 50 ; Table stores expected values 2-4 Components of MACRO-64 Source Statements 2.1.3 Operand Field The operand field can contain operands for instructions or arguments for either assembler directives or macro calls. Operands for instructions identify the memory locations or the registers that are used by the machine operation. The operand field for a specific instruction must contain the correct number and type of operands required by that instruction. Arguments for a directive must meet the format requirements of that directive. Chapter 5 describes the directives and the format of their arguments. Operands for a macro must meet the requirements specified in the macro definition. See the description of the .MACRO directive in Chapter 5. Use a comma (,) to separate operands for instructions and directives. (See Section 2.8 for a discussion of expressions.) The semicolon that starts the comment field terminates the operand field. If a line does not have a comment field, the operand field is terminated by the end of the line. In the following source statement example, 50 is the operand field supplied to the operator field, .BLKL: EXP: .BLKL 50 ; Table stores expected values 2.1.4 Comment Field The comment field contains text that explains the function of the statement. You can use comments to describe algorithms, reasons for selecting particular methods, and parameters passed to routines. Comments do not affect assembly processing or program execution. The comment field must be preceded by a semicolon (;) and can contain any printable ASCII character. It is terminated by the end of the line. A comment can appear on a line by itself. If a comment does not fit on one line, it can be continued on the next, but the continuation must be preceded by another semicolon. Components of MACRO-64 Source Statements 2-5 In the following source statement example, "Table stores expected values" is the comment field. Note that the comment field begins with a semicolon. EXP: .BLKL 50 ; Table stores expected values 2.2 Character Set When coding source statements, you need to be aware of what characters are acceptable to the assembler, and how the assembler interprets them. The following numbers and characters are accepted by the assembler: o The letters of the alphabet, A to Z, uppercase and lowercase. By default, the assembler converts all lowercase letters to uppercase. This means it considers lowercase letters equivalent to uppercase letters. The assembler can operate in a case-sensitive mode. In case-sensitive mode, the assembler does not convert lowercase letters to uppercase letters. On OpenVMS and OpenVMS AXP systems, you can select case-sensitive mode from the command line with the /NAMES=AS_IS qualifier. o The digits 0 to 9. o The special characters listed in Table 2-2. 2-6 Components of MACRO-64 Source Statements Table_2-2_Special_Characters_Used_in_MACRO-64_Statements___ Character ___CharacteName________Function____________________________ _ Underscore Character in symbol names. $ Dollar Character in symbol names. sign . Period Character in symbol names, current location counter, and decimal point. : Colon Local label terminator. :: Double Global label terminator. colon = Equal sign Local direct assignment operator and macro keyword argument terminator. == Double Global direct assignment operator. equal sign # Number Literal value indicator. sign @ At sign Arithmetic shift operator. ; Semicolon Comment field indicator. + Plus sign Unary plus operator and arithmetic addition operator. - Minus sign Unary minus operator, arithmetic or subtraction operator, and line hyphen continuation indicator. * Asterisk Arithmetic multiplication operator. / Slash Arithmetic division operator. & Ampersand Logical AND operator. ! Exclamation Logical inclusive OR operator. point \ Backslash Logical exclusive OR and numeric conversion indicator in macro arguments. ^ Circumflex Unary operators and macro argument delimiter. (continued on next page) Components of MACRO-64 Source Statements 2-7 Table 2-2 (Cont.) Special Characters Used in MACRO-64 __________________Statements_______________________________ Character ___CharacteName________Function____________________________ ( ) Parentheses Displacement and register field delimiter in an instruction operand. Argument delimiter to a lexical operator. <> Angle Argument or expression grouping brackets delimiters. ? Question Created local label indicator in mark macro arguments. ' Apostrophe Macro argument concatenation indicator. " Double Quoted literal delimiter. quote % Percent Delimits the beginning of a lexical sign operator. (space) Space or Separates source statement fields. tab Spaces within expressions are (tab) otherwise ignored. , Comma Separates symbolic arguments within the operand field. Multiple expressions in the operand field _______________________must_be_separated_by_commas.________ 2.3 Numbers Numbers can be integers or floating-point numbers. The following sections describe these types of numbers. 2.3.1 Integers You can use integers in any expression, including expressions in operands and in direct assignment statements. For information on expressions, see Section 2.8. FORMAT snn 2-8 Components of MACRO-64 Source Statements s An optional sign: plus sign (+) for positive numbers (the default), or minus sign (-) for negative numbers. nn A string of numeric characters that is legal for the specified radix. MACRO-64 interprets all integers in the source program as decimal unless the number is preceded by a radix control operator. For more information on radix control operators, see Section 2.9.1. Integers must be in the range of -263 to +263-1 for signed data or in the range of 0 to 264-1 for unsigned data. Negative numbers must be preceded by a minus sign; MACRO- 64 translates such numbers into two's complement form. In positive numbers, the plus sign is optional. 2.3.2 Floating-Point Numbers You can use a floating-point number in the .DOUBLE, .FLOAT, .F_FLOATING, .D_FLOATING, .G_FLOATING, .S_FLOATING, and .T_FLOATING directives. For more information on directives, see Chapter 5. You cannot use a floating-point number in an expression or with a unary or binary operator except the unary plus and unary minus. For information on unary and binary operators, see Section 2.9 and Section 2.10. You can specify a floating-point number with or without an exponent. FORMAT Floating-point number without exponent: snn snn.nn snn. Floating-point number with exponent (E): snnEsnn snn.nnEsnn snn.Esnn Components of MACRO-64 Source Statements 2-9 s An optional sign. nn A string of decimal digits in the range of 0 to 9. The decimal point can appear anywhere to the right of the first digit. A floating-point number cannot start with a decimal point because MACRO-64 treats the number as a user- defined symbol. For information on user-defined symbols, see Section 2.5.3. 2.4 Quoted Literals A quoted literal is a string of characters enclosed in double quotes (" "). Use the following guidelines when specifying characters in a quoted literal: o Any character except null, carriage return, and form feed can appear within the string. o To include a double quote or backslash in a string, you must precede it with a backslash (\). o To specify an arbitrary character, you can specify "\xhh", where each h represents a single hexadecimal digit. For example: "AB\\CD\"EF\x47" This string contains the following characters: AB\CD"EFG Also note that the assembler does not convert the case of alphabetic characters within a quoted literal. Quoted literals can be continued over several lines. Use the hyphen (-) as the line continuation character and delimit the string with double quotes. For example: 2-10 Components of MACRO-64 Source Statements .ASCII "Strings are delimited with double quotes." .ASCII "The backslash is an escape character." .ASCII "Strings can be continued onto multiple lines - just as any other line." .ASCII "Use two backslashes (\\) to represent - the back-slash itself." .ASCII "Hexidecimal escape sequences use - lower or upper X: \x00 or \X00" .ASCII "Precede a double quote with a backslash (\") - to embed the quote." 2.5 Symbols You use symbols in MACRO-64 source statements to represent an instruction, directive, register name, or value. You can use four types of symbols in MACRO-64 source programs: permanent symbols, predefined symbols, user-defined symbols, and macro names. 2.5.1 Permanent Symbols Permanent symbols consist of MACRO-64 directives and instruction mnemonics. You need not define directives before you use them in the operator field of a MACRO- 64 source statement. It is also not necessary to define instruction mnemonics before using them in the instruction statements. 2.5.2 Predefined Symbols Predefined symbols are MACRO-64 register symbols that are not permanently reserved. You can delete the definition of any of these predefined register symbols. You can also define your own register symbols. You can express the 32 general registers and the 32 floating-point registers of the Alpha AXP processor in a source program as follows: ___________________________________________________________ Register Name____Description________________________________________ R0 General register 0. Components of MACRO-64 Source Statements 2-11 ___________________________________________________________ Register Name____Description________________________________________ R1 General register 1. . . . . . . R29 or General register 29 or frame pointer. If you use FP R29 as a frame pointer, Digital recommends you use the name FP. If you use R29 as a general register, Digital recommends you use the name R29. R30 or General register 30 or stack pointer. If you use SP R30 as a stack pointer, the name SP is recommended; if you use R30 as a general register, the name R30 is recommended. R31 General register 31. F0 Floating-point register 0. . . . . . . F31_____Floating-point_register_31.________________________ ________________________ Note ________________________ When MACRO-64 operates in /NAMES=AS_IS mode, all of the previous register symbols are defined in all uppercase and all lowercase. ______________________________________________________ To define your own register symbols, use either the .DEFINE_FREG or .DEFINE_IREG directive for floating-point or integer registers, respectively. For more information about the .DEFINE_FREG or .DEFINE_IREG directives, see the description in Chapter 5. You can delete a register symbol definition with the .UNDEFINE_REG directive. For more information about the .UNDEFINE_REG directive, see the description in Chapter 5. While an identifier is defined as a register symbol, it can only be used in those contexts that allow a register. 2-12 Components of MACRO-64 Source Statements 2.5.3 User-Defined Symbols and Macro Names You can use symbols to define labels, or you can equate them to a specific value by a direct assignment statement. (See Section 2.11.) You can also use these symbols in expressions. For more information on expressions, see Section 2.8. Use the following rules to create user-defined symbols: o Use alphanumeric characters, underscores (_), dollar signs ($), and periods (.). Any other character terminates the symbol. o The first character of a symbol cannot be a number. o The symbol must be no more than 31 characters long and must be unique. o The symbol must not be a register name. o The symbol cannot be one of the following conditional or macro directives: .ELSE .ENDC .ENDM .ENDR .IF .IF_FALSE (.IFF) .IF_TRUE (.IFT) .IF_TRUE_FALSE .IIF (.IFTF) .INCLUDE .IRP .IRPC .LIBRARY .MACRO .MCALL .MDELETE .MEXIT .NARG .NCHAR .REPEAT In addition, by Digital convention: o The dollar sign ($) is reserved for names defined by Digital. This convention ensures that a user-defined name (that does not have a dollar sign) will not conflict with a Digital-defined name (that does have a dollar sign). o Do not use the period (.) in any global symbol name because many languages, such as Fortran, do not allow periods in symbol names. Components of MACRO-64 Source Statements 2-13 Macro names follow the same rules and conventions as user-defined symbols. See the description of the .MACRO directive in Chapter 5 for more information on macro names. User-defined symbols and macro names do not conflict; that is, you can use the same name for a user-defined symbol and a macro. 2.5.4 Determining Symbol Values The value of a symbol depends on its use in the program. MACRO-64 uses a different method to determine the values of symbols in the operator field than it uses to determine the values of symbols in the operand field. 2.5.4.1 Using Symbols in the Operator Field A symbol in the operator field can be either a permanent symbol or a macro name. MACRO-64 searches for a symbol definition in the following order: 1. Macro and conditional directives: .ELSE .ENDC .ENDM .ENDR .IF .IF_FALSE (.IFF) .IF_TRUE .IF_TRUE_FALSE .IIF (.IFT) (.IFTF) .INCLUDE .IRP .IRPC .LIBRARY .MACRO .MCALL .MDELETE .MEXIT .NARG .NCHAR .REPEAT 2. Previously defined macro names 3. Permanent symbols (instructions and other directives) This search order allows most permanent symbols, except conditional directives and macro directives, to be redefined as macro names. If a symbol in the operator field is not defined as a macro or a permanent symbol, the assembler displays an error message. 2-14 Components of MACRO-64 Source Statements 2.5.4.2 Using Symbols in the Operand Field A symbol in the operand field must be either a user-defined numeric symbol, a label, or a register name. User-defined numeric symbols and labels can be either local (internal) symbols or global (external) symbols. Whether numeric symbols and labels are local or global depends on their use in the source program. You can reference a local numeric symbol or label only in the module in which it is defined. If local numeric symbols or labels with the same names are defined in different modules, the symbols and labels are completely independent. The definition of a global numeric symbol or label, however, can be referenced from any module in the program. MACRO-64 treats all user-defined numeric symbols and labels as local unless you explicitly declare them to be global by doing one of the following: o Use the double colon (::) in defining a label. For more information on labels, see Section 2.1.1. o Use the double equal sign (==) in a direct assignment statement. For more information on direct assignment statements, see Section 2.11. o Use the .WEAK directive. For more information on the .WEAK directive, see Chapter 5. You can only use user-defined lexical string symbols with the lexical string operators. For more information on lexical string operators, see Chapter 3. You can define a macro using the same name as a previously defined local numeric symbol, global numeric symbol, or a lexical string symbol. However, you cannot define a lexical string symbol and a numeric symbol using the same name. In addition, you cannot use the same name for both a local and global numeric symbol. You cannot use the same symbol name for both a numeric symbol (local or global) and a label (local or global). Components of MACRO-64 Source Statements 2-15 2.6 Temporary Labels Within Source Code Use temporary labels to identify addresses within a block of source code. Format nnnnn$: nnnnn A decimal integer in the range of 1 to 65,535. In most cases, you can use temporary labels in the same way you use other labels that you define; however, there are some differences: o Temporary labels cannot be referenced outside the temporary label block in which they are declared. o Temporary labels can be redeclared in another block of source code. o Temporary labels that occur within a psect with the MIX or NOMIX attribute do not appear in the debugger symbol table; thus, they cannot be accessed by the symbolic debugger. For more information on psects, see Chapter 5. o Temporary labels cannot be used in the .END or .PROCEDURE_DESCRIPTOR directives. For more information on the .END directive, see Chapter 5. By convention, temporary labels are positioned like statement labels: left-justified in the source text. Although temporary labels can appear in the program in any order, by convention, the temporary labels in any block of source code should be in increasing numeric order. Temporary labels are useful as branch addresses when you use the address only within the block. You can use temporary labels to distinguish between addresses that are referenced only in a small block of code and addresses that are referenced elsewhere in the module. A disadvantage of temporary labels is that their numeric names do not provide any indication of their purpose. Consequently, you should not use temporary labels to label sequences of statements that are logically unrelated; you should use user-defined symbols instead. 2-16 Components of MACRO-64 Source Statements Digital recommends that users create temporary labels only in the range of 0$ to 29999$ because the assembler automatically creates temporary labels in the range of 30000$ to 65535$ for use in macros. For more information on temporary labels, see Section 4.7. The temporary label block in which a temporary label is valid is delimited by the following statements: o A user-defined label: global or local. o A .PSECT directive. For more information on the .PSECT directive, see Chapter 5. An example showing the correct and incorrect use of temporary labels follows: A: ADDQ R1, R2, R3 BEQ R3, 2$ ; correct use MULQ R2, R3, R4 2$: ADDQ R1, R4, R5 ; definition of temporary label B: BNE R5, 2$ ; illegal C: SUBQ R2, R4, R6 In this example, 2$ is a temporary label defined in the block between A: and B:. The forward reference in the second instruction is properly resolved. The line labeled B: also references 2$, but the label B has already closed the range. The temporary label 2$ can be used later in the program, but its definition must appear within the same block as the label. o The .ENABLE and .DISABLE directives, which can extend a local label block beyond user-defined labels and .PSECT directives. For more information on the .ENABLE and .DISABLE directives, see Chapter 5. A temporary label block is usually delimited by two user- defined labels. However, the .ENABLE LOCAL_BLOCK directive starts a local block that is terminated by one of the following: o A second .ENABLE LOCAL_BLOCK directive o A .DISABLE LOCAL_BLOCK directive followed by a user- defined label or a .PSECT directive Components of MACRO-64 Source Statements 2-17 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 .SAVE_PSECT [LOCAL_BLOCK] and .RESTORE_PSECT directives, see Chapter 5. 2.7 Label Addresses In the absence of optimization and automatic data alignment, label addresses are defined to be the psect and offset of the current location counter (see Section 2.11) at the point where the label is defined. When either optimization or automatic data alignment are enabled, the following additional considerations apply. See Section B.7 for information on optimizations and automatic alignment. 2.7.1 Label Addresses, Optimization, and Code Alignment Optimization and code alignment can affect the addresses assigned to labels defined in psects that have the EXE and NOMIX attributes. Optimization and code alignment are disabled by default, and can be enabled with the /OPTIMIZE and /ALIGNMENT command-line qualifiers (see Section 1.2.1) and the .ENABLE directive (see Section 5.1). In general, the assembler assigns the psect and offset of the current location counter before optimization or alignment of code labels. However, the assembler adjusts references to labels in branch instructions to the address of the label after optimization and code alignment processing. The assembler does not adjust references to labels where the label reference occurs in an expression with more than one term. The following example shows this: .PSECT CODE, EXE, NOMIX BSR R0, 10$ ; R0 -> 10$ (postoptimization) 10$: LDA R1, 20$-10$(R0) ; R1 -> 20$ (preoptimization) JMP (R1) [...] 20$: In the previous example, the assembler adjusts the target address of the BSR instruction to be the location of 10$ after optimization and code alignment have taken place. Thus, the branch to 10$ functions as expected. However, when processing the LDA instruction, the assembler computes the offset between 20$ and 10$ before optimization and code 2-18 Components of MACRO-64 Source Statements alignment. Thus, the address of 20$ that is stored in R1 is the address prior to optimization and code alignment. Depending on the sequence of instructions between 10$ and 20$, the address before optimization and code alignment may differ from the address after optimization and code alignment and the JMP instruction may not transfer control to the expected address. Note also that the assembler only performs postoptimization adjustment of label addresses when the label is the only term in the expression. For example: .PSECT CODE, EXE, NOMIX .BASE R27,LINKAGE LDQ R26, ROUTINE1_ADDR JSR R26, (R26) LDQ R26, ROUTINE2_ADDR JSR R26, (R26) RET R28 NOP NOP ROUTINE1: RET (R26) ROUTINE2: RET (R26) .PSECT LINKAGE, NOEXE LINKAGE: ROUTINE1_ADDR: .ADDRESS ROUTINE1 ROUTINE2_ADDR: .ADDRESS ROUTINE2+0 In the previous example, the assembler adjusts the address stored with the .ADDRESS ROUTINE1 directive to the address of label ROUTINE1 after optimization and code alignment. However, since the expression in the .ADDRESS ROUTINE2+0 directive is not a single term, the assembler adds the offset 0 and the address of ROUTINE2 before optimization and code alignment and stores the result. Since the address stored is the address before optimization and code alignment, the second JSR instruction may not transfer control to the address that is expected. Components of MACRO-64 Source Statements 2-19 2.7.2 Label Addresses and Automatic Data Alignment Automatic data alignment can affect the addresses assigned to labels in psects that have the NOEXE or MIX attributes. Automatic data alignment is enabled with the .ENABLE ALIGN_DATA directive or the /ALIGNMENT=data command-line option. For more information on automatic alignment, see Section 5.2. For more information on the .ENABLE directive, see Section 5.3. A label that occurs in a statement with a data-storage directive is assigned the psect and offset of the storage allocated by the data-storage directive. If the data- storage directive requires automatic alignment, the address is assigned to the label after automatic alignment. The same is true of labels that occur in statements by themselves and that are followed by a data directive in a subsequent statement. However, if a label occurs in a statement by itself and is followed by a statement that is not a data-storage directive, a macro directive, a conditional directive, or a lexical-string symbol assignment, the label is assigned the psect and offset of the current location counter before any automatic alignment. The assembler only assigns addresses to labels after alignment under the conditions previously described and only with automatic alignment. If you place a label before a .ALIGN directive that manually aligns the current location counter, the assembler assigns the address of the label before performing the manual alignment. The following example shows the interaction of label address assignment and automatic data alignment: 2-20 Components of MACRO-64 Source Statements .ENABLE ALIGN_DATA .PSECT DATA, NOEXE .BYTE 1 ; The byte is stored in psect data at offset 0 A: .PRINT "Not aligned" ; Any non-macro, nonconditional ; statement, including this .PRINT directive ; prevents A from being automatically aligned ; -- A is assigned offset 1 B: ; B is automatically aligned to offset 4 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 8 E: .OCTA 3 ; E is automatically aligned to offset 16 Automatic data alignment and label-address assignment can be an important consideration when calculating the difference between two labels. For example, consider the following macro, which stores a string preceded by a word that contains the string's length: .MACRO VARYING_STRING STRING ?L1, ?L2 .WORD L2-L1 L1: .ASCII "STRING" L2: .ENDM VARYING_STRING If an invocation of the VARYING_STRING macro is followed by a data-storage directive that requires automatic alignment, the VARYING_STRING macro will not store the correct string length. For example: .PSECT DATA, NOEXE, .OCTA .ENABLE ALIGN_DATA VARYING_STRING