wAx2 Tutorial - Chysn/VIC20-wAx2 GitHub Wiki

With most native VIC-20 machine language monitors, you're either running the monitor or you're in BASIC. wAx isn't like that. wAx is a system of tools bound together by a common interface that runs as a BASIC extension. It integrates seamlessly into the VIC-20's native environment, providing a great deal of agility. It's a machine language monitor that works with you.

If you've used wAx before, there are some important changes in wAx2. If you've used other native VIC-20 assemblers (like VICmon or HES MON), much will be familiar, but wAx does a lot of extra things. So whether you're a new wAx user, or are upgrading to wAx2, the following tutorial will get you up to speed.

Invoking wAx Tools

All wAx tools start with a period (.). The tool's command comes after the period (actually, after any number of periods). In most cases, parameters follow the command, depending on what the tool does. Once you've started wAx, try the following:

.?

This is the Help Tool. It displays a list of all wAx tools. Each of these can be invoked by entering a period, the command, and usually one or more parameters. Let's invoke a simple tool:

.R

This shows the register display, and the cursor is now flashing after a period, the wAx prompt. Most tools will finish by showing some kind of prompt. This prompt is there for convenience. It doesn't mean that you're "in" wAx. You never left the VIC-20's BASIC environment.

Disassembly

Now enter this:

.D EABF

You might recognize this bit of code as part of the VIC-20's interrupt handler. You'll notice that, in addition to the wAx prompt, the cursor is flashing over the D command. Invoking D with only a starting address will display 16 lines of code and then pause. Press RETURN. You'll see the next 16 lines of code. Press RETURN again, and hold down the SHIFT key once the code starts rolling. The disassembly will continue until you release SHIFT. You may also disassemble a range of code:

.D 0073 008A

How do you get out of wAx? Well, you were never "in" wAx to begin with, remember. But you can dismiss the wAx prompt in several ways:

  • Press X and then RETURN (the Exit Tool)
  • Press DEL until the wAx prompt is gone
  • Press the CRSR Down key to go the next line
  • Press STOP/RESTORE
  • Press SHIFT/CLR

Assembly

This is what you're here for, right? Try entering this:

.A 1800 LDA #$2A

Once you press RETURN, wAx displays a new kind of prompt. It automatically generates the next A command and populates the next memory address, 1802. Continue entering code:

.A 1802 LDY #$10
.A 1804 JSR $FFD2
.A 1807 DEY
.A 1808 BNE $1804
.A 180A RTS
.A 180B {RETURN}

At the .A 180B prompt, just press RETURN. You'll go back to the normal wAx prompt. Now execute this program with the Go Tool:

.G 1800
****************

After returning from the program, wAx shows the register display, and a new wAx prompt. Now disassemble your code:

.D 1800 180A

Cursor up to address $1800, and change the line to LDA #$5C and press RETURN. You may edit your code directly from the disassembly, and comma is an alias for A, the Assemble Tool.

BASIC Assembly

All wAx commands can be used in BASIC programs. Dismiss the wAx prompt (with X or DEL), and enter the following BASIC program:

NEW
10 .A 1900 INC $900F
20 .A 1903 JMP $1900
RUN

READY.
SYS 6400

The program doesn't do much. It just changes the screen color until you press STOP/RESTORE. This is a simple way to add assembly to BASIC. However, it might be too simple for all but the most trivial uses. Here's a somewhat more advanced example:

NEW
10 S = 6400
20 .A 'S’  INC $900F
30 .A * @L LDA $A2
40 .A *    BNE @L
50 .A *    JMP 'S’
60 .D 'S’ *
RUN

This program demonstrates some more advanced assembly features:

  • On line 10, you're setting the BASIC variable S, which is to be the start address of the machine language code
  • On line 20, 'S’ tells wAx to insert the value of S as the assembly address after the A command
  • On line 30, the * is the "Command Pointer." It is replaced by the next address after the last tool that has been executed. So it sort of behaves like the automated prompt in this construction. But * can be used in any wAx command (see line 60), so it's very useful
  • Also on line 30, @L defines a symbol, whose name is @L and whose value is the current address
  • On line 40, the @L symbol now appears as an operand, creating a simple loop to the code on line 30
  • On line 50, the BASIC variable S makes another appearance, this time as a JMP operand, to go back to the beginning
  • Line 60 commands wAx to disassemble the code from the address in variable S to the Command Pointer, right after the JMP instruction

You an go ahead and execute this code with SYS 6400 (or SYS S). Press STOP/RESTORE to exit it.

And now, on line 10, change S = 6400 to S = 6450 and RUN it again. Combining wAx's advanced features allows you to relocate your code. wAx even makes the Command Pointer available to BASIC:

PRINT CP

You can use wAx in BASIC to automate assembly. This example generates an "unrolled loop":

NEW
10 .* 1800
20 .A * LDA #"!"
30 FOR I = 1 TO 10
40 .A * JSR $FFD2
50 NEXT I
60 .A * RTS
RUN

READY.
.D 1800 *

Some new syntax to note:

  • In line 10, we're using * as a command to set the Command Pointer, to set the beginning of the code. Can you use . 'S’*? Absolutely!
  • In line 20, we're using a character operand for LDA#. There are several ways to specify immediate operands in wAx

Other Memory Editors

In addition to assembly, wAx has several additional ways to edit memory. Text can be added with quotation marks, and hex values can be entered with : and then up to eight hex bytes:

.A 1800 LDA #<@T
.A 1802 LDY #>@T
.A 1804 JSR $CB1E
.A 1807 RTS
.A 1808 @T "HELLO, WORLD"
.A 1814 :49 00
.A 1816 {RETURN}

Also, note that we're using another symbol, this time @T. Here are some interesting things about this symbol usage:

  • A symbol always holds a 16-bit value, but you can specify the low or high byte of the value by prefixing the symbol name with < or >
  • Notice that the symbol @T is used in operands before it is defined as the address 1808. This is called a "forward reference." When a symbol is used before it's defined, wAx keeps track of where it's used, and then fills those spots in upon the symbol's definition.

wAx also has a binary editor, with one binary byte per line. You can use the Binary Tool, whose command is %, to view binary on one byte per line, with 1s highlighted:

.A 0061 %00111100
.A 0062 %01000010
.A 0064 %10100101
.A 0064 %10000001
.A 0065 %10100101
.A 0066 %10011001
.A 0067 %01000010
.A 0068 %00111100
.A 0069 {RETURN}
.% 0061 0068

There's a lot more, but it'll be covered in the rest of the manual. Hopefully this tutorial has given you some idea how wAx is the finest VIC-20 native assembler that no-money can buy!

⚠️ **GitHub.com Fallback** ⚠️