I.3 Revision History

Version 0.03.01 (April 2, 2004): Updated for release of MesaDX version 0.03a. MesaDX 0.03a includes several bug fixes and includes support for Power-On Configuration bit "SMS1 Bus".

Version 0.03.00 (March 13, 2004): Update for release of MesaDX version 0.03

Version 0.02.00 (August 26, 2001): Update for release of MesaDX version 0.02

Version 0.01.00 (June 10, 2001): Update for release of MesaDX version 0.01

Version 0.00.01: Formatting Changes.

Version 0.00.00: Initial version. Corresponding to MesaDX version 0.00

I.4 Acknowledgements

Super Majik Spiral Crew, Jon, and Richard Talbot-Watkins: Their documents describing the technical details of the Sega Master System and Sega Game Gear are the foundations of the public's current understanding of these systems.

Andrew Lindsay: Designer of the MK1. His help with the SMS memory system and ROM storage was invaluable. With this information I was able to design and build the SMSARCH, a SMS cartridge backup unit.

James McKay: Provided me with my first glimpse of the SMS memory architecture. Also, for providing miscellaneous information in a (publically released) e-mail converstation with "Neon Spiral Injector."

Bock (or Zoop or Omar Cornut): Bock has been a strong presence in the SMS/GG emulation community. His contributions have on many occasions inspired my own efforts. Additionally, his founding and continuous support of S8-Dev has been a great service to all of us still interested in software development for Sega 8-bit systems.

Maxim: Maxim has made numerous contributions to the world of Sega 8-bit emulation including utilities, demo programs, and technical documents. Maxim is an active member of the S8-Dev forum and can always be depended on to step up and answer the difficult technical questions. Maxim also wrote an outstanding document covering the TI SN76489 sound chip.

Charles MacDonald: Charles' unending work documenting the minutae of the various Video Display Processors used in various SM3A implementations has been invaluable during the development of MesaDX. Charles has also written many test programs and has on several occasions been kind enough to test demo programs on a real SMS.

Martin Konrad: Martin Konrad is the brains behind the SDSC Debug Console. He is also the author of an outstanding SMS debugging emulator, eSMS. eSMS is the first emulator to include an SDSC Debug Console. Hopefully, MesaDX will be the second.

Heliophobe: Heliophobe has made many technical contributions to Sega 8-bit emulation including demos and a SMS emulator for the Dreamcast: SMEG. Heliophobe has also provided feedback and suggestions for improving MesaDX, many of which have been implemented in MesaDX.

S8-Dev: All the members of S8-Dev deserve to be thanked, not only for their continuous interest in Sega 8-bit development, but also for perhaps being the only people in the world who might be interested in using an emulator like MesaDX

Quinntesson (Jeff Quinn, my brother, author of the Genesis/SegaCD/32X emulator AGES): His understanding and interest in the more technical aspects of emulation have greatly increased my own understanding of emulation. Our long conversations about all things emulation-related have proved to be invaluable during the (long) development of MesaDX.

1.1 Installing MesaDX

1.2 Associating Files with MesaDX

Also, compiled within the MesaDX executable are several icons that can be used for files of types: *.mdx, *.sms, and *.gg.

2.1 Creating a New System Configuration

The New System Configuration window is broken into two tabbed dialog box sections: the Devices section and the Power-On Configuration section.

The Devices page allows the user to specify which devices they'd like to have installed in the system. A list of all the devices in an AGAMA (Sega Mark 3, Sega Master System, or Game Gear) system is shown under "Installed Devices". For each of these devices the Device ID, Model number and Version number is shown, or the device is marked "Not Installed". By clicking the device mnemonic in this list, the user is then allowed to select which device emulator they would like to have installed in that device slot. The list of available device emulators for a particular device slot is shown in the "Select Device to Install" list. This list shows all the devices that are suitable for a particular device slot. For example, selecting "PROC" in the "Installed Devices" list will allow the user to select which processor emulator they'd like to use in the current system configuration. In this release of MesaDX (and the Kokin DLL), only one processor device emulator is provided, (the A080 model). The information about the provided processor emulators is shown in the "Select Device to Install" list, and since only one emulator is provided and the PROC is a require device, this device emulator will be selected automatically. For other device slots, more than one device emulator may be available. Clicking a device in the "Select Device to Install" list will select that device for installation in the device slot specified. Descriptions for each of the device emulators are also provided when the device is clicked. This description should provide the user with enough information to decide which device emulator they want to use in a particular system configuration. If a device is not required for a particular device slot, then the option "Not Installed" will also appear in the "Select Device to Install" list. Selecting "Not Installed" will leave that device slot empty. If a device requires a memory image file, then the "Data File" and "Back-up RAM File" entry boxes will be enabled. All devices for which the "Data File" box is enabled will require that a data file be specified. Not specifying a file will result in an error. The "Back-up RAM File" is optional. The other tab, the Power-On Configuration tab, allows the user to specify flags that control how the emulator devices power-on. You will notice that some of the power-on configuration flags are disabled and that the Suspended flag is permanently checked. The current version of MesaDX does not support AGAMA Monitor Mode or GG Mode, so these flags are disabled. Also, MesaDX currently requires that the emulator start in the suspended state so that various debug features can be initialized, which is why the Suspended flag is checked. It is possible that future versions of MesaDX will allow the user to select whether or not the emulator powers-on in the suspended state. Currently, though, the user is permitted to adjust the settings of the other power-on configuration options: the machine region, clock frequency, the bus type, and the boot device.

The Export Region flag is used to indicate the system's region setting. When the flag is unchecked, the system is a native Japanese NTSC system. When the flag is checked, the system is an export (U.S. NTSC) system. (European PAL systems are not yet supported in MesaDX.) The Export Region flag is checked by default in MesaDX Version 0.04, (representing the personal biases of the emulator author).

The 50 Hz flag is used to select whether the system VDP should use a 60 Hz or 50 Hz clock. 60 Hz clocks are used by NTSC systems. 50 HZ are used by PAL systems.

The SMS1 Bus flag is used to indicate the behavior of the system's processor bus. When the flag is checked, the system uses a SMS1-type bus. A SMS1 bus retains the last data value driven on the bus. In the case of a bus transaction where no devices respond, the data returned is the last data value that appeared on the bus. Usually, this data value is the last byte of the most-recently fetched instruction. If the flag is unchecked, the system uses a SMS2/GG-type bus. This bus will always return a $FF if no data is driven on the bus by a responding device.

The final option, the Boot Device menu, allows the user to specify which memory device is enabled (mapped into the Z80 address space) at power-on. The default is the Boot ROM, which represents the system's internal ROM or "BIOS". (BIOS is technically the wrong term since BIOS is an acronym for Basic Input/Output Service which doesn't really exist in the Sega Mark III Architecture. For this reason, all MesaDX documentation will refer to the built-in system ROM as Boot ROM, or BROM.)

Along with the Boot Device option comes a Lock Boot Device flag. This flag will prevent the boot device from being mapped out of addressable memory via writes to port $3E, permanently locking the Boot Device into addressable memory. Once the memory devices have been configured, the Power On button should be click to being the emulation session. If a Power On problem occurs it is likely a result of a badly configured system. In general, the steps required to successfully create a system configuration are:

• Select the machine region by checking or unchecking the "Export Region" box
• Select the desired boot device from the "Boot Device" drop-down menu, making sure that the boot device is marked to be installed.
• Lock the boot device, unless a Boot ROM is being used that can detect which memory devices are installed and can be enabled.
• Make sure an emulator device is installed in the boot device slot.
• Select a data (ROM) file for each installed memory device
• (Optionally) select a data (back-up RAM) file for the Cartridge (EXT0) device

Once the system is powered-on, the system configuration can be saved. Select the Save or Save As... options from the File menu in the main MesaDX application window to save the system configuration.

2.2 (Quick Start) Loading ROM Images

To quickly load a ROM image as a cartridge, simply select Load ROM Image... from the File menu in the main MesaDX application window (or use the Ctrl-I hot-key combination). The New System Configuration dialog box will open, with the system pre-configured and ready for power-on. The user can select one of 6 different types of pre-configured system configurations in the "System Type" drop-down box. These include:

The default configuration is the first one, SMS1 Export NTSC (American). Selecting OK will power-on the system. However, if the user desires to view or modify the default configuration settings before power-on, then check the Show System Configuration box before clicking OK. Doing so will open the standard System Configuration dialog box when the user does click OK. All the devices will already be configured as appropriate based on the system configuration they chose. The user can now modify the system configuration as desired. Clicking OK here will then power on the system.

2.3 Viewing the Current System Configuration

The System Configuration view contains the Power-On Configuration settings as well as a list of all the installed emulator devices. Along with the device mnemonic, each installed device has its Device ID, Model and Version numbers listed. These identifiers are not that important in this version of MesaDX, but they will be critical once AGAMA Monitor Mode is supported. Devices not currently installed in the emulation system are labelled as Not Installed.

For more information about each device, select a device mnemonic in the device list (even for devices not installed) and click the Details... button. A window showing the device mnemonic, ID, model and version numbers will open. The window will also contain a short description of the device. For memory devices, the data files installed as the memory contents will also be shown.

2.4 Power-On Self Test (POST)

3.1 Resuming and Suspending Emulation

3.2 Control Pad 1

Please note that in order to use these keys for controller 1, the Primary Video Output view must be the active window. (The Primary Video Output view opens automatically when a system configuration is loaded.) If another view is active, any keystrokes will be directed to that view (notably the arrow keys which are used to scroll certain views).

Future versions of MesaDX will support peripheral port 2 and other controller types.

3.3 Shutdown

When the emulator enters Shutdown, a message box indicating the cause will be displayed. The message box will indicate the responsible device and give the shutdown code. Table 3.3.a below lists the shutdown codes defined in the current release of MesaDX along with a brief description of each code.

Most of the codes above apply to monitor mode, which is disabled in the current version of MesaDX, so Shutdown should occur very infrequently. In fact, the only time Shutdown should occur with the current version of MesaDX is if the SHUTDOWN event handling flag for a specific device event is set, or in other words, the user requested that the system shutdown (instead of suspending) in response to a certain event. Please note that all compulsory events have their SHUTDOWN flags set automatically, so if a compuslory event triggers and no other event handling mechanism is specified the system will shutdown.

4.1 Instruction Unassembly View

Each unassembled instruction is one row in the view. The information for each instruction is arranged in columns. The left-most column contains the instruction's address in hexadecimal. The next column is the instruction object code, also in hexadecimal. Finally, the last column is the instruction mnemonic and operands. All immediate operands are displayed in hexadecimal.

The instruction pointed to by the current PC is highlighted in a gray box. This instruction is the next instruction to be executed. For some types of instructions a fourth column showing additional information will be displayed. For memory reference instructions, the current data in memory at the reference address will be shown. For jump or branch instructions the current and target PC will be shown. The forth column is only displayed for the current instruction.

The Instruction Unassembly view also includes a toolbar to ease navigation through the unassembly listing.

Type a memory address in the "Scroll to" box (and press 'Enter') to have the view scroll directly to nearest instruction on or before that address. Pressing 'Escape' will cancel the "Scroll to" operation.

Check the "Track PC" box to always keep the current instruction in view. (If the current instruction is not on a recognized instruction boundary, the view will jump to an address near the current instruction. Use the "Expand Listing" option to make all the instructions visible.)

Check the "Expand Listing" box to show the unassembly for every byte in memory. Instructions in black are those instructions that line on instruction boundaries based on unassembly starting from address $0000 in memory. Instructions printed in gray are instructions that do not lie on instruction boundaries based on unassembly starting from address $0000 in memory. (See the Technical Note above for more information about instruction boundaries.)

4.2 Processor (PROC) Registers View

The Processor (PROC) Registers view can also be used to edit the values in registers or flags.

Registers can be edited by typing a new value into the register edit box and pressing 'Enter'. To cancel an edit, press 'Escape' instead. The Tab key can be used to cycle through the registers for editing.

The flags can be edited two ways. The first is to simply edit the value in the "AF" register as described above. This method requires that you know which bits correspond to which flags. The other way is to set the flag bits directly by clicking on the radio button for the desired settings in the right hand side of the register view. Note that the Parity and Overflow flag are really the same flag bit; setting (or reseting) one will like-wise set (or reset) the other.

Whenever a register or flag is changed during execution, the change is highlighted in red text. These highlights can be used to quickly determine when a register value changes. If a register's value didn't change during execution, the value will be displayed in the standard black text. Note that when executing a group of instructions using the Resume command, any changes to register values are highlighted, not just the changes made during the execution of the last instruction in the group.

4.3 Video Display Processor (VDP) Registers View

The Video Display Processor (VDP) Registers view can also be used to edit the values in the VDP or Palette registers.

Registers can be edited by typing a new value into the register edit box and pressing 'Enter'. To cancel an edit, press 'Escape' instead. The Tab key can be used to cycle through the registers for editing.

Like the Processor (PROC) Register view, changes in a register's value during execution are highlighted in red text. If a register's value didn't change during execution, the value will be displayed in the standard black text. Note that when executing a group of instructions using Resume command, any changes to register values are highlighted, not just the changes made during the execution of the last instruction in the group.

4.4 Programmable Sound Generator (PSG) Registers View

The Programmable Sound Generator (PSG) Registers view can also be used to edit the values in registers or noise channel settings.

Registers can be edited by typing a new value into the register edit box and pressing 'Enter'. To cancel an edit, press 'Escape' instead. The Tab key can be used to cycle through the registers for editing.

The noise channel configuration can be adjusted in two ways. The first is to simply edit the value the noise channel control register as described above. This method requires that you know which bits correspond to which settings. The other way is to set the control bits directly by clicking on the radio buttons for the desired settings in the right hand side of the register view.

Whenever a register or flag is changed during execution, the change is highlighted in red text. These highlights can be used to quickly determine when a register value changes. If a register's value didn't change during execution, the value will be displayed in the standard black text. Note that when executing a group of instructions using the Resume command, any changes to register values are highlighted, not just the changes made during the execution of the last instruction in the group.

4.5 AGAMA Extension Registers (AXR) Views

The AXRs in each of the views described below can be edited by typing a new value into the register edit box and pressing 'Enter'. To cancel an edit, press 'Escape' instead. The Tab key can be used to cycle through the registers for editing.

Whenever a register is changed during execution, the change is highlighted in red text. These highlights can be used to quickly determine when a register value changes. If a register's value didn't change during execution, the value will be displayed in the standard black text. Note that when executing a group of instructions using the Resume command, any changes to register values are highlighted, not just the changes made during the execution of the last instruction in the group.

4.6 Processor (PROC) Memory View

To edit the memory contents, simply double-click on the byte or word that should be changed. An edit box will open allowing the user to enter a new value. Press the "Enter" key to commit the result. "ESC" will cancel the edit. The Processor (PROC) Memory view also includes a toolbar that allows some customization of the display.

Type a memory address in the "scroll to" box (and press 'Enter') to have the view scroll directly to a memory address. Pressing 'Escape' will cancel the "Scroll to" operation.

Chose between "Byte Width" or "Word Width" to select how the data should be displayed.

Check the "Display ASCII" box to show the ASCII characters for each byte of memory. Unprintable characters are shown as a period (.).

4.7 Video Display Processor (VDP) Memory View

To edit the memory contents, simply double-click on the byte that should be changed. An edit box will open allowing the user to enter a new value. Press the "Enter" key to commit the result. "ESC" will cancel the edit. The Processor (PROC) Memory view also includes a toolbar that allows some customization of the display.

Type a memory address in the "Scroll to" box (and press 'Enter') to have the view scroll directly to a memory address. Pressing 'Escape' will cancel the "Scroll to" operation.

4.8 Primary Video Output View

4.9 Tiles/Palette View

The Tiles/Palette view also includes a toolbar that allows some customization of the display.

Check the "Double Size (Magnify 2x)" box to double the size of the view.

If the VDP is in Mode4, checking the "Use Sprite Palette" box will instruct the VDP to render the tiles using the sprite palette (last 16 palette entries) instead of using the normal first 16 palette entries.

If the VDP is in Graphics2, then checking the "Use Sprite Palette" box will instruct the VDP to render the sprite patterns and the fixed Graphics2 palette. Unchecking the option will instruct the VDP to simply render the pattern table.

Note that the affect of checking (or unchecking) the "Use Sprite Palette" box will only be seen while the emulator is running (resumed) since the VDP renders this screen only while it is running. If the emulator is suspended when the box is checked or unchecked, the update won't occur until the next time the emulator resumes execution.

4.10 Breakpoints View

To add a breakpoint, click the Add button in the Breakpoint view's toolbar. An Add Breakpoint dialog box will open. The current version of MesaDX supports the following breakpoint types:

• PROC Memory Execute
• PROC Memory Write
• PROC Memory Read
• PROC Port Out
• PROC Port In
• PROC Register Write
• PROC Register Read
• VDP Memory Write
• VDP Memory Read
• VDP Register Write
• VDP Palette Write
• PSG Register Write

In the Add Breakpoint dialog box, select the type of breakpoint desired, and then define the breakpoint location. If the location is a memory or port address, type the address in the Memory/Port Address edit box and type 'Enter' to commit the address ('Escape will discard the address). Otherwise, use the drop down boxes for the appropriate breakpoint type to select the breakpoint location. For the PSG, see Table 4.10.a for a list of the mnemonics used to refer to the different PSG registers. The register mnemonics for the other devices are self explanatory.

Once the breakpoint type and location have been selected, click "OK" to add the breakpoint. The new breakpoint will appear in the Breakpoints view. The type and location of the breakpoint will be shown and the breakpoint will be enabled.

Once a breakpoint is added it can be removed or disabled.

Removing a breakpoint deletes it from the list. Once a breakpoint is removed it has to be added again using the Add button and the breakpoint type and location information will have to be re-entered. To remove a breakpoint, select the breakpoint from the list by clicking in the Type column in the row corresponding to the desired breakpoint. The breakpoint should be highlighted. Now, click the Remove button in the Breakpoints view toolbar. The breakpoint will be removed from the list and will no longer trigger.

However, if a breakpoint only needs to be temporarily removed, it is better to simply disable it. To disable a breakpoint, select the breakpoint from the list by clicking in the Type column in the row corresponding to the desired breakpoint. Now, the Enabled check box can be clicked to disable the breakpoint. The breakpoint information will remain in the breakpoints list, but the breakpoint will no longer trigger. To re-enable the breakpoint simply select the desired breakpoint and again and check the Enabled box in the toolbar. Enabling and disabling a breakpoint is a convenient way control breakpoint behavior without the need to keep re-entering breakpoint information.

To remove all breakpoints at once, click the Remove All button in the Breakpoints view toolbar.

4.11 Debug Console View

5.1: SDSC Debug Console

5.2: Events

The current versions of MesaDX and the Kokin emulator library support two different mechanisms for handling events: SUSPEND and SHUTDOWN. If SUSPEND is specified for an event and the event triggers, the emulator will suspend execution, allowing the user to investigate the exact circumstance and instruction where the event triggered. If SHUTDOWN is specified for an event and the event triggers, the emulator will enter Shutdown mode. Once the emulator is in shutdown the only way to get out is to perform a Power-On (Hard-Reset). The user can still investigate the reasons the system entered shutdown, via the various device AXR views, but generally SUSPEND is preferred since emulation can be resumed from right where it left off. Note, though, that if no event handling mechanism is specified at all for an event and the event triggers, the system will automatically enter Shutdown.

Programming an event cause the system to either suspend or shutdown is accomplished via the device's Event Handling Code Register (EHCR) and EVent Handling Flags Register (EHFR). First, write the 8-bit event code for the desired event into the EHCR (use the device's AXR view for this). Once the write is committed the EHFR will be updated to reflect that event's current handling flags. Now, set either the SUSPEND flag (bit 8) or the SHUTDOWN flag (bit 10), or both. Note, though, that the SHUTDOWN bit is ignored unless no other handling flag is set, so setting both flags is unnecessary. Now, the next time the event triggers the system will either suspend or shutdown. In the case of suspend, though, the way the system resumes depends on the type of event. Event types are discussed next.

There are three kinds of events currently defined in the AGAMA specification: compulsory events, protection events, and breakpoint events. Each of these events behaves slightly differently and affects the way the system resumes.

Compulsory events always trigger. They cannot be silenced (via the COMPATIBLESILENT or MONITORSILENT flags in the EHFR). Generally a compulsory events indicate errors that the system cannot resolve on its own. The user will usually have to manually re-configure some portion of the system to prevent a compulsory event from triggering. An example of a compulsory event is the processor's INVALID_INSTR event that gets triggered whenever the processor encounters an unknown (or unsupported) opcode. Compulsory events have their SHUTDOWN flags set by default, so if no other handling mechanism is specified, the system will simply enter shutdown when a compulsory event triggers.

Protection events are the second kind of event. Protection events are generally used to prohibit certain actions, like data writes. When a protection event triggers it indicates that an illegal action was attempted. The event triggers to allow the user to respond to or investigate the action before any machine state is altered or corrupted. One example of a protection event is in the SRAM device which allows various types of protection to be applied to RAM. Unlike compulsory events, protection events can be silenced. However, the action that triggers the event is still prohibited. For example, if memory writes to RAM are protected, and the event is silenced, a write transaction will still occur, but the SRAM device will simply throw out the write data leaving memory unchanged. Protection events also have their SHUTDOWN flags set by default, so if no other handling mechanism is specified, the system will simply enter shutdown when a protection event triggers.

The third and final type of event is a breakpoint event. Breakpoint events are similar to protection events except that a silenced breakpoint event allows the action to proceed. Furthermore, the silence flags for breakpoint events are automatically set when the event triggers. This allows the user to investigate the cause of the breakpoint but then easily resume execution without having to worry about the breakpoint triggering again. Unlike compulsory and protection events, breakpoint events do not have their SHUTDOWN flags set. If no handling mechanism for a breakpoint event is specified the event is simply ignored.

5.3: Determining Why the Emulator Suspended

B

C

D

E

F

G

H

I

J

K

L

M

N

O

P

Q

R

S

T

U

V

W

X

Y

Z