Command Line Options

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

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

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

-normal	This option select the normal speed of an Expert MSX. The Z80 runs at 3.57 MHz and interrupts arrive at 60 Hz. This option is enabled by default.
-fast	In this mode, the interrupts still arrive at 60 Hz, but the Z80 run as fast as your host computer can emulate. In my AMD-K6 233MHz, this means the Z80 run at a speed of 65 MHz (waay faster than a Turbo-R). This mode is useful to make compilations in MSX and to accelerate the BASIC. Sound is disabled in this mode.
-turbo	In this mode, everything runs in top speed. However, the proportion of opcodes emulated per virtual interrupt is equal to a normal-speed MSX. This mode is useful to skip intros of games and, of course, to show how fast BrMSX is.
-ifreq <n>	You can change the interrupt frequency with this option. The default value is 60 (NTSC/PAL-M). European users should try "-ifreq 50". This option can also be used to control the speed of the games.

Memory options

-roma <mapper>	This option select the kind of MegaROM Mapper used by the cartridge inserted in slot A. Supported MegaROM Mappers are #0, #2, #3, #4, #5, #6, #7 and #8, BrMSX will try to autodetect the Mapper if you don't use this option. Know more about this in the MegaROM Mappers section. If a game has internal battery-backed SRAM, then this memory will be saved to disk with extension ".SRM".
-romb <mapper>	This option is the same as above, but select the Mapper for the slot B.
-ramslot <slot>	This option select the slot of RAM. Valid slots are 2 and 3. The original Expert has RAM in slot 2, so this is the default value. You need to switch the RAM to slot 3 in two cases: first, if you want to faithfully emulate the HotBit, second, if you have a game with bad programmed loader, and it require the RAM in slot 3. Read more about it in the Troubleshooting section.
-korean	Use this option to enable the memory layout of Korean MSX machines. You will need a set of Korean ROMs: a Korean MSX.ROM and a Korean MSXHAN.ROM. This last ROM will be loaded in the page 2 (8000h) of slot 0.
-megaram <n>	Select the size of the MegaRAM. Valid values are 0=128kb, 1=256kb, 2=512kb, 3=1Mb and 4=2Mb. Default value is 256kb.
-mapper <n>	Select the size of the Memory Mapper. Valid values are 0=64kb, 1=128kb, 2=256kb, 3=512kb, 4=1Mb, 5=2Mb and 6=4Mb. Default value is 128kb.

Video options

-res <n>	This option select the resolution used by BrMSX. Valid values are 0 (320x200), 1 (256x200), 2 (512x256), 3 (256x192) and 6 (512x384x15). Resolution 0 is the default and will work in any VGA video board. Resolution 1 uses a tweaked VGA mode to enable a wide screen, but it may not work in all monitors. Resolution 2 requires a Super VGA with VESA 2.0 driver, but enable the awesome TV emulation, with scanlines and low-pass filter. Resolution 3 also uses a tweaked VGA mode, but it's more compatible than resolution 1 and have square pixels. Resolution 6 is the "Parrot" video engine, this one uses a 15-bit color mode and two digital filters in order to reduce the blockiness of MSX games.
-vsync	This option enable the vertical retrace syncronization. This can make the emulation slower, but some games require it to have a smooth scroll (like Rally-X), or to achieve smooth palette changes (like Penguin Adventure).
-green	Use this to enable the green monitor emulator. Everything will become shades of green. Used together with TV emulation, this is a perfect emulation of Gradiente's original monitor.
-frame <n>	This option adjust the frame skipping. The default value of 1 means all frames are rendered. If BrMSX is slow for you, you can increase this number, but the default value has full speed in a 486sx25 (and even on some fast 386dx!!)
-allspr	This option disables the 5th sprite ocultation. This is useful to reduce flickering in games like Zanac and Nemesis, but it will produce graphic errors in games like Antartic Adventure and Parodius.
-nosprcol	This option disables the sprite collision detection. This is useful to make some games easier (like Abu Simbel's Profanation) and it can make emulation faster in slower machines.
-vdptiming	Enable correct VDP timing. When this option is turned on, accesses to the VDP must wait at least 50 clock cycles to succeed. This option is useful to developers who want to ensure their software will work in a real MSX.
-nocache	This option disables the video cache. This will make emulation a lot slow, but it can be used in case of video cache failure. Read the Troubleshooting section for more details.
-cpugraph	This option enables the CPU graph, an indication of how many time your computer is spending in each step of emulation. The first bar is the time spent on Z80 emulation. The second is the time spent in background rendering, and the third is the sprite renderer. The fourth bar measures the time spent copying data from the main RAM to the RAM in your video board. The fifth bar is the overhead of the graph itself. Use this option to profile the emulator. This option will only work in machines with RDTSC, like Pentium processors.
-psggraph	This option enables the PSG graph, a very nice bar graph showing amplitudes for each sound channel. You'll see three bars for the PSG and five more if the SCC is enabled.

Sound options

-nosound	Disable the sound engine. Useful if the Sound Blaster detection is locking your computer or if you're playing Nemesis at the office.
-scc	Enable the SCC emulation. This is not enabled by default, since SCC emulation is still not perfect. Works only with Mappers #0 and #2.
-sr <n>	Change the sample rate of the output. The default value is 45455 (CD quality), but you may want to decrease this value in slower machines, or if you don't have a 100% Sound Blaster compatible soundboard.
-fmpac	Enable the FM-PAC (YM2413) emulation. Emulation of FM-PAC is very limited at the moment and it will sound very bad. To really enable FM-PAC you also need to use the original FMPAC.ROM (64kb) as cartridge 1.
-speaker	Enable sound through the PC Speaker. The speaker can reproduce all the three melody channels of PSG at the same time, by using a special temporal multiplex algorithm.
-speaq <n>	Change the quality of PC speaker sound. The value controls how fast the channels are multiplexed. The default is 1, and you don't want to increase this number too much, since the quality begins to decrease at a point. I like "-speaq 2", but you may try other values. The range is 1 to 9.

I/O options

-diska <f.dsk>	Enable the disk-drive emulation and select f.dsk as the drive image. Disk images must be in .DSK format, and can be four different types: 40 tracks / 1 side (180kb), 40 tracks / 2 sides (360 kb), 80 tracks / 1 side (360kb) and the common 80 tracks / 2 sides (720 kb). Multi-disk images created with COPY /B are not supported yet.
-disklow	Disk emulation through the I/O ports D0h-D4h. This option is enabled by default, and will only work with brazilian port-based DISK.ROM. Many brazilian programs require this option, like Super Disk Copy, Hello, Chave Mestra and the disk version of Robocop.
-diskhigh	Disk emulation through BDOS patches. This option works with most DISK.ROM, but it is more restricted than the above one. Only .DSK with 720kb can be used, and the Drive LED will not be emulated.
-mount <dir>	Mount a directory as the MSX drive A: . With this option, you don't need to create a .DSK image file to play games in .BIN format. Please check the "troubleshooting" section to get more details.
-tape <t.cas>	Enable the tape emulation through BIOS patches and select t.cas as the tape image. Emulation of tape is restricted on this version, the tape image must not be greater than 64kb.
-joy	Enable the joystick emulation. The joystick will be conected in port A (in most cases this means as player one). If you want to change to port B, go to the section Debugger to learn how to do it. The joystick is calibrated automatically in the start-up, so don't touch it before the emulator starts.
-joysens <n>	Adjust the joystick sensivity. Valid values are from 0 to 7, and the default value is 3. Users of joypads should try this option to get more precision.
-fakejoy	Map the keyboard into the joystick port A, with this option you can play joystick-only games (like Gauntlet) on the keyboard. The mapping for this mode is Cursor Keys= Directional, Left Control= Button 1, Left Alt= Button 2.
-autofire	This option enables the automatic fire (automatically press the spacebar). This is great for shoot'n'up games like Gall Force.
-autorun	This option is similar to the above, but it press the left and right keys. Use this in sports games like Decathlon and Hyper Sports. Press the left and right keys at the same time to run.
-autospeed <n>	Adjust the speed for "-autofire" and "-autorun". The range is from 0 (fastest) to 9 (slowest). The default value is 5.
-snespad	Enable a SNESpad connected to LPT1 and make it act as the joystick in port A. To know how to build a SNESpad interface, please check the BrMSX homepage.

Multiplayer options

-server	Select the computer as the server. Only the monitor connected to the server will display the MSX screen. Always use the fastest computer as the server.
-client	Select the computer as the client. The keyboard of this computer will act as the MSX josytick B. The speed of this computer doesn't matter, you can use a slow 386 to be a BrMSX client.
-com <port>	Select the COM serial port in which you connected the serial cable. This option is required in both sides. Read more about multiplayer games in the Multiplayer section.

Control options

-nommx	Disable the MMX optimizations. Use this if BrMSX detects an MMX processor when you have none.
-nomouse	Disable the mouse driver detection. Use this in case of mouse driver conflict. Without a mouse driver you won't be able to use the GUI.
-novesa	Disable the VESA driver detection. Use this in case of video driver conflict. Without VESA 2.0, you won't be able to use TV emulation.
-noled	Disable the LED emulation. Use this if your keyboard seems to miss keypresses.
-nopentium	Disable the Pentium extensions and CPU autodetect. Use this if the autodetection is failing and causing the machine to hang. Without a Pentium you won't be able to use the CPU graph.
-noenter	Disable the enter pressing at start. Useful to front-end makers.
-help	Show a small help screen.

Inside the emulation

The MSX has some keys not present in the PC. The key mapping is presented in the 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:

Reset	Reset the computer. This reset is a soft-reset, since it does not erase the contents of the RAM or the VRAM.
Turn OFF	Turn off the computer. This is like a reset, but erases all RAM and VRAM contents. You must click on Turn ON to return to emulation.
Load ROM	This option loads a new ROM into the slot A. The ROMs must be in the same directory of BrMSX.
CPU Graph	This option toggles the CPU Graph on and off.
PSG Graph	This option toggles the PSG Graph on and off.
Save state	This option saves the machine state in file called BRMSX.STA. This is great for finishing games!
Load state	This option loads a previously saved state.
Quit	This option quit BrMSX and return to MS-DOS.

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:

S	Exit the debugger and restart emulation.
Q	Exit the debugger and quits to MS-DOS.
F7	Step into a Z80 instruction. This option execute only one Z80 opcode.
F8	Step over a Z80 instruction. Use this option to skip CALL and RST instructions.
U dddd	Disassemble from address dddd.
D dddd	Dump memory from address dddd.
Page Up	Scroll the dump region up.
Page Down	Scroll the dump region down.
Up	Scroll the disassembler window one byte up.
Down	Scroll the disassebler windows one opcode down.
E dddd xx	Edit the byte of address dddd, overwriting it with the value xx.
R rr dddd	Edit the value of the pair of registers rr. "rr" can be AF, BC, DE, HL, PC, SP, IX, IY, AX(=AF'), BX(=BC'), DX(=DE') and HX(=HL').
B dddd	Restart emulation with a breakpoint in address dddd.
F2	Save the machine state to file BRMSX.STA
F3	Load the machine state from file BRMSX.STA
1	Select the debug screen 1
2	Select the debug screen 2
0	View the MSX screen
M	Select the emulation mode (normal, fast, turbo)
Y	Toggle the VSync on and off.
V	Switch between the resolutions (320x200, 256x200, 512x384, 256x192)
J	Switch the joystick emulation between Port-A, Port-B and none.
C	Calibrate the joystick again.
F1	Show the help screen.

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:

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:

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

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

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

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

Games: Gall Force, Eggerland Mystery 2, Golvellius.

Games: Xanadu.

Games: Hydlide 2.

Games: FM-PAC cartridge.

Memory layout

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: How do I run these .BAS and .BIN games?
A: You can use the "-mount" option. It works this way:
(1) Create a directory with "md c:\msxgames"
(2) Copy your games to this directory with "copy game*.* c:\msxgames"
(3) Start BrMSX with "brmsx -mount c:\msxgames"
After creating a .DSK file, just use the commands RUN"GAME.BAS" or BLOAD"GAME.BIN",R .

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 game again, 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.

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: What must I do run "Metal Gear 2" in fMSX?
A: Please don't send me questions about fMSX, CJS or any other MSX emulator. I spend too much time answering e-mails, and this time could be better used programming BrMSX. If you have troubles with any other emulator, contact Marcelo Eiras through his page http://www.geocities.com/~msxsite (Portuguese), or contact TFH through his page http://www.casema.net/~tfh (English) .

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.

Many thanks to my brother, Raul Tabajara. He made all the graphics in BrMSX, from the GUI design to the logo. He is currently searching for a job as a graphic designer for games, you can see more of his work in http://www.lsi.usp.br/~ricardo/raul.htm, and to contact him you can just send an e-mail to me at ricardo@lsi.usp.br.

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.

"I can't believe THAT!", said Alice. "Can't you?", the Queen said, in a pitying tone. "Why, sometimes I've believed as many as SIX impossible things before breakfast!" (Lewis Carroll)