SjASMPlus 1.07 Documentation [31.05.2007]

SjASMPlus licensed under BSD license.

SjASMPlus is Z80 Assembly Language Cross Compiler. It is available for Win32, DOS and FreeBSD(mainly 5.x) systems. It is based on SjASM source code by Sjoerd Mastijn (http://xl2s.tk)

Special thanks to Sjoerd Mastijn, the author of SjASM.

Aprisobal - main programming, documentation, etc.

Thanks to:

And big thanks to all people, who helped me in development of the compiler!

WWW: http://sjasmplus.sourceforge.net

E-Mail: aprisobal(at)tut.by or aprisobal(at)gmail.com

Old SjASMPlus 1.06 log was removed.

You can grab last binaries and sources SourceForge project page: http://sourceforge.net/projects/sjasmplus/

Win32 package has:

DOS and FreeBSD versions has same files in their packages. Linux version you can compile using Makefile from sources package.

Usage:

sjasmplus [options] sourcefile(s)

Option flags as follows:

  --help                   Help information
  -i<path> or -I<path> or --inc=<path>
                           Include path
  --lst=<filename>         Save listing to <filename>
  --lstlab                 Enable label table in listing
  --sym=<filename>         Save symbols list to <filename>
  --exp=<filename>         Save exports to <filename> (see EXPORT pseudo-op)
 By output format (you can use it all in some time):
  --raw=<filename>         Save all output to <filename> ignoring OUTPUT pseudo-ops
  Note: use OUTPUT,LUA/ENDLUA and other pseudo-ops to control output
 Logging:
  --nologo                 Do not show startup message
  --msg=error              Show only error messages
  --msg=all                Show all messages (by default)
  --fullpath               Show full path to error file
 Other:
  --reversepop             Enable reverse POP order (as in base SjASM version)
  --dirbol                 Enable processing directives from the beginning of line
  --dos866                 Encode from Windows codepage to DOS 866 (Cyrillic)

Lines in the source file should have the following form:

Label Operator Operand Comment

All fields are optional. Lines without label should start with whitespace. Operators and operands can be inlined:

      Operator Operand:Operator Operand:Operator Operand... Comment

Comments should start with ';' or '//'. Comment blocks start with '/*' and end with '*/'.

; comment
// comment
 ld /* comment */ a,80
/*
 comment
*/
 ld /*
 but this won't be ld a,3!
 */ a,3

Labels are case-sensitive and may be of any reasonable length, that is: up to about 70 characters. Label definitions should start on the beginning of a line, but don't have to be followed by a colon ':'. Generally labels should start with a letter or a underscore ('_'), the following characters may be chosen from letters, numbers and the following special symbols: '_', '.', '!', '?', '#' and '@'. Note that the '.' has special meaning, as it is used between module names, labels and local labels. The following are all legal and distinct labels:

Kip
KIP
Kip@@
MAIN.loop?

It is possible to use mnemonics, pseudo-ops and register names as labels but it is not advised to do so. Also note that the identifiers defined with the DEFINE pseudo-op use another name space.

When there is a module definition (see module pseudo-op) all labels (except those starting with a '@') are local to that module. To use a label from outside the module use modulename.labelname, in this example: 'vdp.Cls' Labels starting with a '.' are also local to the previous non-local label.

MODULE main
Main:                           ; main.Main
        CALL SetScreen          ; SetScreen
        CALL vdp.Cls            ; vdp.Cls
.loop:                          ; main.Main.loop
        LD A,(.event)           ; main.Main.event
        CALL ProcesEvent        ; label not found: main.ProcesEvent
        DJNZ .loop              ; main.Main.loop

    MODULE vdp
@SetScreen:               ; SetScreen
.loop                     ; vdp.SetScreen.loop
        RET
Cls:                      ; vdp.Cls
.loop                     ; vdp.Cls.loop
        DJNZ .loop        ; vdp.Cls.loop
        RET

    ENDMODULE
Main.event                ; main.Main.event
    BYTE 0

Labels starting with a '@' are not touched by the label processing and used 'as-is'. See 'SetScreen' in the previous example code.

    MODULE xxx
Label      ; xxx.Label
.Local     ; xxx.Label.Local
@Label     ; Label
.Local     ; xxx.Label.Local => duplicate label error
@Label2    ; Label2
.Local     ; xxx.Label2.Local
@yyy.Local ; yyy.Local
yyy.Local  ; xxx.yyy.Local

To keep the number of used labels reasonable it is possible to use numbers as labels. These labels can only be used as labels to jump to. To jump to these labels, use the number followed by an 'F' for forward branches or a 'B' for backward branches. Temporary labels should not be used within macro's.

        ADD A,E
        JR NC,1F
        INC D
1       LD E,A
2       LD B,4
        LD A,(DE)
        OUT (152),A
        DJNZ 2B

Numeric constants should always start with a digit or $, # or %. The following formats are supported:

12     decimal
12d    decimal
0ch    hexadecimal
0xc    hexadecimal
$c     hexadecimal
#c     hexadecimal
1100b  binary
%1100  binary
14q    octal
14o    octal

Character constants are characters surrounded by single quotes. It is possible to use double quotes in some cases, but in general it is better to use single quotes. String constants are characters surrounded by double quotes. The following escape sequences are recognized:

\\ 92
\? 63
\' 39
\" 34
\A 7
\B 8
\D 127
\E 27
\F 12
\N 10
\R 13
\T 9
\V 11

    BYTE "stringconstant"  ;
    BYTE 'stringconstant'  ;with single quotes escape sequences above (\N,\T..) will not work
    LD HL,'hl'
    LD HL,"hl" ; :(
    LD A,"7"   ; :(
    LD A,'8'   ; :)
    LD A,'\E'
    LD A,'"'
    LD A,"'"

Expressions are evaluated in 32 bits in this version of SjASMPlus.

'$' represents the current program counter. '$$' represents the current page in the current slot in the real device emulation mode.

It is possible to use parenthesis '(' and ')' to override the precedence of the operators. The following operators may be used in expressions:

!     !x       logical not
~     ~x       complement
+     +x       does absolutely nothing :)
-     -x       minus
low   low x    low 8 bits of 16 bit value
high  high x   high 8 bits of 16 bit value
not   not x    logical not

*     x*y      multiplication
/     x/y      division
%     x%y      modulo
mod   x mod y  modulo

+     x+y      addition
-     x-y      subtraction

<<    x<<y     shift left
>>    x>>y     shift right signed
>>>   x>>>y    shift right unsigned
shl   x shl y  shift left
shr   x shr y  shift right signed

<?    x<?y     minimum
>?    x>?y     maximum

<     x<y      less than
>     x>y      greater than
<=    x<=y     equal or less than
>=    x>=y     equal or greater than

=     x=y      equal
==    x==y     equal
!=    x!=y     not equal

&     x&y      bitwise and
and   x and y  bitwise and

^     x^y      bitwise xor
xor   x xor y  bitwise xor

|     x|y      bitwise or
or    x or y   bitwise or

&&    x&&y     logical and

||    x||y     logical or

This version only accepts Z80 mnemonics. There are some additions to what I think is standard Z80:

    SET 4,(IX+4),C ; (aka LD C,SET 4,(IX+4)) is LD C,(IX+4) / SET 4,C / LD (IX+4),C
    RRC (IY),A     ; (aka LD A,RRC (IY+0))   is LD A,(IY)   / RRC A   / LD (IY),A

    PUSH AF,BC  ; push af / push bc
    POP  AF,BC  ; pop  af / pop  bc

    LD A,B,B,D,D,H 
   /* this is:
     LD A,B
     LD B,D
     LD D,H
   */
   ;or you can write  LD A,B:LD B,D:LD D,H

Of course the Z80 is only an 8 bit cpu, but sometimes ld hl,de would be nice. SjASMPlus now 'fakes' some instructions like that. This improves the readability of the source, but it might not be the fastest way to get the result. Also possibly some 'new' load instructions do affect the flags in ways you wouldn't expect. Anyway, here's the list:

  rl bc
  rl de
  rl hl
  rr bc
  rr de
  rr hl
  sla bc
  sla de
  sla hl
  sll bc
  sll de
  sll hl
  sli bc
  sli de
  sli hl
  sra bc
  sra de
  sra hl
  srl bc
  srl de
  srl hl

  ld bc,bc
  ld bc,de
  ld bc,hl
  ld bc,ix
  ld bc,iy
  ld bc,(hl)
  ld bc,(ix+nn)
  ld bc,(iy+nn)

  ld de,bc
  ld de,de
  ld de,hl
  ld de,ix
  ld de,iy
  ld de,(hl)
  ld de,(ix+nn)
  ld de,(iy+nn)

  ld hl,bc
  ld hl,de
  ld hl,hl
  ld hl,ix
  ld hl,iy
  ld hl,(ix+nn)
  ld hl,(iy+nn)

  ld ix,bc
  ld ix,de
  ld ix,hl
  ld ix,ix
  ld ix,iy

  ld iy,bc
  ld iy,de
  ld iy,hl
  ld iy,ix
  ld iy,iy

  ld (hl),bc
  ld (hl),de

  ld (ix+nn),bc
  ld (ix+nn),de
  ld (ix+nn),hl

  ld (iy+nn),bc
  ld (iy+nn),de
  ld (iy+nn),hl

  ldi bc,(hl)
  ldi bc,(ix+nn)
  ldi bc,(iy+nn)

  ldi de,(hl)
  ldi de,(ix+nn)
  ldi de,(iy+nn)

  ldi hl,(ix+nn)
  ldi hl,(iy+nn)

  ldi (hl),bc
  ldi (hl),de

  ldi (ix+nn),bc
  ldi (ix+nn),de
  ldi (ix+nn),hl

  ldi (iy+nn),bc
  ldi (iy+nn),de
  ldi (iy+nn),hl

  ldi a,(bc)
  ldi a,(de)
  ldi a,(hl)
  ldi b,(hl)
  ldi c,(hl)
  ldi d,(hl)
  ldi e,(hl)
  ldi h,(hl)
  ldi l,(hl)
  ldi a,(ix+nn)
  ldi b,(ix+nn)
  ldi c,(ix+nn)
  ldi d,(ix+nn)
  ldi e,(ix+nn)
  ldi h,(ix+nn)
  ldi l,(ix+nn)
  ldi a,(iy+nn)
  ldi b,(iy+nn)
  ldi c,(iy+nn)
  ldi d,(iy+nn)
  ldi e,(iy+nn)
  ldi h,(iy+nn)
  ldi l,(iy+nn)

  ldd a,(bc)
  ldd a,(de)
  ldd a,(hl)
  ldd b,(hl)
  ldd c,(hl)
  ldd d,(hl)
  ldd e,(hl)
  ldd h,(hl)
  ldd l,(hl)
  ldd a,(ix+nn)
  ldd b,(ix+nn)
  ldd c,(ix+nn)
  ldd d,(ix+nn)
  ldd e,(ix+nn)
  ldd h,(ix+nn)
  ldd l,(ix+nn)
  ldd a,(iy+nn)
  ldd b,(iy+nn)
  ldd c,(iy+nn)
  ldd d,(iy+nn)
  ldd e,(iy+nn)
  ldd h,(iy+nn)
  ldd l,(iy+nn)

  ldi (bc),a
  ldi (de),a
  ldi (hl),a
  ldi (hl),b
  ldi (hl),c
  ldi (hl),d
  ldi (hl),e
  ldi (hl),h
  ldi (hl),l
  ldi (ix+nn),a
  ldi (ix+nn),b
  ldi (ix+nn),c
  ldi (ix+nn),d
  ldi (ix+nn),e
  ldi (ix+nn),h
  ldi (ix+nn),l
  ldi (iy+nn),a
  ldi (iy+nn),b
  ldi (iy+nn),c
  ldi (iy+nn),d
  ldi (iy+nn),e
  ldi (iy+nn),h
  ldi (iy+nn),l
   
  ldd (bc),a
  ldd (de),a
  ldd (hl),a
  ldd (hl),b
  ldd (hl),c
  ldd (hl),d
  ldd (hl),e
  ldd (hl),h
  ldd (hl),l
  ldd (ix+nn),a
  ldd (ix+nn),b
  ldd (ix+nn),c
  ldd (ix+nn),d
  ldd (ix+nn),e
  ldd (ix+nn),h
  ldd (ix+nn),l
  ldd (iy+nn),a
  ldd (iy+nn),b
  ldd (iy+nn),c
  ldd (iy+nn),d
  ldd (iy+nn),e
  ldd (iy+nn),h
  ldd (iy+nn),l

  ldi (hl),nn
  ldi (ix+nn),nn
  ldi (iy+nn),nn

  ldd (hl),nn
  ldd (ix+nn),nn
  ldd (iy+nn),nn

  sub hl,bc
  sub hl,de
  sub hl,hl
  sub hl,sp

ldi increases the data pointer after the data access, so LDI A,(HL) is the same as LD A,(HL):INC HL. likewise, LDD A,(DE) is LD A,(DE):DEC DE.

To enable this mode you must use pseudo-op DEVICE.

In this mode the compiler compiling program to virtual memory (as at MSX's WB-ASS2, ZX-Spectrum's GENS, ZEUS, ALASM etc). After this all you can use new pseudo-ops as SAVEBIN, SAVEHOB, SAVETRD, PAGE, SLOT, LABELSLIST and use special functions in Lua scripts.

    DEVICE ZXSPECTRUM128
    ;in this device, SLOT 3 enables to current by default.    

    ORG 32768
StartProg:
    JP $

    DEVICE NONE
    ;do something, if you don't want to corrupt virtual
    ;memory with other code, for example, loader of code.
    ;...code...

    ;return to our virtual device:
    DEVICE ZXSPECTRUM128

    SAVESNA "snapshotname.sna",StartProg
 

Predefined devices:

If you want to see other devices you must write to us. See Feedback chapter.

SjASMPlus has predefined defines.

     .SOMEPSEUDOOP ;or 
     SOMEPSEUDOOP  ;or
     somepseudoop

It may be useful to assemble a part or not based on a certain condition.

The MACRO pseudo-op defines a macro. It should be followed by the name of the macro, optionally followed by the parameters. The following lines will be stored as the macro-body until an ENDM pseudo-op is encountered. Macro's have to be defined before their use.

  MACRO ADD_HL_A
    ADD A,L
    JR NC,.hup
    INC H
.hup
    LD L,A
  ENDM

Labels in a macro starting with a dot are local to each macro expansion.

  MACRO WAVEOUT reg, data
    LD A,reg
    OUT (7EH),A
    LD A,data
    OUT (7FH),A
  ENDM
; this macro will make
  WAVEOUT 2,17
; expand to:
  LD A,2
  OUT (7EH),A
  LD A,17
  OUT (7FH),A

    MACRO LOOP
      IF $-.lus<127
        DJNZ .lus
      ELSE
        DEC B
        JP NZ,.lus
      ENDIF
    ENDM

Main
.lus
    CALL DoALot
    LOOP
; This will expand to:
Main
.lus                  ; Main.lus
    CALL DoALot
    DJNZ .lus         ; Main.lus

Angle brackets can be used when the arguments contain commas.

    MACRO UseLess data
      DB data
    ENDM

    UseLess <10,12,13,0>
; expands to:
    DB 10,12,13,0

; use '!' to include '!' and '>' in those strings.

  UseLess <5, 6 !> 3>
; expands to:
  DB 5, 6 > 3

  UseLess <"Kip!!",3>
; expands to:
  DB "Kip!",3

Structures can be used to define data structures in memory more easily. The name of the structure is set to the total size of the structure.

A structure definition starts with: STRUCT <name>,[<initial offset>] and ends with ENDS. Structure definitions are local to the current module, but, as with labels, '@' can be used to override this.

Lines between STRUCT and ENDS should have the following format:

membername pseudo-operation operands

All fields are optional. Lines without label should start with whitespace.

Between the STRUCT and ENDS pseudo-instructions the following instructions can be used:

Why is scripting engine as Lua embedded to the compiler? Answer is simple: It need to add extra features by users. And to whole other Lua is enough small, fast and powerful scripting engine.

You must use LUA and ENDLUA pseudo-ops.

    LUA
        print "Hello World!"
    ENDLUA

From Lua you can control some variables and use functions of the compiler. Complete list:

lpack.c

a Lua library for packing and unpacking binary data

by Luiz Henrique de Figueiredo <lhf(at)tecgraf.puc-rio.br>

The library adds two functions to the string library: string.pack and string.unpack.

pack is called as follows: string.pack(F,x1,x2,...), where F is a string describing how the values x1, x2, ... are to be interpreted and formatted. Each letter in the format string F consumes one of the given values. Only values of type number or string are accepted. pack returns a (binary) string containing the values packed as described in F. The letter codes understood by pack are listed in lpack.c (they are inspired by Perl's codes but are not the same). Numbers following letter codes in F indicate repetitions.

unpack is called as follows: string.unpack(s,F,[init]), where s is a (binary) string containing data packed as if by pack, F is a format string describing what is to be read from s, and the optional init marks where in s to begin reading the values. unpack returns one value per letter in F until F or s is exhausted (the letters codes are the same as for pack, except that numbers following 'A' are interpreted as the number of characters to read into the string, not as repetitions).

The first value returned by unpack is the next unread position in s, which can be used as the init position in a subsequent call to unpack. This allows you to unpack values in a loop or in several steps. If the position returned by unpack is beyond the end of s, then s has been exhausted; any calls to unpack starting beyond the end of s will always return nil values.

List of types for F string: