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] <Cr/Lf>

^^^^^   ^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^  ^^^^
 |    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 <expression>

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 <expression>

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 <expression>


.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 <expression>

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 <expression>


 .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 <symbolname>

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 <character string>

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 <character string>

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 <expression>



.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 <character string>

example: .Warning "This is not going well"



.DATE

Sets the date in the listing file header.

syntax:
    .DATE <character string>



example:   .DATE "11-10-96"



.TIME

Sets the time in the listing file header.

syntax:
      .TIME <character string>

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  <expression> <relation> <expression>
    .IFC  <expression>



.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] <targetname> <objectfile1> [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

<targetname> is the name of the hexfile and of the map file.
<objectname> 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.

