V0.4 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. (V0.41 - a few bug fixes from 0.40)

Test Goals

Version 0.4 is intended to give users an early exposure to the X16AE. This version is not yet able to interactively assemble instructions, but it can host programs externally assembled. Additionally, a Python helper program (clc.py) is available to compile symbols for the X16AE to interpret.

You would be an ideal test subject if you are:

• An experienced assembly language programmer
• Working with a cross assembler on a host computer
• You are able to run assembly programs on the emulator (certified against R32)]
• 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?
• Does the X16AE work, within its current limits?
• What needs to be added to this documentation?

Limitations and capabilities of V0.4

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

• No interactive entry of assembly instructions
• You can not save a program (neither binary or text)
• Symbols must be compiled using the helper Python program, clc.py (See Building your program)
• 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
• STEPin and STEPover are not yet supported
• 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
• You can not yet set break points
• Watch mode only displays an address, it will display a defined label (future release)
• Hi memory pages $FC, $FD, $FE are used by X16AE
  • 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
• Only VERA mode 80x60 is currently supported
• X16AE uses several zero page locations. These will be preserved by the environment in a future release.

Known BUGS (don't bother reporting these):

• Assembly listing doesn't always clear the background
• Sometimes assembly listing appears to stop halfway down the screen
• Processor status is not shown on the break

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.