V0.5 Alpha Test

Downloading

If you are anxious to download, this is the spot. I recommend that you read the rest of this page to understand the limitations of this version.

You can download the X16AE from here.

Test Goals

Version 0.5 is intended to give users the opportunity to begin creating programs using the X16AE. This version can still host externally hosted programs, and the symbol compiler (clc.py) has been updated to work with the extended DBG file format.

You would be an ideal test subject if you are:

• An experienced or an aspiring assembly language programmer
• You are able to run assembly programs on the emulator (certified against R33)]
• Willing to send detailed error reports to x16.asm.env@gmail.com
  • The best reports will include detailed steps showing how to reproduce the error and sample code illustrating the error (if possible).

I am looking for the following types of feedback:

• Is the UI "usable", and if not, what is confusing or hard to work with?
• What features are not working as intended?
• Does the X16AE work, within its current limits?
• What needs to be added to this documentation?

Limitations and capabilities of V0.5

This release is available in the interest is getting early feedback, however this version is quite limited in its functionality.

• Watch supports bytes (8 bits), words (16 bits), "C strings", and "P strings"
  • C strings are character strings terminated with a NUL character
  • P strings are character strings prepended with an 8 bit byte length
• Running your program requires an explicit start address, when done return to the X16AE via RTS
• Break is supported if you insert a BRK instruction in your program, you may single step instructions (STEPO). Step in is not yet supported. Setting a break point will work, but you can't continue from the break.
• View menu supports memory ranges, and showing the saved user screen
  • You can not alter memory contents
• Assembly mode only allows for showing a listing of assembly code
• Watch mode only displays an address, it will display a defined label (future release)
• Hi memory pages used by X16AE and kernal, see Hi Memory Usage for more details
  • You can access other high memory pages by specifying the page number separated by a colon from the address, e.g. 1:A000, or 3F:A000
• Display modes supported by the kernal saved / restored for displaying the program screen.
• X16AE uses several zero page locations, these are saved on breakpoints. These do not interfere with the user program.

Known BUGS (don't bother reporting these):

• Setting a breakpoint will work, but you can not continue from there. Inserting a BRK in your program will work.

WARNING:

• Displaying memory or watch variables on IO mapped devices may have side effects, use with care (i.e. VERA registers).

acme --report example.l --vicelabels example.lbl example.a

python clc.py example.lbl -s

Note that the acme assembly step produces a source listing (example.l) and a label file (example.lbl). The label file is in "Vice format", used by the Vice C64 emulator. The helper program, clc.py, will convert this file into the format that X16AE expects. If you are using a different assembler, you will need to alter the clc program.

Loading your program

The first thing you'll need to do is load your target program.

Running and interrupting your program

After your program is loaded, you start the program by selecting the RUN option (F4) and enter the appropriate start address. Your program will begin running and continue until it performs the final RTS or it encounters a BRK instruction. If you've included a BRK, the display will revert to the AE and look something like the following (example.a contains a break)

Note that the assembly display shows the next instruction to execute (e.g. the one after the break) at the top of the assembly listing. The register windows shows the processor registers and the processor status. Any watched locations will be shown.

To continue your program, press CONTinue (F4). The AE restores your program's screen, and continues execution after the break. Remember, STEPin, and STEPover are not yet implemented. If you select STOP, your program is terminated and you are returned to the initial screen. Your program is still loaded and memory is untouched. You can always view the final screen by selecting VIEW (F2), and SCR (F2), any key press will exit screen view and return to the AE.

Examining code, memory, and variables

You can examine code assembly by entering ASM (F3) then Address (F1). After entering the address, the code will be disassembled and displayed. Associated labels will be shown in context. The following image shows the example.a code starting at $A000.

The previous example also shows watch variables. Add watch variables by entering WATCh (F7) then choosing the type of watch you wish to display. This example shows two word watches and a byte watch location.