---------------------------------------------------------- WLA DX GB-Z80/Z80/6502/6510/65816 Macro Assembler Package Copyright 1998-2001 Ville Helin ---------------------------------------------------------- 1..... Introduction 2..... WLA GB-Z80/Z80/6502/6510/65816 History 3..... WLAB History 4..... WLAD History 5..... WLALINK History 6..... Assembler Directives 7..... Assembler Syntax 7.1.. Case Sensitivity 7.2.. Comments 7.3.. Labels 7.4.. Number Types 7.5.. Strings 7.6.. Supported Mnemonics 7.7.. Brackets? 8..... Error Messages 9..... Supported Types 9.1.. ROM Size 9.2.. RAM Size 9.3.. Cartridge Type 10.... Bugs 11.... Files 11.1. 'examples' 11.2. 'examples/gb-z80/lib' 12.... Temporary Files 13.... Compiling 13.1. Compiling ROM Images 13.2. Compiling Object Files 13.3. Compiling Compact Object Files 13.4. Compiling Library Files 13.5. Compiling Compact Library Files 13.6. Compiling Program Files 14.... Arithmetics 15.... Linking 16.... Disassembling 17.... Binary to DB Conversion 18.... Pocket Voice 19.... WLA Flags 20.... Compile time definitions 21.... Good things to know about WLA 22.... Author 23.... Thanks 24.... Future 25.... Support 26.... 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, 6510 and 65816. 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 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! About the names... WLA DX means all the tools covered in this documentation. So WLA DX includes WLA GB-Z80/Z80/6502/6510/65816 macro assembler (what a horribly long name), WLAB, WLAD and WLALINK GB-Z80/Z80/6502/6510/65816. I use plain WLA to refer to the macro assembler. WLA DX's homepage: http://www.hut.fi/~vhelin/wla.html Even though WLA is written under RedHat 7.0 Linux the compiling is done with an old egcs compiler (if you don't have CC/LD defined) as it works much better than the latest beta gcc that's shipped with RH7.0. And if you happen to write something cool using WLA DX, please let me know. ------------------------------------------------------------------------------ 2... WLA GB-Z80/Z80/6502/6510/65816 History ------------------------------------------------------------------------------ v7.1 (13-Mar-2001) [ALL] Added 'x' switch to generate extra compile time definitions (WLA_TIME, WLA_FILENAME). [ALL] Characters can now be used in computations (eg. LD A, 'F'-10). [ALL] WLA could not get the correct section size from a section name if more than one underline was used. [ALL] .INCLUDE and .INCBIN used wrong name in error messages if the file was found on the current working directory and not in the .INCDIR directory. [ALL] Unix makefiles default now to gcc (if no CC/LD is defined). [ALL] .REPT can now be used inside macros. [ALL] .REPTs can be used inside .REPTs. [ALL] Macro arguments in computations work now better. [ALL] Error engine's line counting works now inside macros. [ALL] File doesn't need to end to a line feed anymore. [ALL] Added '>=' and '<=' to .IF. [ALL] Added .IFGREQ and .IFLEEQ. [ALL] .IF -directives should now work with computations. [Z80] WLA gives only a warning if .COMPUTESMSCHECKSUM is used on a ROM file smaller than 32KB. [650] Fixed "INC ?" to work (wrong type previously). v7.0 (03-Mar-2001) [ALL] WLA couldn't handle files starting with ";". [ALL] Enhanced error messages. [ALL] Compiling WLA DX under Unix is now done with egcs (if no CC is defined). [ALL] Added error messages to .ENUM and made it to accept lowercase symbols. Also added fake symbols. [ALL] Fixed a serious bug with 8bit pending calculations. [ALL] Enhanced makefiles (behave now better under Unix). [ALL] The code works now regardless of the endian type. [ALL] .INCLUDE and .INCBIN try to find the file in the current working directory if it's not in the .INCDIR directory. [ALL] Definitions take also strings as values. [ALL] Code cleanups. [ALL] Exporting an undefined definition doesn't break the compiling loop (only a warning is issued). [ALL] Quotation marks are accepted inside strings. [ALL] Temporary files are placed into the current working directory and under Unix the names incorporate PID. [ALL] .DBSIN and the rest were broken due to a typo. [ALL] Optimized string parsers. [ALL] Added .IFEXISTS. [ALL] Macro argument place holders (eg. "\1") and \@ can now be used in computations (eg. "LD A, \1+\2+\@"). [ALL] Macros can be used inside macros (but macro arguments cannot be directly forwarded to the next level). [ALL] "/*/" isn't interpreted as an empty comment anymore. [ALL] Section size can be defined insize the section name string. [Z80] Added TI-86 system include file to the archive. [Z80] Added .COMPUTESMSCHECKSUM for computing the Sega Master System ROM checksum. [Z80] Fixed "LD (IX+x), x" to work. [!GB] Few mnemonics caused stack calculator to create garbage. [GB ] Complement check computing could fail with some really bad luck. v6.9 (23-Oct-2000) [ALL] Enhanced .MACRO error messages. [ALL] Enhanced .DW error recognition. [ALL] .SECTION handling might broke with some bad luck. [ALL] \@ can now be used inside strings inside a .MACRO. [65x] Added support for "ASL", "LSR", "ROL" and "ROR". [650] Fixed "STA ?" to $8D (was $80). [650] Fixed "EOR ?" to $4D (was $40). [650] Fixed "RTI" to $40 (was $4D). [650] Fixed "STA ?,X" to $9D (was $90). [650] Fixed "ORA ?,X" to $1D (was $10). [650] Fixed "EOR ?,X" to $5D (was $50). [650] Fixed "ADC ?" to $6D (was $60). [650] Fixed "ADC ?,X" to $7D (was $70). v6.8 (09-Oct-2000) [Z80] Fixed "LD C, RL*" -mnemonics. [651] Added support for 6510 systems (wla-6510). [ALL] Enhanced documentation. [ALL] Library file compiling was broken in the previous release. v6.7 (07-Oct-2000) [ALL] Added NARGS to .MACRO. [ALL] Enhanced documentation. [ALL] Enhanced error messages. [ALL] Optimized the first internal pass. [ALL] Macros couldn't have .PRINTT directives with linefeeds. [65x] Added .8BIT and .16BIT. [658] Added support for 65816 systems (wla-65816). [658] Added .24BIT. [Z80] Fixed RST-mnemonics. [GB ] Moved lib to examples/gb. v6.6 (25-Sep-2000) [ALL] .EMPTYFILL didn't function properly when .ROMBANKMAP was used instead of .ROMBANKS. [ALL] Fixed few byte size checks. [650] Added support for 6502 systems (wla-6502). [!GB] Header and footer sizes are now shown in the verbose mode's result information. v6.5 (20-Sep-2000) [ALL] Optimized number decoding. [ALL] Enhanced documentation. [ALL] Binary file compiling is now called program file compiling (still doesn't suit it 100%). [ALL] Macros couldn't be used before setting an ORG. [Z80] Program file compiling accepts now BANKHEADER section for bank 0. [Z80] The default program file suffix is now '.prg'. [Z80] NO$GMB symbol files can also be written. v6.4 (12-Sep-2000) [ALL] Returned '*' commenting (from the beginning of a line). [ALL] 'LABEL:XYZ' is now correctly decoded. [ALL] BIT/RES/RST/SET opcodes understand now defines and calculations. [ALL] References to local labels outside sections were possible. [ALL] Added a much faster and enhanced MACRO language. [ALL] IF directives can now be nested. [ALL] .INCBIN works in library files. [ALL] Added .REDEFINE. [ALL] Added .PRINTT and .PRINTV. [ALL] Added .DBSIN, .DBCOS, .DWSIN and DWCOS. [ALL] Added .IFEQ, .IFNEQ, .IFGR and .IFLE. [ALL] Added .IF with the following operators: '>', '<', '!=' and '=='. [ALL] Added .IFNDEFM and .IFDEFM. [ALL] Added .UNDEF. [ALL] Added .FAIL. [ALL] Added SEMIFREE sections. [ALL] Fixed a bug in opcode case sensitivity checks. [ALL] Opcode case sensitivity mode can be changed so WLA understands only uppercase letters (flag u). [ALL] Added support for modulo ('#') in calculations. [ALL] Enhanced error messages. [ALL] ROM banks can be inserted into different sized slots as long as the bank fits fully inside the slot. [ALL] Computations are now computed internally with higher precision when possible and the result is converted to an integer. v6.3 (04-Sep-2000) [ALL] Enhanced error messages. [ALL] Optimized section handling. [ALL] Optimized label handling. [ALL] Removed support for '*' commenting. [ALL] Added support for special ROM bank header sections. [ALL] Added support for powers ('^') and shifts ('<<' and '>>') in calculations. [ALL] Fixed calculator engine to work better. [ALL] Enhanced calculation detection. [ALL] .DB and .DW take now comma separated data. Make sure to use commas when placing arithmetic calculations inside .DB and .DW data fields. [ALL] .DSW, .DSB, .DW and .DB take labels and pending computations as data. [ALL] The following directives can be redefined as long as the values equal: .ROMBANKS, .EMPTYFILL and .ROMBANKSIZE. [ALL] .ROMBANKMAPs and .ROMBANKS can be redefined as long as they match (as much as possible). WLA will then use the biggest defined ROM bank map. [GB ] The following directives can be redefined as long as the values equal: .NAME, .RAMSIZE, .CARTRIDGETYPE, .LICENSEECODENEW, .LICENSEECODEOLD, .COMPUTECHECKSUM, .COMPUTECOMPLEMENTCHECK, .ROMDMG, .ROMGBC and .ROMSGB. v6.2 (31-Aug-2000) [ALL] Enhanced error messages. [ALL] Enhanced number size checks in the opcode decoding loop. [ALL] Braces are not needed anymore in arithmetics. [ALL] Added a fully functional stack calculator engine. [ALL] Unused local labels don't get smoked anymore. [ALL] WLA could crash when including a file while using the old error message engine. [ALL] Negative values in the 16bit range are now handled with better care. [ALL] When compiling a ROM image and using a section inside direct mapped code WLA would screw up the data. v6.1 (26-Aug-2000) [ALL] Directives accept now definitions as arguments. [ALL] Added more security checks to .MEMORYMAP. [ALL] Optimized .MEMORYMAP building. [ALL] Optimized SLOT usage. [ALL] Added .ROMBANKMAP and .ENDRO. [ALL] .BANKSIZE is now .ROMBANKSIZE. [ALL] 4G worth of ROM banks are supported. [ALL] SLOT numbers start from 0. v6.0 (23-Aug-2000) [ALL] Rewrote and optimized opcode decoding. [ALL] Preprocessing subroutine removed comments from inside data strings. [ALL] Support for old syntax directives is dropped. [ALL] Enhanced the documentation. [ALL] Enhanced the error messages. [ALL] .INCBIN could break the line numbering in the error messaging engine. [ALL] Fixed a bug in .FORCE section handling. [ALL] Added .BANKSIZE. [ALL] Added .MEMORYMAP and .ENDME. [ALL] Added .ENDASM and .ASM. [ALL] '*' can also be used to comment away lines. [ALL] WLA can now test compile (flag t). [ALL] .ROMSIZE is replaced with .ROMBANKS. [ALL] Changed FREE section positioning a little. [Z80] Binary files can be compiled with the flag 'b'. [Z80] Added .HEADER. [Z80] Added .FOOTER. v5.0 (09-Jul-2000) Enhanced brackets detection. Enhanced the documentation. Enhanced error messages. WLA outputs now a NO$GMB symbolic information file along with a ROM image (s flag). .SECTION without a specifier is treated as a FREE section. Optimized directive decoding. Optimized parser loop. If .RAMSIZE is not defined a warning is issued instead of an error. Added SWAP to .INCBIN. Verbose mode shows data usage percentages (per bank as well). WLAD (WLA Disassembler) is now included with the WLA archive. v4.6 (21-Jun-2000) Enhanced the documentation. Optimized directive decoding. "JP (HL)" is now known as "JP HL". GB-Z80 syntax parser supports now brackets as well. WLA doesn't crash if the project's main file is missing. v4.5 (15-Jun-2000) Enhanced the documentation. Fixed the reintroduced '.INCDIR ""'-bug. Target file name can now be left away as WLA has now built in default suffices (.gb, .o and .lib). Added lib-directory to the archive. Trying to compile a compact ROM file will give a warning. v4.4 (09-Jun-2000) Enhanced the documentation. Fixed "RR A"->"RRCA" and "RL A"->"RLCA" transformations. "EI" and "RST $x" were followed by a "NOP"! Hexadecimal and binary values are supported in arithmetics. Optimized number decoding. v4.3 (03-Jun-2000) Enhanced error messages. Number decoding routines are now compatible with the new error messaging system. Optimized define and macro handling. Optimized GB-Z80 opcode decoding. Optimized source file parsing. Very long (typos?) tokens don't crash WLA anymore. .INCDIR accepts directory paths which are not terminated with '/' (or '\' under MSDOS). Added support for very simple arithmetics. Fixed "LD HL, SP+x". Removed "EX HL, (SP)". Added OVERWRITE to .SECTION (patch tool function). Added .BACKGROUND (patch tool function). WLA would crash if the whole project was inside one file, and if the file was not found. "=" can be optionally left away from many directives. Added "JP (HL)". v4.2 (11-Apr-2000) Enhanced documentation. Enhanced error messages. WLA could crash if .REPT wasn't ended with .ENDR. .MACRO and .REPT are now compatible with the new error messaging system. .REPT size is now 2k. v4.1 (29-Mar-2000) Enhanced documentation. Enhanced error messages. Optimized number conversion. Added ANSI-C -like commenting ("/* ... */"). v4.0 (19-Mar-2000) Optimized data parsing. Added a much better error messaging system as default. Added "-f" -option for fast compiling (uses old error messaging system with few enhancements). "LDH (x), A" and "LDH A, (x)" support was broken due to a typo. WLA accepts now negative values as well. WLA's flags and usage changed totally! Read about the changes in the documentation. Input and output files cannot be the same. Enhanced the documentation. v3.0 (20-Feb-2000) Added support for "LDH (x), A", "LDH A, (x)", "LD (HLI), A", "LD (HL+), A", "LD A, (HLI)", "LD A, (HL+)", "LD (HLD), A", LD (HL-), A", "LD A, (HLD)" and "LD A, (HL-)". WLA filters away unreferenced local lables in object/library output mode. MSDOS temporary file directory is now the current working directory. Added "-co" -option for compact object file producing. Added "-cl" -option for compact library file producing. Enhanced .SECTION logic (syntax changed!). Added new error messages. Optimized temporary file usage. Optimized directive decoding. Optimized internal pass 2. Optimized .SECTION handling. Optimized .DSB and .DSW. Optimized pass 1. Optimized .INCLUDE. v2.9 (16-Feb-2000) Section names with spaces crashed WLA. Fixed address bound checking in .BANK. Added more error messages. v2.8 (15-Feb-2000) Added .EXPORT. All strings starting with "." are treated as directives. Directives are not case sensitive any more. Fixed a broken 0x0D filter (in MSDOS text files). Source file ending into a comment could crash WLA. Optimized .INCLUDE. Libraries can now have references outside. Amiga object/library files were not compatible with PC files. Fixed a bug in object file generator that could crash WLA. v2.7 (07-Feb-2000) WLA returns 0 when help information is displayed. WLA returns 1 when execution ended in error. -1 produced ugly error messages on Amiga computers. WLA gives now an error when the user tries to produce a library file which has references to outside. Amiga version has version string. Enhanced some error messages. Enhanced documents. v2.6 (03-Feb-2000) PC relative reference distances inside sections could be more than 127 bytes. v2.5 (29-Jan-2000) Enhanced documents. Fixed GBC indicator from $C0 to $80. v2.4 (26-Jan-2000) Fixed a typo "NET NC" to "RET NC". Enhanced some error messages. Added .ROMGBC, .ROMDMG and .ROMSGB. Rewriting memory with equal data doesn't give an error. v2.3 (23-Jan-2000) Added .SECTION, .ENDS. Added "-l" -option for library file producing. Fixed address calculations a little more. WLA returns -1 when execution ended in error. Local labels are now local to sections or object file. Enhanced the documents. v2.2 (16-Jan-2000) Added .DSW, .DW, .ENUM and .ENDE. v2.1 (14-Jan-2000) Added $BE (Pocket Voice) to supported cartridge types. Added "-v" -option for verbose information displaying. Optimized pass 1. Fixed possible errors in address calculations. v2.0 (12-Jan-2000) Enhanced the documents. Optimized internal pass 2 and directive including. Fixed overflow check (in .ORG). Added "-o" -option for object file producing. Added linker executable "wlalink". Added .INCDIR. v1.9 (06-Jan-2000) Optimized .INCBIN, .INCLUDE and internal passes 1 and 2. v1.8 (23-Dec-1999) Enhanced the documents. Fixed overflow checker once again. Every bank gained one byte more (total 16384). v1.7 (04-Dec-1999) Enhanced the documents. Added gb_hardware.i. .INCBIN didn't free buffer memory. Optimized .INCBIN. .INCBIN now caches all the files. Optimized internal passes 1 and 2. Linux version is optimized for 486. v1.6 (14-Nov-1999) Enhanced the documents. Fixed nintendo_logo.i so it works on a real Game Boy. Fixed complement check calculation to work. Overflow checker thought GB ROM banks were 8KB each! Fixed to 16KB. Ville no baka! Added .REPT. Added .ENDR. v1.5 (10-Jun-1999) Enhanced the documents. WLA does now one pass to the input data and two passes to the internal data. v1.4 (25-May-1999) Renamed nintendo_logo.s to nintendo_logo.i. Fixed nintendo_logo.i Wzonka-Lad-compatible. Fixed pass-texts, as WLA does actually one pass, three of the old ones were made to the WLA's internal data. Added one funky new optcode, "DEBUG", which will translate to $ED (unused in GB-Z80). This one will flash the power light when executed on Wzonka-Lad, my Game Boy emulator. Use it only for debugging! v1.3 (01-Jan-1999) Enhanced the documents. WLA now shows the unused areas of the ROM file after a successful compile in hexadecimal format. Many WLA directives accepted non-pure values, not anymore. Added .DSB. .DB handles now strings as well. v1.2 (21-Dec-1998) Enhanced the documents. Added a list ("gb-z80.txt") of the supported GB-Z80 commands to the archive. Free strings don't break the compile loop anymore. Added .INCBIN. v1.1 (13-Dec-1998) Enhanced the documents. Removed an unused function. Number input now detects and discards numbers from outside the word boundaries. WLA now shows the unused areas of the ROM file after a successful compile. Added .IFNDEF. Added .IFDEF. Added .ELSE. Added .ENDIF. Added @@@ to .MACRO. .DB accepted values from outside the byte boundaries. v1.0 (12-Dec-1998) The first public release. ------------------------------------------------------------------------------ 3... WLAB History ------------------------------------------------------------------------------ v1.1 (04-Sep-2000) Uses now WLA v6.3+ syntax (introduced commas). Accepts now files bigger than 64KB. v1.0 (23-Aug-2000) The first public release. ------------------------------------------------------------------------------ 4... WLAD History ------------------------------------------------------------------------------ v1.3 (21-Oct-2000) String detection works better. v1.2 (01-Sep-2000) SLOT numbers are handled correctly. Uses ROMBANKS instead of ROMSIZE. String detection works better. v1.1 (23-Aug-2000) Added flag 'a' to disable address output. v1.0 (10-Jul-2000) The first public release. ------------------------------------------------------------------------------ 5... WLALINK History ------------------------------------------------------------------------------ v3.8 (02-Feb-2001) Supported object file format is now "WLAB" for non GB-Z80 systems (adds checksum computing). Due to a typo the bank number of the pending calculation could get corrupted in object file parsing. v3.7 (08-Oct-2000) Added support for 6510. v3.6 (07-Oct-2000) Added support for 65816 (24bit values). v3.5 (24-Sep-2000) Added support for program file output (!GB, flag b). NO$GMB symbol files can also be written (!GB). Fxied few byte size checks. Header and footer sizes are now shown in the verbose mode's result information. v3.4 (09-Sep-2000) Label duplicate checker didn't handle local labels correctly. Added support for modulo in calculations. Added support for SEMIFREE sections. Computations are now computed internally with higher precision when possible and the result is converted to an integer. v3.3 (04-Sep-2000) Enhanced error messages. Added support for powers and shifts in calculations. Added support for special ROM bank header sections. Labels' slot and bank numbers inside library files could get corrupted. Optimized label handling. v3.2 (31-Aug-2000) The supported file formats are only "WLAP", "WLA9" (GB-Z80) and "WLAA" (Z80). Added a fully functional stack calculator engine. Objects with different ROM sizes can be combined, and the result will use the biggest ROM size found as long as the sizes of the ROM banks match. Optimized file parsers. Enhanced error messages. v3.1 (26-Aug-2000) The supported file formats are only "WLAO", "WLA7" (GB-Z80) and "WLA8" (Z80). Exported definitions were handled incorrectly. Memory overwrite warnings were displayed when fixing relative addresses. v3.0 (23-Aug-2000) The supported file formats are only "WLAO", "WLA5" (GB-Z80) and "WLA6" (Z80). Rewrote 30% of the code. WLALINK arguments changed! WLALINK needs now a linkfile. v2.0 (09-Jul-2000) WLALINK outputs now NO$GMB symbolic information files along with a ROM image (flag s). Verbose mode shows data usage percentages (per bank as well). v1.9 (25-May-2000) Added support for WLA v4.3's .SECTION OVERWRITE. v1.8 (20-Feb-2000) The supported file formats are only "WLAN" and "WLA4". WLALINK uses now less memory. Enhanced some error messages. v1.7 (15-Feb-2000) Added support for WLA's .EXPORT. Enhanced some error messages. Optimized ROM file generation. The supported file formats are only "WLAM" and "WLA3". Amiga object/library files were not compatible with PC files. v1.6 (07-Feb-2000) WLALINK returns 0 when help information is displayed. Amiga version has version string. v1.5 (03-Feb-2000) PC relative reference distances inside sections could be more than 127 bytes. Enhanced some error messages. v1.4 (31-Jan-2000) Duplicate labels positioned in different places in Game Boy memory map break the linking loop. Fixed object identifier, verbose mode screwed up the names. Enhanced some error messages. Referencing to a label inside a section more than once screwed up the label's address. v1.3 (26-Jan-2000) Rewriting memory with equal data doesn't give an error. Enhanced some error messages. v1.2 (23-Jan-2000) Added support for library files. v1.1 (14-Jan-2000) Added support for Pocket Voice. Added "-v" -option for verbose information displaying. WLALINK now checks the object file formats. v1.0 (12-Jan-2000) The first public release. ------------------------------------------------------------------------------ 6... 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, 6510 and 65816 versions apply. [GB ] - Only the GB-Z80 version applies. [658] - Only the 65816 version applies. [65x] - Only the 6502, 6510 and 65816 versions apply. [!GB] - Only the Z80, 6502, 6510 and 65816 versions apply. Group 1: [GB ] .COMPUTECHECKSUM [Z80] .COMPUTESMSCHECKSUM Group 2: [GB ] .CARTRIDGETYPE 1 [GB ] .COMPUTECOMPLEMENTCHECK [ALL] .EMPTYFILL $C9 [ALL] .EXPORT work_x [!GB] .FOOTER "abc.bin" [!GB] .HEADER "xyz.bin" [GB ] .LICENSEECODENEW "1A" [GB ] .LICENSEECODEOLD $1A [GB ] .NAME "NAME OF THE ROM" [GB ] .RAMSIZE 0 [GB ] .ROMDMG [GB ] .ROMGBC [GB ] .ROMSGB Group 3: [65x] .16BIT [658] .24BIT [65x] .8BIT [ALL] .ASM [ALL] .BACKGROUND "parallax.gb" [ALL] .BANK 0 SLOT 1 [ALL] .ROMBANKSIZE $4000 [ALL] .DB 100, $30, %1000, "HELLO WORLD!" [ALL] .DBCOS 0.2, 10, 3.2, 120, 1.3 [ALL] .DBSIN 0.2, 10, 3.2, 120, 1.3 [ALL] .DEFINE IF $FF0F [ALL] .DSB 256 $10 [ALL] .DSW 128 20 [ALL] .DW 16000, 10, 255 [ALL] .DWCOS 0.2, 10, 3.2, 1024, 1.3 [ALL] .DWSIN 0.2, 10, 3.2, 1024, 1.3 [ALL] .ELSE [ALL] .ENDASM [ALL] .ENDE [ALL] .ENDIF [ALL] .ENDM [ALL] .ENDME [ALL] .ENDR [ALL] .ENDRO [ALL] .ENDS [ALL] .ENUM $C000 [ALL] .FAIL [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" [ALL] .MACRO TEST [ALL] .MEMORYMAP [ALL] .ORG $150 [ALL] .PRINTT "Here we are...\n" [ALL] .PRINTV DEC DEBUG+1 [ALL] .REDEFINE IF $F [ALL] .REPT 6 [ALL] .ROMBANKS 2 [ALL] .ROMBANKMAP [ALL] .SECTION "Init" FORCE [ALL] .UNDEF DEBUG 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. This is not a compulsory directive. ------ .16BIT ------ Analogous to .8BIT. .16BIT forces all addresses and 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. ---- .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. ----------------------------- .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. Angles range from 0 to 359, 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 defined. 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. .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. 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). This is not a compulsory directive. ----------------------- .NAME "NAME OF THE ROM" ----------------------- Fills the 16 bytes ranging from $134 to $143 with the provided string. If the string is shorter than 16 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. ---------------- .COMPUTECHECKSUM ---------------- 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. 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 ROM. Note that this directive can only be used with wla-z80. 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. ----------------------- .COMPUTECOMPLEMENTCHECK ----------------------- When this directive is used WLA computes the ROM complement check found at $14D in a GB ROM. This is not a compulsory directive, but very recommended. ;) -------------------------------------- .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 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. 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. ------------------------- .BACKGROUND "parallax.gb" ------------------------- This chooses an existing ROM image (parallax.gb in this case) as a background data for project. You can overwrite the data with OVERWRITE sections only. With .BACKGROUND defined you can leave away .ROMSIZE, .ROMTYPE and .RAMTYPE. .BACKGROUND can be used only when compiling a ROM image, not library or 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. ----- .FAIL ----- Terminates the compiling process. This is not a compulsory directive. ----------- .MACRO TEST ----------- Begins a macro called 'TEST'. WLA v6.4 introduced finally a nice little macro language that can handle macro parameters. You can use '\@' inside a macro to eg. 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. Also, if you want to use macro arguments in eg. calculation, you can type '\X' where X is the number of the argument. X ranges from 1 to 256 as you can give maximum of 256 parameters to a macro. Remember to use .ENDM to finish the macro definition. Note that you cannot use .INCLUDE inside a macro. With WLA v7.0+ you can call macros from inside a macro. Note that the preprocessor code does not expand the macros. WLA jumps through the code according to the macro calls. 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 And here's how they can be used: NOPMONSTER LOAD_ABCD $10, $20, $30, XYZ, "merman.bin" QUEEN 123 Note that you must separate the arguments with commas. Every time a macro is called a definition NARGS is created. It shows only inside the macro and holds the amount 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 the macro. This is not a compulsory directive, but when .MACRO is used this one is required to terminate it. -------------- .BANK 0 SLOT 1 -------------- Defines the ROM bank and the slot it is inserted into in the memory. You can also type the following: .BANK 0 This tells WLA to move into BANK 0 which will be put into the DEFAULTSLOT of .MEMORYMAP. This is a compulsory directive. ------------------ .ROMBANKSIZE $4000 ------------------ Defines the ROM bank size. Old syntax is ".BANKSIZE x". This is a compulsory directive unless .ROMBANKMAP is defined. --------- .ORG $150 --------- Defines the starting address. The value supplied here is relative to the ROM bank given with .BANK. This is a compulsory directive. ------------ .DSB 256 $10 ------------ Defines 256 bytes of $10. This is not a compulsory directive. ----------- .DSW 128 20 ----------- Defines 128 words (two bytes) of 20. This is not a compulsory directive. ----------------------------------- .DB 100, $30, %1000, "HELLO WORLD!" ----------------------------------- Defines bytes. This is not a compulsory directive. ------------------ .DW 16000, 10, 255 ------------------ Defines words (two bytes each). .DW takes only numbers and characters as input, not strings. This is not a compulsory directive. ---------------- .DEFINE IF $FF0F ---------------- Assigns a number or a string to a definition label. By default all defines are local to the file where they are presented. If you want to make the definition visible to all the files in the project, use .EXPORT. This is not a compulsory directive. ---------------- .REDEFINE IF $0F ---------------- Assigns a new value or a string to an old definition. If the definition doesn't exist, REDEFINE performs DEFINE's work. When used with .REPT REDEFINE helps creating tables: .DEFINE CNT 0 .REPT 256 .DB CNT .REDEFINE CNT CNT+1 .ENDR This is not a compulsory directive. -------------- .IF DEBUG == 2 -------------- If the condition is fulfilled the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped. Operands must be immediate values. The following operators are supported: < - smaller than <= - smaller or equal to > - greater than >= - greater or equal to == - equals to != - doesn't equal to All IF (yes, including .IFDEF, .IFNDEF, etc) directives can be nested. This is not a compulsory directive. --------- .IFDEF IF --------- If "IF" is defined, then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped. This is not a compulsory directive. ------------------ .IFEXISTS "main.s" ------------------ If "main.s" file can be found, then the following piece of code is acknowledged until .ENDIF/.LESE occurs in the text, otherwise it is skipped. By writing the following few lines you can include a file if it exists without breaking the compiling loop if it doesn't exist. .IFEXISTS FILE .INCLUDE FILE .ENDIF This is not a compulsory directive. ------------ .UNDEF DEBUG ------------ Removes the supplied definition label from system. If there is no such label as given no error is displayed as the result would be the same. This is not a compulsory directive. ---------- .IFNDEF IF ---------- If "IF" is not defined, then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped. This is not a compulsory directive. ---------- .IFDEFM \2 ---------- If the specified argument is defined (argument number two, in the example), then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the macro, otherwise it is skipped. This is not a compulsory directive. .IFDEFM works only inside a macro. ----------- .IFNDEFM \2 ----------- If the specified argument is not defined, then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the macro, otherwise it is skipped. This is not a compulsory directive. .IFNDEFM works only inside a macro. ------------- .IFEQ DEBUG 2 ------------- If the value of DEBUG equals to 2, then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped. Both arguments can be computations, defines or immediate values. This is not a compulsory directive. -------------- .IFNEQ DEBUG 2 -------------- If the value of DEBUG doesn't equal to 2, then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped. Both arguments can be computations, defines or immediate values. This is not a compulsory directive. ------------- .IFLE DEBUG 2 ------------- If the value of DEBUG is less than 2, then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped. Both arguments can be computations, defines or immediate values. This is not a compulsory directive. --------------- .IFLEEQ DEBUG 2 --------------- If the value of DEBUG is less or equal to 2, then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped. Both arguments can be computations, defines or immediate values. This is not a compulsory directive. ------------- .IFGR DEBUG 2 ------------- If the value of DEBUG is greater than 2, then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped. Both arguments can be computations, defines or immediate values. This is not a compulsory directive. --------------- .IFGREQ DEBUG 2 --------------- If the value of DEBUG is greater or equal to 2, then the following piece of code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped. Both arguments can be computations, defines or immediate values. This is not a compulsory directive. ----- .ELSE ----- If the previous .IFxxx failed then the following text until .ENDIF is acknowledged. This is not a compulsory directive. ------ .ENDIF ------ This terminates any .IFxxx directive. This is not a compulsory directive, but if you use any .IFxxx then you need also to apply this. ------- .REPT 6 ------- Repeats the text enclosed between ".REPT x" and ".ENDR" x times (6 in this example). You can use .REPTs inside .REPTs. This is not a compulsory directive. ----- .ENDR ----- Ends the repetition. This is not a compulsory directive, but when .REPT is used this one is required to terminate it. ----------- .ENUM $C000 ----------- Starts enumeration from $C000. Very useful for defining variables. Here's an example: ... .ENUM $A000 _scroll_x DB _scroll_y DB player_x DW player_y DW map_01 DS 1024 map_02 DS 2048 .ENDE ... Previous example transforms into following definitions: .DEFINE _scroll_x $A000 .DEFINE _scroll_y $A001 .DEFINE player_x $A002 .DEFINE player_y $A004 .DEFINE map_01 $A006 .DEFINE map_02 $A406 DB, DW and DS can also be in lowercase. You can also use a dot version of the symbols, but it doesn't advance the memory address. Here's an exmple: .ENUM $C000 bigapple .dw bigapple_l db bigapple_h db .ENDE And this what is generated: bigapple $C000 bigapple_l $C000 bigapple_h $C001 This way you can generate a 16bit variable address along with pointers to its parts. This is not a compulsory directive. ----- .ENDE ----- Ends the enumeration. This is not a compulsory directive, but when .ENUM is used this one is required to terminate it. ---------- .MEMORYMAP ---------- Begins the memory map definition. Using .MEMORYMAP you must first describe the target system's memory architecture to WLA before it can start to compile the code. .MEMORYMAP gives you the freedom to use WLA Z80/6502/6510/65816 to compile data for numerous different real Z80/6502/6510/65816 based systems. Examples: .MEMORYMAP SLOTSIZE $4000 DEFAULTSLOT 2 SLOT 0 $0000 SLOT 1 $4000 .ENDME .MEMORYMAP DEFAULTSLOT 1 SLOTSIZE $6000 SLOT 0 $0000 SLOTSIZE $2000 SLOT 1 $6000 SLOT 2 $8000 .ENDME SLOTSIZE defines the size of the following slots. You can redefine it as many times as you wish, like in the second example. DEFAULTSLOT describes the default slot for banks which aren't explicitly inserted anywhere. Check .BANK definition for more information. SLOT defines a slot and its starting address. SLOT numbering starts at 0 and ends to 255 so you have 256 slots at your disposal. This is a compulsory directive, and make sure all the object files share the same .MEMORYMAP or you can't link them together. ------ .ENDME ------ Ends the memorymap. This is not a compulsory directive, but when .MEMORYMAP is used this one is required to terminate it. ----------- .ROMBANKMAP ----------- Begins the ROM bank map definition. You can use this directive to describe the project's ROM banks. Use .ROMBANKMAP when not all the ROM banks are of equal size. Note that you can use .ROMBANKSIZE and .ROMBANKS instead of .ROMBANKMAP, but that's only when the ROM banks are equal in size. Some systems based on a real Z80 chip, 6502/6510/65816 CPUs and Pocket Voice cartridges for Game Boy require the usage of this directive. Examples: .ROMBANKMAP BANKSTOTAL 16 BANKSIZE $4000 BANKS 16 .ENDRO .ROMBANKMAP BANKSTOTAL 510 BANKSIZE $6000 BANKS 1 BANKSIZE $2000 BANKS 509 .ENDRO The first one describes an ordinary ROM image of 16 equal sized banks. The second one defines a 4MB Pocket Voice ROM image. In the PV ROM image the first bank is $6000 bytes and the remaining 509 banks are smaller ones, $2000 bytes each. BANKSTOTAL tells the total amount of ROM banks. It must be defined prior to anything else. BANKSIZE tells the size of the following ROM banks. You can supply WLA with BANKSIZE as many times as you wish. BANKS tells the amount of banks that follow and that are of the size BANKSIZE which has been previously defined. This is not a compulsory directive when .ROMBANKSIZE and .ROMBANKS are defined. You can redefine .ROMBANKMAP 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. ------ .ENDRO ------ Ends the rom bank map. This is not a compulsory directive, but when .ROMBANKMAP is used this one is required to terminate it. --------------------- .SECTION "Init" FORCE --------------------- Begins a section called "Init". Before a section can be declared, .BANK and .ORG must be used unless WLA is in library file output mode. Library file's sections must all be FREE ones. .BANK tells the bank number where this section will be later relocated into. .ORG tells the offset for the relocation from the beginning of .BANK. You can supply the preferred section size (bytes) inside the section name string. Here's an example: .SECTION "Init_100" will create a section ("Init") with size of 100 bytes, unless the actual data overflows from the section, in which case the section size is enlarged to contain all the data. FORCE after the name of the section tells WLA that the section _must_ be inserted so it starts at .ORG. FORCE can be replaced with FREE which means that the section can be inserted somewhere in the defined bank, where there is room. You can also use OVERWRITE to insert the section into the memory regardless of data collisions. Using OVERWRITE you can easily patch an existing ROM image just by .BACKGROUND'ing the data and inserting an OVERWRITE section into it. SEMIFREE sections are also possible and they behave much like FREE sections. The only difference is that they are positioned somewhere in the bank starting from .ORG. You can also leave away the type specifier as the default type for the section is FREE. You can name the sections as you wish, but there is one special name. A section called "BANKHEADER" is placed in the front of the bank where it is defined. These sections contain data that is not in the memory map of the machine, so you can't refer to the data of a BANKHEADER section, but you can write references to outside. So no labels inside BANKHEADER sections. These special sections are useful when writing eg. MSX programs. Note that library files don't take BANKHEADER sections. Here's an example of a "BANKHEADER" section: .BANK 0 .ORG 0 .SECTION "BANKHEADER" .DW MAIN .DW VBI .ENDS .SECTION "Program" MAIN: CALL monty_on_the_run VBI: PUSH HL ... POP HL RETI .ENDS Here's an example of an ordinary section: .BANK 0 .ORG $150 .SECTION "Init" FREE DI LD SP, $FFFE SUB A LD ($FF00+R_IE), A .ENDS This tells WLA that a FREE section called "Init" must be located somewhere in bank 0. If you replace FREE with SEMIFREE the section will be inserted somewhere in the bank 0, but not in the $0-$14F area. This is not a compulsory directive. ----- .ENDS ----- Ends the section. This is not a compulsory directive, but when .SECTION is used this one is required to terminate it. ------- .ROMGBC ------- Inserts data into the specific ROM location to mark the ROM as a GBC ROM ($C0 -> $0143, so ROM name is max. 15 characters long). This is not a compulsory directive. ------- .ROMDMG ------- Inserts data into the specific ROM location to mark the ROM as a DMG ROM ($00 -> $0146). This is not a compulsory directive. .ROMDMG cannot be used with .ROMSGB. ------- .ROMSGB ------- Inserts data into the specific ROM location to mark the ROM as a SGB enhanced ROM ($03 -> $0146). This is not a compulsory directive. .ROMSGB cannot be used with .ROMDMG. -------------- .EXPORT work_x -------------- Exports the definition "work_x" to outside. .EXPORT can only be used inside object and library files. Exported definitions are visible to all object files and libraries in the linking procedure. Note that you can only export value definitions, not string definitions. This is not a compulsory directive. ----------------- .HEADER "xyz.bin" ----------------- Uses the file "xyz.bin" as a header for the ROM image. HEADER can only be used in ROM output mode and with wla-z80. This is not a compulsory directive. ----------------- .FOOTER "abc.bin" ----------------- Uses the file "abc.bin" as a footer for the ROM image. FOOTER can only be used in ROM output mode and with wla-z80. This is not a compulsory directive. -------------------------- .PRINTT "Here we are...\n" -------------------------- Prints the given text into stdout. Good for debugging stuff. PRINTT takes only a string as argument, and the only supported formatting symbol is '\n' (line feed). This is not a compulsory directive. ------------------- .PRINTV DEC DEBUG+1 ------------------- Prints the value of the supplied definition or computation into stdout. Computation must be solvable at the time of printing (just like definitions values). PRINTV takes two parameters. The first describes the type of the print output. "DEC" means decimal, "HEX" means hexadecimal. Use PRINTV with PRINTT as PRINTV doesn't print linefeeds, only the result. Here's an example: .PRINTT "Value of \"DEBUG\" = $" .PRINTV HEX DEBUG .PRINTT "\n" This is not a compulsory directive. ------------------------------------------------------------------------------ 7... Assembler Syntax ------------------------------------------------------------------------------ 7.1. Case Sensitivity WLA is case sensitive, so be careful. By default directives are not case sensitive. If you wish to speed up compiling, use uppercase directives and flag 'u' (uppercase mnemonics). 7.2. Comments Comments begin with ';' or '*' and end along with the line. ';' can be used anywhere, but '*' can be placed only at the beginning of a new line. Version 4.1 of WLA introduced ANSI-C -like commenting. This means you can start a multiline comment with "/*" and end it with "*/". Version 6.0 of WLA introduced .ASM and .ENDASM directives. These function much like ANSI-C comments, but unlike the ANSI-C comments these can be nested. 7.3. Labels Labels are ordinary strings that end to ':'. Labels starting with "_" are considered as local labels and do not show outside sections where they were defined, or outside object files, if they were not defined inside a section. Here are few examples of different labels: VBI_IRQ: _VBI_LOOP: main: 7.4. Number Types 1000 - decimal. $100 - hexadecimal. %100 - binary. 'x' - character. All numbers must be integers. *SIN/*COS -families are exceptions as they take real numbers as some of their arguments. 7.5. Strings Strings begin with and end to '"'. Note that no 0 is inserted to indicate the termination of the string like in eg. ANSI C. You'll have to do it yourself. You can place quotation marks inside strings the way C preprocessors accept them. Here are some examples of strings: "Hello world!" "He said: \"Please, kiss me honey.\"" 7.6. Supported Mnemonics Check out the files (under the directory "systems") "gb-z80.txt" for GB-Z80, "z80.txt" for Z80, "6502.txt" for 6502, "6510.txt" for 6510 and "65816.txt" for 65816 mnemonics and platform specific compiling information. Additionally there is an extra mnemonic in the GB-Z80 version of WLA called "DEBUG" which will translate to $ED. This one is not used in real GB-Z80, but my Game Boy emulator, Wzonka-Lad, will invert the power light mode when $ED is executed. Don't use DEBUG if you are going to use your code elsewhere! 7.7. Brackets? With v4.6+ of WLA brackets are also supported in the GB-Z80/Z80/6502/6510 syntax. So you can write LDI (HL), A or LDI [HL], A Yes, you could write LDI [HL), A but I don't recommend that. ;) Note that brackets have special meaning when dealing with a 65816 system so you can't use AND [$65] instead of AND ($65) as they mean different things. ------------------------------------------------------------------------------ 8... Error Messages ------------------------------------------------------------------------------ There are quite a few of them in WLA, but most of them are not as informative as I would like them to be. This will be fixed in the future. Mean while, be careful. ;) ------------------------------------------------------------------------------ 9... Supported Types ------------------------------------------------------------------------------ 9.1. ROM Size GB-Z80 version of WLA supports the following ROM bank sizes. There's no such limit in the Z80/6502/6510/65816 version of WLA. Supply one of the following values to .ROMBANKS. $0 - 256Kbit = 32KByte = 2 banks $1 - 512Kbit = 64KByte = 4 banks $2 - 1Mbit = 128KByte = 8 banks $3 - 2Mbit = 256KByte = 16 banks $4 - 4Mbit = 512KByte = 32 banks $5 - 8Mbit = 1MByte = 64 banks $6 - 16Mbit = 2MByte = 128 banks $52 - 9Mbit = 1.1MByte = 72 banks $53 - 10Mbit = 1.2MByte = 80 banks $54 - 12Mbit = 1.5MByte = 96 banks 9.2. RAM Size Supply one of the following hex values to .RAMSIZE in the GB-Z80 version of WLA. $0 - None $1 - 16kbit = 2kByte = 1 bank $2 - 64kbit = 8kByte = 1 bank $3 - 256kbit = 32kByte = 4 banks $4 - 1Mbit = 128kByte = 16 banks 9.3. Cartridge Type It's up to the user to check that the cartridge type is valid and can be used combined with the supplied ROM and RAM sizes. Give one the the following values to .CARTRIDGETYPE in the GB-Z80 version of WLA. $0 - ROM ONLY $1 - ROM+MBC1 $2 - ROM+MBC1+RAM $3 - ROM+MBC1+RAM+BATT $5 - ROM+MBC2 $6 - ROM+MBC2+BATTERY $8 - ROM+RAM $9 - ROM+RAM+BATTERY $B - ROM+MMM01 $C - ROM+MMM01+SRAM $D - ROM+MMM01+SRAM+BATT $F - ROM+MBC3+TIMER+BATT $10 - ROM+MBC3+TIMER+RAM+BATT $11 - ROM+MBC3 $12 - ROM+MBC3+RAM $13 - ROM+MBC3+RAM+BATT $19 - ROM+MBC5 $1A - ROM+MBC5+RAM $1B - ROM+MBC5+RAM+BATT $1C - ROM+MBC5+RUMBLE $1D - ROM+MBC5+RUMBLE+SRAM $1E - ROM+MBC5+RUMBLE+SRAM+BATT $1F - Pocket Camera $BE - Pocket Voice $FD - Bandai TAMA5 $FE - Hudson HuC-3 $FF - Hudson HuC-1 ------------------------------------------------------------------------------ 10.. Bugs ------------------------------------------------------------------------------ If you find bugs, please let me know asap. Anything, small or big, send me email! ------------------------------------------------------------------------------ 11.. Files ------------------------------------------------------------------------------ 11.1. 'examples' The main purpose of the files in the 'examples' directory is to teach people few things about WLA. If you feel a little uncertain with the syntax check out this place. 'examples' directory holds five directories, 'gb-z80', 'z80', '6502', '6510' and '65816'. 'include' directory under 'gb-z80' could be very useful as the five include files there have all the Game Boy hardware register address and memory definitions you could ever need and more. 11.2. 'examples/gb-z80/lib' This folder holds few very useful libraries for you to use in your Game Boy projects. Instead of reinventing the wheel, use the stuff found in here. Remember to compile the libraries right after you've installed WLA by executing 'make' in the 'lib' directory. ------------------------------------------------------------------------------ 12.. Temporary Files ------------------------------------------------------------------------------ Note that WLA will generate two temporary files while it works. Both files are placed into the current working directory. Under Amiga: "wla_a.tmp" and "wla_b.tmp". Under MSDOS: "wla_a.tmp" and "wla_b.tmp". Under Unix: ".wla%PID%a" and ".wla%PID%b" (where %PID% is the process id). When WLA finishes its work these two files are deleted as they serve of no further use. ------------------------------------------------------------------------------ 13.. Compiling ------------------------------------------------------------------------------ 13.1. Compiling ROM images To compile a ROM image from an asm file use the following: "wla -[fstuvx]r [OUTPUT FILE]" One asm file (or more included in the main asm file), one ROM image. Simple, but not very flexible. Compile object files and link them together in the case of a bigger project. 13.2. Compiling Object Files Version 2.0 of WLA introduced object files. To compile an object file use: "wla -[ftuvx]o [OUTPUT FILE]" These object files can be linked together (or with library files) later with "wlalink". Name object files so that they can be recognized as object files. Normal suffix is ".o" (WLA default). With object files you can reduce the amount of compiling when editing small parts of the program. Note also the possibility of using local labels (starting with "_"). Note! When you compile objects, group 1 directives are saved for linking time, when they are all compared and if they differ, an error message is shown. It is advisable to use something like an include file to hold all the group 1 directives for that particular project and include it to every object file. If you are interested in the WLA object file format, take a look at the file "txt/wla_file_formats.txt" which is included in the release archive. 13.3. Compiling Compact Object Files Version 3.0 of WLA introduced compact object files. To compile a compact object file use: "wla -[ftuvx]co [OUTPUT FILE]" Compact object files are just like object files, but the local labels are made as small as possible by renaming them to short, cryptic strings like "_a" and "_9e" to save space. 13.4. Compiling Library Files Version 2.3 of WLA introduced library files. To compile a library file use: "wla -[cftuvx]l [OUTPUT FILE]" Name object files so that they can be recognized as library files. Normal suffix is ".lib" (WLA default). With library files you can reduce the amount of compiling. Library files are meant to hold general functions that can be used in different projects. Note also the possibility of using local labels (starting with "_"). Library files consist only of FREE sections. 13.5. Compiling Compact Library Files Version 3.0 of WLA introduced compact library files. To compile a compact library file use: "wla -[ftuvx]cl [OUTPUT FILE]" Compact library files are just like library files, but the local labels are made as small as possible by renaming them to short, cryptic strings like "_a" and "_9e" to save space. 13.6. Compiling Program Files Version 6.0 of WLA Z80 introduced program files. Program file's size is arbitrary and defined by the amount of compiled data. Let's say you give 32KB bounds (rom size) to WLA and have two sections in it, one starting at 0 and ending at 100, the other starting at 200 and ending at 511. If WLA was to make a program compile out of this, you'd end up having a file of 512 bytes worth your data. It'd have 98 unused bytes also. Anyway, I guess you'll get the idea. ;) Nowadays it's possible to compile program files with WLA Z80, 6502, 6510 and 65816. Only the GB version is restricted to ROM images as it's the only possible format on that platform. To compile a program file, write: "wla -[fstuvx]b [OUTPUT FILE]" All ROM image compiling rules apply to program file compiling. Note that depending on the destination system your result program file might need a header of some kind. Use "BANKHEADER" section for bank 0 to achieve this. Also note that to achieve the most compact program file make all your sections FREE ones or don't use sections at all. This way you will avoid the gaps between static and free sections. ------------------------------------------------------------------------------ 14.. Arithmetics ------------------------------------------------------------------------------ With the coming of WLA DX v6.2 WLA has been able to solve complex calculations like -((HELLO / 2) | 3) skeletor_end-skeletor Before v6.2 there were severe limitations in the computation sentences, but those are void forever. ;) So now you can type something like LD HL, data_end-data LD A, (pointer + 1) CP (TEST + %100) & %10101010 WLALINK also has this ability so it can compute the pending calculations WLA wasn't able to solve. The following operators are valid: (, ), | (or), & (and), ^ (power), << (shift left), >> (shift right), +, -, # (modulo), * and /. WLA computes internally with real numbers so (5/2)*2 produces 5, not 4. ------------------------------------------------------------------------------ 15.. Linking ------------------------------------------------------------------------------ After you have produced one or more object files and perhaps some library files, you might want to link them together to produce a ROM image. "wlalink" is the program you use for that. Here's how you use it: "wlalink [-vs] " Link file is a text file which contains information about the files you want to link together. Here's the format: 1. You must define the group for the files. Put the name of the group inside brackets. Valid group definitions are [objects] [libraries] Z80/6502/6510/65816 linking will also support these two: [header] [footer] 2. Start to list the file names. [objects] main.o vbi.o level_01.o ... 3. Give parameters to the library files: [libraries] bank 0 slot 1 speed.lib bank 4 slot 2 map_data.lib ... You must tell WLALINK the bank and the slot for the library files. 4. If you want to use header and/or footer in your Z80/6502/6510/65816 project, you can type the following: [header] header.dat [footer] footer.dat If flag "v" is used, WLALINK displays information about ROM file after a succesful linking. If flag "s" is used, WLALINK will produce a NO$GMB symbol file. It's useful when you work under MSDOS (NO$GMB is a very good Game Boy emulator for MSDOS/ Windows) as it contains information about the labels in your project. Make sure you don't create duplicate labels in different places in Game Boy memory map as they break the linking loop. Duplicate labels are allowed when they overlap each other in the destination machine's memory. Look at the following example: ... .BANK 0 .ORG $150 ... LD A, 1 CALL LOAD_LEVEL ... LOAD_LEVEL: LD HL, $2000 LD (HL), A CALL INIT_LEVEL RET .BANK 1 .ORG 0 INIT_LEVEL: ... RET .BANK 2 .ORG $0 INIT_LEVEL: ... RET ... Here duplicate INIT_LEVEL labels are accepted as they both point to the same memory address. ------------------------------------------------------------------------------ 16.. Disassembling ------------------------------------------------------------------------------ WLAD is a disassembler that can be used to disassemble an existing ROM image into a WLA-syntax compatible source file. It won't produce very readable code as all the labels etc. are discarded in the last phase of linking when the ROM image is made. In the current state WLAD doesn't generate labels, but it will in the future. Here's how you use it: "wlad [-dsa] " Give it the binary file (usually the extension is .gb or .cgb) and WLAD will output the source code into stdout (the shell you are using). Here's an example what you can do if you want the source code into a file instead of the screen: "wlad tbp.cgb > tbp.s" WLAD has three option flags: a - Disable address output. d - The upper banks (1->) are disassembled as data. s - The upper banks (1->) are disassembled as data with string detection enabled. Use the 's'-flag if you intend to change texts in games. The flags 'd' and 's' cannot be used at the same time. Examples: [root@jaakkopotti parallax]# wlad -da parallax.gb > parallax.s [root@jaakkopotti parallax]# wlad -s parallax.gb > parallax.s WLAD supports both normal ROMs and Pocket Voice (tm) ROM images. Only WLAD GB-Z80 exists curently. ------------------------------------------------------------------------------ 17.. Binary to DB Conversion ------------------------------------------------------------------------------ WLAB converts binary files to WLA's byte definition strings. Here's how you use it: "wlab -[ap]{bdh} " Give it the binary file and WLAB will output the WLA DB formatted data of it into stdout. Here's an example from real life: "wlad -da gayskeletor.bin > gayskeletor.s" WLAB has three command flags of which one must be given to WLAB: b - Output data in binary format. d - Output data in decimal format. h - Output data in hexadecimal format. WLAB has also two option flags: a - Print the address (relative to the beginning of the data). p - Don't print file header. Examples: [root@jaakkopotti src]# wlab -bap iscandar.bin > iscandar.s [root@jaakkopotti src]# wlab -h starsha.bin > starsha.s ------------------------------------------------------------------------------ 18.. Pocket Voice ------------------------------------------------------------------------------ Pocket Voice uses its own MBC. You can enable Pocket Voice mode by selecting Pocket Voice cartridge type ($BE in $0147) and defining correct .ROMBANKMAP and .MEMORYMAP. In PV mode bank 0 is 24KB and the rest are 8KB. Note that WLA assumes that ROM offset is all the time 0. If you use something else as the offset, make sure to compute the jumps by hand as WLA cannot do that. Check out examples/gb/includes/pocket_voice.i for more information. ------------------------------------------------------------------------------ 19.. WLA Flags ------------------------------------------------------------------------------ Here are short descriptions for the flags you can give to WLA: You can supply WLA with some (or all or none) of the following option flags. c - Compact mode. Can be used when compiling a library or an object. Minimizes the size of the local labels. f - Fast mode. Turns on the old error messaging engine (v3.0-), which lacks among other things line numbers. Fast is fast, but for advanced users only. s - Output NO$GMB symbol file. Targetted to people who want to do some GB debugging. Works only when compiling a ROM image. t - Test compile. Doesn't output any files. u - Opcodes are written with uppercase letters. This will speed up compiling process, but all the opcodes must be written with uppercase letters. v - Verbose mode. Shows a lot of information about the compiling process. x - Extra compile time definitions. WLA does extra work by creating few helpful definitions on the fly. One (and only one) of the following command flags must be defined. l - Output a library file. o - Output an object file. r - Output a ROM image. b - Output program file (not in WLA GB-Z80). Examples: [root@jaakkopotti tbp]# wla -vucfo testa.s [root@jaakkopotti tbp]# wla -fcl testb.s testb.lib [root@jaakkopotti tbp]# wla -vr testc.s mygame.gb Note that the first example produces file named "testa.o". ------------------------------------------------------------------------------ 20.. Compile time definitions ------------------------------------------------------------------------------ When you supply WLA with the flag 'x' it will maintain few useful definitions while compiling your source codes. Please use the enhanced error reporting engine (so don't use flag 'f') in conjunction with flag 'x' as some of the definitions require extra information about the flow of the data which isn't available when using the old, crippled error reporting engine. Here's a list of what you get when you use flag 'x': WLA_TIME - A string definition holding the calendar time (obtained using C's ctime()). WLA_FILENAME - A string definition holding the file name WLA is currently processing. So you can do for example something like .DB WLA_TIME to store the time when the build process started into the ROM file you are compiling. ------------------------------------------------------------------------------ 21.. Good things to know about WLA ------------------------------------------------------------------------------ - Want more stack depth (.REPT and .MACRO)? Check out "defines.h". - WLA preprocessor doesn't expand macros and repetitions. Those are actually traversed in the assembling phase. ------------------------------------------------------------------------------ 22.. Author ------------------------------------------------------------------------------ Ville Helin, the author of Wzonka-Lad, a Game Boy emulator for the Amiga machines. I have 23 years behind me, many more to travel through. I study information technology at the Helsinki University of Technology (http://www.hut.fi). I like Game Boy (goes without saying), anime soap operas and gym. If you seek a programmer to work on a console game, please let me know. email: vhelin@cc.hut.fi hpage: http://www.hut.fi/~vhelin smail: Ville Helin Dagmarinkatu 8 C 38 00100 Helsinki Finland ------------------------------------------------------------------------------ 23.. Thanks ------------------------------------------------------------------------------ - Gaelan Griffin for endless suggestions and fast bug reports! - Nicolas Warren for few some serious bug reports (and even fixes to them!!!) and for the good ideas!!! - Madonna MkII (Matra Computer Corp.), Mike Blum, Anders Montonen, Robert Kihl and Arto Salmi for reporting bugs in WLA and providing me with great ideas. - Mark Knox, Igor Wronsky and Anders Montonen for helping me with the MSDOS port! - Gaelan Griffin for the Amiga port! - John Schneider for makefile enhancements! - Timo Jantunen for helping me with makefiles. - People at gameboy@vip.co.za and gameboydev@listbot.com for keeping up the good work! ;) ------------------------------------------------------------------------------ 24.. Future ------------------------------------------------------------------------------ Future enhancements (if I get really inspired): - Much more features to WLAD (I already know of three) and Z80/6502/6510/65816 support. - Other optimizations, bug fixes and new features. - You tell me. ------------------------------------------------------------------------------ 25.. Support ------------------------------------------------------------------------------ The currently supported systems are MSDOS/x86, AmigaOS/680x0, Linux/x86. If you'd like to see WLA for other platforms/configurations, send me email and we'll see what I can do about it. ------------------------------------------------------------------------------ 26.. Legal Note ------------------------------------------------------------------------------ WLA GB-Z80/Z80/6502/6510/65816 Macro Assembler Copyright 1998-2001 Ville Helin WLAB GB-Z80/Z80/6502/6510/65816 Binary to WLA DB Converter Copyright 2000 Ville Helin. WLAD GB-Z80 Disassembler Copyright 2000 Ville Helin. WLALINK GB-Z80/Z80/6502/6510/65816 Macro Assembler Linker Copyright 2000-2001 Ville Helin. I take no responsibility what WLA, WLAB, WLAD or WLALINK do on your machine. Remember that when using WLA, WLAB, WLAD or WLALINK you do it at your own risk. WLA, WLAB, WLAD and WLALINK are freeware as long as it is used to produce non-commercial software. WLA, WLAB, WLAD or WLALINK cannot be used in any commercial project without my permission. If and when WLA, WLAB, WLAD or/and WLALINK are used in a commercial project, I want something as well, like the finished product. ;) Or credits would be nice. Even credits in the documents will do. ;) Something, so I know there are people using WLA. WLA, WLAB, WLAD or WLALINK may not be put on any CD DISC or HD DISK or any other form of media for distribution unless I myself grant the premission. If I am not contacted before WLA, WLAB, WLAD or WLALINK is used in a process that involves money, then may the seven drunken Gods strike such a foul business down! If the Gods won't do me a favor, I'll come and do my Kung-Fu. Game Boy and Game Boy Color are copyrighted by Nintendo. Pocket Voice is copyrighted by Bung HK.