The wAx API - Chysn/VIC20-wAx2 GitHub Wiki
The following subroutines will be useful in the development of user plug-ins.
Note: wAx is located in Block 5 ($A000) for the wAxpander cartridge, but may alternately be located in Block 3 ($6000). For Block 3 versions of wAx, the call addresses start at $6000 instead of $A000.
Addr2CP
Copy Working Address to Command Pointer
Call Address: $A027
Affected Registers: Accumulator
Description: Copies the Working Address, which is usually the current address for a wAx process, to the Command Pointer, which indicates the next default address.
CharGet
Get character from input
Call Address: $A006
Affected Registers: Accumulator, X Description: Gets the next character from the input buffer. Spaces are not returned unless within quotes. Accumulator of 0 indicates end of input.
CharOut
Add character to output
Call Address: $A009
Affected Registers: None
Description: Adds a character with PETSCII code in Accumulator to the output buffer. Note that the output buffer is not flushed to the screen until PrintBuff is called.
DirectMode
Determine plug-in's execution mode
Call Address: $A030
Affected Registers: Y
Description: Sets the Zero flag if the plug-in is currently running in direct mode, and clears the Zero flag if the plug-in is currently running within a BASIC program.
JSR DirectMode
BEQ @D ; RUNNING DIRECT
BNE @B ; RUNNING BASIC
Disasm
Add disassembly at working address to the output buffer
Call Address: $A036
Affected Registers: Accumulator, X, Y
Description: Gets the 6502 instruction at the working address, disassembles it to the output buffer, and advances the working address by the number of bytes for the instruction.
HexGet
Get hexadecimal byte from input
Call Address: $A003
Affected Registers: Accumulator, X
Description: If the next two non-space characters in the input buffer represent a valid hexadecimal byte, the value is returned in the Accumulator and the Carry flag is set. Otherwise, the carry flag is clear.
HexOut
Add hexadecimal byte to the output buffer
Call Address: $A00C
Affected Registers: Accumulator, X
Description: Adds the value in the accumulator to the output buffer as a two-character hexadecimal number. Note that the output buffer is not flushed to the screen until PrintBuff is called.
IncAddr
Increment the working address
Call Address: $A00F
Affected Registers: Accumulator, X
Description: Sets Accumulator to the value of the working address, then increment the working address. The Accumulator will be the value of the address prior to the increment.
IncCP
Increment the Command Pointer
Call Address: $A012
Affected Registers: None
Description: Increments the Command Pointer.
Install
Start wAx
Call Address: $A000
Affected Registers: Accumulator, X, Y
Description: This is the jump to starting wAx with SYS 40960.
Lookup
Get 6502 instruction data
Call Address: $A015
Affected Registers: Accumulator, X, Y
Description: Looks up a 6502 instruction with the opcode in the Accumulator. The Carry flag is set if it's a valid instruction. The instruction's addressing mode is returned in the Accumulator. The instruction's mnemonic is packed in zeropage locations $A4 and $A5, with five bits per letter in bits 0-14.
You may include "illegal" opcodes in the lookup by setting zeropage location $AF to value $2C in preparation for the call.
Lookup Addressing Mode Table
Mode Accum. Example
---------------------------------
INDIRECT $10 JMP ($0306)
INDIRECT_X $20 STA ($1E,X)
INDIRECT_Y $30 CMP ($55),Y
ABSOLUTE $40 JSR $FFD2
ABSOLUTE_X $50 STA $1E00,X
ABSOLUTE_Y $60 LDA $8000,Y
ZEROPAGE $70 BIT $A2
ZEROPAGE_X $80 CMP $00,X
ZEROPAGE_Y $90 LDX $FA,Y
IMMEDIATE $a0 LDA #$2D
IMPLIED $b0 INY
RELATIVE $c0 BCC $181E
ACCUM $d0 ROR A
NextList
Handle next list item
Call Address: JMP $A02D
Affected Registers: N/A
Description: NextList is not a subroutine, it is an endpoint for List-type plug-ins. When the plug-in has finished processing the output for a list item, jump to NextList to allow wAx's list system to handle the next address. Contrast this with Normal-type plug-ins that end with RTS.
PrintBuff
Flush output buffer to screen
Call Address: $A018
Affected Registers: Accumulator, Y
Description: Flushes the output buffer to the screen or output device, to a limit of 22 characters. The output buffer is terminated by $00. PrintBuff always ends with Reverse Off and Linefeed. Note that PrintBuff does not reset the buffer itself, so a new line should be started with ResetOut.
PrintStr
Print a string
Call Address: $A02A
Affected Registers: Accumulator, X, Y
Description: Similar to BASIC's $CB1E routine, PrintStr will print a $00-terminated string from address A (low), Y (high). Its limit is 256 characters. The main difference between PrintStr and $CB1E is that PrintStr can be used to print text from Page 2 ($200-$2FF) without corrupting the top of BASIC memory.
ResetIn
Reset input buffer
Call Address: $A01B
Affected Registers: Accumulator
Description: Sets the input buffer index back to the beginning. After ResetIn, input routines like CharGet and Buff2Byte will start reading from the beginning of the input buffer.
ResetOut
Reset output buffer
Call Address: $A01E
Affected Registers: Accumulator
Description: Sets the output buffer index back to the beginning, to start a new line of output.
ShowAddr
Add working address to the output buffer
Call Address: $A021
Affected Registers: Accumulator
Description: Adds the working address to the output buffer as a 16-bit hexadecimal address.
ShowCP
Add Command Pointer address to the output buffer
Call Address: $A024
Affected Registers: Accumulator
Description: Adds the Command Pointer address to the output buffer as a 16-bit hexadecimal address.
SizeOf
Return size of 6502 instruction
Call Address: $A033
Affected Registers: X
Description: Returns the byte size of a valid (non-"illegal") 6502 instruction, in the X register.