The Mirage Monitor Disk

OS-1 User's Manual



Welcome to the wonderful world of "hacking" your own version of the MIRAGE operating system. This disk and manual will enable you to examine and alter the contents of the MIRAGE memory and disks.

While this is a powerful tool that can open new possibilities for the dedicated enthusiast it also requires some skill to use successfully. The purchase of an airplane does not imply that the purchaser has the ability to fly. In the same sense, modification of an operating system requires some understanding of what you are changing. Fortunately, the consequences of failure are relatively painless if you plan ahead, but "crashing the system" is part of the hacker's life, so prepare for that possibility.

If you just want to look around inside the operating system then you have nothing to worry about, but if you plan to change anything, consider the following precautions:

Connecting Up

The MIRAGE Monitor Disk is a version of OS 3.2 that lets you communicate with the computer inside the MIRAGE. In order to communicate successfully, you must connect an ASCII terminal to your MIRAGE. This can either be a "dumb" terminal or a computer running communication (terminal) software.

The MIDI input and output of your MIRAGE provide the connection needed for your terminal. If you have a MIDI interface already connected to your computer's serial port, then you should be able to talk with the MIRAGE directly. (Apple Macintosh user's will need to make a minor modification to use non-MIDI data rates - see Appendix 1) If you have a special MIDI interface card (Apple II, etc.) then you should examine the card documentation to see how to access the card as a serial I/0 device. If you do not have a MIDI interface, you will need to buy or construct one. (see Appendix 1.)

Once you have connected the terminal or computer to the MIRAGE, you must select the desired data rate. Parameter 73 is used to set the Monitor program's baud rate from the table.

PARAMETER 73 = Baud Bate
00 = 300
01 = 600
02 = 1200
03 = 2400
04 = 4800
05 = 31,250 ( MIDI )

Once you have selected a baud rate, you may save it on the monitor disk with the SAVE PARAMETERS command. If all is connected properly and working, you should see the prompt CMD: on your terminal when you press the SAMPLE LOWER key on your MIRAGE. If it does not appear, try pressing the return key on your terminal. If a garbled response is returned, you may have the wrong data rate. If you get no response, check to see that the interface is connected properly.

What is a Monitor?

The disk included with this manual is a modified version of Ensoniq's operating system version 3.2 which contains a "monitor" program. You may use this disk to load and play sound samples just as you would use any other 3.2 disk. This disk doesn't let you sample new sounds, however. It replaces the sampling function with what is called a "monitor" program.

A "monitor" is a fairly simple program that lets a computer user interact with the machine on a fundamental level. It allows you to examine and change the contents of memory and to start the computer at some location.

Your MIRAGE is actually a very specialized kind of computer. It normally spends its time processing key events, MIDI messages, and front panel commands and then sending information to the sound synthesis chip.

At the heart of the MIRAGE is a 6809E micro-computer that does most of the work. This same computer can be harnessed to run a monitor program that lets you examine the MIRAGE OS and then change the way it operates. The monitor is actually running in the MIRAGE and not in the device connected to it. When the monitor program is running, you can't play music on the keyboard or operate the keypad and display. The 6809 is running the monitor instead of the operating system.

You can return to the OS and see the result of your patches (assuming that they didn't cause the OS to crash). By patching and testing back and forth, you can test the results of your modifications as you go.

When you are happy with the result of a patch, you can make the change permanently in the image of the OS that is loaded in from disk when the MIRAGE boots (starts up.) Disk read / write commands let you put your patch directly onto the disk.

Using the Monitor

This disk actually contains three different monitor programs. The first (the el-cheapo instant byte boffer) allows you to change memory from the keypad. Parameters 74 and 75 are set to the MSB and LSB of the memory location you wish to change and parameter 76 contains the value of the selected memory location. You can alter this value with the up / down keys, but beware!! There aren't many locations in the OS that you can just set to any value without causing a major system crash. This keypad trick is primarily useful for tweaking a constant in the OS or code you've already created using the other monitors but it lets you play in real time without having to leave and re-enter the OS or disable the keyboard.

The other two monitor programs interact with a computer terminal or terminal program. A mini-monitor (in the memory space normally used for sampling software) lets you modify memory and display blocks of data. A more complete monitor is loaded in the wavetable memory area. You can move back and forth between these two monitor programs as long as both are present. You initially enter the mini-monitor by pressing either the SAMPLE UPPER or SAMPLE LOWER keys on the keypad.

Splitting the monitor this way has several advantages beyond the need for more code space for the full monitor. You can load sounds into lower wave memory and experiment using the mini-monitor. You can also use the full monitor in lower memory to load in a new operating system or utility which you want to work with. As long as you stay in the full monitor you can work with the new program in System RAM. Of course the path to return to this monitor was lost when you loaded the new OS so you can quit the monitor but can't return to it unless you boot the MONITOR disk again.

Monitor Commands

Both monitors respond to:

C change to other monitor (if present)
D xxxx yyyy Display data from xxxx to yyyy
J xxxx Jump to xxxx and run code
M xxxx Memory modify / change (*see below)
Q Quit (return to OS.)

The full monitor has these additional commands:

B xxxx yyyy Binary dump from xxxx to yyyy
F xxxx yyyy dd Fill xxxx-yyyy with data dd
L Load data (Motorola hex format)
N Load New operating system
P xxxx yyyy Motorola hex dump of xxxx-yyyy
R tt ss Read disk track/sector to buffer
W tt ss Write track/sector from buffer
X xxxx yyyy zzzz Copy block xxxx-yyyy to zzzz-

* The memory command opens location xxxx and displays - xxxx dd_

You may then type new hex data, a non-hex character (to look at next location), ^ to go back a location, or <cr> to exit from M

The table on the previous page shows the monitor's commands. The commands are entered without spaces. The monitor supplies the spacing. Thus displaying memory from 0100 to 01FF would be accomplished by typing D010001FF even though the display will show D 0100 01FF. The command will be executed when the last digit is received. Note that leading zeros are required.

All data must be supplied as two or four hex digits as shown in the command listings. If you decide to bail-out half way into a command, typing a non-hex character when a hex digit is expected will terminate the command. The mini-monitor prompts you for input with CMD: while the full monitor offers:

Mirage Monitor

This way you can tell which monitor you are in.

The C command lets you swap back and forth. It checks to see if the other monitor is still in memory before swapping.

The D command displays memory, 16 locations per line, in both hex and ASCII (if a valid character.) There is no way to break into this command, so if you accidentally type D 0000 FFFF you may have to wait a while.

The J command lets you start the 6809 executing at the designated address. It's a good idea to know what you are doing when you use this, because you won't get back to the monitor again unless your code explicitly returns to the monitor.

The M command is the workhorse of the monitor. It lets you examine and change any byte. Once you have specified an address, you can change contents, examine the next location, step back to the previous location or return to command mode.

The Q command lets you quit the monitor and return to the current operating system to use the keyboard or to try out your modifications.

In the extended monitor, the B command causes a binary dump of the specified block of memory. When the command is received there is a slight delay followed by the transmission of an "@" character, followed by the specified block, sent as 8-bit ASCII.

The F command lets you fill a large block of memory with some value. Of course, filling the memory where your monitor or operating system resides is not a really good idea.

The L command lets you load a program or data block into the MIRAGE from an external computer using the standard Motorola hex format. Blocks start with "S1" followed by the block length, the load address, the block data and finally a checksum. All information consists of hexadecimal data sent as two ASCII hex digits. The load is terminated when an "S9" is received.

The N command causes an operating system to be loaded as if the disk were being booted. Control returns to the monitor after the load takes place. Thus you can load other operating systems and then dump them to an external computer or explore them. Note that unless you load the MONITOR disk back in, there is no mini-monitor to return to (or to let you return to this monitor.)

The P command dumps data from the MIRAGE using the same S-format described under the L command.

The R command lets you read a sector of disk data into a buffer. The track and sector are specified in the command. If the read is successful, the sector data will appear in the buffer at hex 1000-13FF (or 1000-11FF if reading sector 05 which is only 512 bytes long.)

The W command lets you write the sector buffer onto a disk. It is up to you to write to the correct sector. The command does request that you verify the track/sector number before it lets you write on the disk.

The X command lets you copy blocks of data from one location to another. The command "X 0100 01FF 0200" will cause the data at 0100-01FF to be repeated at 0200-02FF. Of course copying to overlapping RAM such as "X 0100 01FF 0101" will fill the contents of 0100-0200 with the data at 0100 unless you copy to another area and then back to 0101.

Let's examine a simple example of how we can use the monitor program to modify OS 3.2 slightly. Those of you who have been following the Between the Keys column in the Transoniq Hacker may recall that issue #17 discussed alteration of the MIRAGE temperament. If you didn't see that issue, the tuning of notes within an octave is determined by a twelve entry table that appears at 8BF1 hex in OS 3.2. This table has the following entries for C-B: 00 15 2B 40 55 6B 80 95 AB C0 D5 EB in locations 8BF1 to 8BFC. If you change the values around in this table, you can change the arrangement of the keys in an octave. If you put FF EB D5 C0 AB 95 80 6B 55 40 2B 15 into this table, the keyboard will play in a somewhat backward manner.

You could do this by setting parameter 74 to 8B, parameter 75 to F1, and 76 to FF and then stepping parameters 75 and 76 until all the data is entered. This is a slow and painful process.

Here is a better way. With your computer terminal connected, press SAMPLE UPPER and observe the CMD: prompt on your terminal (if you have problems, see CONNECTING UP). Now type M 8BF1 and the display will show - 8BF1 00_ . Now type FF and the monitor will enter this value into memory and display - 8BF2_. Type EB D5, etc. until you have entered 15. Then press <return> to get out of the M command and Q to get back to the keyboard OS to try it out.

Modifying Mirage Disks

If you followed the example at the end of the previous section then you have a good idea of how to modify memory locations within the Operating System. Your keyboard is now playing upside down - at least until you turn off the power. Patches made in OS RAM are fine for testing out ideas, but if you get something you really like, it would be nice to be able to make these changes permanently on one of your disks.

Let's try saving the inverted keyboard on a disk. Either get an old 3.2 disk or make a copy of a disk with the CHAMELEON utility or the ENSONIQ formatter. Don't use a disk that you care about, and especially don't use your MONITOR disk. EVER!!

Remember, the pitch table was at 8BF1-8BFC hex. If you look at the Load Address Map, you will see that the part of the OS that loads into memory from 8800 to 8BFF is on track 00 sector 02 of the disk.

Get into the full monitor by first pressing SAMPLE UPPER and then using the C command to switch monitors, giving you the prompt:

Mirage Monitor

Now type R 00 02 to read the sector into the buffer.

The OS code that would normally have loaded into system memory at 8800-8BFF has now been loaded into the disk buffer in wavetable memory at 1000-13FF. The pitch table that we are looking for is now at 13F1-13FC.

If you don't understand how we arrived at this magic number, think about the way that the disk loader works. The 1024 bytes of information stored on this sector is dumped into memory starting at the beginning of the buffer. In a normal OS load, the pointer would be at 8800 where it was left by the previous sector load. Our monitor sets the pointer to 1000 before loading it.

You can now use the memory change command to enter the inverted scale as before. This time type M l3F1 instead, so that you will change the contents of the disk buffer. Enter the table as before by typing FF EB D5 BE C0 AB 95 80 6B 55 40 2B 15 and then <return>.

You have changed the table in the disk buffer. Now you can write the changes onto the disk. Remove the disk from the drive and slide the plastic write tab away from the edge of the disk so it covers the write-protect hole. Put the disk back in the drive and type W 00 02. The monitor will ask you to verify that you plan to write on track 00 sector 02 by asking you to type "Y". When you have responded, it will write the contents of the sector buffer back onto the disk.

You now have modified an OS 3.2 disk. Slide the write-tab back to the open (protected) position. If you power down your MIRAGE and then boot it with this new disk, it will immediately provide you with an inverted keyboard. Not, perhaps, too useful a feature, but you now understand how the monitor disk commands work, and you also know how to change the pitch table back (I hope!)

Note that you can copy a disk this way - if you have the patience to swap disks 960 times. Somewhat more useful is the ability to copy a sector to another location on the disk. Of course, you need to know what your doing or you'll be in big trouble. You also need to be careful not to do this by accident, either.

The next two pages are maps of the entire disk, with both short and long sequences. The operating system is on all of track 00 and 01 and then on sector 05 of tracks 02 through 0A. It loads from 8000-BFFF. Each LOWER sound first loads the wavepointer and loop parameters into 0000-03FF and copies them into the parameter area of the OS. It then loads into bank A of wavetable RAM from 0000-7FFF. Finally, it switches to bank B and loads from 0000-7FFF again. UPPER sounds load into banks C and D of RAM.

Mirage Disk Sector Map

Load Address Map of Mirage Disk

Mirage Hardware Memory Map

0000-7FFF Bank of Wavetable RAM. There are four banks of 32K selected by lines on the Port 8 output of the VIA. This RAM appears to the Q-chip's DMA as two 64K banks.
8000-BFFF Operating system RAM. Where OS is loaded.
C000-DFFF Expansion slot space. Where Input Sampling Filter or Sequencer Expansion RAM appear.
B800-BFFF Where short sequences are loaded.
B800-DFFF Where long sequences are loaded.
E100 MIDI interface UART control/status
E101 MIDI interface UART data
E200-E20F Versatile Interface Adapter (VIA)
E200 VIA data reg. B (bank sel./disk sel.)
E201 VIA data reg. A (front panel keypad/display)
E202 VIA data direction reg. B
E203 VIA data direction reg. A
E204 VIA timer 1 counter LSB
E205 VIA timer 1 counter MSB
E206 VIA timer 1 LSB latch
E207 VIA timer 1 MSB latch
E208 VIA timer 2 counter LSB
E209 VIA timer 2 counter MSB
E20A VIA shift register
E20B VIA auxiliary control reg.
E20C VIA peripheral control reg.
E20D via interrupt status register
E20E VIA interrupt enable reg.
E20F VIA data reg. A - no handshake
E408-E41F VFC parameters for Osc. 1-8
E408-E40F Filter cut-off frequency
E410-E417 Filter Resonance
E418-E41F Multiplexer address pre-set (no output)
E800-E803 Floppy disk controller
EC00-ECEF Ensoniq Q-chip registers
F000-FFFF Bootstrap ROM (contains disk I/O, pitch and controller parameter tables and Q-chip drivers)

Ensoniq Mirage Overall Block Diagram

03/26/86 R.H. Lord

APPENDIX I - MIDI Connections

Macintosh MIDI Interface Modifications

CTS / TRxC pin must be switched to normal baud rates.
Communications programs don't configure for ext. clock and see osc. on CTS.

Proper Design of RS-232 / MIDI Interface

Improper quick & dirty Design

APPENDIX II - Useful Monitor Entry Points

The following addresses may be useful to you in constructing additional commands for the monitor program.

0400 CMD Monitor entry point - use for cmd. returns
043A GETRNG Input 8 hex dig. as address range into y and x
0445 GETAD Input 4 hex dig. address in x reg.
0456 GETHEX Input 2 hex dig. to A reg. (set V if non-hex)
0484 INCHE Input character, make upper case, echo out
0498 INCH Input character from UART (8-bit)
04A2 OUT4HS Output 4 hex dig. and space at x++
04A4 OUT2HS Out 2 hex dig. and space at x+
04A6 OUTS Output space (ASCII $20)
04AA OUTHEX Output 2 hex digits (byte) at x+
04AC OUTHX Output 2 hex dig. from "a" reg.
04C4 OUTSTA Out char. string at x terminated by 00
04C9 OUTCA Output CRLF ($OD, $0A)
04CF OUT Output character in "a" reg.


6809 Data

6809 Data cont.

6809 Data cont.

Mirage Monitor Disk OS-1 and OS Mods ©1987 R.H. Lord
OS 3.2 is ©1986 Ensoniq
Ensoniq™ and Mirage™ are registered trademarks of Ensoniq Corporation