dox/urasm.txt

   1 unsorted notes on UrAsm commands and quirks
   2
   3
   4 EQU vs '='
   5 ==========
   6 EQU defines unique label (which cannot be redefined)
   7
   8 '=' assigns value to label (creating new label if necessary, or
   9 redefining the existing one)
  10
  11
  12 labels
  13 ======
  14 if label starts with '@@', it doesn't reset local labels.
  15
  16 if label starts with '.', it is a local label; all local
  17 labels will be forgotten after new global label.
  18
  19
  20 displaying expressions while assembling
  21 =======================================
  22
  23 DISPLAY ...
  24   pring args on the second pass; can print strings and perform math
  25 DISPLAY0 ...
  26   pring args on the first pass; can print strings and perform math
  27 DISPLAYA ...
  28   pring args on each pass; can print strings and perform math
  29 DISPHEX ...
  30 DISPHEX0 ...
  31 DISPHEXA ...
  32   the same as "DISPLAY*", but prins all numbers as hex values
  33
  34
  35 define output format
  36 ====================
  37 DEFFMT fmt
  38   SNA -- .sna, no autorun
  39   RUNSNA -- .sna, with autorun
  40   TAP, TAPE -- .tap, no autorun
  41   RUNTAP, RUNTAPE -- .tap, with autorun (i.e. with BASIC loader)
  42   BIN, RAW -- just a raw binary (or several binaries, one for each ORG)
  43   DMB, RUNDMB -- DMB, DMB with autorun
  44   NONE, NOTHING -- no output file
  45
  46 for tapes with autorun you can use "CLR" command to define BASIC "CLEAR".
  47
  48
  49 macros (experimental)
  50 =====================
  51  MACRO downxx  regpair, asret=0, asjp=0
  52   inc  =regpair[0]
  53   ld   a,=regpair[0]
  54   and  #07
  55  IF =asret
  56   ret  nz
  57  ELSEIF =asjp
  58   jp   nz,..done
  59  ELSE
  60   jr   nz,..done
  61  ENDIF
  62   ld   a,=regpair[1]
  63   add  a,32
  64   ld   =regpair[1],a
  65  IF =asret
  66   ret  c
  67  ELSEIF =asjp
  68   jp   c,..done
  69  ELSE
  70   jr   c,..done
  71  ENDIF
  72   ld   a,=regpair[0]
  73   sub  8
  74   ld   =regpair[0],a
  75  IF =asret
  76   ret
  77  ELSE
  78 ..done:
  79  ENDIF
  80  ENDM
  81
  82
  83   downxx de
  84   nop
  85   downxx hl,1
  86   nop
  87   downxx bc,,1
  88   nop
  89
  90 "..label:" is label local to macro.
  91
  92
  93 ORG
  94 ===
  95 ORG addr
  96   set current logical and physical destination address
  97
  98
  99 DISPlacements
 100 =============
 101 DISP addr
 102 ENDDISP
 103  or
 104 PHASE addr
 105 DEPHASE | UNPHASE
 106   physical code location is not changed, but logical code location set to "addr"
 107
 108
 109 ALIGN
 110 =====
 111 ALIGN size
 112   aligns PC.
 113   cannot be used in DISP
 114
 115
 116 DISPlacement ALIGN
 117 ==================
 118 DISPALIGN size
 119  or
 120 PHASEALIGN size
 121   ALIGN, but for "DISP" blocks.
 122
 123
 124 code ENTry point
 125 ================
 126 ENT addr
 127   sets code entry point (for formats with autostart).
 128
 129
 130 BASIC CLEAR
 131 ===========
 132 CLR addr
 133   sets CLEAR addess for BASIC tap loader.
 134   default value: 24999
 135
 136
 137 RESERVE address space (not implemented yet)
 138 ===========================================
 139 RESERVE addr, size
 140   will automaticaly skip the given area (and insert all necessary
 141   jumps) if assembled code will overlap.
 142
 143   *** NOT IMPLEMENTED YET!
 144
 145
 146 INClude BINary file
 147 ===================
 148 INCBIN name [,maxlen]
 149   include binary file "as-is", possibly with max length limit.
 150
 151
 152 MODULEs
 153 =======
 154 MODULE mname
 155 ENDMODULE [mname]
 156   all non-local labels between those will be "exported" to the other
 157   code as "mname.labelname".
 158
 159
 160 code DUPlication
 161 ================
 162 DUP cnt
 163  ...
 164 EDUP
 165   duplicates given code fragment "cnt" times. nested DUPs are allowed.
 166
 167
 168 conditional compilation
 169 =======================
 170 IF <condexpr>
 171 IFX <condexpr>
 172 ELSE
 173 ELSEIF <condexpr>
 174 ELSEIFX <condexpr>
 175 ENDIF
 176   for "IF", all labels in "condexpr" must be defined.
 177   for "IFX", any undefined label in "condexpr" turns it to 0 (false).
 178
 179
 180 add value to data
 181 =================
 182 DEFINCR val
 183   will add "val" to all data defined via:
 184     DB, DW, DR, DS,
 185     and to *NUMBERS* (NOT strings) in DM, DZ, DX É DC
 186
 187 DEFine Bytes
 188 ============
 189 DEFB or DB:
 190   define bytes
 191
 192 DEFine Words
 193 ============
 194 DEFW or DW:
 195   define 16-bit little-endian words
 196
 197 DEFine Reversed Words
 198 =====================
 199 DEFR ÉÌÉ DR:
 200   define 16-bit big-endian words
 201
 202
 203 DEFine repeated values
 204 ======================
 205 DEFS or DS:
 206 DEFS <rep[,value]>+
 207   define repeated values
 208
 209
 210 DEFine strings
 211 ==============
 212 DEFM or DM:
 213   define string data
 214
 215
 216 DEFine asciiZ strings
 217 =====================
 218 DEFZ or DZ:
 219   define string data, automatically adding zero byte after each one
 220
 221
 222 DEFine high-bit-terminated string
 223 =================================
 224 DEFX or DX:
 225   define string data, automatically set highest bit on the last char of each one
 226
 227
 228 DEFine byte-Counted strings
 229 ===========================
 230 DEFC or DC:
 231   define string data, automatically insert byte length before each one
 232
 233
 234 known functions in expressions
 235 ==============================
 236   defined(xxx) -- is label "xxx" value defined?
 237   known(xxx) -- is label "xxx" seen? (its value may be still undefined)
 238   aligned256(xxx) -- xxx%256 == 0
 239   sameseg(x0, x1) -- x0/256 == x1/256
 240   align(xxx[, what]) -- align xxx by what, default what == 256
 241   low(xxx) == low byte of xxx
 242   high(xxx) == high byte of xxx
 243   abs(xxx) == absolute value of xxx
 244   bswap(xxx) -- swap bytes in 16-bit word
 245
 246   scraddr8x8(x, y, base=#4000) -- calculate screen address; coords are in chars
 247   scraddr8x1(x, y, base=#4000) -- calculate screen address; x coord is char, y coord is pixel
 248   scrattr8x8(x, y, base=#4000) -- calculate attribute address; coords are in chars
 249
 250   marg2str(argname) -- get macro argument name as string value; always lowercased
 251     this is to use macro arguments in comparisons, like this:
 252       IF marg2str(=regpair) == "hl"
 253         ...
 254       ENDIF
 255     note the '=' prefix. result of `marg2str()` will be lowercased.
 256
 257   strlen(str) == string length
 258
 259
 260 you can use "[]" instead of "()" in math expressions.
 261
 262
 263 numeric literals
 264 ================
 265 start numeric literal with "0" to get octal.
 266 you can end hex number with "h" instead of using prefix (but this is not recommended).
 267
 268 allowed number prefixes for hex numbers:
 269   0xNN
 270   #NN
 271   $NN
 272   &HNN
 273
 274 allowed number prefixes for bin numbers:
 275   0bNN
 276   %nn
 277   &BNN
 278
 279 allowed number prefixes for octal numbers:
 280   0NN
 281   0oNN
 282   &ONN
 283
 284 allowed number prefixes for decimal numbers:
 285   [1-9]NN
 286   0dNN
 287   &DNN
 288
 289
 290 two-char string literals as numbers
 291 ===================================
 292 two-char string literals (in single or double quotes) can be used
 293 as numeric literals. the difference is:
 294
 295   "ab" -- 'a' will be in low (first) byte
 296   'ab' -- 'a' will be in high (second) byte
 297
 298
 299 EX AF,AF'
 300 =========
 301 you can use either "AF'" or "AFX" form for this.
 302
 303
 304 colons for commands
 305 ===================
 306 you can separate multiple commands with colons:
 307
 308   ld a,42 : ld b,69
 309
 310
 311 math priorities (WARNING! NOT C!)
 312 =================================
 313    ! (logical not)
 314    ~ (bitwise not)
 315   ------------
 316    <<
 317    >> (signed shift)
 318    >>> (unsigned shift)
 319   ------------
 320    &
 321   ------------
 322    |
 323    ^
 324   ------------
 325    *
 326    /
 327    %
 328   ------------
 329    +
 330    -
 331   ------------
 332    <
 333    >
 334    = (equality test, the same as '==')
 335    ==
 336    !=
 337    <> (inequality test, the same as '!=')
 338    <=
 339    >=
 340   ------------
 341    &&
 342   ------------
 343    ||
 344   ------------
 345
 346   logical '&&' É '||' are short-circuited.