EasyAsm

EasyAsm is an on-device assembly language programming tool for the MEGA65 personal computer. It uses the MEGA65's operating system as part of a complete assembly language development workflow, and maintains a minimal memory footprint when not in use.

Features:

• All 45GS02 CPU instruction types and addressing modes.
• Supports a subset of the Acme cross-assembler syntax and features.
• Maintains a minimal memory footprint when running your program or during editing, so you can use the full power of your computer.
• Uses the MEGA65 screen editor's Edit mode for editing assembly language source code.
• Maintains your display settings: screen mode, upper/lowercase, colors.
• Assembles to memory for testing, or to disk files for distribution.
• Can produce a bootstrap loader as part of your program.
• Preserves source code in memory while running your program, and exits cleanly from your program back to the screen editor with source code restored. Can restore source code after an abnormal exit.

EasyAsm is released under the GNU Public License v3. See LICENSE.

---

I hope you enjoy EasyAsm! Please consider sponsoring my MEGA65 work: ko-fi.com/dddaaannn

---

Project status

This is EasyAsm version 0.2. It requires a recent ROM beta version, 920401 or newer, to assemble to disk.

All 0.x versions are public beta test releases. Syntax and features may change before the 1.0 release. Please file issues to report bugs, request features, or provide feedback. Thank you for trying EasyAsm!

In v0.2, !binary and !source are not yet implemented. See also the "Roadmap," below.

An important note

Save your work to disk, early and often.

Writing a program for a microcomputer using the microcomputer itself comes with the inherent risk that a bug in your program will interfere with your programming environment. EasyAsm preserves your source code in memory while you are testing your program, but this cannot be guaranteed to work if the program does something unexpected.

By design, EasyAsm does not force you to save your work to disk before testing your program. Please remember to do this yourself.

Quick reference

• MOUNT "EASYASM.D81" : BOOT : install EasyAsm; erases program memory

• Press Help to launch the EasyAsm interactive menu

• EDIT ON / EDIT OFF : enable/disable Edit mode; prompt is OK. when enabled

• DSAVE "..." : save source file to disk; do this with Edit mode enabled!

• DSAVE "@..." : save source file to disk, overwriting an existing file

• MONITOR : start the Monitor from the READY./OK. prompt

Using EasyAsm

To activate EasyAsm, BOOT the EASYASM.D81 disk:

MOUNT "EASYASM.D81"
BOOT

EasyAsm installs itself in the MEGA65's upper memory, clears program memory, and configures the Help key. The prompt changes from READY. to OK. to indicate that you are in Edit mode. This mode lets you edit a file of text data as if it were a BASIC program, including line numbers. All BASIC commands are still available for direct entry, but now when you type a line with a line number, the MEGA65 understands it as text instead of a line of a BASIC program.

Enter a simple assembly language program:

10 !TO "SIMPLE", RUNNABLE
20
30   INC $D020
40   RTS

Tip: To insert a blank line in Edit mode (such as line 20 in this example), type the line number, press Shift+Space, then press Return.

Save the source file to disk:

DSAVE "SIMPLE.S"

Tip: Use .S at the end of the source filename to indicate that it is assembly language source. In this case, I saved the source file as SIMPLE.S, so I can use the name SIMPLE for my program name.

Assemble and run the program:

1. Press Help.
2. Select option 1.

EasyAsm assembles the program, finds no errors, installs it into memory, then runs the program. The program changes the border color, then exits. EasyAsm notices the program has exited using rts, and restores the source code into the editor's memory. View the listing:

LIST

Next, assemble the program to disk:

1. Press Help.
2. Select option 2.

EasyAsm assembles the program again, finds no errors, then creates a new PRG file on disk. The !TO directive in the program tells EasyAsm that the PRG's filename is SIMPLE, and that EasyAsm should make the program "runnable."

Exit out of Edit mode, then load and run the runnable program from disk:

EDIT OFF

RUN "SIMPLE"

Note: Source code and programs share the same memory. Be sure to save your source code file before loading a program from disk.

To load your source file back into memory, return to Edit mode, then DLOAD the file SIMPLE.S:

EDIT ON

DLOAD "SIMPLE.S"

Assuming your program hasn't erased EasyAsm from memory, it is still present, and you can continue working. See below for a description of EasyAsm's memory requirements.

How to stop a running program

Because source code and programs often share the same memory, EasyAsm copies your source file to another memory location before it assembles and runs the program. When you assemble and run your program, EasyAsm watches for the program to exit using the rts instruction, then copies the source file back into program memory so you can continue to edit it.

That's nice, but it's not always possible—or even desired. A typical machine code program never exits. A broken machine code program might get stuck before it can exit.

Try entering a slightly different program:

10 !TO "FOREVER", RUNNABLE
20
30 LOOP:
40   INC $D020
50   JMP LOOP

Assemble and run the program. This program changes the border color repeatedly, in an infinite loop. It does not exit.

To interrupt this program and return to BASIC, hold Run/Stop and press Restore. The program stops, and the MEGA65 Monitor starts. Type X then press Return to exit the Monitor and return to the OK prompt.

Now type LIST:

LIST

Uh oh, there's something wrong with the first line! EasyAsm did not see the program exit with the RTS instruction, so it didn't get a chance to restore the source file.

When this happens—and it will happen often—use menu option #9 to tell EasyAsm to bring back the source file:

1. Press Help.
2. Select option 9.

Type LIST again to see the restored source.

An edge case about restoring source code

EasyAsm stashes a copy of program memory every time it is invoked, so that it can copy itself into program memory to perform its functions. If your program exits with RTS, or EasyAsm exits some other way, it restores the stashed program memory containing your source code on its way out, so you can continue working.

If your program does not exit with RTS (as above), the next time you invoke EasyAsm, it avoids stashing program memory, because program memory does not contain your source code: it contains your assembled program. It keeps track of whether it ought to stash source by remembering whether it restored source the last time it was invoked, or if it is being invoked for the first time since you booted the EasyAsm disk.

This is clever in most cases, but it has a small flaw. If you assemble and test your program, interrupt the program such that it doesn't exit via RTS, then load new source code into program memory manually (using the DLOAD command, or typing NEW then entering a new program), the next time EasyAsm is invoked, it will get confused into thinking program memory contains the previously interrupted program and ought to be overwritten by the previously stashed source code.

I have an idea on how to improve this in a later version. For now, just remember to invoke EasyAsm to restore your source code after interrupting a test run of your program.

Breaking to the Monitor

EasyAsm is designed so that you can use all of the tools available in the MEGA65 operating system as part of your development workflow. This includes the Monitor, a powerful tool for inspecting and experimenting with the state of a machine code program.

Type the MONITOR command to start the Monitor at the OK. prompt. (Naturally, this also works at the READY. prompt when not in Edit mode.)

MONITOR

The Monitor accepts commands through the screen editor. A typical command is a single letter followed by some arguments. You can use the Monitor to inspect CPU registers (R) and memory locations (M1600), examine code (D2014), and call subroutines (J2032). Addresses and values are specified in hexadecimal.

To exit the Monitor, enter the X command. This returns you to the OK. (or READY.) prompt.

The Monitor can be especially useful for debugging an assembly language program thanks to a special feature of the MEGA65 operating system. When a program executes a BRK instruction, the operating system halts the program, and starts the Monitor. The Monitor displays the status of the CPU registers as they were at the exact point in the program where the BRK occurred. You can continue to enter Monitor commands to inspect the state of the system.

Type in then assemble and test this example:

10 !TO "BRKDANCE", RUNNABLE
20
30   INC $D020
40   BRK
50   DEC $D020
60   RTS

The border changes color, then the program breaks to the Monitor. In the Monitor, enter the G command without an argument to continue the program where it left off. The border returns to its previous color, and the program exits. EasyAsm restores the source to program memory.

The Monitor is powerful, but sometimes tricky to use. For example, it is not always possible to resume a paused program, and you may have to exit the Monitor with the X command. In this case, you must ask EasyAsm to restore the program source file, as we did after interrupting the program with Run