Box16

[StephenHorn]

Box16

Last stable release: nr41.1 (Koutoubia Mosque), use with the r41 ROM.
   Current CI build: nr42.xx (Akhet),           use with the latest (post-r43, pre-r44) ROM.

(You may need to be signed into GitHub to access the current CI build.)

basic-prompt_2.png (10.4 KiB) Viewed 8751 times

Box16 is an emulator for the Commander X16, focused on providing debugging and inspection tools to help a programmer understand the state of the system and debug their programs. The latest "stable" release of Box16 is nr41.1 (link), available for download on GitHub. It works with the rom.bin provided by the official Commander X16 r41 emulator. Box16 is also in continuing development, and the latest continuous-integration builds usually work with the latest similar builds from commanderx16/x16-rom (link) on GitHub.

debugging-symbols-and-watch_1.png (86.44 KiB) Viewed 8751 times

The CPU monitor includes a "smart stack" which shows the callstack of jsr targets and interrupts, complete with symbol names if the appropriate files have been loaded. Hovering over items in the smart stack and show additional information, such as the address that the program counter was at when it entered that stack context. Clicking on smart stack elements will set the disassembler to the address that was jumped into. Any number of breakpoints and memory watches can be set, with breakpoints applying to execution, memory reads, or memory writes.

memory-dumps_1.png (135.4 KiB) Viewed 8751 times

There are memory dump views, as well, that can change between different banks in RAM and ROM. Clicking on symbols or addresses in the disassembler can focus a memory dump window to that location automatically, or will set the disassembler to the location in the case of branch and jump instructions.

[StephenHorn]

vera-debugging_1.png (122.47 KiB) Viewed 8749 times

There are also a variety of displays for displaying the status of the VERA components, including a VRAM dump, as well as layer and sprite displays.

vera-palette-and-tiles_1.png (65.44 KiB) Viewed 8749 times

Palette and tile display are also present. The palette display allows you to edit palette entries in real-time, even when the CPU is paused. If your program adjusts the palette mid-frame, however, this may result in artifacts as the debugging tools here aren't sophisticated enough to differentiate between palette entries prior to any particular point on the display.

psg-and-ym2151_1.png (250.55 KiB) Viewed 8749 times

Extensive displays for PSG and YM2151 state are also present.

cpu-visualization_1.png (310.36 KiB) Viewed 8749 times

While it's as much a toy as a tool, there is also a CPU visualization display that shows program execution timing relative to the VERA's video frame processing, and the highlight function can emphasize a few different contexts of execution, such as H-blank and V-blank periods where it's safest to perform video operations. When colored by CPU operation, the colors are based on Michael Steil's instruction grouping and colors at https://www.pagetable.com/c64ref/6502/?cpu=65c02s&tab=2.

cpu-visualization-2_1.png (316.17 KiB) Viewed 8749 times

I don't currently have a way of easily lining up and/or overlaying the VERA display with the CPU visualization, but this still can give a programmer a sense of when their program is executing relative to the video frame and what it is doing.

[StephenHorn]

controllers_2.png (18.41 KiB) Viewed 8748 times

A couple of additional tidbits:

• If the operating system recognizes any controllers, Box16 will automatically detect them and attempt to bind them to SNES controller ports for the X16, including binding new controllers that appear after Box16 has been started. These can be freely re-bound via the menu option.
• SD cards can also be freely attached and detached via the menu, though at present Box16 does not attempt to automatically discover SD card images on the host filesystem, so folks have to find/open them with a popup for now.

options_1.png (36.97 KiB) Viewed 8748 times

There are an extensive number of options to configure Box16's behavior, covering almost the entire set of command-line options. These can be saved to an ini file in the user's profile directory so that commonly used command-line options will not need to be specified each time Box16 is started.

For many of the debug displays, Box16 will also remember whether or not they were open at the time Box16 was closed. Unfortunately, Box16 does not, at this time, remember loaded symbols, breakpoints, or watch points, but that is "on the radar".

As the maintainer of Box16, I whole-heartedly welcome code contributions and pull requests on GitHub. If you're a developer and there's a feature you think is missing and would like to contribute, please don't hesitate to create your own fork on GitHub.

Feel free to post questions and I will answer when I am able. I am also frequently reachable on the semi-official (unofficial?) Commander X16 Discord server. Bugs and feature requests can be submitted to my GitHub repository (link) -- that's the easiest way to ensure that something is not completely forgotten. But please be patient, I am only one human and this is my hobby.

[StephenHorn]

[reserved for future updates]

[Johan Kårlin]

I think the debugging features are just great and I would really like to use this. But my laptop is not powerful enough. The emulator runs at 50% of normal speed. The official emulator runs at 100%. I have a Dell Latitude 5300 with Intel(R) Core i5-8265U CPU. Can you say anything about minimum requirements?

[StephenHorn]

 
TL;DR: Best guess minimum recommended specs: 3.0GHz cpu
 

Regrettably, I don't have the spectrum of hardware necessary to be able to really pinpoint minimum system requirements at the moment. I can only say with certainty that the following computers I own can run Box16 at 100% speed when no debugging windows are open:

• Intel Core i7-9700K @ 3.60GHz / 3.60GHz, with slightly-overclocked RAM (a custom build PC, circa 2019, Windows 10).
• Intel Core i7-1185G7 @ 3.00GHz / 1.80GHz (a Dell Latitude 5520 laptop, circa 2023, Windows 11)
• (Same machine as above, but running Debian 11 through WSL)
• Intel Core i5-3570 @ 3.4GHz (a custom build PC, circa 2013, Debian 11)

Opening the CPU Monitor, Disassembler, and VERA Monitor windows slowed these system down to 100%, 100%, 95%, and 75%, respectively.

The laptop could be brought down to 80% in each Box16 window if I ran Box16 with those windows open using both the native Windows binary and the Linux binary, running simultaneously.

My Raspberry Pi 4 (ARM Cortex-A72 @ 1.50GHz / 600MHz), through a VNC display with no windows open, runs Box16 at 40%-45%; with the aforementioned windows open it slows to 35%-40%.

As for other high-level information about the hardware, the two PCs were built for gaming and are filled with then-contemporary high-performance components to maximize the machines' abilities. The laptop was chosen mostly because I was able to get it at a figurative steal for a price and I needed a replacement laptop to drag along with me for low-impact development and creative writing. I would need to dust off my previous gaming laptop before I could use it as a point for comparison. Still, I would venture to guess that means Box16 really wants something on the order of a 3.0GHz cpu. As ever, I say we ought to blame the VERA for being expensive to emulate in software. But I haven't profiled Box16 in a while, perhaps something is eating away the performance somewhere else.

As far as prioritizing optimization, I have several major submissions in the works related to gz and zip file support, VICE monitor commands, and coming back up to parity with the official emulator's CBM DOS emulation on the host filesystem. My initial inclination is that once those are done, I'll have time to do some profiling on Box16 again to tackle performance problems.

[Johan Kårlin]

Thanks for your detailed answer. It sounds reasonable with 3.0 Ghz. My laptop is running at 1.60 GHz. Maybe this is the reason i need to finally buy a new one …

[desertfish]

i5-8265U CPU is a 15 watt cpu, which is extremely constrained (ultrabook form factor).

If you're considering a new laptop may I suggest looking into at least a ~30 watt class cpu (-P letter suffix for Intel parts) if you can afford it.
And a -H one is even more watts but faster still. Might be worth diving into some productivity benchmarks.

I don't know what the AMD equivalents are for laptops but they have these kinds of power brackets as well.