Manual PASM

Texte intégral

(1)Manual PASM. Lifeboat Associates. :. '. ;é á'. "' '.. .. N"*. "'7. Third Avenue New York, NY. 10028 Tel: (212) 860-0300 TWX: 710-581-2524 (LBSOFT NYK) Telex: 640693 (LBSOFT NYK). 1651.

(2) PHOENIX. SOFTWARE. ASSOCIATES. LTD.. PASM. User"s. Manual. Revision 1.0 February. Written. by. Copyright 1980 by Phoenix Reproduced. I,. 1980. Neil J. Colvin Software. with Permission. arid. Associates Ltd. Distributed. LIFEBOAT ASSOCIATES 1651 Third Avenue Y. New York, N. 10028 (212) 860-0300 Tel: TWX: 710-581-2524 Telex: 640693. by.

(3) PASMA. Asserabíer. PSA Macro. Chapter. t: Irítroductioa Chapter. 1. Introduction. symbolic assembly Software Associates Ltd. (a Z80 trademark of program for microprocessors which execute the (requiring assembler a is Zilog, Inc.) instruction two-pass set. It process) the source program to be read twice to complete the assembly Software Associates Ltd. PDOS (or the Phoenix designed to run under device independent, similar) operating system. It is therefore allowing complete user flexibility in the selection of standard input and output device options. machine language The assembler performs many functions, making and programming the more faster, easier, efficient. Basically, by program assembler processes the Z80 programmer"s statements source codes mnemonic translating operation to the binary codes needed in machine instructions, relating symbols to numeric values, assigning and relocatable or absolute memory addresses for program instructions data, and preparing an output listing of the program which includes any errors encountered during the assembly. The PSA Macro Assembler also contains a powerful macro capability which allows the programmer to create new language elements, thus expanding and adapting the assembler to perform specialized functions tor each programming job. the PSA Assembler provides the facilities required In addition, linkages, allowing the PSA Linkage Editor to specify program module (LINK) modules program together into to link independently assembled single executable program. This allows for the modular and a of large prograins, and for easy systematic development sharing of modules common program among different programs. PASM. is the. Pheoníx. Statements Assembler. prepared on a terminal, with the are usually editing program. A program consists of a sequence of the assembly language. Each statement is normally written on one line, and terminated by a carriage return/line feed PSA Macro Assembler sequence. This statements are free-format. means that the various statement elements are not placed at a specific numbered column on the line. There are four elements in an assembler statement (three of which separated from each other by specific characters. are optional), These elements are by in the identified their order of appearance (or delimiting) statement, and by the separating character which follows or precedes the elements. Statements are written in the general form: programs. aid of a text statements in. label: The. operator. operand,operand. assembler converts statements binary machine instructions.. ;comment. written. <CR-LF>. in. this form into the.

(4) PASMA. PSA Macro. Chapter. Assembler. I: Introduction. Instruction. Formats. The Z80 A given uses variable a length format. be machine may one, instruction two, three, or four bytes long depending code and specific machine on the on the addressing mode The PSA Assembler specified. automatically produces the correct code bytes number of machine the operation specified. A code mnemonics Appendix specifies the various machine accepted by and the format of the operands the assembler required.. instruction. for. Statement. particular. Format. As described, assembler statements consist previously of a and a combination of a label, an operator, more operands, one or on the cownent; the particular combination depends statement usage and operator requirements. and The assembler interprets these statements, processes one more binary generating instructions or or data bytes, or control process. A statement must contain performing sorne assembly Sorne at least one of these elements, and rnay contain all four. statements have no operands, while others may have many. and be represented operands may Statement labels, operators, The numerically or symbolically. assembler interprets all symbols and replaces them with a numeric (binary) value. Symbols The progranuner uiay create symbols to use as statement labels, as may consist of any combination operators, and as operands. A symbol of from one to six characters from the following set: The 26 A-Z O-9 Ten Three special characters:. letters: digits: $ %. .. (Dollar Sign) (Percent) (Period). the Radix-40 character characters constitute set (so named 40 Any characters). only contains statement character which is not in the Radix-40 set is treated as a symbol delimiter when encountered by the assembler. The first character of a symbol must not be numeric. Symbols may also not contain embedded spaces. A symbol may contain more than six characters, but only the first six are used by the assembler. The PSA Assembler wíll accept programs written using both upper and symbols. Lower and lower case letters case letters are treated and lower special characters as upper case in symbols. Additional case letters elsewhere are taken unchanged. These because. it.

(5) PASM:. PSA Macro. Chapter. Assembler. l: Introduction. Labels to is the symbolic name created by the programmer the as written the label is identify a statement. If present, first A statement and is terminated by i.tem in a statement, a colon (: the same may contain more than one label, in which case all identify A however. by be Each must colon, a followed label statement. (or labels), in which case the statement may consist of just a label label(s) identifies the following statement. When a symbol a symbolic specifies label, as a is used A (have be symbols Such value). a defined address. are said to defined symbol can reference an instruction or data byte at any point in the program. be defined an attempt is A label can with only one value. If second made to redefine value is value, the a label with a different and indicated. an error is ignored, The following are legal labels: A. label. ).. it. $SUM: ABC:. Bl23: WHERE%:. The. following. 30QRT: AB CD:. If too used.. are assembler. are. illegal:. (First character (Cannot. contain. must not be a embedded space). digit). many characters are used in a label, ZYXWVUTSR: For example the label be ZYXWVUABC: the same as to. .. only. the. first by. is recognized. six the. Operators codes, operator may be one of the mnemonic machine instruction assembly code which directs the a pseudo-operation process, or a user (either pseudo-op defined code or macro). The assembler pseudo-op 3 and codes summarized B. in Appendix are described in Chapter The element by of a statement is terminated any operator character not in the Radix-40 set (usually a space or a tab). Ifthea must appear the operator statement has no label, in first statement. used as an operator A symbol must be predefined by the assembler before its first appearance as an operator in a or the programmer statement. An. Operands. the symbolic addresses of the data to be are usually instruction an is executed, the names of processor be used registers the in operation, or the input data or arguments to pseudo-op a macro to or instruction. In each case, the precise of the operand(s) is dependent on the specific interpretation Operands being processed. statement operator are separated by Operands accessed when. 3.

(6) PASPi:. PSA Macro. Chapter. I:. and. commas,. Assembler. Introduction. returri/line Symbols. are feed. used. terminated. by. operands. must. as. a. (;). semicolon have. assembler or defined by the programmer. references to previously defined labels be found, this instruction are to or constant values or character strings.. or. carriage. a. valued predefined. a. These. may the arguments symbols may. where. the. by. the symbolic. be. used. by. represent. Comments The programmer may add a comment to a statement by preceding Comments are ignored by the assembler but with a semicolon (;)· are useful for documentation and later program debugging. The comment is terminated by the carriage return/line feed at the end of the assembly and macro (eg. conditional cases In certain statement. and definitions), the use of the left right square brackets ((I) should be avoided in a comment could affect the assembly as process. An assembler statement may consist of just a comment, but each such statement must begin with a semicolon.. it. it. Statement Processing The. assembler. recording the names These tables are:. I. 2.. Macro. Table. empty,. and. Op-Code mnemonics. several internal maintains and used values of symbols. symbol. tables for during the assembly.. table contains all macros. It is - This defines macros. as the programmer. grows. Table. This table contains all of the machine operation (op-codes), the assembler pseudo-operations. (pseudo-ops), and user defined operators (.OPSYNS). and pseudo-ops, and contains the basic op-codes provides additional prograwrner defínítions. 3.. initially. It initially as the. grows. Table - This table contains all programmer-defined symbols contains the other than those described above. It initially and symbols as then grows names, new standard register are defined. Symbol. InternaZly, all of these tables the available space can be used Order. of. Symbol. the saíne occupy as required.. space,. so. that. all of. Evaluation. following table searches the tables for The. shows a symbol. the order in appearing in. which the assembler of the statement. each. fields:. Label Field: L.. followed present.. Symbol. is. by. a. colon.. If. no. colon. is found,. no. label.

(7) PASM:. Assembler. PSA Macro. I:. Chapter. Introduction. Operator Field:. l.. Macro Machine Assembler Symbol. 2. 3. 4.. operator operator. Field:. Operand. Number Macro Symbol Machine. l.. 2. 3. 4.. operator. the different could be used ambiguity.. Because of same symbol no. Prograwmer-Defined. table as. a. searching orders for each label, an operator, and a. field, the macro,. with. Symbols. symbols: labels and are two type of programmer-defined As labels described, previously assignments. are generated by LABEL: Symbols used as by symbol (e.g. followed colon a entering a labels cannot be redefined with a different value once they have been The value of a label is the value of the location counter defined. at the time the label is defined. numbers, symbolically, Assignments are used to represent, bit Assignments simplify the program strings. patterns, or character development task by allowing single a source program modification (the assignment statement) to change all uses of that number or bit throughout the program. Symbols given values in an pattern have assignment statement 'ínay values assigned in subsequent new symbol The current value of an assigned is the last one statements. given to it. A symbol may be entered into the symbol table with its assigned by value using a direct assignment statement of the form: There. ).. symbol. =. value. {; or. CR-LF}. the value may be any valid nuníeric value or expression. value assigned to the symbol may subsequently be changed another direct asignment statement. The following are valid assignment statements:. where. The. by. VALUEI = 23 SIZE = 4*36 ZETA = SIZE. is desired If itsubsequently. to. fix the value assigned to. redefined, the cannot This statement statement should be assignínent statement except that the symbol For example: signs instead of one. FIXED NEWVAL. be used.. == 46 == SIZE. 5. a symbol. so that direct fixed assignment is the same as the direct is followed by two equal. it.

(8) PASM:. PSA Macro. Assembly-Time. It. Assembler. I: Introduction. Chapter. Assignments. is often desirable. to defer the assignment of a value to a underway is actually (i.e. not specify the value as part of the source program). This is especially useful in and setting program origin, buffer sizes, in specifying parameter be used assembly values which will pseudo-ops. to control conditional The PSA Assembler provides the ability to specify symbols with values to be determined at assewbly time, and the mechanism by which be the values may interactively defined. To specify an assembly-time assignment, the following format is used: symbol. until the. symbol. =\ {svalue}. assembly. where. the svalue in braces indicates the optional specification of a time before to be output on the console device at assembly Any the symbo1"s value. valid requesting string value may be including multi-line values. specified, After the optional message is output on the console, a colon (: that the assembler is waiting for the desired output to indicate is The value which is to be assigned to the symbol value to be entered. is then input on the console device and the assembly continues with the symbol having the specified value. This interaction only occurs The unchanged symbol"s during the first assembly value remains pass. during subsequent passes. be entered Only numeric values rnay through the console in this The nuuiber fashion. which is input uiust conform to the same rules as number used in the assembly any other source program, and may be (see the by radix modifier an optional section on Numbers followed by a assumed be number The decimal unless followed is below). to radix modifier. The value being input is not processed until a carriage return is Any mistyped character deleted by the use of the entered. may be DELETE (or RUBOUT) key (which will echo the deleted character) or the CTL-H) key BACKSPACE (or which will backspace over the deleted deleted by entering CTL-U may be character, and the entire number U Any character which is key). (simultaneous use of the CTRL and the input but is not valid as part of a number will be echoed as a BELL and will be ignored. examples The following assembly-time of assignment are statements: message. ). BUFSIZ =\ "BUFFER SIZE (50 TO 500 CHARACTERS)" (O-PAPER TAPE I-DISK)" DISK =\ "VERSION. Assembly-time assignment statements are similar to direct fixed assignments (==) in not allowing the symbol to be redefined elsewhere in the program. Local. and. Global. Symbols. assembling a large program, is used keep track of the symbols for local modular programming, To facilitate branching.. it. When. 6. difficult andto data references the PSA Assembler. sometimes.

(9) PASM:. PSA Macro. Chapter. I:. within a single program. for both global and local symbols two periods with which start are defined as being local, example, For symbols following. provides. All. Assembler. Introduction. symbols. and. the. are global.. all other valid local symbols:. are. ..ABCD:. ..1234: 0 0 0 *. within the particular occurrence of a local symbol is only defined example, For global symbols. enclosing boundaries of its in the ..SYML symbol the following sequence of label definitions, is only between A. (and. defined. definition of. be referenced) can only GLOBI and GLOB2:. within. the. program. the. 0 * 9. GLOB!: 9 0 0. ..SYMI: 0 0 0. GLOB2: 0 0 0. the same symbol to be the unambiguously more than once in program. It also simplifies by understandability immediately differentiating between program and global symbols. local In addition to labels, any other programwer-defined symbol maybe Because of the specified as local (e·g? macros) in the same manner. do local usage of these symbols, they not appear in the symbol table listing or in the symbol table optionally output to the object file. This. used. localization of. External,. Internal,. symbol. and. definitions allows. Entry. Symbols. used as Programmer-defined symbols also be external, may and entry point symbols as in addition to their appearance internal, labels or in assignment statements. Symbols which fall into one of these three groups are different from other symbols in the prograrn because they can be referenced by assembled, other, separately modules. The manner program in which depends where used they are located: in the program in on they are which they are defined, in which they are a or in the program reference to a symbol defined elsewhere. in a program in which is defined, If the symbol appears available by the use of must be declared as being to other programs .INTERN .ENTRY, the pseudo-ops or or through the use of the "="" "=="'" > or delimiters · " » " ? "_\:" in their definition """' These special delimiters statements. equivalent to the are exactly. it. sequence: .INTERN symbol. symbol. <de1imiter. without. colon (: )>. it.

(10) PASM:. PSA Macro. Chapter. Assembler. Introduction. I:. is the normal symbol definition operator In each case, the delimiter added =\) (: =, ==, with an additional colon (: to indicate an symbol internal definition. the symbol is located in a program in which is a reference If symbol be declared as must defined in another program, to a external by the use of the .EXTERN pseudo-op, or through the use of This special symbol modifier is appended the "//" symbol modifier. to symbol end For example, of any external. the the to declare statement:. ,. ). it. it. it. LXI. H,SYMBOL//. is exactly equivalent. to:. .EXTERNAL SYMBOL LXI H,SYMBOL Numbers Numbers. in radix. tO 10. 10 10. IOB OFFH. in current radix. 4. is not. the. logical. / & !. numbers:. digit start with. binary must. Logical. a numeral. Operations. using arithmetic defined symbols may be combined The following operators are available: operators.. (or Subtract Multiply Integer Integer Logical Logical. Add. a. number. and. Numbers. @. are invalid. following. Arithmetic. -*. a program (number base). decimal !0 binary (2 decimal) FF hexadecimal (255 decimal). 14B FFH. +. are interpreted specified by the. by. the assembler where according to a programmer, 2 8 be 10 (binary), (decimal), the radix way (octal), or 16 The the .RADIX pseudo-op programmer uses (hexadecimal). to set the .RADIX statement radix for all numbers which follow. the is not If used, the assembler assumes a radix of 10 (decimal). The radix may be changed a radix for a single number by appending B end number. These modifiers modifier to the of the binary, for are D H O for hexadecimal. or . (period) for decimal, and or Q for octal, To specify the hexadecimal digits, the letters A through F are used however, inust for the values 10 through 15 decimal. All numbers, the following are valid numbers: begin with a numeral. For exarnple,. The. used. and. unary plus) (or unary minus) division (remainder discarded) remainder (quotient discarded) AND. inclusive. OR. 8. and.

(11) PÁSM:. I: Introduction. Chapter ^ // < >. Assembler. PSA Mácro. exclusive OR (or unary radix Logical unary NOT Left binary shift Right binary shift LogíoaZ. change). of numbers and the l6-bit value of a series assembler cowputes connected symbols by these operators. defined All results are Two"s complement arithmetic is truncated to the left, necessary. weaning most (the of the sign bit used, with the significant bit) that a numeric value may be Thís means being left to the programmer. either between O and 65,535 or between -32,768 and 32,767, depending is signed or unsigned. on whether These combinations of number and defined symbols with arithmetic When and logical evaluating an expressions. operators are called operations expression, the assembler performs the specified in a particular order, as follows: The. if. it. I.. 2. 3. 4. 5. 6. 7.. Unary Unary. or plus (-. minus. change. radix. (^B. Left right binary Logical operators (& Multiply/Divide (* I) and. Add/Subtract each. "Q. shift " //). ^D ^H) (< >). (@). Remainder. "Within. !. +) "O. (+. of the. left to right.. For. -) above groups, the operations example, in the expression:. are performed from. -ALPHA+3*BETA/DELTA&"H55. then DELTA is ANDed with a the unary minus of ALPHA is done first, by 3, the result hexadecimal 55, then BETA is multiplied of which is divided by the result of the AND, and finally, that result is added to the negated ALPHA. To chaage the order in which the operations are performed, and to µarentheses rnay be used to "delimit expressions specify the Each desired order of computation. expression within parentheses is considered to be a single numeric value, and is completely evaluated before is used to compute any further values. For example, in the expression:. it. 4*(ALPHA+BETA). the addition Radix. Change. of. ALPHA. to. BETA. peformed. is. before the. multiplication. Operator. The. radix change operator is used to temporarily change the radix in which a following number or expression is to be interpreted. It is written as an up-arrow (") followed by the radix modifier of the These modifiers desired radix. are the sarne as those used to specify the radix of a single number (B-binary, O or Q-octal, D-decimal, and The change H-hexadecimal). radix only affects the immediately For example, following number or parenthesized numeric expression.. g.

(12) PASM:. PSA Macro. I:. Chapter. Assembler. Introduction. all of the following 33:. are. valid representations. of the decimal. number. 33. 33D ^033. ^0(10*3+3) ^D(I0*THREE+THREE) ^DIO*^D3+"D3. but the following is not a representation radix is not decimal: prevailing. of. decimal. 33. if. the. ^D3*10+3. the radix. because. it,. in. this. case. change. only affects. the value immediately. following. 3.. Binary Shifting (< operators left, > right) are used to value 16-bit the to left or right. The number of logically shift a by be shifted is specified the value following the shift places to of the shift is operator. If that value is negative, the direction have a value For example, of the following reversed. expressions all 4 of decimal: The. binary. shift. 8>1 1<2 2>-1. One-byte. Values. All of the above discussion has been based l6-bit (two byte) numeric values. Many of the. the computation of operations require computations are done as a all only eight bits will discard for significant byte) of the value. zero or minus one (all one bits),. Since B-bit (one byte) value. l6-bit value, an operation calling the high order eight bits (the most If the byte discarded is not either a warning will be given on the assembly an. Character. on Z80. listing.. Values. generate a binary value equivalent to the ASCU representation of a character string, the single (") or double (") quotation mark is used. The character string is enclosed in a pair of the quotation marks. For example, all of the following are valid character values: To. "A" "B" "AB" "CD". 10.

(13) PASbí:. Assembler. PSA Macro. i: Introduction. Chapter. that whichever quotation mark is used to initiate the character is longer than the string string must be used to terminate it. If Each two bytes, is truncated to the left. 7-bit ASCII character in an B-bit byte, with the high-order bit set to zero. is stored A of this type way be used wherever a numeric character string value is allowed. A single quote delimited by double inside a string may be used quotes, and vice-versa. If is necessary to use a single quotebe within a string delimited by single quotes, two single quotes must used. The same is true for a double quote in a string delimited by double quotes. Note. it. it. Location Counter Reference The location counter may be referenced by the use of the symbol The (period). . always the Location counter value at assembly language stateriient. For example: JMP. is. as a numeric 16-bit value value represented by . is the start of the current. .. an. effective error trap, jumping to itself continuously. Variables. Temporary. convenient to be In addition to named symbols, is sometimes assembly by able to reference a time variables numeric value or The PSA Macro Assembler allows the definition of a single subscript. global assembly time array for this purpose. This array has the special name "*" and is referenced by "*[subscript]" where subscript is any valid L6-bit absolute expression with a value between C) and the number of array elements minus I. This array reference may occur anywhere a normal symbol or label reference or definition is allowed. A temporary be variable assigned any numeric value, either may absolute or relocatable, within the normal l6-bit restríctíon. The allocation of space for this array is done by the .TEMPS pseudo-op described later. For example:. it. V=5. *[V]=4*V W=5. MVI. A,*[W]+23. String. Variables. In addition. to being able to assign a numeric value to a symbol, allows a symbol to be assigned a string value pseudo-op as well. This is through the .DEFINE in the same (see Chapter manner in which a macro is defined 4), except that A defined string variables may have no arguments. string variable may only be DEFINEd once in a program. String variables may be used anywhere a string value is called for (eg. the .ASCII pseudo-op). the. PSA Macro. For. Assembler done. example:. 11.

(14) PASM:. PSA Macro. l: Introduction. Chapter .DEFINE. Assembler. PR0MPT=[>>] "ENTER N1JMBER",PROMPT. .ASCII. Substring. Operator. is sometime It argument. desirable to obtain a substring The PSA Macro string variable. or through the use of the substring that capability format for the use of this operator is:. macro. of a given Assembler operator. string,. provides The "<".. <[s{,L}]dtextd or <[s{,l}]svariab1e expression whose value is the starting character L6-bit an optional expression the length of I for O. the string to use. The first string character the length is If the of the used. omitted, entire string rest is is The a delimited form uses string as its string argument. first the d represents a delimiter which may be any character not contained The string argument within the string itself. starts with the first and terminates with the character after the delimiter, last character The delimiters before the corresponding are not part of delimiter. bracket a the string. If the initial delimiter (I), then the is left The is a right bracket matching delimiter left and right (I). brackets are paired, so that intervening pairs of left and right brackets will not terminate the string. The second form uses a string variable as its string argument. where to be. s is used,. For. .DEFINE. a. 16-bit. and. is. example:. STRNG1=[THIS. IS. STRING. ONE]. <[0,I]STRNGL .ASCII <[5,3j"0l23456789" .ASCII The substring operator expression in place of a. also be used in a normal arithmetic For single or double character value.. may. example: MVI. A,<[V,lj"0l23456789". String. Length Operator. of a given string It is often quite necessary to use the length To facilitate value as a value in an numeric expression. this, the used by prefixing is string length operator "@" is provided. It to the front of the string value whose length is desired, and may be For example: used anywhere an absolute number is allowed.. it. STRNGI=[THIS .DEFINE STRNGL .ASCIZ MESSI: LXI H,MESSI MVI B,@STRNGI. IS. A STRING]. 12.

(15) PASM:. PSA. Chapter String. Macro. I:. Assembler. Introduction. Values. generic "string value" argument. A string value is either a delimited string (see Substring Operator For example, above), a string variable or a substring operation. all STRNGL of the following are valid string values (assuming as defined above): Many. pseudo-ops. utilize. a. STRNGL "THIS IS. A STRING" A [BRACKETED] DELIMITED <[0,5]"THIS IS A SUBSTRING" <[3,2)STRNGI [THIS. IS. STRING].

(16) PAM: PSA Macro Assembler Chapter 2: Addressing and Relocation Chapter Addressing. Address. and. 2. Relocation. Assignment. source statements are processed by the assembler, consecutive addresses are assigned to the instruction and data bytes of the object program. This is done by incrementing an internal program Some time a memory byte is assigned. counter each statements may increment this internal counter by only one, while others could and increase direct it by a large amount. Certain pseudo-ops assignment statements have no effect on the counter at all. In the program listing generated by the assembler, the address assigned to every statement is shown. As. memory. Relocation PSA Macro Assembler program may be loaded into has been previously loaded.. will create. The. object program. a relocatable part of memory as a function of what accomplish this, certain l6-bit have a must addresses within the program values which represent This relocation relocation constant added to them. constant, added when the program is loaded into memory, is the difference between the (or piece of data) is actually loaded memory location an instruction had into, and the location it was lOóassembled at. and If anwasinstruction been assembled (decimal), loaded location into at location 1100 (decimal), then the relocation constant would be 1000 (decimal). be by the relocation Not must modified quantities all ForL6-bit example, the constant. instruction: This. any To. H,0OFFH. LXI. references However,. a. i6-bit quantity. (OOFFH). which. does. not. need. relocation.. the set of instructions:. DONE. JZ 0 0 e. DONE:. l6-bit quantity (the addressDONE of DONE) which must be changes depending on location of the physical is loaded into memory. the 16-bit relocation, value forming an this by the assembler is marked for later modification linkage editor. Whether a partícular l6-bit value marked depends arithmetic of the evaluation expression the on so is A constant value (integer) is absolute is obtained. from which and Point references (not relocatable), (.) are never modified.. reference a relocated, since where the program To accomplish address reference by the loader or does. it. 14.

(17) Assembler PSA Macro 2: Addressing and. PASM:. Chapter. Relocation. code is being (assuming generated), and are relocatable relocatable by always modified the loader or linkage editor. Symbolic references absolute or relocatable. way be either symbol may is defined by a direct assignment statement, a If depending the be absolute or relocatable on the expression following code (and symbol relocatable equal sign (=). is is a label If the relocatable. being generated) then is To evaluate the relocatability of an expression, consider what happens constant, r, must at load or linkage edit time. A relocation and be added the expression evaluated. relocatable element, to each in the expression: For example,. it. it. Z. = Y+2*X-3*W+V. where. V,. W,. X,. and. Y. relocation constant. the expression becowe.s: Z(r). Z(r). Assume to each. O*r. the following. the expression,. = Y+2*X-3*W+V. This expression single addition expression can the following,. is the term,. +. is obtained:. r. contains only a is suitable for relocation because the of the relocation constant r. In general, be rearranged to result in the addition of either of is legal:. it. if. it. the rearrangement results where. if illegal.. the expression involves r to any power Thís leads to the following rules:. Also,. n. is not. O. in the following,. n*r. it. is illegal:. or I other than. l,. it. is. Only two values of relocatability for a complete expression are allowed (le. n*r where n = O or I). Division by a relocatable value is illegal. Two relocatable values may not be multiplied together. Relocatable values may not be combined by logical operators. A relocatable value may not be logically shifted.. l. 2. 3. 4. 5.. If. that r relocatable. absolute expression relocatable expression. l*r. If. relocatable. this constant. (Y+r)+2*(X+r)-3*(W+r)+(V+r). =. rearranging. By. are. Adding. of these. any. error. If. message is X, Y, and. X+Y-Z X—Z. X+7. 3*X-Y-Z. rules is broken, the expression given. Z are relocatable symbols, then:. is relocatable is absolute is relocatable is relocatable. 15. is illegal. and. an.

(18) PASM:. PSA Macro Assembler 2: Addressing and. Chapter 4&X-Z. Relocation. is illegal. Only. l6-bit quantities absolute or an error will Relocation One. may be relocated. be given.. All B-bit values. be. inust. Bases. of the unique capabilities. of. the PSA Macro Assembler is its to separately located areas of where the mapping of symbols memory, to physical addresses occurs at linkage edit time. The symbolic names for independently located bases". These relocation bases called "relocation memory areas are ROM COMMON RAM, shared inay represent vs. areas, special memory areas such mapped each I/O, etc. refresh, as video memory Within by a unique subprogram, each of these mewory areas is referenced allocation deferred to the link edit and' load name, with the actual references memory within the assembled program All process. are of these relocation one bases. to relative As each base relocation is assigned a name in the program (through the use of the .EXTERN pseudo-op), is implicitely number. assigned a sequential identifying This number appears in the listing as part of any address relative to that base. Four of these (0-3) have relocation bases predefined names and and meanings, edit time than the at linkage are treated differently remainder of the bases. Base D represents absolute memory locations always has the Base L has the name .PROG. and value of O). (le. PROM (maybe code represents the program area or ROM). Most program non-romned programs) (and data in generated to is relative this relocation base. Base 2 has the name .DATA. and represents the local Most local data area for each uíodute. data is defined relative to 3 has and .BLNK. Base name base. the represents the global this "blank common". This relocation base is always assigned the value of the first free byte in memory after the local data storage (.DATA.) by the Linkage editor. and other data relocation Because segments always modules allocated, referencing the last this area can be is included in any order, regardless of the amount of the area they use. Relocation segments relative to bases I and 2 (.PROG. and .DATA.) (íe. after each module is allocated, are always allocated additively base is the value of the relocation increased by the size of the bases segment). All other relocation to have are normally assumed by the allocation (usually assigned during values constant process the linkage editor). has a Each symbol relocation base defined during the assembly There with no associated limitations on inter-base are it. reference data can freely references (le. code relative to .PROG. symbols must evaluate to .DATA.). Expressions containing to relative relocation base, but may single a contain a value to relative base relocation bases. relocation references multiple to All be must the result references except of part for final T For example, sub-expressions which evaluate to absolute values. V W U base 2, and and and relative to are symbols relative to base I, X and Y relative to base 3, then the following are valid expressions:. ability to handle symbolic references. it. it. it. if. 16.

(19) PSA Macro Assembler Chapter 2: Addressing and PASM:. Relocation. (note the parentheses to a subexpression). T+(V-W). make. V-W. X+3. T-(V-W)*U+(X-Y) and. the following. are. invalid:. (within a relocatiori base, the normal relocation rules apply) (T-l-V is the first subexpression, and is mixed relocation bases). T+U T-l-V-W. it. should be noted that conceptually, normal external symbols are relocation bases with a size of zero (O), and the assembler them that way. An assignment of the form:. It simply treats N==P+5 where. P. is. relative to. an external P, even though. symbol, P. has. makes no. N. size.. a. symbol Hence,. address is expressions of the whose. form:. 5*(P-N) where. P. and. N. have. the. same. relocation. 17. base, are in fact. valid..

(20) PASM:. PSA Macro Assembler 3: Pseudo-Operations. Chapter. Chapter. 3. Pseudo-Operations. Pseudo-operations (pseudo-ops) are directions to the assembler to perform certain operations for the programmer, as opposed to machine Pseudo-ops which are instructions operations to the computer. perform such functions as data conversion, listing control, or storage allocation. Address The. MOde and PSA. Origin Assembler. assembles normally programs in be that the resultant program loaded can for execution. Therefore, all programs are their first byte is at address zero (O), because anywhere. When desired, however, the assembler code, either for the entire program, or will generate absolute object The assembler will also locate the assembled just selected portions. The code at pseudo-ops two address desired. any which control mode, base and relocation address address origin are .LDC and .RELOC. Macro mode, relocatable so anywhere in memory assembled assuming be relocated they can. .LOC. n. This statement sets the location counter to the value n, which any valid expression. If n is an absolute value, then the assembler will assign absolute addresses to all of the instructions and then relocatable data which follow. If n is relocatable, base of the addresses will be assigned, relative to the relocation expression. The program is assumed to to start with an implicit .LOC to (O) base named .FROG. address of the relocation relocatable zero base (the default relocation for normal programs). Él program can contain wore than one .LDC, each controls the assignment of addresses to the statewents following it. To reset the program counter to its value prior to the last .LDC, the statement:. may be. .RELOC. This statement restores both the value, the relocation base and the addressing mode which were in effect before the immediately .LDC. preceding If no .LDC has been done, then a .RELOC is equivalent to a:. is used.. .LDC. O. in relocatable addressing mode, the assembler will determine whether each I6-bit value is absolute or relocatable as described in Chapter 2. When. 18.

(21) PSA Macro Assembler Chapter 3: Pseudo-Operations PASM:. Definition. Data. PSA Macro Assembler describing and entering. The. for. provides data to. a number be used by. of different pseudo-ops the program.. .RADIX When. it. converts indicated .RADIX. it. the assembler encounters a number in a statement, to a l6-bit binary value according to the radix The statement: by the programmer.. n. is 2, 8, ID, to n for all numbers or 16, sets the radix .RADIX statement is encountered, or which follow, unless another by the "r operator the radix is modified or a suffix radix modifier. The statement: where. n. .RADIX. 10. implicitly begins. each. assembly. program, setting. to decimal.. the. intial radix. .BYTE. enter one (or more) program, the statement: To. {[r]}n {, {[r]}n. .BYTE. B—bit. (one. byte) data values into. the. ·..}. r is an optional repeat count which can be any 16-bit value (including O) and n is any expression with a valid B-bit value, is used. More than one byte can be defined at a time by from the preceding value with a comma. separating All of the .BYTE bytes defined single a in statement are assigned For example: consecutive memory locations.. where. it. 23,4*^HOFF,BETA-ALPHA,[5]0. .BYTE. defines. three sequential. bytes of data.. .WORD. To. enter statement: .WORD. nn. {,. nn. a. l6-bit. (two. byte) value. into. the. progratn, the. ...}. where. nn is any expression with a valid l6-bit value, is used. Multiple l6-bit values may be defined with one .WORD statement by separating each from the preceding one with a comma. All í6-bit values defined by the .WORD pseudo-op are stored in standard Z80 word format, least significant byte first. the following statement: For example,. 19.

(22) PASM:. PSA Macro Assembler 3: Pseudo-Operations. Chapter. ALPHA,234'U3ETAJHOEEFF. .WORD. defines three sequential of data. .ASCII,. and .ASCIS .ASCIZ, To enter strings. l6-bit. values,. of text characters. or. into. the stateuients: .ASCII .ASCIZ .ASCIS. l. s s s. l I. total of six 'bytes. a. the program,. one. of. [n] [n] [II]. valid string value. Each is used. The s represents any character in the converted text to is its 7-bit ASCII and (with the eighth bit representation zero), stored in The string sequential memory locations. value may be followed by comma), and this another string value (seperated by an optional may be repeated as desired. If it is necessary to include values in the text string for which no character exists, then the second option shown above may be used. If in place of a string value, the assembler finds a bracket square (I), then the numeric expression enclosed left and a matching right square within bracket (I) is evaluated as the next byte of the string. These an B-bit value and stored as B-bit values may be intermixed with stríng values as required Note (optionally seperated by commas). that this precludes the delimited as strings values in these use of bracketed string statements. tab, carriage return, and line to note that It is important characters within a value. feed are all valid string Itmoreis .ASCIX possible that a encompass therefore statement will than one line in the source program. between The difference the three pseudo-ops described above by the byte the of generated last is in their treatment The The the byte. .ASCII statement just stores statement. .ASCIZ byte after the last one, a statement stores one additional The mark end of the string in memory. the null (zero) byte to .ASCIS pseudo-op sets the high-order (eighth) of the bit last byte to one to flag the last byte. The following are all valid .ASCIx statements:. it. .ASCII /This .ASCIZ /This [^H0D]. .ASCIS. is a string/ strings is two/ "Message ". [^H0A]. in on. one new. .ASCII \ Message. line\ .string variable. place". line". on new. .ASCII. PNAME. .ASCIZ. <[2,B]"substring. plus expression". string.. .RAD40 The. allows memory.. a. Radix-40 character set for six character symbol to be To allow the program to 20. symbols. was. chosen. because. it. stored in only four bytes of define data bytes in this.

(23) Assembler PSA Macro 3: Pseudo-Operations. PASN:. Chapter. character. set,. the statement: .. symboll {,. .RAD40. symbo12. ...}. is used. The symbol must conform to all the rules specified for assembler symbols, and is converted into the Radix-40 notation and stored bytes of memory. in four sequential If multiple be separated each and must be symbols stored, converted are to from the preceding one by a comía. Storage Allocation Assembler The PSA Macro allows the programmer to reserve single the execution use during locations, blocks of many locations, for or pseudo-ops used The two the of for this purpose are .BLKB program. The format of the statement using these pseudo-ops and .BLKW. is: .BLKx. n. is the number of storage locations to be reserved. consists of one For the .BLKB pseudo-op, each storage location above bytes of contiguous n so byte, the statement will reserve The .BLKW location the starting memory, counter. current at (two pseudo-op bytes) as its storage unit, so the above uses a word statement would reserve n words, or two times n bytes of contiguous where. n. memory. For. of bytes of storage:. exampLe,. (decimal) .BLKB .BLKW .BLKB. each. the. following. statements. reserves. 24. 24.. ^Dl2 2*12. Variables. Temporary The. Assembler. of temporary allows the allocation These arrays arrays for use during the assembly process. The may be used. both on a global basis, and within macro expansions. use of these arrays in each of these contexts is described elsewhere The actual allocation iri this manual. of space for these arrays is done usírig the .TEMPS pseudo-op. The format of this statement is: PSA. Mácro. variable. .TEMPS. n. the number of array elements to n is a i6-bit value specifying allocate. This statement may appear anywhere in the program, and may be used more than once. (global either In context or macro), the of the results the reallocation in of the statement reappearance A zero value of results the freeing of in allocated array space. all is dynamic, and the freed space may be space. This space allocation used by other parts of the assembly process.. where. 21.

(24) PASM:. PSA Mácro Assembler 3: Pseudo-Operations. Chapter Program. of. Termination. Every program this statement. .END. must. be. terminated. by. a. .END. pseudo-op.. The. format. is:. start. address for the program. The start is optional an starting starting address is normally only necessary for the main program. Subprograms, which are called frotn the wain program, need no starting. where. address.. When. the assembler encounters the .END pseudo-op during pass ! of the assembly, initiates pass 2 of the assembly. On a listing pass, the .END pseudo-op initiates the printing of the Onsymbol table suppressed by a a object not prior .XSYM pseudo-op). (if pseudo-op .END producing pass, the the EOF record to the output object file.. it. Subprogram. Linkage. and usually of a wain program consist numerous communicate each with other through parameter subroutines which linkages and through reference to symbols defined elsewhere in the provides the means for the program. Since the PSA Macro Assembler components separately from each various program to be assembled editor (which finally puts the pieces together) other, the linkage must be able which are references (or to identify those symbols For a given subprogram, referenced) external .to the current program symbols symbols these "linkage" defined internally which are either must be available to reference, or symbols used to other programs to the program. Symbols de'fined internally but defined externally within the program but available to other subprograms are called Symbols used "internal" symbols. internally but defined elsewhere symbols. are called "external" subprograms, To set up these linkages between four pseudo-ops are and .ENTRY. .EXTERN, .INTERN, provided: .IDENT, The .IDENT statement has the format: Programs. symbol. .IDENT. This name is used by name. is the relocatable module module on memory allocation maps, the linkage editor to identify the and to allow the selective of a loading of the module part is does .IDENT subprogram appear the statement not library. If in a The .IDENT asstuned. ".MAIN." name appears the nane is at program, the top of every listing page, and is displayed on the console at the start of the second assembly pass ofhavethat module. the same format: All three remaining statements where. symbol. if it. .EXTERN .INTERN .ENTRY. symboll {, symbol2 symboll {, symbol2 symboll {, syrnbo12. ...} ...} ...}. 22.

(25) PASbí:. Éíácro. PSA. Chapter. 3:. Assembler. P"eudo-Operations. syriiboll is the symbol being declared as external, internal, or be symbols declared in the same may Multiple as an entry point. each by one with a comma. the preceding from separating statement symbols The .EXTERN which are defined statement identifies be symbols must defined within the current External elsewhere. not symbols used be in the same manner as any ínay subprogram. External with the following restrictions: other relocatable symbol, where. l. 2.. The. use. of. more Thus. than V+W. symbol a single expression one external W V and where are both external is be the following Therefore additive. V (where symbol): an external. in. is illegal. only Externals way expressions are illegal. illegal.. is. -V 2*V SQR-V 2*V-V 3.. final evaluation of the expression containing the external reference must result in external symbol + (or —) constant value. Furthermore, this expression is used as an B-bit (byte) value, -128 and +255 the constant must be between or an error will The. if. result.. deciared as external by the .EXTERN pseudo-op may also be done by bases. This is using an external symbol as relocation by the .LOC as the argument pseudo-op. All memory allocated to a addressed .LDC be assembler after the will relative to the specified relocation base. The most common use of this capability is the blocks for the sharing of data between declaration of COMMON subprograms. All named COMMON blocks are in assembler arid FORTRAN used fact just different relocation bases. Symbols as relocation bases assembly have unique values during the of the program module. At any point in time, the current value of the relocation base symbol have been base number so far. allocated to that of bytes which is the pseudo-ops .LDC This means that subsequent referencing the same external syiíbol will at the next start the memory allocation available byte in that relocation base, not at relative location zero (O). There base relocation symbols: .PROG., are three predefined .DATA. and .BLNK.. These relocation bases are used for the program code, seperately located data (in a ROM/RAM environment), and blank (unnamed) common respectively. The .INTERN pseudo-op identifies those symbols within the current subprogram be made which are to accessible as to other programs symbols. external This statewent has no effect on the assembly process for the current program, but merely records the name and symbols value of the identified on the object tape for later use by An symbol be the linkage editor. must internal defined within the current program as a label, or in a direct assignment statement. The .ENTRY pseudo-op functions identically to the .INTERN sometimes pseudo-op, with one addition. is desirable to put many It subroutines with common usage into one "library", and to allow the linkage editor to select only those programs from the library which SywboLs. used. 23.

(26) PASM:. PSA Macro Assembler 3: Pseudo-Operations. Chapter. are called. the program being linkage edited. statement, in addition to functioníng as a .INTERN symbols also flags the specified as prograw entry points. statement, subprogram the is into a library, later put this will specify to If the linkage editor that this program is to be included only one of its entry points is referenced as an external symbol by an already included program. Since these entry points are external to the program referencing them, they must be listed in a .EXTERN statement in the calling program. by .ENTRY. The. if. Identification. Program. facilitate. To. the. identification. of. various. the programmer, manipulated the unique program identification capability. pseudo-op controlling this feature is: by. .PROGID where. id. PSA. Macro. program AsseInbler The format. modules. provides a of the. id,ver,rev is. valid assmbler symbol uniquely identifying the program ver is an B-bit value specifying the program version, and rev is B-bit value specifying the program revision. This an information is ouput to the object file in a special identification record which has no effect on the linkage edit process (as opposed to The information provided by this pseudo-op the .IDENT pseudo-op). is by the linkage editor so as to listed on the map listing presented used in the linkage identify which particular module was actually process. any. module,. Listing. Control. listings are printed. if. listing contains l.. 2. 3. 4.. on. The. the. list. device during the second enabled. listing is printed as the source are processed during the pass. The standard (from left to right):. Program asembly pass program statements. Error flags (if present). Location counter for the first byte generated by this statement. Instruction or data in hexadecimal (maximum of six bytes per line printed). linage Exact of the input statement.. displays all 16-bit quantities standard listing in 16-bit (two These quantities byte), most significant byte first, format. are code by the Z80. A required as properly reversed in the object l6-bit relocatable address relative to the .PROG. relocation base is flagged with an apostrophe ("), one relative to the .DATA. relocation base is flagged with an asterisk (*), and all others are followed by number of their relocation base. the assigned (byte) quantities are displayed as B-bit (byte) values B-bit All (or relocation base), in except when relative to an external symbol which case they are followed by the assigned number of the external or relocation base. The. 24.

(27) PASM:. PSA Macro Assembler 3: Pseudo-Operations. Chapter. Within the macro a macro expansion, only call and those code normally object which actual statements generate listed. are of five a single statement generates more than the maximum If bytes that can be listed on a single line, the remaining bytes are properly generated, but not normally listed. A listing always begins at the top line of the page, and 60 lines with a two line margin at the top, and a two page, printed are per and Each page the bottom. can have an is numbered, margin at line optional title and sub-title. The standard listing options by the and expanded can be changed the following use of pseudo-operations: .PAGE. w. {, L} This statement controls the assetnbly used for the Listing. B-bit B-bit. value, value.. the. optional This change takes. and. page The. length. effect. width width. and. is. length ut,. I, also immediately. is. any an. .PAGE. This statement causes the assembler to skip to the top (by counting lines). A form feed of the next page character in the input text will have the same effect.. .XLIST. This statement. .LIST. This statement is resume. the assembler to stop this point.. causes program at. assembled. normally. used. following. listing the a .XLIST. to. listing.. program. .TALL. This statement causes the assembler to list everything which is processed. This includes all text, macro and expansions, other normally statements all suppressed in the standard listing.. .XALL. This statement is the norrnal resume. .SALL. This statement expansions and subsequent. normally. a. .LALL. listing.. causes. .LALL. following. used. the. suppression. their or. text. .XALL.. It. can. be. of aLL reset. to. macro by a. .XSYM. This statement suppresses the symbol table listing .END normally performed upon encountering the statement.. .LSYM. Normally not of the symbol pseudo—op.. .LADDR. used,. this statement enables the listing suppressed by the .XSYM table previousty. This statement causes the assembler to list all l6-bit quantities in the same order generates them in the object code (least significant byte first).. it. .XADDR. Normally staternent quantities. used. following. resumes the non-swapped. in. a. .LADDR. normal format.. statement, of. listing. this !6-bit.

(28) PASM:. PSA Macro Assembler 3: Pseudo-Operations. Chapter. This statement causes the assembler to list every byte more than one line (at six bytes per generated, even mode, required. In this the assembler will line) is the input attempt to split source statement to indicate which part of the statement is generating which bytes.. .LIMAGE. if. .XIMAGE. .LIMAGE Normally used following a statement resumes the normal listing of generated data per statement.. .LCTL. This statement causes all subsequent listing control be (eg. .XIÁST) Listed themselves. statements to no Normally, control statement listing is itself listed. The .XCTL pseudo-op is used to reset this option.. .XCTL. '. statement, this of only six bytes. .LCTL Normally used following a statement, the default suppression of statement resmes listing of listing control statements.. this the. .SLIST. This statement causes the current listing control flags The four element push-down on a stack. to be saved unchanged. These flags settings remain setting current with the .RLIST pseudo-op. This may later be restored pseudo-op may be followed on the same line with another control pseudo-op, which will take effect prior listing the of the .SLIST statement. to listing. .RLIST. This statement restores the listing control flags from These stack. the top element of the .SLIST push-down with the following take effect the new flags statement .RLIST.. This statement defines the string value to be the at the top of every page of the title to beThe printed be no actual text of the title must listing. 72 .TITLE pseudo the characters. op is longer than If then the new the first statement on a page, will title be printed at the top of that page.. .TITLE. svalue. .SBTTL. svalue. .REMARK. This statement defines the string value to be the the sub-title to be printed at the top of every page of .TITLE rules the sanie as the follows listing. It pseudo-op.. svalue The. .PRNTX. This statement inserts string value can be any. a remark number of. into the listing. lines long.. when encountered, causes the svalue This statement, be typed the console. This on value to string used to statement is frequently print out conditional and the information, to report progress through pass I on very long assemblies.. 26.

(29) PASM:. PSA Macro Assembler Chapter 3: Pseudo-Operations. Control. object. normally produces an object file in the (see Appendix Format D). However, the Standard Relocatable INTEL produce with the compatible object assembler can an file which format is being Standard Absolute Hex Format. To control .PABS are .PREL and used. The .PABS produced, the two pseudo-ops produce INTEL pseudo-op compatible file the assembler to an causes for all following generated code. The .PREL causes the assembler to return to producing a TOL Format file. Every program starts with an implicit .PREL pseudo-op. the assembler can output the object file in both In addition, binary and ASCII. To control which type of output is being produced, and .PHEX .PBIN the two pseudo-ops are used. The .PBIN pseudo-op the assembler to produce a binary causes output in the current The .PHEX pseudo-op format. the output of an ASCII file. causes Every program starts with an implicit .PHEX pseudo-op. To control the generation object modules, two of linkable The .LINK pseudo-op pseudo-ops indicates that Linkage are provided. produced. The information is to be included in the object file .XLINK pseudo-op inhibits this information from being output. Every program starts with an implicit .XLINK pseudo-op. The PSA Macro Assembler provides one additional facility to PSA Z80 Debugging (BUG). System At assist the the programmers option, the assembler will output all of the global (non-local) symbols module in the program into the end of the object file. For each symbol, the assembler also punches its relocation base and its value relative to that base. Two pseudo-ops are provided to control this symbol table output. The .PSYM pseudo-op enables the output, and the .XPSYM pseudo-op disables it. The default is to not output the symbol table (.XPSYM). The. PSA Macro. Assembler. TDL. Conditional. Assembly. be assembled inay on Parts of a program a depending on the results of certain tests specified through the use of the .TFX pseudo-op. The general form of the pseudo-op is:. .IFx arg,[true. conditonal basis to the assembler. text]. ··· {[false text]} within the first square is test on the argument. the text brackets is assembled only if TRUE, and the specified the optional text within the second the condition is set of brackets is assembled Any number false. of spaces blank lines (or linés with only or comments) may seperate the true and false texts. The square brackets around the true text may be omitted there is no false text, and the entire true text is contained on the same line as the .IFx pseudo-op. The first set of conditions which can be tested are the numeric value of the argument. These pseudo-ops are listed below: where. if. if. .IFE .IFN. n,{...] n,[...]. TRUE TRUE. if if. n=O n<O. or n=blank or n>O. 27.

(30) PASM:. PSA Macro Assembler Chapter 3: Pseudo-Operations. n,[...] n,[...] n,[...] n,[...]. .IFG .IFGE. .IFL .IFI.E. TRUE TRUE TRUE. following processing pass.l The. .IFI. n>O ri>O n<O n<O. or. n=O. or. n=O. .IF pseudo-ops or not:. ,[...] ,[...]. .IF2. if if if if. TRUE. if it if it. TRUE TRUE. is pass l is not pass. The. next set of conditionals defined yet or not:. symbol,[...] symbol,[...]. .IFDEF .IFNDEF. The next value argument. s,[...] s,[...]. .IFB .IFNB The and. string tabs.. if if. TRUE TRUE. the the. value. if if. s s. symbol symbol. the assembler. a symbol. has. been. is defined is undefined. tests to see whether format is as follows:. The. is. 1. for whether. tests. set of .IF pseudo-ops is blank or not. TRUE TRUE. for whether. test. its string. is blank is not blank. is blank. if it. is. empty,. or consists. only of. spaces. The last pair They of conditionals operate on string values. and make by character take two string value arguments a character the condition is met. comparison of the two strings to determine The format of these conditionals as follows: is. if. .IFIDN SI .IFDIF sI. S2,[...] s2,[...]. TRUE. TRUE. if. sI. if.sl. identical to s2 different from s2. maximum length of the strings to In making the comparison, all trailing the two arguments.. The. be. compared and. blanks. is 255 characters. tabs are ignored in. Synonyms. for documentation or ease of The already symbols. existing for has Assembler which allow the definition of The format of these pseudo-ops symbols. defined already for. sometimes. It. becomes. programming, to define PSA Macro synonyms. is: .xxSYN. useful,. new names four pseudo-ops. symbol1,symbol2. The only and .MASYN. four pseudo-ops are .SYN, .OPSYN, .SYSYN, difference between the four is that the latter three limit the type of symbol for which the synonym is being defined. operand The being as the second defines statement above of the .SYN the case with the first operand. In synonymous pseudo-op, the symbol tables are searched for the first operand in The.

(31) PSA Macro Assembler Chapter 3: Pseudo-Operations PASM:. The .OPSYN defined symbol, macro, operatíon. .SYSYN pseudo-op limits the search to operations, the The second to programmer operand is defined symbols, and the .MASYN to macros. operand be the synonym identical at the time defined to to the first will not affect the is defined. Later changes to the first operand second. The following are valid synonym definitions:. the order:. programmer. .OPSYN .BYTE,DB .SYN .WORD,DW .SYSYN ALPHA,BETA .SYN A,RI. object. Machine. Validation. Assembler Although the PSA Macro will run only on a Z80 compatible processor, can obviously be used to generate object T(j facilitate 8080 compatible micro-processors. code for any of the pseudo-ops the use of the assembler for this purpose, two additional .18080 and .Z80. are available: pseudo-op The .18080 of machine uses causes all subsequent Z80 (and hence unavailable on the operations which are unique to the be Such uses 8080) to be flagged with a Z warning message. will assembled however. properly The .Z80 pseudo-op (which is the default) disables the feature so that no further Z warnings will be given.. it. Library. File Generation. It is often desirable to maintain object modules as a single source and the library search facility of the pseudo-op .PRGEND the facilitate this. a related set of independent object file for later use with PSA Linkage To Editor (LINK). The format can be used. is:. .PRGEND. This. functions identically to the .END pseudo-op, except module, completing the assembly of the current the assembler continues with another module following. Multíple modules assembled from a single source in this manner file produce a single be object file which can linked in library search mode, and a single listing. Each module assembly is completely independent however. The module be in the source file must terminated by a .END last .PRGEND. pseudo-op, not a pseudo-op. that, after. Library. Source. File. Usage. able to utilize the same section It is often convienentin toa benumber assembler source code of different assemblies. .INSERT pseudo-op The format allows this to be done easily. is: .INSERT. {d: }file{.ext}. 29. of The.

(32) PASM:. PSA Macro Assembler 3: Pseudo-Operations. Chapter where. d. is the optional PIJOS disk specifier (defaulting to the source and ext disk), the name, is desired is the optiorial file file(defaulting file ASM). extension to file This pseudo-op causes the specified file to be copied into the assembly exactly as were in its entirety, and to be treated of the part original source file. All inserted source is flagged Only .INSERT one level of with an "@" on the listing. is allowed, be they cannot nested. This pseudo-op will generate an "F" error if the file is not .INSERT an found, incorrectly specified, or is already in progress.. if it. if. Date. and. Time. Reference. is often desirable to include the date and time of assembly in within messages a the text of various program. The PSA Macro Assembler allows this through the addition of two new pseudcj-ops. pseudo-ops and These .DATE .TIME. These take no arguments. are: They simply cause of the specified ASCII the generation string at date, that location in the program. For is MM/DD/YY, and for bytes of time, generates 8 is HH: MM:SS. Each pseudo-op PODS pseudo-ops used on a these compatible information. are If operating system which does not support time and/or date, then 8 bytes of spaces will be generated by the pseudo-op.. It. it. it. 30.

(33) PASM:. Assembler PSA Macro 4: Yacros. Chapter. 4. Chapter Macros. language programs characteristic of assembly is that many coding sequences are repeated over and over with only a change to in one or two of the operands. It is convenient, therefore, can be generated provide a mechanism by which the repeated sequences Assernbler PSA The Macro by the provides single a statement. be do by sequences the allowing repeated so to to written, capability A single with dummy values for the changed operands, as a macro. by and providing values for name statement, referring to the macro the dummy operands, can then generate the repeated sequence. A common. Macro. Definition. A macro is defined by use of the .DEFINE pseudo-op. This is The macro name must followed by the symbolic name of the macro. follow the rules for the construction of symbols. The name may be enclosed in square brackets. followed by a list of dummy arguments be any symbol by and may The dummy arguments commas, separated are and optional dummy Following the macro name which is convenient. The must be an arguments fio1lowíng are exaznples of equal sign (=). the heading part of a macro definition: .DEFINE .DEFINE .DEFINE. MACRO. = MOVE[A,B] = BIGMAC[ARGI,ARG2,ARG3,%ARG5]. =. Following the macro definition header need not macro. It start on the same byline The body of the macro a is delimited example: For brackets square right (II). .DEFINE [LDA A STA B} Macro. comes as the matched. the. body. definition pair. of. of the header.. left. and. MOVE[A,B]=. Calls. A macro may be called by any statement. A macro consists of by the macro (optionally) name followed of arguments. The a be enclosed in arguments are separated by commas, and may optionally and used (the brackets square the brackets. list. left first. call. right are (II).after If non-blank/non-tab character the macro name is a left by terminated a square bracket), then the arguments are right square bracket. there are n dummy arguments in the macro definition, If then all arguments after the first n are ignored (although they do take space and time to process). omitted, the If the brackets are semicolon ends when a arguwent string carriage is return or encountered. The arguwents must be written in the order in which they are to 31.

(34) PASM:. PSA Macro Assembler 4: Macros. Chapter be. substituted for the dummy arguments. The first argument is each substituted appearance of the first dummy argument, the for second The for the second, actual arguments etc. as are substituted character strings for the dummy arguments, no evaluation of the arguments takes place until the macro is processed. Referring to the definition of MOVE above, the occurrence of the statement:. MOVE. ALPHA,BETA. wiLl. cause. the. substitution. of. ALPHA. for. A and. BETA. for. B. in the. macro.. Statewents which contain macro calls may be labelled and have like any other statement. argurnents carriage return, are terminated only by comma, (when by semicolon, or right square bracket started square left unless These be used arguments bracket). characters may not in the the argument is enclosed in parentheses. Each time an argument is passed but all to a macro, one set of matched parentheses is removed, characters within the parentheses are substituted of the for the dummy argument in the macro. Trailing spaces and tabs at the end of argument (not enclosed in parentheses) are ignored. a macro A substring expression may be used as an argument to a macro, and be paretheses, evaluated before the macro is will if not enclosed in called. do Macros name (and to have arguments. The macro not .need any) 'may anywhere where arguments appear in a statement a symbol and the text of the macro exactly replaces the would normally appear, macro name and its arguments in that statement. comments Macro. if. Comments Comments may be included within a macro comments with the macro (so that they appear however. expanded) the comment takes space by two semicolons (instead is preceded be ignored during the the comment not be stored as part of the of the comment the appearance every time the however.. definition will. If. will. listed, Created. definition.. Storing the the macro is within the macro of the normal one), definition of the macro, and definition. This will eliminate macro expansion is. will. when. Symbols. is called, is often useful to generate symbols them in the call. A good example of this without explicitly stating is labels within the macro body. It is usually not necessary to externally expansion, therefore refer to these label to the macro should be concerned as to what there is no reason why the programmer The with temporary data areas. To avoid same those labels are. however, is necessary that a different symbol be used conflicts, each time the macro is called (even with local symbols, the macro be Created called more than once between two global symbols). could symbols are used for this purpose. Each time a is called, a that requires a created symbol macro When. it. a macro. it. 32.

(35) PASM:. PSA Macro Assembler 4: Mácros. Chapter. These symbols symbol are is generated and inserted into the macro. should followed by four digits). of the form ..nnnn (two periods It symbols be noted that this makes these local symbols (start with two The programmer periods). is advised not to use symbols of this form. The four digits start at 0000 and are incremented by one each time a symbol is created. symbol A created in the macro is specified definition by by a When the macro is preceding a dummy argument percent sign (%). by %symbol called, all dummy arguments replaced of the form are (each with a different one). IE, however, the created symbols position of the dummy argument in the argument list corresponds to an argument provided in the call, then the actual actual argument is used in place of the created one. An actual argument can in fact be empty (signified by two An argument of this kind consecutive commas in the argument list). (a "null" argument) is considered to be "defined as having a value of and the empty string (no characters), will prevent the generation of dummy argument. corresponding a created symbol for its For example: .DEFINE PRINT{A,%B}= [CALL LINPRT JMP. %B. \A\. .ASCIS %8:. ]. This macro prints a message on the printer. The first argument to LINPRT is a line printer the macro is the text string to be printed. routine. Labelling the location following the text is necessary because The use of the indeterminate length of the message. of a created symbol here is useful since there would normally be no reason Calling the macro by: to reference the label. PRINT. This. is the. message. would result in printing was executed. If. macro. PRINT. This. is the. "This. it. had. is the. been. message". when. the. assembled. called:. message,MAIN. the message would have been printed, but control would MAIN, the label which substituted to for %B instead symbol.. be. of. transfered a created. Concatenation The. apostrophe or single quote (") is defined within a macro the as concatenation This allows a macro definition operator. argument to be only part of a symbol with the or expression, character string which is substituted for the dummy argument being joined with other character strings that are part of the macro symbol form a complete to definition This joini.ng is or expression. called concatenation. Concatenation is performed by the assembler when an apostrophe is used between the strings to be joined (one or 33.

(36) PSA Macro Assembler 4: Macros. PASM:. Chapter. both of which .DEFINE [JR"A B]. a dummy macro. argument).. For. example:. When conditional branch statement. called, the argument JR the form single a symbol. If the call were: to to. a appended. BR. be. BR[A,B]=. defines. is. must. A. Z,LOOP. then the generated JRZ. would. be:. LOOP. Default. Arguments. Normally, For. code. missing arguments in the macro:. example,. in. a macro. are replaced. by. nulls.. BYTES[AI,A2,A3,A4,A5,A6]= A1,A2,A3,A4,A5,A6]. .DEFINE [.BYTE. of BYTES[I,2] would generate a .BYTE. arguments to the pseudo-op To remedy the assembler. call. an. error. because. of the missing. provides the programmer with the this, arguments to be used when no argwnent is to supply default provided in the macro call. Default argument are defined as part of the macro definition by enclosing them in parentheses and inserting them immediately after the dummy argument to which they refer. To above solve the problem, the definition would be written as:. means. BYTES[AI(O),A2(0),A3(0),A4(0),A5(0),A6(0)]= AI,A2,A3,A4,A5,A5]. .DEFINE [.BYTE. which. would. arguments. always were. generate six bytes of data, regardless provided in the call.. Interpretation. ASCII. of. Numeric. of. how many. Arguments. (\) preceeds the first character of an the value of the expression following the call, in an ASCII converted slash is to string. This string is then reverse used as the argiment to the call. The value is considered to be a done in the current !6-bit positive value, and the conversion is unless the value is zero. Leading zeros are suppressed radix. the reverse. If. argument. For. V W. = =. slash. a macro. example:. 5 6. MACRO. is the. \V+W, same. \V*W. as:. 34.

(37) PASM:. PSA. Chapter. li,. !4ACRO. if. 4:. Macro Assembler Macros. 30. the current. radix. Under. LO.. Termination. Expansion. Mácro. is. a macro expansion terminates at the end desirable to terminate the is sometimes usually This the end of the A assembly within the macro. conditional. conditions,. normal. definition. prior to. of the macro macro expansion done as of part special pseudo-op. some. It. is provided for. definition.. is. this purpose:. .EXIT pseudo-op immediately processed by the assembler, the .EXIT the end of the macro had terminates the rrtacro expansion, just as Only been the current encountered. expansion is terminated multiple macro expansions are being nested. When. if. Defined. User. Macro. Errors. a macro cause an assembly to have invalid parameters are passed to the A special pseudo-op parameters are missing. is provided. sometimes It isThis might. error.. if. macro,. if. desirable. be. done. when. or to allow this:. string value. .ERROR. This pseudo-op code, the error. will. cause. count to The error. .REMARK pseudo-op, and can nature of the error.. listed. as. an. asterisk (*) to be listed as the error incremented by one, and the line to be exactly as in a string value is treated be used to provide information about the. an be. Nesting may be nested. This means that macros may be both called A macro defined within other macros. that is defined within has been another macro may not be called until the defining macro At that time, the new macro called. is available to be called by any statement. The deep and only limit to how many levels calls macro be amount the may nested of memory ís available. definitions Macros. and. Macro. Labels. and. often desirable to process different parts of the depending on certain conditions, or to repeatitively process one part over again. To provide for both abilities, macro labels and branches are provided. A macro label is specified in the same manner as a normal label, is followed by a right angle bracket (>) instead of a except that There colon (: may be multiple macro labels per line, and a macro Macro label may exist on a line by itself. labels have no effect on. macro. It. is quite. Branching. definition. ).. it.