APDL Public Domain 1

home *** CD-ROM | disk | FTP | other *** search

/ APDL Public Domain 1 / APDL_PD1A.iso / program / assembler / tla / Manual < prev next >

Wrap

Text File | 1993-10-11 | 24.9 KB | 890 lines

The TLA for the ARM ------------------- Last updated 12th April 1991 version 0.1f G.F.A.@ Lancaster copyright 1989--1991 G.F.A. Lancaster Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. COPYING POLICIES ---------------- You may copy and distribute verbatim copies of the TLA for the ARM as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy a valid copyright notice `Copyright 1989 G.F.A.@ Lancaster'' (or with whatever year is appropriate). You may not charge a distribution fee for the physical act of transferring a copy. You may not copy, sublicense, distribute or transfer the TLA for the ARM except as expressly provided under this license agreement. Any attempt otherwise to copy, sublicense, distribute or transfer the TLA for the ARM is void and your rights to use the programme under this license agreement shall be automatically terminated. However, parties who have received computer software programmes from you with this license agreement will not have their licenses terminated so long as such parties remain in full compliance. NO WARRANTY ----------- BECAUSE THE TLA FOR THE ARM IS LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING G.F.A. LANCASTER AND/OR OTHER PARTIES PROVIDE THE TLA "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL G.F.A.@ LANCASTER BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF THE PROGRAMME TO OPERATE WITH ANY OTHER PROGRAMMES) THE TLA, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. Acknowledgements ---------------- Electronic thank-you's go to the following persona: The idea of using the TLA for the Archimedes came from Edgar Fuss who is an old UCSD Pascal fanatic just like me. The original TLA version (for the 65000) was written by Jens-Erik Riedel. Edgar Fuss analysed the AOF format and tried to explain it to me. He also implemented TeX on the Archimedes so I could write the manual in texinfo! H & H supplied many tools including my Archimedes (those were the days). Tools GmbH, Bonn. ArchiTeX and ArcMF are avaiable from TooLs GmbH, Kes-senicher Strasse 108, D-5300 Bonn 1, Germany. Introduction ------------ Most users of the Archimedes do not require any other assembler than the BBC BASIC V assembler. But if you are using a programming language like Pascal or C, the BASIC assembler is inadequate as it is unable to generated AOF files which the linker requires. This assembler is supposed to fill that hole. The main reason I took the time to write an assembler myself was that the price for commerial AOF generating assemblers is in my opinion far too high and I needed one to implement MF for the @Archimedes. This assembler was modeled after the The Last Assembler (TLA) developed at the University of Waterloo. The actual implementation it is based on was the 65000 assembler by Jens-Erik Riedel for the Apple II. The basic concept behind the TLA is the use of a central machine-independent core that is common to all versions of the assembler. The central core is augmented with machine-specific code to handle the pecularities of each individual machine. One advantage over most other macro assemblers is that the TLA is a one pass assembler. There are some restrictions due to this but assembly is faster than with a multi-pass assembler. This manual is intended for readers familiar with the BASIC assembler or any other assembler for the Archimedes. It does not explain the ARM assembly language. Assembler Input File Structure ------------------------------ The overall structure of input files is procedure orientated. This concept is somewhat different from the structure of Unix or similar assemblers. Actual code can only be declared in a procedure block. Each procedure block shares global definitions that are given at the beginning of the input file with all other procedures. Global definitions are non-code generating operations. They define global constants, register identifiers, macros etc. Any identifier declared inside a procedure is local to that procedure except when exported. example .TITLE "TLA example file" ; define a title sp .EQU R12 ; sp is R12 link .EQU R14 ; link is R14 .PROC ernie STMFD SP!,{R0-R3,link} SWI OS_WriteS .STRING "Hello there!" LDR R0,MyString SWI OS_Write0 LDMFD SP!,{R0-R3,PC} MyString .STRING "Data string" .PROC bert TEQ R0,#0 MOVEQS PC,link LDR R0,DataWord DataWord .WORD 0FFFF .END In the above example the identifiers sp and link are global and can be used in every procedure. The identifier MyString is local to the procedure ernie} as DataWord} is to bert}. As shown in the example, all assembler directives begin with a period. This distinguishes them from other identifiers. The main purpose of this structure is to make assembler files more similar in structure to high level languages, so that it is easier to write external procedures for these languages in assembly language. Syntax of Assembly Statements ----------------------------- Identifiers ----------- Identifiers are character strings starting with a letter. The following characters must be alphanumeric or the underline '_' or the dollar sign '$'. The maximum identifier length is 255. On encountering an undefined identifier in an expression the assembler assumes that the identifier will eventually be defined as a label, which is the most probable case. Any identifier which is not a label must be defined before it is used. Labels ------ Labels are identifiers that represent a position in the code that is being assembled. The numeric value is an address in the code. Only labels and comments may begin in the first column, with no preceding spaces. Labels may optionally be followed by a colon which is not part of the label identifier. Local Labels ------------ Local labels must have a backslash '\' as the first non-space character. This is part of the label identifier and must be used in each reference. Their purpose is to conserve symbol table space and permit the use of an identifier name twice in a procedure. They are mainly used to jump around within a small segment of code. The local labels are held in a special stack separate from other identifiers so that they can even have the same name as a normal label (with a leading backslash '\'). This stack can hold up to 50 local labels. It is flushed each time a regular label is encounter at the beginning of a line. CopySomething LDR R0,Source LDR R1,Destination \CopyIt LDR R2,[R0],#1 TEQ R2,#0 STRNE R2,[R1],#1 BNE \CopyIt CopyAnother LDR R0,NextSource LDR R1,NextDest \CopyIt LDRB R2,[R0],#1 TEQ R2,#0 STRNEB R2,[R1],#1 BNE \CopyIt In the first loop of the example a word aligned structure is copied. The label at the beginning of the loop is a local label called CopyIt}. In the second loop a byte aligned structure is copied. The loop label has the same name as before but as a regular label occured before the local label stack was cleared and all local labels can be newly defined. Operators -------- The following operators can be used in expressions processed by this assembler: + As a unary and binary operator. - As a unary and binary operator. ~ As a unary operator, denotes ones complement of the following expression. ^ Binary operator for exclusive or. * Multiplication operator. / Division (DIV). % Remainder division (MOD). | Bit-wise OR. & Bit-wise AND. = Equal comparison. <> Not equal comparison. << Logical shift left. >> Logical shift right. All operators have the same precedence. Constants --------- Constants are either given as a numeric constant or as a character constant. The value used in an expression is always the numeric value of the constant. Numeric constants ----------------- Numeric constants begin with a digit (0@dots9), the following characters can be either further digits or the letters 'A'..'F' for hexadecimal constants. The default radix is hexadecimal, but you can specify the base by placing one of the following characters at the end of the constant: H For hexadecimal constants (default, e.g. 0F0H) . For decimal constants (e.g. 10.) O For octal constants (e.g. 756O) T For binary constants (e.g. 11001T) Character constants ------------------- Character constants are enclosed in single quotation marks. E.g. 'A', ';' and '['. Their numeric value is the ASCII value of the character. Expressions ----------- The handling of expressions is simple as opposed to high level language compilers. This may be changed in future releases. The assembler evaluates expressions from left to right, and all operators have the same precedence. Parentheses can be used to override straightforward evaluation 3+2*5 result = 25 3*2+5 result = 11 3+(2*5) result = 13 Expression Types ---------------- The assembler uses the following expression types: Boolean, Register, Absolute, Label. Boolean Boolean expressions have either the value TRUE or FALSE. They are mainly used for conditional assembly. Register Register expression specifiy an ARM register. No arithmetic is allowed in register expressions, they are used in assigments (.EQU) to define alternative names for the registers. Possible values are: R0 -- R15, PC}. Absolute Absolute expressions are the most common expressions. They specify absolute numeric values. You can use absolute expressions to define immediate constants or constants in the code (.WORD). They can also be mixed with label expressions. Label Label expressions are used to specify labels. Adding or subtracting absolute values from labels gives a label as result, but multiplying or other operations give an absolute value. Assembler Directives -------------------- Global And Routine Directives ----------------------------- Every assembly must include at least one .PROC and one .END, even in the case of stand-alone absolute code which will not be linked. PROC ---- Identifies a procedure or that should return no value. A .PROC is terminated by the occurence of a new .PROC or .END. FUNC ---- Is equivalent to a .PROC on the @Archimedes@ as the AOF file does not distinguish functions that return values from procedures that do not. END --- This directive is used to denote the physical end of an assembly. ABSOLUTE -------- If .ABSOLUTE is specified in an assembly file, the assembler will generated an executable absolute image, not a linkable AOF file. The directive must appear before any procedure is defined. ENTRY ----- Identifies a label which will be used as the entry point into a linked programme. .ENTRY Startup .PROC main .EXPORT Startup Startup . . . CODEAREA -------- Begin code area (read-only part) of AOF image. DATAAREA -------- Begin data area (read-write part) of AOF image. Label Definitions And Space-Allocation Directives EQU --- Assigns a value to an identifier. Used to assign register names, boolean flags and values to labels. Register identifiers can only be equated to other register identifiers. sp .EQU R13 Boolean identifiers can only be equated to boolean values, logical expressions are currently not allowed. Debug .EQU TRUE Labels may be equated to an expression containing labels and/or absolutes. One must define a label before it is used unless it will be simply equated to another label. A local label may not appear on the left-hand side of an .EQU. label .EQU value ORG --- Takes the operand of .ORG as the offset, relative to the start of the assembly file, where the next word or byte of code is to go. Words or bytes of zeros are produced to get the current location counter (LC) to the correct value. .ORG 9000 ALIGN ----- .ALIGN is used to align the code location counter to a certain byte boundary. If no absolute expression follows the directive a 4 byte word boundary is used. WORD ---- Allocates a word of space in the code stream for each value in the valuelist. Associates the (optional) declaration label with the word space allocation. Table .WORD 0, 2, 4 BYTE ---- Allocates a byte of space into the code stream for each value listed. Each value actually stored must have a value between 0 and 255. If the value is outside of this range an error will be flagged. If a label is associated with .BYTE, the address at which the byte is stored will be assigned to it BLOCK ----- Allocates a block of space into the code stream for the value listed with the given length. Data .BLOCK 4,6 This will allocate four bytes each with value 6. Data is a label to the start of the block. ASCII ----- With .ASCII you can specify ASCII data which is inserted into the code. A string must follow the directive. .ASCII "String data" STRING ------ Does the same as .ASCII, but adds a zero byte at the end of the ASCII data HASCII ------ Same as .ASCII but each byte allocated has the highest bit set. HSTRING ------- Same as .STRING but each byte has highest bit set. HBYTE ----- Allocates a byte of space with the high byte of the given value. .HYBTE 3000 This will insert the hex byte 30 in the code stream. LBYTE ---- Allocates a byte of space with the low byte of the given value. .LBYTE 1234 This will insert the hex byte 34 in the code stream. Macro Facility Directives ------------------------- A macro is a named section of text that can be defined once and repeated in other places simply by using its name. The entire macro definition may precede the first .PROC in the assembly file. The text of the macro may be parameterized, so that each invocation results in a different version of the macro contents. At the invocation point, the macro name can be followed by a list of parameters, each terminated by a comma (except for the last one, which is terminated by end of line or the comment character (;). The text of the macro definition, modified by substituting the invocation parameters, is inserted by the assembler at the invocation point. Wherever %n (where n is a single decimal digit greater than zero) occurs in the macro definition, the text of the n-th invocation parameter is substituted. Leading and trailing blanks are stripped from the parameter before the substitution. If the macro definition includes a reference to a parameter not provided in a particular invocation (too few parameters or no parameter before a terminating comma), a null string is substituted. A macro definition may not contain another macro definition. A definition can certainly, however, include macro invocations. This ``nesting'' of macro invocations is limited to five levels deep. .MACRO MOVEBYTE LDRB %1,[%2] STRB %1,[%3] .ENDM MACRO ----- Indicates the start of a macro definition and gives the macro an identifier. .MACRO identifier ENDM ---- Indicates the end point of a macro definition. Conditional Assembly Directives ------------------------------- Conditionals are used to selectively exclude or include sections of code at assembly time. When the assembler encounters a .IF directive, it evaluates the associated Boolean expression. In the simplest case, if the expression is FALSE, the assembler simply discards the text until a .ENDC is reached. If there is a .ELSE directive between the .IF and .ENDC directive, the text before the .ELSE is selected if the expression is TRUE, and the text after the .ELSE if the condition os FALSE. The unassembled part of the conditional will not be included in any listing. Conditionals may be nested. IF -- Identifies the beginning of an conditional. ELSE ---- Identifies the alternate to a .IF. If the conditional expression is FALSE then the else portion is used. ENDC ---- Identifies the end of a conditional. External Communication Directives --------------------------------- Separate routines may share data structures and subroutines by linkage from one assembly routine to another assembly routine. This is made possible through the use of .DEF and .REF. These directives cause the assembler to generate link information that allows separately assembled routines to be linked together. By using .DEF and .REF, one assembly routines may call subroutines found in another assembly routine. The use of .REF and .DEF is not limited to subroutines and data defined in other assembly files. You can reference any symbol defined in a AOF file, e.g. a C or Pascal routine or data. DEF --- Identifies a label that is defined in the current routine as being available for use in other AOF files. REF --- Identifies a label used in the curremt routine which refers to a symbol declared in an other AOF file. EXPORT ------ Is equivalent to .DEF. IMPORT ------ Is equivalent to .REF. Listing Control Directives -------------------------- LIST ---- Enable or disable listing. Listing can be toggled anywhere in an assembly. PAGE ---- Output a form feed onto the list file. TITLE ----- Set a title for the normal pages of a listing. .TITLE "P-Code Interpreter 1.1a" GTITLE ------ Set a global title for the pages of a listing. This title will always appear. .TITLE "This file is (C) Arthur Dent 1990." CONDLIST -------- Enable or disable conditional listing. .CONDLIST OFF MACROLIST --------- Enable or disable macro expansion listing. PATCHLIST --------- Enable or disable backpatch listing. NOLIST ------ Disable listing. NOMACROLIST ----------- Disable macro expansion listing. NOPATCHLIST ----------- Disable backpatch listing. File Directives --------------- INCLUDE ------- Include the specified file into assembly. Nesting is allowed. .INCLUDE "s.RegDefs" This will include the file @file{s.RegDefs. Configuration Directives ------------------------ PAGING ------ Turn paging on list file ON or OFF. With no parameter .PAGING defaults to ON .PAGING OFF PAGESIZE -------- Specify size of page as number of lines on a page. .PAGESIZE 50. CASESENSE --------- Enable case-sensitive or case-insensitive mode. SYMBOLTABLEDUMP --------------- Enable or disable symbol table dump at end of assembly. Default is ON. SIGNEDARITHMETIC ---------------- Enable or disable signed arithmetic. Obscure Directives ------------------ These are special hacks and can only be used by TLA wizards. ASECT PSECT PORG ERROR Command Line Arguments ---------------------- The TLA is executed from the command line, it can take the following form: tla [-bchvVw] [-l list] input [output] The input file is searched for with the directory prefix @file{s.. If no output file is specified the default @file{o.input is used. Otherwise the file name as specified. Command Line Options -b Enable batchmode. Execution will not stop when an error is flagged. -c Parsing will be case-insensitive. -h Display command line usage. -l list Generate a listing in file list. -v Display version number at beginning of assembly. -V Enable verbose mode. Output on VDU is like original TLA. Syntax Error File ----------------- The syntax error messages used by the TLA are kept in the file TLA_Errors. This file is searched for with the path variable TLA$Path and with the default system variable File$Path. Assembly Examples ----------------- A filetype set routine: SP .EQU R13 .PROC SetFileType STMFD SP!,{R0,R1,R2,R14} MOV R2,R1 MOV R1,R0 MOV R0,#18. SWI XOS_File LDMFD SP!,{R0,R1,R2,PC}^ .END The code fetch macro of my Infocom Adventure Z-Code interpreter (a parameterless macro). .MACRO ZIPFETCH LDRB OpCode,[IPC],#1 .IF Statistics BL CountStatistics .ENDC .IF Debug BL DebugCode .ENDC LDR PC,[PtrJmpTable,OpCode,LSL #2] .ENDM Macros for VIDC programming: .MACRO VIDC .WORD (%1 << 24.) | (%2 << 14.) .ENDM .MACRO VIDC1 VIDC %1,(%2-1) .ENDM .MACRO VIDC2 VIDC %1,((%2-%3)/2) .ENDM .MACRO ModeVIDC ; %1 = XRes, %2 = YRes ; %3 = HorBorderStart, %4 = HorBorderWidth ; %5 = VerBorderStart, %6 = VerBorderWidth ; %7 = HorSyncWidth, %8 = VerSyncWidth ; %9 = Adjust VIDC2 HorCycle,%1+%3+(2*%4)+1,2 VIDC2 HorSyncWidth,%7,2 VIDC2 HorBorderStart,%3,1 VIDC2 HorDisplayStart,%3+%4,%9 VIDC2 HorDisplayEnd,%1+%3+%4,%9 VIDC2 HorBorderEnd,%1+%3+(2*%4),1 VIDC1 VerCycle,%2+%5+(2*%6) VIDC1 VerSyncWidth,%8 VIDC1 VerBorderStart,%5 VIDC1 VerDisplayStart,%5+%6 VIDC1 VerDisplayEnd,%2+%5+%6 VIDC1 VerBorderEnd,%2+%5+(2*%6) .WORD -1 .ENDM Mode20VIDC .WORD 0 .WORD 20. ModeVIDC 640., 512., 131., 4, 18., 2, 36., 1, 7 .END Referencing external variables in assembler ------------------------------------------- C-Programme: int LittleInt; char BeautifulChars[20]; int main(void) { AssProc(); ... } Assembler Prcoedure: .PROC AssProc .IMPORT LittleInt .IMPORT BeautifulChars LDR R1, IntAdrs MOV R0, #0 STR R0, [R1] ; set LittleInt to 0 LDR R2, ChsAdrs STRB R0, [R2] ; set BeautifulChars to "" MOVS PC, R14 IntAdrs .WORD LittleInt ChsAdrs .WORD BeautifulChars .END Assembler Directive Summary --------------------------- Global And Routine Directives ----------------------------- .PROC procedure-name .FUNC function-name .END .ABSOLUTE .ENTRY label .CODEAREA area-name .DATAAREA data-name Label Definitions And Space-Allocation Directives ------------------------------------------------- label .EQU value .ALIGN [alignment] [label] .WORD [valuelist] [label] .BYTE [valuelist] [label] .BLOCK count[,value] [label] .ASCII string [label] .STRING string [label] .HASCII string [label] .HSTRING string [label] .HBYTE value [label] .LBYTE value @end example Macro Facility Directives ------------------------- .MACRO macro-name .ENDM Conditional Assembly Directives ------------------------------- .IF logical-expression .ELSE .ENDC External Communciation Directives --------------------------------- .DEF label .REF label .EXPORT label .IMPORT label Listing Control Directives -------------------------- .LIST boolean .PAGE .TITLE string .GTITLE string .CONDLIST [boolean[,boolean]] .MACROLIST [boolean] .PATCHLIST [boolean] .NOLIST .NOMACROLIST .NOPATCHLIST Listing Control Directives -------------------------- .INCLUDE string Configuration Directives ------------------------ .PAGING [boolean] .PAGESIZE value .CASESENSE [boolean] .SYMBOLTABLE [boolean] .SIGNEDARITHMETIC [boolean] Obscure Directives ------------------ .ASECT .PSECT .PORG value .ERROR