X-Assembler version 2.2

INTRODUCTION  USAGE  SYNTAX  FAQ  BACK

CHANGES

Version 2.2

• invalid absolute CPX and CPY op-codes bug fixed
• branch addressing mode not checking bug fixed
• ICL in last line bug fixed
• OPT H-H+ bug fixed
• first ORG * bug fixed
• origin setting not required until not used
• Unix ($0a), Macintosh ($0d) and Atari ($9b) EOLs allowed in source
• value of 'true' changed to 1
• setting environment variables on error option
• assembling only if source newer than object option
• op-code extracting
• line repeating
• instructions pairing
• conditional repeat and skip pseudo commands
• (),0+ and (),0- pseudo addressing modes

Version 2.0

• truncating name of object bug fixed
• EQU and DTA forward reference bugs fixed
• hex number recognizing bug fixed
• now .OBX is default extension for Atari executables
• assembling options (switches and OPT directive)
• listing generation
• label table generation
• conditional assembling
• user errors
• warnings
• improved headers generation
• improved expressions - 19 operators and brackets, 32-bit arithmetic
• improved signed numbers
• 6 new pseudo commands (memory-to-memory move)
• 8 pseudo addressing modes
• indirect conditional jumps
• Atari floating-point numbers generation
• improved INS: inserting specified part of file

Version 1.2

• first release

INTRODUCTION  USAGE  SYNTAX  FAQ  BACK

System requirements

• a PC compatible computer with 386 or better CPU
• a MS-DOS compatible OS
• a numeric coprocessor for generating sinus tables. Your CPU probably has a built-in coprocessor.

Creating a source program

Converting Quick Assembler files

Assembling a source program

XASM source [options]

Optional options are:

/c

Enable listing false conditionals.
By default lines skipped because of false condition are not listed.

/e

Enable setting environment variables when error occurs.
With this option, X-Asm sets two environment variables: ERRFILE and ERRLINE. They may be used in a batch file to locate error and set editor on it. For example, in my batch file I use such construction:

XASM %1 /e

IF NOT ERRORLEVEL 1 GOTO ok

NCE +%ERRLINE% %ERRFILE%

NCE stands for Norton Classic Editor.

If there was no error, variables point at last warning. If no warning occured, they are removed from the environment.

/i

Disable listing included source.
Only main source file will be listed.

/l[:fname]

Enable generating listing. If no fname given, listing is written to source.lst.

/n

Check source and object modification times and assemble only if source is newer than object file. X-Asm does NOT check included nor inserted files but only main source, so be careful with this option.

/o:fname

Specify object name. Default is source.obx.

/s

Disable converting spaces to tabs in listing. Using tabs makes listing file shorter.
Tab stops are assumed to be every 8 characters.

/t[:fname]

List label table. If no fname given, table is written at the end of listing.

INTRODUCTION  USAGE  SYNTAX  FAQ  BACK

• empty lines - ignored, of course
• comments - ignored, too
• statements - not ignored :-)

Expressions  Statements

Numbers

Expressions  Statements

• label field
• operation field
• one or two operand fields
• comment field

• Defining a label.
  Label is a symbol representing an integer of range -$ffff..$ffff.
  Name of a label can contain letters, digits and underscores (_). Digit can't be label's first character. Name of a label can be as long as you want and all the characters are meaningful. In Quick Assembler only 6 leading characters were recognized and some programs may not compile under X-Asm for this reason.
  Defining a label without using EQU makes it equal to current value of the origin counter.
  Label can't be redefined.

• Repeating the line.
  Repeating means assembling single line several times as if there were several identical lines. Note it is not just duplicating bytes written to object.
  Repeat count, which can be any valid expression, has to be preceded with a colon.
  Examples:

  :4 asl @
  
  :2 dta a(*)
  
  

  In the latter example each DTA has different operand value.
  If repeat count equals zero, remaining part of line is not assembled. This allows conditional assembly on single line to be more compact.

 adc:sta $80

 adc $80

 sta $80

1. 6502 command
   One of 56 well known processor commands.
   
   
2. compiler directive
   One of the following:

   EQU - assign a value of expression to the label

   Note that label represents a number, not a text macro.
   Examples:

   five equ 5
   
   here equ *
   
   

   OPT - set assembling options

   Currently there are two options: listing generating and headers generating. You can turn any of these on or off.
   Default (if no OPT specified) is opt l+h+.
   Examples:

    opt l-    listing off
   
    opt h-    headers off
   
    opt l+h-  listing on, headers off
   
   

   ORG - set new origin counter

   You can set some options applied to new header (if headers are on):

   • a: tells X-Asm to always make a header, even it is unnecessary, like in ORG *.
   • f: works same as a:, but additionally tells to generate a $ff,$ff prefix before header. X-Asm adds it to the first header in file by default, so use this option only if you want the $ff's somewhere inside.
     

   Examples:

    org $600
   
    org f:$700
   
   table org *+100
   
   

   In the latter example table points to 100 bytes of uninitialized data (note label is assigned to * before ORG directive is executed).

   DTA - define data

   There are various data types:

   • numbers
     • bytes: b(200)
     • words: a(10000)
     • low bytes of words: l(511) defines byte 255
     • high bytes of words: h(511) defines byte 1
       You may enter many expressions in parentheses and combine different types of data in single line, separating things with commas.
       You may also define a sinus table. Syntax is:
       sin(centre,amp,size,first,last)
       where:
       • centre is a number which is added to every sinus value
       • amp is the amplitude of sinus
       • size is the period of sinus
       • first,last define range of values in the table. They are optional. Default are 0,size-1.
       Example: dta a(sin(0,1000,256,0,63)) defines table of 64 words representing a quarter of sinus with amplitude of 1000.

     • real numbers: r(-1.23456e12)
       Real numbers are written in 6-byte Atari Floating-Point format. You can't combine reals with operators, as you can integers.

   • text strings
     • ASCII strings: c'Text' or c"Text"
     • ANTIC strings: d'Text' or d"Text"
     A character string consists of any of characters surrounded by quotation marks. Within a string, a single quotation mark character is represented by two succesive quotation marks.
     Placing a * character after a string inverts high bit in every byte of string.

   Examples of DTA:

   
    dta b(2,5),a(1000,-1),l(12345,sin(0,127,256))
   
    dta d"ANTIC"*,c'It''s a string',b(155)
   
   

   ICL - include another source file

   Specifies another file to be included in the assembly as if the contests of the referenced file appeared in place of the ICL statement. The included file may contain other ICL statements. The .ASX extension is added if none given.

   Examples:

   
    icl 'macros.asx'
   
    icl 'c:\atari\xasm\fileio'
   
   

   END - end assembling file

   Remaining part of the file is not assembled. If this statement does not occur, assembler stops assembling when encounters end of file.
   Example:

   
    end
   
   

   INS - insert contents of file

   Copies every byte of specified file into object file and moves origin counter, as if these bytes were defined with DTA.
   You may specify range of inserted file. Syntax is:

   
    ins 'file'[,offset[,length]]
   
   

   First byte in file has offset 0.
   If offset is negative, it is counted from the end of file.
   Examples:

   
    ins 'picture.raw'
   
    ins 'file',-256   insert last 256 bytes of file
   
    ins 'file',10,10  insert bytes 10..19 of file
   
   

   RUN - generate run address

   The Atari executable program should have run address specified. A program may be loaded in many areas of memory and started from any address.

    run addr
   
   

   is equivalent to:

    org $2e0
   
    dta a(addr)
   
   

   Examples:

    run start
   
    run program
   
   

   INI - generate init address

   The Atari executable program may have some routines which are executed during loading process. There may be many init blocks in one file.
   Examples:

    ini init
   
    ini showpic
   
   

   ERT - generate error if expression is true

   Examples:

    ert *>$c000
   
    ert len1>$ff||len2>$ff
   
   

   IFT - assemble if expression is true
   ELS - else
   EIF - end if
   

   With these directives you can construct fragments which are assembled when a condition is met. Conditional constructions can be nested.
   Example:

   noscr equ 1
   
    ift noscr
   
    lda #0
   
    els
   
    lda #$22
   
    eif
   
    sta $22f
   
   

   Above example can be rewritten using line repeating feature:

   noscr equ 1
   
   :noscr<>0 lda #0
   
   :noscr=0 lda #$22
   
    sta $22f
   
   

3. pseudo-command
   It is something like built-in macro. Note that it is not an illegal instruction and works on typical 6502.

   ADD - addition without carry

   If you ever programmed 6502, you must have noticed that you had to use a CLC before ADC for every simple addition.
   X-Asm can do it for you. ADD replaces two instructions: CLC and ADC.

   SUB - subtraction

   It is SEC and SBC.

   RCC, RCS, REQ, RMI, RNE, RPL, RVC, RVS - conditional repeat

   They are branches to the previous instruction. They take no operand, because the branch target is the address of previously assembled instruction.
   Example:

    ldx #0
   
    mva:rne $500,x $600,x+
   
   

   The example code copies memory $500-$5ff to $600-$6ff. With standard 6502 commands only it would be:

    ldx #0
   
   loop lda $500,x
   
    sta $600,x
   
    inx
   
    bne loop
   
   

   SCC, SCS, SEQ, SMI, SNE, SPL, SVC, SVS - conditional skip

   They are branches over the next instructions. No operand is required, because the target is the address of instruction following the next instruction.
   Example:

    lda #40
   
    add:sta $80
   
    scc:inc $81
   
   

   In the above example word variable $80 is incremented by 40.
   Nor conditional repeat nor skip pseudo-commands require operand, thus they can be paired with any other command.

   JCC, JCS, JEQ, JMI, JNE, JPL, JVC, JVS - conditional jumps

   They are a kind of 'long' branches. While standard branches (BNE, BEQ) have range of -128..+127, these jumps have range of all 64 kB.
   Example:

    jne dest
   
   

   is equivalent to:

    seq:jmp dest
   
   

   INW - increment word

   It is a 16-bit memory increment command.
   Example:

    inw dest
   
   

   is equivalent to:

    inc dest
   
    sne:inc dest+1
   
   

   MVA, MVX, MVY - move byte using accumulator, X or Y

   Any of these pseudo-commands requires two operands and substitutes two commands:

    mva source dest = lda source : sta dest
   
    mvx source dest = ldx source : stx dest
   
    mvy source dest = ldy source : sty dest
   
   

   MWA, MWX, MWY - move word using accumulator, X or Y

   They also require two operands and are combinations of two MV*'s: one to move low byte, and the other to move high byte.
   You can't use indirect nor pseudo addressing modes with MW*. Destination must be absolute address (indexed or not).
   When source is also absolute, a MW* SOURCE DEST will be:

    mv* source   dest
   
    mv* source+1 dest+1
   
   

   When source is immediate, a MW* #IMMED DEST will be:

    mv* <immed dest
   
    mv* >immed dest+1
   
   

   When <immed equals >immed and immed is not forward-referenced, X-Asm uses optimization:

    mv* <immed dest
   
    st* dest+1
   
   

 nop

 asl @

 lda >$1234	assembles to lda #$12

 lda $100,x

 lda a:0	generates 16-bit address

 jmp ($0a)

 lda ($80),y

 cmd a,x+    =  cmd a,x   : inx

 cmd a,x-    =  cmd a,x   : dex

 cmd a,y+    =  cmd a,y   : iny

 cmd a,y-    =  cmd a,y   : dey

 cmd (z),y+  =  cmd (z),y : iny

 cmd (z),y-  =  cmd (z),y : dey

 cmd (z,0)   =  ldx #0    : cmd (z,x)

 cmd (z),0   =  ldy #0    : cmd (z),y

 cmd (z),0+  =  ldy #0    : cmd (z),y : iny

 cmd (z),0-  =  ldy #0    : cmd (z),y : dey

INTRODUCTION  USAGE  SYNTAX  FAQ  BACK

• Q: Why does X-Asm ignore +2 in following line?

  label equ 1 +2
  
  

  A: X-Asm treats space as operand terminator. Remaining part of line is a comment. You should write 1+2 without any spaces.

• Q: Why does lda #<table not work?

  A: < and > represent addressing modes rather than LOW and HIGH operators.
  You specify lda <table, not lda #<table like in most 6502 assemblers.

• Q: What's wrong with asl a ?

  A: You should use @ for accumulator addressing mode.

• Q: What's wrong in following line?

  label: lda #0
  
  

  A: Label definition can not include a colon.

• Q: I wrote end start, where start points to program beginning, but program seems not to start there. Why?

  A: You should have explicit run address specified. Use run start directive. end takes no operand.

• Q: Why this construction does not work:

  three equ one+two
  
  two   equ one+one
  
  one   equ 1
  
  

  while this does:

  
  two   equ one+one
  
  one   equ 1
  
  

  A: X-Asm reads source twice (in pass 1 and pass 2) from the beginning until the end.
  This allows forward references, but not too complex.
  Keep in mind that assembler should know all the values in second pass.

  Example:

  two   equ one+one   This value is known in 2nd pass only
  
  one   equ 1         This value is known as early as in 1st pass
  
  

  These values can be fixed in two passes.
  If you insert following statement as first line:

  three equ one+two
  
  

  X-Asm will generate an error because it can't fix the value of three in second pass.

• Q: X-Asm displayed single error while assembling my program. When I fixed it, another error appeared. Why?

  A: X-Asm displays only first error.
  When you were assembling for the first time, both errors might exist, but X-Asm stopped assembling on the first one.

• If you have other questions/problems, write to me.