
	Octa-assembler version 0.17

	Octasm is a multi-pass assembler for x86 processors
At least a cpu 80486 and OctaOS or DOS is required.
DOS version can work in dpmi (dos protected mode interface) or in real mode
if any memory manager is detected it will use all the available memory
if a memory manager other than xms (vdisk,emm386) is detected, only conventional
memory  will be used

In this doc only especial features of Octasm are explained, is assumed
that the reader already knows x86 instruction set.
Octasm has a complete ia32 instruction set but instructions added after
Pentium processors are not well tested
Octasm has no command line options, everything is inside the source
source files must start with the string: 'LANG OCTASM,0.1'
Octasm is case sensitive and most instructions are lower case
Intel like sintax is used with some exceptions.
_______________________________________________________
Files:
	Filenames are relative to the directory or current source, unless a
	absolute pathname is used.
	Filenames should begin with '\' and should end by ' ' or new-line
	others chars are valid included ';' but is recommended to use
	normal names without operator chars.
	files can be used as operands, octasm open the file in mode r/w/create
ex:
eax=\file.pcx          ;eax= file handler1
eax=\file.pcx          ;eax= file handler2

Octasm can assemble or link various source and elf relocatable files
To include a binary file use directive include:
include file,position,number of bytes to copy
	       used to copy binary files inside the program
	       position and number of bytes are optional
ex:
\test.asm               ;assemble a source file
\lib\test.elf           ;link a elf relocatable file
include \a              ;copy a binary file in the output
include \img.bmp,54,100 ;copy 100 bytes from \img.bmp starting at offset 54

file_out \file
	 sets the file where assembled data must be writen
	 can be used in every section (not in virtual)
	 examples:
	 section 0                      ;assembled to ram memory
	 section 1                      ;assembled to ram
	 section 2  file_out \prog.com  ;assembled to 'prog.com'
	 section 3                      ;virtual , no code output
	 section 4  file_out \prog.dat  ;assembled to  'prog.dat'
	 section 5                      ;assembled to  'prog.dat'
					;etc...

file_sym file
	sets the file to store the symbol table
	is a file that defines all the names used in a program
	can be used only one time.
	symbol tables are useful for making:
	incremental compilation,overlays and debug.
	When assembling to ram the program works like a octasm's
	overlay and octasm code can be used including the
	symbol table
	example:
	lib{ \octasm.sym } ;'octasm.sym' is generated from 'octasm.asm'
			   ;the use of 'lib' directory prevents from
			   ;name conflicts
_______________________________________________________
Asembling programs to ram
	Octasm allows directly execution of source code without writing
	executable files on disk.
	Programs must exit with 'ret' instruction
	this version can only run 32 bits programs
	Octasm for DOS versions before 0.16 can run 16 bit programs.

Asembling programs to files
	By default octasm initializes with: 'org 0 use16_32'
	to make a '.com' program these instructions are required:
	org 100h use16
	and instructions like 'eax=\file ' should not be used

_______________________________________________________
single line comments can be added after the char ';'
for multiline comments write ';;' at the begining of first and last text lines.
examples:
;;      comment begin here
	and
	finish
;;      here
  ;;    this is a single line comment because ;; are not the first chars of the line
;single comment too

_______________________________________________________
Instruction that always have only one operand can be writen with multiple
operands, octasm will repeat the same instruction for every operand
ex: 'pop ax,5,[bx]'   is assembled as 'pop ax pop 5 pop [bx]'
Instruction 'push' is the exception because it gets operands
from right to left.
ex: 'push ax,5,[bx]'  is the same that 'push [bx] push 5 push ax '
a few instructions can be writen using keywords or like this:
ex:             is the same that:
eax=0           xor eax,eax
ax=[bx+2]       mov ax,[bx+2]
ax=bx+2         lea ax,[bx+2]
es=ss           push ss pop es
es=5            push 5  pop es
d[bx]=[esp+4]   push d[esp+4] pop d[bx]
eax=ah          movzx eax,ah
f1()            call f1    ;without spaces
f1( 1,2,3 )     push 1,2,3 call f1
++eax           inc eax
--eax           dec eax
eax+=eax        add eax,eax
eax-=eax        sub eax,eax
al=!0fh         mov al,0f0h ;0f0h=not 0fh
&=  and
|=  or
<<= shl
>>= shr
_______________________________________________________
Names:
	In octasm names can be numbers,offsets and directories
the same name can be used for a directorie and a number/offset
examples:
n1=10           ;now 'ax=n1' is equivalent to 'ax=10'
#l1             ;offset/label definition 'l1:' in others assemblers
#               ;anonimous label
{               ;anonimous directory ,names used in this dir.
		;can be used only in this dir.
}               ;close dir.
d1{             ;definition of directory 'd1'
  #l1           ;complete pathname is d1\l1
  #l2{          ;definition of directory and offset
     #l2 { }    ;offset + anonimous directory
     l1()       ;if 'l1' is not defined in actual directory it will be
		;searched in parents directories
     d1=5       ;pathname 'd1\l2\d1'
     ax=d1      ;ax=5
     }
  ax=d1         ;ax=2
  ax=l2\d1      ;ax=5
  l2\l2()       ;outside of directory 'l2' the pathname is required
  jmp <1        ;error because '#' is not defined in this dir. but in parent
  jmp >1        ;jmp forward
  #
  }
d1=2            ;'d1' already defined as a dir. and now is also a number.
jmp <1          ;jmp back
_______________________________________________________
Numbers:
numbers are case insensitive.
hexadecimals end with 'h' and start with '0' if first char is a letter
hexadecimals can also start with '0x'
ex:  43h 0123h  0xa1
binary numbers end with 'b' ex: 1101b
floating point numbers should have '.'
ex:        1.0e34  -0.0034E+3
character _ can be used to make numbers more readable
ex:  1001_0010_1111_0000_b
_______________________________________________________
Strings:
	'" are used to delimite text strings
sigle cuote ' means that the string is placed in the instruction
double cuote " stores the string in 'section text' and returns a pointer.
examples:
		eax='A'+1 ret
is equal to     eax=65+1 ret
		eax="hello world" ret
is equal to     eax=label ret #label db 'hello world'
eax='hello word'    ;erroneus because the string has more than 32bits
two commads can be used inside a string:
%nb       returns the number of bytes to the end of the string, 255 max
	  must be followed by one espace.
%0-255    used to represent any char ,if followed by a espace ,the
	  espace is suprimed.
%name     if name was defined with 'define' then it is preprocessed
%\        continue on next line
example: db '%nb %13%10 %nb '     equals to :  db 2,13,10,0
_______________________________________________________
multiline instructions
	character '\' followed by ';' or new line means that the instruction
continues on next line,on strings %\ is used.
_______________________________________________________
Arithmetic:
	octasm uses the math coprocesor to calculate expressions
is important to know how numbers are rounded:
in octasm 3/2=2   in others assemblers 3/2=1
because 3/2=1.5 and 1.5 is rounded to 2
_______________________________________________________
anonimous labels '#':
	previous labels '<1' max 7
	next labels     '>1' max 8
examples:  jmp >2 jc >1 # jc <1 #
_______________________________________________________
Pointers:
	Pointers are memory locations
	brackets are used ex:'[bx+5]' '[5*ebx+es+5]' 'd[cs+128]'
	the operand size must be before the brackets
	ex: 'd[bx+5]'
	operand size must be used only if not specified by the instruction.
	octasm can use 32 bits offsets in 16 bits programs if required.
	ex: '[12]'  ; 8 bits
		 '[1234]' ;16 bits in 16 bits programs
			  ;or 32bits in 32 bits programs
		'[123456]'; 32 bits

_______________________________________________________
Instructions 'call' and 'jmp' :
	Call operator '()' only can be used if the operand is a name
examples:  f1() f2( ax,bx )
operands are pushed from right to left
in others situations use 'call'
ej:   call >1 ret  #
      call far [bx]
      call far d[bx]  ;32 bits offset + 16 bit segment
      jmp far w[56]   ;16 bits offset + 16 bit segment
      call ax
      jmp 1,2        ; offset,segment not segment:offset
      call d 1,8     ;32 bits offset + 16 bit segment


_______________________________________________________
b,w,d,q  operand size is 1,2,4,8 bytes
	 write 'push w(4+5)' instead of 'push w 4+5'

far      offset+segment

db,dw,dd,dq  data declarations for numbers of 1,2,4,8 bytes
	      'db' is also used for strings

float,double,dt   data declarations for floating point numbers 4,8,10 bytes
_______________________________________________________
rb number         writes a number of bytes with zeros
	the number can be a numeric expression with forward references
_______________________________________________________
section number(0-15)
		  section is the memory espace where the code
		  will be assembled, sections are encapsulated with {}
ex:
	section 0  ;output to section 0
	{
	section 1  ;output to section 1
	}          ;output again to section 0

		  by default four sections are initialized
code      section 0
		  Instructio 'align' uses 'nop' in this section
		  and zeros in others sections
text      section 1 ;this section is used to store double cuoted strings
data      section 2
virtual   section 3 ; this section is only used to calculate offsets
		  this section is only used to calculate offsets
		  no data is writen in this section
		  like the '?' operator in some assemblers.

  examples:
  code    section 5     ;defines section 5 as code section
  text    section 5     ;now strings will be stored in section 5
			;that is also a code section
  data                  ;predefined section 2
  text                  ;set section 5
  section 4             ;defines seccion 4 like section 5 (code,strings)
  data                  ;set seccion 2
  text                  ;set seccion 4
		   sections are assembled by numerical order (0->15)
		   and are written to files in the same order
		   when assembling to ram sections can be placed anywere

_______________________________________________________
org number     sets the instruction pointer used in offsets calculations
	       default value is zero
	       this directive must be used only
	       to assemble files
	       ex: org 100h
		   #
		   inicio=5000
		   org inicio+45
		   org <1        ;org 100h

_______________________________________________________
align number   fill with zeros or 'nop' until the instruction pointer
	       is multiple of number
	       ex:
	       align 4                ok
	       align 7c00h+510        ok
	       align >1 #             error
_______________________________________________________
use16   16 bits program,32 bits instructions will be coded with prefixes
use32   32 bits program
use16_32  unreal mode program ,is the default option
	  is like use 16 but instructions with implied registers will
	  be code in the 32bits form:
	  lods  (lodsb lodsw lodsd)
	  movs stos scas cmps ins outs
	  loop

_______________________________________________________
enum
'enum inc,name1,name2...namen' this instruction can be used to
define variables ,is the same as:
   #name1 rb inc .......... #namen rb inc
_______________________________________________________
define
'define name(parameters) text' asigns text to name 'text' ends at the end of line
or when a comment ';' is found
later in the source 'name' will be replaced by 'text' using the parameters.
inside strings it must be preceded by '%' to be preprocessed.
'name' must be defined before is used and can not be redefined in nested
directories examples:

 {
 define uno 1   ; no parameters no parenthesis
	{ #uno  ;error
	define dos 2
	push uno,dos  ;push 1,2
	}
	{
	#dos   ;correct ,is another directory
	}
 }
 define f1(a)  eax=#1 edx=#2 ecx=#0 call a
 ;#1 #2 are variable parameters the maximum is #9
 ;'a' is fixed and gets the first parameter, fixed parameters are limited to 16
 ;and have the same sintax that names, first char must be a letter.
 ;#1 #2 are replaced by the rest or parameters on each iteration
 ;#0 is the iteration number begining from 0
 f1(lh2,10,20,30,40)  ;eax=10 ebx=2 ecx=0 call lh2 eax=30 ebx=40 ecx=1 call lh2
 define f2() #1  ;the first space char is ignored
 push f2(e,a,x,( , ),e,b,x)  ;push eax , ebx
 ;( , ) parenthesis are needed for the special char comma
 define a a  ;this produces a infinite loop ,since 'a' is preprocessed again and again


Example to easy declare stack
variables for subroutines:

use16
prueba(1,2,3) ret

define LOCALS   pusha enter ->1,0 virtual org >1->2 # enum 2,  ;2 bytes variables at least one is required
define PARAMS   # rb 20 enum 2,
define CODE     #RETURNS code
define RETURN   [bp+16]=ax leave popa retp RETURNS-20

#prueba{    ;'{' is required to avoid duplicate name definitions
	LOCALS x,y,z          ;locals variables
	PARAMS p1,p2,p3       ;parameters passed by calling procedure
	CODE
	w[bp+x]=10 w[bp+y]=20 w[bp+z]=30   ;inicialization of local variables
	ax=[bp+p1] add ax,[bp+y]           ;do something
	RETURN                             ;return result in ax
					   ;other registers are preserved

       }

;subroutine 'prueba',without define

#prueba{
	virtual
	org -6 #x rb 2 #y rb 2 #z rb 2
	rb 20 #p1 rb 2 #p2 rb 2 #p3 rb 2
	code
	pusha enter 6,0
	w[bp+x]=10 w[bp+y]=20 w[bp+z]=30
	ax=[bp+p1] add ax,[bp+y]
	[bp+16]=ax leave popa retp 6
	}
_______________________________________________________
Operators
defined name    this operator returs 0 if the name is a undefined symbol or -1 if not
req     name    this operator returs -1 if the name requires to be defined because is used
		in a previous instruction or 0 if not.
n1==n2  returns 0 if n1 not equal to n2 ,returns 1 if they are equal
	n1 and n2 can not be labels or not yet resolved symbols.
+       addition
-       substraction or negative sign
*       multiplication
/       division
n1 pow n2   returns n1 multiplied by itself n2 times
	ex: 2 pow 3   -> 8
	ex: 9 pow 0.5 -> 3
>>  <<  bit displacement to the right and to the left

_______________________________________________________
R       File 'R' is a program that can be used to learn assembly
	executing a few instructions and printing the contents of registers
	registers are saved in 'regs.dat'.
	use: >octasm \r instructions
	esp must remain unchanged.
	examples:
>octasm \r eax=1 ecx=4
>octasm \r shl eax,cl
>octasm \r add eax,ecx
	now eax=20
	'R' comes only with Octasm for DOS in OctaOS there is
	integrated debugger.
_______________________________________________________
OCTASM\compile
	this instructions compiles and executes previous sources
as a separate program,the purpose of this instruction is to add new
custom features to octasm at compile time.The compiled program is called
with ebp->octasm_struct and then it can setup new instructions before
compilation continues.The octaos avr assembler is one example.
Must be used at level 0 (nivel=0) ,out of '{}'.



