====== Assembler syntax ======

==== Overview ====

The assembler is designed to cope with many common formats, but in practice most programs from books will need modifying. By default the program is assembled to address $4000; change this with the ORG directive.

This is a two-pass assembler, meaning the source code can reference labels that are not defined until later in the program.

Once successfully assembled the program will be listed in the Disassembly panel. If a special label "start" was defined it will be listed from here and be ready to start. Otherwise $4000 is the default address.

=== Comments ===

Everything on a line from a **;** (semicolon) onward is treated as a comment and ignored by the assembler. For compatibility a ***** (star) symbol can also be used.

=== Numeric constants ===

Numbers are in decimal by default. Specify hexadecimal values by preceding the digits by the **$** symbol. Also the C standard **0x** format is recognised. For binary precede the digits by the **%** symbol. Positive and negative numbers are preceded by the **+** and **-** symbols respectively. Constants and labels can be chained together with simple arithmetic (just plus and minus).

  const asciiZero=48, asciiNine=+57, asciiEight=$38 
  const asciiSeven=0x37, asciiOne=%00110001, minusNineteen=-$13
  const PIA=$FF20
  
  start:  
    lda #'9
    lda #asciiZero
    lda #asciiNine
    lda #asciiEight
    lda #asciiSeven
    lda #asciiOne
    lda #minusNineteen
    ldb PIA+1

=== Labels ===

Labels are used to refer to constants and memory addresses. A label starts with a letter and may continue with letters, digits, or the **_** (underscore) character. There is no limit to their length, though it's best to keep them fairly short. They are not case sensitive.

When a label is defined at the start of a line, follow it with a **:** (colon). Otherwise, make sure the label is at the very start of the line with no whitespace. There are no reserved words, but avoid confusion by not using 6809 instructions or registers.

There is a special label called 'START': define this and your program will execute and be listed from here.

  const txtRAM=$400
  
  vidRAM EQU $600
  
  start:
    jsr vidInit
    line_buffer: rmb $20
  
  vidInit:
    ldx #txtRAM
    ldy #vidRam
    ldu #Line_Buffer
    rts
 
=== Directives ===

A directive does not assemble to a machine language instruction, but either defines data or specifies the way in which the assembler should process the instructions and data. They are not case sensitive.

== ORG <address> ==

Sets the **origin** of the code. Instructions and data following this directive in the source file will be assembled at that address onward in memory. The default value is **$4000** .

  start:
    jsr libRoutine01     ;  jsr $f000
  ; ...
  org $F000
  
  libRoutine01:
    pshs d,x
    
== END ==

Signals the end of the source file. There may be text following but it will not be assembled.

  finish:
    clra
    rts    
  
    ; Some reminders here ...
    
    end
    
    More reminders here ...

== RMB <word> ==
== DS <word> ==

Reserve memory bytes (or define space). The assembler reserves space for **<num>** bytes of memory without defining their values.

    lineInput: rmb 33     ; 33 bytes for a line input buffer
    textArea:  ds $0200   ; 512 bytes for a text screen 
    
== CONST <label> = <value> ==    

Defines a comma-separated list of numeric constant assignments. This is preferred to the traditional method of using EQUates.
    
    const bufferSize=100
    const min=10, max=bufferSize+1
    
  start:
    ldb #min
    leax buffer,pcr
    cmpb #max
  ; ...
  buffer:   rmb bufferSize
  
== VAR <num> , <label> ==

Define space for one or more variables. The first parameter is the size of the variable(s) in bytes (usually one or two), followed by a comma-separated list of labels. This is preferred to the traditional method of using FCB or RMB directives.

  var 1, xPos, yPos
  var 2, bitmapSize, bitmapAddress
  bitmap1:  dw %1111111111111111, %1000000000000001, %1000000000000001, %1111111111111111
  
  start:
    clra
    sta xPos
    stb yPos
    ldx #8
    stx bitmapSize
    leay bitmap1,pcr
    sty bitmapAddress
  
== EQU ==
== = ==

Equate. Set a label equal to a constant. Deprecated here (use **CONST**), used for compatibility. The label in legacy code normally will not have a colon so should be at the start of the line with no leading spaces.

  graphicsStart EQU $1F00
  xPos = 40
  yPos = 25
  
  start:
    lda #xPos
    ldb #yPos
    ldx #graphicsStart
    jsr setCursor
  
  setCursor:
  
  
== SETDP <byte> ==
== DIRECT <byte> ==

Assume the DP register contains the value **<byte>**. It does not assemble any instructions to set this value however; this must be done explicitly. From now on memory accesses within this page will be encoded using Direct mode rather than Extended (unless forced with the **>** operator). When explicitly using Direct mode (using **<**) accesses outside this range will be flagged as errors.

  start:
    lda #$40
    tfr a,dp
    setdp $40
    lda $4000    ; assembled in Direct mode
    rts
    
    
== FILL <byte>, <word> ==

Tells the assembler to fill the next **<word>** bytes of memory with the value **<byte>**.

  start:
    leax blanks,pcr   ; point to zero-terminated string of 80 spaces
    
  blanks:
    fill $20, 80
    db 0

== DB <byte> | <string> ==
== FCB ==
== FCC ==
== .BYTE ==

Define Byte, Format Constant Byte, Format Constant Character, & .Byte are identical. They take as an argument a comma-separated list of values, and instruct the assembler to include as bytes in the code. Numeric values, labels, or strings can be mixed. Strings should be in double quotes, though single quotes are accepted.

  start:
  length:  db 5
  chars:   fcb $38, $35, $3C, $3C, $3F
  text:    fcc "HELLO",0
  empty:   .byte 5, 10, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0

== DW <byte> | <string> ==
== FDB ==
== .WORD ==

Define Word, Format Double Byte, & .Word are identical. Similar to DB etc., they take as an argument a comma-separated list of values, and instruct the assembler to include as 16-bit words in the code. 

  start:
    const false=-1, limit=1000
    ldd #false
    ldx #limit
  bitmap: 
    dw %1111111111111111, %1000000000000001, %1000000000000001, %1111111111111111