Compatibility testing
This page was last modified 21:19, 7 March 2018 by Mars2000you. Based on work by Sd snatcher and NYYRIKKI.

According to wikipedia, Compatibility testing is part of software non-functional tests, where tests are conducted on the application to evaluate the application's compatibility with the computing environment.

Compared to other computer systems of the same era, the MSX standard is very flexible, to allow as much as hardware independence as possible. This is intended to both (1) allow easy/cheaper future expandability and (2) accomodate different designs from different hardware makers.

So much flexibility resulted on some issues when software wasn't coded strictly following the standard recommendations. At that time, add this to the lack of good documentation, the novelty of the idea, the limited resources of the smaller software companies (who couldn't afford having a lot of different machines to test) and that some parts of the world had only a few models available, and the result is that there are many programs that will glitch or even freeze when you try to run it on machines with different configurations.

But it doesn't need to be like this anymore. These days there are a lot of MSX programming documentation available on the Net. The coding guidelines are well known and clearly described on the MSX Technical Handbook. It's now only up to the programmer to decide whether he want's or not to code according to the standards or not.

For those worried about the compatibility & compliance issues, this article provides information to help them to stress test their software and try to minimize any surprises that would compromise his/her image as a good programmer. Most of the tests can be done using the excellent openMSX emulator features, to reduce costs.

Each step try to deal with an specific aspect that is known to cause headaches. This procedure will obviously not catch every possible bug, but will certainly help you to iron out the majority of them and deliver a higher quality software. You will also learn a lot about the MSX architecture while working to solve the bugs.

It's good to keep in mind that if your software fails on a specific test or one of the mentioned machines, it's not the case that "it's just that machine". The machines listed here are mentioned as the representatives for that category, but bugged software that fail on one of them will probably fail on many other non-listed machines with similar configuration.

Last, but not least, there are at least two principles that a MSX programmer always have to keep in mind:

  1. MSX machines are not all alike. They're not just clones of each other like on other closed architectures and there are hundreds of different models
  2. Your program can never assume that it will run alone on the machine. There's a high probability of an extension being present, or the BIOS doing some processing on the machine at some point. Since there's no memory protection, you program must behave to coexist, or it will inevitably fight with someone in the neighborhood at some point.


Slot handling tests

Bad slot handling is one of the most famous troublemakers on the standard. A lot of software fails to run or to detect extensions just because of such basic element of the architecture. To stress test it, you can try the following tests:

Test on Acid1Test

This is a non-existing machine, specifically designed with a very complicated slot layout that combines features from real machines that are known to cause problems with many existing software. This reduces your time spent on testing: instead of testing on a dozen of emulated machines, you can try this one that summarizes nearly all of them.

  1. Installing
    1. Download the Acid1Test from this site and unzip it into the share\machines folder of your openMSX installation.
    2. Get the ROMs for the Expert Turbo (or Expert3) and Sanyo PHC-70FD somewhere on the Net. Unzip them on the share\systemroms folder of your openMSX installation.
    3. Depending on the frontend used to launch openMSX, you may need to force a scan of the available machines.
  1. Running the test
    1. No secret here. Just fire up openMSX as usual, but select Acid1Test-slots as your target machine. Then you can use the excellent openMSX debugger to investigate any problems.

Test on the emulated known troublemakers of this category

Some machines are known to cause problems on this category. You can also check your software against their emulated versions on openMSX. Test it at least on:

  • Sony HB-F500. This machine is the worst programmer's nightmare on many aspects, and a lot of software is known to fail to run on it. Some of it's many characteristics are known to cause trouble:
    • It has a complicated slot layout: half of the 64K RAM is on slot0-0. The other half is on slot 0-2. The disk controller is between them. On European models, there are also three external primary slots: 1, 2 and 3.
    • The real machine is very picky with VDP timing. If you write too fast to the VDP, it might corrupt data.
    • Note: There are some regional variations of this same machine: HB-F500D and HB-F500F. The main differences seems to be the keyboard layout, and the presence of either the Kanji ROM or a 3rd slot connector. All of them will behave exactly the same on the tests. Later, Sony released the Japanese HB-F500 "mk II", with a more conservative memory layout, closer to the European HB-F700P model in many aspects.
  • Toshiba HX-23F: This machine also has its RAM split in half, between slot 0 and slot 3-0. This causes trouble to programs that assume that all the RAM will be available continuously in a single slot. It's little brothers HX-23 and H-22 feature this same RAM layout.
  • Victor HC-95: This beautiful and powerful MSX2 (the first one with turbo) is known to cause some trouble because it has a unusual slot configuration, with its RAM located in the expanded slot 0-2. Software that only deal with primary slots (like most ZX-Spectrum ports) will never run on this machine without a proper bugfix. Tricks like the POKE-1,xxx won't workaround the problem. openMSX already emulates this machine (only in Z80 mode), so it can be used for testing.
    • Note: There are some model variations for this machine: HC-90, HC-95(V), HC-95(T). Some have 1 floppy, others have 2. The (T) model is said to have a V9958 inside. Take a look the respective wiki article for more details.
  • Sony HB-10P: This machine was designed with a cost saving address decoder that results in an unusual memory layout that contains in slot 0 a mirror the page-3 of RAM, that is in fact located in slot-3. The BIOS handles this quite well, but it causes some less cautious software to have problems.
  • Casio PV-8: This machine has only 8KB of RAM on slot-0 and a single cartridge connector, and a docking station that adds another 8KB + 2 cartridge connectors, and many users added an external RAM expansion (+16KB or +64KB) that, when used, will cause the memory to select the upper 16KB from the slot 0 and the rest from the external expansion. It also can be a test of running your software on the minimal possible MSX configuration. Unfortunately, openMSX doesn't emulate this machine yet. The Casio MX-10/MX-101 and the Yamaha CX-5M will also present the same split-RAM behavior when an external RAM expansion is used on them.
  • National CF-3300: This machine is a minor ofender. It has its RAM on slot-2 and some software (like Eggerland Mystery 2) doesn't seem to handle that well.
  • RAM expansions, like National CF-2131, Casio OR-216, Sharp HB-4100, or memory mappers. When used to expand the RAM of machines that have less than 64KB of memory, the result will almost always be a split-memory layout. Some software incorrectly assume that the RAM on lower frames will be on the in the same slot as the frame-3, causing them to crash on machines with RAM expansion cartridges like these.

Speed/timing tests

This category of tests try to detect two kinds of bugs:

  • Writing/reading data to/from the MSX1 VDP quicker than it can handle
  • Being able to run at the correct speed even on turbo machines (either CPU or the blitter)

Fortunately, openMSX provides all the necessary tools for the developer to test these.

MSX1 VDP I/O speed

  • Fire up some MSX1 machine, like the National CF-3000
  • Pause it on the MSX boot screen (press the Pause key on PCs, or cmd+P on Macs)
  • Open the openMSX console (press F10 on PCs, or cmd+L on Macs)
  • Type toggle_vdp_access_test
  • Remove the pause by pressing Pause or cmd+P again.

As your program runs, this script will then nicely summarize all the addresses that do I/O to the MSX1 VDP at a higher speed than allowed. You don't have to worry about turbo speeds on this test: the turbo machines required to provide some mechanism to allow the proper I/O speed, either by lowering the CPU clock on each VDP I/O (MSX1, MSX2) or by generating the necessary waitstates when needed (MSX2+, MSX Turbo-R).

Turbo compliance tests

There are a lot of turbo machines out there. Some are have native turbo, some were upgraded by their owners (who probably upgraded the RAM and many other machine features too). While the homebrew kits usually have a switch to turn the turbo off, the native ones usually will require the user to reboot his machine to change the current CPU or CPU speed. This is annoying and time consuming for nothing, as the software can easily deal with that because the VDP provides a proper mechanism for timing.And the software can even take advantage of the extra speed for lowering loading times, quicker screen changes, less slowdowns on crowded areas, as it's also sad for the user to face such slow behaviors when he knows he has a fast machine.

Turbo test: CPU speed

To stress test the timing routines of your software, proceed as this:

  • Fire up the Sanyo PHC-70DF2 on openMSX. It's the best machine for this test.
  • Pause it on the MSX boot screen (press the Pause key on PCs, or cmd+P on Macs)
  • Open the openMSX console (press F10 on PCs, or cmd+L on Macs)
  • type the following commands:
  set z80_freq 80000000
  set z80_freq_locked off
  • Remove the pause by pressing Pause or cmd+P again.

Now you have a very fast machine to deal with. Timing improperly done with empty software loops will be blown to space. This will also check if you did a proper VDP blitter handling: bugged software will also get partial blits when this test is run, because they don't check the completion status bit as required.

Keep in mind that openMSX preserves this ultra speed setting between runs. To disable it, you just need to type the following command on the console:

 set z80_freq_locked on

Don't worry about the 80MHz setting. It's only used then you release the frequency lock.

Turbo test: VDP blitter speed

This is the maximum speed test possible on an MSX. Just run this test after running the previous turbo test that only accelerates the CPU, otherwise you will not catch the mentioned partial blitting bugs.

To perform it, follow these steps:

  • Fire up the Sanyo PHC-70DF2 on openMSX. It's the best machine for this test.
  • Pause it on the MSX boot screen (press the Pause key on PCs, or cmd+P on Macs)
  • Open the openMSX console (press F10 on PCs, or cmd+L on Macs)
  • type the following commands:
  set z80_freq_locked off
  set cmdtiming broken
  • Remove the pause by pressing Pause or cmd+P again.

Please notice that it's assumed that you already configured the Z80 to 80MHz on the previous test, so you don't need to type that command again.

This commands will turn this MSX2+ machine into a speed demon: The Z80 will run at 80MHz and the VDP blitter will run at a fantastic speed. Timing routines must be very well coded to couple with that.

OpenMSX don't preserve the turbo blitter between runs, so you will need to enable it on each time you test. Also don't forget to disable the turbo CPU after your testings, as there are many other machines with disk controllers that can't handle such speed.

Coding guidelines compliance tests

BIOS programming test

The MSX Technical handbook and the MSX datapack states that the only BIOS internal addresses assured to remain at the same addresses are the BIOS jump & information tables and the Math Pack. Buy unfortunately some programmers ignored this and thus their programs have issues to run between different MSX versions of MSX models that have those addresses changed.

There is an MSXAcid test planned to catch this kind of bug, but it still isn't implemented. Meanwhile, you can try to run the following tests to catch some of the most BASIC errors:

Most MSX machines use exactly the same standard BIOS, while others have just binary patches done on an hexadecimal editor. But there are some with bigger modifications that cause trouble to bugged software:

  • Run the software on an emulated Sharp HB-8000, AKA "Hotbit" (preferably the v1.2). This machine had its BIOS recompiled, and this caused a lot of internal addresses to change as allowed by the standard. And the result is obvious: some software fails miserably. There's even a classic case of weird behavior: Konami's Gradius-3 only runs on the HB-8000 if a printer is connected and ready. But the Konami logo will show up completely corrupted. This happens because there's an illegal direct jump to a BIOS internal routine and the HB-8000 has its printer routines right there that change some stack values and wait for the ready pin.
  • Run the software on the Panasonic FS-A1ST. Yes, you read it right. The very first MSX Turbo-R model had many changes on its BIOS. This caused many bad behaved software to have some failures, like the Game Master. On the FS-A1GT Panasonic had to implement quite some workarounds to try to deal with the problem. Too good there are patches to fix those GameMasters already.
  • Run the software on C-BIOS. This is an awesome projet that aims to implement a completely opensource compatible alternative for the MSX BIOS. Since it doesn't use any ASCII/MS code, the internals are completely different. But if you read the source, you'll notice that they unfortunately had to implement a lot of workarounds for bugged software. Since nobody wants to give them any more unneeded trouble, please test your software against the C-BIOS.

Illegal Direct I/O access test

This is the hardest of all the tests ever. If your software pass on this test, you can consider yourself a programmer that truly dominates the MSX programming. You must know the architecture very well to be able to master this skill and achieve good results. This select club is formed by nearly all NAMCO, ASCII and Konami pos-1985 games.

This test could be even harder, but there's still no support for changing the Memory-Mapper I/O and subslot register address on openMSX yet. So keep in mind that these two aspects of the MSX architecture will still not be tested for now.

  1. Installing
    1. Download the Acid2Test from this site and unzip it into the share\machines folder of your openMSX installation.
    2. Get the ROMs for the Expert Turbo (or Expert3) and Sanyo PHC-70FD2, standalone MSX-AUDIO v1.0 and MSX-DOS v2.2 somewhere on the Net. Unzip them on the share\systemroms folder of your openMSX installation.
    3. Depending on the frontend used to launch openMSX, you may need to force a scan of the available machines.
  1. Running the test
    1. No secret here. Just fire up openMSX as usual, but select Acid2Test-hardware as your target machine. Then you can use the excellent openMSX debugger to investigate any problems.

While running this special machine, you can also set some breakpoints to detect the addresses that do illegal direct hardware access, like this:

VDP (will catch the illegal hardcoded access, but legal non-hardcoded direct access will pass fine)

debug set_watchpoint write_io { 0x99 0x9A }
debug set_watchpoint read_io { 0x99 0x9A } 


debug set_watchpoint write_io { 0xA8 0xAB }
debug set_watchpoint read_io { 0xA8 0xAB }


debug set_watchpoint write_io { 0xA0 0xA2 }
debug set_watchpoint read_io { 0xA0 0xA2 }

Similarly, you can set this kind of watchpoints for every other devices: MSX-Music (0x7C~0x7D), MSX-Audio (0xC0~0xC3), RTC (0xB4~0xB5), Printer Port (0x90~0x91), Reset Status Register (0xF4)

Test on the emulated known troublemakers of this category

The Neos MA-20 is an MSX2 upgrade kit for MSX1 machines. It's a nice piece of hardware, and is finally being emulated by openMSX. Since it uses the secondary set of VDP I/O ports, software with this kind of bug will fail to run on it. There are more machines on this category: The brazilian Expert Plus and Expert DD-Plus machines upgraded to MSX2+, and there will be the NEOS MA-20 clone being designed by the MSX community in France.

To test the NEOS MA-20 on openMSX, select an MSX1 machine and plug the NEOS MA-20 into a slot. Probably the Gradiente Expert DD-Plus is one of your best choices here, because it's one of the very few MSX1 machines with a built-in DS/DD drive, and that will make your life easier for testing disk software.

Common less known mistakes tests

There are some obscure less documented aspects of the MSX standard that can also cause trouble on some specific configurations. Some tests to catch them will be detailed here:

Incorrect Stack Pointer placement

Some games have the bad habit of setting the Stack Pointer to a fixed position, without worrying if there will be anything there. According to the standard, this is the correct way to find a place for the stack:

  • For ROMs and BASIC, use the recommended top memory position indicated by the HIMEM pointer (at FC4Ah).
  • For MSX-DOS, the CP/M programming recommendations are valid. Either 0100h for small utils that don't use any MSX inter-slot call by themselves, or "LD SP,(BDOS+1)" for more complex games/programs that need to use inter-slot calls (BDOS address is 0005h).

A good machine to test your game against this kind of bug is again, the dreaded Sony HB-F500. A ROM game will not boot correctly on this machine if the stack hardcoded to F380h like many gamed did.

Test if the VDP R#25 bits 0 and 4 are changed

The the bits 0 and 4 of the V9958's R#25 mustn't be changed by user software. Their contents must always be preserved when writing this register.

For the bit-0, the issue is that the V9958 has a built-in waitstate generator that can be enabled by software. But this is a specific feature that must be implemented on a per-machine basis. Enabling it by yourself can cause problems on some machines that doesn't have the necessary circuit, and disabling it on machines that have the circuitry will also cause problems on turbo mode.

The unwritten rule here is that user software shouldn't ever touch this bit. Only the BIOS may change it when needed.

But if you noticed, this bit is located on the same register that enables the border masking feature for the MSX2+ horizontal scroll. So there are some software that inadvertently disable this bit when they enable the border masking. So, if you're not using the MSX2+ horizontal scroll features you don't need to worry about this test.

To catch the piece of code that disables the WAIT bit from V9958 when they run, use the following command:

debug set_watchpoint write_io 0x99 { [ expr [debug read VDP\ regs 25] & 4 ] == 0 } {debug break}

For the bit-4, changing it to 1 will cause the MSX to freeze. But forcing it to 0 will cause problems with any machine that uses the VDS signal.

Test if the VDP R#9 bit-0 is changed

The the bit 0 V9958's R#9 mustn't be changed by user software. Its contents must always be preserved when writing this register.

If the machine has no superimpose feature, writing a 1 to this bit will cause it to freeze. On the other hand, depending on how the SuperImpose feature was implemented, writing a 0 to this bit can cause it to loose sync.

Test for reads of the PSG write-only I/O ports

MSX machines based on TTL chips or on the Yamaha MSX Engines (S3527 and S1985) are prone to a bug where illegal reads of the PSG write-only port will cause register corruption on the PSG. To make things worse, this port is mirrored at the 0xA5 port. This can give an unwarned programmer a lot o headache because the bugged software will run just fine on emulators and on machines based on the Toshiba MSX-Engines, as they have a much more robust implementation, but will cause all kinds of erratic behavior on the other machines, risking even to fry the PSG of the TTL based machines.

To catch this kind of bug, use the following commands:

debug set_watchpoint read_io 0xA1

debug set_watchpoint read_io 0xA5

MSX-MUSIC compatibility

There are some peculiarities to properly support the MSX-MUSIC and avoid incompatibilities. If your software has MSX-MUSIC support, you must always check those special cases. Fortunately, all of them are properly emulated by openMSX:

  • The Panasonic FS-A1WSX and FS-A1WX MSX2+ models are prone to have their internal MSX-MUSIC BIOS partly disabled if the detection isn't done according to the protocol. This has nasty side effects such as BASIC CALL commands crashing the system and MSX-MUSIC detection fail.
  • The Panasonic FM-PAC (SW-M004) requires the YM2413 chip to be enabled before using, otherwise there will be no sound.
  • The MSX-AUDIO BIOS v1.3 (or higher) has MSX-MUSIC compatibility, but it requires your software to use the BIOS properly. If your software passes on the Acid2Test you should have no worries. But it's always good to test it both on the Boosted_Audio and OPL3 extensions.

Memory Mapper handling

Some software assume that the bigger memory mapper will always be selected by default, but this isn't true. For example, MSX Turbo-R machines always select the internal memory-mapper by default, since external memory mappers have a huge performance penalty (the speed drops to the equivalent of a Z80/5.37MHz).

The programmer should always use the MSX-DOS2 EXTBIO function-1 to obtain the memory mapper table, and look for all entries where's the one big enough for his program needs.

To test your program, just select a Panasonic FS-A1ST and add an external 4MB memory-mapper.

Register saving for BIOS routines with hooks

There's one unwritten rule of the MSX standard that may cause problems if you aren't aware: Many BIOS routines have 5-byte hooks in RAM, so they can be extended using RST 30h (CALLF) to another slot, right? This means that for those routines you have to push to the stack the register you want to save considering the ones modified by both the BIOS routine in question and by CALLF.

I.e.: When you look at the CHPUT "modified register" section, it mentions only "EI". But if the respective hook HCHPU is used with an RST 30h instruction, the registers AF', BC', DE', HL', IX, IY, DI will be added to the list.

Ignoring this causes problems on many machines, with games like Kinnikuman and Maxima freezing on Korean and Arabic machines.

If your software uses the CHPUT routine, always test it on a Daewoo CPC-300 and a Yamaha_AX350II. If it uses other hooks, be sure to test it by capturing those hooks with another software beforehand.

Test on real hardware

Last but not least, always test your software on real hardware, because there are some idiosyncrasies not implemented on any emulator. But there are machines that are more tolerant to some software errors and others that are very picky to some aspects.

In general, if you have the resources (or friends to ask help) it's ideal to have your software tested by someone at least on the following machines:

  • MSX1 machines with the Toshiba T6950 VDP. Albeit fully compliant to the MSX specs, this VDP doesn't have some undocumented modes that the TI TMS99x8 series had. Therefore it's always advisable to test any MSX1 software against this VDP too. Known machines that had this VDP are: Sony HB-10P, Sony HB-20P and Toshiba HX-20.
  • Sony MSX2+ models (HB-F1XDJ or HB-F1XV). Those are the pickest machines ever when it comes to timing to access the V99x8 VDP. If your software don't follow the correct timing it will randomly show video corruption on the most unexpected situations.
  • MSX Turbo R in R800 mode. The superb CPU speed is not the only reason why you should test on this machine: While in this mode, it has the so called VDP I/O slowdown that can cause video flickering and artifacts on software that have racing condition bugs on their video code.
  • Any real MSX1 model. It would be good to also test it on a machine with the Toshiba VDP, since this chip isn't implemented on any emulator yet
  • Expert Turbo/Expert3: This machine is native turbo 7MHz an relies on the V9958 waitstate generator to be able to do the VDP I/O at the right speed. As mentioned, if the software inadvertently disables the V9958 WAIT generation, the image will get corrupted. And you can't rely on any homebrew turbo kit for this test, as they're not standardized. While there are some homebrew turbo kits that also use this feature as it allows much more speed, there are other slower turbo kits don't have this as they just switch to 3.57MHz on every I/O.

On the other hand, there are machines that are very tolerant to other programming issues. While this solid-as-a-rock personality makes them confortable for the user, this also causes them mask any programming mistakes for the following aspects:

  • Except for the cases mentioned above, the MSX Turbo R computers are very tolerant to everything else related to software programming. They will take any suffering without complaints: access to wrong I/O ports, access to the VDP at any speed etc. The same indeed applies to any MSX based on a Toshiba MSX-Engine, like the Panasonic and Sanyo MSX2+ models. Their are very tolerant to programming mistakes too.