Quick summary of the Secal instruction set and syntax
           =====================================================

The Secal compiler recognises the followings:

- Secal instructions
- Assembly
    (Standard Motorola 68000-68020 assembly instructions, closed by a
    semicolon, with the Secal syntax of effective addressing (see later).
    Also the operand separator have been changed to a comma (",") in some
    special cases, where standard assembly uses something else)
- Labels
    (An identifier followed by a colon, for marking a program location)
- Assignments
    (In the form of "ea := expr ;")

>-------------------------------------------------------------------------<

                            Secal instructions
                            ~~~~~~~~~~~~~~~~~~
Legend:
  <xx>       = to be substituted
  [xx]       = optional
  xx1, xx2   = repeatable
  <...>      = multiple instructions
  ...        = multiple macro parameters
  xx | xx    = one or the other
  ea         = effective address

Conditional execution:
  IF <cond> THEN <...> [ELIF <cond> THEN <...>] [ELSE <...>] ;

Loops:
  REPEAT <...> UNTIL <cond> ;
  WHILE <cond> DO <...> ;
  FOR <counter> := <start> UPTO | DOWNTO | TO <stop> [STEP <step>] DO <...> ;

Macros:
  DEF <id> [(<par1>, <par2>, ...)] [= <text>] ;
  PATTERN <id> [(<par1>, <par2>, ...)] IS <...> ENDP ;

File inclusion:
  INCLUDE "<filename>" ;
  INCBIN "<filename>" [, <offset>, <size>] ;
  INCOBJ "<filename>" ;
  INCLIB "<filename>" ;

Section control:
  SECTION <name> [, <type>] ;
  SECTION <name> [, <type_a>, <org> [, <load>]] ;
  CODE ; CODE_C ; CODE_F ; DATA ; DATA_C ; DATA_F ; BSS ; BSS_C ; BSS_F ;
  ORG [<address>] ;

Direct code operations:
  DC [. <size>] <val1>, <val2> ;
  DS [. <size>] <count> ;
  DCB [. <size>] <repcount> [, <val1>, <val2>] ;
  BLK [. <size>] <count> [, <val1>, <val2>] ;
  ALIGN <value> [, <offset>] ;

Compiler variable:
  SET <id> = <value> ;

Variables, structures:
  OBJ | DOBJ [<id1>, <id2>] : <type> = <initval> ;
  STRUCT | UNION <id> IS <...> ;

Control transfer:
  GO | CALL | GO_cc <address> ;

Stack operations:
  PUSH [. <size>] <ea1 | reglist1>, <ea2 | reglist2> ;
  POP <ea1 | reglist1>, <ea2 | reglist2> ;

Parallel assignments:
  SAFE <...> ;

External interface:
  IMPORT [<extname> AS] <id1>, <id2> : <type> ;
  EXPORT <id1>, <id2> [AS <extname>] ;

Compiler options:
  OPT <keyword> = <text> ;


                           Effective addressing
                           ~~~~~~~~~~~~~~~~~~~~
M68000
        Dn
        An
        [An]
        [An+]
        [-An]
        [An+d16]
        [An+Rn.SIZE+d8]
        [PC+d16]
        [PC+Rn.SIZE+d8]
        [addr.w]
        [addr.l]
        const

        pc, sr, ccr, ssp, usp

M68020+
        [An+Rn.SIZE*SCALE+d8]
        [bd+An+Rn.SIZE*SCALE]
        [[bd+An]+Rn.SIZE*SCALE+od]
        [[bd+An+Rn.SIZE*SCALE]+od]
        [PC+Rn.SIZE*SCALE+d8]
        [bd+PC+Rn.SIZE*SCALE]
        [[bd+PC]+Rn.SIZE*SCALE+od]
        [[bd+PC+Rn.SIZE*SCALE]+od]

        Dx:Dy
        sfc, dfc, vbr, cacr, caar, msp, isp

   (Note that bd and od are not supported together, and their sizes must be
   word. ZAn and ZPC can be used to indicate a suppressed base register.)


                                   Types
                                   ~~~~~
        byte    .b
        ubyte   .ub
        word    .w
        uword   .uw
        long    .l
        ulong   .ul

  In the place of these standard types, a new structure/union definition can
  also be recognised, introduced with the STRUCT or UNION keyword, similar to
  the STRUCT and UNION instructions.


                                 Operators
                                 ~~~~~~~~~
        +, -, /, *
        and=&, or=|, xor
        lsl=<<, lsr=>>, asl, asr, rol, ror, roxl, roxr
        bchg, bclr, bset
        inv=~, -

        orif=||, andif=&&
        not=!

>-------------------------------------------------------------------------<

                                 Secal.lib
                                 ~~~~~~~~~
String functions:
~~~~~~~~~~~~~~~~~
strlen( str )                                   -> d0.l=length, a0=stringend
strcopy( source, dest )                         -> a0=destend
strcopym( source, dest, max )                   -> a0=destend
strdiff( source, dest )                         -> d0=firstdiff/0
strdiffi( source, dest )                        -> d0=firstdiff/0
strcat( source, dest )                          -> a0=destend
strcatm( source, dest, max )                    -> a0=destend

>-------------------------------------------------------------------------<

                                 Extension
                                 ~~~~~~~~~

General functions:
~~~~~~~~~~~~~~~~~~
  x_Init                                                -> d0=success
  x_Done

Audio functions:
~~~~~~~~~~~~~~~~
  x_AudioStart( chanmask )                              -> d0=success

  x_Mus_New( modul, chanmask )                          -> a0=mus/0
  x_Mus_Load( filename, chanmask )                      -> a0=mus/0
  x_Mus_Dispose( mus )
  x_Mus_Play( mus, pos )
  x_Mus_Stop( mus)
  x_Mus_Continue( mus )
  x_Mus_Modify( mus, pos, volume )

  x_PlaySound( start, length, repstart, replen, channel, period, volume )
  x_StopSound( channel )
  x_ModifySound( channel, period, volume )
  x_PlaySoundQ( pri, start, length, repstart, replen, channel, period, volume )

  x_SetFilter( state )

Graphics variables:
~~~~~~~~~~~~~~~~~~~
  x_VBlankCode : ulong
  x_VBlankCnt : ulong

Graphics functions:
~~~~~~~~~~~~~~~~~~~
  x_GraphicsStart

  x_Scr_Open( mode, width, height, depth, title, colors, taglist )   -> a0=scr/0
  x_Scr_Close( scr )
  x_Scr_AddBmp( scr )                                   -> d0=success
  x_Scr_ActivateBmp( scr, index, xoffset, yoffset )
  x_Scr_GetBmp( scr, index )                            -> a0=bmp
  x_Scr_LoadRGB8( scr, colors, start, count )

  x_RGB8Intensity( source, count, dest, intensity, target )

  x_Bmp_Alloc( width, height, depth )                   -> a0=bmp/0
  x_Bmp_Free( bmp )

  x_Ani_New( animdata, looping )                        -> a0=ani/0, a1=rbg8, d0=numcolors
  x_Ani_Load( filename, looping )                       -> a0=ani/0, a1=rbg8, d0=numcolors
  x_Ani_Dispose( ani )
  x_Ani_DoFrame( ani, bmp, x, y, scr )                  -> d0=duration

  x_Spr_NewGrp( sprarray, sprcnt, flags, depth )        -> a0=sgrp/0
  x_Spr_DisposeGrp( sgrp )
  x_Spr_Draw( sgrp, destbmp, xoffset, yoffset )
  x_Spr_Restore( sgrp, destbmp, bgnd, bgndwidth )
  x_Spr_PrepGfx( sgfxarray, sgrp, count )               -> d0=success
  x_Spr_UnPrepGfx( sgfxarray, count )
  x_Spr_ChngGfx( sgfx, spr, nextframe )
  x_Spr_CollChk( mode, spr1, spr2 )                     -> d0=collission
  x_Spr_Sort( sgrp, customsort )
  x_Spr_CutMsk( spr, data, x, y, width, height )
  x_Spr_GrpCutMsk( sgrp, data, x, y, width, height )
  x_Spr_AddBgBuf( spr, size )                           -> d0=success
  x_Spr_GrpAddBgBuf( sgrp )                             -> d0=success
  x_Spr_AddMskBuf( spr, size )                          -> d0=success
  x_Spr_GrpAddMskBuf( sgrp )                            -> d0=success

  x_MakeMask( source, dest, width, height, depth, mplane )
  x_ClrBlit( dst, dstw, width, height )
  x_MoveBlit( src, srcw, dst, dstw, width, height )

Miscellaneous functions:
~~~~~~~~~~~~~~~~~~~~~~~~
  x_Randomize
  x_Rnd                                                 -> d0=random

  x_LoadFile( filename, memflags )                      -> a0=loadedfile, d0.l=size
  x_UnLoadFile( loadedfile )

  x_SetTaskPri( task, pri )                             -> d0=oldpri
  x_RevertTaskPri
  x_EasyRequest( window, titletxt, bodytxt, gadgettxt ) -> d0=num

General system functions callable without a library base:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  x_DisplayBeep( scr )
  x_Delay( ticks )
  x_OwnBlitter
  x_DisownBlitter
  x_WaitBlit
  x_WaitTOF
  x_VBeamPos                                            -> d0.l=beampos
  x_WBenchToFront                                       -> d0=success
  x_WBenchToBack                                        -> d0=success
  x_OpenWorkbench                                       -> d0=success
  x_CloseWorkbench                                      -> d0=success

>-------------------------------------------------------------------------<