{"id":15060286,"url":"https://github.com/jblang/supermon64","last_synced_at":"2025-07-21T05:03:14.168Z","repository":{"id":38805709,"uuid":"78076739","full_name":"jblang/supermon64","owner":"jblang","description":"Original sources and binaries for Supermon+64 V1.2 by Jim Butterfield","archived":false,"fork":false,"pushed_at":"2024-01-31T21:48:38.000Z","size":174,"stargazers_count":143,"open_issues_count":1,"forks_count":29,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-06-23T01:07:57.215Z","etag":null,"topics":["6502","assembler","assembly","c64","commodore","monitor","retrocomputing"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jblang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-01-05T03:45:50.000Z","updated_at":"2025-06-21T18:34:41.000Z","dependencies_parsed_at":"2025-06-23T01:07:57.935Z","dependency_job_id":"7296ded4-61f5-4672-bbbe-497fead21537","html_url":"https://github.com/jblang/supermon64","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jblang/supermon64","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jblang%2Fsupermon64","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jblang%2Fsupermon64/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jblang%2Fsupermon64/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jblang%2Fsupermon64/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jblang","download_url":"https://codeload.github.com/jblang/supermon64/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jblang%2Fsupermon64/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266242054,"owners_count":23898101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["6502","assembler","assembly","c64","commodore","monitor","retrocomputing"],"created_at":"2024-09-24T22:55:57.903Z","updated_at":"2025-07-21T05:03:14.162Z","avatar_url":"https://github.com/jblang.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Supermon+64 V1.2\nBy Jim Butterfield et. al.\n\nSupermon64 is a machine-language monitor for the Commodore 64.  In modern parlance, it would be\ncalled a debugger, providing functions including inspecting and altering registers and memory locations;\nsearching, comparing, and transferring blocks of memory; and assembling and disassembling machine code.\n\nHere is a 10-minute video I made demonstrating many of its features: https://www.youtube.com/watch?v=MEjnMt_3wkU\n\n## Contents\n\nOriginal artifacts:\n- [sprmon64.txt](sprmon64.txt) is a posting to comp.binaries.cbm\n  containing a uuencoded self-dissolving archive with the Supermon+64 V1.2\n  sources, instructions and binaries.\n- [sprmon64.d64](sprmon64.d64) is a D64 image created from the \n  archive for use with VICE, disk drive emulators, or to create a real floppy disk.\n- [supermon64.prg](supermon64.prg) is the original Supermon+64 binary taken from\n  the archive. The sources below will build an identical binary.\n\nModernized sources:\n- [supermon64.asm](supermon64.asm) is the Supermon+64 V1.2 source code, converted to 64tass format\n and heavily commented by me. \n- [relocate.asm](relocate.asm) is the disassembled machine-code stub that loads Supermon+64 into\n  the top of BASIC memory.\n- [build.py](build.py) is a python script I wrote that transforms the assembled relocator\n  stub and the fixed-location Supermon binaries into a relocatable binary.\n- [Makefile](Makefile) is a GNU makefile that will build the final supermon64.prg binary\n  using the above sources.\n\n## Background\n\nSupermon is closely associated with [Jim Butterfield](https://en.wikipedia.org/wiki/Jim_Butterfield)\nbut it had many contributors over the years.  The original version of Supermon for the Commodore PET\ncontained the following credits:\n\n- Dissassembler by Wozniak/Baum\n- Single step by Jim Russo\n- Most other stuff (,HAFT) by Bill Seiler\n- Tidied \u0026 Wrapped by Jim Butterfield\n\nThe earliest documented appearance of Supermon that I could find was in the \n[January 1980 issue of The Transactor](https://archive.org/details/transactor-magazines-v2-i08). \nFrom its origins on the PET, Supermon made its way to the VIC and the Commodore 64. It apparently\nshares some DNA with the monitor and mini assembler on the Apple II as well as Micromon \nand MADS monitors on various Commodore computers.\n\nThe first version for the Commodore 64 appeared as a type-in program in the \n[January 1983 issue of Compute Magazine](https://archive.org/details/1983-01-compute-magazine). \nAn improved version followed in 1985, updated to include the features in the built-in monitors\nfor the Commodore Plus/4 and 128.  This is the version that is preserved here.\n\nSupermon 64 was widely distributed by Commodore User's Groups and included on the \n[demo diskettes](http://www.zimmers.net/anonftp/pub/cbm/demodisks/c64/starter-kit.d64.gz)\nand tapes that Commodore provided with their hardware.  It was also included as a type-in\nprogram in the back of many books on machine language programming, including Rae West's\n[Programming the Commodore 64: The Definitive Guide](https://archive.org/download/Compute_s_Programming_the_Commodore_64_The_Definitive_Guide/Compute_s_Programming_the_Commodore_64_The_Definitive_Guide.pdf)\nand Jim Butterfield's own \n[Machine Language for the Commodore 64](https://archive.org/details/Machine_Language_for_the_Commodore_Revised_and_Expanded_Edition).\n\nMore than 30 years later, I decided to learn 6502 assembly. After working my way through \nJim Butterfield's excellent book using Supermon64, I wanted to find some real assembly code to \nstudy, and the software I had just been using seemed like a natural place to start.  I started \nlooking for the sources online but for a piece of public domain software, it wasn't as easy as\nto find as you'd think.  \n\nI found [this thread](http://comp.sys.cbm.narkive.com/KUAL6oqM/attn-jim-butterfiled-i-m-looking-for-supermon-64-source-code)\non comp.sys.cbm where someone asked for the sources and Jim Butterfield himself responded, but\nat the time he didn't have easy access to the sources. One person pointed to this\n[modified version](http://www.ffd2.com/fridge/programs/supermon.s)\nbut I wanted the original.  Someone else mentioned a file called SPRMON64.SDA at a now-defunct FTP\nsite.  I googled for the filename and found what was apparently the last remaining copy on the internet\non a [gopher proxy](https://gopherproxy.meulie.net/sdf.org/1/users/rogertwo/prgs/cbm/c64/programming/).\n\nI downloaded it and found that it contains what appear to be the original source and binaries\nfor the updated 1.2 version.  Since it doesn't seem to have an official home and it's \ncontinued availability on the internet seemed precarious, I decided to give it one on GitHub.\n\nI modernized the source code so it can be built using the [64tass](https://sourceforge.net/projects/tass64/)\ncross-assembler. The original source (included on the D64 image) was almost completely uncommented and used a\nfew constructs that were unsupported by 64tass.  I converted these to the equivalent 64tass constructs, \nindented the code, and then worked my way through the code line-by-line until I understood it all, commenting\nit as I went along.\n\nAs Jim noted in his usenet posting, the provided sources don't produce the final Supermon 64 binary:\n\n\u003eI should note that, since Supermon+64 is relocatable code, the source\ndoes not assemble into the final binary file.  It may seem crude, but\nI follow this procedure:  (1) The source is carefully structured so\nthat there are no \"dispersed addresses\" such as might be created with\nsomething like LDA #\u003eVECTOR .. LDY #\u003cVECTOR - every relocatable\naddress is two adjacent bytes;  (2) I assemble the source TWICE, to\ntwo different page addresses; the only difference in the binaries will\nbe the high-order bytes of the relocatable addresses; (3) a small\npost-processing program blends the two binaries into a relocatable\npackage, adding a Basic driver to complete the bundle.\n\nNeither the sources for the relocator nor the post-processing program Jim refers to were included\nin the archive, so I disassembled the original supermon64.prg binary and \nreconstructed the relocator stub from that. I also wrote a simple python script that builds a\nrelocatable binary according to Jim's instructions above.  I have confirmed that the\nbinary produced by assembling `supermon64.asm` and `relocator.asm` and then combining them using\n`build.py` is identical to the original binary `supermon64.prg` provided in the archive.\n\nI  converted the usage instructions from a PETSCII file in the archive to the Markdown\nbelow.  Lastly, I researched and documented the history of the code that you are reading now.\nI hope you enjoy this piece of computing history!\n\n## Usage Instructions\n\nSUPERMON+ is a new version of 'SUPERMON'. The reason for the new\nversion is to provide identical commands to those of the built-in\nmonitor of the Commodore 128.\n\nThe most visible changes from earlier versions of SUPERMON are:\n\n  - decimal or binary input allowed;\n  - disk status and commands (@);\n  - looser (easier) syntax.\n\n### Number Conversion \n\n```\n$2000\n      $2000\n      +8192\n      \u002620000\n      %10000000000000\n```\n\nIn the above example the user has asked for the numeric\nequivalents to hexadecimal 2000.  The reply shows the value in hex\n($), in decimal (+), in octal (\u0026) and in binary (%).\n\nThe user could ask for a number to be converted from any of these\nbases by giving the appropriate prefix.\n\nIMPORTANT NOTE -- At any time in the following text, you may enter\nany number in any base and conversion will be done for you.\n\nExample:\n\n```\nm +4096\n```\n\nWill cause a memory display from decimal address 4096. In the\ndisplay, the hex address ($1000) will be shown. Similarly,\n\n```\n+2048 lda#%10000000\n```\n\nWill be converted to assemble: \"a $0400 lda #$80\"\n\nIf you don't give a prefix, the monitor will assume hexadecimal.\n\n\n### Register Display\n\n```\nr\n\n   pc  sr ac xr yr sp\n; 0000 01 02 03 04 05\n```\n\nDisplays the register values saved when SUPERMON+ was entered.\nValues may be changed by typing over the display followed by a\nreturn character.\n\npc - program counter\nsr - status register\nac, xr, yr - a, x, and y registers\nsp - stack pointer\n\n### Memory Display\n\n```\nm 200 209\n\n\u003e0200 4d 20 32 30 30 20 32 30: m 200 20\n\u003e0208 39 00 00 04 00 04 00 04: 9.......\n```\n\nDisplay memory from 0200 hex to 0209 hex. Display is in lines of\n8, so addresses $200 to $20f are shown. If only one address is\nused then 12 lines (96 locations) will be shown. If no address is\ngiven display will go from the last address. Equivalent ASCII\ncharacters are shown in reverse at the right. Values are changed\nby typing over the display followed by a return character.\n\n\n### Exit to BASIC\n\n```\nx\n```\n\nReturn to BASIC READY mode. When you wish to return to SUPERMON+,\ncommand \"SYS 8\".  \n\n### Simple Assembler\n\n```\na 2000 lda #+18\n```\n\nchanges  to:\n\n```\na 2000 a9 12    lda #$12\na 2002  ..next instruction\n```\n\nIn the above example the user started assembly at 2000 hex. The\nfirst instruction was load a register with immediate 18\ndecimal. In following lines the user need not type the \"a\" and\naddress. The simple assembler prompts with the next address. To\nexit the assembler type a return after the the address prompt.\n\nPrevious lines may be changed by typing over the right hand part.\n\n### Disassembler\n\n```\nd 2000 2004\n\n. 2000 a9 12    lda #$12\n. 2002 9d 00 80 sta $8000,x\n```\n\nDisassembles instructions from 2000 to 2004 hex. If one address\nis given, 20 bytes will be disassembled. If no address, \nstart from the last used address.  \n\nCode may be reassembled by moving the cursor back and typing over\nthe right hand part.\n\n\n### Fill Memory\n\n```\nf 1000 1100 ff\n```\n\nfills the memory from 1000 hex to 1100 hex with the byte ff hex.\n\n### Go (run)\n\n```\ng 1000\n```\n\nGo to address 1000 hex and begin running code. If no address is\ngiven, the address from the \u003cpc\u003e register is used.\n\n### Jump (subroutine)\n\n```\nj 1000\n```\n\nCall address 1000 hex and begin running code. Return to the\nmonitor.\n\n### Hunt Memory \n\n```\nh c000 d000 'read\n```\n\nHunt thru memory from c000 hex to d000 hex for the ascii string\n\"read\" and print the address where it is found. A maximum of\n32 characters may be used.\n\n```\nh c000 d000 20 d2 ff\n```\n\nHunt memory from c000 hex to d000 hex for the sequence of bytes\n20 d2 ff and print the address. A maximum of 32 bytes may be used.\n\n### File Handling\n\n#### Load \n\n```\nl\n```\nLoad any program from cassette #1.\n\n```\nl \"ram test\"\n```\n\nLoad from cassette #1 the program named \"ram test\".\n\n```\nl \"ram test\",08\n```\n\nLoad from disk (device 8) the program named  \"ram test\". This\ncommand leaves basic pointers unchanged.\n\n#### Save\n\n```\ns \"program name\",01,0800,0c80\n```\n\nSave to cassette #1 memory from 0800 hex up to but not including\n0c80 hex and name it \"program name\".\n\n```\ns \"0:program name\",08,1200,1f50\n```\n     \nSave to disk drive #0 memory from 1200 hex up to but not including\n1f50 hex and name it \"program name\".\n\n### Transfer Memory \n\n```\nt 1000 1100 5000\n```\n\nTransfer memory in the range 1000 hex to 1100 hex and start storing\nit at address 5000 hex.  \n\n### Compare Memory\n\n```\nc 1000 1100 5000\n```\n\nCompare memory in the range 1000 hex to 1100 hex with memory\nstarting at address 5000 hex.  \n\n### Disk Operations\n\n```\n@\n```\n\nGet disk status message\n\n```\n@9\n```\n\nGet disk unit 9 status message\n\n```\n@,$0\n```\n\nGet drive 0 directory\n\n```\n@,s0:temp\n```\n\nScratch file 'temp' from disk\n\n### Output to Printer\n\nCall SUPERMON+ from basic with:\n```\nopen 4,4:cmd 4:sys 8\n```\nAll commands will go the printer.  When complete, return to basic\nwith \"x\" and command:\n\n```\nprint#4:close 4\n```\n\n\n### Summary\n\n- `$ , + , \u0026 , %`  number conversion\n- `g`  go (run)\n- `j`  jump  (subroutine)\n- `l`  load from tape or disk\n- `m`  memory display\n- `r`  register display\n- `s`  save to tape or disk\n- `x`  exit to basic\n- `a`  simple assembler\n- `d`  disassembler\n- `f`  fill memory\n- `h`  hunt memory\n- `t`  transfer memory\n- `c`  compare memory\n- `@`  disk status/command\n\n### Restarting Supermon\n\nSupermon will load itself into the top of memory...wherever that happens to\nbe on your machine. Be sure to note the SYS command which links SUPERMON\nto the Commodore. It may be used to reconnect the monitor if it is\naccidentally disconnected by use of the run-stop/restore keys.\n\n## License\n\nTo the best of my knowledge, this software is in the public domain.  I claim no ownership.\n\nThe comments in `supermon64.asm` and `relocate.asm` as well as the entirety of `build.py` are my own.\nI hereby place them in the public domain. However, I would greatly appreciate attribution if you make use of them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjblang%2Fsupermon64","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjblang%2Fsupermon64","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjblang%2Fsupermon64/lists"}