DISCLAIMER USAGE OF THIS SOFTWARE IS AT YOUR ONE RISK. THE SOFTWARE IS IN A BETA STAGE AND WILL ONLY WORK FOR A LIMITED TIME AFTER THIS TIME YOU WILL GET A NEW VERSION SEND BY EMAIL OR YOU MUST BUY THE FIRST OFFICIAL RELEASE. Chapter 1 Overview Chapter 2 Source program format Chapter 3 Operands Addresses and expressions Chapter 4 Assembler Directives Chapter 5 Macro processor Chapter 6 Errors and warnings Chapter 8 The linker Chapter 9 Instruction set Chapter 10 Output file format Chapter 11 Differences with Sgs-Thomson assembler Chapter 12 Copyright and disclaimer Chapter 1 Introduction This document describes ..... ST6 Assembler and linker usage..... 1.1 Overview This section provides some diagrams to give an overview of the ST6 assembler and linker package and how it might fit in the bigger ST6 development suite context. ---------- | Object | -------> | File | ------------- -------------- / ---------- | st6 source| | Eclipson | -----/ | file | -----> | Macro | | | | Assembler | -----\ ---------- ------------- -------------- \ |Listing | -------> | file | ---------- ----------- | Rel/Abs | | Object | ---\ | file 1 | \ ----------- \ ------> ---------- \ ------------ / | Bin | ----------- \ | | --/ | file | | Rel/Abs | -----> | Eclipson | -------\ ---------- | Object | -------------> | linker | ---\ -> | hex | | file n | ------> | | -- \ | file | ----------- / | | \ \ ---------- / ------------ \ \--> | map | ----------- / | \ | file | | Rel. | / | \ ---------- | Library | --- | \--> | debug | | file | \ \ | file 1 | ----------- \ \ ---------- \ -> | debug | \ | file n | \ ---------- \ \ \ \ ----------- \--------> | library | | | ----------- ------------ | Hex | | or | -------\ -------------- | bin file | \ | | ------------ \--> | Eclipson | | | | Simulator& | ------------ | | | Debug | ------------> | Debugger | | file 1 | | | ------------ /--> | for Win 95 | / | | ------------ / -------------- | debug | ------- | file n | ------------ Finally the assembler and linker will be fully integrated in the ST6 development environment, but will initially be released as two separate tools for MS-DOS (or UNIX). 1.1 Features - Two pass assembler - Macros - Conditional assembly - Nested source file inclusion - Relocatable and absolute object modules - ... 1.2 Platforms supported Assembler and linker - IBM PC or compatible, running MS-DOS 4.0 or higher (ask information for LINUX, AMIGA, Macintosh or other UNIX platforms) Check config.sys Check if the "files=" statement in the file config.sys is high enough. 1.3 Command-line usage General syntax is: EASM [options] sourcefile [sourcefile] [sourcefile] [....] The options are: coresponding option function default value directive --------------------------------------------------------------------- -L, -l turn on listfile generation No listfile .list 1 -C, -c Turns on case sensitive assembly Not case sensitive - -D, -d Generate Debug info in obj file No debug info .debug -P, -p Defines pagelength in list file 40 .pl=40 usage: -P=3D35 -W, -w Defines the page width 127 .linesize=80 usage: -W=3D80 range 20-228 -T, -t defines the table lenght 8 usage -T=3D3 range above 5 If sourcefile has no extension .ASM will be added to the filename. Chapter 2 Source program format 2.1 A source file consists of blocks of instructions (sections) and a global data declaration block. The sourcefile starts with the (file) Global data declaration and the external declarations. Symbols defined here may be used in the hole file. In the global data declaration part no st6-instructions are allowed. A section marks the start of the block of code. A section may be relocatable (.SECTION) or it can be absolute (.ORG). In a section you can declare local data sybols, those symbols are unknown outside the section. A source file typically exists of a filename with the .asm extension. The file consists of lines with a maximum of 127 characters. Each line is terminated by a newline and/or linefeed character (0dH,0aH) Each line has at most one statement. A source line consists of four fields and a newline. The fields are label field, operation field, operand field, and comment field The general form of all source lines is as follows [label] mnemonic [Operand],[operand],[operand] [;comment] ^^^^^ ^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^ | operation field | Comments | | Operands (newline/carriage return) labelfield For example Loop ld a,10h ; This is comment label : LOOP operation : ld operands : a and 10h comment : This is comment The label field is optional but is exits it must start at the first position The operation field must have a leading space or tab. The Operation can be a ST6 mnemonic or a assembler directive (see chapter 4) The operand field depends on the operation field. Some operations don't have any operands, while others may have many. The comment field is optional, but if it is used, it should always begin with a semi-colon. Any text following the semicolon will be ignored by the assembler. Example: ; this is a comment starting at pos 0 Lab1 jp interrupt_req ; this is is a comment after an instruction 2.3 Numbers A number can be specified in a specific dataform Four different formats: hexadecimal, octal, decimal or binary. Each format A number without any suffix is considered to be decimal. Hexadecimal characters can start with the characters 0-9 and a-f. When a valuee start with a character a-f and the same symbol exist the symbol will overule the value. ------------------------------------------------------- Base suffix legal characters examples ------------------------------------------------------- Hexadecimal (16) H,h 0-9,a-f,A-F 1234h,a8H,0a8H Decimal (10) none 0-9 1234,001 Octal (8) O,o 0-7 117O,77o,123o Binary (2) B,b 0,1 10101B,1111111b 2.3 Characters strings A character string starts and and with a double quotation mark example : "This is a character string" 2.4 Symbols A symbol (identifiers) may represent a numeric value, a programspace address, a dataspace address, a register name. Symbols have the following restrictions: - Maximum of 31 characters long - Any character except space and comma It is advised that the first character of the symbol is in the range a-z,A-Z or underscore. Any following character should have an ASCII value between 33 and 127 except comma. - Symbols can't have the name of the reserved names (the predefined symbols) Some examples of symbols: source used symbol(s) buf .rds 2 ; buf test .def 80 ; test .extern testadc ; testadc .extdata mem ; mem .section interrupt ; interrupt Loop jrr 1,test,Loop ; test and Loop And_This_Is_A_Long_Symbol JP Loop ; And_-This_Is_A_Long_Symbol and = Loop The predefined symbols $ and PC (redefineable) currently represent the program counter. --- to be filled in ----------- Chapter 3 Operands Addresses and expressions 3.1 Operators There are two kinds of operators: - Arithmetic - Relational 3.1.1 Arithmetic Operator example meaning ------------------------------------------------- +,- -7 +4H unary plus or minus (give number a sign) +,- 2+10-3 addition substraction * 100H*3 multiplication / 80/3 Division ~ ~2 bit inversion (1's complement) % 100%2 Modulo & 100&10 Bitwise and | 100|10 Bitwise or ^ 32 ^ 8 Bitwise exclusive or 3.1.2 Binary NOT HIGH LOW SHR,SHL AND OR XOR ----- to be filled in---------- 3.1.3 Relational function -------------------------------- >= GTE Greater then or equal <= LTE Less then or equel <> NEQ Not equal = EQ Equal < LT Less than = > GT Greater than DF Defined NDF Not Defined The relational operator only works with the .if directive ------- to be filled in -------- 3.2 Oprarator Precedence ------ to be filled in ----- 3.3 Numerical expressions ---- to be filled in --------- Chapter 4 Assembler Directives A directive should not be confused with an ST6 instruction. The main difference is that a directive does not produce object code, except for directives: .word, .byte, .block and .ascii. They change the state of the assembler and add information to the objectfile or listing files. The directives are divided in 6 groups: - Symbol definition - Memoryspace Reservation/allocation - Program Linkage and assembler state control - Listfile state control - Conditional, macro and preprocessor directives - Not supported, obsoleted and future enhancement directives. 4.1 Symbol definition .DEF Assigns directive an internal dataspace to the specified symbol. syntax: Symbol_name .DEF The expression must be a simple non-relocatable expression and may not contain forward references. note: r-mask, w-mask and !m are not yet suported (!m will not be supported) .EQU Assigns a numerical value to a specified symbolname. syntax: Symbol_name .EQU The expression must be a simple non-relocatable expression and may not contain forward references. A symbol defined by EQU may not be redefined or undefined in a later state. .SET The SET directive is similar to the EQU, except that the defined symbol may be undefined (UNSET) or redefined by another SET. syntax: Symbol_name .SET .UNSET Unsets a set declaration. If the symbol is only once defined using the SET directive, unsetting a symbol will result in an undefined symbol. However, if the SET directive has been used more than once, the UNSET directive restores the previous value of the syumbol. syntax: LabelName .UNSET 4.2 Memoryspace Reservation/allocation 4.2.1 Data space allocation .RDS Reserves a number of bytes in the dataspace. syntax: Symbol_name .RDS The expression must not contain relocatbale symbols and may not cantain forward references. The result of the expression should not exceed the limitation of the ST6 processor. example: buf .RDS 10 ; allocates 10 bytes buffer 4.2.2 program space allocation intialization .BYTE Initializes program memory with byte values. syntax: [label] .BYTE expression[,expression][,expression,...] The results of the expression(s) must be between 0-255. If this not the case a warning is generated and the value will be 8 least significant bits of the expression (i.e. expression modulo 256). .WORD The WORD directive is similar to the BYTE directive except that it stores two byte values. The high byte is stored at first address and the low byte is stored at the next address (also know as "little endian"). syntax: [label] .WORD expression[,expression][,expression,...] .BLOCK Allocates a specifeid number of bytes the bytes will be written with zeroes. syntax: [label] .Block Expresion Future syntax: [label] .BLOCK Expresion, fillbytes where filLbytes is a 8 bit value that fills the block .ASCII and .ASCIZ These directives store an ASCII string in program space. The difference between these two directives is that ASCIZ will append a null character after the last byte of the string. syntax: [label] .ascii character_string [label] .asciz character_string 4.3 Program Linkage and assembler state control .EXTERN Lists the program symbol(s) that are defined in other modules (.asm or .lib) syntax: .extern symbol[,symbol][,symbol,...] .GLOBAL and .PUBLIC You can make a data space or a program space symbol public for other modules to use it. PUBLIC is the replacement name of the GLOBAL directive. The use of GLOBAL is still possible, however a warning will be generated. syntax: .global symbol[,symbol][,symbol, ..] .EXDATA Lists the data symbol(s) that are defined in other modules (.asm or .lib). syntax: .EXDATA symbol[,symbol][,sumbol,...] .ORG Markes the start of an absolute program section. The section ends by another ORG directive , a SECTION directive or an END directive. syntax: [label] .ORG .SECTION The section tells the assembler that a relocatable section has started. the section end by an ORG directive, another section directive or an END directive. syntax: [label] .SECTION The symbolname can either be a number between 0 and 32 (to be compatible) or it can be a normal symbol. .WINDOW The window directive starts the beginning of a window section in program space a windows end when 1 an ORG 2 an SECTION 3 An END syntax: [label] .WINDOW [Symbolname] .END The END directives markes the end of the sourcefile any lines after the .END directive a ignored. If the assembler reaches the end of the file without having seen an END directive a warning is generated. syntax: .END 4.4 Listfile state control .DISPLAY Prints the string to the standard output (console) during the assembly process. Syntax: .DISPLAY example: .diaplay "Reached second part." .EJECT The EJECT will generate a newpage in the listingfile. A formfeed will be generated and a new header will be written to the list file. If no listfile is open a warning will be generated. syntax: .EJECT .ERROR This directive will generate an error with the specified string. Syntax: .ERROR Example: .if NDF SYMBOL .error "symbol not defined" ; when the symbol is not defined an error will occur .endc .LINESIZE Sets the length of a line in the listng file syntax: .LINESIZE .LIST List will turn on listing file generation. It is possible to turn on and off the listing file so only a part of the listing will be in the listing file. syntax; .LIST expression If the result of the expression is one (1) the listfile is turned on If the result is zero (non 1 value) the listing file is turned off For every list 1 must be a list 0. A list can be nested. .PL Sets the pagelength of the listing file. syntax: .PL expression example: .PL 66 ; sets the pagelength to 66 lines including headerline .TITLE Changes the headerline of the listingfile. syntax: .TITLE character_string example: .TITLE "This is my assembly file" .WARNING This directive will generate a warning with the specified string. Syntax: .Warning example: .Warning "This is not going well" .DATE Sets the date in the listing file header. syntax: .DATE example: .DATE "11-10-96" .TIME Sets the time in the listing file header. syntax: .TIME example: .TIME "Twelve O'clock" .DEBUG Turns on debug information required by the simulator. syntax: .debug 4.5 Conditional, macro and preprocessor directives .ELSE The assmbler continues here if the exprresion of the corresponding IF results into false. Syntax: .ELSE .ENDM Markes the end of a macro. syntax: .ENDM .ENDC Markes the end of (a nesting) conditional assembly. Syntax: .ENDC .IFC --- to be filled in ------------ These directive allows conditional assembly. syntax: .IFC .IFC .INCLUDE AND .INPUT These directives include a second file into the source of the current. When during assembling the .include directive occurs, the assembler continue with the pecified file. At the end of the included file the assembler resumes with the first file. Nested includes are allowed upto 10 levels. .MACRO Macro work the same as with the SGS-Thomson assmbler and allow nesting upto 10 levels deep. See Chapter 5 macro processor. 4.6 - Not supported, obsoleted and future enhancement directives. .CDEBUG Future enhancement. Support for coming C-compiler. .DP_ON Future enhancement or future obsolete directive. .NOTRANSMIT Obsolete. Use public and extdata instead. .PAGE_D Future enhancement. .PP_ON Future enhancement or future obsolte directive. .ROMSIZE Obsolete directive. Size matching is done in linker. .TRANSMIT Obsolete directive. Use Public and exdata instead. .VERS Not supported. .W_ON Obsolete. Don't need this directive windowing is automaticly done. .LOCALE Not supported maybe future enhancement. .REP Future enhancement macro directive. .REPP Future enhancement macro directive. .MEXIT Future enhancement macro directive. Chapter 5 Macro processor Almost compatible with the SGS-Thomson assembler ------- to be filled in ------------ Chapter 6 Errors and warnings ----------- to be filled in ----------- Chapter 8 The linker Linker Commandline The linker can relocate sections with absolute jumps and 8, 5 and 3 bit relative branches. Dataspace symbols can also be relocated. ELNK [options] [objectfile] [objectfile] options are Option function default value -s,-S Loads Shapefile ST6210 -c,-C case sensetive on Not case sensetive -d,-D Debug info on No debug -p,-P Sets pagelength 40 -w,-W Set page width 127 is the name of the hexfile and of the map file. is the name of the object files or library file If no extesion is given .obj will be used Chapter 9 Instruction set ADD A,(X) ADD A,(Y) AND A,(X) AND A,(Y) COM A CP A,(X) CP A,(Y) DEC (X) DEC (Y) DEC V DEC W DEC X DEC Y INC (X) INC (Y) INC V INC W INC X INC Y LD (X),A LD (Y),A LD A,(X) LD A,(Y) LD A,V LD A,W LD A,X LD A,Y LD V,A LD W,A LD X,A LD Y,A RETI RET RLC A STOP SUB A,(X) SUB A,(Y) WAIT ADDI A,expsresion ANDI A,expression CPI A,expression SUBI A,expression LDI expression ADD A,expression AND A,expression CP A,expression DEC expression INC expression SUB A,expression LD A,expression = ADDI A,expression ADD A,expression ANDI A,expression AND A,expression CPI A,expression CP A,expression DEC expression INC expression SUBI A,expression SUB A,expression LDI A,expression LD A,expression = CALL expression JP expression JRC expression JRNC expression JRNZ expression JRZ expression JRR expression,expression,expression JRS expression,expression,expression LDI expression LD expression You can also use the disassembler on random file to see a few. Chapter 10 Output file format Check generated files ---- TO BE FILLED IN ------- Chapter 11 Differences with Sgs-Thomson assembler -The most inportend changes are some of the directives. for example .EXDATA (new) .SECTION (enhanced) .TRANSMIT (Obsolete) -Another change is that symbol names can be 31 instead of 8 char's long. -The assembler can make debug info for simulator. -Section and org can be mixed in one or more files. -Global symbol en local sysmbols in a section. Chapter 12 Copyright and disclaimer Disclaimer This software is a beta product meaning that it may contain bugs !!!!! THIS SOFTWARE IS PROVIDED "AS IS", WHITOUT WARRENTY OF ANY KIND, EITHER EXRESSED OR IMPLIED. THERE IS NO GUARANTEE THAT THE SOFTWARE WILL FUNCTION AS DESCRIBED IN THIS MANUAL. IN NO EVENT WILL THE AUTER BE LIABLE FOR DIRECT, INDIRECT, INCIDENTAL OR CONCEQUENTIAL DAMAGES OR DATA LOSS RESULTING FROM THE USE OR MISUSE OR APPLICATION OF THIS SOFTWARE. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMACE OF THIS SOFTWARE IS ASSUMED BY THE USER. Copyright notices EASM, ELNK, EDIS AND ESIM is (c) A.C. Vreugdenhil and A.A. Klos of Eclipson. It is not publicdomain nor shareware, meaning that you are not allowed distribute it in any way. ST6 and related name are (c) by SGS Thmoson Other trademarks are (c) by there respective owners.