BrMSX
the Brazilian MSX Emulator
by Ricardo Bittencourt

BrMSX is a MSX 1 emulator for DOS.

In these days, every kid knows what an emulator is. What is an MSX, that's another history.

MSX is the best 8 bit computer ever created. The first version of the MSX uses a Zilog Z80 running at 3.57 MHz, and offers true parallelism, with three slave processors. The Texas TMS9928 controls the video and generate the interrupts. The GI AY-3-8912A controls the sound and joysticks. The Intel 8255 controls the remaining hardware, like the tape, the memory manager, and the keyboard.

The MSX was produced in a lot of countries. It was a success in Brazil, Japan, Spain, the Netherlands, France, Italy, the list go on. Still today, many users think the MSX is better than the average PC. And I'm one of them.

The MSX has a lot of charisma. It was the more powerful computer of his time, influencing a generation of future engineers and computer scientists. With the MSX, almost everyone was a programmer. It was so easy, everyone could develop software for it. This is the one thing the PC can never achieve.

And of course, there are the games! The MSX has lots of great games, produced by Konami, Compile, Namco, Falcom, lots of arcade conversions, addictive games that you can never forget!

Unfortunately, the MSX is not produced anymore. The old users still have their machines, but new users could never taste the joy of MSX.

Until now. Until BrMSX.

With BrMSX you can use your PC to feel a sample of the MSX greatness. You can play the MSX games, you can program its BASIC, you can use its debugger to learn assembly. You can join the MSX community.

But, before you immerse yourself in an unforgettable MSX experience, it's better to learn more about this emulator. Read this manual from the beginning until the end: then stop and start BrMSX.

Of course, you may become so addicted to MSX, that you may want to buy a real machine. There are user groups that can sell you a second-hand machine. In the BrMSX page you'll find the home pages of many active brazilian groups.

Have fun!

Current version: 1.155

Requirements

BrMSX requires a 386 processor or better, since it is written in 100% 32-bit assembly. The slowest computer I have access is a 486sx25, and BrMSX runs at full framerate in this one. Some games run at full speed on a 386dx40.

BrMSX requires 2Mb of RAM memory, 4Mb if you want to use disk emulation.

BrMSX can adapt itself to Pentium processors and MMX processors to take advantage of theirs specials features.

A VGA with 256kb of VRAM is required. To enable the TV emulation, you'll need a Super VGA with a VESA 2.0 driver.

Sound emulation require a Sound Blaster with auto-initialized DMA at 45455 Hz or 100% compatible sound board. If you don't have a Sound Blaster, you can enable the sound through the PC Speaker.

Multiplayer game requires two computers equipped with UARTs capable of 57600 bauds.

BrMSX is designed to run under DOS 6.22 . It will work under Windows 3.11 and Windows 95, but will not work under Windows NT. Some options cannot be used under Windows.

Features

BrMSX is modeled after the brazilian Expert 1.0. It has lots of nice features:

Very accurate Z80 emulation. BrMSX is the only MSX emulator to pass in all ZEXALL tests for Z80 compliance. BrMSX emulates all the undocumented opcodes and all the undocumented flags. BrMSX also emulate undocumented features of the VDP and the PSG.

Port-based disk emulation, BrMSX is the only MSX emulator that can run brazilian software like Super Disk Copy and Chave Mestra.

Emulation of the brazilian memory expansion MegaRAM, BrMSX is the only MSX emulator that can fully run ExecROM.

Wave based sound emulation, BrMSX is the only MSX emulator that can play PCM samples in game like Super Laydock, Fuzzball and Oh Shit!

LED emulation, BrMSX is the only MSX emulator to properly handle the Caps Lock LED in the keyboard.

TV emulation and Green Monitor emulation, BrMSX is the only MSX emulator that handles VESA 2 resolutions with scanlines and low-pass filters.

Multiplayer games, BrMSX is the only MSX emulator to support two players at the same time in different computers.

Fast emulation, BrMSX is the fastest MSX emulator of all.

A great debugger with step-by-step execution and capabilities to read all the hardware information.

Many other nice features like a GUI, save and load machine state at any time, full support to korean roms, and more!

Command Line Options

BrMSX can be invoked from the MS-DOS command line using the following syntax:

brmsx [CartA.ROM] [CartB.ROM] [options]

Everything is optional, except that brmsx in the beginning. If no parameters are passed, BrMSX will start a standard emulation of the BIOS and the BASIC.

The cartridges can be simple 16kb ROMs, starting at 0000h, 4000h or 8000h, BASIC 16kb cartridges starting at 8000h, 32kb cartridges starting at 4000h, or MegaROM cartridges (eight mappers are supported).

If you don't pass any cartridge in command line, a MegaRAM with 256kb will be inserted in slot 1. The normal RAM of BrMSX is Memory Mapped with 128kb.

You can select two cartridges at the same time, this is useful for resident programs, like the Mega-Assembler, and also for cartridge combos. More about this in the Cartridge Combo section.

There are lots of command line options. All of them start with a "-" and must be used in lower-case. Some of them require a parameter, that must be placed right after the option, separated by a space.

The options supported will be presented in functional blocks:

CPU options

Memory options

Video options

Sound options

I/O options

Multiplayer options

Control options

Inside the emulation

The MSX has some keys not present in the PC. The key mapping is presented in table below:

The LEDs in the keyboard are also emulated:

Some keys have special meanings:

The GUI can also be called with a press in the left mouse button.

Graphic User Interface

The GUI is very easy to use (after all, that's the idea!)

The menu is presented in the left of the screen, and you must use the mouse and its left button to select the options. Click anywhere out of a window to return to emulation.

The options of the GUI are:

Debugger

By pressing ESC in the intro, or F10 in the emulation, you enter the Fudebug (Full Debugger). I will not explain the many things presented in the screen. If you don't know what's on the screen, then the debugger is not for you.

The Fudebug is a very powerful tool to aid in MSX programming. The commands always have one letter, and some of them may take arguments. Be careful when entering arguments, because there is no backspace. Values entered must be always in hexadecimal.

The commands supported are:

Multiplayer

With BrMSX, you can connect two computers to play multiplayer games, using a serial cable. The first computer controls the keyboard of MSX (player 1), and the keyboard of the second computer acts as the joystick B to the MSX (player 2).

The key mapping for the second player is:

To start a multiplayer session, you must type in the fastest computer "brmsx -server -com 2", replacing of course "2" with the number of your COM port.

After starting the server, type in the client "brmsx -client -com 1" , again, don't forget to check the COM port. This will start the emulation in multiplayer mode. Only the server monitor will display the MSX screen.

To exit the multiplayer session, finish the client emulator first!! The wrong order will lock both computers.

Some games with option to two players are: Konami's Soccer, Salamander, Konami's Ping Pong, Super Laydock, Yie Ar Kung Fu 2, Warroid, and lot more that I don't remember.

Cartridge Combo

BrMSX has support to two cartridges at the same time. This is useful to programmers (you can load Mega-Assembler and XBasic at the same time), and also is useful for game players.

Many games will have secret options when connected together with other cartridge. Some examples are:

Nemesis in slot A and Twin Bee in slot B: your ship will turn into a Bee.

Nemesis 2 in slot A and Penguin Adventure in slot B: your ship will turn into a Blue Penguin.

Nemesis 2 in slot A and Q-Bert in slot B: you can press "F1" and type the secret codes LARS18TH and METALION.

Salamander in slot A and Nemesis 2 in slot B: a secret stage will appear after the three planets, you can defeat Venom and see the good ending.

MegaROM Mappers

BrMSX supports almost all MegaROM Mappers used in MSX 1 games. If BrMSX finds a game in its internal database, then the MegaROM Mapper will be autodetected. Otherwise, it will be used the Mapper #0.

The Mappers supported are:

#0: Generic MegaROM with SCC

Games: Animal Land, Super Laydock, Jagur, Vaxol, Mirai, Donkey Kong, Digital Devil Story, The Fairy Land Story, Final Zone, 3 Kingdoms, 1942.

#2: Konami with SCC

Games: Nemesis 2, Nemesis 3, Salamander, King's Valley 2, F1 Spirit, Parodius.

#3: Konami without SCC

Games: Nemesis, The Maze of Galious, Shalom, Penguin Adventure.

#4: ASCII 8kb

Games: Valis - The Fantasm Soldier, Hydlide 3, Fantasy Zone, Dragon Slayer 4.

#5: ASCII 16kb

Games: Gall Force, Eggerland Mystery 2, Golvellius.

#6: ASCII 8kb with 8kb SRAM

Games: Xanadu.

#7: ASCII 16kb with 2kb SRAM

Games: Hydlide 2.

#8: Original Panasonic FM-PAC with 8kb SRAM

Games: FM-PAC cartridge.

Memory layout

brmsx

brmsx cartA.rom cartB.rom

brmsx -ramslot 3 cartA.rom cartB.rom

brmsx -korean cartA.rom cartB.rom

brmsx -diska msxdos.dsk cartA.rom

Troubleshooting

Answers to some common questions:

Q: How do I run these .ROM games?
A: Copy the .ROM to the same directory of BrMSX and use the built-in GUI. You can also type "brmsx game.rom" if you're smart enough to use the DOS prompt.

Q: How do I run these .DSK games?
A: Just type "brmsx -diska game.dsk". From now on, everything will be like a real MSX with a disk-drive.

Q: I'm trying to run this game "Terramex" and it doesn't work!
A: This is not a BrMSX bug, you actually found a bug in the game loader. Try to run the gameagain, but this time start BrMSX with the option "-ramslot 3". Some games that require it are Terramex, Oh Shit and Camelot Warriors.

Q: This large game "Gall Force" is not working!
A: If the game is greater than 32kb, then BrMSX couldn't guess the right MegaROM Mapper for this games. Try to use the "-roma" option with all available values, until you find one that works.

Q: I'm trying to play "Zanac" but the ship is flickering! Sure you made a mistake since I tried the same ROM in another emulator and it doesn't flicker.
A: This flickering will also appear on a real MSX, it's a feature of the VDP called "5th sprite occultation". Some games require it to display correct graphics, like Parodius, Goonies and Antartic Adventure. You can disable this feature with the command line option "-fakespr". If this flickering does not appear in your other emulators, then either they don't emulate this feature or it is disabled by default.

Q: I can't hear any sound!
A: BrMSX only supports the Sound Blaster and 100% compatible sound cards. Some older models, like the Sound Blaster Pro, are not supported. BrMSX also don't have sound with the ESS audiodrive. Gravis Ultrasound users should use the Sound Blaster emulator MEGAEM. Give me enough time and I'll write drivers for all these cards. Meanwhile, you can try the PC Speaker sound or the 22222Hz version (brmsx22.exe).

Q: Why "Bubble Bobble" and "Metal Gear" don't work in BrMSX?
A: These are MSX-2 games. BrMSX only emulate the MSX-1 by now. ***

Q: When BrMSX will have MSX2 emulation?
A: Just after I finish MSX1 emulation. There is no point in adding MSX2 emulation if the MSX1 is not fully implemented! There are many MSX1 features still not implemented in any emulator (mainly the undocumented ones), and to achieve perfect emulation, I must add all of them. ***

***Note: The two Questions above for the brmsx v1.155 these problems where fixed in v2.06, to Run METAL GEAR 2 or Bubble Bobble just Add the extension"-MSX2" in somewhere in the command line… So don’t worry!!!

Q: Where can I find this ZEX test? Does it have versions for 6502?
A: The ZEX (Z80 Exerciser) is a program to test Z80 compliance. It can be found in the YAZE package. YAZE stands for Yet Another Z80 Emulator and can be found in CP/M sites. The original version of ZEX run in MSX-DOS, but I made a .ROM version before adding disk support. If you're interested in this version, mail me. ZEX was only made for Z80, and it's not available for any other processor.

Q: Can I be a beta-tester?
A: You already are a beta-tester, since all my releases are beta-versions.

Credits

Some people believe I make BrMSX alone. That's not true. I really program alone, but BrMSX is much more than a simple program. Many people helped me contributing with sample source code, data books, tests in real machines, bug reporting and just with incentive.

First of all, I want to thank Arnon Cardoso. It was his idea to start a brazilian MSX emulator. You people should try his great Java MSX emulator. Someday the PC standard will die, and BrMSX will not be useful anymore. But a Java emulator has the potential to be used forever.

Many thanks to Sean Young. He gave me lots of insights in the early stages of BrMSX (but of course the most important of all was "sometimes you must STOP and THINK" :). The source code of Virtual MSX and his tech pages were great resources.

I can't forget Isaac Santaolalla Solorzano. Sometimes I think he spend more time debugging my emulator than his one! He is the one guy that really have fun with MSX. Try his emulator MSKISS, it has lots of features not found in BrMSX, like native GUS support and MegaROM Mapper auto-detection.

Adriano Cunha was a great inspiration. He HATES emulators, and I have to make BrMSX become a perfect emulator to make he use it. It's not impossible after all.

And of course I have to thanks Thomas Pytel. Without his library PMODE, I would never learn protected mode assembly, and BrMSX would never be so fast.

If I would thank everyone who helped me, this file would become too large to download. But can't end this manual without mentioning the help of Marco Antonio Simon Dal Poz, Enrique Sanchez, Alex Wulms, Hans Guijt, Eduardo Toledo Santos, KSH, Edison Pires, Insano Delavy, Marcellus Pereira, Marat Fayzullin, Marcel de Kogel, Ademir Carchano, Pierluigi Piazzi, Cyberknight, Walter Marujo, Werner & Weber Kai, Shawn Hargreaves, Mark Feldman, Giovanni Fudeba, Alex Sato, Zoop, Erik Dias, FRS'9X, Ricardo Juracy, Italo Valério, Daniel Caetano, Vanessa Sabino, Daniel Vicentini, Rogério Cobra Bello, Tiago Tresoldi, Miki Watanabe, Luciano Menezes, Marcelo Eiras, Saez Frank, Ulrich Doewich, Mudkicker, TFH, Omar Mosqueda, Leonard Silva de Oliveira, Jaime Magno Flaviano Galle, Neckfreak of Bandwagon, Peter Latimer, Alwin Henseler and all the people who sent me e-mails with bug reports and comments. Thank you all!

If you want to translate this manual to Japanese, Korean, Dutch, Italian, or any other language spoken by MSX lovers, please contact me.