-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathwla_readme.html
More file actions
3442 lines (2478 loc) · 89.8 KB
/
wla_readme.html
File metadata and controls
3442 lines (2478 loc) · 89.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html>
<head>
<title>wla readme</title>
<link rel="stylesheet" type="text/css" href="./index.css" />
</head>
<body>
<table>
<tr>
<td>
<pre>
---------------------------------------------------------------------------------
WLA DX GB-Z80/Z80/6502/65C02/6510/65816/HUC6280/SPC-700 Macro Assembler Package
Written by 1998-2008 Ville Helin
---------------------------------------------------------------------------------
1..... Introduction
2..... Assembler Directives
3..... Assembler Syntax
3.1.. Case Sensitivity
3.2.. Comments
3.3.. Labels
3.4.. Number Types
3.5.. Strings
3.6.. Mnemonics
3.7.. Brackets?
4..... Error Messages
5..... Supported ROM/RAM/Cartridge Types (WLA-GB)
5.1.. ROM Size
5.2.. RAM Size
5.3.. Cartridge Type
6..... Bugs
7..... Files
7.1.. 'examples'
7.2.. 'examples/gb-z80/lib'
7.3.. 'memorymaps'
8..... Temporary Files
9..... Compiling
9.1.. Compiling Object Files
9.2.. Compiling Library Files
10.... Linking
11.... Arithmetics
12.... Disassembling
13.... Binary to DB Conversion
14.... Things you should know about coding for...
14.1. Z80
14.2. 6502
14.3. 65C02
14.4. 6510
14.5. 65816
14.6. HUC6280
14.7. SPC-700
14.8. Pocket Voice (GB-Z80)
14.9. GB-Z80
15.... WLA Flags
16.... Extra compile time definitions
17.... Good things to know about WLA
18.... Author
19.... Thanks
20.... Future
21.... Support
22.... Legal Note
------------------------------------------------------------------------------
1.... Introduction
------------------------------------------------------------------------------
I wrote this because I had never written an assembler before and I really
needed a macro assembler which could compile the GB-Z80 code I wrote. ;)
Gaelan Griffin needed real Z80 support for his SMS projects so I thought
I could write WLA to be a little more open and nowadays it supports all
the Z80 systems you can think of. You'll just have to define the memorymap
of the destination machine for your project. After fixing some bugs I thought
I could add support for 6502 systems so all NES-people would get their
share of WLA as well. After finishing that few people said they'd like 65816
support (they had SNES developing in mind) so I added support for that. And
then I thought I should write a 6510 version of WLA as well...
Almost all rules that apply to Z80 compiling apply also to 6502, 65C02, 6510,
65816, HUC6280 and SPC-700.
This is my ideal GB-Z80 macro assembler (not in final form, not yet). ;)
Tastes differ. Thus WLA! Notice that WLA was initially made for Game Boy
developers so the GB-Z80 version and the rest differ a little.
Currently WLA can also be used as a patch tool. Just include the original
ROM image into the project with .BACKGROUND and insert e.g., OVERWRITE .SECTIONs
to patch the desired areas. Output the data into a new ROM image and there
you have it. 100% readable (asm coded) patches are reality!
Note that you can directly compile only object and library files. You must
use WLALINK to link these (or only one, if you must) into a ROM/program file.
About the names... WLA DX means all the tools covered in this documentation.
So WLA DX includes WLA GB-Z80/Z80/6502/65C02/6510/65816/HUC6280/SPC-700
macro assembler (what a horribly long name), WLAB, WLAD and WLALINK
GB-Z80/Z80/6502/65C02/6510/65816/HUC6280/SPC-700 linker. I use plain WLA to refer
to the macro assembler.
WLA DX's homepage: http://www.iki.fi/~vhelin/wla.html
And if you happen to write something cool using WLA DX, please let me know,
I want to see it!
------------------------------------------------------------------------------
2.... Assembler Directives
------------------------------------------------------------------------------
Here's the order in which the data is placed into the output:
1. Data and group 3 directives outside sections.
2. Group 2 directives.
3. Data and group 3 directives inside sections.
4. Group 1 directives.
Here are the supported directives (with examples) in WLA:
[ALL] - All, GB-Z80, Z80, 6502, 65C02, 6510, 65816, HUC6280 and SPC-700
versions apply.
[GB ] - Only the GB-Z80 version applies.
[GB8] - Only the GB-Z80 and 65816 versions apply.
[Z80] - Only the Z80 version applies.
[658] - Only the 65816 version applies.
[SPC] - Only the SPC-700 version applies.
[65x] - Only the 6502, 65C02, 6510, 65816 and HUC6280 versions apply.
[!GB] - Only the Z80, 6502, 65C02, 6510, 65816, HUC6280 and SPC-700
versions apply.
Group 1:
[GB ] .COMPUTEGBCHECKSUM
[Z80] .COMPUTESMSCHECKSUM
[658] .COMPUTESNESCHECKSUM
[Z80] .SDSCTAG 1.0, "DUNGEON MAN", "A wild dungeon exploration game", "Ville Helin"
[Z80] .SMSTAG
Group 2:
[GB ] .CARTRIDGETYPE 1
[GB ] .COMPUTEGBCOMPLEMENTCHECK
[ALL] .EMPTYFILL $C9
[658] .ENDEMUVECTOR
[658] .ENDNATIVEVECTOR
[658] .ENDSNES
[ALL] .EXPORT work_x
[658] .FASTROM
[658] .HIROM
[GB ] .LICENSEECODENEW "1A"
[GB ] .LICENSEECODEOLD $1A
[658] .LOROM
[GB8] .NAME "NAME OF THE ROM"
[ALL] .OUTNAME "other.o"
[GB ] .RAMSIZE 0
[GB ] .ROMDMG
[GB ] .ROMGBC
[GB ] .ROMSGB
[658] .SLOWROM
[658] .SMC
[658] .SNESEMUVECTOR
[658] .SNESHEADER
[658] .SNESNATIVEVECTOR
Group 3:
[65x] .16BIT
[658] .24BIT
[65x] .8BIT
[658] .ACCU 8
[ALL] .ASC "HELLO WORLD!"
[ALL] .ASCTABLE
[ALL] .ASCIITABLE
[ALL] .ASM
[ALL] .BACKGROUND "parallax.gb"
[ALL] .BANK 0 SLOT 1
[658] .BASE $80
[ALL] .BLOCK "Block1"
[ALL] .BR
[ALL] .BREAKPOINT
[ALL] .BYT 100, $30, %1000, "HELLO WORLD!"
[ALL] .ROMBANKSIZE $4000
[ALL] .DB 100, $30, %1000, "HELLO WORLD!"
[ALL] .DBM filtermacro 1, 2, "encrypt me"
[ALL] .DBCOS 0.2, 10, 3.2, 120, 1.3
[ALL] .DBRND 20, 0, 10
[ALL] .DBSIN 0.2, 10, 3.2, 120, 1.3
[ALL] .DEFINE IF $FF0F
[ALL] .DEF IF $FF0F
[ALL] .DS 256, $10
[ALL] .DSB 256, $10
[ALL] .DSTRUCT waterdrop INSTANCEOF water DATA "tingle", 40, 120
[ALL] .DSW 128, 20
[ALL] .DW 16000, 10, 255
[ALL] .DWM filtermacro 1, 2, 3
[ALL] .DWCOS 0.2, 10, 3.2, 1024, 1.3
[ALL] .DWRND 20, 0, 10
[ALL] .DWSIN 0.2, 10, 3.2, 1024, 1.3
[ALL] .ELSE
[ALL] .ENDASM
[ALL] .ENDB
[ALL] .ENDE
[ALL] .ENDIF
[ALL] .ENDM
[ALL] .ENDME
[ALL] .ENDR
[ALL] .ENDRO
[ALL] .ENDS
[ALL] .ENDST
[ALL] .ENUM $C000
[ALL] .EQU IF $FF0F
[ALL] .FAIL
[ALL] .FCLOSE FP_DATABIN
[ALL] .FOPEN "data.bin" FP_DATABIN
[ALL] .FREAD FP_DATABIN DATA
[ALL] .FSIZE FP_DATABIN SIZE
[ALL] .IF DEBUG == 2
[ALL] .IFDEF IF
[ALL] .IFDEFM \2
[ALL] .IFEQ DEBUG 2
[ALL] .IFEXISTS "main.s"
[ALL] .IFGR DEBUG 2
[ALL] .IFGREQ DEBUG 1
[ALL] .IFLE DEBUG 2
[ALL] .IFLEEQ DEBUG 1
[ALL] .IFNDEF IF
[ALL] .IFNDEFM \2
[ALL] .IFNEQ DEBUG 2
[ALL] .INCBIN "sorority.bin"
[ALL] .INCDIR "/usr/programming/gb/include/"
[ALL] .INCLUDE "cgb_hardware.i"
[658] .INDEX 8
[ALL] .INPUT NAME
[ALL] .MACRO TEST
[ALL] .MEMORYMAP
[ALL] .ORG $150
[ALL] .ORGA $150
[ALL] .PRINTT "Here we are...\n"
[ALL] .PRINTV DEC DEBUG+1
[ALL] .RAMSECTION "Vars" BANK 0 SLOT 1
[ALL] .REDEFINE IF $F
[ALL] .REDEF IF $F
[ALL] .REPEAT 6
[ALL] .REPT 6
[ALL] .ROMBANKMAP
[ALL] .ROMBANKS 2
[ALL] .SEED 123
[ALL] .SECTION "Init" FORCE
[ALL] .SHIFT
[ALL] .SLOT 1
[ALL] .STRUCT enemy_object
[ALL] .SYM SAUSAGE
[ALL] .SYMBOL SAUSAGE
[ALL] .UNBACKGROUND $1000 $1FFF
[ALL] .UNDEFINE DEBUG
[ALL] .UNDEF DEBUG
[ALL] .WORD 16000, 10, 255
Descriptions:
-----
.8BIT
-----
There are a few mnemonics that look identical, but take different sized
arguments. Here's a list of such 6502 mnemonics:
ADC, AND, ASL, BIT, CMP, CPX, CPY, DEC, EOR, INC, LDA, LDX, LDY, ORA, ROL,
SBC, STA, STX and STY.
For example:
LSR 11 ; $46 $0B
LSR $A000 ; $4E $00 $A0
The first one could also be
LSR 11 ; $4E $0B $00
.8BIT is here to help WLA to decide to choose which one of the opcodes it
selects. When you give .8BIT (default) no 8bit address/value is expanded
to 16bits.
By default WLA uses the smallest possible size. This is true also when WLA
finds a computation it can't solve right away. WLA assumes the result will
be inside the smallest possible bounds, which depends on the type of the
mnemonic.
You can also use the fixed argument size versions of such mnemonics by
giving the size with the operand (i.e., operand hinting). Here are few
examples:
LSR 11.B ; $46 $0B
LSR 11.W ; $46 $0B $00
In WLA-65816 .ACCU/.INDEX/SEP/REP override .8BIT/.16BIT/.24BIT when considering
the immediate values, so be careful. Still, operand hints override all of
these, so use them to be sure.
This is not a compulsory directive.
------
.16BIT
------
Analogous to .8BIT. .16BIT forces all addresses and immediate values to
be expanded into 16bit range, when possible, that is.
LSR 11 ; $46 $0B
that would be the case, normally, but after .16BIT it becomes
LSR 11 ; $4E $0B $00
This is not a compulsory directive.
------
.24BIT
------
Analogous to .8BIT and .16BIT. .24BIT forces all addresses to
be expanded into 24bit range, when possible, that is.
AND $11 ; $25 $11
that would be the case, normally, but after .24BIT it becomes
AND $11 ; $2F $11 $00 $00
If it is not possible to expand the address into .24BIT range,
then WLA tries to expand it into 16bit range.
This is not a compulsory directive.
-------
.ACCU 8
-------
Forces WLA to override the accumulator size given with SEP/REP. .ACCU
doesn't produce any code, it only affects the way WLA interprets the
immediate values (8 for 8 bit operands, 16 for 16 bit operands) for opcodes
dealing with the accumulator.
So after giving .ACCU 8
AND #6
will produce $29 $06, and after giving .ACCU 16
AND #6
will yield $29 $00 $06.
Note that SEP/REP again will in turn reset the accumulator/index register
size.
This is not a compulsory directive.
--------
.INDEX 8
--------
Forces WLA to override the index (X/Y) register size given with SEP/REP.
.INDEX doesn't produce any code, it only affects the way WLA interprets the
immediate values (8 for 8 bit operands, 16 for 16 bit operands) for opcodes
dealing with the index registers.
So after giving .INDEX 8
CPX #10
will produce $E0 $A0, and after giving .INDEX 16
CPX #10
will yield $E0 $00 $A0.
Note that SEP/REP again will in turn reset the accumulator/index register
size.
This is not a compulsory directive.
----
.ASM
----
Tells WLA to start assembling. Use .ASM to continue the work which has been
disabled with .ENDASM. .ASM and .ENDASM can be used to mask away big blocks
of code. This is analogous to the ANSI C -comments (/*...*/), but .ASM and
.ENDASM can be nested, unlike the ANSI C -counterpart.
This is not a compulsory directive.
-------
.ENDASM
-------
Tells WLA to stop assembling. Use .ASM to continue the work.
This is not a compulsory directive.
----------------
.DBRND 20, 0, 10
----------------
Defines bytes, just like .DSB does, only this time they are filled with
(pseudo) random numbers. We use the integrated Mersenne Twister to generate
the random numbers. If you want to seed the random number generator,
use .SEED.
The first parameter (20 in the example) defines the number of random
numbers we want to generate. The next two tell the range of the random
numbers, i.e. min and max.
Here's how it works:
.DBRND A, B, C
for (i = 0; i < A; i++)
output_data((rand() % (C-B+1)) + B);
This is not a compulsory directive.
----------------
.DWRND 20, 0, 10
----------------
Analogous to .DBRND (but defines words).
This is not a compulsory directive.
-----------------------------
.DBCOS 0.2, 10, 3.2, 120, 1.3
-----------------------------
Defines bytes just like .DSB does, only this time they are filled with
cosine data. .DBCOS takes five arguments.
The first argument is the starting angle. Angle value ranges from 0 to
359.999..., but you can supply WLA with values that are out of the range -
WLA fixes them ok. The value can be integer or float.
The second one descibes the amount of additional angles. The example
will define 11 angles.
The third one is the adder value which is added to the angle value when
next angle is calculated. The value can be integer or float.
The fourth and fifth ones can be seen from the pseudo code below, which
also describes how .DBCOS works. The values can be integer or float.
Remember that cos (and sin) here returns values ranging from -1 to 1.
.DBCOS A, B, C, D, E
for (B++; B > 0; B--) {
output_data((D * cos(A)) + E)
A = keep_in_range(A + C)
}
This is not a compulsory directive.
-----------------------------
.DBSIN 0.2, 10, 3.2, 120, 1.3
-----------------------------
Analogous to .DBCOS, but does sin() instead of cos().
This is not a compulsory directive.
------------------------------
.DWCOS 0.2, 10, 3.2, 1024, 1.3
------------------------------
Analogous to .DBCOS (but defines words).
This is not a compulsory directive.
------------------------------
.DWSIN 0.2, 10, 3.2, 1024, 1.3
------------------------------
Analogous to .DBCOS (but defines words and does sin() instead of cos()).
This is not a compulsory directive.
-----------------------
.NAME "NAME OF THE ROM"
-----------------------
If .NAME is used with WLA-GB then the 16 bytes ranging from $0134
to $0143 are filled with the provided string. WLA-65816 fills
the 21 bytes from $FFC0 to $FFD4 in HiROM- and from $7FC0 to $7FD4
in LoROM-mode with the name string (SNES ROM title).
If the string is shorter than 16/21 bytes the remaining space is
filled with $00.
This is not a compulsory directive.
-----------
.ROMBANKS 2
-----------
Indicates the size of the ROM in rombanks. This value is converted to a
standard GB ROM size indicator value found at $148 in a GB ROM, and there
this one is put into.
This is a compulsory directive unless .ROMBANKMAP is defined.
You can redefine .ROMBANKS as many times as you wish as long as
the old and the new ROM bank maps match as much as possible. This
way you can enlarge the size of the project on the fly.
----------
.RAMSIZE 0
----------
Indicates the size of the RAM. This is a standard GB RAM size indicator value
found at $149 in a GB ROM, and there this one is put to also.
This is not a compulsory directive.
--------------
.EMPTYFILL $C9
--------------
This byte is used in filling the unused areas of the ROM file. EMPTYFILL
defaults to $00.
This is not a compulsory directive.
----------------
.CARTRIDGETYPE 1
----------------
Indicates the type of the cartridge (mapper and so on). This is a standard
GB cartridge type indicator value found at $147 in a GB ROM, and there this
one is put to also.
This is not a compulsory directive.
--------------------
.LICENSEECODEOLD $1A
--------------------
This is a standard old licensee code found at $14B in a GB ROM, and there this
one is put to also. .LICENSEECODEOLD cannot be defined with .LICENSEECODENEW.
This is not a compulsory directive.
---------------------
.LICENSEECODENEW "1A"
---------------------
This is a standard new licensee code found at $144 and $145 in a GB ROM, and
there this one is put to also. .LICENSEECODENEW cannot be defined with
.LICENSEECODEOLD. $33 is inserted into $14B, as well.
This is not a compulsory directive.
------------------
.COMPUTEGBCHECKSUM
------------------
When this directive is used WLA computes the ROM checksum found at $14E and
$14F in a GB ROM. Note that this directive can only be used with wla-gb.
Note that you can also write .COMPUTECHECKSUM (the old name for this
directive), but it's not recommended.
This is not a compulsory directive.
-------------------
.COMPUTESMSCHECKSUM
-------------------
When this directive is used WLA computes the ROM checksum found at $7FFA and
$7FFB in a SMS/GG ROM. Note that this directive can only be used with wla-z80.
Also note that the ROM size must be at least 32KB. Data beyond 256KB limit
is not taken into account when calculating the SMS checksum, which should
be the right way to do it.
This is not a compulsory directive.
--------------------
.COMPUTESNESCHECKSUM
--------------------
When this directive is used WLA computes the SNES ROM checksum and
inverse checksum found at $7FDC-$7FDF (LoROM) or $FFDC-$FFDF (HiROM).
Note that this directive can only be used with wla-65816. Also note
that the ROM size must be at least 32KB for LoROM images and 64KB for
HiROM images.
.LOROM or .HIROM must be issued before .COMPUTESNESCHECKSUM.
This is not a compulsory directive.
-------
.SMSTAG
-------
.SMSTAG forces WLA to write an ordinary SMS/GG ROM tag to the ROM file.
Currently only the string "TMR SEGA" and ROM checksum are written
(meaning that .SMSTAG also defines .COMPUTESMSCHECKSUM).
This is not a compulsory directive.
-----------------------------------------------------------------------------
.SDSCTAG 1.0, "DUNGEON MAN", "A wild dungeon exploration game", "Ville Helin"
-----------------------------------------------------------------------------
.SDSCTAG adds SDSC tag to your SMS/GG ROM file. The ROM size must be at least
32KB just like with .COMPUTESMSCHECKSUM and .SMSTAG, as the data goes into
$7FE0-$7FEF of the ROM. For more information about this header take a look
at http://www.smspower.org/dev/sdsc/. Here's an explanation of the arguments:
.SDSCTAG {version number}, {program name}, {program release notes}, {program author}
Note that program name, release notes and program author can also be pointers
to strings instead of being only strings (which WLA terminates with zero, and
places them into suitable locations inside the ROM file). So
.SDSCTAG 0.8, PRGNAME, PRGNOTES, PRGAUTHOR
...
PRGNAME: .DB "DUNGEON MAN", 0
PRGNOTES: .DB "A wild and totally crazy dungeon exploration game", 0
PRGAUTHOR:.DB "Ville Helin", 0
works also. All strings supplied explicitly to .SDSCTAG are placed somewhere
in .BANK 0 SLOT 0.
.SDSCTAG 1.0, "", "", ""
.SDSCTAG 1.0, 0, 0, 0
are also valid, here 0 and "" mean the user doesn't want to use any descriptive
strings. Version number can also be given as an integer, but then the minor
version number defaults to zero.
.SDSCTAG also defines .SMSTAG (as it's part of the SDSC ROM tag specification).
This is not a compulsory directive.
-------------------------
.COMPUTEGBCOMPLEMENTCHECK
-------------------------
When this directive is used WLA computes the ROM complement check found at
$14D in a GB ROM.
Note that you can still use .COMPUTECOMPLEMENTCHECK (the old name for this
directive), but it's not recommended.
This is not a compulsory directive.
--------------------------------------
.INCDIR "/usr/programming/gb/include/"
--------------------------------------
Changes the current include root directory. Use this to specify main
directory for the following .INCLUDE and .INCBIN directives.
If you want to change to the current working directory (WLA also defaults
to this), use
.INCDIR ""
This is not a compulsory directive.
-------------------------
.INCLUDE "cgb_hardware.i"
-------------------------
Includes the specified file to the source file. If the file's not found
in the .INCDIR directory, WLA tries to find it in the current working
directory.
This is not a compulsory directive.
----------------------
.INCBIN "sorority.bin"
----------------------
Includes the specified data file into the source file. .INCBIN caches
all files into memory, so you can .INCBIN any data file millions of
times, but it is loaded from hard drive only once.
You can optionally use SWAP after the file name, e.g.,
.INCBIN "kitten.bin" SWAP
.INCBIN data is divided into blocks of two bytes, and inside every block
the bytes are exchanged (like "SWAP r" does to nibbles). This requires that
the size of the file is even.
You can also force WLA to skip n bytes from the beginning of the file
by writing for example:
.INCBIN "kitten.bin" SKIP 4
Four bytes are skipped from the beginning of kitten.bin and the rest
is incbinned.
It is also possible to incbin only n bytes from a file:
.INCBIN "kitten.bin" READ 10
Will read ten bytes from the beginning of kitten.bin.
You can also force WLA to create a definition holding the size
of the file:
.INCBIN "kitten.bin" FSIZE size_of_kitten
Want to circulate all the included bytes through a filter macro? Do this:
.INCBIN "kitten.bin" FILTER filtermacro
The filter macro is executed for each byte of the included data, data
byte being the first argument, and offset from the beginning being the
second parameter, just like in the case of .DBM and .DWM.
And you can combine all these four commands:
.INCBIN "kitten.bin" SKIP 10 READ 8 SWAP FSIZE size_of_kitten FILTER filtermacro
This example shows how to incbin eight bytes (swapped) after skipping
10 bytes from the beginning of file "kitten.bin", and how to get the
size of the file into a definition label "size_of_kitten". All the data bytes
are circulated through a filter macro.
Note that the order of the extra commands is important.
If the file's not found in the .INCDIR directory, WLA tries to find it
in the current working directory.
This is not a compulsory directive.
-----------
.INPUT NAME
-----------
.INPUT is much like any Basic-language input: .INPUT asks the user
for a value or string. After .INPUT is the variable name used to store
the data.
.INPUT works like .REDEFINE, but the user gets to type in the data.
Here are few examples how to use input:
.PRINTT "The name of the ROM? "
.INPUT NAME
.NAME NAME
...
.PRINTT "Give the .DB amount.\n"
.INPUT S
.PRINTT "Give .DB data one at a time.\n"
.REPEAT S
.INPUT B
.DB B
.ENDR
...
This is not a compulsory directive.
-------------------------
.BACKGROUND "parallax.gb"
-------------------------
This chooses an existing ROM image (parallax.gb in this case) as a
background data for the project. You can overwrite the data with OVERWRITE
sections only, unless you first clear memory blocks with .UNBACKGROUND
after which there's room for other sections as well.
Note that .BACKGROUND can be used only when compiling an object file.
.BACKGROUND is useful if you wish to patch an existing ROM image with
new code or data.
This is not a compulsory directive.
-------------------------
.UNBACKGROUND $1000 $1FFF
-------------------------
After issuing .BACKGROUND you might want to free some parts of the
backgrounded ROM image for e.g., FREE sections. With .UNBACKGROUND
you can define such regions. In the example a block starting at
$1000 and ending at $1FFF was released (both ends included). You can
issue .UNBACKGROUND as many times as you wish.
This is not a compulsory directive.
-----
.FAIL
-----
Terminates the compiling process.
This is not a compulsory directive.
------------------
.FCLOSE FP_DATABIN
------------------
Closes the filehandle FP_DATABIN.
This is not a compulsory directive.
----------------------------
.FOPEN "data.bin" FP_DATABIN
----------------------------
Opens the file "data.bin" for reading and associates the filehandle with
name "FP_DATABIN".
This is not a compulsory directive.
----------------------
.FREAD FP_DATABIN DATA
----------------------
Reads one byte from "FP_DATABIN" and creates a definition called "DATA"
to hold it. "DATA" is an ordinary definition label, so you can .UNDEFINE it.
Here's an example on how to use .FREAD:
.fopen "data.bin" fp
.fsize fp t
.repeat t
.fread fp d
.db d+26
.endr
.undefine t, d
This is not a compulsory directive.
----------------------
.FSIZE FP_DATABIN SIZE
----------------------
Creates a definition called "SIZE", which holds the size of the file
associated with the filehandle "FP_DATABIN". "SIZE" is an ordinary
definition label, so you can .UNDEFINE it.
This is not a compulsory directive.
-----------
.MACRO TEST
-----------
Begins a macro called 'TEST'.
You can use '\@' inside a macro to e.g., separate a label from the other
macro 'TEST' occurrences. '\@' is replaced with an integer number
indicating the amount of times the macro has been called previously so
it is unique to every macro call. '\@' can also be used inside strings
inside a macro or just as a plain value. Look at the following examples
for more information.
You can also type '\!' to get the name of the source file currently being
parsed.
Also, if you want to use macro arguments in e.g., calculation, you can
type '\X' where X is the number of the argument. Another way to refer
to the arguments is to use their names given in the definition of the
macro (see the examples for this).
Remember to use .ENDM to finish the macro definition. Note that you
cannot use .INCLUDE inside a macro. Note that WLA's macros are in fact
more like procedures than real macros, because WLA doesn't substitute
macro calls with macro data. Instead WLA jumps to the macro when it
encounters a macro call at compile time.
You can call macros from inside a macro. Note that the preprocessor
does not expand the macros. WLA traverses through the code according to
the macro calls, so macros really define a very simple programming
language.
Here are some examples:
.MACRO NOPMONSTER
.REPT 32 ; evil...
NOP
.ENDR
.ENDM
.MACRO LOAD_ABCD
LD A, \1
LD B, \2
LD C, \3
LD D, \4
NOPMONSTER
LD HL, 1<<\1
.INCBIN \5
.ENDM
.MACRO QUEEN
QUEEN\@:
LD A, \1
LD B, \1
CALL QUEEN\@
.DB "\@", 0 ; will translate into a zero terminated string
; holding the amount of macro QUEEN calls.
.DB "\\@", 0 ; will translate into a string containing
; \@.
.DB \@ ; will translate into a number indicating
; the amount of macro QUEEN calls.
.ENDM
.MACRO LOAD_ABCD_2 ARGS ONE, TWO, THREE, FOUR, FIVE
LD A, ONE
LD B, TWO
LD C, THREE
LD D, FOUR
NOPMONSTER
LD HL, 1<<ONE
.INCBIN FIVE
.ENDM
.MACRO TEST NARGS 3
.DB \1, \2, \3
.ENDM
And here's how they can be used:
NOPMONSTER
LOAD_ABCD $10, $20, $30, XYZ, "merman.bin"
QUEEN 123
LOAD_ABCD_2 $10, $20, $30, XYZ, "merman.bin"
TEST 1, 2, 3
Note that you must separate the arguments with commas.
If you want to give names to the macro's arguments you can do that
by listing them in order after supplying ARGS after the macro's name.
Every time a macro is called a definition NARGS is created. It shows
only inside the macro and holds the number of arguments the macro
was called with. So don't have your own definition called NARGS.
Here's an example:
.MACRO LUPIN
.IF NARGS != 1
.FAIL
.ENDIF
.PRINTT "Totsan! Ogenki ka?\n"
.ENDM
This is not a compulsory directive.
-----
.ENDM
-----
Ends a .MACRO.
This is not a compulsory directive, but when .MACRO is used this one is
required to terminate it.
------
.SHIFT
------
Shifts the macro arguments one down (\2 becomes \1, \3 -> \2, etc.).
.SHIFT can thus only be used inside a .MACRO.
This is not a compulsory directive.
--------
.FASTROM
--------
Sets the ROM memory speed bit in $FFD5 (.HIROM) or $7FD5 (.LOROM) to
indicate that the SNES ROM chips are 120ns chips.
This is not a compulsory directive.
--------
.SLOWROM
--------
Clears the ROM memory speed bit in $FFD5 (.HIROM) or $7FD5 (.LOROM) to
indicate that the SNES ROM chips are 200ns chips.
This is not a compulsory directive.
----