CALMPSEU.DOC CALM pseudo-instructions PSEUDO-INSTRUCTIONS Pseudo-instructions are commands to the assembler. All pseudo-operations start with a period. Pseudo-instructions are composed of a pseudo-operation which may be followed by one or more expressions (which are separated by commas). There are two types of pseudo-instructions: - pseudo-instructions allowing a preceeding label: .ASCII, .ASCIZ, .ASCIZE, .BLK.n, .DATA.n, .FILL.n, .n (.8, .16, .32, etc.), .STRING, .SYSCALL.n . These pseudo-instructions generate code or reserve memory space. Byte ordering in 16 and 32 bits words depends on the microprocessor. - pseudo-instructions without a previous label: .ALIGN, .APC, .BASE, .CHAP, .ELSE, .END, .ENDIF, .ENDLIST, .ENDMACRO, .ENDTEXT, .ERROR, .EVEN, .EXPORT, .IF, .IMPORT, .INS, .LAYOUT, .LIST, .LISTIF, .LOC, .LOCALMACRO, .MACRO, .MESSAGE, .ODD, .PAGE, .PROC, .PROCSET, .PROCVAL, .RANGE, .REF, .START, .TEXT, .TITLE . These pseudo-instructions do not generate code and do not depend on the processor. A preceeding label is not allowed for the following reasons: a) ambiguity: for instance, a label before the pseudo-instruction .LOC does not determine clearly the value of the label. b) unclearness: for example, a label before the pseudo-instruction .IF does not appear in the listing, as the pseudo-instructions for the conditional assembly are not copied in the listing. c) impossibility: a label before the pseudo-instruction .MACRO has no meaning. d) Pseudo-instructions are primarily commands to the assembler and have nothing to do with labels, which are used in the program by the user. .ALIGN Descript.: Align the APC value to the next multiple of the given value. Comment: The title is repeated in the following pages. The contents of the bytes which are skipped are undefined. Example: .LOC 16'234 ; APC has the value 16'234 .ALIGN 16'200 ; APC has the value 16'400 .ALIGN 16'100 ; APC has the value 16'400 .APC Descript.: Select one of the assembler program counters (APC). Comment: Normally only one assembler program counter is used. The pseudo-instruction .APC enables the user to choose between different program counters (e.g. ROM and RAM areas). Up to eight APC-values are usual. All APC values are zero at the beginning of the program. Example: ROM = 0 RAM = 1 .APC ROM ; ROM: starts at 16'0 .LOC 16'0 .APC RAM ; RAM: starts at 16'2000 .LOC 16'2000 ... .APC ROM ; program JUMP BEGIN TESTRAM: MOVE.8 ALPHA,D0 .APC RAM ; data ALPHA: .8 0 ... CALM pseudo-instructions page: 2 .ASCII Descript.: Insert the ASCII codes of the given printable characters. The syntax diagram of the ASCII string is given in fig. 1. The printable characters "left angle bracket" and "double quotes" are expressed by repeating them twice. Any 8 bit value could be inserted in a string using angle brackets. Comment: The pseudo-instruction .ASCII is equivalent to .8 , but is more natural. Non-printable characters can be inserted with angle brackets. Example: .ASCII "Here is an example" The character string "A( " )--------->(printable character except " < )--------->( " )-> --- | | ------------------------------- ^ ^ --- | | | | | | --- ---------------------- --- | | | |->( < )--->[ simple expression ]->( > )-| | | | --- | ---------------------- --- | | | | | | | | | | --- | | | | `------------------------->( < )-| | | | --- | | | | --- --- | | | `------------->( " )--->( " )-------------' | | --- --- | | | `------------------------>-----------------------' Fig. 1 .ASCIZ .ASCIZE Descript.: Same effect as .ASCII. Add at the end the ASCII code . Comment: In many cases the zero acts as a terminator at the end of the string: .ASCIZ "ABC" or: .ASCII "ABC<0>" .ASCIZE "ABC" ; = .ASCIZ + .EVEN (generates 0) .BASE Descript.: Define the next default base. Comment: The assembler starts with the decimal base. Current bases are: binary, octal, decimal and hexadecimal. If no base prefix is used, the new base must be expressed in the old base. Example: .BASE 10'16 CALM pseudo-instructions page: 3 .BLK Descript.: Add the product of the data size times the number of items to the value of the APC. Comment: This instruction reserves memory locations without affecting their content. The possibility of mixing different data sizes makes the reservation of data structures more clear. Examples: .BLK.8 100 ; add to the APC-value 100 .BLK.16 100 ; add to the APC-value 200 .BLK.32 100 ; add to the APC-value 400 .BLK.8.16.32 12 ; add to APC 84 (1+2+4)*12 .CHAP Descript.: Add the specified text in the subtitle header of the subsequent pages. Comment: This instruction starts an important part of the assembler program or a subroutine. The text describes the functions carried out by the particular routine. The text appears in the subtitle header. Normally, a page is skipped, when a .CHAP is encountered. Example: .CHAP symbol handling .DATA Descript.: Insert the given values in binary, each value having the given size. Comment: Byte ordering in 16 and 32 bits depends on the micro- processor (as defined by .PROC). The size specified is added to the assembler program counter. Examples: .DATA.8 255, 0, 2'1111 ; range (.8): -256..+255 .DATA.16 16'FFFF .DATA.32 -1 ; = 16'FFFFFFFF .DATA.8.8.16 "A", "Z", AD_A_Z Equivalent pseudo-instructions: .8, .16, .32, ... .ELSE Descript.: Consider the next instructions up to a matching .ENDIF, only if the expression associated with the correspondant .IF was false. Optional printable characters after .ELSE are ignored. Comment: The text following the .ELSE is usually the repeated expression of the corresponding .IF in order to increase the legibility of a program, especially when the corresponding .IF and .ENDIF are far away and when there are many nested .IFs. Example: see .IF. .END Descript.: Terminate the program instructions. This allows the addition of free comments after this pseudo-instruction. Comment: The assembler ignores all the program instructions after this pseudo-instruction. The pseudo-instruction .END also terminates an inserted file called by the pseudo- instruction .INS. Example: .END CALM pseudo-instructions page: 4 .ENDIF Descript.: End an .IF/.ELSE section. Optional printable characters after .ENDIF are ignored. Comment: The text following the .ENDIF is usually the repeated expression of the corresponding .IF in order to increase the legibility of a program, especially when the corresponding .IF and .ENDIF is far away and when there are many nested .IFs. Example: see .IF. .ENDLIST Descript.: End of a conditional list segment. Comment: Printable characters after the pseudo-instruction .ENDLIST are ignored. In order to increase the legibility of a program, the text following the corresponding .LIST is usually repeated, especially when the corresponding .LIST is far away and when there are many nested .LISTs. Example: see .LIST. .ENDMACRO Descript.: End of a macro definition. Example: see .MACRO. .ENDTEXT Descript.: Return to assembler instructions. Example: see .TEXT. .ERROR Descript.: Generates an error message. Example: .ERROR Error: program too long .EVEN Descript.: Align the APC value to the next even value (do not change if already even). Comment: The content of the byte which is skipped is undefined. Example: .LOC 16'233 ; APC has the value 16'233 .EVEN ; APC has the value 16'234 .EVEN ; APC has the value 16'234 The pseudo-instruction .EVEN is equivalent to: .ALIGN 2 .EXPORT Descript.: Define the exported symbols. Comment: Normally only addresses can be exported. The generated binary file contains this information. The linker verifies that all symbols are defined. Example: .EXPORT MUL64, DIV64 .FILL Descript.: Fill the given length with the given value. Comment: The following example fills 2048 memory locations with the value 16'FF (e.g. for EPROM): .FILL.8 2048, 16'FF Other examples: .FILL.16 10, 16'A5A5 .FILL.32 16, AD_ROUT CALM pseudo-instructions page: 5 .IF Descript.: Consider the next instructions up to a matching .ELSE or .ENDIF only if the expression is true. The .IF may be nested. Comment: This pseudo-instruction allows the conditional assembly. Example: .IF M6801 ... ; is assembled when M6801 = TRUE .IF DEBUG ... ; is assembled when M6801 = TRUE ; and DEBUG = TRUE .ENDIF DEBUG ... .ELSE M6801 ... ; is assembled when M6801 = FALSE .ENDIF M6801 .IMPORT Descript.: Define the imported symbols. Comment: These symbols should have been exported (by .EXPORT) in another module. Imported symbols are addresses. Example: .IMPORT MUL64, DIV64 .INS Descript.: Insert the mentioned source file. The filename extension (if none) is the same as the source file. Comment: A complex problem may be divided into several smaller files which are then called by the main file. The file extension is added automatically and must be the same as the source file if no extension is present. Constants may be defined in this way. Example: .INS CONSTANTS .LAYOUT Descript.: Define the layout parameters for the listing. These parameters are given either in a file ("FILE filename") or by a list of reserved names (OCT, HEX, TAB n, LENGTH n, WIDTH n, etc.). Comment: This pseudo-instruction has been defined in a very general form and allows any possible extensions. To define the listing layout as flexible as possible, only one pseudo-instruction has been defined. Other assemblers have for this purpose many different pseudo- instructions, which are here integrated only once. The following names have been reserved up to now: HEX, OCT (data in hexadecimal or octal representation) LENGTH n (defines n lines per page; n=0: infinite) WIDTH n (defines n caracters per line) TAB n (a tabulator corresponds to n spaces) LEADING0 TRUE/FALSE ('0'/' ' before add./val. [.LST]) DEFFIRST, LSBFIRST, MSBFIRST (order [.16, .32, ...]) Example: .LAYOUT HEX, LENGTH 66 .LIST Descript.: List subsequent instructions only if the expression is true. The pseudo-instructions .LIST may be nested. Comment: This pseudo-instruction allows the conditional listing. Example: .LIST DEBUG ; this program section is listed when DEBUG = TRUE. .ENDLIST DEBUG CALM pseudo-instructions page: 6 .LISTIF Descript.: List all pseudo-instructions .IF/.ELSE/.ENDIF in the listing (.LST). Comment: If there is no expression or the expression is not zero, then this additional listing is done. Example: .LISTIF DEBUG_IF .LOC Descript.: Assign a new value to the current assembler program counter. By default, APC values are zero at the beginning of the program. Example: .LOC 16'2000 .LOCALMACRO Descript.: Declare the local symbols in a macro. Comment: This pseudo-instruction is only valid within a macro definition. The assembler replaces the corresponding symbols by local symbols (e.g.: M_10$) at macro call time. Example: see .MACRO. .MACRO Descript.: Beginning a macro definition with the name of the macro followed by a parameter list (optional). The macro name syntax is identical to the symbol name. Comment: The parameter list corresponds to the default values if the corresponding parameter is not present when calling the macro. Inside the macro, the parameters are denoted by the percent character followed by a digit. Example (68000): Macro definition: .MACRO DELAY, D0, 1 .LOCALMACRO LOOP MOVE.16 #%2-1,%1 LOOP: DJ.16,NMO %1,LOOP .ENDMACRO First call: DELAY D1,ONE_MSEC gives: MOVE.16 #ONE_MSEC-1,D1 M_0$: DJ.16,NMO D1,M_0$ Second call: DELAY ,TWO_MSEC ; without first parameter gives: MOVE.16 #TWO_MSEC-1,D0 M_1$: DJ.16,NMO D0,M_1$ .MESSAGE Descript.: Shows the specified text while assembling. Example: .MESSAGE assembling takes about 10 minutes .n (.8, .16, .32, ...) Descript.: Insert the given values in binary, each value having the given size. Comment: The byte ordering in .16 and .32 depends on the microprocessor (as defined by .PROC). The given size is added to the assembler program counter. Examples: .8 255, 0, 2'1111 ; range (.8): -256..+255 .16 16'FFFF .32 -1 ; = 16'FFFFFFFF .8.8.16 "A", "Z", AD_A_Z CALM pseudo-instructions page: 7 .ODD Descript.: Align the APC value to the next odd value (do not change if already odd). Comment: The content of the byte which is skipped is undefined. Example: .LOC 16'234 ; APC has the value 16'234 .ODD ; APC has the value 16'235 .ODD ; APC has the value 16'235 The pseudo-instruction .ODD is equivalent to: .ALIGN APC+1-(APC.AND.1) .PAGE Descript.: Starts a new page in the listing (.LST). Comment: When a parameter N is specified, ASCALM checks if there N lines remaining after .PAGE. If there are not enough lines, a new page starts. Example: .PAGE .PROC Descript.: Insert the mentioned processor description and generate the code for the processor. Comment: The CALM assemblers consist of a general part and a part which is processor dependent. Hence there exist only one CALM assembler program, but several processor descriptions. These files are loaded by the pseudo- instruction .PROC. Example: .PROC M68000 .PROCSET .PROCVAL Descript.: Allows some local adjustments in a processor module .PRO. Comment: .PROCSET allows names. .PROCVAL allows names and values. The names and the values are module specific. Examples: .PROCSET FPU ; allows FPU instructions (M68020.PRO) .PROCVAL FPU_ID 2 ; the FPU number is 2 .RANGE Descript.: Defines the allowed value range for .DATA, .FILL and .n. Comment: Predefined ranges: - .RANGE.8 -256,+255 - .RANGE.16 -65536,+65535 - .RANGE.32 16'80000000,16'7FFFFFFF ; special case, ; because 32 bit arithmetic Example: .RANGE.16 -32768,+32767 .16 value ; -32767 <= value <= +32767 .RANGE.16 -65536,+65535 ; default values CALM pseudo-instructions page: 8 .REF Descript.: Insert the mentioned symbol table. Symbol names and values are known. Comment: The pseudo-instruction .REF allows the loading of a set of symbols with fixed values directly in the assembler symbol table. These symbols are: - fixed memory addresses (e.g. in ROM) - hardware I/O definitions - non-printable ASCII-characters (e.g. CR, LF) - etc. The format of this file depends on the internal structure of the assembler symbol table. This method has two advantages. Firstly, the file loading is very fast (no analyse required) and, secondly, the file occupies less memory space than the equivalent method with .INS. Example: .REF SYMBOLS .START Descript.: Define the starting address. Comment: The starting address is the address, where the processor should start the execution. The default value is zero (if no starting address has been defined). Example: .START 16'100 .STRING Descript.: Same effect as .ASCII. Insert the length (8 bits) of the character string as the first code. Example: .STRING "Hello!" or: .ASCII "<6>Hello!" .SYSCALL Descript.: Defines a special instruction (system call). Comment: .SYSCALL.8, .SYSCALL.16 and .SYSCALL.32 are possible. Generates .8, .16, or .32 with the SYSCALL name and the calling name. Example: .SYSCALL.16 INT ; definition, in addition ; INTDOS=16'CD21 INT DOS ; call, generates: .16 INTDOS .TEXT Descript.: Until an .ENDTEXT is encountered, the following lines are ignored. Comment: With the pseudo-instructions .TEXT and .ENDTEXT, it is possible to insert additional information (like text, tables, graphics) in an assembly program. The assembler does not interpret this information as assembler statements, but copies them to the listing file. No limits are imposed for this information, however the following notation must be respected: .TEXT all is possible here .ENDTEXT .TITLE Descript.: Start a new page with the specified title in the title header. The title is repeated in the following pages. Comment: This pseudo-instruction is normally in the beginning of a program. One should indicate the name of the program. The system time and date should automatically appear in the listing header when possible. Example: .TITLE ASSEMBLER