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
