This specification, including any code samples included, has been released into the Public Domain under the Creative Commons CC0 licence version 1.0 or later, as described here: <http://creativecommons.org/publicdomain/zero/1.0>
The 86Box Unit Tester is a facility for allowing one to unit-test various parts of 86Box's emulation which would otherwise not be exposed to the emulated system.
The original purpose of this was to make it possible to analyse and verify aspects of the monitor framebuffers in order to detect and prevent regressions in certain pieces of video hardware.
This specification follows the rules of Semantic Versioning 2.0.0 as documented here: <https://semver.org/spec/v2.0.0.html>
The format is `major.minor.patch`.
- Before you mess with this specification, talk to the other contributors first!
- Any changes need to be tracked in the Version History below, mostly in the event that this document escapes into the wild and doesn't have the Git history attached to it.
- If it clarifies something without introducing any behaviour changes (e.g. formatting changes, spelling fixes), increment the patch version.
- If it introduces a backwards-compatible change, increment the minor version and reset the patch version to 0.
- If it introduces a backwards-incompatible change, increment the major version and reset the minor and patch versions to 0.
- If you make a mistake and accidentally introduce a backward-incompatible change, fix the mistake and increment the minor version.
- To clarify, modifications to *this* section are to be classified as a *patch* version update.
- If you understand SemVer 2.0.0, you may also do other things to the version number according to the specification.
And lastly, the 3 golden rules of protocol specifications:
1. If it's not documented, it doesn't exist.
2. If it's not documented but somehow exists, it's a bug.
3. If it's a bug, it needs to be fixed. (Yes, I'm talking to you. You who introduced the bug. Go fix it.)
The checklist:
- Work out what kind of version number this document needs.
- Update the version number at the top of the file.
- Add an entry to the "Version History" section below describing roughly what was changed.
-`e8` ("either") denotes an 8-bit value where the most significant bit is clear - in effect, this is a 7-bit unsigned value, and can be interepreted identically as a signed 8-bit value.
-`[y][x][0]` is the blue component, or 0x00 if the pixel is outside the snapshot area.
-`[y][x][1]` is the green component, or 0x00 if the pixel is outside the snapshot area.
-`[y][x][2]` is the red component, or 0x00 if the pixel is outside the snapshot area.
-`[y][x][3]` is 0x00, or 0xFF if the pixel is outside the snapshot area.
### 0x03: Verify Screen Snapshot Rectangle
As per 0x02 "Read Screen Snapshot Rectangle", except instead of returning the pixel data, it returns a CRC-32 of the data.
The CRC is as per zlib's `crc32()` function. Specifically, one uses a right-shifting Galois LFSR with a polynomial of 0xEDB88320, bytes XORed against the least significant byte, the initial seed is 0xFFFFFFFF, and all bits of the output are inverted.
(Rationale: There are better CRCs, but this one is ubiquitous and still really good... and we don't need to protect against deliberate tampering.)
Input:
*`e16L` w: rectangle width in pixels
*`e16L` h: rectangle height in pixels
*`i16L` x: X offset relative to image start
*`i16L` y: Y offset relative to image start
Output:
*`u32L` crc: CRC-32 of rectangle data
### 0x04: Exit 86Box
Exits 86Box, unless this command is disabled.
- If the command is enabled, then program execution terminates immediately.
- If the command is disabled, it still counts as having executed correctly, but program execution continues. This makes it useful to show a "results" screen for a unit test.
Input:
* u8 exit code:
- The actual exit code is clamped to no greater than the maximum valid exit code.