V0.81 Beta 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.80 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 (requires R38)]

• 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.81

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

• This version (V0.81) requires emulator R38

  • Program can be saved to disk (PRG, DBG, DBI)

• Absolute addresses are patched during code edit

• Relative addresses (BRx instructions) are patched during code edit

• Address expressions supported (#< for low byte, #> for high byte)

  • e.g. lda #<label

• Pseudo ops for data values

  • .pstr "str" to create a Pascal style string

  • .cstr "str" to create a C style string

  • .byte $42 to create an 8 bit byte value in memory

  • .word $1234 to create a 16 bit word value in memory

• Add / Delete labels

• Insert / Delete / Edit (in-place) instructions

• Many bug fixes since 0.81

• 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, but if find others, let me know!):

• Watch values of strings overwrite the display area.

• The AssemblyEnvironment will NOT run correctly if the emulator is using the host filesystem for storage. This is an emulator restriction, which could be relaxed in the future.

WARNING:

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

Installation and running X16AE

1. Unzip X16AE_V81.zip

2. Copy sdcard-x16ae.img to your emulator directory

3. Run the emulator with "x16emu -sdcard sdcard-x16ae.img"

4. Load the AE via: LOAD "X16AE"

5. Run

Your display looks like the following image

Loading your program

The first thing you'll need to do is load your target program. After loading a program, your display will resemble the following annotated image

The main areas of the AE you will interact with are:

• Function Menu - the menu showing you which functions are available to you at any point in time. In general F8 is always "exit" (although in break mode, it's "stop").

• The main display is where you will see memory and assembly listings displayed

• The program region shows which bank is in effect, and the start/end of the program

• The debug area shows processor, stack, memory, and zero page register state during debug breaks. While your program is not running, this area is blank.

Building your program

Your program must not be located in, or use the, the following ranges:

• $0000 - $3500 (X16AE lives there, for now, for this version I'll use $6000)

• Hi memory pages (top four pages) as these are used by X16AE to save your program state. See Hi Memory Usage.

You can start by loading "x16skel.prg". This is a basic program that supplies definitions for symbols of zero page registers and several kernal entry points. If you wish too other labels or entry points to the skeleton program, edit x16skel.a, and assemble it with acme assembler.

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

python clc.py x16skel.lbl -s

Note that the acme assembly step produces a source listing (x16skel.l) and a label file (x16skel.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 may need to alter the clc 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:

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 x16skel.a with a byte and word watch starting at $600E.

The previous example shows watch variables. Add watch variables by entering WATCh (F7) then choosing the type of watch you wish to display. While in watch mode, you may select watch values using up/down arrows. F6 allows you to delete a watch.