V0.90 Beta Test

Downloading

This version of CodeX is no longer available as a standalone download. It is now integrated into one of the ROM banks of the Commander X16. There is a companion program to produce text disassembly, as well as an example skeleton starter program. These are available as an SD card image you will want to use for development. You can download the card image from here.

Test Goals

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

To test this tool you should:

• An experienced or an aspiring assembly language programmer

• You are able to run assembly programs on the emulator (requires R39)]

• 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 CodeX work, within its current limits?

• What needs to be added to this documentation?

Limitations and capabilities of V0.90

This release is available in the interest is getting early feedback, however this version may have defects in its functionality.

• This version (V0.90) requires emulator R39

  • 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 CodeX via RTS

• Break is supported if you insert a BRK instruction in your program, you may single step instructions (STEPO).

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

• CodeX 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 may overwrite the display area.

• CodeX 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 CodeX

1. Unzip sdcard.zip

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

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

4. Invoke Codex using the command "CODEX"

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 should be located in the traditional areas for machine language programs. The starter program "X16SKEL.PRG" starts at $0801 and contains a BASIC boot stub to allow the PRG to be loaded solo.

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