This PR implements masking and behavior tests for the following COP0 registers:

• Random
• Wired
• Status
• Config
• Processor Revision Id
• Unused (7, 21, 22, 23, 24, 25, and 31)
• Parity Error
• Cache Error

I've included rustdocs for each test to explain any finer details of what behavior is being tested. Below are some extra notes regarding the design of this PR.

Random

While it is possible to test only the masking by naively checking if Random is some value less than 64, this could produce a false-positive case. An emulator could allow writes to the lower 6 bits, but this is incorrect as the entire register is read-only. You also can't perform a simple "read, write, read, compare equality" test because the value is supposed to change on every instruction.

I'm planning to try to address this later in a different PR, to have different levels of scrutiny (not every emulator cares about being extremely accurate).

Also note, despite the name, Random is definitely not random in any way.

Status and Config

These regs, especially Config, have some constant 0 and 1 bits. So the test writes the existing value combined with whatever the opposite of these constant bits are. Then checks if the readback has these constant bits. Just writing all 1's or all 0's (like other masking tests) could produce false-negatives.

Processor Revision Id

I provided a test to the homebrew community that prints out their system's PRId register. All tested systems, including one PAL, produced 0xB22. It's safe to assume, until and exception is found, that this is likely what all n64 consoles will provide.

Unused

The COP0 has several "unused" registers which aren't completely unusable. Writes to any of these registers, won't actually store anything, but the written value is held in some kind of internal "latch", and can be read back at a later time. Only writes to any COP0 register appears to change the "latched" value. Other instructions that store data to regular GPR's do not affect it.

Also, all unused registers are effectively interchangeable. Writing some value to Unused7, will match the readback from Unused31, etc. Writes to any used register (whether read-only or not), will match the readback from any Unused register.

Parity and Cache Error

According to VR4300 docs, these registers only exist for "compatibility reasons" but also supposedly aren't used by the CPU. They do still exist though, so they do not behave like the Unused registers. The lower 8-bits of Parity are also write-able.

Found this in an unrelated test:

LB $1, 0($2) LUI $2, 0x8000

The LUI seems to change the memory address that the LB is loading from. Investigate this deeper. Does this happen with just LUI or also other instructions?

Previously, we always needed to use some roundabout way of compiling the project, using some external tool or secondary project. From my experience using Rust for other embedded hardware, I've learned how to set up this project, such that much of what nust64 (and cargo-n64) would normally do for us, can be done directly by Cargo.

By adding a field in rust-toolchain.toml, Cargo will automatically install the extra toolchain component (rust-src) if it is missing. Similarly, Cargo (via rustup) will also install the listed toolchain version automatically as well. Cargo/rustup will actually do this if you try to run most, if not all, cargo/rustup commands within the project directory.

By setting default = ["default_tests"] in Cargo.toml, the default_tests feature flag will automatically be set by default, unless --no-default-features is specified. I think it's safe to say that this is the typical expected behavior for most developers. We can still explore alternative ways to organize tests in the future.

Most of the magic though happens in .cargo/config.toml. The build target and other flags that normally would be specified with environment variables and CLI arguments, can be expressed here instead. Not only does this eliminate the need for nust64/cargo-n64 handling the compilation step, it gives the project developer full control over the build target and linker script.

However, this will still result in an ELF file. In order to create an N64 ROM, we must still use some external program. Fortunately, Cargo also lets you specify a "runner". A runner is a program which Cargo will automatically run when compilation completes, while also including the path to the ELF file. nust64 will be this runner for now. If anyone wants to build/use a different runner, then they can freely do so. (I cannot identify any way to have cargo automatically install the runner for the user. Using a build.rs script doesn't work for this as far as I could tell. But the install process is very simple, and specified in the README.)

In the future, if anything needs to be done pre-compilation, it should be possible to use build.rs (https://doc.rust-lang.org/cargo/reference/build-scripts.html)

Please note: Because the compilation side is handled entirely by cargo instead of nust64, the builder/ project is no longer necessary. And so I've deleted it, and moved all of the n64-systemtest files back to the root directory. Fortunately, this time git actually understands what I did lol, and just shows them as being file renames.

Advantages:

• The project developer, gains far more control over the build process. That means: They can use any linker script they want, and reconfigure the build target.
• The Cargo workspace with the "builder" project is no longer necessary, thus reducing repository complexity/size, and improving compile speeds (as it's only compiling n64-systemtest, and not builder+nust64+dependencies).
• Compiling in debug mode (aka the 'dev' profile) is now available. Although, due to some build target issue(s), opt-level=0 cannot be used.
• Rust projects like this one, are much less dependent on external software (cargo-n64/nust64).

Disadvantages:

• The runner program must be installed by anyone wishing to compile the project (cargo install nust64)
• The runner can only be one program. So people who want an emulator/etc to run automatically after building, must make their own script (e.g. .sh/.bat). This might be solvable by adding some extra functionality to nust64, or perhaps we can provide example shell scripts and commented-out runner configurations.

~~PR will remain a draft until Lemmy completes his FPU test additions~~

I'm trying to build on Fedora 36. I get this response:

[loganmc10@toolbox n64-systemtest]$ cargo run --release
   Compiling proc-macro2 v1.0.39
   Compiling unicode-ident v1.0.1
   Compiling syn v1.0.96
   Compiling serde_derive v1.0.137
   Compiling serde v1.0.137
   Compiling autocfg v1.1.0
   Compiling crc32fast v1.3.2
   Compiling libc v0.2.126
   Compiling memchr v2.5.0
   Compiling serde_json v1.0.81
   Compiling adler v1.0.2
   Compiling semver v1.0.10
   Compiling cfg-if v1.0.0
   Compiling camino v1.0.9
   Compiling ryu v1.0.10
   Compiling hashbrown v0.12.1
   Compiling os_str_bytes v6.1.0
   Compiling itoa v1.0.2
   Compiling once_cell v1.12.0
   Compiling textwrap v0.15.0
   Compiling termcolor v1.1.3
   Compiling strsim v0.10.0
   Compiling crc-catalog v1.1.1
   Compiling bitflags v1.3.2
   Compiling bytes v1.1.0
   Compiling dunce v1.0.2
   Compiling miniz_oxide v0.5.3
   Compiling indexmap v1.9.0
   Compiling clap_lex v0.2.2
   Compiling crc v2.1.0
   Compiling flate2 v1.0.24
   Compiling quote v1.0.18
   Compiling atty v0.2.14
   Compiling object v0.28.4
   Compiling clap v3.2.5
   Compiling cargo-platform v0.1.2
   Compiling toml v0.5.9
   Compiling cargo_metadata v0.14.2
   Compiling nust64 v0.1.3
   Compiling builder v0.1.0 (/var/home/loganmc10/git_stuff/n64-systemtest/builder)
    Finished release [optimized] target(s) in 29.34s
     Running `target/release/builder`
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }', /var/home/loganmc10/.cargo/registry/src/github.com-1ecc6299db9ec823/nust64-0.1.3/src/elf.rs:188:10

In the TLB tests, some exceptions are expected at 80000180, others at 80000080. Figure out why this is needed and maybe design some specific test cases around that

This should cover all instructions that can produce an inexact denormal on the host FPU. Previously, this was tested only for DIV.S, and in CTV.S.D (though only for positive denormals).

Technically, the final result is identical to the case in which an exact denormal is calculated by the host (either an unimplemented exception, or a flush), but for the emulator they are likely different codepaths as the control flags generated by the host FPU are likely different.

This PR adds tests for integer division by zero and dividing the minimum value by -1 for all four opcodes (DIV/DIVU/DDIV/DDIVU), checking both the quotient and remainder for correctness.

Note that emulators not explicitly supporting the min / -1 case tend to crash with an arithmetic overflow exception on x86, which makes diagnosing the issue a bit more tricky unless you are aware of this test.

Small PR to implement a few options that were missing compared to the old makefile.

• Added a message upon successfully building and saving the rom, which tells the user where the rom was saved to.
• Added arguments for running the finished rom with usb64 and unfloader.

The makefile appeared to have a way to start some undefined emulator, but I didn't port this because not every emulator's CLI interface works the same way.

There was also a command to build the mini-ipl3 source. But since it's highly unlikely a non-contributor would need to edit that, and the compiled binary is included in the repo, adding this command doesn't seem necessary. Plus, it's very possible the user doesn't have bass installed on their PATH or at all.

There is a problem with discoverability of what feature flags are available. But this should be resolved in later PR(s) that rework test selection. (For now, people can look at n64-systemtest's Cargo.toml, even though it isn't user-friendly.)

Currently, a fork of cargo-n64 in combination with a makefile, is used for building this project into an n64 rom.

There are several problems with cargo-n64 including:

1. Unmaintained for over a year.
2. Relies on an old version of Rust nightly (which is partly why a fork is used).
3. Arbitrarily limits the size of the resulting binary for no apparent reason (again, partly why a fork is used).
4. Overly-complicated codebase which makes modifications difficult.
5. Cannot be used as a crate, necessitating a makefile for ease-of-use.

I've dissected cargo-n64 to learn exactly what it's doing that makes this whole process work, and reworked everything into a new crate: nust64. In short, the build process boils down to two steps: running a cargo build command with special arguments (e.g. custom architecture target) which produces an ELF binary, and extracting/combining the necessary parts of the ELF into a rom.

Migrating to nust64 fixes all of the above problems. However, in order to use it, this project's structure has to change a little. In this PR, you'll see in the Cargo.toml, it now uses a Cargo/Rust feature called Workspaces. Nearly everything from the current repo, has been moved into its own directory /n64-systemtest/, and a new directory /builder/ has been created. Each workspace "member" is its own separate project, but they can still be run/built/accessed from other members and from the root directory.

Due to how the root Cargo.toml is set up, when you run cargo build or cargo run in the root directory, cargo will only perform the respective command on the "builder" project. You can think of the "builder" project, as a makefile, except that it is a full Rust program.

This PR only handles the migration to nust64. It doesn't change the n64-systemtest code at all (besides moving it). It doesn't add any new functionality. It does update the README to reflect the changed build instructions. There is potential for additional functionality to be added later, but this PR is only focused on the migration. (The n64-systemtest code is up-to-date as of 5fb0574a24bfd2a05e80b27d3e6e93d1811294f5)

Similar to the make n64 command, running cargo run or cargo run --released will by default include --features default_tests and default to the mini-ipl3 binary, unless otherwise specified.

If you run into any problems building this PR into a working rom, I suggest running cargo clean once to clear out any outdated junk. Otherwise, let me know any other problems or questions you have.

Adds some docs to commonly used methods and structures.

While this isn't a crate, rustdocs are still helpful for new developers who are learning the codebase (such as myself). IDE's and editors that support Rust, typically have some way of rendering these docs. Otherwise devs can run cargo doc to generate the Rust standard web-based docs (/target/doc/n64_systemtest/index.html).

The following features no longer have to be declared: const_fn_trait_bound, asm, global_asm

Unfortunately, a few new features are needed now: asm_const, asm_experimental_arch (as we're on MIPS) and asm_sym.

Stil a win as asm! itself got stabilized and we just need subfeatures.