README.DOC

                      S3Asm

                  Version 2.00C


  Copyright Giles Goddard and Krister Wombell 1994


Introduction:
------------

 S3Asm is an 8086 machine code assembler for Psion Series3a pocket
computer. The bulk of the program is written in 8086, so its capable
of very high assembly speeds. 

 Machine code compiled using S3Asm can be incorporated into OPL
programs or can be translated into an image file ready for running
from the System screen.



WARNING:

 Extreme caution should be taken when using this program, if the code
you have just assembled has a bug, it could and most often does, crash 
the machine. Also, S3Asm holds NO WARRANTY. If the bug is caused by S3Asm 
itself not assembling correctly, then neither us (the authors) or Psion 
can be held responsible for any loss of data or damaged caused to you, your
machine or anything else in near proximity.


Registration:
-------------

 This version of S3Asm is fully functional, the only limitation is
the size of the output object code. This is set 256 bytes, which is
more than enough for most small programs. If you would like to 
assemble larger programs or if you just want to show your appreciation 
for this software please register it by either,

Sending 10 UK pounds to:

 Giles Goddard,
 6, Court Royal Mews,
 Northlands Road,
 Southampton. SO3
 England.

Or,

 Typing GO SWREG on Compuserve and following the prompts. S3Asm's
registration code is 2703 and it costs 20.00 dollars.


Installation:
------------

If you have RFM installed you may prefer to use the PC batch file
Install.bat to setup S3Asm. It assumes you have the s3a connected and 
ready. Otherwise just follow these simple steps:

Copy S3Asm.opa into an \APP directory on your Series3a, any drive will 
do, and install it by pressing Psion-I from the system screen.

If everything is well you should have the S3Asm icon with S3Asm
written underneath.

Next, make a directory on any drive called \ASM which holds the
source files for any machine code you write. 

copy s3obj.opl to \OPL 
copy s3obj.opo to \OPO

These files are used to load object code into your OPL programs.


If you would like to use the example source and EPOC service include
files then please:

Make another directory called \INC which holds the include files.
copy *.inc to \INC 
copy *.asm to \ASM
copy win.opl to \OPL

Selecting one of the example files that should appear under the S3Asm 
icon by pressing enter will run S3Asm using that file.



Usage:
-----

 When you run S3Asm you should be presented with a menu of commands,
these are:


Open file - Change the current source file.  

Setup     - Change the intialisation file for S3Asm.
Reset     - Reset intialisation file to default settings.

Assemble  - Start assembling the current source file.

Register  - Register S3Asm to assemble larger files and to the remove 
            nag screen.
About     - Show information about S3Asm.
Exit      - Exit S3Asm



Setup:
-----

The setup file for S3Asm is 'M:\OPD\s3asm.ini' it is created 
automagically and reset to the default settings when you first run S3Asm. 
You can change these settings using the Setup menu command.

Memory:

Amount of memory allocated for source block. S3Asm loads your source
file in small chunks or blocks. If you dont have enough memory on
your machine for the default setting, you can reduce the amount
allocated.

Amount of memory allocated for object block. This is the maximum size
of you object code output. For non-registered users this is limited
to 256 bytes.

Amount of memory allocated for symbols. Everytime you define a label,
equate or variable the name gets added to the symbol list. This is 
the total memory available for all your symbols names.

Amount of memory allocated for Forward References. If you reference a
label or variable which has been defined later on in the source file,
S3Asm stores this reference in the FR block and then later adjusts
the object code.

Amount of  memory allocated for relocations. If you use non-relative
addresses, such as referencing a variable or address of a variable
then S3Asm stores this information into the relocation block. When you 
use the object file in your OPL program, the relocation is automatically 
done for you.

Amount of memory for macros. Macros take up memory whenever they are
defined, this lets adjust the maximum amount of memory for all the
macros.


Directories:

S3Asm normally writes all of its output files back into the directory
from where the source file came from. You can override this for each
output file type.

Binary files, .BIN files that use loaded into your OPL programs.

Image file, .IMG files that can be run from the system screen.

OPL files, .OPL files that can be included into your OPL programs and
compiled.
(Warning: It can be dangerous to set this to your main \OPL
directory, where S3Asm may write over an existing OPL file of the
same name.)


Image files:
The intitial stack size and priority used when creating image files
may be changed.





Creating source files:
----------------------

Source files may be created using the built in Program application.
The easiest way of doing this is by installing the Asm.als file included 
with S3Asm, which makes a 'virtual' copy of Program and tells it to use 
the directory \ASM and files with the .ASM extension. Copy the file 
Asm.als into a \APP and install it using Psion-I. You can then create 
and edit files the same way as you would OPL files.



Assembling source files:
------------------------

When you assemble a source file S3asm asks you which type of output
you would like, this can be Binary, OPL or Image. This can be made 
automatic by placing the word BINARY, OPL or IMAGE at the top of your 
source file, eg.

    BINARY

    mov ax,0

    retf

or,

    OPL

    mov ax,0

    retf

or,    

    IMAGE

somedata
    dw 1234

    CODE   
    mov ax,0
    retf


Notice the CODE line in the last example. This tells S3Asm where your
actual program starts. Image files are split into 2 parts, the Data
segment and Code segment. All variables and other data should be
placed before the CODE statment. 

If you select OPL output then S3Asm will ask you to give it a
variable name. This variable is used to put object code into, see
below for more details.



Note: The option to write out Image file types at the end of assembly
is just included for completeness. If you select this option you will 
be warned that you have no IMAGE statement in your code.


Assembler syntax:
----------------

S3Asm tries to keep to standard 8086 assembler syntax where possible.

Comments must start with a  ';'  unless they come after the end of
the instruction ie.

; This  is ok

    mov ax,0  ; so is this
    mov ax,1  and this

but this is not





Instruction format:

Instructions and data declarations must be preceeded by at least one
space or tab, ie.
  
 mov ax,1 ; is ok
mov ax,1 ; is bad

Labels and equates:

Labels and equates must start a line, ie. no spaces or tabs before
them, ie.

    mylabel  mov ax,0   ; is bad

mylabel  mov ax,0       ; is ok


Labels and equates must start with a non digit and can be upto 255
bytes long. ie.

6label dw 0            ; is bad

label6 dw 0            ; is ok

datapp1 equ $28   ; is ok


Also, for future versions please dont use labels with these
characters:

 - * , / + = % ! & > < $ " 



References to labels must be enclosed in square brackets, eg.

   mov ax,[a_label]



Addresses of labels use the OFFSET syntax, eg.

  mov bx, offset a_label

  mov ax,[bx]



Absolute addresses use the ABS syntax, eg.

  mov ax, ABS [datapp1]





Data:

 There are 3 types of data statement:

  db 0
  dw 0
  db "A string",0




Numbers:

 ASCII, Decimal, Hex and Binary numbers are supported, they have the
following syntax:



    mov ax,1234    ; a decimal number

    mov ax,$5678   ; a hex number

    mov ax,%0101   ; a binary number

    mov al,"a"     ; an ASCII character must be surrounded by quotes



Macros:

 Macros can be defined as such;

Name MACRO
     mov ax,!0  ; move 1st parameter into ax
     mov ax,!1  ; move 2nd parameter into ax
     ENDM

!0 to !9 are used to reference parameters, !0 being the 1st, !9 the 10th.

To envoke the macro use;
    name parameter1,parameter2.... 

eg.

increg MACRO
    inc !0
    ENDM

    increg ax

Macros cannot be nested.





Include files:

Include files can contain machine code, data, macros, equates or indeed 
anything that you would use normaly in a source file. They must be 
placed at the top of your main source file and cannot be nested. ig.

  include "m:\inc\win.inc"


The standard convention for include filenames is to have a .INC
extension and to be placed in a \INC directory.



Epoc functions:

S3Asm has a special instruction for defining EPOC service interupts.
Its syntax is such:

Name  EPOC  Function number, Int number, register1, register2....

eg.

HeapAllocateCell    EPOC   $00,$81,cx

    HeapAllocateCell  1000


And would expand out to be;

    mov cx,1000
    mov ah,$81
    int $81




How to use your assembled file:
------------------------------

 As mentioned earlier, S3Asm can output 3 types of file; Binary, OPL
and Image.

Binary files (with extensions .BIN) can be loaded into your OPL
programs using the Procedure LoadO: (fname$), which is included in
the S3Obj.opl file. A typical example would be;


    Global ass%

    LoadM ("m:\opo\s3obj.opo")

    ass%=LoadO:("m:\asm\win.bin")
    if ass%=0  : Alert ("Unable to load binary file")  :  endif

    usr(ass%,0,0,0,0)


LoadO: attempts to load the file, allocate enough memory to hold it
and then relocate any references that need to be. It returns a
pointer to the start of the machine code, which you then use to USR
to.
LoadO: returns a 0 if it cannot load the file for any reason. It also
Raises an error if there are any file errors. You could trap these
errors using the OPL command ONERR, to jump to your own error
handler.


S3Asm's OPL output files can be included into your OPL source code. 

  Global ass%
  Global a&(6)

  a&(1)=&73413353
  a&(2)=&4C504F6D
  a&(3)=&00000010
  a&(4)=&201B0000
  a&(5)=&00CB0001
  a&(6)=&00000000

  LoadM ("a:\opo\s3obj.opo")

  ass%=Reloc:(addr(a&()))
  if ass%=0 : Alert ("Cannot relocate") : endif

  usr(ass%,0,0,0,0)


Reloc: attempts to relocate any references that need to be. It
returns a pointer to the start of the machine code, which you then
use in the USR function. 
Like LoadO: you can use ONERR to trap any errors produced by Reloc:

Both the above procedures may be be copied and used in your OPL
source code freely. The original OPL source file for these procedures
can be found in S3Obj.opl


Image files should be copied into a \IMG directory and can be run
using the RunImg standard application. 

Note: There will be a utility available soon to registered users that
allows .APP files to be created from these .IMG files.


Example files:
-------------

S3Asm comes with some example files to help you get the jist of whats
going on. They are:

win.asm - Open a window and bitmap, and draw directly using 8086.
win.opl - After you have assembled the above file, you can load it
          using this OPL program.

winimg.asm - This is the same as the above, except it is a stand
             alone Image file version. Use RunImg to run it.
	     (Note: At the time of writing, this only works in 
                    series3 compatability mode)


Please take a look at what they do and how they work.


Using the Epoc include files:
-----------------------------

Most if not all of the EPOC service interrupts are included in the
following files:

buffers.inc  
dbf.inc      
gen.inc      
io.inc       
mem.inc      
proc.inc     
win.inc      

Please read the relevent SDK documentation for full details.



Bugs and Contact:
----------------

Please send any bugs, suggestions or hellos to:

Giles Goddard at

gsg@cix.compulink.co.uk
Compuserve - 71125,532
giles@twics.co.jp

or

Krister Wombell at

kristerw@cix.compulink.co.uk


(thanks to dw2@Psion for his help and advice)




Disclaimer
----------
Neither us (the authors) or Psion can be held responsible for any loss 
of data or damaged caused to you, your machine or anything else in 
near proximity caused directly or indirectly by S3Asm or its
associated programs.

S3Asm is copyright Giles Goddard and Krister Wombell 1994

This zip file may be distributed freely as long as all files
are kept together in their original form.



END OF FILE