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
  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 to use `regpair` as full register name: `inc =regpair[]`.
  93
  94 default arg can be empty, like `MACRO xxx arg=`. to test it, use:
  95   IF marg2str(=arg) != ""
  96     ...
  97   ENDIF
  98
  99
 100 ORG
 101 ===
 102 ORG addr
 103   set current logical and physical destination address
 104
 105
 106 DISPlacements
 107 =============
 108 DISP addr
 109 ENDDISP
 110  or
 111 PHASE addr
 112 DEPHASE | UNPHASE
 113   physical code location is not changed, but logical code location set to "addr"
 114
 115
 116 ALIGN
 117 =====
 118 ALIGN size
 119   aligns PC.
 120   cannot be used in DISP
 121
 122
 123 DISPlacement ALIGN
 124 ==================
 125 DISPALIGN size
 126  or
 127 PHASEALIGN size
 128   ALIGN, but for "DISP" blocks.
 129
 130
 131 code ENTry point
 132 ================
 133 ENT addr
 134   sets code entry point (for formats with autostart).
 135
 136
 137 BASIC CLEAR
 138 ===========
 139 CLR addr
 140   sets CLEAR addess for BASIC tap loader.
 141   default value: 24999
 142
 143
 144 RESERVE address space
 145 ===========================================
 146 RESERVE addr, size
 147   will automaticaly skip the given area (and insert all necessary
 148   jumps) if assembled code will overlap.
 149
 150   WARNING! this is not properly tested, and it will happily try
 151            to insert jumps even in def* data!
 152
 153
 154 INCLUDE source file
 155 ===================
 156 INCLUDE "name"
 157 INCLUDE <name>
 158   includes source file. for simple quotes, searching starts from the
 159   directory with the file we are processing right now (same as in C).
 160   angle brackets means "search in system library dir".
 161   if file name starts with "?", this is "soft include". if file could
 162   not be found, the include will be silently ignored. you can separate
 163   "?" from the file name with spaces.
 164
 165
 166 INClude BINary file
 167 ===================
 168 INCBIN name [,maxlen]
 169   include binary file "as-is", possibly with max length limit.
 170
 171
 172 MODULEs
 173 =======
 174 MODULE mname
 175 ENDMODULE [mname]
 176   all non-local labels between those will be "exported" to the other
 177   code as "mname.labelname".
 178
 179
 180 code DUPlication
 181 ================
 182 DUP cnt [,itervarname [,initval [,increment]]]
 183  ...
 184 EDUP
 185   duplicates given code fragment "cnt" times. nested DUPs are allowed.
 186   if `itervarname` is specified, it will contain iteration counter.
 187   note that this var is local for DUP block, and will be destroyed
 188   when DUP complete (i.e. it won't go to ref, and can shadow other
 189   labels).
 190
 191   you can specily initial value (default is 0), and increment
 192   (default is 1) for iteration variable.
 193
 194   you can use REPT/ENDR as synonyms.
 195
 196
 197 conditional compilation
 198 =======================
 199 IF <condexpr>
 200 IFX <condexpr>
 201 ELSE
 202 ELSEIF <condexpr>
 203 ELSEIFX <condexpr>
 204 ENDIF
 205   for "IF", all labels in "condexpr" must be defined.
 206   for "IFX", any undefined label in "condexpr" turns it to 0 (false).
 207
 208
 209 add value to data
 210 =================
 211 DEFINCR val
 212   will add "val" to all data defined via:
 213     DB, DW, DR, DS,
 214     and to *NUMBERS* (NOT strings) in DM, DZ, DX É DC
 215   it is possible to use complex expression to modify the data, by using string.
 216   all operations are done on the properly sized value.
 217   operators:
 218     shr, <count>
 219     shl, <count>
 220     sar, <count>  -- arith shift, extend bit 7
 221     sal, <count>  -- arith shift, extend bit 0
 222     ror, <count>
 223     rol, <count>
 224     and, <byte>
 225     xor, <byte>
 226     or, <byte>
 227     add, <byte>
 228     sub, <byte>
 229   example:
 230     DEFINCR "expr", "shl",3, "xor",0x80, "or",1
 231
 232
 233 DEFine Bytes
 234 ============
 235 DEFB or DB:
 236   define bytes
 237
 238 DEFine Words
 239 ============
 240 DEFW or DW:
 241   define 16-bit little-endian words
 242
 243 DEFine Reversed Words
 244 =====================
 245 DEFR ÉÌÉ DR:
 246   define 16-bit big-endian words
 247
 248
 249 DEFine repeated values
 250 ======================
 251 DEFS or DS:
 252 DEFS <rep[,value]>+
 253   define repeated values
 254
 255
 256 DEFine strings
 257 ==============
 258 DEFM or DM:
 259   define string data
 260
 261
 262 DEFine asciiZ strings
 263 =====================
 264 DEFZ or DZ:
 265   define string data, automatically adding zero byte after each one
 266
 267
 268 DEFine high-bit-terminated string
 269 =================================
 270 DEFX or DX:
 271   define string data, automatically set highest bit on the last char of each one
 272
 273
 274 DEFine byte-Counted strings
 275 ===========================
 276 DEFC or DC:
 277   define string data, automatically insert byte length before each one
 278
 279
 280 known functions in math expressions
 281 ===================================
 282   defined(xxx) -- is label "xxx" value defined?
 283   known(xxx) -- is label "xxx" seen? (its value may be still undefined)
 284   aligned256(xxx) -- xxx%256 == 0
 285   align(xxx[, what]) -- align xxx by what, default what == 256
 286   sameseg(x0, x1) -- x0/256 == x1/256
 287   low(xxx) -- low byte of xxx
 288   high(xxx) -- high byte of xxx
 289   abs(xxx) -- absolute value of xxx
 290   bswap(xxx) -- swap bytes in 16-bit word
 291
 292   scraddr8x8(x, y, base=#4000) -- calculate screen address; coords are in chars
 293   scraddr8x1(x, y, base=#4000) -- calculate screen address; x coord is char, y coord is pixel
 294   scrattr8x8(x, y, base=#4000) -- calculate attribute address; coords are in chars
 295
 296   marg2str(argname) -- get macro argument name as string value; always lowercased
 297     this is to use macro arguments in comparisons, like this:
 298       IF marg2str(=regpair) == "hl"
 299         ...
 300       ENDIF
 301     note the '=' prefix. result of `marg2str()` will be lowercased.
 302
 303   strlen(str) -- string length
 304
 305
 306 you can use "[]" instead of "()" in math expressions.
 307
 308
 309 numeric literals
 310 ================
 311 start numeric literal with "0" to get octal.
 312 you can end hex number with "h" instead of using prefix (but this is not recommended).
 313
 314 allowed number prefixes for hex numbers:
 315   0xNN
 316   #NN
 317   $NN
 318   &HNN
 319
 320 allowed number prefixes for bin numbers:
 321   0bNN
 322   %nn
 323   &BNN
 324
 325 allowed number prefixes for octal numbers:
 326   0NN
 327   0oNN
 328   &ONN
 329
 330 allowed number prefixes for decimal numbers:
 331   [1-9]NN
 332   0dNN
 333   &DNN
 334
 335
 336 two-char string literals as numbers
 337 ===================================
 338 two-char string literals (in single or double quotes) can be used
 339 as numeric literals. the difference is:
 340
 341   "ab" -- 'a' will be in low (first) byte
 342   'ab' -- 'a' will be in high (second) byte
 343
 344
 345 EX AF,AF'
 346 =========
 347 you can use either "AF'" or "AFX" form for this.
 348
 349
 350 colons for commands
 351 ===================
 352 you can separate multiple commands with colons:
 353
 354   ld a,42 : ld b,69
 355
 356
 357 math priorities (WARNING! NOT C!)
 358 =================================
 359    ! (logical not)
 360    ~ (bitwise not)
 361   ------------
 362    <<
 363    >> (signed shift)
 364    >>> (unsigned shift)
 365   ------------
 366    &
 367   ------------
 368    |
 369    ^
 370   ------------
 371    *
 372    /
 373    %
 374   ------------
 375    +
 376    -
 377   ------------
 378    <
 379    >
 380    = (equality test, the same as '==')
 381    ==
 382    !=
 383    <> (inequality test, the same as '!=')
 384    <=
 385    >=
 386   ------------
 387    &&
 388   ------------
 389    ||
 390   ------------
 391
 392   logical '&&' É '||' are short-circuited.
 393
 394
 395 $MATHMODE
 396 =========
 397 $MATHMODE <old|new>
 398
 399 new is more C-like, and the current default.
 400 directive is here for compatibility with the old code.
 401
 402
 403 $CASTRATES
 404 ==========
 405 $CASTRATES <yes|no>
 406
 407 allow hex numbers like "&abc"? note that turning this on
 408 will turn off "&b" binary prefix.
 409
 410
 411 $REFOPT
 412 =======
 413 $REFOPT <default|alllabels|noupcase>
 414
 415 what to output to label reference file? default is "alllabels".
 416 "noupcase" means "omit all-uppercase labels".
 417
 418
 419 $PRINTF
 420 $PRINTF0
 421 $PRINTFA
 422 ========
 423 $PRINTF "fmt" [,args...]
 424
 425 very simple printf. automatically advances the line.
 426 "printf" works only on the second pass.
 427 "printf0" works only on the first pass.
 428 "printfa" works on all passes.
 429
 430
 431 $ERROR
 432 ======
 433 $ERROR "fmt" [,args...]
 434
 435 prints "user error" message, and aborts compilation.
 436
 437
 438 $WARNING
 439 ========
 440 $WARNING "fmt" [,args...]
 441
 442 prints "user warning" message, but doesn't abort compilation.
 443
 444
 445 adding external data files to the resulting image
 446 =================================================
 447 DATABIN "name"[,len[,offset[,codeaddr]]]
 448 DATABIN "name|dfname"[,len[,offset[,codeaddr]]]
 449
 450 load external file with the given name, and write it to the
 451 resulting image (tap, scl, etc.). loader will NOT automatically
 452 load it. to autoload it, use CODEBIN.
 453
 454 WARNING! all such blocks will be appended (and loaded) *AFTER*
 455          the normal memory blocks.
 456
 457
 458 writing part of the code
 459 ========================
 460 $SAVECODE "filename",addr,size [,ldaddr [,options...]]
 461
 462 options:
 463   wipe -- wipe saved area (mark it as unused)
 464   data -- save as data (do not autoload it)
 465
 466 this can be used to assemble and write code for additional 128K
 467 pages.
 468
 469 WARNING! all used code labels must be known, because the code will
 470 be copied "as is", and unknown labels won't be patched!
 471
 472 WARNING! all such blocks will be appended (and loaded) *AFTER*
 473          the normal memory blocks.
 474
 475
 476 structures
 477 ==========
 478 STRUCT <flags> structname [,init_ofs]
 479 ...
 480 ENDS
 481 STRUCT <flags> extend structname [,init_ofs]
 482 ...
 483 ENDS
 484 STRUCT <flags> structname extend parentstructname [,init_ofs]
 485 ...
 486 ENDS
 487
 488 you can extend existing struct with new fields using the second form.
 489 this will not create a new struct, but simply append fields to the existing
 490 one (and fix `._sizeof`).
 491
 492 the third form is used to "subclass" existing structure. i.e. to create a
 493 new structure with a new name, and with all fields from the parent, followed
 494 by new fields.
 495
 496 optional `init_ofs` can be used to set initial offset of the declared fields.
 497 for extensions, it sets the initial offset of the first extension field.
 498
 499 field definitions:
 500   fldname <type>
 501
 502 types are:
 503   byte
 504   word
 505   dword  (4 bytes)
 506   address  (2 bytes, same as "word")
 507   label
 508   defs <size>
 509   ds <size>
 510
 511 for non-label and non-ds fields it is possible to specify an initial value.
 512   field word = 0x29a
 513
 514 each struct will automatically get "structname._sizeof" label.
 515
 516 <flags> is a comma-separated list of flags in square brackets. optional.
 517 currently defined flags:
 518   `zero_fill`: fill uinitialised struct fields with zeroes.
 519
 520
 521 create anonymous struct
 522   structname [init]
 523
 524 create named struct
 525   label: structname [init]
 526
 527 for named structs, labels with fields addresses will be automatically
 528 created. i.e. "boo: goo" will create labels "boo.fldname", etc.
 529
 530 struct initialisation consists of "name = value" pairs, delimited by
 531 commas. all pairs must be on the same line. to create multiline inits,
 532 use culry brackets:
 533
 534 structname {
 535   field0 = 0x29a, field1 = 666
 536   field1 = 69
 537 }
 538
 539 opening bracket must be last at the line, and closing bracket must be
 540 the only non-blank char in the line.
 541
 542
 543 existing structure can be extended:
 544 STRUCT *mobj
 545   ; user data
 546   cdir byte 0
 547   colid byte 0
 548 ENDS
 549
 550 this will add two new fields to the *EXISTING* struct named `mobj`.
 551 "_sizeof" label will be adjusted.
 552
 553
 554 existing structure can be "subclassed":
 555 STRUCT +mobj mobjex
 556   userdata address
 557 ENDS
 558
 559 this will create a new struct "mobjex", with all fields from "mobj", and
 560 one new field.