This is an emulator for the Commander X16 computer system. It only depends on SDL2 and should compile on all modern operating systems.
11
12
Features
13
--------
14
15
*CPU: 65C02 and 65C816 instruction sets, selected by command line switch
16
* VERA
17
* Mostly cycle exact emulation
18
* Supports almost all features:
19
* composer
20
* two layers
21
* sprites
22
* VSYNC, raster, sprite IRQ
23
* Sound
24
* PCM
25
* PSG
26
* YM2151
27
* Real-Time-Clock
28
* NVRAM
29
* System Management Controller
30
* SD card: reading and writing (image file)
31
* VIA
32
* ROM/RAM banking
33
* keyboard
34
* mouse
35
* gamepads
36
37
Binaries & Compiling
38
--------------------
39
40
Binary releases for macOS, Windows and Linux are available on the [releases page][releases].
41
42
The emulator itself is dependent only on SDL2. However, to run the emulated system you will also need a compatible `rom.bin` ROM image. This will be
43
loaded from the directory containing the emulator binary, or you can use the `-rom .../path/to/rom.bin` option.
44
45
>__WARNING:__ Older versions of the ROM might not work in newer versions of the emulator, and vice versa.
46
47
You can build a ROM image yourself using the [build instructions][x16rom-build] in the [x16-rom] repo. The `rom.bin` included in the [_latest_ release][releases] of the emulator may also work with the HEAD of this repo, but this is not guaranteed.
48
49
###macOS Build
50
51
Install SDL2 using `brew install sdl2`.
52
53
###Linux Build
54
55
The SDL2 development package is available as a distribution package with most major versions of Linux:
56
-Red Hat: `yum install SDL2-devel`
57
- Debian: `apt-get install libsdl2-dev`
58
59
Type `make` to build the source. The output will be `x16emu` in the current directory. Remember you will also need a `rom.bin` as described above.
It builds and runs as on any Linux; nothing in the Makefile or the sources is specific to RISC-V. Checked on an OrangePi RV2 (Ky X1, eight X60 cores at 1.6 GHz) with Ubuntu 24.04, gcc 13.3 and SDL 2.30:
64
65
```
66
sudo apt-get install build-essential make libsdl2-dev zlib1g-dev
67
make -j8
68
```
69
70
The Makefile's `-Werror` build is clean there, and takes about two minutes. To run it without a display, use SDL's dummy drivers:
-**Speed.** On that board it keeps up with a real X16 at the BASIC prompt and in programs that wait for VSYNC with `WAI` (with about 40% to spare), and reaches about 63% of real speed in a program that draws on the bitmap and plays FM and PSG sound without pause. The emulator's window title shows its own figure.
79
-**A display without a GPU driver.** Drawn by Mesa's software OpenGL (under Xvfb, for instance), the window ran at 3-4% of real speed: the time goes to drawing the window, not to the emulation.
80
-**`SDL_VIDEODRIVER=wayland` without a compositor** makes `SDL_Init` fail ("wayland not available"); set `SDL_VIDEODRIVER=x11` or `dummy`.
81
-**Measuring.** On the X60, where hot code happens to land can move run time by several per cent, so compare builds over several runs, not one.
82
- The control API's conformance suite (`src/extern/retro-remote-debug-controller/conformance`) runs natively as `.github/workflows/conformance.yml` runs it, with `python3-pytest` installed.
Steps for compiling WebAssembly/HTML5 can be found [here][webassembly].
87
88
###Windows Build
89
90
Currently macOS/Linux/MSYS2 is needed to build for Windows. Install mingw-w64 toolchain and mingw32 version of SDL.
91
Type the following command to build the source:
92
```
93
CROSS_COMPILE_WINDOWS=1 MINGW32=/usr/x86_64-w64-mingw32 WIN_SDL2=/usr/x86_64-w64-mingw32 make
94
```
95
Paths to those libraries can be changed to your installation directory if they aren't located there.
96
97
The output will be `x16emu.exe` in the current directory. Remember you will also need a `rom.bin` as described above and `SDL2.dll` in SDL2's binary folder.
98
99
100
Starting
101
--------
102
103
You can start `x16emu`/`x16emu.exe` either by double-clicking it, or from the command line. The latter allows you to specify additional arguments.
104
When starting `x16emu` without arguments, it will pick up the system ROM (`rom.bin`) from the executable's directory.
105
106
*`-prg <app.prg>[,<load_addr>]` lets you specify a `.prg` file that gets loaded after start. It is fetched from the host filesystem, even if an SD card is attached. The override load address is hex without a prefix.
107
*`-bas <app.txt>` lets you specify a BASIC program in ASCII format that automatically typed in (and tokenized).
108
*`-run` executes the application specified through `-prg` or `-bas` using `RUN`.
109
*`-scale {1|2|3|4}` scales video output to an integer multiple of 640x480
*`-widescreen` Stretch output to 16:9 resolution to mimic display of a widescreen monitor.
115
*`-fullscreen` Start up in fullscreen mode instead of in a window.
116
*`-opacity (0.0,...,1.0)` Set the opacity value (0.0 for transparent, 1.0 for opaque) of the window. (default: 1.0)
117
*`-rtc` causes the real-time-clock set to the system's time and date.
118
*`-echo [{iso|raw}]` causes all KERNAL/BASIC output to be printed to the host's terminal. Enable this and use the BASIC command "LIST" to convert a BASIC program to ASCII (detokenize).
119
*`-rom <rom.bin>` Override KERNAL/BASIC/* ROM file.
120
*`-ram <ramsize>` specifies banked RAM size in KB (8, 16, 32, ..., 2048). The default is 512.
121
*`-cart <crtfile.crt>` loads a cartridge file. This requires a specially formatted cartridge file, as specified in the documentation.
122
*`-cartbin <romfile.bin>` loads a raw cartridge file. This will be loaded starting at ROM bank 32. All cart banks will be flagged as RAM.
123
*`-joy1`, `-joy2`, `-joy3`, `-joy4` enables binding a gamepad to that SNES controller port
124
*`-nvram` lets you specify a 64 byte file for the system's non-volatile RAM. If it does not exist, it will be created once the NVRAM is modified.
125
*`-keymap` tells the KERNAL to switch to a specific keyboard layout. Use it without an argument to view the supported layouts.
126
*`-noemucmdkeys` Disable emulator command keys. `Ctrl+M`/`⇧⌘M` will always be intercepted by the emulator.
127
*`-capture` starts the emulator with the mouse/keyboard captured
128
*`-nokeyboardcapture` prevents the emulator from fully capturing the keyboard in capture mode, which allows OS-level keystrokes like Alt+Tab to work while in capture mode.
129
*`-sdcard` lets you specify an SD card image (partition table + FAT32) which will be presented as device 8 at boot.
130
*`-hostfsdev <unit>` specifies the device number to use for the HostFS device. If this argument is not used, and `-sdcard` is specified, HostFS is disabled. If `-sdcard` is not specified, the default is 8. If both `-sdcard` and `-hostfsdev 8` are specified, HostFS will take precedence, but both will be active. In this circumstance, if the HostFS device is changed away from unit 8 via a channel 15 command (e.g. `"S-9"`), the SD card device will then become visible on unit 8.
131
*`-fsroot <dir>` specifies a file system root for the HostFS interface. This lets you save and load files without an SD card image. (As of R42, this is the preferred method.) Default is the current working directory.
132
*`-startin <dir>` specify the host filesystem directory path that the emulated filesystem starts in. Default is the current working directory if it lies within the hierarchy of fsroot, otherwise it defaults to fsroot itself.
133
*`-serial` makes accesses to the host filesystem go through the Serial Bus [experimental].
134
*`-nohostieee` or `-nohostfs` disables IEEE API interception to access the host fs. IEEE API HostFS is normally enabled unless `-sdcard` or `-serial` is specified.
135
*`-warp` causes the emulator to run as fast as possible, possibly faster than a real X16.
136
*`-pastewarp` causes the emulator to enter warp mode during pasting (`Ctrl+V` or `⌘V`) and during loading via `-bas`.
137
*`-gif <filename>[,wait]` to record the screen into a GIF. See below for more info.
138
*`-wav <filename>[{,wait|,auto}]` to record audio into a WAV. See below for more info.
139
*`-log` enables one or more types of logging (e.g. `-log KS`):
140
*`K`: keyboard (key-up and key-down events)
141
*`S`: speed (CPU load, frame misses)
142
*`V`: video I/O reads and writes
143
*`-debug [<address>]` enables the debugger. Optionally, set a breakpoint
144
*`-dump` configure system dump (e.g. `-dump CB`):
145
*`C`: CPU registers (7 B: A,X,Y,SP,STATUS,PC)
146
*`R`: RAM (40 KiB)
147
*`B`: Banked RAM (2 MiB)
148
*`V`: Video RAM and registers (128 KiB VRAM, 32 B composer registers, 512 B palette, 16 B layer0 registers, 16 B layer1 registers, 16 B sprite registers, 2 KiB sprite attributes)
149
*`-memorystats <filename.txt>` Saves memory read and write access statistics to the given file when emulator exits.
150
*`-testbench` Headless mode for unit testing with an external test runner
151
*`-sound <device>` can be used to specify the output sound device. If 'none', no audio is generated.
152
*`-abufs` can be used to specify the number of audio buffers (defaults to 8 when using the SD card, 32 when using HostFS). If you're experiencing stuttering in the audio, try increasing this number. This will result in additional audio latency though.
153
*`-via2` installs the second VIA chip expansion at $9F10.
154
*`-midline-effects` enables mid-scanline raster effects at the cost of vastly increased host CPU usage.
155
*`-mhz <integer>` sets the emulated CPU's speed. Range is from 1-40. This option is mainly for testing and benchmarking.
156
*`-enable-ym2151-irq` connects the YM2151's IRQ pin to the system's IRQ line with a modest increase in host CPU usage.
157
*`-wuninit` enables warnings on the console for reads of uninitialized memory.
158
*`-zeroram` fills RAM at startup with zeroes instead of the default of random data.
159
*`-version` prints additional version information of the emulator and ROM.
160
*`-c02` selects the 65C02 CPU (default).
161
*`-c816` selects the 65C816 CPU (experimental).
162
*`-rockwell` when used while running with the 65C02 CPU, suppresses the console warning emitted on the first occurence when executing a Rockwell instruction. These are the SMBx, RMBx, BBRx, and BBSx instructions. Since these instructions are not supported on the 65C816 processor, such a program using them would not run properly on the 65C816.
163
*`-longpwron` Simulate a long press of the power button at system power-on.
164
* When compiled with `#define TRACE`, `-trace` will enable an instruction trace on stdout.
165
166
Run `x16emu -h` to see all command line options.
167
168
Keyboard Layout
169
---------------
170
171
The X16 uses a PS/2 keyboard, and the ROM currently supports several different layouts. The following table shows their names, and what keys produce different characters than expected:
Keys that produce international characters (like [ä] or [ç]) will not produce any character.
190
191
Since the host computer tells the Commander X16 via the emulator the *position* of keys that are pressed, you need to configure the layout for the X16 independently of the keyboard layout you have configured on the host.
192
193
**Use the `MENU` command to select a layout, or set the keyboard layout at startup using the `-keymap` command line argument.**
194
195
The following keys can be used for controlling games:
196
197
|Keyboard Key | SNES Equivalent |
198
|--------------|-----------------|
199
|X or Ctrl | A |
200
|Z or Alt | B |
201
|S | X |
202
|A | Y |
203
|D | L |
204
|C | R |
205
|Shift | SELECT |
206
|Enter | START |
207
|Cursor Up | UP |
208
|Cursor Down | DOWN |
209
|Cursor Left | LEFT |
210
|Cursor Right | RIGHT |
211
212
213
Options for the WebEmulator
214
--------
215
216
The following options are available for the WebEmulator. With the exception of manifest, they all work exactly the same as in the normal emulator.
217
*`manifest`
218
*`ram`
219
*`cpu`
220
*`mhz`
221
*`keymap`
222
*`longpwron`
223
*`widescreen`
224
*`capture`
225
*`midlineeffects`
226
227
####The Address Line
228
`manifest` tells the emulator what should be loaded as a startup program. If the file is a .bas or .prg, the emulator will load it and try to execute it. If the file is a .zip, the WebEmulator will get access to all the files inside that zip-file. When using a zip-file you may add a manifest file to provide additional information - See section below for more information on `manifest.json`
229
230
On the Commander X16 forums, a link to the webemulator could look something like this:
This will load the forum file with id 1218 into the emulator.
233
Give the emulator 2MB of RAM
234
Set the CPU type to 65C816
235
Set the CPU speed at 10 MHz
236
Set the keyboard layout to Danish
237
Show the emulator in widescreen mode
238
Capture the mouse and keyboard input
239
The options `longpwron`, `widescreen`, `capture`&`midlineeffects` do not have any values, it is enough to have them on the address line to enable the feature.
240
241
####The manifest.json File
242
If an application requires more than a single file to function, for example graphics or audio assets, it is necessary to package the needed files in a zip file. If there are more than one start file (BAS or PRG) the `manifest.json` file can be used to specify the default start file with `start_prg` or `start_bas` otherwise the WebEmulator will start the .prg or .bas it finds in the zip file.
243
244
Here is an example of the optional `manifest.json` file
245
246
{
247
"manifest_version": "1.0.0",
248
"name": "My Program",
249
"author": "John Smith",
250
"app_version": "1.0.0",
251
"license": "GPL 3",
252
"ram": "2048",
253
"cpu": "c816",
254
"mhz": "10",
255
"keymap": "da",
256
"widescreen": true,
257
"capture": true,
258
"longpwron": false,
259
"midlineeffects": false,
260
"start_prg": "MYPROG.PRG",
261
"resources": [
262
"MYPROG.PRG",
263
"FILE1.BIN",
264
"FILE2.BIN"
265
]
266
}
267
268
If the resources section is present, only files specified will be made available to the WebEmulator.
269
Options set in `manifest.json` will override options on the address line.
270
271
Functions while running
272
-----------------------
273
274
####Windows and Linux
275
*`Ctrl` + `F` and `Ctrl` + `Return` will toggle full screen mode.
276
*`Ctrl` + `M` will toggle mouse capture mode.
277
*`Ctrl` + `P` will write a screenshot in PNG format to disk.
278
*`Ctrl` + `R` will reset the computer.
279
*`Ctrl` + `Backspace` will send an NMI to the computer (like RESTORE key).
280
*`Ctrl` + `S` will save a system dump (configurable with `-dump`) to disk.
281
*`Ctrl` + `V` will paste the clipboard by injecting key presses.
282
*`Ctrl` + `=` and `Ctrl` + `+` will toggle warp mode.
283
284
####Mac OS
285
*`⌘F` and `⌘Return` will toggle full screen mode.
286
*`⇧⌘M` will toggle mouse capture mode.
287
*`⌘P` will write a screenshot in PNG format to disk.
288
*`⌘R` will reset the computer.
289
*`⌘Delete` aka `⌘Backspace` will send an NMI to the computer (like RESTORE key).
290
*`⌘S` will save a system dump (configurable with `-dump`) to disk.
291
*`⌘V` will paste the clipboard by injecting key presses.
292
*`⌘=` and `⇧⌘+` will toggle warp mode.
293
294
295
GIF Recording
296
-------------
297
298
With the argument `-gif`, followed by a filename, a screen recording will be saved into the given GIF file. Please exit the emulator before reading the GIF file.
299
300
If the option `,wait` is specified after the filename, it will start recording on `POKE $9FB5,2`. It will capture a single frame on `POKE $9FB5,1` and pause recording on `POKE $9FB5,0`. `PEEK($9FB5)` returns a 128 if recording is enabled but not active.
301
302
303
WAV Recording
304
-------------
305
306
With the argument `-wav`, followed by a filename, an audio recording will be saved into the given WAV file. Please exit the emulator before reading the WAV file.
307
308
If the option `,wait` is specified after the filename, it will start recording on `POKE $9FB6,1`. If the option `,auto` is specified after the filename, it will start recording on the first non-zero audio signal. It will pause recording on `POKE $9FB6,0`. `PEEK($9FB6)` returns a 1 if recording is enabled but not active.
309
310
311
Emulator I/O registers
312
-------------------
313
x16-emulator exposes registers in the range of, from `$9FB0`-`$9FBF`, which allows one to control or toggle various emulator features from within emulated code.
314
315
When writing machine code that uses these registers, good practice is to read `$9FBE` and `$9FBF` and check for their return values. If the emulator is present, those memory locations will return the ASCII/PETSCII characters "1" and "6" respectively (`$31` and `$36` hex). After verifying that the code is running under the emulator, you can confidently use the features provided by these registers.
316
317
Several of the following registers are particularly useful for debugging. In particular, writing data to `$9FB9`, `$9FBA`, or `$9FBB` will output debug information to the console, terminal, or command prompt window from which you ran x16emu.
318
319
320
| Register | Read Behavior | Write Behavior |
321
|-|-|-|
322
| \$9FB0 | Returns debugger enabled flag |`0` disables, `1` enables the debugger, overriding the absence or presence of the `-debug` command line argument. |
323
| \$9FB1 | Returns video logging flag |`0` disables, `1` enables logging of VRAM accesses to the console |
324
| \$9FB2 | Returns keyboard logging flag |`0` disables, `1` enables logging of keyboard events to the console |
325
| \$9FB3 | Returns echo mode |`0` disables, `1` enables raw echo, `2` enables cooked (`\Xnn` for non-ASCII), and `3` enables ISO (w/ conversion to UTF-8). When on, characters sent via the `BSOUT` KERNAL call will also appear on the console. |
326
| \$9FB4 | Returns save-on-exit flag |`0` disables, `1` enables save-on-exit. When this option is set and the program counter reaches \$FFFF, the emulator outputs a dump of emulator state to `dump.bin` before exiting. |
327
| \$9FB5 | Returns GIF recorder state |`0` pauses, `1` captures a single frame, and `2` activates/resumes GIF recording. The path to the GIF file must have been passed to the `-gif` command line option in advance. |
328
| \$9FB6 | Returns WAV recorder state |`0` pauses, `1` enables WAV recording, and `2` sets up autostart. The path to the WAV file must have been passed to the `-wav` command line option in advance. |
329
| \$9FB7 | Returns emu command key flag |`0` allows, and `1` inhibits most emulator command keys. Setting this flag prevents the emulator from intercepting keystrokes such as Ctrl+V/⌘V or Ctrl+R/⌘R, allowing the Commander X16 application running inside to make use of them. |
330
| \$9FB8 | Latches the cpu clock counter and returns bits 0-7 | Resets the cpu clock counter to 0 |
331
| \$9FB9 | Returns bits 8-15 from the latched cpu clock counter value | Outputs `"User debug 1: $xx"` to the console with xx replaced by the value written. |
332
| \$9FBA | Returns bits 16-23 from the latched cpu clock counter value | Outputs `"User debug 2: $xx"` to the console with xx replaced by the value written. |
333
| \$9FBB | Returns bits 24-31 from the latched cpu clock counter value | Outputs the given character to the console. This is basically a STDOUT port for programs running in the emulator. Only printable characters are allowed. Non-printables are replaced with �.
334
| \$9FBC | - | - |
335
| \$9FBD | Returns the keymap index, based on the argument to the `-keymap` command line option | - |
336
| \$9FBE | Returns the value `$31`/ASCII "1", useful for emulator presence detection | - |
337
| \$9FBF | Returns the value `$36`/ASCII "6", useful for emulator presence detection | - |
338
339
340
BASIC and the Screen Editor
341
---------------------------
342
343
On startup, the X16 presents direct mode of BASIC V2. You can enter BASIC statements, or line numbers with BASIC statements and `RUN` the program, just like on Commodore computers.
344
345
*To stop execution of a BASIC program, hit the `RUN/STOP` key (`Pause`), or `Ctrl+C`.
346
* To insert characters, first insert spaces by pressing `Shift+Backspace` or `Insert`, then type over those spaces.
347
* To clear the screen, press `Shift+Home`.
348
* To send NMI, similar to `STOP+RESTORE` on the C64, use Ctrl+Backspace/⌘Delete. On real hardware this is done with `Ctrl+Alt+RESTORE` (`Ctrl+Alt+PrtScr`) or by pressing the NMI button.
349
350
351
SD Card Images
352
--------------
353
354
The command line argument `-sdcard` lets you attach an image file for the emulated SD card. Using an emulated SD card makes filesystem operations go through the X16's DOS implementation, so it supports all filesystem operations (including directory listing though `DOS"$` command channel commands using the `DOS` statement) and guarantees full compatibility with the real device.
355
356
Images must be greater than 32 MB in size and contain an MBR partition table and a FAT32 filesystem. The file `sdcard.img.zip` in this repository is an empty 100 MB image in this format.
357
358
On macOS, you can just double-click an image to mount it, or use the command line:
359
360
# hdiutil attach sdcard.img
361
/dev/disk2 FDisk_partition_scheme
362
/dev/disk2s1 Windows_FAT_32 /Volumes/X16 DISK
363
# [do something with the filesystem]
364
# hdiutil detach /dev/disk[n] # [n] = number of device as printed above
365
366
On Linux, you can use the command line:
367
368
# sudo losetup -P /dev/loop21 disk.img
369
# sudo mount /dev/loop21p1 /mnt # pick a location to mount it to, like /mnt
370
# [do something with the filesystem]
371
# sudo umount /mnt
372
# sudo losetup -d /dev/loop21
373
374
On Windows, you can use the [OSFMount](https://www.osforensics.com/tools/mount-disk-images.html) tool. Windows VHD files can also be created using the built-in Disk Manager. Careful attention should be paid to the settings when creating and formatting the VHD:
375
376
*The file must be at least 32MB and must be fixed size. Expanding VHDs are not supported.
377
* Use an MBR partition tables. The Commander X16 does not recognize GPT partition tables.
378
* You must format the VHD with FAT32. Other file formats are not supported.
379
380
This is a trick, since Fixed-size VHD files contain the data first, with the metadata in a footer at the end. Since the emulator does not read or edit that medatada, it will only work with fixed-size files that are fully populated.
381
382
383
Host Filesystem Interface
384
-------------------------
385
386
If the system ROM contains any version of the KERNAL, and there is no SD card image attached, all accesses to the ("IEEE") Commodore Bus are intercepted by the emulator for device 8 (the default). So the BASIC statements will target the host computer's local filesystem:
387
388
DOS"$"
389
LOAD"FOO.PRG"
390
LOAD"IMAGE.PRG",8,1
391
SAVE"BAR.PRG"
392
OPEN2,8,2,"FOO,S,R"
393
394
The emulator will interpret filenames relative to the directory it was started in. On macOS, when double-clicking the executable, this is the home directory. To specify a different path as the emulated root, you can use the `-fsroot` command line option.
395
396
To avoid compatibility problems between the PETSCII and ASCII encodings, you can
397
398
*use uppercase filenames on the host side, and unshifted filenames on the X16 side.
399
* use `Ctrl+O` to switch to the X16 to ISO mode for ASCII compatibility.
400
* use `Ctrl+N` to switch to the upper/lower character set for a workaround.
401
402
As of R42, the Host Filesystem interface (or HostFS) is the preferred method of accessing files. It does not require creating or managing an SDcard image, and it supports all of the CMDR-DOS commands. However, it is not cycle-accurate, since the emulator traps calls to DOS and performs the same actions in the host environment. If performance and hardware accuracy is required, you will want to perform final testing using an SD card image.
403
404
Dealing with BASIC Programs
405
---------------------------
406
407
BASIC programs are encoded in a tokenized form when saved. They are not simply ASCII files. If you want to edit BASIC programs on the host's text editor, you need to convert it to tokenized BASIC encoding from ASCII encoding before calling `LOAD` in the emulator.
408
409
*To convert the basic file from ASCII to tokenized BASIC encoding, reboot the machine and paste the ASCII text using `Ctrl + V` (Mac: `Cmd + V`) into the terminal. You can now run the program with `RUN`, or use the `SAVE` BASIC command to write the tokenized version to the host disk. Below is an example.
410
1. Copy ASCII text from host basic file "PRG.BAS"
411
2. Paste into new terminal session
412
3.`SAVE"ENCODED.BAS`
413
4. Now you can restart the emulator and load the encoded basic file with `LOAD"ENCODED.BAS"`
414
5. Run with `RUN"ENCODED.BAS"`
415
416
*To convert BASIC to ASCII, start x16emu with the `-echo` argument, `LOAD` the BASIC file, and type `LIST`. Now copy the ASCII version from the terminal.
417
418
419
Using the KERNAL/BASIC environment
420
----------------------------------
421
422
Please see the [KERNAL/BASIC documentation](https://github.com/X16Community/x16-docs/).
423
424
425
Debugger
426
--------
427
428
The debugger requires `-debug`. To start the debugger, press the F12 key. Without `-debug`, the debugger is disabled and won't start. If you wish to set an initial breakpoint you can also include the memory address, in hexadecimal, of the breakpoint after the `-debug` switch. For example `-debug 080d`.
429
430
There are 2 panels you can control. The code panel, the top left half, and the data panel, the bottom half of the screen. You can also edit the contents of the registers PC, A, B, C, D, K, DB, X, Y, and SP.
431
432
Greyed out numbers in the register display indicate values that are fixed at their given value due to the current processor state. This applies to
433
-the high bytes of X and Y if the index flags is set
434
- the flags M (memory) and I (index) if emulation mode is active
435
- the high byte of SP if emulation mode is active.
436
437
The debugger uses its own command line with the following syntax:
|d %x|Change the code panel to view disassembly starting from the address %x.|
442
|m %x|Change the data panel to view memory starting from the address %x.|
443
|v %x|Display VERA RAM (VRAM) starting from address %x.|
444
|b %s %d|Changes the current memory bank for disassembly and data. The %s param can be either 'ram' or 'rom', the %d is the memory bank to display (but see NOTE below!).|
445
|r %s %x|Changes the value in the specified register. Valid registers in the %s param are 'pc', 'a', 'b', 'c', 'd', 'k', 'dbr', 'x', 'y', and 'sp'. %x is the value to store in that register.|
446
447
NOTE. To disassemble or dump memory locations in banked RAM or ROM, prepend the bank number to the address; for example, "m 4a300" displays memory contents of BANK 4, starting at address $a300. This also works for the 'd' command.
448
449
The debugger keys are similar to the Microsoft Debugger shortcut keys, and work as follows
| F1 | resets the disassembly position to the current PC |
454
| F2 | resets the emulated CPU but not any of the hardware. |
455
| F5 | close debugger window and return to Run mode, the emulator should run as normal. |
456
| F9 | sets the breakpoint to the currently code position. |
457
| F10 | steps 'over' routines - if the next instruction is JSR it will break on return. |
458
| F11 | steps 'into' routines. |
459
| F12 | is used to break back into the debugger. This does not happen if you do not have -debug |
460
| PAGE UP | scrolls memory up by page. |
461
| PAGE DOWN | scrolls memory down by page. |
462
| Shift + PAGE UP | scrolls disassembly up by 16 bytes. |
463
| Shift + PAGE DOWN | scrolls disassembly down by 16 bytes. |
464
| UP | scrolls memory up by row. |
465
| DOWN | scrolls memory down by row. |
466
| Shift + UP | scrolls disassembly up by one byte. |
467
| Shift + DOWN | scrolls disassembly down by one byte. |
468
| TAB | when stopped, or single stepping, hides the debug panel while pressed. |
469
470
When `-debug` is selected the STP instruction (opcode $DB) will break into the debugger automatically.
471
472
Keyboard routines only work when the emulator is running normally. Single stepping through keyboard code will not work at present.
473
474
CRT File Format
475
---------------
476
477
The Commander X16 will support cartridge ROMs, including auto-booting game cartridges. On the Gen-1 Developer board, the first slot will be used for cartridges. On the Gen-2 console machine, there is only one slot. ROM carts should work on both systems.
478
479
This CRT format is intended for the emulator, and it is not required or used by the hardware. You can, however, use the MakeCart tool to convert between a single CRT file and BIN files that can be used to program a ROM burner. Also, note that this is different from the CRT format used the VICE emualtor, so files are not interchangable.
480
481
Commander X16 cartridges will occupy the same address space as the Commander's KERNAL and BASIC ROMs. You can control the active bank by writing to address $0001 on the computer. Banks 0-31 are the built-in ROM banks, and banks 32-255 will select the cartridge ROMs.
482
483
###Header Layout
484
485
This is the cartridge header. The first 256 bytes are ASCII data and Human readable. The second 256 bytes are bank data; these are byte integers. Text fields are set to 16 or 32-byte boundaries for ease of formatting.
||| 00: Not Present. No data is present in the emulator or in the file. |
499
||| 01: ROM: 16KB of ROM data. Data is write protected in emulator. |
500
||| 02: RAM: No data in file. Bank is read/write in emulator. |
501
||| 03: RAM: Data present: data is loaded from the file and discarded on shutdown. Useful for testing. |
502
||| 04: NVRAM: No Data in file. Memory is writeable. Emulator saves data to NVRAM file. |
503
||| 05: NVRAM: Data present. Memory is writeable. Emulator saves data to NVRAM file. |
504
| 512-end || Payload data. |
505
||| 16384 bytes per bank for types 1, 3, and 5. |
506
||| 0 bytes for types 0,2, and 4. |
507
508
509
For NVRAM banks: on shutdown, the emulator will write out an NVRAM file that contains the data of all of the NVRAM banks. The next time this cartridge is started, the NVRAM file will be loaded into any NVRAM bank. This overwrites any data present in NVRAM banks in the CRT file.
510
511
For types 00, 02, and 04: The file does *not* contain data for these bank types. Instead, the file skips straight to the next bank with initialized data (01, 03, or 05).
512
513
For all "No Data" banks, the data in RAM is *undefined*. While the emulator currently initializes RAM to 0 bytes, the hardware will have random values. In addition, unpopulated addresses will be "open collector" and will have unpredicatable results.
514
515
###Vectors
516
517
X16 hardware, and thus the emulator, will only read 6502 vectors out of bank 0. This is done via the CPU's VPB pin being connected to the ROM bank latch reset pin. In the past specific vectors were recommended in cartridge ROMs, but this is no longer true. In cartridges, the addresses `$FFFA`-`$FFFF` are free to use for data.
518
519
520
<!-- For PDF formatting -->
521
<divclass="page-break"></div>
522
523
##MakeCart Conversion Tool
524
525
A conversion tool to pack cartridge data into a CRT file, `makecart`, is included in this release.
526
527
`-cfg <filename.cfg>`
528
Use this file to pack the cartridge data. Config file is simply the command line switches, one per line.
529
530
`-desc "Name/Description"`
531
Set the description field of the cartridge file. Up to 32 bytes of ASCII text.
532
533
`-author "Author Information"`
534
Set the author information field of the cartridge file. Up to 32 bytes of ASCII text.
535
536
`-copyright "Copyright Information"`
537
Set the copyright information field of the cartridge file. Up to 32 bytes of ASCII text.
538
539
`-version "version"`
540
Set the version information field of the cartridge file. Up to 32 bytes of ASCII text.
541
542
`-fill <value>`
543
Set the fill value to use with any partially-filled banks of cartridge memory. Value can be defined in decimal, or in hexadecimal with a '$' or '0x' prefix. 8-bit values will be repeated every byte, 16-bit values every two bytes, and 32-bit values every 4 bytes.
Define rom banks from the specified list of files. File data is tightly packed -- if a file does not end on a 16KB interval, the next file will be inserted immediately after it within the same bank. If the last file does not end on a 16KB interval, the remainder of the rom will be filled with the value set by '-fill'.
548
549
Valid bank numbers are 32 - 255.
550
551
`-ram <start_bank> [<end bank>]`
552
Define one or more banks of RAM. RAM banks are not included in the payload.
Define pre-initialized nvram banks from the specified list of files. File data is tightly packed like with -rom. If the last file does not end on a 16KB interval, the remainder of the rom will be filled with the value set by '-fill'.
566
567
`-none <start_bank> [<end_bank>]`
568
Define one or more unpopulated banks of the cartridge. By default, all banks are unpopulated unless specified by a previous command-line option. These banks are not present in the payload and only popualte the bank header in the CRT file.
569
570
`-o <output.crt>`
571
Set the filename of the output cartridge file.
572
573
All options can be specified multiple times, and are applied in-order from left to right. For -desc and -o, it is legal to specify them multiple times but only the right-most instances of each will have effect.
574
575
`-unpack <input.crt> [<rom_size>]`
576
Unpacks the binary data from the cartridge file into `<rom_size>` slices. (for use with an EPROM programmer.) The ouptut files will be the same filename as the input file, with _### appended. This will also create a .cfg file that can be used to re-pack the files into a new CRT if needed.
577
578
The config file is just a series of command-line switches, with one item per line. This example assumes ladder.bin uses 3 banks, for a total of 48K, and that each level map is 4KB in size.
Since the NVRAM bank is not initialized, it is not included in the file. This makes the file a total of 66,048 bytes long. (512 bytes, plus four 16KB banks.)