VAX 11 KS500 CROSS ASSEMBLER USER'S GUIDE ========================================= VERSION 0.6 AUGUST 1983 =========== =========== D.J.HONEY SOFTWARE SCIENCES LTD ========= ===================== CONTENTS ======== Section Contents Page ------- -------- ---- 1 INTRODUCTION 1 2 NOTATION 2 3 ASSEMBLY LANGUAGE ELEMENTS 3 3.1 Source Lines and Fields 3 3.1.1 Introduction 3 3.1.2 Comment Lines 3 3.1.3 Label Field 3 3.1.4 Instruction Field 3 3.1.5 Operand Field 4 3.1.6 Comment Field 4 3.2 Items 5 3.2.1 Introduction 5 3.2.2 Instruction Mnemonics and Directive Names 5 3.2.3 User Symbols 5 3.2.4 Register Names 6 3.2.5 Floating Point Constants 7 3.2.6 Addresses and Address Operator 7 3.2.7 Strings 8 3.2.8 Decimal Constants 8 3.2.9 Octal Constants 8 3.2.10 Hexadecimal Constants 8 3.2.11 Binary Constants 9 3.2.12 ASCII Character Constants 9 3.2.13 Current Address 10 3.3 Expressions 11 3.3.1 Operators 11 3.3.2 Order of Evaluation 12 3.3.3 Relocatability and attributes 12 of expressions 3.4 Literals 15 3.5 Delimiters 16 4 INSTRUCTIONS 17 4.1 Introduction 17 4.2 Memory Reference Instructions 17 4.3 Conditional Jump Instructions 18 4.4 Shift Instructions 19 4.5 Register Operation Instructions 20 4.6 Skip Instructions 21 4.7 Bit Operation Instructions 21 4.8 Argument Instructions 22 4.9 Input/Output Instructions 22 4.10 Interrupt Instructions 23 4.11 Miscellaneous Instructions 23 Section Contents Page ------- -------- ---- 5 DIRECTIVES 25 5.1 Introduction 25 5.2 Data Storage Directives 25 5.2.1 DC Directive 25 5.2.2 DS Directive 25 5.3 Symbol Manipulation Directives 27 5.3.1 Introduction 27 5.3.2 EQU Directive 27 5.3.3 XTRN Directive 28 5.3.4 NTRY Directive 28 5.3.5 KILL Directive 28 5.3.6 HIDE Directive 28 5.4 General Control Directives 29 5.4.1 Introduction 29 5.4.2 TITLE Directive 29 5.4.3 FILL Directive 29 5.4.4 BASE Directive 30 5.4.5 NO_BASE Directive 30 5.4.6 END Directive 30 5.4.7 DEFINS Directive 30 5.4.8 Parity Directives 31 5.5 Conditional Assembly Directives 32 5.5.1 Introduction 32 5.5.2 IF Directive 33 5.5.3 ELSE Directive 33 5.5.4 ENDIF Directive 33 5.5.5 IFB and IFNB Directives 33 5.5.6 IFIDN and IFNIDN Directives 34 5.5.7 IFDEF and IFNDEF Directives 34 5.6 Macros 35 5.6.1 Introduction 35 5.6.2 MACRO and ENDM Directives 35 5.6.3 Commas and Special Characters in Macro 37 Arguments 5.6.4 Nesting of Macros 37 5.6.5 Redefinition of Macros 38 5.7 Listing Control Directives 39 5.7.1 Introduction 39 5.7.2 FORMLN Directive 39 5.7.3 PAGE Directive 39 5.7.4 SUBTTL Directive 39 5.7.5 NLIST and LIST Directives 40 5.7.6 NCLIST and CLIST Directives 40 5.7.7 NMLIST and MLIST Directives 40 5.7.8 NBLIST and BlIST Directives 40 5.8 Program Section Directives 41 5.8.1 Introduction 41 5.8.2 RSECT Directive 41 5.8.3 ASECT Directive 41 6 SEPARATION OF CODE AND DATA 43 7 ASSEMBLER OPERATION 45 Section Contents Page ------- -------- ---- 8 ASSEMBLY LISTING AND ERRORS 48 8.1 Introduction 48 8.2 Source Listing 48 8.3 Program Section Details 48 8.4 Symbol Table 49 8.5 Cross Reference Listing 49 8.6 Assembly Errors 49 APPENDICES A PERMANENT SYMBOLS 52 B CUSTOMISING THE PERMANENT SYMBOL FILE 54 C SYNTAX OF EXPRESSIONS AND CONSTANTS 57 D ASSEMBLER ERROR MESSAGES 59 E INCOMPATABILITIES WITH KS500 HOSTED ASSEMBLER 64 Page 1 1 INTRODUCTION ============ The VAX 11 hosted KS500 cross assembler runs on the VAX 11 series of computers in native mode under the VMS operating system. The cross assembler reads one or more files containing KS500 assembly language statements and optionally produces three files: an object file containing relocatable binary data, a listing file including optional symbol table and cross reference listing, and an error file listing any errors found during assembly. It is a two pass assembler; the first pass is used to define all symbols and resolve forward references, whilst the second pass is used to generate the object code and assembly listing. The cross assembler accepts nearly all of the standard KS500 instructions and directives, but in addition provides enhanced facilities as a compatible superset. Existing assembly language programs may thus be transported to the VAX environment with only minor or no changes. This user's guide describes the facilities provided by the standard cross assembler, and gives instructions how to run it under the VMS operating system. The assembly language may be further enhanced or customised by changing or creating a new permanent symbol file. This file is read by the cross assembler to define the instruction mnemonics, directive names and pre-defined user symbols. A brief description of the instruction set is given; for a detailed account, the user is referred to the KS500 programmers instruction set manual. Page 2 2 NOTATION ======== The following notation is used throughout this user's guide: [ item ] Optional item which may be omitted. ... Horizontal ellipsis indicates that an item may be repeated. . . Vertical ellipsis indicates that intervening lines . have been omitted. A single ASCII character with the specified name. E.G. means carriage return. Type of item or grammatical construction. E.G. means any valid integer expression. Page 3 3 ASSEMBLY LANGUAGE ELEMENTS ========================== 3.1 Source Lines and Fields ----------------------- 3.1.1 Introduction An assembly language program consists of one or more files containing assembler source lines. Each line may contain comments which generate no code, instructions which generate code usually on a one to one basis, and directives which control the assembler and provide facilities for storing data. Each line may contain up to four separate fields: a label field, an instruction field, an operand field, and a comment field. Some of these fields are optional; others must be supplied in certain circumstances. 3.1.2 Comment Lines A line starting with an asterisk or the explicit comment marker ! is treated as a comment line and ignored by the assembler. It is recommended that the comment marker ! be used for consistency with comments placed after instructions or operands. 3.1.3 Label Field The label field always starts in column 1 of the source line and may contain any valid user symbol. ( See section 3.2.3 ) Most instructions use the label field for labels so that memory reference instructions may refer to a label rather than an address. In these circumstances, the label is optional and may be omitted by starting the label field with at least one space or tab. Some directives, for example the EQU directive, use the label field to define symbols. In these cases, the label field cannot be omitted and must contain a valid user symbol. Omitting the symbol will result in a "Label Error" being reported. The label field may be terminated by a tab, space, :, !, or . It is recommended that all labels be terminated by a colon, and symbols by a space or tab. This helps to make it clear whether the label field is holding a label, or being used to define a user symbol. 3.1.4 Instruction Field The instruction field is separated from the label field by one or more spaces or tabs, or a colon followed by zero or more spaces or tabs. If the instruction field starts with the explicit comment marker !, the assembler ignores the rest of the line, and the comment appears in the listing tabulated at the instruction field. Otherwise, the instruction field must contain a valid assembler instruction or directive name, or a defined macro name. The field may be terminated by a space, tab, !, or . Any comment after an instruction appears in the listing tabulated to the comment field. Page 4 3.1.5 Operand Field The operand field is separated from the instruction field by one or more spaces or tabs. The field is used to hold operands in a form specific to the type of instruction or directive in the instruction field. If an instruction does not require any operands, then this field should be omitted by terminating the line with or an explicit comment starting with !. 3.1.6 Comment Field The comment field is separated from the operand field by one or more spaces or tabs, or by the explicit comment marker !. If no operand field is present, or no instruction and operand field is present, then comments can only be included using the explicit comment form. Comments may contain any character and are terminated by . Page 5 3.2 Items ===== 3.2.1 Introduction A source line may contain certain types of objects or items in each of the label, instruction and operand fields. These items represent different classes of data such as strings, decimal constants, floating point constants etc. and are used to express data in a form most convenient or relevant to the user. 3.2.2 Instruction Mnemonics and Directive Names Each type of instruction in the KS500 instruction set is given a unique instruction name or mnemonic. Similarly, assembler directives are given unique names which specify the required action. Instruction and directive names may only appear in the instruction field. They may be of any reasonable length, although only the first six characters are significant. They may contain any of the following characters: A to Z (upper case only), 0 to 9, and . In addition, the underline character _ may be freely inserted within the names as a separator, although this should not be the first character. The underline is ignored by the cross assembler and is not part of the name. It may be used to make an instruction name or directive more readable. For example, the directive NOBASE is more clearly written as NO_BASE; the two are equivalent. Instruction and directive names are permanent and may only be redefined by modifying the permanent symbol file which the cross assembler reads before commencing assembly. (See Appendix B) 3.2.3 User Symbols User symbols are names which the user is free to define and associate with values or addresses to make the program easier to understand. Labels are an example of user symbols. These symbols are treated quite separately from the fixed instruction names or register names. Hence it is permissable to define a user symbol with the same name as an instruction, directive or register. The context of its use determines which type of object is meant. User symbols may be of any reasonable length, although only the first six characters are significant. For example, the symbol SERVOMOTOR is considered identical to the symbol SERVOMECHANISM. This may be used with caution to greatly improve the readability of assembler programs. Symbols may contain any of the following characters: A to Z (Upper case only), 0 to 9, or , although they must not start with a digit. The underline character _ may be freely used as a separator within symbols to make their meaning clear. Symbols should not start with an underline character. For example, the symbol SERVOMOTOR is more clearly written SERVO_MOTOR. Page 6 3.2.4 Register Names Register names have the same form as user symbols but, like the instruction mnemonics, are fixed and cannot be redefined. They are treated quite separately from instruction mnemonics or user symbols. The following sets of register names are defined: Name Desciption Type Value 0 Zero pseudo register Source 0 Z Zero pseudo register Source 0 S Status register Bit Operation 0 D Accumulator Extension General 1 P Program counter General 2 B Base register General 3 L Link register General 4 A Accumulator General 5 T Temporary register General 6 X Index register General 7 W Single bit register Bit Reg 0 DOF Dynamic overflow Bit Reg 1 SOF Static overflow Bit Reg 2 CRY Carry Bit Reg 3 R Memory Relocation Reg GET/PUT Reg 0 Q I/O Relocation Reg GET/PUT Reg 1 S Status register GET/PUT Reg 2 X Execute Index Reg Exec Reg 0 BX Execute Base + Index Exec Reg 1 L Execute Link Exec Reg 2 A Execute Accumulator Exec Reg 3 where the register types are as follows: Source : May be used as the source register in a register operation instruction. Destination : May be used as the destination register in a register operation instruction. Bit Reg : May be used as a single bit register name in a bit operation instruction. Bit Oper Reg : May be used in conjunction with a bit number in a bit operation instruction. General : May be used in a register or bit operation instruction. Exec Reg : May be used in an EXECute instruction. Page 7 3.2.5 Floating Point Constants Floating point constants may only be used in certain contexts, for example, in literals (See section 3.4) or in the DC data constant operand field. (See section 5.2.1). They may have any of the following forms: F or, F where is an optional leading + or -. The may be written in any of the following forms: . . . The is written in the form E. Examples of valid floating point constants are: F2.3 F.05 F001.2E2 F1.E0 F1.0E+2 F1.0E-2 F-3E5 F-5.7E-12 Examples of invalid floating point constants are: F 2.3 Spaces are not allowed F2E2.3 Exponent cannot have a decimal point F-2E Missing exponent F++2.0 Only one optional sign allowed 3.2.6 Addresses and Address Operator The address operator A() is used to indicate that the item contained within the brackets is an address or an integer 16 bit quantity. The A() operator is also used as a modifier for strings to maintain compatability with the Kongsberg hosted assembler. The cross assembler allows arithmetic expressions to be written without the use of the A() operator providing that there is no ambiguity between a user symbol starting with a F and a floating point constant. For example, A(FRED) may be written just as FRED. However, A(F32) cannot be written as F32 since the cross assembler interprets F followed by a digit as meaning a floating point constant. The A() operator may thus be dropped providing that the expression does not start with a user symbol of the form F followed by a digit or a period. Page 8 3.2.7 Strings The assembler allows users to specify strings in literals and in the operand field of the DC data constant directive. Strings are written in the following forms: H'' for Left/Right packing, or A(H'') for Right/Left packing, where may contain any character except , and where each single quote is represented by two such quotes. The strings are assembled with two ASCII characters packed in each word, the order being dictated by the use of the A() modifier. Any unused byte in the last word is set to zero. For example, the string H'PLUGH' is assembled as: ------------- | 'P' | 'L' | | 'U' | 'G' | | 'H' | 0 | ------------- By default, each character is assembled with zero parity. This may be changed by using one of the parity directives described in section 5.4.8. 3.2.8 Decimal Constants Decimal constants consist of one or more decimal digits. They may be used wherever an expression or data constant is permitted. Negative decimal constants are written as an expression -. 3.2.9 Octal Constants Octal constants may be written in any of the following forms: (i) @ (ii) @+ (iii) @- where consists of one or more octal digits. The forms (ii) and (iii) are for compatability with the Kongsberg hosted assembler. It is recommended that users write negative octal constants as an expression of the form -@ for consistency with all the other constants. 3.2.10 Hexadecimal Constants The cross assembler accepts hexadecimal constants in the form $, where consists of one or more hex digits. Negative hex constants are written as an expression of the form -$. Page 9 3.2.11 Binary Constants Binary constants are written in the form %, where consists of one or more binary digits. Negative binary constants are written as an expression of the form -%. 3.2.12 ASCII Character Constants Character constants are not to be confused with strings. Strings may only be written in literals or in the operand field of the DC data constant directive. Character constants are integer values which may be included as part of an expression, or wherever an expression is permitted. Character constants have the following forms: '' Single ASCII character in lower byte, upper byte is zero. '' Character 1 in upper byte, character 2 in lower byte, both characters ASCII coded. where may be any character excluding , and where a single quote is written as two such single quotes. Examples: --------------------------------- 'A' | 0 | 'A' | --------------------------------- --------------------------------- '''' | 0 | | --------------------------------- --------------------------------- 'AB' | 'A' | 'B' | --------------------------------- --------------------------------- '''''' | | | --------------------------------- If an ASCII character constant contains more than two characters, a value error is reported and the last two characters are used. By default, each character is assembled with zero parity. This may be changed by using one of the parity directives described in section 5.4.8. Page 10 3.2.13 Current Address Whenever it is required to use the value of the current address, the item * may be used. This is used most often in memory reference instructions where the use of a label is not warranted. Example: IOT LPR ! Transfer to printer if ready JMP *-1 ! Not ready, try again The * item is not to be confused with the multiplication operator *. The meaning of an asterisk is made unambiguous by the context of its use. Examples: 1*2 Multiplication operator 1+* Current Address + 1 1** 1 multiplied by the current address Page 11 3.3 Expressions ----------- 3.3.1 Operators The cross assembler allows the following operators to be used within arithmetic expressions: ( ) Parantheses to force the order of evaluation. Binary Operators * / Multiplication and Division (Signed) 'MOD' Modulus, remainder after division. For an expression of the form A'MOD'B the result has the same sign as the left hand term A. E.G. 11'MOD'5 = 1 -11'MOD'5 = -1 11'MOD'-5 = 1 -11'MOD'-5 = -1 'SHR' Shift Right: X'SHR'Y means X shifted right Y places. 'SHL' Shift Left: X'SHL'Y means X shifted left Y places. + - Addition, Subtraction = Relational Operators. If the condition is true, <> the result is -1 (@177777). If the condition < is false, the result is 0. <= > Examples: 2<3 = -1 >= 2>3 = 0 0>=0 = -1 -1<0 = -1 'AND' Logical AND. For example: %1101'AND'%1001 = %1001 'OR' Logical Inclusive OR. 'XOR' Logical Exclusive OR. Unary Operators - these operate on a single right hand term and may be combined. + Non-negation. - Negation, 2's complement. 'NOT' Bit-wise complement, 1's complement. 'HIGH' Selects the upper byte of a 16 bit quantity. This is exactly the same as shifting the item 8 places right. E.G. 'HIGH''AB' = 'A' Page 12 'LOW' Selects the lower byte of a 16 bit quantity. This is exactly the same as ANDing the item with @377. E.G. 'LOW'@123456 = @56 3.3.2 Order of Evaluation - Operator Precedence Expressions are evaluated according to the precedence or priority of the operators. When several items are joined by operators of the same precedence, evaluation is performed left to right. The operators are evaluated in the following order: ( ) Parenthesised sub-expressions are evaluated first. + - 'NOT' 'HIGH' 'LOW' Unary operators next. * / 'MOD' 'SHR' 'SHL' Multiplication, Division and Shifting. + - Addition, Subtraction = <> < <= > >= Relational operators 'AND' Logical AND 'OR' 'XOR' Inclusive and Exclusive OR evaluated last. Examples: 1+2*3 = 7 (1+2)*3 = 9 1+2*-3 = -5 1+2*3=7 = -1 (True) (1+2)*3=7 = 0 (False) 1+2*3=7'AND'1>0 = -1 (True) It is recommended that parantheses be used where the meaning or result of an expression is unclear. The last example should be written equivalently as follows: ((1+2*3)=7)'AND'(1>0) 3.3.3 Relocatability and Attributes of Expressions Items within expressions have a relocation attribute. This attribute may take one of three possible states: (i) Absolute - The value is fixed and will not be changed when the program is link-loaded. (ii) Relocatable - The value is relative to the start of a relocatable program section and will be relocated when the program is link-loaded. (iii) External - The value is not defined within the current program module, but will be supplied from another module when the program is link-loaded. Page 13 Absolute and relocatable items also have another attribute: the program section attribute. This indicates which program section, if any, the item was defined in or associated with. This attribute is used to check that expressions do not mix labels defined in different program sections. It is also used for implicit base addressing with the BASE directive to determine whether the operand of a memory reference instruction is to be addressed relative to the program counter or base register. (See section 5.4.4) When two terms in an expression are joined by a binary operator, the relocation attribute of the result depends upon the attributes of each of the terms and upon the operator used. Some operations are invalid and will result in a relocation error being reported. The rules for relocatability in expressions are given below. Operation Case Result Error Multiplication Abs * Abs Abs Abs 0 * Reloc or Ext Abs 0 Abs 1 * Reloc or Ext Reloc or Ext Abs <> 0,1 * Reloc or Ext Abs Reloc Reloc or Ext * Abs 0 Abs 0 Reloc or Ext * Abs 1 Reloc or Ext Reloc or Ext * Abs <> 0,1 Abs Reloc All other cases Abs Reloc Division Abs / Abs 0 Abs 0 Value Abs / Abs <> 0 Abs Abs / Reloc or Ext Abs Reloc Reloc or Ext / Abs 0 Abs 0 Reloc Reloc or Ext / Abs 1 Reloc or Ext Reloc or Ext / Abs <> 0,1 Abs Reloc Modulus Abs 'MOD' Abs 0 Abs 0 Value Abs 'MOD' Abs <> 0 Abs Abs 'MOD' Reloc or Ext Abs Reloc All other cases Abs Reloc Shift Abs ('SHL' or 'SHR') Abs Abs Reloc Reloc ('SHL' or 'SHR') Abs 0 Reloc Extern ('SHL' or 'SHR') Abs 0 External All other cases Abs Reloc Addition Abs + Abs Abs Abs + Reloc or Ext Reloc or Ext Reloc or Ext + Abs Reloc or Ext All other cases Abs Reloc Subtraction Abs - Abs Abs Reloc or Ext - Abs Reloc or Ext Reloc - Reloc (same sections) Abs Reloc - Reloc (different sectn) Abs Reloc All other cases Abs Reloc Relational Only absolute values allowed Abs Logical Only absolute values allowed Abs Page 14 Unary Operators Absolute Abs + Reloc Reloc + External External All other cases Absolute Reloc The rules may seem complex, but may be easily summarised as follows: (i) Absolute terms may use any of the operators, providing that a division by zero is not performed. (ii) Relocatable or external terms may only be multiplied by 0 or 1 using the multiplication, division or shift operators. Relocatable or external terms may only have absolute terms added to them. Two relocatable terms may be subtracted to give an absolute difference, but they must be associated with the same relocatable section. Page 15 3.4 Literals -------- Literals are used in memory reference instructions to save the programmer from having to assign specific labels for data constants. For example, if the index register X is to be loaded with the value 5000, then this can be done using a conventional label: LDX C5000 . . . C5000: DC 5000 ! Data constant to be loaded This can be accomplished by using a literal as follows: LDX =5000 . . . FILL The FILL directive informs the assembler that a convenient point has been reached to save any literals such as the constant 5000. The cross assembler handles the storing of the literals and the calculation of their addresses. The general form of a literal is: = where may be any of the following types of items: (i) Floating Point Constant (ii) String ( with or without the A() operator ) (iii) Integer Expression - this includes all the other types of data constant. Note, that since a literal is addressed relative to the program counter, memory reference instructions should not specify base addressing. E.G. LDX =5000,B will result in an address error being reported and the instruction will be assembled as if the ,B was missing. Page 16 3.5 Delimiters ---------- The Konsgerg hosted assembler uses three different types of delimiters in the operand field: (i) Separates registers, address and addressing modifiers. (ii) Separates a processor or interrupt level from an interrupt register name. (iii) Separates items in a list for such directives as DC, NTRY, XTRN etc. The cross assembler accepts these delimiters in the cases described, but also allows a to be used as a delimiter in the operand field for any instruction or directive. It is recommended that the the use of should not be continued because of its inconsistency with the for most instructions and directives. The cross assembler allows extra spaces or tabs to be freely inserted after any of the three delimiters in the operand field. Commas in the instruction field are part of the instruction mnemonic and hence spaces or tabs should not be inserted. Page 17 4 INSTRUCTIONS ============ 4.1 Introduction ------------ The cross assembler accepts all of the standard KS500 instruction names. It also allows more meaningful synonyms to be used as a superset of the native Kongsberg instruction set. These synonyms are assembled into equivalent standard instructions as described in each sub-section. 4.2 Memory Reference Instructions ----------------------------- These are instructions which directly read or write their operands from or to memory. The operand may consist of an address or a literal as shown below. If the operand is a relocatable address, it must be in the current program section and within the addressing range -128 to +127 from the current instruction. Operand Field: [
] or =[
] where
may include any or all of the following addressing modes: ,B Base Addressing (Not for Literals) ,I Indirect Addressing ,X Indexed Addressing It is recommended that the addressing modes be written in the order B I X since this represents the order in which the effective operand address is calculated by the Kongsberg processor. Examples: LDA SERVO_MOTOR,B LDA =5000 LDF =F32.5 LDF =H'STRING' STL FLINK,B,I,X JMP LABEL The following standard instructions and enhanced synonyms are provided: Instruction Equivalent Description LDA Load accumulator LDD Load accumulator and D register LDX Load index register LDL Load link register LDF Load floating point STA Store accumulator STD Store accumulator and D register STX Store index register STL Store link register STF Store floating point ADD Add to accumulator Page 18 SUB Subtract from accumulator AND AND with accumulator OR Inclusive OR with accumulator FAD Floating Add FADD FAD Floating Add FSB Floating Subtract FSUB FSB Floating Subtract FMU Floating Multiply FMUL FMU Floating Multiply FDV Floating Divide FDIV FDV Floating Divide JMP Jump to address JUMP JMP Jump to address JPL Jump to subroutine JSUBR JPL Jump to subroutine MSW Memory swap MSWAP MSW Memory swap MIN Memory Increment and skip if zero ISZ MIN Increment and skip if zero ZRO Pseudo instruction with zero opcode 4.3 Conditional Jump Instructions ----------------------------- These are instructions which jump to the address specified in the operand field if the specified condition is true. The address modifier bits in the opcode are used to indicate the required condition and hence the operand may only consist of an address. Operand: Examples: JAF LOOP JAZ ZERO_ACC The following standard instructions and enhanced synonyms are provided: Instruction Equivalent Description JAP Jump if accumulator positive JAN Jump if accumulator negative JAZ Jump if accumulator zero JAF Jump if accumulator non zero (filled) JXZ Jump if index register zero JXN Jump if index register non zero JPC Increment index register and jump if its positive. JNC Increment index register and jump if its negative. JNZ JAF Jump if accumulator non zero. INXJXP JPC Increment X, jump if X positive. INXJXN JNC Increment X, jump if X negative. Page 19 4.4 Shift Instructions ------------------ The shift instructions act directly on the A and/or D registers providing three different sorts of shift operations: (i) Arithmetic Shift The sign bit is preserved, and on right shifts extended. (ii) Logical Shift The whole word(s) is shifted with vacant bits set to zero. (iii) Rotational Shifts The whole word is rotated with the vacant bits being taken from the opposite end of the word(s). Each of these types of shift may act on the accumulator, the D register, or the accumulator and D register combined as a doubleword register. The operand is specified as shown below. Operand: Number of shifts or ,X No of shifts modified by index register. where is in the range -32 to +31. The following standard instructions and enhanced synonyms are provided: Instruction Equivalent Type of Shift Directn Register(s) SLA Arithmetic Left A SRA Arithmetic Right A SRAZ Logical Right A SLD Arithmetic Left D SRD Arithmetic Right D SRDZ Logical Right D SLL Arithmetic Left A and D SRL Arithmetic Right A and D SRLZ Logical Right A and D SLRA Rotational Left A SRRA Rotational Right A SLRD Rotational Left D SRRD Rotational Right D SLRL Rotational Left A and D SRRL Rotational Right A and D ASHLA SLA Arithmetic Left A ASHRA SRA Arithmetic Right A LSHRA SRAZ Logical Right A ASHLD SLD Arithmetic Left D ASHRD SRD Arithmetic Right D LSHRD SRDZ Logical Right D ASHLAD SLL Arithmetic Left A and D ASHRAD SRL Arithmetic Right A and D LSHRAD SRLZ Logical Right A and D ROTLA SLRA Rotational Left A ROTRA SRRA Rotational Right A ROTLD SLRD Rotational Left D Page 20 ROTRD SRRD Rotational Right D ROTLAD SLRL Rotational Left A and D ROTRAD SRRL Rotational Right A and D 4.5 Register Operation Instructions ------------------------------- These instructions specify operations between any two general registers. The instruction requires the operand field to contain one of the following types of operand: (i) No operand Some synonyms assemble directly to an instruction. (ii) Single register The source register is implicit in the instruction or synonym and should not be specified. (iii) Two registers A source register and a destination register. The Z or 0 pseudo register may only be used for the source register, since it has no meaning as a destination. Listed below are the instructions provided and which type of operand has to be supplied: Instruction Operand Equivalent Description COPY R1,R2 Copy R1 to R2 CLR R2 COPY Z,R2 Clear register COPY,N R1,R2 Copy 1's complement ONECOM R2 COPY,N R2,R2 1's complement CPYI R1,R2 Copy and increment INC R2 CPYI R2,R2 Increment R2 CPYI,N R1,R2 Copy 2's complement TWOCOM R2 CPYI,N R2,R2 2's complement CPYY R1,R2 Copy with carry CPYY,N R1,R2 Copy 2's com & carry RADD R1,R2 Register add RADD,N R1,R2 Add 1's complement DEC R2 RADD,N Z,R2 Decrement register RADI R1,R2 Reg add with increment RADI,N R1,R2 Add 2's comp = subtract RSUB R1,R2 RADI,N R1,R2 Register subtract RADY R1,R2 Reg add with carry RADY,N R1,R2 Add 1's compl & carry RMPY R1,R2 Register multiply RMPY,N R1,R2 Register divide RDIV R2 RMPY,N Z,R2 Register divide EXIT COPY L,P Return from subroutine SWAP R1,R2 Swap registers RAND R1,R2 Register AND RAND,N R1,R2 AND with 1's comp of R1 ROR R1,R2 Register Inclusive OR ROR,N R1,R2 OR with 1's comp of R1 RXOR R1,R2 Register Exclusive OR RXOR,N R1,R2 XOR with 1's comp of R1 Page 21 4.6 Skip Instructions ----------------- Skip instructions perform comparisons on two general registers and skip the next instruction if the specified condition is true. The operand is specified as an addition or subtraction operation between the registers as follows: + or - The following standard instructions are provided: SKEQ Skip if result equal to zero SKGE Skip if result greater or equal to zero SKUE Skip if result not equal to zero SKLT Skip if result less than zero Examples: SKLT R1-R2 Skip if R1-R2 less than zero, i.e. R1 less than R2. SKEQ R1+R2 Skip if R1+R2 equals zero, i.e. if R1 = -R2. The following enhanced synonyms are also provided: SKGT R1-R2 assembled as SKLT R2-R1 SKLE R1-R2 assembled as SKGE R2-R1 4.7 Bit Operation Instructions -------------------------- These instructions perform operations a single bit in any of the general registers. The operand may be specified as a bit register name, or as a general register name followed by a bit number. Operand: or , where may be one of the following: W Temporary bit register CRY Carry SOF Static overflow DOF Dynamic overflow and may be one of the following: S Status register D D register P Program counter B Base register L Link register A Accumulator T Temporary register X Index register and must yield a value between 0 and 15. Page 22 4.8 Argument Instructions --------------------- Argument instructions use the lower byte of the opcode to hold the operand of the instruction, a signed 8 bit value. The operand may thus consist of an integer expression in the range -128 to +127. Operand: The following instructions are provided: Instruction Description SAA Set argument to accumulator SAX Set argument to index register SAL Set argument to link register SAB Set argument to base register AAA Add argument to accumulator AAX Add argument to index register AAL Add argument to link register AAB Add argument to base register 4.9 Input/Output Instructions ------------------------- These instructions transfer data between the accumulator and the device specified by the device code. The operand may consist of any valid integer expression yielding a value between 0 and 255. The standard Kongsberg instructions use bit 7 to indicate the direction of transfer, i.e. whether it's a read or write. Hence operands between 0 and 127 are reads, 128 to 255 are writes. Instruction Description IOIS Skip the next instruction if the device has not requested an interrupt. IOPI Prepare device for interrupt. IOA Transfer data to/from device. IOAP Transfer data to device which requested an interrupt. IOS Skips the next instruction if the specified device is ready. IODI Disable interrupt from device. IOT Attempt transfer of data and skip if device was ready. IOTP Start the device, prepare it for interrupt and transfer data. Page 23 4.10 Interrupt Instructions ---------------------- Interrupt instructions control the state of the Kongsberg interrupt system. These are types of SDC ( System Device Call ) instructions which are explicitly provided for clarity. The operand field must contain one of the following types of operand, depending on the type of instruction: Operand: IDR Interrupt Detect Register IER Interrupt Enable Register IVR: Interrupt Vector Register and Level RLR: Running Level Register and processor number. ICR: Interrupt Control Register and Level ILR: Interrupting Level Register and processor no. The following instructions are provided: READ Read Interrupt Status. The operand field may contain any of the registers IDR, IER, IVR, RLR or ILR. MACL Masked Clear. This clears bits in the specified interrupt register as specified by the accumulator. The operand field may contain any of the registers IDR, IER, IVR or ICR. MAST Masked Set. This sets bits in the specified interrupt register as specified by the accumulator. The operand field is as for the MACL instruction. 4.11 Miscellaneous Instructions -------------------------- The following instructions are provided: Instruct Operand Operand Limits Description TEST Test on computer type. CPM Clear priveledge mode. USAV Unsave registers from level head. ZWL Set interrupt wait level. NLZ -128 to +127 Normalise floating point accumulator. DNZ -128 to +127 De-normalise floating point accumulator. EXF 0 to +127 Executive Function. Page 24 MOC 0 to +15 Monitor Call. ZRLR 0 to +15 Set Interrupt running level register. WAIT Wait on interrupt level. EXEC X, BX, L or A Execute instruction pointed to by register. GET R, Q or S Get specified register into accumulator. PUT R, Q or S Put specified register from accumulator. Page 25 5 ASSEMBLER DIRECTIVES ==================== 5.1 Introduction ------------ Assembler directives provide facilities for controlling the cross assembler and storing data in a convenient form. The cross assembler accepts most of the standard KS500 directives, and in addition provides some enhanced features. The directives may be divided into the following categories: (1) Data Storage (2) Symbol Manipulation (3) General Control (4) Conditional Assembly (5) Macros (6) Listing Control (7) Program Sectioning 5.2 Data Storage Directives ----------------------- 5.2.1 DC Directive The DC ( Data Constant ) directive allows the user to store data constants in the most convenient or relevant form. The operand field may contain one or more items as follows: DC [,...] where may be any of (i) Floating point constant (ii) String (iii) Integer expression The items may be separated by commas or semicolons. 5.2.2 DS directive The DS ( Data Storage ) directive reserves the number of words specified by the operand field. This is used to allocate storage space for program variables. The directive is written in the form: DS The should not contain any symbols which are undefined in pass 1, since on pass 2, subsequent instructions may become displaced differently from pass 1 and result in phasing errors being reported. Example: DS NO_OF_WORDS NO_OF_WORDS EQU 5 Page 26 When the DS directive is assembled in pass 1, the symbol NO_OF_WORDS is undefined, and the statement is equivalent to DS 0. On the second pass, the symbol is defined, and is equivalent to DS 5. Any instructions which follow will thus be displaced by 5 words relative to their positions in pass 1. This situation is remedied by assigning the symbol value before its use in the DS directive. Page 27 5.3 Symbol Manipulation Directives ------------------------------ 5.3.1 Introduction This group of directives allows the programmer to define symbols with particular values and attributes for general use within a program. The following directives are supported: EQU EQUates a symbol with a value, i.e. defines a symbol. XTRN Declares a symbol as being external, i.e. not defined within the current assembly module. NTRY Declares that a symbol is to be an entry, i.e. made available to other modules at link-load time. KILL Kills or deletes a symbol definition. This allows the same symbol name to be reused with a different value. HIDE Makes a symbol hidden, such that it does not appear in the symbol table or cross reference listing unless the /HIDDEN assembly option is used. 5.3.2 EQU Directive The EQU directive is used to define meaningful names for program constants. The directive is written in the following form: SYMBOL EQU where is a valid user symbol appearing in the label field, and represents the value to be assigned to the symbol. Example: OPS_DISPLAY EQU @343 SDC OPS_DISPLAY Note that if the contains any undefined symbols, the symbol EQUated will also be undefined. Forward referencing is limited to two levels because the assembler performs two passes. Example: A EQU B B EQU 2 This is correct, since at the end of pass 1, B will be defined so that on the second pass A can be defined. Example: A EQU B B EQU C C EQU 3 Page 28 This is incorrect, since at the end of pass 1, symbol C is defined. On pass 2, the assembler cannot define A since the definition of B follows it. Hence at the end of pass 2, symbols B and C will be defined, but symbol A will be undefined. 5.3.3 XTRN Directive The XTRN directive defines one or more symbols as external to the current program module. These will be resolved by the link loader from other modules containing corresponding NTRY points. The operand field may contain one or more symbols to be declared. The symbols may be separated by commas or semicolons. XTRN [, ...] 5.3.4 NTRY Directive The NTRY directive makes one or more symbols global, i.e. available to other modules. This is used to resolve references to external symbols at link-load time. The symbols may be separated by commas or semicolons in the format shown below: NTRY [, ...] 5.3.5 KILL Directive The KILL directive deletes one or more previously defined symbols. This may be used to re-define symbols or to prevent other routines later on in the program from inadvertently using the symbols. The operand field may be blank, in which case all currently defined symbols are killed. Otherwise, the operand field should contain one or more explicit symbols to be killed as shown below. KILL [, ...] 5.3.6 HIDE Directive The HIDE directive makes the specified symbol(s) hidden. Such symbols do not appear in the symbol table or cross reference listing unless the /HIDDEN assembler option is specified. This allows the programmer to define useful program constants for a suite of programs without the symbols being listed when each program module is assembled. A number of symbols are hidden automatically in the symbol definition file which is read by the assembler. Further details of these are included in Appendices A and B. The directive may be written in the following forms: HIDE ! Hides all known symbols HIDE [,...] ! Hide specific symbols Page 29 5.4 General Control Directives -------------------------- 5.4.1 Introduction This group of directives provide facilities to control the operation of the cross assembler. The following directives are provided: TITLE This names the current assembler program module. This information appears in the assembly listing at the top of each page and is also passed to the object code file so that the link loader may read the module name. FILL Instructs the cross assembler to fill in any literals which have been used. The literals are output in sequential locations starting at the current address. BASE This enables the use of "implicit base addressing" so that memory reference instructions can be written without the ,B address modifier. The assembler determines the addressing mode required and calculates the offset to the required item. NO_BASE Disables the use of any previous BASE directive. END Informs the assembler that the end of the current program module has been reached. Any further lines in the current source file, or any further source files are ignored. DEFINS This is used to define the Kongsberg instruction set and the assembler directives before commencing assembly of any user program. 5.4.2 TITLE Directive This defines the current program module name. The operand field should contain a valid symbol name to be used for the module name. As with user symbols, only the first six characters are significant. Only one TITLE directive must appear in a program module. Subsequent attempts to re-define the module name will be reported as a multiple definition error and the original name will be kept. If the program module does not contain a TITLE directive, a default module name is used, this being up to the first six characters of the first source filename. 5.4.3 FILL Directive This directive is used in conjunction with literals as described in section 3.4. The FILL directive forces the assembler to output any literals used since the previous FILL. The directive should not have any item present in the operand field. Page 30 5.4.4 BASE Directive The BASE directive enables the use of "implicit base addressing". This saves the programmer from having to write memory reference instructions using the ,B addressing mode. The cross assembler determines from the operand whether the item should be addressed relative to the program counter or base register. This can be used to assist in the separation of code and data as described in section 6. The operand field should contain an address specification as shown below: BASE This enables the use of implicit base addressing where the base register is assumed to hold the address specified by . Further details of the use of this directive are given in section 6. 5.4.5 NO_BASE Directive This directive disables the use of any previous BASE directive. By default, implicit base addressing is disabled unless explicitly requested using the BASE directive. The operand field should be blank. 5.4.6 END Directive The END directive marks the end of the current assembler program and any further source lines or files are ignored. If an END directive is omitted from the program, the assembler terminates assembly when the end of the last source file is reached. The directive does not take any operands and hence the operand field should be blank. 5.4.7 DEFINS Directive This directive defines an instruction or directive and indicates how the instruction is to be assembled. The general form of the directive is as follows: DEFINS = , , where is the name of the instruction or directive to be defined, is an integer expression indicating the cross reference mode and attributes of the instruction, is an integer expression indicating the type of instruction, i.e. what operands are expected, and how these are to be assembled, and is the base value of the instruction opcode. Page 31 Further details of how to define additional instructions are given in Appendix B. 5.4.8 Parity Directives By default, KS500ASS assembles all character constants and strings with zero parity (bit 6=0). This may be changed using one of the parity directives as follows: ZERO_PARITY Selects zero parity (default) ONE_PARITY Parity bit always set EVEN_PARITY Even parity generated ODD_PARITY Odd parity generated Page 32 5.5 Conditional Assembly Directives ------------------------------- 5.5.1 Introduction Conditional assembly directives are used to control whether sections of a source program are to be assembled depending on a specified condition. This allows variations of a program module to be produced from a single source program by specifying the required assembly conditions. It also allows test versions of a program to be produced without the need to re-edit the source program. The following directives are provided: IF ELSE ENDIF IFB IFNB IFIDN , IFNIDN , IFDEF IFNDEF Conditional assembly blocks consist of a section of program enclosed by a starting IFXXX directive, and a terminating ENDIF directive, with optional ELSE directives within the block. These blocks may contain other conditional assembly blocks nested up to 20 deep. Example: IF TRUE : : IF TRUE : ! Program assembled ELSE : ! Not assembled ENDIF : : ELSE __ : ! : ! IF TRUE ! : ! ELSE !> Not assembled : ! ENDIF ! : ! : ! ENDIF -- Page 33 5.5.2 IF Directive The IF directive starts a conditional assembly block which will be assembled depending on the value of the expression specified in the operand field. Assembly is enabled if the value is non zero, and disabled if expression value is zero. Usually the expression contains relational operators to yield a TRUE or FALSE value. Example: IF OPTION=1 : ! Code assembed if the symbol : ! OPTION has a value of 1. 5.5.3 ELSE Directive The ELSE directive specifies an alternative for any previously specified IF directive. The directive does not take any operands. A nesting error will be reported if no previous IF exists. Example: IF OPTION=1 : ! Assembled if OPTION=1 : ELSE : ! Assembled if OPTION<>1 : ELSE : ! Assembled if OPTION=1 : 5.5.4 ENDIF Directive The ENDIF directive terminates any conditional assembly block started by an IF directive. A nesting error will be reported if no previous IF exists. The directive does not take any operands and the operand field should be blank. Example: IF : : ELSE : : ENDIF ! Ends previous IF directive 5.5.5 IFB and IFNB Directives The IFB (IF blank) and IFNB (IF not blank) directives begin a conditional assembly block which is assembled depending on whether the string in the operand field is blank. The operand should contain a string as shown below: IFB "" or IFNB "" Page 34 where may consist of zero or more characters excluding carriage return, and where a double quote within the string is represented by two double quotes. The enclosing double quotes may be dropped if the argument is non blank and does not contain any commas, spaces, tabs or exclamation marks. Examples: IFB "ARG1" : ! Assembled if the string ARG1 : ! is blank. ENDIF IFNB "ARG1" : ! Assembled if the string ARG1 : ! is non blank. ENDIF Note that these directives are only of use within macros, since their operands are essentially constants. 5.5.6 IFIDN and IFNIDN Directives The IFIDN (IF identical) and IFNIDN (IF not identical) directives start a conditional assembly block which is assembed depending on whether the two strings specified in the operand field are identical. The directives take the following form: IFIDN "", "" or IFNIDN "", "" where may consist of zero or more characters excluding carriage return, and where each double quote within the string is represented by two double quotes. The enclosing quotes may be dropped if both strings are non blank and do not contain any spaces, tabs, commas or exclamation marks. Note that these directives are only of use within macros since their operands are essentially constants. Page 35 5.6 Macros ------ 5.6.1 Introduction Macros are a technique of generating one or more source lines for assembly from a single line. This may be used to reduce the chore of writing repetitive sections of program, to make the program easier to understand, or to provide additional user defined pseudo-instructions. A macro has three important parts: (i) A Macro Name (ii) Optional Formal Parameters (iii) A Macro Body The macro name is used as a unique reference to the macro whenever one wishes to invoke the macro. Like procedures, a macro may optionally have formal parameters which are replaced by actual parameters when the macro is invoked. The macro body contains a block of text which will be substituted when the macro is expanded. Macros work by the process of text substitution. When the cross finds a name in the instruction field which is not a standard instruction or directive, it attempts to find a macro with the specified name. If a macro has been defined with the specified name, the line containing the macro is conceptually substituted for the line or line(s) contained in the macro body. These lines are then assembled in the normal way. 5.6.2 MACRO and ENDM Directives The MACRO directive is used to define a macro with a specified name and formal parameters. The ENDM macro is used to end the definition of the macro body. This is best explained by means of the example below: TABLE MACRO ARG1, ARG2, ARG3 DC ARG1, ARG2, ARG3 ENDM The first line contains a MACRO directive. This tells the cross assembler that a macro is being defined. The label field contains the name to be given to the macro, i.e. TABLE. The operand field contains three formal parameters ARG1 ARG2 and ARG3. The body of the macro, i.e. the macro definition, starts on the following line and contains a DC directive. The third line contains the ENDM directive which tells the cross assembler that the end of the macro body has been reached and that the macro definition is complete. The macro may now be used by writing the name TABLE in the instruction field together with zero or more actual parameters. For example: TABLE 5, 6, 1 Page 36 The cross assembler sees the name TABLE in the instruction field and since it is not a valid instruction or directive name, looks to see if a macro has been defined with the name TABLE. Since it has, it expands the body of the macro, replacing the formal parameters in the definition with the actual parameters specified in the operand field. The macro thus expands to the line: DC 5, 6, 1 The macro works by the process of text substitution. When macros are expanded, the cross assembler does not worry about the validity of the lines generated and knows nothing about the various fields such as the comment field within such lines. For example, one could use the macro TABLE as follows: TABLE #, * which would generate the following line: DC #, *, The line would then be assembled in the normal way, and errors reported. Since the expansion of macros is performed purely on the basis of replacing one section of text with another, one must be careful in the naming of formal parameters. For example, consider the macro below: TRICK MACRO A, B, C DC A, B, C ! Store A, B and C ENDM One might be led into believing that the macro TRICK has three formal parameters A, B and C and that the expansion of the macro using the line TRICK 1,2,3 would be as follows: DC 1, 2, 3 ! Store A, B and C However, the formal parameter "A" appears twice in the macro body, the formal parameter "B" also twice, and the formal parameter "C" three times. Hence the macro would be actually expanded as follows: D3 1, 2, 3 ! Store 1, 2 and 3 This would be flagged as an error, since D3 is not a valid instruction, nor is it a macro. Users of macros should therefore select formal parameter names sufficiently complex and unique such that they do not appear in undesirable places within the macro body. Formal parameters may use any character excluding space, tab, comma or exclamation mark. It is thus convenient to prefix formal parameter names with an unusual character such as # or %. The previous example could be re-written to work properly as follows: TRICK MACRO %A, %B, %C DC %A, %B, %C ! Store %A, %B and %C ENDM Page 37 A macro may use up to ten formal and/or actual parameters. Any further parameters are ignored and a nesting error will be reported. If when a macro is expanded, an actual parameter is omitted, this will not result in an error. The formal parameter will merely be replaced by a null string. 5.6.3 Commas and Special Characters in Macro Arguments It is sometimes useful for the actual parameters to a macro to include commas and other delimiters. This might be used, for example, to pass a string as an argument to a macro. This can be acheived by enclosing the actual parameter within double quotes. Example: TABLE "H'String with a comma,", 2, 3 Any double quotes within such a parameter must be represented by two double quotes. For example: TABLE "H'String with "" double quotes", 2, 3 The first parameter consists of the string H'String with " double quotes. 5.6.4 Nesting of Macros Macros may be nested in two ways: (i) Nesting of macro definitions (ii) Nesting of macro expansions Nesting of macro definitions occurs when a macro definition contains as part of the macro body, other macro definitions. The cross assembler permits macro definitions to be nested within other definitions to a level of 20 deep. Example: NAME MACRO #ARG1, #ARG2 LEVEL2 MACRO #ARG1 DC #ARG2 ENDM ENDM The first line defines a macro called NAME with two formal parameters. The body of this macro definition contains a further macro definition for the macro LEVEL2 which will not be defined until the macro NAME is actually expanded. Nesting of macro expansions occurs when the body of a macro definition contains other macros to be expanded. This continues until all macros have been expanded. Macros may contain references to other macros nested to a depth of ten levels. A macro may even call itself. Since this leads to a potentially infinite expansion, the user should ensure that this terminates before being nested more than ten levels. Page 38 5.6.5 Redefinition of Macros The cross assembler allows macros to be redefined. This is acheived by using the MACRO and ENDM directives in the normal way. A macro may even redefine itself. The new macro will only take effect when the macro is invoked again. Page 39 5.7 Listing Control Directives -------------------------- 5.7.1 Introduction This group of directives provides facilities for controlling the format and nature of the assembly listing file. The following directives are provided: FORMLN Specifies the listing form length. PAGE Forces next line onto a new page. SUBTTL Defines a sub title to appear at the top of each page. NLIST Disables listing LIST Re-enables listing NCLIST Disables listing of false conditional assembly blocks CLIST Re-enables listing of false conditional assembly blocks NMLIST Disables listing of macro expansions MLIST Re-enabled listing of macro expansions 5.7.2 FORMLN Directive The FORMLN directive specifies the assembly listing form length to be used until subsequently redefined. By default, the cross uses a form length of 55 lines. The directive itself does not appear in the assembly listing unless an error occurred or the /SHOW_ALL assembler option was specified. The directive may be used to change the form length as follows: FORMLN where represents the new form length. This must be in the range 10 to 1000 inclusive. The form length may be changed back to the default by using a blank operand field as follows: FORMLN 5.7.3 PAGE Directive This forces the next assembler listing line onto a new page. The directive does not take any operands and will not appear in the assembly listing unless an error is detected or the /SHOW_ALL option was specified. 5.7.4 SUBTTL Directive The SUBTTL directive defines a sub-title which will be printed at the top of each assembly listing until changed by a further SUBTTL directive. The new sub-title is used before the listing of the next line. The SUBTTL directive itself does not appear in the assembly listing unless an error is detected or the /SHOW_ALL assembler option was specified. At the start of assembly, the sub title is blank. If the first program source line is a SUBTTL directive, then the new sub-title comes into effect on the first listing page. The sub-title may be re-defined as often as required to make the assembly listing easier to follow. Page 40 The directive takes the form: SUBTTL ! Defines a blank sub-title SUBTTL ! Defines a sub-title of where is an ascii string of the form 'CCCC...' where CCCC represents zero or more characters such that a single quote is represented by two single quotes. Example: SUBTTL 'It''s a sub-title' defines a sub-title of "It's a sub-title". 5.7.5 NLIST and LIST Directives The NLIST and LIST directives may be used to suppress the unwanted listing of source lines. The directives do not take any operands and do not appear in the assembly listing unless an error is detected or the /SHOW_ALL option is used. 5.7.6 NCLIST and CLIST Directives The NCLIST and CLIST directives may be used to suppress the cross assembler from listing any conditional assembly blocks which were disabled, i.e. not assembled. The NCLIST directive disables the listing of such blocks. The CLIST directive enables the listing of all conditional assembly blocks; this is the default condition. The directives do not take any operands and do not appear in the assembly listing unless an error occurred or the /SHOW_ALL assembler option was specified. 5.7.7 NMLIST and MLIST Directives The NMLIST directive instructs the cross assembler not to list the expansion of macros in the assembly listing. This may be turned on again by the use of the MLIST directive. By default, all macro expansions are listed. The directives do not take any operands and do not appear in the listing unless an error occurred or the /SHOW_ALL option was specified. 5.7.8 NBLIST and BLIST Directives The BLIST directive instructs the cross assembler to only list those lines which would appear in the listing with an octal address or data. This includes lines containing instructions and EQUs, and excludes lines containing comments, symbol manipulation directives, conditional assembly directives etc. This may be turned on again by using the NBLIST directive. By default, all lines are listed. The directives do not take any operands and do not appear in the listing unless an error occurred or the /SHOW_ALL option was specified. Page 41 5.8 Program Section Directives -------------------------- 5.8.1 Introduction This group of directives allows the programmer to define program sections containing different items of code or data. This enables the user to define at link load time where each program section is to be located and to separate code and data. Typically this may take the form of grouping certain code sections for specific PROMS and data sections for RAM areas. If no section directive appears within an assembler program, the program is assumed to be a relocatable section and is given a default section name. If the default section is empty, i.e. does not contain any code, it is given a name of ".REL.". Otherwise, it is given a default name using up to the first six characters of the first source filename. 5.8.2 RSECT Directive The RSECT ( Relocatable Section ) directive defines a new section with a specified name. The section is relocatable and may be physically located anywhere in memory at link-load time. The directive takes the form: RSECT
where
is of the same form as a valid user symbol name. If the named section already exists, the assembler generates code at addresses following from the last address used by that section. The section defined previously with the same name must be of the same type, i.e. relocatable, otherwise a relocation error will be reported. Example: RSECT PROM1 ! Start a new section called PROM1 JMP HERE HERE: JMP THERE ! RSECT PROM2 ! Start a new section called PROM2 JMP * ! RSECT PROM1 ! Go back to the section PROM1 DC 1 ! This will be placed after HERE: 5.8.3 ASECT Directive The ASECT directive is similar to the RSECT directive except that it defines an absolute section. Such a section is permanently located at the specified address and cannot be relocated at link load time. This is useful for ensuring that a code or data section is located at a specific address if it uses fixed hardware addresses. The directive takes the form shown below: Page 42 ASECT
or ASECT
, where
is a valid symbol name to be assigned to the program section, and must evaluate to an absolute address specifying the start address or next address for the section. If the address item is omitted as shown in the first example, an address of zero is assumed for a new section, or if the section already exists, the address continues from the last address of the section. Example: ASECT PROM1 ! New Section PROM 1 starts at 0 DC 0 ! ASECT PROM2, @100000 ! New section PROM 2 starts at @100000 DC 1 ! ASECT PROM1 ! Back to section PROM 1 DC 2 ! This is at address 1 Page 43 6 SEPARATION OF CODE AND DATA =========================== The cross assembler provides facilities to simplify the writing of programs which require code and data to be separated. This arises, for example, when a program is to be embedded into one or more PROMS. The program thus needs to be split into one or more code sections containing program code and read only data, and one or more data sections situated in RAM. This chapter describes how such separation may be acheived. Program sections may be defined using the RSECT or ASECT directives. This allows sections of code or data to be grouped together for location in PROM or RAM. Relocatable sections may be independantly located at link-load time to any required position within the Kongsberg address space. However, Kongsberg assembler programs tend to use base relative addressing to access local variables since this is highly efficient. The cross assembler allows the programmer to allocate space for such base addressed local variables automatically, thus reducing the chance of an error and making the program easier to verify. This is accomplished by the use of the BASE directive. The example below shows how this can be used. BASE BASE_REGISTER ! Indicate where local data is. RSECT CODE ! Program section to go into PROM ! START: LDX BASE_REGISTER COPY X,B ! Initialise base register for ! access to local variables. . . . LDA VARIABLE ! Read local "VARIABLE" . . . LOOP: LDA ARRAY,X ! Read element X of local ARRAY MIN COUNT ! Increment local var COUNT JMP LOOP . . . RSECT LOCAL_DATA ! Start of data section NTRY ARRAY ! Make the array global as well ! BASE_REGISTER EQU *+128 ! Implicit base address VARIABLE: DS 1 ! Space for local VARIABLE ARRAY: DS 10 ! 10 element array space COUNT DS 1 . . . END Page 44 The assembler recognises whether each memory reference instruction is referring to the current program section or to a local data section and calculates the address displacement accordingly. The BASE directive informs the assembler that all memory reference instructions written without a ,B should be checked. The operand to the BASE directive indicates where the base register is assumed to be pointing at run time. It is up to the programmer to ensure that the base register is initialised either explicitly by assignment as shown in the example, or implicitly by presetting in the process's level head. The instruction "LDA VARIABLE" is effectively assembled as "LDA VARIABLE-BASE_REGISTER,B". Global data may be accessed using indirect addressing. For example, the variable ARRAY in the previous example was made an entry point. This allows other modules to access the data as follows: RSECT MORE_CODE XTRN ARRAY .ARRAY: DC ARRAY . . . SAX 1 LDA .ARRAY,I ! Read element 1 of ARRAY . . . END Page 45 7 ASSEMBLER OPERATION =================== The cross assembler is run under VMS by entering a command of the form: KS500ASS ... [/ ... /] where to are the file specifications of the source files to be assembled. The following assembler options are provided, where (D) means that the options is selected by default unless overridden: /NO_LIST (D) Don't produce an assembly listing. /LIST Produce an assembly listing to the default listing file. /LIST= Produce an assembly listing to the specified listing file. /NO_OBJECT Don't produce any relocatable binary object code. /OBJECT (D) Produce object code to the default object file. /OBJECT= Produce relocatable object code to the specified file. /NO_ERRORS Don't report assembly errors. Errors will still be flagged in the listing file. /ERRORS (D) Report assembly errors to the file SYS$OUTPUT, usually the terminal. /ERRORS= Report assembly errors to the specified file. /NO_SYMBOL_TABLE Don't produce a symbol table in the assembly listing file /SYMBOL_TABLE (D) Produce a symbol table at the end of the assembly listing. The /LIST option must be active for this to be operative. /NO_HIDDEN (D) Don't show hidden symbols in the symbol table and/or cross reference listing. /HIDDEN Enable the showing of hidden symbols in the symbol table and/or cross reference listing. /NO_CROSS_REFERENCE (D) Don't produce a cross reference listing. /CROSS_REFERENCE Produce a cross reference listing at the end of the listing file. The /LIST option must also be active for this to be operative. Page 46 /NO_LOCALS (D) Don't include local symbol definitions in the object code file. /LOCALS Include local symbol definitions in the object code file. This allows the link loader to print details about the local symbols in the load map. /DEFINE = Define the symbol whose name is specified by with the value of the . This may be used to control the assembly of the program to produce different versions without the need to re-edit the assembler source. /WIDE (D) Produce an assembly listing in wide 132 column format. /NARROW Produce an assembly listing in narrow 80 column format. This allows a listing to be printed on a terminal or on narrow listing paper. This option should not be used for normal listing purposes since some information is omitted from the listing, and some characters may be lost due to truncation in each of the label, instruction, operand or comment fields. /NO_SHOW_ALL (D) Don't show all source lines and macro expansions in the assembly listing. /SHOW_ALL This instructs the cross assembler to show all source lines and macro expansions in the assembly listing, over-riding the effect of any NLIST, NCLIST or NMLIST directives. /NO_MULT_XTRNS (D) Specifies that multiple XTRNS are not permitted, i.e. will be reported as multiple symbol definitions. /MULT_XTRNS Specifies that multiple XTRNS are allowed and will not be treated as multiple symbol definitions. The cross assembler options may be abbreviated provided that the short form unambiguously indicates which option is required. For example, the option NO_LIST may be abbreviated to NO_LI but any further since it becomes ambiguous with NO_LOCALS. The cross assembler uses defaults wherever possible to simplify the commands which have to be entered. The default options are show above. Similarly, defaults are also applied to the files read and produced by the cross assembler. Page 47 SOURCE OBJECT LIST ERROR DEVICE : Current Current Current Current DIRECTORY : Current Current Current Current FILENAME : SYS$OUTPUT TYPE : .KS5 .ROB .LIS .ERR VERSION : Highest Next Highest Next Highest Next Highest where means the current device and directory default. Page 48 8 ASSEMBLY LISTING AND ERRORS =========================== 8.1 Introduction ------------ The assembly listing file may contain up to four distinct groups of information: (1) Source Listing with code expansion (2) Program Section details and error count (3) Symbol Table (4) Cross Reference Listing 8.2 Source Listing -------------- The source listing shows the code generated for each assembly language source statement and also reports any errors found during assembly. The general format of each line is as follows: EEE LLLLLL AAAAAA DDDDDD M Source statement Where EEE are zero or more error letters indicating an assembly error as described in section 8.6, and LLLLL is a listing line number used for cross referencing purposes, and AAAAA is the address in octal of the code generated, and DDDDD is the code data generated in octal, and M is a letter indicating the relocation mode of the data, where A is absolute, R is relocatable and E is external. 8.3 Program Section Details ----------------------- The cross assembler lists the program sections defined in the following format: Section Type Start Address Last Address Size SSSSSS MMMMMMM @AAAAAA AAAAAA @AAAAAA AAAAA @AAAAAA AAAAAA Where SSSSSS is the section name, MMMMMM is the section mode, Absolute or Relocatable, and AAAAAA are the start address, last address and size of the program section. Page 49 8.4 Symbol Table ------------ The symbol table lists the symbols defined in the program in the following groups: (1) Externals (2) Entries (3) Literal Blocks (4) Local Symbols The symbols in each group are listed in alphabetic order, apart from the literal blocks, which appear in order of appearing in the program. The literal block symbols indicate where each block of literals are placed in memory by the FILL directives. The local symbols also include the symbols in the entries group. 8.5 Cross Reference Listing ----------------------- The cross reference listing shows all the symbols referenced in the the program together with the line numbers and modes in which they were referenced. Each line is output in the form shown below: SSSSSS TTTTTT LLLLLL XX LLLLLL XX LLLLLL XX LLLLLL XX LLLLLL XX LLLLLL XX LLLLLL XX LLLLLL XX LLLLLL XX etc where SSSSSS is the symbol name, TTTTTT is the symbol type, LLLLLL are the line numbers on which the symbol was referenced, and XX are the modes in which the symbol was referenced. The cross reference modes are as follows: D Defined W Written WR Written and Read R Read J Jump C Procedure Call Symbolic Reference K Killed Page 50 8.6 Assembly Errors --------------- Assembly errors are reported in the listing and/or error file by the use of letter error flags: Letter Error Cause(s) A Addressing Error (1) Operand out of addressing range (2) Illegal use of address modifiers (3) Illegal address modifier B Balance Error (1) Mismatching parentheses (2) Mismatching quote in string E Expression Error (1) Illegal character in expression (2) Missing Operand (3) Illegal Operand (4) Illegal Operator F File Error Illegal file specification, or file could not be opened. I Instruction Error Illegal or Unknown instruction or macro in the instruction field. K Kill error Attempt to KILL an NTRY symbol. L Label Error (1) Invalid label symbol (2) Missing symbol in label field M Multiple Definition (1) Symbol already defined (2) Two symbols not unique in first six characters (3) Module name already specified N Nesting Error (1) INCLUDEs nested too deeply (2) Too many items in DC, XTRN etc (3) Too many literals or FILL missing (4) Missing IF for ELSE or ENDIF (5) Missing ENDIF for IF (6) Missing MACRO for ENDM (7) Missing ENDM for MACRO (8) IFs nested too deeply (9) Macro definitions nested too deeply (10) Macro expansions nested too deeply (11) Too many formal macro parameters (12) Too many actual macro parameters O Operand Error (1) Missing operand (2) Too many operands (3) Illegal Operand (4) Illegal character in operand field P Phasing Error (1) DS directive used symbol which was undefined in pass 1. (2) File is different in pass 2 compared to pass 1. Page 51 Q Questionable Syntax (1) Too many delimiters (2) Missing delimiter (3) Illegal character R Relocation Error (1) Expression involving invalid use of relocatable and/or external terms (2) EQU expression contains external symbol. (3) Attempt to address an item not in the current program section or local base area. S Symbol Error Reference to a symbol which is multiply defined. U Undefined Symbol Reference to a symbol which is currently undefined. V Value Error The operand field contains a number which is too large or small. * Too Many Too many errors occurred on the source line to report them all. In addition, the cross assembler may output a number of error messages as the result of an illegal assembler option, or as the result of a fatal error. These take the form: %KS500ASS - Error description and may be optionally followed by a standard VAX error message further describing the cause of the error. For example, specifying a source file which does not exist will result in the following messages: %KS500ASS - Error opening source file %RMS-E-FNF, File not found Appendix D lists all of the assembler error messages and their causes. Page 52 APPENDIX A PERMANENT SYMBOLS ========== ================= The cross assembler uses a permanent symbol file to define the instruction and directive names and any pre-defined user symbols. The standard cross assembler provides the following permanent symbols: Instructions and Directives --------------------------- AAA AAB AAL AAX ADD AND ASECT ASHLA ASHLAD ASHLD ASHRA ASHRAD ASHRD BAND BAND,N BASE BCOM BONE BOR BOR,N BSEQW BSEW BSNEW BSNW BSON BSONE BSZR BSZRO BZERO BZRO CHAN CLIST CLR COPY COPY,N CPM CPYC CPYI CPYI,N CPYY CPYY,N DC DEC DEFINS DNZ DS ELSE END ENDIF ENDM EQU EVEN_PARITY EXEC EXF EXIT FAD FADD FDIV FDV FILL FMU FMUL FORMLN FSB FSUB GET HIDE IF IFB IFDEF IFIDN IFNB IFNDEF IFNIDN INC INXJXN INXJXP IOA IOAP IODI IOIS IOPI IOS IOT IOTP ISZ JAF JAN JAP JAZ JMP JNC JNZ JPC JPL JSUBR JUMP JXN JXZ KILL LDA LDD LDF LDL LDW LDW,N LDX LIBR LIST LSHRA LSHRAD LSHRD MACL MACRO MAIN MAST MIN MLIST MOC MSW MSWAP NCLIST NMLIST NLIST NLZ NTRY NOBASE ODD_PARITY ONECOM ONE_PARITY OR PAGE PUT RADD RADD,N RADI RADI,N RADY RADY,N RAND RAND,N RDIV READ RMPY RMPY,N RNAND RNOR ROR ROTLA ROTLAD ROTLD ROTRA ROTRAD ROTRD RSECT RSUB SAA SAB SAL SAX SKEQ SKGE SKGT SKLE SKLT SKUE SLA SLD Page 53 SLL SLRA SLRD SLRL SRA SRAZ SRD SRDZ SRL SRLZ SRRA SRRD SRRL STA STD STF STL STW STW,N STX SUB SUBTTL SWAP TEST TITLE TWOCOM USAV WAIT XTRN ZERO_PARITY ZRLR ZRO ZWL User Symbols ------------ LPR REA PNT RKE PUN RTC Page 54 APPENDIX B CUSTOMISING THE PERMANENT SYMBOL FILE ========== ===================================== The permanent symbol file contains definitions of the Kongsberg instructions, directives and device names. These may be enhanced by including additional definitions in the file. This appendix describes how this may be acheived. The cross assembler reads the file KS500ASS_PERMANENT_SYMBOLS (a logical name) before commencing assembly of any user programs. The file is normally held in the same directory as the cross assembler executable image KS500ASS.EXE. However, specific users may require different enhancements or pre-defined symbols. This may be acheived by assigning the logical name KS500ASS_PERMANENT_SYMBOLS to a file in their own directory where their customised symbol file is kept. The standard symbol file should not be customised with project or user specific data since this affects all normal users of the cross assembler. Example: A user on device DRA1: with directory [USER] may maintain a separate symbol file MYSYMBOLS.SYM. The command ASSIGN DRA1:[USER]MYSYMBOLS.SYM KS500ASS_PERMANENT_SYMBOLS over-rides the normal translation of the logical name and hence the cross assembler is re-directed to read the user's symbol file. The file itself, is a normal KS500 assembly language program. The only difference between the symbol file and a user source file is that the symbol file is only read once, rather than twice for user source files. Hence no code can be generated from the symbol file. The symbol file may contain user symbol definitions, instruction and directive definitions, and macro definitions. Pre-defined user symbols such as the Kongsberg device names are defined in the standard way using the EQU directive. (See section 5.3.2) Instructions and directives are defined using the DEFINS directive described in section 5.4.7. The cross assembler comes provided with a file KS500ASS.SYB which contains a permanent symbol file which is easier to understand and modify since it attempts to be self documenting. Either file may be used with the cross assembler, although KS500ASS.SYM is more efficient. KS500ASS.SYB contains a number of user symbols which are defined for use with the DEFINS directive. These symbols are normally "hidden" and killed so that they do not clash with any symbols in the user's source program and do not normally appear in the symbol table or cross reference listing. The normal file KS500ASS.SYM is a compacted form of KS500ASS.SYB with the symbols replaced by their actual values. A new file may be generated from the ".SYB" file using the text editor to replace each symbol with it's value. The symbols form two categories: (1) Cross reference and flag values (2) Instruction handler values The cross reference and flag values are used to specify whether the instruction reads, writes, reads and writes, etc memory, and whether the label field must hold a user symbol to be defined. The following symbols are used: Page 55 XR_DEFINE Symbol definition XR_WRITE Write to memory XR_W_READ Writes and reads memory XR_READ Reads from memory XR_JUMP Jump instruction XR_CALL Procedure call instruction XR_SYMBOLIC Symbolic reference XR_KILL Symbol killed FL_SYM_DEF Label field must contain symbol to be defined FL_COND_DIR Instruction is a conditional assembly directive FL_MACRO_DIR Instructon is a macro directive The instruction handler values tell the assembler what type of operand(s) the instruction should have, and how these should be used with the base opcode value to form the instruction. The following symbols are used: Symbol Type of Instruction Operand(s) IH_ILLEGAL Unknown or Illegal None IH_DEFINS DEFINS directive ** See section 5.4.7 IH_EQU EQU directive ** IH_DC DC directive See section 5.2.1 IH_DS DS directive IH_KILL KILL directive None or [, ...] IH_HIDE HIDE directive None or [, ...] IH_NTRY NTRY directive [, ...] IH_XTRN XTRN directive [, ...] IH_FILL FILL directive None IH_BASE BASE directive IH_NO_BASE NO_BASE directive None IH_TITLE TITLE directive IH_SUBTTL SUBTTL directive IH_PAGE PAGE directive None IH_FORMLN FORMLN directive IH_RSECT RSECT directive IH_ASECT ASECT directive [, ] IH_INCLUDE INCLUDE directive IH_END END directive None IH_IF IF directive IH_ELSE ELSE directive None IH_ENDIF ENDIF directive None IH_IFB IFB and IFNB directives IH_IFDEF IFDEF and IFNDEF directives IH_IFIDN IFIDN and IFNIDN directives , IH_LIST LIST and NLIST directives None IH_MLIST MLIST and NMLIST directives None IH_CLIST CLIST and NCLIST directives None IH_BLIST BLIST and NBLIST directives None IH_PARITY Parity directives None Page 56 IH_MEM_REF Memory reference instruction [] or [] IH_COND_JUMP Conditional jump instruction IH_BIT_REG Bit operation instruction or , IH_TWO_REG Register operation instruction , IH_NO_OPER Register op and Miscellaneous None IH_SIG_8_BIT Argument etc, -128 to +127 IH_UNS_8_BIT I/O etc, 0 to 255 IH_UNS_7_BIT EXF, 0 to 127 IH_UNS_4_BIT ZRLR, 0 to 15 IH_MOC MOC, monitor call, 0 to 15 IH_SHIFT Shift Instructions [, X] IH_DEST_REG Register operation instruction IH_GET_PUT GET and PUT instructions IH_EXECUTE EXECute instruction IH_SKIP Normal skip instructions + or - IH_EXT_SKIP Extended skip instructions - IH_EXT_REG Extended register operation IH_READ_INT READ interrupt instruction See section 4.10 IH_MASK_INT MACL, MAST interrupt instr See section 4.10 ** Note: The DEFINS and EQU directives are permanently defined within the cross assembler itself so that the directives may be used to define the remaining instructions. Examples: DEFINS STX= XR_WRITE, IH_MEM_REF, @014000 This defines the STX (Store X) instruction as being a write to memory, memory reference instruction with a base opcode value of octal 014000. DEFINS RMPY,N= XR_SYMBOLIC, IH_TWO_REG, @147600 This defines the RMPY,N (Register divide) instruction as being symbolic symbol reference (no memory read/write), with two registers for the operand and a base opcode value of octal 147600. Page 57 APPENDIX C SYNTAX OF ARITHMETIC EXPRESSIONS AND CONSTANTS ========== ============================================== ::= | | A() | | A() ::= F ::= | ::= | . | . | . ::= + | - | ::= ::= E ::= H'' ::= Sequence of any characters excluding carriage return, and where each ' is represented by two single quotes. ::= [ ] ::= 'OR' | 'XOR' ::= [ 'AND' ] ::= [ ] ::= = | <> | > | >= | < | <= ::= [ ] ::= + | - ::= [ ] ::= * | / | 'MOD' | 'SHL' | 'SHR' ::= | ::= + | - | 'NOT' | 'HIGH' | 'LOW' Page 58 ::= | * | | | | | | () ::= | . | ::= | | . ::= A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ::= | ::= @ | @+ | @- ::= | ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 ::= $ ::= | ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | A | B | C | D | E | F ::= % ::= | ::= 0 | 1 ::= '' | '' ::= Any character excluding carriage return and where each single quote is represented by two single quotes. Page 59 APPENDIX D ASSEMBLER ERROR MESSAGES ========== ======================== This appendix lists all the error messages which the cross assembler may issue and which result in termination of assembly. These do not include the assembly errors reported as a result of errors in the the source file(s). Errors Reported in Command Decoding ----------------------------------- Source file specification A source file specification is too long too long to be valid. (Longer than 132 chars) Missing source file No source file(s) were given on the specification command line. Missing option after / No assembler option was given after a / option delimiter. Option keyword too long An assembler option was too long to be valid. (Longer than 132 chars) Unknown option keyword An unknown or invalid assembler option was specified. Keyword is ambiguous, too An assembler option was abbreviated few characters given too much and does not select a unique assembler option. Specify more characters, or type in full. Illegal character after An illegal delimiter character was option, / expected specified after an assembler option. Option keywords should be followed by zero or more spaces and a / character. First source filespec invalid, The first source file specification cannot form default module did not have any main filename. The name default module name is taken from up to the first six characters of the first filename. File specification after The list filespec was too long to be /LIST is too long valid. (Greater than 132 chars) Missing file specification No file specification was given after after /LIST= the option /LIST=. If the default file is required, omit the = sign. File specification after The object filespec was too long to be /OBJECT is too long valid. (Greater than 132 chars) Missing file specification No file specification was given after after /OBJECT the option /OBJECT=. If the default file is required, omit the = sign. File specification after The error filespec was too long to be /ERRORS= is too long valid. (Greater than 132 chars) Page 60 Missing file specification No file specification was given after after /ERRORS= the option /ERRORS=. If errors are required on the terminal, omit the = sign. Missing symbol name after No user symbol was given after the /DEFINE option /DEFINE option. Symbol name after /DEFINE Too many characters were given in the option is too long user symbol. Symbol after /DEFINE option User symbols cannot start with a digit, cannot start with a digit and should begin with A to Z or '.'. Missing = after /DEFINE SYMBOL The equals sign after the user symbol option was omitted. Missing value after /DEFINE No value or arithmetic expression was SYMBOL= option given for the user symbol. Error in expression after The arithmetic expression for the /DEFINE SYMBOL= symbol value was invalid. This may be due to: (1) Illegal character (2) Illegal operator (3) Illegal operand (4) Missing operand (5) Missing operator Undefined symbol in expression The arithmetic expression for the after SYMBOL= symbol value contained an undefined symbol. No symbols are defined when the command line is read. Enter the symbol value explicitly. Symbol is already defined The symbol specified in the /DEFINE option was already defined. This must be because the same symbol was given in another /DEFINE option earlier in the command line. Invalid mixture of relocatable The arithmetic expression for the terms in expression symbol value used the * operand incorrectly. See section 3.3.3. Value error in expression The symbol value expression contained after SYMBOL= a value which was too large or small. This can be caused by: (1) Division by zero (2) Constant too large (3) Constant too small Invalid expression after The symbol value expression was SYMBOL= invalid. This can be caused by: (1) Mismatching parentheses (2) Mismatching quotes (3) Illegal character Page 61 Fatal internal error, option A software error occurred in the number out of range. decoding of the command line. This indicates a bug in the cross assembler which should be reported as soon as possible. Errors Reported when using Source, Object, Listing and Error files ------------------------------------------------------------------ These error messages are normally followed by a standard VAX RMS error message indicating why the attempted operation was unsuccessful. Error in opening symbol file The cross assembler symbol file could KS500ASS_PERMANENT_SYMBOLS not be opened. This can be caused by: (1) File not present (2) Logical Name KS500ASS_PERMANENT _SYMBOLS not defined or illegal. (3) File priveledges do not allow you use of the file. Error in closing symbol file The cross assembler symbol file KS500ASS_PERMANENT_SYMBOLS could not be closed. This error is highly unusual and may represent a bug in the cross assembler. Error in opening assembly The assembly listing file could not listing file. be opened. This may be caused by: (1) File already exists (2) Disk quota exceeded (3) Insufficient priveledges Error in opening object The object code file could not be code file. opened. See above. Error in opening error The error listing file could not be listing file. opened. See above. Error in opening SYS$OUTPUT The file SYS$OUTPUT could not be opened. This may be caused by: (1) The logical name SYS$OUTPUT is invalid. (2) The logical name SYS$OUTPUT translates to a file which already exists. (3) Cross assembler bug. Error in closing listing file The assembly listing file could not be closed. This is highly unusual, see above. Error in closing object code The object code file could not be file closed. This is highly unusual, see above. Error in closing SYS$OUTPUT The logical name SYS$OUTPUT could not be closed. This is highly unusual, see above. Page 62 Illegal or missing source One of the source file specifications file specification is illegal or missing. Error in opening source file One of the source files could not be opened. This may be caused by: (1) File not present (2) Insufficient priveledges (3) Illegal filename or logical name. Error in reading source file An error occurred whilst reading one of the source files. This is unusual and may represent a possible cross assembler bug. Please report this as soon as possible. Error in closing source file One of the source files could not be closed. This is highly unusual, see above. Error in closing INCLUDE file An error occurred when an INLUDEd file was closed. This is highly unusual and represents a possible bug. Error in writing to file An error occurred whilst writing to one of the cross assembler files. This may be caused by: (1) Disk quota exceeded (2) Cross assembler bug Miscellaneous Errors -------------------- Error in reading system The cross assembler could not read date and time the VAX system date and time. This represents a possible bug in the cross assembler or VMS, and should be reported as soon as possible. Illegal Logical Unit Number This represents an internal cross assembler fault and should be reported as soon as possible. Logical Unit Number in use This is a cross assembler bug and should be reported as soon as possible. File not opened before writing This represents an internal error in the cross assembler and should be reported. File not opened before reading Cross assembler bug to be reported as soon as possible. Symbol table could not be The cross assembler could not create created a symbol table dynamically. This is highly unusual and should be reported as a suspected bug. Page 63 Fatal error, cannot extend The cross assembler could not extend symbol table the symbol table. This may be caused by: (1) Too many symbols and/or cross referencing. (2) Too many macros, or ENDM missing. (3) Insufficient virtual memory (3) User has exceeded memory quota Formal macro parameter number This is an internal cross assembler out of range fault which should be reported as soon as possible. Cannot find redefined macro This is an internal error in the cross in pass 2 assembler and should be reported as soon as possible. Cannot find macro definition Internal cross assembler fault to be in pass 2 reported as soon as possible. Page 64 APPENDIX E INCOMPATABILITIES WITH KS500 HOSTED ASSEMBLER ========== ============================================= This appendix lists the known incompatabilities with the KS500 hosted assembler which may necessitate minor changes to assembler programs when transferred from the KS500 to the VAX. Since the cross assembler provides some enhanced features as a compatable superset, this does not cover the case where assembler programs developed on the VAX are transferred to the KS500. (1) The KS500 hosted assembler used commands of the form )COMMAND to control the assembler. Since these consisted of highly specific and implementation dependent commands, they have not been implemented on the VAX KS500 cross assembler. (except for the KILL directive). (2) The )KILL command has been implemented as the KILL directive for consistency. (3) The BASE directive on the KS500 hosted assembler disables the use of implicit base addressing if the operand is negative. The cross assembler accepts any integer expression and the use of a previous BASE directive is cancelled using the NO_BASE directive. (4) The KS500 assembler uses the first line as the page title. This is implemented on the cross assembler as the TITLE and SUBTTL directives. (5) Arithmetic expressions on the KS500 hosted assembler were deemed to be relocatable if an odd number of relocatable terms were present. This is potentially incorrect, and has been changed to deal with all types of operators and operands. (See section 3.3.3) (6) The native KS500 assembler accepts an arithmetic expression of 0/0, yielding a value of 1. The cross assembler will flag this as a value error. (7) The Kongsberg hosted assembler allows arithmetic expressions to contain relocatable terms which are multiplied by numbers other than 1 or 0. The cross assembler will flag such use of relocatable terms as a relocation error. (8) The native assembler allows an '@' character to be placed in the operand field of instructions which do not take any operands. This may be used as a means of having a comment field for such instructions. The cross assembling will flag this as an operand error. Comments may be included using the explicit comment marker '!'. (9) The Kongsberg assembler supported three separate directives LIBR, MAIN and CHAN. These defined a library entry symbol, a process entry, and a channel entry. These have been implemented as a standard NTRY, i.e. they are synonomous with using NTRY. Library files are generated as a separate activity from assembly using the BSO librarian. Process and channel records are created by the utility KSABS. Page 65 (10) The KS500 hosted assembler allows user symbols defined as labels or using the EQU directive to be redefined without killing them. Since this is potentially dangerous, the cross assembler flags these as multiply defined symbols. It is recommended that temporary symbols, if required, are killed immediately after use to prevent inadvertent errors, and that permanent symbols are not reused, i.e. a symbol has only one value, address or meaning. Note that since symbols cannot be redefined without killing them, that attempts to define symbols such as RKE, PNT, i.e. standard KS500 device names, will be flagged as multiple definition errors. These errors can be avoided by KILLing all device names using a single KILL directive at the start of the program. (11) By default, the cross assembler generates strings without parity, i.e. zero parity. The native KS500 assembler generates even parity strings. This may be overcome using the EVEN_PARITY directive. (12) The KS500 hosted assembler allows the BASE directive to specify the address of a section of code or data. The cross assembler will object to this. The section of code or data being BASEd must either be defined with offsets EQUated to absolute values, or as labels in a different program section either absolute or relocatable.