Planet Virtual Boy

This is a work post.

Truth be told, I started working on this project about a week before the 3DS thing came up. The two ideas merged together to form into what we have today. What this means for us is that we're not starting from square one--we've already got some progress to go off of.

In this post, we'll take a look at the current state of the project as of the start of the initiative.


Where We're At

Attached to this post is a ZIP file containing a JAR file containing the source code of the current build of the emulator. And the JAR file itself is the current build of the emulator. If you have a Java Runtime Environment installed (Linux users will want OpenJDK), you can try it out! If you don't have a Java Runtime Environment installed and have interest in this project, you might consider installing it. The desktop application will only be available on the Java platform.

When you load it up, you'll have an empty window with a File menu, which you can use to load a Virtual Boy ROM. Once you select something, you'll be presented with a Debugger window and a Memory window. The Debugger is the main attraction today, but if you want to navigate around the Memory window you can use Ctrl+G to go to any address you please.

The Debugger window looks like this:




On the left is the disassembler, and on the right are the registers. You can navigate around the disassembler with the arrow keys, Page Up/Page Down and the mouse wheel, or use Ctrl+G to go to a specific address.

Program execution is managed with the following keys:
• F11 - Single Step (aka Step Into). Executes the current instruction.
• F10 - Step Over. Attempts to execute until the following instruction is reached, which works as a traditional Step Over but is also useful for breaking out of the warm-up loop at the beginning of the crt0 routine. If one frame's worth of CPU cycles is processed without reaching the target instruction, it will stop in order to prevent running endlessly.

The top panel of registers is for system registers, and the bottom panel is for program registers (aka general registers). All those numbers are in fact text boxes, allowing the user to change their values directly (no pop-up window). I couldn't think of a cleaner way to present the 46 registers on the CPU, but if anyone has a better idea, now's a great time to try something out.

See those + signs next to several of the registers in the image? You can click on those to "expand" the corresponding register for more options:




For system registers, this gives controls for configuring the individual bit-packed fields within the 32-bit value. PSW is demonstrated here, where there are check boxes for all of the flags and a text field for "I", the interrupt masking level.

All program registers can be displayed with one of four presentation formats, depending on what you're debugging. "Signed" and "Unsigned" are decimal representations.

Most instructions are implemented, but not bit string or floating-point instructions, since they will be miniature projects in and of themselves. There are also no implementations for hardware components, meaning interrupts will never occur. This means most games will eventually enter an endless loop waiting for a global variable to be changed that will never change.


Technical Stuff

Why Java? Because it's available on most operating systems and the geniuses who maintain it have done all of the heavy lifting for things like localization, networking, GUI stuff, etc. I've been around the block two or three times looking for solutions to the cross-platform problem and Java is the best one I've come across.

Naturally, Java isn't going to be the language used in the 3DS build, so how pray tell will this work? The answer isn't ideal, but it gets the job done: there will be two implementations of the emulation core. One in Java, and the other in C.

The emulation core is a module that handles only the bare minimum necessary to manage a simulated Virtual Boy. It's pure program code: it relies on the encapsulating application for things like timing, user input and presenting output. A C core will be used by the 3DS build, and the Java application will use... well, that's where it gets interesting.

At the heart of the Java application is a class that represents the emulation core. It's currently an abstract class, but I'm thinking of turning it into an interface... In either case, it doesn't contain any actual program code of its own, but acts as a sort of stand-in template for other classes to implement. It looks like a duck and quacks like a duck, but it's just the hollow shell of a duck.

Classes that implement the methods of this core interface are the meat of the internal engine. Currently I've set up a class that provides a generic Java implementation of the emulation core. In the future, at least one more implementation will be provided that makes use of the C version of the emulation core, which will offer improved efficiency and performance.

Java can use C code through the Java Native Interface (JNI), which loads shared object/DLL files at runtime. The drawback is that we need to produce those library files for every single operating system that we want native support for. Fortunately, those systems that don't receive native libraries will be able to fall back on the Java implementation instead, and everything will still work just fine.

When it's all said and done, the C emulation core module itself will be one of the products of the initiative. Other development teams the world over will be able to use it to easily integrate Virtual Boy emulation into their projects.

This is a work post.

Let's take a look at what needs to get done going forward.


Project Outline

Development in the initiative is broken up into four main sections with the following hierarchy:

┌ Emulation core
│ ├ 3DS software
│ └ Desktop application
└ Technical documentation

The emulation core needs to be done before either the 3DS or Java applications can exist. The technical documentation can be maintained alongside development regardless of what's being worked on.

In previous iterations of the project, I found that starting development in C is an uphill climb. It's much easier to do rapid prototyping and debugging in Java, which is a highly substantial benefit for productivity. The Debugger and Memory windows in the Java application already give me a CPU's-eye view of what's going on so I can verify it's working correctly. Additionally, due to C's flexibility, it's likewise easier to make a C analog of something written in Java than the other way around.

The order of operations, then, becomes only slightly more involved:

┌ Java emulation core
│ ├ C emulation core
│ │ ├ 3DS software
│ │ └ Desktop native modules
│ └ Desktop application
└ Technical documentation

In terms of priority:

1) Technical documentation
2) Java emulation core
3) C emulation core
4) 3DS software, Desktop application
5) Desktop native modules

This is the guide I will be using as I work on things, so now there's a plan of action. I'll make an effort to develop the 3DS software and desktop application fairly, since I feel both target audiences are equally important. The desktop native modules are not necessary for the desktop application to function, so their development is not urgent.


To Do - Week of April 16, 2018

• Establish the groundwork for "VB Sacred Tech Scroll v1.0" and begin migrating content.

While I do already have a draft of v1.0 in the works, it's still based on the Nocash-style formatting and lately I'm thinking improved usability is more important than a cheeky homage.

Specifically, I want to incorporate content as it is implemented into the emulation core. Since right now the emulation core only consists of the CPU, the initial state of the new document will likewise only consist of the CPU. As additional components are incorporated into the emulation core, they will be cross-checked against the hardware and added to the document.

Critically, nothing will be implemented in the emulation core without first being verified on the hardware and documented. We're gonna do this the right way.

• Produce "CPU Workshop" Virtual Boy software for verifying CPU functionality.

This will be a simple program that can be used to test individual instructions. A before-and-after snapshot of all registers will be recorded when testing instructions. Certain instructions cannot be tested this way (HALT, RETI, etc.), but most can.

The remaining CPU functionality will need special-purpose routines, and hopefully I can get it all sorted out in this one program.

Just donated on Patreon. I've wanted an emulator on the 3DS since I got it. Why Nintendo hasn't released a VC title on the 3DS baffles me, but if this gets the ROMs running smoothly, I'll install immediately! Good luck!

I really, REALLY hope this moves foward. If Nintendo will not rerelease the VB titles, We will by any shape or form :)

Pledged on Day 1... think I was #3 :) Good luck! Can't wait to see how this comes along!

Another round of shout-outs to all supporters. You're gonna make this all worthwhile. (-:

This is a work post.

Attached to this post is a preliminary CPU Workshop ROM that has been tested on the hardware. It provides binary-level control over the instructions being tested and accounts for most scenarios regarding CPU behavior. A few things to keep in mind:

• Instructions that disrupt program flow will be ignored when attempting to test them. These include JAL, JMP, JR, RETI, SEI and any form of Bcond that isn't NOP.
• Despite the above precaution, LDSR into PSW can still crash the program, so be careful with it.
• Exceptions are handled, so testing things like division by zero, invalid opcodes or the TRAP instruction work just fine.

The program is arranged with a sort of tab strip at the top, with four distinct views. Use the L and R buttons to switch between them.


Instruction

The primary dialog that allows you to configure an instruction to test. When the Test command is invoked, the instruction will be tested in the context of a function call with the following arguments:
• r6 = Specified by user
• r7 = Specified by user
• r9 = 32 bytes of scratch memory available to the user

The values of r6 and r7, as well as the bits of the instruction to test, can be configured. The left D-Pad moves the cursor to select individual digits, then Up and Down on the right D-Pad will change the digit.

Moving the cursor down below the "Bits" field will select the Test command. Press the A button to perform a test, but bear in mind that the test is performed in the background and you will not see any effects until you look at the other menus.

A disassembly is provided as a courtesy to help make sure the instruction that's going to be tested aligns with the instruction you intend to test. The program requires you to have a good working knowledge of V810 instruction formats. For more information, refer to the Sacred Tech Scroll's list of instructions by mnemonic.

The left 16 digits of the Bits field are used for 16-bit instructions, and all 32 are used in order for 32-bit instructions. If a 16-bit instruction is specified, the second 16 bits are ignored during the test, so you don't need to configure them.


System, Program

Displays two snapshots of system registers and program registers, respectively. These views are for display only and have no functionality.

For each register, there are two values shown: the top one is the register's value before the test, and the bottom one is the register's value after the test.

All system register indexes from 0 to 31 are displayed. This seems unnecessary at first, but it was discovered that system registers 29, 30 and 31 do in fact exist.


Misc.

Displays additional information regarding the test.

The bit-packed fields in system register PSW are decoded for easier assessment of the status flags.

There are 32 bytes of scratch memory available for testing read/write instructions with, pointed to by r9. The "before" and "after" states of these bytes are displayed here.

I find this tool a lot like VSU Workshop! This will answer questions regarding not only the sound functionality, but also the CPU.

Now do VIP Workshop.

Yay, the site's back. I have one more section to prepare in the first batch of content for the new tech scroll document, and I'll have that ready for presentation sometime tomorrow.

Quote:
I can't promise this one's gonna happen. The VIP has enough moving parts that I expect it's more likely to make test programs for individual features rather than one giant program encompassing everything.

This is a work post.


We have results!

You may recall that I mentioned having a draft of v1.0 of the Sacred Tech Scroll in the works, but I discarded it and started a brand-new document instead. And that new document is already 8000 words long! I intended to have it in its current state yesterday, but the new content and formatting took a bit longer than I expected.

The current, work-in-progress draft of the new Tech Scroll can be found here:
http://perfectkiosk.net/stsvb1.html

It currently contains most of the CPU documentation. A few editor's notes are strewn here and there for things that need additional research, and the instruction cache isn't documented at all. But otherwise, I believe the rest is in there. There aren't very many blanks left to fill in: CPU Workshop was an invaluable tool for getting lots of tricky things figured out.

Quite a bit has changed from the original Sacred Tech Scroll document, not the least of which involves innumerable corrections. I encourage you to take a look and let me know what you think.

This is enough to get started designing and implementing a formal emulation core. I realize a big wordy document isn't as fun as a flashy emulator, but I trust you can appreciate just how much of a benefit it is to have this available.