chore(): initial commit 03a3459e6372

# http://clang.llvm.org/docs/ClangFormatStyleOptions.html

BasedOnStyle: LLVM

AccessModifierOffset: -4

AlignAfterOpenBracket: AlwaysBreak

AlignConsecutiveAssignments: true

AlignConsecutiveDeclarations: true

AlignEscapedNewlinesLeft: true

AlignOperands: true

AlignTrailingComments: true

AllowAllParametersOfDeclarationOnNextLine: true

AllowShortBlocksOnASingleLine: false

AllowShortCaseLabelsOnASingleLine: true

AllowShortFunctionsOnASingleLine: false

AllowShortIfStatementsOnASingleLine: false

AllowShortLoopsOnASingleLine: false

AlwaysBreakAfterDefinitionReturnType: All

AlwaysBreakAfterReturnType: None

AlwaysBreakBeforeMultilineStrings: true

# AlwaysBreakTemplateDeclarations (bool)

# BinPackArguments (bool)

BinPackParameters: true

# BraceWrapping (BraceWrappingFlags)

# BreakAfterJavaFieldAnnotations (bool)

# BreakBeforeBinaryOperators (BinaryOperatorStyle)

BreakBeforeBraces: Linux

# BreakBeforeTernaryOperators (bool)

# BreakConstructorInitializersBeforeComma (bool)

# BreakStringLiterals (bool)

ColumnLimit: 0

# CommentPragmas (std::string)

# ConstructorInitializerAllOnOneLineOrOnePerLine (bool)

# ConstructorInitializerIndentWidth (unsigned)

# ContinuationIndentWidth (unsigned)

# Cpp11BracedListStyle (bool)

DerivePointerAlignment: false

# DisableFormat (bool)

# ExperimentalAutoDetectBinPacking (bool)

# ForEachMacros (std::vector<std::string>)

# IncludeCategories (std::vector<IncludeCategory>)

# IncludeIsMainRegex (std::string)

IndentCaseLabels: true

IndentWidth: 4

# IndentWrappedFunctionNames (bool)

# JavaScriptQuotes (JavaScriptQuoteStyle)

# KeepEmptyLinesAtTheStartOfBlocks (bool)

# Language (LanguageKind)

# MacroBlockBegin (std::string)

# MacroBlockEnd (std::string)

# MaxEmptyLinesToKeep (unsigned)

NamespaceIndentation: All

# ObjCBlockIndentWidth (unsigned)

# ObjCSpaceAfterProperty (bool)

# ObjCSpaceBeforeProtocolList (bool)

# PenaltyBreakBeforeFirstCallParameter (unsigned)

# PenaltyBreakComment (unsigned)

# PenaltyBreakFirstLessLess (unsigned)

# PenaltyBreakString (unsigned)

# PenaltyExcessCharacter (unsigned)

# PenaltyReturnTypeOnItsOwnLine: 1000

PointerAlignment: Right

# ReflowComments (bool)

SortIncludes: false

# SpaceAfterCStyleCast (bool)

# SpaceAfterTemplateKeyword (bool)

SpaceBeforeAssignmentOperators: true

SpaceBeforeParens: ControlStatements

SpaceInEmptyParentheses: false

# SpacesBeforeTrailingComments (unsigned)

# SpacesInAngles (bool)

SpacesInCStyleCastParentheses: false

# SpacesInContainerLiterals (bool)

SpacesInParentheses: false

SpacesInSquareBrackets: false

# Standard (LanguageStandard)

TabWidth: 4

UseTab: ForIndentation

IndentPPDirectives: AfterHash

root = true

[*]

charset = utf-8

end_of_line = lf

indent_style = tab

insert_final_newline = true

tab_width = 4

trim_trailing_whitespace = true

[README]

indent_style = space

[*.yml]

indent_style = space

[*.py]

indent_style = space

[*.md]

indent_style = space

[{*.css,*.html,*.js}]

indent_style = space

# Arcade reference material (ROM dumps, disassembly, sprite sheets) —

# local-only, never shipped. Generated headers derived from it ARE

# committed (same policy as the sibling pac-man-x16 project).

reference/

# Git 

.git

.github

.gitignore

.gh

.github-pandoc.css

.gitmodules

# Legacy build

.travis

.travis.yml

# The Flow image .flow/image/build.sh exports: about 2.3 GB.

/.flow/image/*.tar

# Build output

bin/

release/

build/

# Emulator scratch (memory.dump, storage volume side effects)

memory.dump

*.neo

!src/**/*.neo

# llvm-mos / C build artefacts

*.o

*.obj

*.elf

*.lst

*.map

# Editor / OS noise

.vscode/

.idea/

*.swp

.DS_Store

# Tiled session state

*.tiled-session

# Python

__pycache__/

*.pyc

.ruff_cache/

.pytest_cache/

.venv/

venv/

# build-generated

src/generated/

# Local cross-session coordination + audit scratch — shared out-of-band by

# absolute path, deliberately never committed (a stray `git add -A` swept the

# board into a PR once; this stops it recurring).

docs/calculator_codesign.md

agy_audit.md

reference/

# AI

.claude

# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as

contributors and maintainers pledge to making participation in our project and

our community a harassment-free experience for everyone, regardless of age, body

size, disability, ethnicity, sex characteristics, gender identity and expression,

level of experience, education, socio-economic status, nationality, personal

appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment

include:

* Using welcoming and inclusive language

* Being respectful of differing viewpoints and experiences

* Gracefully accepting constructive criticism

* Focusing on what is best for the community

* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or

 advances

* Trolling, insulting/derogatory comments, and personal or political attacks

* Public or private harassment

* Publishing others' private information, such as a physical or electronic

 address, without explicit permission

* Other conduct which could reasonably be considered inappropriate in a

 professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable

behavior and are expected to take appropriate and fair corrective action in

response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or

reject comments, commits, code, wiki edits, issues, and other contributions

that are not aligned to this Code of Conduct, or to ban temporarily or

permanently any contributor for other behaviors that they deem inappropriate,

threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces

when an individual is representing the project or its community. Examples of

representing a project or community include using an official project e-mail

address, posting via an official social media account, or acting as an appointed

representative at an online or offline event. Representation of a project may be

further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be

reported by contacting the project team at [email protected]. All

complaints will be reviewed and investigated and will result in a response that

is deemed necessary and appropriate to the circumstances. The project team is

obligated to maintain confidentiality with regard to the reporter of an incident.

Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good

faith may face temporary or permanent repercussions as determined by other

members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,

available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see

https://www.contributor-covenant.org/faq

Copyright (c) 2019 Michael Steil

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

##################################################################################################

#

# COMMANDER X16 EMULATOR MAKEFILE

#

##################################################################################################

ifeq ($(CROSS_COMPILE_WINDOWS),1)

	SDL2CONFIG?=$(WIN_SDL2)/bin/sdl2-config --prefix=$(WIN_SDL2)

else

	SDL2CONFIG=sdl2-config

endif

ifeq ($(CROSS_COMPILE_WINDOWS),1)

	TARGET_WIN32=yes

else ifeq ($(OS),Windows_NT)

	TARGET_WIN32=yes

endif

CFLAGS=-std=c11 -O3 -Wall -Werror -g $(shell $(SDL2CONFIG) --cflags) -Isrc/extern/include -Isrc/extern/retro-remote-debug-controller/core -pthread

CXXFLAGS=-std=c++17 -O3 -Wall -Werror -Isrc/extern/ymfm/src

LDFLAGS=$(shell $(SDL2CONFIG) --libs) -lm -lz -pthread

ifdef ADDL_INCLUDE

	CFLAGS+=-I$(ADDL_INCLUDE)

endif

X16_ODIR = build/x16emu

X16_SDIR = src

MAKECART_ODIR = build/makecart

MAKECART_SDIR = src

ifdef TRACE

	CFLAGS+=-D TRACE

endif

X16_OUTPUT=x16emu

MAKECART_OUTPUT=makecart

GIT_REV=$(shell git diff --quiet && /bin/echo -n $$(git rev-parse --short=8 HEAD || /bin/echo "00000000") || /bin/echo -n $$( /bin/echo -n $$(git rev-parse --short=7 HEAD || /bin/echo "0000000"); /bin/echo -n '+'))

CFLAGS+=-D GIT_REV='"$(GIT_REV)"'

ifeq ($(MAC_STATIC),1)

	LDFLAGS=$(LIBSDL_FILE) -lm -liconv -lz -Wl,-framework,CoreAudio -Wl,-framework,AudioToolbox -Wl,-framework,ForceFeedback -lobjc -Wl,-framework,CoreVideo -Wl,-framework,Cocoa -Wl,-framework,Carbon -Wl,-framework,IOKit -Wl,-weak_framework,QuartzCore -Wl,-weak_framework,Metal -Wl,-weak_framework,CoreHaptics -Wl,-weak_framework,GameController -pthread

	LDEMU=-ldl -Wl,-rpath,$(HOMEBREW_LIB)

else ifeq ($(CROSS_COMPILE_WINDOWS),1)

	LDFLAGS+=-L$(MINGW32)/lib

	# this enables printf() to show, but also forces a console window

	LDFLAGS+=-Wl,--subsystem,console

	LDFLAGS+=-static-libstdc++ -static-libgcc

ifeq ($(TARGET_CPU),x86)

	CC=i686-w64-mingw32-gcc

	CXX=i686-w64-mingw32-g++

else

	CC=x86_64-w64-mingw32-gcc

	CXX=x86_64-w64-mingw32-g++

endif

else # Not Mac, not Windows, probably Linux

	LDEMU=-ldl

endif

# build with link time optimization

ifndef NOLTO

	CFLAGS+=-flto

	LDFLAGS+=-flto

endif

ifdef TARGET_WIN32

	LDFLAGS+=-ldwmapi

endif

ifdef EMSCRIPTEN

	LDFLAGS+=--shell-file webassembly/x16emu-template.html --preload-file rom.bin -s TOTAL_MEMORY=32MB -s ASSERTIONS=1 -s DISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR=1

	# To the Javascript runtime exported functions

	LDFLAGS+=-s EXPORTED_FUNCTIONS='["_j2c_reset", "_j2c_paste", "_j2c_start_audio", _main]' -s EXPORTED_RUNTIME_METHODS='["ccall", "cwrap"]' -s USE_ZLIB=1 -s EXIT_RUNTIME=1

	CFLAGS+=-s USE_ZLIB=1

	X16_OUTPUT=x16emu.html

	MAKECART_OUTPUT=makecart.html

else

	LDFLAGS+=-pthread

endif

ifeq ($(FLUIDSYNTH),1)

	CFLAGS+=-DHAS_FLUIDSYNTH

endif

_X16_OBJS = cpu/fake6502.o memory.o disasm.o video.o i2c.o smc.o rtc.o via.o serial.o ieee.o vera_spi.o audio.o vera_pcm.o vera_psg.o sdcard.o main.o debugger.o javascript_interface.o joystick.o rendertext.o keyboard.o icon.o timing.o wav_recorder.o testbench.o files.o cartridge.o iso_8859_15.o ymglue.o midi.o netcard.o coverage.o

_X16_OBJS += extern/ymfm/src/ymfm_opm.o

# retro-remote-debug-controller: x16 backend + portable server core (submodule)

_X16_OBJS += control_backend.o extern/retro-remote-debug-controller/core/retro_control.o

ifdef TARGET_WIN32

	_X16_OBJS += video_win32.o

endif

X16_OBJS = $(patsubst %,$(X16_ODIR)/%,$(_X16_OBJS))

X16_DEPS := $(X16_OBJS:.o=.d)

_MAKECART_OBJS = makecart.o files.o cartridge.o makecart_javascript_interface.o

MAKECART_OBJS = $(patsubst %,$(X16_ODIR)/%,$(_MAKECART_OBJS))

MAKECART_DEPS := $(MAKECART_OBJS:.o=.d)

.PHONY: all clean wasm

all: x16emu makecart

x16emu: $(X16_OBJS)

	$(CXX) -o $(X16_OUTPUT) $(X16_OBJS) $(LDFLAGS) $(LDEMU)

$(X16_ODIR)/%.o: $(X16_SDIR)/%.c

	@mkdir -p $$(dirname $@)

	$(CC) $(CFLAGS) -c $< -MD -MT $@ -MF $(@:%o=%d) -o $@

$(X16_ODIR)/%.o: $(X16_SDIR)/%.cpp

	@mkdir -p $$(dirname $@)

	$(CXX) $(CXXFLAGS) -c $< -MD -MT $@ -MF $(@:%o=%d) -o $@

makecart: $(MAKECART_OBJS)

	$(CC) -o $(MAKECART_OUTPUT) $(MAKECART_OBJS) $(LDFLAGS)

$(MAKECART_ODIR)/%.o: $(MAKECART_SDIR)/%.c

	@mkdir -p $$(dirname $@)

	$(CC) $(CFLAGS) -c $< -MD -MT $@ -MF $(@:%o=%d) -o $@

cpu/tables.h cpu/mnemonics.h: cpu/buildtables.py cpu/6502.opcodes cpu/65c816.opcodes

	cd cpu && python buildtables.py

# Empty rules so that renames of header files do not trigger a failure to compile

$(X16_SDIR)/%.h:;

$(MAKECART_SDIR)/%.h:;

# WebAssembly/emscripten target

#

# See webassembly/WebAssembly.md

wasm:

	emmake make

clean:

	rm -rf $(X16_ODIR) $(MAKECART_ODIR) x16emu x16emu.exe x16emu.js x16emu.wasm x16emu.data x16emu.worker.js x16emu.html x16emu.html.mem makecart makecart.exe makecart.js makecart.wasm makecart.data makecart.worker.js makecart.html makecart.html.mem

ifeq ($(filter $(MAKECMDGOALS), clean),)

-include $(X16_DEPS)

-include $(MAKECART_DEPS)

endif

<p align="center">

  <img src="./.gh/logo.png" />

</p>

[![Build Status](https://github.com/x16community/x16-emulator/actions/workflows/build.yml/badge.svg)](https://github.com/x16community/x16-emulator/actions/workflows/build.yml)

[![Release](https://img.shields.io/github/v/release/x16community/x16-emulator)](https://github.com/x16community/x16-emulator/releases)

[![License: BSD-Clause](https://img.shields.io/github/license/x16community/x16-emulator)](./LICENSE)

[![Contributors](https://img.shields.io/github/contributors/x16community/x16-emulator.svg)](https://github.com/x16community/x16-emulator/graphs/contributors)

This is an emulator for the Commander X16 computer system. It only depends on SDL2 and should compile on all modern operating systems.

Features

--------

* CPU: 65C02 and 65C816 instruction sets, selected by command line switch

* VERA

	* Mostly cycle exact emulation

	* Supports almost all features:

		* composer

		* two layers

		* sprites

		* VSYNC, raster, sprite IRQ

* Sound

	* PCM

	* PSG

	* YM2151

* Real-Time-Clock

* NVRAM

* System Management Controller

* SD card: reading and writing (image file)

* VIA

	* ROM/RAM banking

	* keyboard

	* mouse

	* gamepads

Binaries & Compiling

--------------------

Binary releases for macOS, Windows and Linux are available on the [releases page][releases].

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

loaded from the directory containing the emulator binary, or you can use the `-rom .../path/to/rom.bin` option.

> __WARNING:__ Older versions of the ROM might not work in newer versions of the emulator, and vice versa.

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.

### macOS Build

Install SDL2 using `brew install sdl2`.

### Linux Build

The SDL2 development package is available as a distribution package with most major versions of Linux:

- Red Hat: `yum install SDL2-devel`

- Debian: `apt-get install libsdl2-dev`

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.

### WebAssembly Build

Steps for compiling WebAssembly/HTML5 can be found [here][webassembly].

### Windows Build

Currently macOS/Linux/MSYS2 is needed to build for Windows. Install mingw-w64 toolchain and mingw32 version of SDL.

Type the following command to build the source:

```

CROSS_COMPILE_WINDOWS=1 MINGW32=/usr/x86_64-w64-mingw32 WIN_SDL2=/usr/x86_64-w64-mingw32 make

```

Paths to those libraries can be changed to your installation directory if they aren't located there.

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.

Starting

--------

You can start `x16emu`/`x16emu.exe` either by double-clicking it, or from the command line. The latter allows you to specify additional arguments.

When starting `x16emu` without arguments, it will pick up the system ROM (`rom.bin`) from the executable's directory.

* `-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.

* `-bas <app.txt>` lets you specify a BASIC program in ASCII format that automatically typed in (and tokenized).

* `-run` executes the application specified through `-prg` or `-bas` using `RUN`.

* `-scale {1|2|3|4}` scales video output to an integer multiple of 640x480

* `-quality {nearest|linear|best}` change image scaling algorithm quality

    * `nearest`: nearest pixel sampling

    * `linear`: linear filtering

    * `best`: (default) anisotropic filtering

* `-widescreen` Stretch output to 16:9 resolution to mimic display of a widescreen monitor.

* `-fullscreen` Start up in fullscreen mode instead of in a window.

* `-opacity (0.0,...,1.0)` Set the opacity value (0.0 for transparent, 1.0 for opaque) of the window. (default: 1.0)

* `-rtc` causes the real-time-clock set to the system's time and date.

* `-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).

* `-rom <rom.bin>` Override KERNAL/BASIC/* ROM file.

* `-ram <ramsize>` specifies banked RAM size in KB (8, 16, 32, ..., 2048). The default is 512.

* `-cart <crtfile.crt>` loads a cartridge file. This requires a specially formatted cartridge file, as specified in the documentation.

* `-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.

* `-joy1`, `-joy2`, `-joy3`, `-joy4` enables binding a gamepad to that SNES controller port

* `-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.

* `-keymap` tells the KERNAL to switch to a specific keyboard layout. Use it without an argument to view the supported layouts.

* `-noemucmdkeys`  Disable emulator command keys. `Ctrl+M`/`⇧⌘M` will always be intercepted by the emulator.

* `-capture` starts the emulator with the mouse/keyboard captured

* `-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.

* `-sdcard` lets you specify an SD card image (partition table + FAT32) which will be presented as device 8 at boot.

* `-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.

* `-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.

* `-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.

* `-serial` makes accesses to the host filesystem go through the Serial Bus [experimental].

* `-nohostieee` or `-nohostfs` disables IEEE API interception to access the host fs. IEEE API HostFS is normally enabled unless `-sdcard` or `-serial` is specified.

* `-warp` causes the emulator to run as fast as possible, possibly faster than a real X16.

* `-pastewarp` causes the emulator to enter warp mode during pasting (`Ctrl+V` or `⌘V`) and during loading via `-bas`.

* `-gif <filename>[,wait]` to record the screen into a GIF. See below for more info.

* `-wav <filename>[{,wait|,auto}]` to record audio into a WAV. See below for more info.

* `-log` enables one or more types of logging (e.g. `-log KS`):

	* `K`: keyboard (key-up and key-down events)

	* `S`: speed (CPU load, frame misses)

	* `V`: video I/O reads and writes

* `-debug [<address>]` enables the debugger. Optionally, set a breakpoint

* `-dump` configure system dump (e.g. `-dump CB`):

	* `C`: CPU registers (7 B: A,X,Y,SP,STATUS,PC)

	* `R`: RAM (40 KiB)

	* `B`: Banked RAM (2 MiB)

	* `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)

* `-memorystats <filename.txt>` Saves memory read and write access statistics to the given file when emulator exits.

* `-testbench` Headless mode for unit testing with an external test runner

* `-sound <device>` can be used to specify the output sound device. If 'none', no audio is generated.

* `-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.

* `-via2` installs the second VIA chip expansion at $9F10.

* `-midline-effects` enables mid-scanline raster effects at the cost of vastly increased host CPU usage.

* `-mhz <integer>` sets the emulated CPU's speed. Range is from 1-40. This option is mainly for testing and benchmarking.

* `-enable-ym2151-irq` connects the YM2151's IRQ pin to the system's IRQ line with a modest increase in host CPU usage.

* `-wuninit` enables warnings on the console for reads of uninitialized memory.

* `-zeroram` fills RAM at startup with zeroes instead of the default of random data.

* `-version` prints additional version information of the emulator and ROM.

* `-c02` selects the 65C02 CPU (default).

* `-c816` selects the 65C816 CPU (experimental).

* `-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.

* `-longpwron` Simulate a long press of the power button at system power-on.

* When compiled with `#define TRACE`, `-trace` will enable an instruction trace on stdout.

Run `x16emu -h` to see all command line options.

Keyboard Layout

---------------

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:

|Name  |Description 	       |Differences|

|------|------------------------|-------|

|en-us |US		       |[`] ⇒ [←], [~] ⇒ [π], [\] ⇒ [£]|

|en-gb |United Kingdom	       |[`] ⇒ [←], [~] ⇒ [π]|

|de    |German		       |[§] ⇒ [£], [´] ⇒ [^], [^] ⇒ [←], [°] ⇒ [π]|

|nordic|Nordic                 |key left of [1] ⇒ [←],[π]|

|it    |Italian		       |[\] ⇒ [←], [|] ⇒ [π]|

|pl    |Polish (Programmers)   |[`] ⇒ [←], [~] ⇒ [π], [\] ⇒ [£]|

|hu    |Hungarian	       |[\] ⇒ [←], [|] ⇒ [π], [§] ⇒ [£]|

|es    |Spanish		       |[&vert;] ⇒ π, &#92; ⇒ [←], Alt + [<] ⇒ [£]|

|fr    |French		       |[²] ⇒ [←], [§] ⇒ [£]|

|de-ch |Swiss German	       |[^] ⇒ [←], [°] ⇒ [π]|

|fr-be |Belgian French	       |[²] ⇒ [←], [³] ⇒ [π]|

|fi    |Finnish		       |[§] ⇒ [←], [½] ⇒ [π]|

|pt-br |Portuguese (Brazil ABNT)|[\] ⇒ [←], [|] ⇒ [π]|

Keys that produce international characters (like [ä] or [ç]) will not produce any character.

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.

**Use the `MENU` command to select a layout, or set the keyboard layout at startup using the `-keymap` command line argument.**

The following keys can be used for controlling games:

|Keyboard Key  | SNES Equivalent |

|--------------|-----------------|

|X or Ctrl     | A               |

|Z or Alt      | B               |

|S 	           | X               |

|A 	           | Y               |

|D 	           | L               |

|C 	           | R               |

|Shift         | SELECT          |

|Enter         | START           |

|Cursor Up     | UP              |

|Cursor Down   | DOWN            |

|Cursor Left   | LEFT            |

|Cursor Right  | RIGHT           |

Options for the WebEmulator

--------

The following options are available for the WebEmulator. With the exception of manifest, they all work exactly the same as in the normal emulator.

* `manifest`

* `ram`

* `cpu`

* `mhz`

* `keymap`

* `longpwron`

* `widescreen`

* `capture`

* `midlineeffects`

#### The Address Line

`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`

On the Commander X16 forums, a link to the webemulator could look something like this:

https://cx16forum.org/webemu/x16emu.html?manifest=/forum/download/file.php?id=1218&ram=2048&cpu=c816&mhz=10&keymap=da&widescreen&capture  

This will load the forum file with id 1218 into the emulator.  

Give the emulator 2MB of RAM  

Set the CPU type to 65C816  

Set the CPU speed at 10 MHz  

Set the keyboard layout to Danish  

Show the emulator in widescreen mode  

Capture the mouse and keyboard input 

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.

#### The manifest.json File

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.  

Here is an example of the optional `manifest.json` file  

	{

		"manifest_version": "1.0.0",

		"name": "My Program",

		"author": "John Smith",

		"app_version": "1.0.0",

		"license": "GPL 3",

		"ram": "2048",

		"cpu": "c816",

		"mhz": "10",

		"keymap": "da",

		"widescreen": true,

		"capture": true,

		"longpwron": false,

		"midlineeffects": false,

		"start_prg": "MYPROG.PRG",

		"resources": [

			"MYPROG.PRG",

			"FILE1.BIN",

			"FILE2.BIN"

		]

	}

If the resources section is present, only files specified will be made available to the WebEmulator.  

Options set in `manifest.json` will override options on the address line.

Functions while running

-----------------------

#### Windows and Linux

* `Ctrl` + `F` and `Ctrl` + `Return` will toggle full screen mode.

* `Ctrl` + `M` will toggle mouse capture mode.

* `Ctrl` + `P` will write a screenshot in PNG format to disk.

* `Ctrl` + `R` will reset the computer.

* `Ctrl` + `Backspace` will send an NMI to the computer (like RESTORE key).

* `Ctrl` + `S` will save a system dump (configurable with `-dump`) to disk.

* `Ctrl` + `V` will paste the clipboard by injecting key presses.

* `Ctrl` + `=` and `Ctrl` + `+` will toggle warp mode.

#### Mac OS

* `⌘F` and `⌘Return` will toggle full screen mode.

* `⇧⌘M` will toggle mouse capture mode.

* `⌘P` will write a screenshot in PNG format to disk.

* `⌘R` will reset the computer.

* `⌘Delete` aka `⌘Backspace` will send an NMI to the computer (like RESTORE key).

* `⌘S` will save a system dump (configurable with `-dump`) to disk.

* `⌘V` will paste the clipboard by injecting key presses.

* `⌘=` and `⇧⌘+` will toggle warp mode.

GIF Recording

-------------

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.

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.

WAV Recording

-------------

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.

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.

Emulator I/O registers

-------------------

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.

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.

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.

| Register | Read Behavior | Write Behavior |

|-|-|-|

| \$9FB0 | Returns debugger enabled flag | `0` disables, `1` enables the debugger, overriding the absence or presence of the `-debug` command line argument. |

| \$9FB1 | Returns video logging flag | `0` disables, `1` enables logging of VRAM accesses to the console |

| \$9FB2 | Returns keyboard logging flag | `0` disables, `1` enables logging of keyboard events to the console |

| \$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. |

| \$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. |

| \$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. |

| \$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. |

| \$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. |

| \$9FB8 | Latches the cpu clock counter and returns bits 0-7 | Resets the cpu clock counter to 0 |

| \$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. |

| \$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. |

| \$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 �.

| \$9FBC | - | - |

| \$9FBD | Returns the keymap index, based on the argument to the `-keymap` command line option | - |

| \$9FBE | Returns the value `$31`/ASCII "1", useful for emulator presence detection | - |

| \$9FBF | Returns the value `$36`/ASCII "6", useful for emulator presence detection | - |

BASIC and the Screen Editor

---------------------------

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.

* To stop execution of a BASIC program, hit the `RUN/STOP` key (`Pause`), or `Ctrl+C`.

* To insert characters, first insert spaces by pressing `Shift+Backspace` or `Insert`, then type over those spaces.

* To clear the screen, press `Shift+Home`.

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

SD Card Images

--------------

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.

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.

On macOS, you can just double-click an image to mount it, or use the command line:

	# hdiutil attach sdcard.img

	/dev/disk2              FDisk_partition_scheme

	/dev/disk2s1            Windows_FAT_32                  /Volumes/X16 DISK

	# [do something with the filesystem]

	# hdiutil detach /dev/disk[n] # [n] = number of device as printed above

On Linux, you can use the command line:

	# sudo losetup -P /dev/loop21 disk.img

	# sudo mount /dev/loop21p1 /mnt # pick a location to mount it to, like /mnt

	# [do something with the filesystem]

	# sudo umount /mnt

	# sudo losetup -d /dev/loop21

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:

 * The file must be at least 32MB and must be fixed size. Expanding VHDs are not supported.

 * Use an MBR partition tables. The Commander X16 does not recognize GPT partition tables.

 * You must format the VHD with FAT32. Other file formats are not supported.

 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.

Host Filesystem Interface

-------------------------

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:

      DOS"$"

      LOAD"FOO.PRG"

      LOAD"IMAGE.PRG",8,1

      SAVE"BAR.PRG"

      OPEN2,8,2,"FOO,S,R"

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.

To avoid compatibility problems between the PETSCII and ASCII encodings, you can

* use uppercase filenames on the host side, and unshifted filenames on the X16 side.

* use `Ctrl+O` to switch to the X16 to ISO mode for ASCII compatibility.

* use `Ctrl+N` to switch to the upper/lower character set for a workaround.

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.

Dealing with BASIC Programs

---------------------------

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.

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

  1. Copy ASCII text from host basic file "PRG.BAS"

  2. Paste into new terminal session

  3. `SAVE"ENCODED.BAS`

  4. Now you can restart the emulator and load the encoded basic file with `LOAD"ENCODED.BAS"`

  5. Run with `RUN"ENCODED.BAS"`

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

Using the KERNAL/BASIC environment

----------------------------------

Please see the [KERNAL/BASIC documentation](https://github.com/X16Community/x16-docs/).

Debugger

--------

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

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.

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

- the high bytes of X and Y if the index flags is set

- the flags M (memory) and I (index) if emulation mode is active

- the high byte of SP if emulation mode is active.

The debugger uses its own command line with the following syntax:

|Statement|Description|

|---------|----------------------------------------------------------------------------------------------------|

|d %x|Change the code panel to view disassembly starting from the address %x.|

|m %x|Change the data panel to view memory starting from the address %x.|

|v %x|Display VERA RAM (VRAM) starting from address %x.|

|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!).|

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

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.

The debugger keys are similar to the Microsoft Debugger shortcut keys, and work as follows

| Key               | Description                                                                             |

|-------------------|-----------------------------------------------------------------------------------------|

| F1                | resets the disassembly position to the current PC                                       |

| F2                | resets the emulated CPU but not any of the hardware.                                    |

| F5                | close debugger window and return to Run mode, the emulator should run as normal.        |

| F9                | sets the breakpoint to the currently code position.                                     |

| F10               | steps 'over' routines - if the next instruction is JSR it will break on return.         |

| F11               | steps 'into' routines.                                                                  |

| F12               | is used to break back into the debugger. This does not happen if you do not have -debug |

| PAGE UP           | scrolls memory up by page.                                                              |

| PAGE DOWN         | scrolls memory down by page.                                                            |

| Shift + PAGE UP   | scrolls disassembly up by 16 bytes.                                                     |

| Shift + PAGE DOWN | scrolls disassembly down by 16 bytes.                                                   |

| UP                | scrolls memory up by row.                                                               |

| DOWN              | scrolls memory down by row.                                                             |

| Shift + UP        | scrolls disassembly up by one byte.                                                     |

| Shift + DOWN      | scrolls disassembly down by one byte.                                                   |

| TAB               | when stopped, or single stepping, hides the debug panel while pressed.                  |

When `-debug` is selected the STP instruction (opcode $DB) will break into the debugger automatically.

Keyboard routines only work when the emulator is running normally. Single stepping through keyboard code will not work at present.

CRT File Format

---------------

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.

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.

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.

### Header Layout

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.

| Location | Length | Description                                                                                        |

|----------|--------|----------------------------------------------------------------------------------------------------|

| 00-15    | 16     | ASCII text: CX16 CARTRIDGE\r\n                                                                     |

| 16-31    | 16     | CRT format version. ASCII digits in format 01.02, space padded.                                    |

| 32-63    | 32     | Name. ASCII text.                                                                                  |

| 64-95    | 32     | Programmer/Developer. ASCII text.                                                                  |

| 96-127   | 32     | Copyright information. ASCII text.                                                                 |

| 128-191  | 32     | Program version. ASCII text.                                                                       |

| 192-255  | 64     | Empty.                                                                                             |

| 256-287  | 32     | Fill with zeros.                                                                                   |

| 288-511  | 224    | Bank Flags.                                                                                        |

|          |        | 00: Not Present. No data is present in the emulator or in the file.                                |

|          |        | 01: ROM: 16KB of ROM data. Data is write protected in emulator.                                    |

|          |        | 02: RAM: No data in file. Bank is read/write in emulator.                                          |

|          |        | 03: RAM: Data present: data is loaded from the file and discarded on shutdown. Useful for testing. |

|          |        | 04: NVRAM: No Data in file. Memory is writeable. Emulator saves data to NVRAM file.                |

|          |        | 05: NVRAM: Data present. Memory is writeable. Emulator saves data to NVRAM file.                   |

| 512-end  |        | Payload data.                                                                                      |

|          |        | 16384 bytes per bank for types 1, 3, and 5.                                                        |

|          |        | 0 bytes for types 0,2, and 4.                                                                      |

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.

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

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.

### Vectors

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.

<!-- For PDF formatting -->

<div class="page-break"></div>

## MakeCart Conversion Tool

A conversion tool to pack cartridge data into a CRT file, `makecart`, is included in this release.

`-cfg <filename.cfg>`

Use this file to pack the cartridge data. Config file is simply the command line switches, one per line.

`-desc "Name/Description"`

Set the description field of the cartridge file. Up to 32 bytes of ASCII text.

`-author "Author Information"`

Set the author information field of the cartridge file. Up to 32 bytes of ASCII text.

`-copyright "Copyright Information"`

Set the copyright information field of the cartridge file. Up to 32 bytes of ASCII text.

`-version "version"`

Set the version information field of the cartridge file. Up to 32 bytes of ASCII text.

`-fill <value>`

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.

`-rom_file <start_bank> [<filename.bin> [<filename.bin>] ... ]`

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

Valid bank numbers are 32 - 255.

`-ram <start_bank> [<end bank>]`

Define one or more banks of RAM. RAM banks are not included in the payload.

`-ram_file <start_bank> [<filename.bin> [<filename.bin>] ... ]`

Define one or more banks of initialized RAM. Note that Initialized RAM banks are not saved to the NVRAM file at shutdown.

`-nvram <start_bank> [<end_bank>]`

Define one or more uninitalized nvram banks.

`-nvram_value <start_bank> <end_bank>`

Define pre-initialized nvram banks with the value set by '-fill'. Repeated payload bytes will be written to the file.

`-nvram_file <start_bank> [<filename.bin> [<filename.bin>] ... ]`

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

`-none <start_bank> [<end_bank>]`

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.

`-o <output.crt>`

Set the filename of the output cartridge file.

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.

`-unpack <input.crt> [<rom_size>]`

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.

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.

```

-o ladder.crt

-name "Ladder"

-author "Yahoo Software"

-copyright "(c) 1982, 1983 Yahoo Software"

-version "1.30TP"

-rom_file 32 ladder.bin

-rom_file 35 level_01.bin level_02.bin level_03.bin level_04.bin

-nvram 37

-fill 0

```

This would create file with

* 512 byte header

* 5 ROM banks

  * 3 for the 48K ladder.bin

  * 1 for the four 4KB level files.

* 1 empty NVRAM bank

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

Web Site

--------

[https://commanderx16.com](https://commanderx16.com)

Forum

-----

[https://cx16forum.com/forum](https://cx16forum.com/forum/)

License

-------

Copyright (c) 2019-2023 Michael Steil <[email protected]>, [www.pagetable.com](https://www.pagetable.com/), et al.

All rights reserved. License: 2-clause BSD

Release Notes

-------------

See [RELEASES](RELEASES.md#releases).

<!-------------------------------------------------------------------->

[releases]: https://github.com/X16Community/x16-emulator/releases

[webassembly]: http://github.com/X16Community/x16-emulator/blob/master/webassembly/WebAssembly.md

[x16rom-build]: https://github.com/X16Community/x16-rom#releases-and-building

[x16rom]: https://github.com/X16Community/x16-rom

<!-- For PDF formatting -->

<div class="page-break"></div>

<p align="center">

  <img src="./.gh/logo.png" />

</p>

## Releases

### Release R49 ("Pyrite")

* Features/Fixes

	* VERA: Add warnings when reading to write-only and when writing to read-only registers [irmen]

	* VERA: Make SPI busy time more true to hardware

	* VERA: Fix wrong behavior of 8bpp sprites when palette offset is nonzero

	* VERA PSG: Fix noise frequency being double that of hardware

	* SDCARD: add READ_MULTIPLE_BLOCK support [stople]

	* VIA: Fix for IFR flag handling [catharinejm]

	* Let emulator exit with Alt+F4 even if SDL does not handle it [JimmyDansbo]

	* Only free clipboard memory buffer when it comes from SDL's paste handler

	* Added serial MIDI emulation via FluidSynth

	* Exclude threading (needed for FluidSynth) in wasm build

	* Added `-gs` support, which implements a system with 24-bit addressable RAM and a 65C816 processor, in anticipation of the planned X16 GS with this feature. [Fulgen301]

	* Vastly improved performance of the HostFS's implementation of MACPTR

	* Added HostFS implementations of XMACPTR and XMCIOUT to mirror the CMDR-DOS implementations

	* 65C816 emulation fixes for MVN, MVP [Fulgen301, cnelson20]

	* Move from C99 to C11, some C syntax and header fixes [skeeto]

	* Additional web emulator options, including those to support CPU type and speed [JimmyDansbo]

	* Emulator debugger fixes, including support for GS, and pressing F9 a second time to clear the breakpoint

	* More changes in the [ROM](https://github.com/X16Community/x16-rom/tree/r49#release-49-pyrite).

### Release R48 ("Cadmium")

* Features/Fixes

	* Emulated VERA SPI clock has been updated to half of the VERA clock speed rather than the CPU clock.

	* Trace for ROM banks 13-15 (x16edit and Basload) is now supported [stefan-b-jakobsson]

	* Fixed debug reads from the stack and a few unbounded values in the debugger display

	* VERA PSG: for the saw and triangle waves, the inverse of the pulse width value is XORed with the value of the wave. This is the behavior of VERA 47.0.2 on hardware. [m00dawg]

	* Allow setting the amount of RAM in the web version of the emulator [JimmyDansbo]

	* Windows 11: Rounded corners should no longer cut off the lower left and lower right of the emulator window.

	* New memory statistics feature [irmen]

	* HostFS: Implement DOS "T"ell command

	* Debugger now includes elapsed cpu clocks since the last breakpoint or step

	* 65C816: Fixed stack relative indirect address calulation wrongly using the direct page [Fulgen301]

	* 65C816: high bytes of .X and .Y are now cleared when PLP or RTI set x=1 [cnelson20]

	* 65C816: PEI no longer does improper page wraparound, `[dp]` indirect modes now properly read the address. [Fulgen301]

	* More changes in the [ROM](https://github.com/X16Community/x16-rom/tree/r48#release-48-cadmium).

### Release 47 ("Roswell")

This is a major release with numerous bugfixes, as well as introducing 65C816 support.

* Features/Fixes.

	* Optionally emulate a 65C816 CPU, selectable via a new command line switch `-c816`. There is also a `-c02` command line switch to explicitly select 65C02 mode.  [Fulgen301]

	* In order to make room for the full 65C816 vector table, the R47 ROM relocates the "MIST" KERNAL signature from 0xFFF6 to 0xC008. Emulator has been updated to check for the signature in the newer location. [Fulgen301]

	* Made IEC device addressing more flexible by preventing the HostFS from consuming every device number [DragWx]

	* Improved timing calculations for HostFS operations to translate wall clock time to elapsed CPU ticks

	* If HostFS is in use, the default `-abufs` audio buffer count is 32, otherwise 8. This should reduce audio stuttering for games which load assets from disk while sound is playing.

	* HostFS can be changed to respond to a non-default device number. New command line option `-hostfsdev`. Using this option in conjunction with `-sdcard` allows both devices to appear on the system.

	* Matching the VERA hardware feature, the layer config T256 bit can be used as a palette switch in tile and bitmap modes. Most useful in 2bpp and 4bpp depths, setting this bit on the layer forces the resolved high bit of the palette entry index to 1. For instance, in 4bpp mode, a tile pixel with index 1, on a tile configured with palette offset 6 would normally resolve to palette entry 0x61 (or 97 decimal), having this layer bit set will cause this pixel to resolve to palette entry 0xE1 (or 225 decmial).

	* Copying VERA hardware behavior, the LINE IRQ can happen in the non-visible vertical blanking area.

	* HostFS: empty filename now returns an error as appropriate

	* IO2, the YM2151 range, is partially decoded on hardware. Emulator behavior now matches this so that the YM2151 is mirrored throughout the $9F42-$9F5F range.

	* New command line switch `-nokeyboardcapture` causes capture mode to operate without intercepting OS-level keystrokes such as Alt+Tab.

	* Improvements to `-wuninit` warnings to show the appropriate opcode and location of uninitialized accesses.

	* Recognize the INTL1 key code, which exists on some keyboard layouts such as pt-BR.

	* Update the 65C02 opcode table to properly handle multi-byte NOPs and update cycle counts.

	* `-trace` output has been updated and enhanced, showing banks for effective addresses. Add listings for new banks.

	* new `-longpwron` option to match SMC 47 long power button press behavior at power on.

	* VERA FX: fix address resolution bug with 4bpp unaligned cache filling.

	* VERA: DC_VSTOP was taking effect one scanline too late.

	* SMC: update activity light logic. Hardware was mistakenly documented as allowing 255 PWM intensity levels, while in fact it is binary on/off.

	* VERA PSG: update PSG volume table from VERA 47.0.0. Prior to this change, there were multiple PSG volume values at the low end that resulted in the same output level.

	* SDL2: Set the application name to "Commander X16 Emulator", which shows up in the audio mixer, and in the screensaver inhibit application list on Linux desktop environments. This should be a bit more informative than "My SDL application".

	* New `-pastewarp` command line switch that warps the emulator when receiving paste data either from the clipboard or from the `-bas` command line switch.

	* HostFS: improve path parsing with both CMD and unix path syntax, particularly with absolute path names.  DOS"MD//:TEST" now creates the directory in the FS root rather than erroneously in the current directory.

	* VERA: DC_HSCALE and DC_VSCALE values > 0x80 now render as they do on hardware.

	* SMC 47.0.0 fast PS/2 read support

	* Now with native build for Apple Silicon (built on the GitHub MacOS ARM runner)

	* More changes in the [ROM](https://github.com/X16Community/x16-rom/tree/r47#release-47-roswell).

### Release 46 ("Winnipeg")

This is mainly a bugfix release.

* Features/Fixes

	* A change in the ROM caused controllers to have their buttons offset due to how the emulated VIA responds to polling. The issue was fixed in the ROM and while it was not technically an emulator bug and no changes were made to the emulator's joystick routines, it gets a mention here.

	* HostFS: UNLSN was incorrectly setting the KERNAL status byte based on whether a file existed upon open. It has been changed to behave like CMDR-DOS. (discovered by [voidstar78])

	* HostFS: Opening a file in Modify mode now properly creates file if it doesn't yet exist (discovered by [m00dawg])

	* Audio: prevent `-sound none` from trying to use the uninitialized ymfm YM2151 library. The YM status register was also modified to always return 0 in this case. (discovered by [jestin])

	* WebAssembly: improve handling of zip files without `manifest.json` [Cyber-Ex]

	* GUI: If emulator launches in a window with the titlebar offscreen, move the window so that it is visible. (with help from [irmen])

	* GUI: Mouse movement now uses relative motion in capture mode, which makes the position of the host mouse irrelevant while in capture mode.

	* GUI: new `-capture` command line option to start emulator with mouse captured

	* Testbench: miscellaneous fixes [irmen]

	* More changes in the [ROM](https://github.com/X16Community/x16-rom/tree/r46#release-46-winnipeg).

### Release 45 ("Nuuk")

This is a minor release with respect to the emulator.  The bulk of the changes are in the [ROM](https://github.com/X16Community/x16-rom/tree/r45#release-45-nuuk).

* Features/Fixes

	* Revert VERA PSG amplitude resolution back to 6 bits. This was upped previously to match VERA firmware. It was subsequently reverted in VERA to make room for the FX feature. [akumanatt]

	* Intellimouse support added to the emulated SMC, partially implementing the new feature in hardware SMC firmware 45.1.0. [stefan-b-jakobsson]

		* Scroll wheel is supported (mouse device ID 3)

		* Not implemented: Extra buttons (mouse device ID 4)

	* New emulator debug register behaviors

		* Reading from \$9FB8-\$9FBB in this order returns the 32-bit CPU clock counter, snapshotted at the time \$9FB8 is read. Previously the clock counter would remain in motion and the upper counter bits could roll over unpredictably.

		* Writing to \$9FB8-\$9FBB has new behaviors:

			* \$9FB8: resets the cpu clock counter to 0.

			* \$9FB9: prints a debug message to the console `User debug 1: $xx`.

			* \$9FBA: prints a debug message to the console `User debug 2: $xx`.

			* \$9FBB: prints the UTF-8 representation of the ISO character to the console. This can be treated like a debug STDOUT.

		* Before using any of these emulator debug registers, it's recommended to test for emulator presence first.

			* Read from `$9FBE` and `$9FBF`. When running under the emulator, the returned values should be `$31` and `$36` respectively. If any other values are returned, you can usually assume to be running on real hardware. While the stock machine doesn't have any I/O devices that listen to the emulator I/O range, an add-on card could choose to use that same address space in the future for its own functions.

	* New MCIOUT (blockwise write) implementation for HostFS, mirroring the feature in the kernal for use on SD card.

	* New command key and capture behavior:

		* Ctrl+M/⇧⌘M is always processed by the emulator to toggle (mouse/keyboard) capture, regardless of the state of the "Disable Emulator Keys" flag.

		* Turning capture mode on disables all other emulator keys until capture mode is toggled off. While capture is on, the emulator also routes most OS shortcut key combos to the X16: for instance, Alt+Tab.

### Release 44 ("Milan")

This is the third release of x16-emulator by the X16Community team

* Features/Fixes

	* Many changes to HostFS, including

		* Fix regression for loading "`:*`" from HostFS while also using an SD card image

		* Fix `-prg` and `-sdcard` options working together, which did not properly handle the case after emulator reset

		* Proper wildcard behavior in dir filters and OPEN string

		* Fix filetype directory filter command parsing

		* Add `$=L` long mode directory listing to emulate the new feature in the ROM.

		* Speed up directory filetype filter

		* Add CMD/SD2IEC style directory navigation: `CD:←` to enter parent directory

		* Partial emulation of case-insensitivity in filenames on case-sensitive host filesystems.

			* This works in `OPEN` strings and directory names in commands (`CD:`, etc.) which do not contain a `/` character.

			* It also works on the last path segment in relative or absolute paths in directory names or `OPEN` strings. In other words, if given a path specification containing one or more `/` characters, it will do only a case-insensitive search on the part after the final `/`.

		* Proper translation between UTF-8 filenames and their ISO representations.

	* Implement VPB behavior to match hardware [akumanatt]

		* Fix BRK to have VPB behavior

	* Support for additional keycodes (NumLock, Menu) [stefan-b-jakobsson]

	* Fix debugger to set the correct bank for breakpoints [gaekwad]

	* New `-fullscreen` CLI option

	* Proper cleanup when the emulator exits when in full screen [irmen]

	* FX emulation, which mirrors the features in the FX enhancement to the VERA firmware. See the [VERA FX Reference](https://github.com/X16Community/x16-docs/blob/master/VERA%20FX%20Reference.md) for details.

	* Writing bit 6 and bit 7 together into VERA_AUDIO_CTRL now enables looping the PCM FIFO (and does not reset the FIFO). Any other write into VERA_AUDIO_CTRL disables looping.

	* New `-opacity` CLI option for window transparency [tstibor]

	* New support for screenshots (Ctrl+P/⌘P) [dressupgeekout]

	* Fix small memory leak caused by pasting into the emulator

	* Use relative mouse motion while in grabbed mode

	* Remove `-geos` CLI option [dressupgeekout]

	* New YM2151 audio core: remove old MAME core, replace with ymfm

		* Allows for IRQs from the YM, requires specifying `-enable-ym2151-irq` on the command line

	* Emulate hardware open bus behavior when reading from a device that doesn't exist in the `$9Fxx` space

	* Reset via I2C command: defer machine reset to the main loop, which allows the I2C write routine to return cleanly.

	* Fix 65C02 `BIT` immediate behavior [XarkLabs]

	* New NMI trigger emulator hotkey, emulates Ctrl+Alt+Restore on hardware (Ctrl+Backspace/⌘Delete) [XarkLabs]

	* Fix line artifact in application icon/logo

	* Grabbing the mouse with (Ctrl+M/⇧⌘M) now grabs the keyboard as well. It allows the emulator to receive keystrokes and key combinations which would otherwise be intercepted by the operating system.

	* Fix description of fill value in `makecart`

	* New features implemented in the [ROM](https://github.com/X16Community/x16-rom/tree/r44#release-44-milan)

* Build

	* Link-time optimization is now enabled by default

	* Portability enhancements [dressupgeekout]

	* Suppress clang warnings due to deprecated sprintf usage in ymfm lib [XarkLabs]

### Release 43 ("Stockholm")

This is the second release of x16-emulator by the X16Community team

* **BREAKING CHANGE**

	* The keyboard protocol between the emulated SMC and the KERNAL has changed, thus x16-emulator version R43 requires x16-rom version R43.

	* This change also affects how the custom keyboard handler vector works (keyhdl). For details, see [Chapter 2 of the Programmer's Reference Guide](https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2002%20-%20Editor.md#custom-keyboard-keynum-code-handler)

	* **Your Keyboard will not work unless** you are running

		* R43 of both x16-rom and x16-emulator

* Features

	* Updates to support translation from SDL scancodes to new keynum encoding supported by KERNAL [stefan-b-jakobsson]

	* More granular support for RAM amount as argument to `-ram`

	* Minor HostFS bugfixes and enhancements, including tying the activity light to HostFS activity.

	* VERA updates: new support for 240p in NTSC/RGB modes. Chroma disable only works on NTSC.

	* Stepping the debugger now supports stepping over `WAI`

	* Debugger now shows the correct bank in the disassembly by default. [gaekwad]

	* Debugger breakpoints are now bank-specific [gaekwad]

	* Randomized RAM is now the default. New option: `-zeroram` [irmen]

	* Host's mouse cursor is now shown unless either the KERNAL mouse is enabled or the mouse cursor is captured (Ctrl+M/⇧⌘M).

	* Esc key is now Esc rather than STOP.  Pause key sends STOP.  (Ctrl+C is also recognized by the KERNAL as STOP)

	* SD card emulation now responds to CMD9

	* Emulated SMC can now assert NMI.

	* Add `-mhz` option to select a speed other than 8

	* When built with `TRACE`, the `-trace` output now shows the effective address for indirect and indexed opcodes and VERA data0/data1 reads and writes.

	* New comamnd line option `-midline-effects` that supports mid-line changes to the palette or tile/sprite data. R42 always had this behavior, which results in performance degradation for programs write to VERA heavily if the host CPU is not fast enough. This behavior is now disabled by default. `-midline-effects` restores this optional behavior.

	* New features implemented in the [ROM](https://github.com/X16Community/x16-rom/tree/r43#release-43-stockholm)

* Other

	* Release builds have link-time optimization enabled which seems to help performance.

	* Add git hash of build to `-version` string.

	* WebAssembly enhancements in the supporting html/js [Cyber-EX]

	* Fixed potential off-by one row with non-zero DC_VSTART.

	* Prevent laggy hostfs reads from causing the emulator to warp to catch up by translating the wall clock time to elapsed 6502 clocks. This effectively makes HostFS MACPTR behave like a DMA card, including the possibility that it prevents the CPU from executing instructions while interrupt sources may have been waiting for service.

	* Bugfix: Process multiple SDL events per frame. (Fixed choppy mouse movement if there were keystrokes in the keyboard buffer)

	* Audio resampling and ring buffer fixes [DragWx]

	* Build fixes on Mac

### Release 42 ("Cambridge")

This is the first release of x16-emulator by the X16Community team

* Features

	* Added testbench mode [stefan-b-jakobsson, indigodarkwolf]

	* Added `-noemucmdkeys` option [jestin]

	* New `FIFO_EMPTY` flag in `PCM_CTRL` to reflect new VERA feature [ZeroByteOrg]

	* Added `-widescreen` option to simulate stretched 640x480 output at a 16:9 aspect ratio [jestin]

	* New `SCANLINE` VERA register behavior to reflect updated VERA feature [mooinglemur]

	* Added `-randram` and `-wuninit` command line arguments to randomize RAM at boot, and to emit a console warning when uninitialized RAM is read, respectively. [stefan-b-jakobsson]

	* Allow specifying non-power-of-2 argument to `-ram`, in increments of 8k [JimmyDansbo]

	* Added `-via2` option to selectively enable a VIA at $9F10. [akumanatt]

	* Added ROM cart loading with `-cart` and `-cartbin` [indigodarkwolf]

	* New `makecart` utility for building `.crt` cartridge files [indigodarkwolf]

	* Compressed SD card image support [indigodarkwolf]

	* Mouse grab mode, press Ctrl+M (Mac: ⇧⌘M) to toggle. [mooinglemur]

	* New `-fsroot` and `-startin` options to specify the root of the emulated host fs, and the host directory to start in respectively. [mooinglemur]

	* Many, many new features implemented in the [ROM](https://github.com/X16Community/x16-rom/tree/r42#release-42-cambridge)

* Other

	* PS/2 devices now connected via SMC via I2C, I2C pins have moved to match hardware [stefan-b-jakobsson]

	* Recognize middle mouse button [ZeroByteOrg]

	* Synchronized keymaps with ROM [megagrump]

	* Build fixes [irmen]

	* Show dialog when a `STP` instruction is encountered with debug turned off [akumanatt]

	* Improved emulated behavior of `WAI` [LRFLEW]

	* Clear D flag on interrupt entry [LRFLEW]

	* Update BRK length in debugger [indigodarkwolf]

	* IRQ/NMI entry clock cycles are now accounted for [mooinglemur]

	* Add reason string to memory dump output [irmen]

	* Clear sprite line buffer when disabling sprite layer [jestin]

	* Improved audio balance between VERA and YM2151. Much improved mixing routines to reduce stutters and clicking. [akumanatt]

	* To match hardware, VERA ISR bits are set at VSYNC, LINE, and SPRCOL regardless of whether their respective IEN bits are set [mooinglemur]

	* Changes to match Proto 4, including moving VIA1 interrupt pin to IRQ [akumanatt]

	* VERA mid-frame raster effects more closely match the timing of real hardware [mooinglemur]

	* Enabled and built out CI/CD build workflows [maxgerhardt, indigodarkwolf, mooinglemur]

	* Many host fs enhancements, bringing host fs very close to feature parity with SD card images [davidgiven, ZeroByteOrg, mooinglemur]

	* Many documentation updates and fixes [veganaize, irmen, tomxp411]

### Release 41 ("Marrakech")

* allow apps to intercept Cmd/Win, Menu and Caps-Lock keys

* fixed `-prg` with `-sdcard`

* fixed loading from host filesystem (length reporting by `MACPTR` on EOI)

* macOS: support for older versions like Catalina (10.15)

### Release 40 ("Bonn")

* Features

	* improved VERA video timings [Natt Akuma]

	* added Host FS bridging using IEEE API

	* added Serial Bus emulation [experimental]

	* added WAV file recording [Stephen Horn]

	* possible to disable Ctrl/Cmd key interception ($9FB7) [mooinglemur] 

* Other

	* Fixed I2C (RTC, SMC)

	* Fixed RAM/ROM bank for PC when entering break [mjallison42]

	* LST support for -trace

## Release 39 ("Buenos Aires")

* Switch to Proto2 Hardware

	* banking through zp addresses 0 and 1

	* modified I/O layout

	* modified VIA GPIO layout

	* support for 4 controllers

	* I2C bus with SMC and RTC/NVRAM

* Features

	* implemented VIA timers [Natt Akuma]

	* added option to disable sound [Jimmy Dansbo]

	* added support for Delete, Insert, End, PgUp and PgDn keys [Stefan B Jakobsson]

	* debugger scroll up & down description [Matas Lesinskas]

	* added anti-aliasing to VERA PSG waveforms [TaleTN]

* Bugs

	* fixed sending only one mouse update per frame [Elektron72]

	* fixed VSYNC timing [Elektron72]

	* switched front and back porches [Elektron72]

	* fixed LOAD/SAVE hypercall so debugger doesn't break [Stephen Horn]

	* fixed YM2151 frequency from 4MHz ->3.579545MHz [Stephen Horn]

	* do not set compositor bypass hint for SDL Window [Stephen Horn]

	* reset timing after exiting debugger [Elektron72]

	* don't write nvram after every frame

	* fixed write outside of line buffer [Stephen Horn]

	* fixed BRA extra CPU cycle [LRFLEW]

	* fix: clear layer line once layer is disabled

	* fixed BBSx/BBRx timing [Natt Akuma]

* Other

	* misc speed optimizations [Stephen Horn]

## Release 38 ("Kyoto")

* CPU

	* added WAI, BBS, BBR, SMB, and RMB instructions [Stephen Horn]

* VERA

	* VERA speed optimizations [Stephen Horn]

	* fixed raster line interrupt [Stephen Horn]

	* added sprite collision interrupt [Stephen Horn]

	* fixed sprite wrapping [Stephen Horn]

	* added VERA dump, fill commands to debugger [Stephen Horn]

	* fixed VRAM memory dump [Stephen Horn]

* SD card

	* SD card write support

	* Ctrl+D/Cmd+D detaches/attaches SD card (for debugging)