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:
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.
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.
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.
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.
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.
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) |
CTS / TRxC pin must be switched to normal baud rates.
Communications programs don't configure for ext. clock and see osc. on CTS.
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.
|
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
