Commander X16

*** VERSION 3 UPLOADED!!! ***
ASMEDIT X16 has been modified to remove the troublesome ROCKWELL instructions BBR, BBS, RMB & SMB, which don't work on a 65c816 CPU. In addition there are new functions included to IMPORT/EXPORT source from/to ASCII text files:

1. CREATE CODE' menu

This existing menu now has a new field included IMPORT TEXT FILE to specify the file name of an ASCII text file to be used as the basis of the new code:-

N.B. The CLEAR CODE field must be set to Y.
The text file should be in ASCII format and be held on the current directory (as set by the F2 directory command)
CR chars indicate a new line.
LF chars are ignored.
Lines greater then 56 chars will be truncated.
A new SECTION is created every 64 lines (leaving plenty of room for code inserts in each section),
Up to a maximum of 99 SECTIONs.
There is no case sensitivity.
There is no verification or conversion of code.

EXPORT TO TEXT FILE is a new command (O filename) within the EDITOR to output the current BUFFER contents.
N.B. Text is written in ASCII format (lowercase).
Sections are output sequentially to one file using the given filename.
The file is written to the current directory.
An existing file will be overwritten.
CR/LF chars are written as line breaks.

The manual has been updated to reflect the new functions. IMPORT (Ref: 3.1) & EXPORT (Ref: 4.23)

See DOWNLOADs below:-

-0O0-

*** NEW VERSION UPLOADED!!! ***
A new function has been added with version 2 of ASMEDIT X16, to browse listings created on disk by the Assembler.

INTRODUCTION

ASMEDIT X16 is an ASSEMBLER (65C02) and EDITOR for the COMMANDER X16. This software, originally developed for the Commodore CBM II Series, has been adapted and ported to the Commander X16 environment.

Source code can be created, saved, loaded, edited and assembled. A 'menu' system is used to navigate between the various functions which include file maintenance. Each of the 'Menu' pages displayed enables the user to choose the current directory path in operation.

ASMEDIT X16 uses a file naming convention to aid the handling of code objects on disk - objects being source code (*.SOR), executable code (*.PRG) and listings (*.LST).

Programs are assigned a CODE NAME by the user. For single SEGMENT programs the CODE NAME is combined with the appropriate FILE TYPE to create a filename e.g., ‘SORT.SOR’.

Large programs may be broken down into SEGMENTs. Each SEGMENT of source code is then stored as a single file prefixed by a 2-character assigned SEGMENT NO. and suffixed by the CODE NAME and FILE TYPE e.g., '3 SORT.SOR'.

LOADING THE SOFTWARE

ASMEDIT X16 can be loaded with BASIC command LOAD “ASMEDIT.PRG” followed by the ‘RUN’ command. ASMEDIT.PRG will then load the following binaries (which will need to be located on the same directory) before entering the PRIMARY COMMANDS menu and be ready for use: -

XAM.BIN Menu Control
XAE.BIN Menu Functions
X0F.BIN Machine Specific Functions
XAI.BIN Default Input Data
XHP.BIN Help Text
XAL.BIN Browse Listing (new with version 2)

DOWNLOAD

Version 3 Version 2 Version 1 Note: A PDF reference manual is included within each download file.

THE ASSEMBLER

The ASSEMBLER generates executable code from source code to run on a 65C02 machine, specifically the commander X16. It can also produce a program listing (complete or errors only). The Listing is created in text format and can be directed to the screen, disk or a printer.

The ASSEMBLER reads through the source code TWICE. The first pass identifies SYMBOLs and builds a SYMBOL table. At this point some SYMBOL values will be unresolved. The second pass resolves these values, creates the listing, identifies and reports coding errors and generates the required machine code. Finally, the SYMBOLs are reported in tabular form, in alphabetic order at the end of the program listing. Progress of the assembly is displayed on the screen.

Large programs may be split into physical SEGMENTS. A SEGMENT is a single source code file which can be loaded into memory. SEGMENTs may be combined at assembly through a naming convention and an assembler command to form a single program.

THE EDITOR

The EDITOR is where the user can enter and edit source code. Source code in memory is logically split into SECTIONS (upto 99), with the current SECTION displayed as a single page (upto 127 lines). [PGDN] & [PGUP] allow the user to scroll through SECTIONS.

Source displayed by the EDITOR is physically held in memory known as BUFFERs. Two BUFFERs are used, BUFFER 1 and BUFFER 2. The EDIT BUFFER is where source code is held when currently in view. This may be either BUFFER 1 or 2. Code entered from the keyboard is always entered into the EDIT BUFFER, similarly all filing is performed to/from the EDIT BUFFER. The STORAGE BUFFER is where code is held temporarily to one side as it were. When in the STORAGE BUFFER it cannot be saved or 'handled' without first passing it back to the EDIT BUFFER. However, its whole contents can be swapped with the EDIT BUFFER at the touch of a key. It may be useful to think of BUFFERs 1 and 2 as being a turn table divided into two. The half nearest and currently in use is then the EDIT BUFFER. The part furthest away is the STORAGE BUFFER. Swapping the BUFFERs is then equated with turning the table so that the other half is then nearer and so becomes the EDIT BUFFER.

The EDITOR supports multiple commands which enable source code to be crafted in the EDIT BUFFER and passed to or from the storage BUFFER. SECTIONs within SEGMENTs can be navigated with the [PGUP]/[PGDN] keys or the GOTO SECTION command. Code entered can be verified with the VERIFY command. Pressing [PF1] in the Editor displays a QUICK GUIDE to the commands available.

#R47

SEGMENTs may be combined at assembly through a naming convention and an assembler command to form a single program.

So, sort of like a linker? Cool. Monoliths are cool in Stanley Kubrick sci-fi movies but not so much in complicated projects.

If I might suggest... would it be possible to support the .S extension, the standard for assembly source files?

kelli217 wrote: ↑Mon Aug 07, 2023 6:32 pm

SEGMENTs may be combined at assembly through a naming convention and an assembler command to form a single program.

So, sort of like a linker? Cool. Monoliths are cool in Stanley Kubrick sci-fi movies but not so much in complicated projects.

If I might suggest... would it be possible to support the .S extension, the standard for assembly source files?

It might actually be better to leave it how it is... the SOR extension makes it clear that the file is meant to be used with this assembler, where the .S extension is more of a ca65 thing.

I ran this in r43. Pretty neat, although so far not total success.

Some initial comments:

40+ page manual!! Nice!

Caution: SHIFT+ALT changes the program font. (probably original CBM didn't do this, but X16 now is?)

Why "PF3"? What's the P for? Program Function? (not an issue, probably just me- old manuals used PFn?)


So here is what I did:

- I ran it, and was following the example in APPENDIX B.
- The example said to enter any of the code on next page. (ok, can't paste from that manual into a text file and get to a SOR file; SOR is a special binary format)
- so I did the example on page 34 and 35.
- I used the V command to verify a few issues, that all worked nicely. Couple mistakes, fixed those.
- on page 33 there might possibly be an issue with the example: in order to get the PRG, I had to go down and enter "Y" on GENERATE CODE. That may be missing in the instructions (or I messed up a step and it was supposed to auto selected to YES?
- I was able to reset and load back my SOR file, so neat I can do work and not lose it between sessions!
- the TEST.PRG was created, it at least starts with 01 08 as expected
- I exit ASMEDIT (and tried a system reset), when I load the TEST.PRG - I can't LIST it or RUN it (does crazy things like makes the screen go white, and says something about line 16000-something)
NOTE: I noticed the created TEST.PRG refers to a X0F.PRG instead of X0F.BIN (in the ZIP archive, we just got the X0F.BIN, no PRG); not sure if that's an issue.

It's possible my SOR validated but I still did something wrong in typing it. Will try more later. Note my TEST.PRG is 77 byte, is that the expected size of that first example?

Well! I have to try it!

So I wrote what I thought was the minimum "hello world" program:

At first, I thought... "How do I RUN it without the BASIC preamble?"
So I tried SYS
SYS $0801

Yoinks! Nope! So I looked at the compiled code in a hex editor, and noted that the jmp instruction at the start was wrong, but it looked fine after that.

So, to start at the beginning of the executable part, I used:
SYS $0810

Assessment: Hey! It works! And it's an honest 1980's experience! But I can't imagine writing anything of any size with this...

But in 1980? I would have done anything to have an assembly editor like this. With a little patience, this works even today!

It does seem a bit light on the buffer space, though. 127 lines is a bit sparse. What about using that vast expanse of VRAM that's barely being used at all when this is running?

Wait! It compiled my code properly, as shown in this actual hexdump from my linux terminal: I was looking at the -debug display with memory dumped at $0801. That looked like this:

All in all, out of the box...

This is a good assembly language trainer for the X16. The "Menu Dance" to get from menu to menu isn't hard once you use if for a short bit, and even if you have a "VI moment" where you say "Hey! How do I close the editor?" you can press the F1 key for help.

You just need to NOT start programs at $0801 (I'm assuming that's why the first few bytes of mine were messed up.)

But short programs to try out assembly, then using the debugger in the emulator to see the results? Yeah! Totally doable.

Hey, I repeated your steps - not exactly sure what I did differently (from what I tried earlier using example from the manual), but my resulting PRG is valid and running. (well, valid aside from the same issue you had as well)

So agreed, mostly-success!!

Is the PRG code mistake because after the "01 08" starting address, the next bytes after that are a regular 6502 instruction JMP, as opposed to being a BASIC tokenized equivalent of the SYS CALL? (the portion in red below -- 4C is an absolute jump?)
I tried manually patching it, but in the end just did the SYS $0810 like you.


Maybe the manual just needs a few brief simple examples. And maybe an overview of .sor and .s syntax differences? (and of course this PRG creation jump fixed)

Thanks for the feedback. I am slightly reluctant to include modern language formats such as .S (but I'm willing to be persuaded otherwise) as this goes against its basic 'old style' architecture. I like it as a discrete environment which just runs on the Commander X16.

A bit of history … the .SOR format started its life in 1979 when I coded an word processor for the PET 2001 with a machine code editor. In those days I needed some home grown compression on the text due to it being run an 8k machine. Later in 1980/81 Commodore commissioned me to port WORDFORM, as it was known then, to the Commodore VIC as they liked the 'typewriter style' of WORDOFRM due to the limit screen size but it called VICWRITER. Later in the 1980s I had a B700 machine (CBM II) for which I developed a menu system to front-end WORDFORM. As you may know the CBMII never really took-off. Also about that time I had written an assembler which ran from just input prompts. Fast forward many decades I found the VICE emulator and decided to reverse engineer much of my old code (written with my machine editor) into assembler source code. I then combined the the menu system and assembler together and I created ASMEDIT 700. From this code I have ported it to the X16. So this is why it has an 80's feel to as it literally is an 80's program. The entire source of ASMEDIT is now held in .SOR files and fully supported by itself .

Calling the functions keys PFn is an old habit I have from my days working on dumb terminals on an IBM mainframe. I think I should change this to Fn.

The reference manual does have some holes in it which I shall rectify. The sample code does need some work on it too and I didn't really think of it being ran , only to be successfully assembled.

Just some clarification on SECTIONs. Yes there is a line limit within a section but there is no problem simply adding sections up to 99 with the 'I' command. Personally I like to have only one sub-routine in a section, often using much less that 127 lines. This is not a problem as unused lines below the sub-routine are not written to disk anyway, just simply ignored until the next section.

One criticism I have is that I cannot read the .LST files on the X16. At the moment I use WINDOWS NOTEPAD to scroll through them. My XAE.LST is 571 kb. I'm not sure if we have such software on the X16 yet, may be I'll look to writing one myself