MSX machines reverse engineering utilities v1.02
------------------------------------------------

This set of utilities is aimed to help owners of MSX models that are not
yet emulated to obtain all specifics about their machines so they can be
properly emulated.

===== 1) Introduction =====

This guide was written to be as simple as possible, so users without any
technical knowledge can help and dump their machines.

Before you begin, always check if your machine isn't already emulated in this
list:
https://github.com/openMSX/openMSX/tree/master/share/machines

Please note that there are different region variations (i.e.: Japanese and
European) of many models and not all variations have been dumped yet. For
example:

- The European Toshiba HX-10 have been dumped, but the original Japanese model
  hasn't.
- Most of the European Spectravideo models have been dumped, but the US models
  still haven't
- The European Sony HB-F500P have been dumped, but the Japanese HB-F500 hasn't
- The Mitsubishi ML-G1 European model have been dumped, but not the Japanese
  model
- The Russian Yamaha YIS805/128 have been dumped, but not the Japanese model
- Only the Yamaha CX5M & CX5MII European models have been dumped. Many otheri
  models are missing: US, Australian, etc.

Many other relevant machines are still missing:

- Hitachi MB-H50
- Toshiba HX-33
- Toshiba HX-34
- Talent DPC-300
- Mitsubishi ML-G10
- Mitsubishi ML-G30
- Mitsubishi ML-G30mkII
- Sanyo PHC-55FD2
- Yamaha YIS805/256
- Many models from the middle East


===== 2) Description =====

a) BENCHMRK

This folder contains the utilities that measure the speed of the MSX
machine in many aspects. It contains the following utilities:

CHKSPD.COM	Measure the CPU speed in MHz. Requires an MSX2 or higher.
DHRYSTON.COM	Measure the CPU speed in dhrystones
DSPEED.COM	Measure the disk read speed.
DSPEEDW.COM	Measure the disk write speed.
OUT98H.COM	Measure the VDP speed. Requires an MSX2 or higher
POWER.COM	Measure the CPU speed against the standard 3.57MHz Z80
VDPSPED2.BAS	Measure the CPU->VRAM write speed

b) REVRENG

This folder contains the utilities that print many aspects related to your
MSX configuration, like layouts and devices present.

BOGUSTST.BAS	Test many VDP specific features
COLORBAR.BAS	Shows the default palette of the machine
IDENT.BAS	Identify the VDP, Z80 and PSG types
KEYMATR.BAS	Shows the keyboard matrix
MASKTEST.BAS	Tests the table masking feature of the VDP
MSXMEM.BAS	Shows what's present on each of the slots
SWIOSCAN.BAS	Scans the switched I/O ports to see if there's any device

c) ROMDUMP

This folder contains the utilities that allow ROMs to be dumped.

SAVEROM.ROM	Saves backups of the ROMs to the disk.
KANJIROM.BAS	Dumps a backup the Kanji ROM to a file

d) Contains the MSX-DOS, required to run the .COM utilities above


===== 3) How to use =====

Using these utilities is very simple.

a) First, you must copy all utilities to a disk. 
You'll also need a disk interface to be present on the MSX, of course. 
MSX uses standard PC FAT formatting for disks, regardless if they're floppy
disks, SD cards or CF cards. You can copy files to MSX media using a PC or Mac
without trouble.

- .BAS utilities are run from the MSX-BASIC with the RUN"UTILITY.BAS" command,
  or from MSX-DOS with the command: BASIC UTILITY.BAS
- .COM utilities are run from the MSX-DOS. Just type the utility name and
  any parameters required after the name, separated by spaces.
- To boot the MSX directly to the BASIC, just leave the disk out of the drive.
  After the MSX is on BASIC, you can insert the disk in the drive again.

b) Run every utility in your machine and take pictures of all the result
   screens of each program. Just don't run on an MSX1 the utilities that
   an require MSX2 or higher, of course.

c) KEYMATRIX.BAS

This utility shows a 1 for each key not being pressed, and a 0 for each key
being pressed. The first thing is to take a picture of the screen while
pressing the following combination on the keyboard:

- SHIFT+GRAPH+0
- Key "1" in the numeric keyboard, if there's one present

After that, only nonstandard MSX keys are of interest. If your keyboard has
any nonstandard keys, take a picture of the screen while holding each one of
them, and only one key each time.

The standard MSX keys are:
- The usual QWERT keyboard
- Optional numeric keyboard
- Special keys: ESC, TAB, CTRL, SHIFT, RETURN, BACKSPACE, RETURN, F1/F6, F2/F7,
  F3/F8, F4/F9, F5/F10, STOP, CLS/HOME, SELECT, INS, DEL, CAPS LOCK, GRAPH,
  KANA LOCK (or CODE)
- Some machines have a PAUSE button. But that's in fact a button and not a
  real key.

Any keys not listed above must be pressed and a picture of the corresponding
location in the keyboard matrix must be taken.

d) Dump the ROMs

Boot a disk with MSX-DOS and run the SAVEROM.COM utility with the following
parameters:

SAVEROM SLOT0-0.ROM /S

SAVEROM will then display again the slot map where any ROMs where found. Take
a picture of this information for the next steps.

Type the following information:

Primary Slot: 0
Secondary Slot: 0 
Select Type: Normal   (use the UP/DOWN arrows here to select)
Begin Address: 0
End Address: FFFF

This will make a full dump of the slot. Emulator programmers will be able to
crop only the necessary parts themselves later. It looks like this:

Now look at the picture you took from the slot layout reported by SAVEROM.
Now you need to repeat the steps for every slot that SAVEROM found some ROM,
like this:

SAVEROM SLOTx-y.ROM /S

(where x-y are the slot ID shown in the "Slot" column of the SAVEROM table)

Primary Slot: x
Secondary Slot: y 
Select Type: Normal   (use the UP/DOWN arrows here to select)
Begin Address: 0
End Address: FFFF


===== 4) Post the results =====

Post the results in the following thread of the MSX.org website:

https://www.msx.org/forum/msx-talk/emulation/dumpingreverse-engineering-msx-models-thread





