Driver:Apollo: Difference between revisions

From MAMEDEV Wiki
No edit summary
(11 intermediate revisions by one other user not shown)
Line 1: Line 1:
'''MAME Apollo Howto'''


==Running the Emulation==
'''Notes''':
* This manual applies to MAME 0.186 and later
* This manual only covers MAME features essential for running the Apollo emulation.
* See the [http://docs.mamedev.org/index.html MAME Documentation] for a full description of all MAME features.


-How to run the Apollo emulation-
 
__TOC__
 
== Running the Emulation ==
 
=== How to run the Apollo emulation ===


MAME will emulate one of the following Apollo workstations and servers:
MAME will emulate one of the following Apollo workstations and servers:


{|
{| class="wikitable"
|MAME System||Apollo||Display
! MAME System  !! Apollo  !! Display
|-
| dn3500        || DN3500  || Color or 15" Monochrome
|-
| dn3500_19i    || DN3500  || 19" Monochrome
|-
| dsp3500      || DSP3500 || Terminal
|-
| dn3000        || DN3000  || Color or 15" Monochrome
|-
| dn3000_19i    || DN3000  || 19" Monochrome
|-
| dsp3000      || DSP3000 || Terminal
|-
| dn5500        || DN5500  || Color or 15" Monochrome
|-
| dn5500_19i    || DN5500  || 19" Monochrome
|-
| dsp5500      || DSP5500 || Terminal
|-
|}
 
To run an emulation start MAME with one system and additional command line options, e.g.
 
$ ./mame64 dn3500 -window -nomax -mouse -log -disk1 <pathname>.awd -flop <pathname>.afd
 
Useful command line options:
 
{| class="wikitable"
! Option                !! Description
|-
| -window              || run MAME in a window (i.e. not in full screen mode)
|-
| -nomax                || don't set the MAME window initially to the maximum supported size
|-
| -mouse                || grab mouse input (for acceptable mouse emulation; use this option only for the DN3x00 emulation)
|-
| -sound none          || turn off the keyboard beeper
|-
| -log                  || error messages will be logged in error.log
|-
| -disk1 <pathname>.awd || specify a Winchester disk image file
|-
| -disk2 <pathname>.awd || specify a second Winchester disk image file (i.e. w0:1)
|-
| -flop <pathname>.afd  || specify a floppy disk image file
|-
| -ctape <pathname>.act || specify a cartridge tape image file
|-
| -ni <pathname>.ani    || specify a node ID image file
|-
|}
 
Notes:
* The boot ROMs must have been setup, before the Apollo emulation may be run ([[#How to setup the boot ROMs|see below]]).
* A disk image file with  Domain/OS is essential for running the Apollo emulation ([[#How to install Domain/OS SR10.4 in a new disk image file|see below]])
* Make sure you understand how to ungrab the mouse before running MAME with option mouse ([[#How to ungrab the mouse|see below]])
* The DN3x00 emulation may be run without option -mouse (i.e. without grabbing the mouse), if you are willing to move the cursor with the arrow keys of the keyboard (works quite good, once you get used to it)
* DN3x00 is being used as shorthand for DN3000 or DN3500 or DN5500; same for DSP3x00
 
see also [http://docs.mamedev.org/commandline/index.html MAME Commandline Usage and OS-Specific Configuration]
 
=== How to run config ===
 
The Apollo emulation should be configured for proper operation.
 
To run config
* switch the Apollo emulation into Service Mode ([[#Service Mode/Normal Mode|see below]]) and reset or restart the emulation
* press Return (in the MAME window or in the Terminal window) until the MD version and prompt (">") are shown
* enter '''ex config''' and wait
* the current configuration will be shown; expect something similar to:
 
Config - Offline(7), revision 10.4, December 2, 1991  7:29:50 pm
        Current configuration
Memory:
        Board #  Size in megabytes
            1              4
            2              4
            3              4
            4              4
        Total configured memory: 16 megabytes
Node-id:      12345
Display type: DISP8C -- 1024x800x8 color display   
Peripheral devices:
        FPU5 -- MC68881/MC68882
        FLP7 -- Floppy disk
        WINCHESTER CONTROLLER TYPE --  SMS/Omti                     
          WIN7 -- Winchester (controller 0  unit 0):  380MB--FA               
        CTAPE7 -- Cartridge Tape (QIC-II)
        ETH802.3_AT -- 802.3 Network Controller-AT (unit 0)
        Principal network: ETH802.3_AT -- 802.3 Network Controller-AT (unit 0)
Would you like to reconfigure this node (Y/N)?
 
* enter '''n''' to quit or '''y''' to modify the configuration; the configuration will be saved in the NVRAM of the emulation.
 
=== How to run calendar ===
 
If the Winchester disk image hasn't been used for some time (14 days), it may be necessary to run calendar.
 
To run calendar
* switch the Apollo emulation into Service Mode ([[#Service Mode/Normal Mode|see below]]) and reset or restart the emulation
* press Return (in the MAME window or in the Terminal window) until the MD version and prompt (">") are shown
* enter '''ex calendar''' and wait
* enter '''w''' to select the Winchester disk
* check and eventually change the timezone
* check and eventually change date and time
* confirm questions as appropriate and wait for the MD prompt to reappear
 
=== How to run salvol ===
 
If Domain/OS has crashed or has been aborted, it may be necessary to salvage the disk.
 
To run salvol
* switch the Apollo emulation into Service Mode ([[#Service Mode/Normal Mode|see below]]) and reset or restart the emulation
* press Return (in the MAME window or in the Terminal window) until the MD version and prompt (">") are shown
* enter '''ex salvol''' and wait
* enter '''w''' to select the Winchester disk
* enter return to start salvaging of logical volume 1 with default options
* confirm ''Anything more to do?'' with '''n''' and wait for the MD prompt to reappear
 
=== How to run dex ===
 
The Diagnostic EXecutive (dex) is a comprehensive diagnostic control system for diagnostic products
in the offline environment.
 
To run dex
* switch the Apollo emulation into Service Mode and set all other Driver Configuration values to Off ([[#Apollo Machine Configuration|see below]])
* reset or restart the emulation
* press Return until the MD version and prompt (">") are shown (in the MAME window or in the Terminal window)
* enter '''ex dex''' and wait
* enter '''help''' for more info
* enter '''auto''' for full test (confirm errors with '''C''' or '''N'''); expect the following tests to fail
** mem.dex Test 140: Parity Checker Test (emulation won't allow more the 40 parity error tests)
** cpu.dex Test 302: SIO keyboard port test (behavior is ok for DSP3x00, run test with option -nokb)
** disp.dex Test 20: Video SYNC Gen. Add. Test (not emulated for Monochrome graphics)
** win.dex Test 103: Format Bad Track Test (not emulated)
** win.dex Test 104: Assign Alternate Track Test may fail (not implemented)
** fpu.dex Test 2: General Instruction (many FPU operations and operands are not yet emulated)
 
=== How to run Domain/OS in the DN3x00 emulation ===
 
* start the MAME emulation for dn3500 or dn3000 (resp.  dn3500_19i or dn3000_19i) with option -mouse
* make sure you understand how to ungrab the mouse ([[#How to ungrab the mouse|see below]])
* if Apollo emulation has been set to Normal Mode Domain/OS will boot without user intervention
* if Apollo emulation has been set to Service Mode perform the following steps
** in the MAME window press Return until the MD version and prompt (">") are shown
** enter '''ex aegis''' (or '''ex domain_os''') and wait until the bootshell prompt ")" appears
** enter '''go''' to load as in normal mode (or '''help''' for more info)
* wait until the DM has been started and the DM screen is shown
* login as user '''user''' with empty password (or '''-apollo-''' if the registry already has been created)
* wait for the first pad to appear and then enter shell commands ...
* [[#Keyboard Mapping|see below]] for the mapping of the Apollo keyboard keys to the PC keyboard function keys
* to logout press key [F1] to move the cursor into the command window and enter '''lo'''
* to shutdown Domain/OS press key [F1] to move the cursor into the command window and enter '''shut'''
 
=== How to run Domain/OS in the DSP3x00 emulation ===
 
* start the MAME emulation for dsp3500 or dsp3000 (w/o option -mouse)
* if Apollo emulation has been set to Normal Mode Domain/OS will boot without user intervention
* if Apollo emulation has been set to Service Mode perform the following steps
** in the MAME window or in the Terminal window press Return until the MD version and prompt (">") are shown
** enter '''ex aegis''' (or  '''ex domain_os''') and wait until the bootshell prompt ")" appears
** enter '''go''' to load as in normal mode (or '''help''' for more info)
* wait until SPM and MBX Helper have been started
* enter '''sh''' to start the login shell (or '''help''' for more info)
* login as user '''user''' with empty password (or '''-apollo-''' if the registry already has been created)
* wait for the shell prompt "$" and then enter shell commands ...
* enter '''exit''' as shell command to logout
* enter '''shut''' to shutdown Domain/OS
 
== MAME Basics ==
 
=== How to stop the emulation ===
 
* in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
* press [Esc] to stop the emulation
see also [http://docs.mamedev.org/usingmame/defaultkeys.html Default Keys]
 
=== How to reset the emulation ===
 
* in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
* press [F3] to reset the emulation
see also [http://docs.mamedev.org/usingmame/defaultkeys.html Default Keys]
 
=== How to restart the emulation ===
 
* stop the emulation (see before) and restart the emulation from the command line, or
* in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
* press [Shift] and [F3] to restart the emulation
 
see also [http://docs.mamedev.org/usingmame/defaultkeys.html Default Keys]
 
=== How to suspend the emulation ===
 
* in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
* press button [P] to pause the emulation
* press button [P] once again to resume the emulation
* eventually delete the extra character p in the emulation
* eventually press [ScrLock] to switch your keyboard back to fully emulated keyboard mode
 
see also [http://docs.mamedev.org/usingmame/defaultkeys.html Default Keys]
 
=== How to ungrab the mouse ===
 
If the emulation has been started with option -mouse, the mouse will be grabbed as long as the emulation is running.
 
Suspend the emulation ([[#How to suspend the emulation|see before]]) to ungrab the mouse.
The mouse will be grabbed again, if the emulation is resumed ([[#How to suspend the emulation|see before]]).
 
=== How to grab the mouse at runtime ===
 
In fullscreen mode the mouse will always be grabbed.
This may be used to toggle at runtime between
* window mode with ungrabbed mouse and
* fullscreen mode with grabbed mouse
 
Start the Apollo emulation for DN3x00 with options -window -nomax -nomouse -nounevenstretch
and (while MAME is running) press [Alt][Return] to toggle between both modes.
 
== Configuration ==
 
=== MAME Options ===
 
The following options in mame.ini or as command line option are useful for running the Apollo emulation:
 
{| class="wikitable"
! Option        !! mame.ini !! command line
|-
| unevenstretch || 0        || -nounevenstretch
|-
| window        || 1        || -window
|-
| maximize      || 0        || -nomaximize
|-
| sound        || none    || -sound none
|-
| skip_gameinfo || 1        || -skip_gameinfo
|-
|}
 
If file mame.ini does not yet exist, run the following command
to create a new mame.ini file with default configuration settings:
 
./mame64 -createconfig
 
refer to [http://docs.mamedev.org/commandline/sdlconfig.html SDL-Specific Commandline Options]
 
=== Service Mode/Normal Mode ===
 
To switch the Apollo emulation between Service Mode and Normal Mode
* open the Apollo Machine Configuration menu ([[#Apollo Machine Configuration|see below]])
* select and change the value of entry Service/Normal
* close the menus and reset the emulation ([[#How to reset the emulation|see before]])
 
=== Apollo Machine Configuration ===
 
To check or modify the Apollo Machine Configuration
* start the emulation for DN3500, DN3000, DSP3500 or DSP3000
* in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
* press [Tab] to enter the Internal User Interface
* press [Cursor Down] to select ''Machine Configuration'' and press [Return] to open the Machine Configuration menu
* the Apollo Machine Configuration menu has the following entries
 
{| class="wikitable"
! Entry            !! Description
|-
| Service/Normal  || select Service mode or Normal mode
|-
| Graphics Controller || select 8-Plane Color, 4-Plane Color or 15" Monochrome graphics controller <br /> (for dn3x00 only, will be ignored for dn3x0_19i and dsp3x00)
|-
| German Keyboard  || select German Apollo keyboard
|-
| 20 Years Ago ... || set default date in the RTC back by 20 years to omit the Nov 2, 1997 problem <br /> of Domain/OS software releases before SR 10.4.1
|-
| 25 Years Ago ... || set default date in the RTC back by 25 years to omit the  Nov 2, 1997 problem <br /> of Domain/OS software releases before SR 10.4.1
|-
| Node ID from Disk|| set node ID to value from the logical volume label of the first logical disk volume; <br /> without this option either the node ID from command line option -ni <br /> or the default node ID 12345 will be used
|-
| Trap Trace      || trace all Domain/OS SVC traps in the error log file
|-
| FPU Trace        || trace all FPU operations in the error log file
|-
| Disk Trace      || trace disk I/O in the error log file (obsolete)
|-
| Network Trace    || trace network packets in the error log file (obsolete)
|-
|}
 
* press [Cursor Down] or [Cursor Up] to select the proper menu entry
* press [Cursor Right] or [Cursor Left] to select the proper value
* press button [Tab] to close the menu
* press button [F3] to restart the emulation using the new settings
* press [ScrLock] to switch your keyboard back to in full emulation mode
Notes:
* the new Machine Configuration setting won't be used unless the emulation has been reset or restarted
* each system (i.e. DN3500, DN3000, DSP3500 or DSP3000) has its own Machine Configuration settings
* '''Warning''': entering character '''p''' in partial emulation mode will pause (i.e. freeze) the emulation (e.g. for "r cpu")
* see also [http://docs.mamedev.org/usingmame/defaultkeys.html Default Keys]
 
=== Dip Switches ===
 
To check or modify the Apollo Dip Switches
* start the emulation for DN3500, DN3000, DSP3500 or DSP3000
* in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
* press [Tab] to enter the Internal User Interface
* press [Cursor Down] to select ''Dip Switches'' and press [Return] to open the Dip Switches menu
* the following Dip Switches should be shown:
 
{| class="wikitable"
! SMS OMTI 8621 disk controller !! [root:isa1:wdc]
|-
| ESDI I/O base                || 01A0h
|-
| Floppy I/O base              || 03F0h
|-
| BIOS control                  || Disabled
|-
| BIOS base                    || 0C8000h
|-
|}
 
{| class="wikitable"
! Archive Cartridge tape controller SC-499 !! [root:isa2:ctape]
|-
| SC499 I/O base (jumpers A3-A9) || 0200h
|-
| SC499 IRQ (jumpers IRQ2-IRQ7)  || IRQ 5
|-
| SC499 DMA (jumpers DRQ1-DRQ3)  || DRQ 1
|-
|}
 
{| class="wikitable"
! 3COM 3C505 Ethernet Controller !! [root:isa3:3c505]
|-
| 3C505 I/O base (jumpers A3-A9) || 0300h
|-
| 3C505 IRQ                      || IRQ 10
|-
| 3C505 DMA                      || DRQ 6
|-
| ROM control                    || Enabled
|-
| ROM base                      || 80000h
|-
|}
 
* press [Cursor Down] or [Cursor Up] to select a DIP switch
* press [Cursor Right] or [Cursor Left] to change the value
* press [Return] to set an entry back to the default value
* press button [Tab] to close the menu
* press [ScrLock] to switch your keyboard back to in full emulation mode
Notes:
* The default DIP switch settings are apropriate for the Apollo emulation. Don't change them.
 
=== Keyboard Mapping ===
 
The additional special keys of the Apollo keyboard are mapped to the function keys (and some other keys) of the PC keyboard.
 
==== Function Keys ====
 
{| class="wikitable"
!  F1  !!  F2  !!  F3  !!  F4  !! !! F5  !!  F6  !!  F7  !!  F8  !! !!  F9  !! F10  !! F11  !! F12
|-
|-
|dn3500||DN3500||Color or 15“ Monochrome
| SHELL|| CUT  || UNDO || MOVE || || INS  || LINE  || CHAR ||      || ||      || SAVE || ABORT|| HELP
|-
| CMD  || COPY || PASTE|| GROW || || MARK || DEL  || DEL  || AGAIN || || READ || EDIT || EXIT || HOLD
|-
|-
|Bread||Pie||more
|}
|}


MESS System Apollo Display
Set Num Lock to use the Function keys F1 - F9 and F10 = F0 without Apollo mapping.
 
dn3500_19i DN3500 19” Monochrome
==== Other Keys ====
dsp3500 DSP3500 Terminal
 
dn3000 DN3000 Color or 15“ Monochrome
{| class="wikitable"
dn3000_19i DN3000 19” Monochrome
!PC Keyboard  !! Apollo Keyboard
dsp3000 DSP3000 Terminal
|-
dn5500 DN5500 Color or 15“ Monochrome
| Insert      || NEXT WINDOW
dn5500_19i DN5500 19” Monochrome
|-
dsp5500 DSP5500 Terminal
| Delete      || POP
|-
| Right Window || NEXT WINDOW
|-
| Menu        || POP
|-
|}
 
Cursor keys and Pad scroll keys have been mapped to the numeric keypad too.
 
=== How to emulate the German Apollo keyboard ===
 
The Multinational Apollo keyboard has some additional keys, a slightly modified layout and some different key labels.
To emulate the German Apollo keyboard
* use a German PC keyboard at your Linux system
* verify that the file keymaps/km_de_LINUX.map exists (as a copy from the mame source distribution)
* verify and evenutally correct the following two entries in mame.ini:
keymap      0
keymap_file keymaps/km_de_LINUX.map
* in the MAME Apollo emulation set the Apollo Machine Configuration ''German Keyboard'' to ON and restart the emulation ([[#How to restart the emulation|see before]])
* in DM pads use the left ALT key (or Shift/ALT) to select national characters
* Note: the MD and the standalone utilities expect a US keyboard (Y and Z must be swapped, other keys may have to be estimated)
 
Key mapping (German Keyboard):
 
{| class="wikitable"
!colspan="3"|PC Keyboard !!
!colspan="4"|Apollo Keyboard
|-
!Key !! Shift!! Alt !!  !! Key  !! Shift  !! Alt  !! Shift
|-
| 3  || ß    ||    ||  || 3    || @      || 3    || @
|-
| fl  || ?    ||  \  ||  || fl    || ?      || ~    || ?
|-
| +  || *    ||  ~  ||  || +    || *      || +    || *
|-
| ‹  ||      ||    ||  || ¸    || ‹      || }    || ]
|-
| ÷  ||      ||    ||  || ˆ    || ÷      || I    || \
|-
| ƒ  ||      ||    ||  || ‰    || ƒ      || {    || [
|-
| <  ||  >  ||  I  ||  || <    || >      || <    || >
|-
|}
 
Note: in table read I as |
 
=== How to run Domain/OS on a small screen ===
 
The Apollo emulation expects a screen size of 1024x800 pixel (for dn3000 and dn3500) resp. 1280x1024 pixel (for dn3000_19i and dn3500_19i) plus around 100 more pixel vertical to display the keyboard mapping, LEDs and the window manager title line.
 
If your host PC has one of the following screen sizes
* WXGA Screen (1280x800)
* XGA Screen (1024x768)
* SXGA Screen (1280x1024)
it may be preferable to run the emulation in full-screen mode and to select an appropriate view without keyboard mapping and LED display.
 
To run the emulation in fullscreen mode set option window in mame.ini to 0 or run the emulation with option -nowindow.
 
To select the appropriate view from the command line run MAME with option -view, e.g.
 
{| class="wikitable"
! PC screen    !! Size      !! MAME command line
|-
| XGA Screen  || 1024x768  || ./mame64 dn3500 -nowindow -view xga ...
|-
| WXGA Screen  || 1280x800  || ./mame64 dn3500 -nowindow -view wxga ...
|-
| SXGA Screen  || 1280x1024  || ./mame64 dn3500_19i -nowindow -view sxga ...
|-
| SXGA+ Screen || 1400x1050  || ./mame64 dn3500_19i -view sxga ...
|-
|}
 
To configure the appropriate view
* start the emulation for dn3x00 resp. dn3x00_19i
* in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
* press [Tab] to enter the Internal User Interface
* press [Cursor Down] to select ''Video Options'' and press [Return] to open the Video Options menu
* for dn3x00 select WXGA or XGA from the options:
** Apollo (1024x800)
** WXGA Screen (1280x800)
** XGA Screen (1024x768)
* for dn3x00_19i select SXGA from the options:
** Apollo 19" Monochrome
** SXGA Screen (1280x1024)
* press [Return] to select the entry
* press [Tab] to close the menu
* press [ScrLock] to switch your keyboard back to in full emulation mode
* start Domain/OS and check the display
 
== Software Installation ==
 
=== How to setup the boot ROMs ===
 
The boot ROM images for the Apollo emulation reside either in the zip file roms/dn3500.zip or in the directory roms/dn3500).
 
* make directory roms/dn3500
* copy the following files from http://bitsavers.org/bits/Apollo/firmware to roms/dn3500:
** 3500_BOOT_12191_7.bin
** 3000_BOOT_8475_7.bin
** 3000_3C505_010728-00.bin
** 3000_OMTI_8621_102640-B.bin
** 5500_BOOT_A1631-80046_1-30-92.bin
** 2500_BOOT_16182_8.bin
* and create the zip file with
 
$ (cd roms/dn3500 && zip -r ../dn3500.zip *)
 
* or (if no zip file shall be used) convert the file names in roms/dn3500 to lowercase, i.e.
** 3500_boot_12191_7.bin
** 3000_boot_8475_7.bin
** 3000_3c505_010728-00.bin
** 3000_omti_8621_102640-b.bin
** 5500_boot_a1631-80046_1-30-92.bin
** 2500_boot_16182_8.bin
 
=== How to install Domain/OS SR10.4 in a new disk image file ===
 
Note: cartridge tape access is very slow (same as the real cartridge tape), be patient when executing software from cartridge tape
 
* get the installation cartridge tape images for Domain/OS SR10.4 (e.g. from http://bitsavers.org/bits/Apollo/SR10.4)
* gunzip the tape image files (if necessary)
 
$ ls -log /tmp/*.ct
-r--r--r-- 1 53678592 Feb 20  2005 /tmp/019593-001.CRTG_STD_SFW_BOOT_1-REV.A.ct
-r--r--r-- 1 58403328 Feb 20  2005 /tmp/019594-001.CRTG_STD_SFW_1.ct
-r--r--r-- 1 61564928 Feb 20  2005 /tmp/019594-002.CRTG_STD_SFW_2.ct
-r--r--r-- 1 56568320 Feb 20  2005 /tmp/019594-003.CRTG_STD_SFW_3.ct
-r--r--r-- 1 57844224 Feb 20  2005 /tmp/019594-004.CRTG_STD_SFW_4.ct
$
 
* start the emulation with a non-existing disk image file and the boot tape image, e.g.
 
$ rm -f /tmp/dn3500_sr10.4.awd
$ ./mame64 dn3500 -mouse -disk1 /tmp/dn3500_sr10.4.awd -ctape /tmp/019593-001.CRTG_STD_SFW_BOOT_1-REV.A.ct
 
* Note: the mouse will be grabbed; make sure you understand how to ungrab the mouse ([[#How to ungrab the mouse|see before]])
* open the Apollo Machine Configuration window and set option '''25 Years Ago ...''' to '''On''', all other options to '''Off''' and reset or restart the emulation
* run invol from the boot tape image with options
** 7 - initialize physical badspot list,
** 1 - initialize virgin physical volume and
** 8 - create or modify an os paging file.
 
> re
> di c
> ex invol
 
* run calendar from the boot tape image to set the timezone and check date and time on the disk image file
 
> re
> di c
> ex calendar
 
* run domain_os to start the installation from the boot tape image
 
> re
> di c
> ex domain_os
  :
Restore complete.
Apollo Phase II Environment  Revision 10.4 RBAK version  Jan 25, 1992  12:58:22 pm
) go
 
* enter sh to start a login shell (DSP3x00 only), login with name user and empty password and run minst
 
sh
login: user
Password:
$ /install/tools/minst
 
* MINST can be run in either of two modes; select '''Novice''' mode if unsure
* select default for all other questions
* select the appropriate cartridge tape image file, e.g. /tmp/019594-001.CRTG_STD_SFW_1.ct (see [[#How to use multiple cartridge tape images]])
* proceed for all 4 cartridge tape image files
* MINST will ask to select a template; enter '''11''' (i.e. '''large''') to install all
* MINST may ask ''Do you wish to select Domain/OS version 10.4 or quit from minst?''; confirm with '''s''' to install Domain/OS
* if installation is done, enter '''shut''' in the command window to shutdown (resp. CTRL/D and then shut for DSP3500)
* stop the emulation and save a copy of the new disk image file (gzipped image file will be ~70 MB)
* proceed with
** [[#How to create the registry in Domain/OS]]
** [[#How to set the network capabilities]]
** [[#How to start TCP/IP in Domain/OS]]
 
see also
* http://bitsavers.org/pdf/apollo/008860-A03_Installing_DOMAIN_Software_Mar92.pdf
* [http://www.hunkler.com/aegis.htm Apollo Workstations Support and Advice]
* [http://forums.bannister.org/ubbthreads.php?ubb=showflat&Number=94705#Post94705 Apollo Domain/OS bare metal startup guide]
 
=== How to create a new disk image file ===
 
* to create a new 348 MB disk image file start the emulation with a non-existing disk image file
 
$ rm -f /tmp/new_disk.awd
$ ./mame64 dn3500 -disk1 /tmp/new_disk.awd ...
 
* to create a new 156 MB disk image file use the UNIX tool dd and start the emulation
 
$ dd if=/dev/zero of=/tmp/new_disk.awd bs=1056 count=147312
$ ./mame64 dn3500 -disk1 /tmp/new_disk.awd ...
 
* open the Apollo Machine Configuration window and set option '''25 Years Ago ...''' to '''On''', all other options to '''Off''' and reset or restart the emulation
 
* execute invol (from net, disk, ctape or floppy)
** for SR10.2 run options
*** 1 - initialize virgin physical volume (will fail, never mind),
*** 7 - initialize physical badspot list,
*** 9 - add to existing badspot list (don't add any entries),
*** 1 - initialize virgin physical volume (once again, will now succeed) and
*** 8 - create or modify an os paging file.
** for SR10.3 or SR10.4 run options
*** 7 - initialize physical badspot list,
*** 1 - initialize virgin physical volume and
*** 8 - create or modify an os paging file.
 
* quit invol, stop the emulation, verify the size of the new disk file image and eventually save a copy  (gzipped image file will be ~ 400 kB).
 
=== How to use multiple cartridge tape images ===
 
To select a different cartridge tape image while the emulation is running
* if changing the cartridge tape is not requested by software, enter
** "rbak -dev ct -rewind" in Domain/OS or
** "RE" in the MD to deselect the current tape image
* in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
* press [Tab] to enter the Internal User Interface
* select the File Manager and press Return
* select ctape (ct) and press Return
* select the appropriate file and press Return
* close the menu
 
== Administration ==
 
=== How to change the Apollo node ID ===
 
The node ID of the Apollo emulation will be be taken from the logical volume label of the first logical disk volume, if option ''Node ID from Disk'' has been set in the Apollo configuration ([[#Apollo Machine Configuration|see before]]).
Otherwise the node ID will be taken either from the command line option -ni or default to 12345.
 
To change the node ID of the Apollo emulation
- the option ''Node ID from Disk'' must be set in the Apollo configuration
- the node ID of the Apollo disk image must be changed
 
To change the node ID of the Apollo disk image
* start the emulation with a copy of the disk image file
* switch the Apollo emulation into Service Mode and reset or restart the emulation
* press Return (in the MAME window or in the Terminal window) until the MD version and prompt (">") are shown
* enter '''ex chuvol''' and wait
* enter '''w''' to select the disk
* enter the new node ID
* confirm the value to be used as "original" node ID and wait until chuvol is done
* confirm ''Anything more to do?'' with '''n''' and wait for the MD prompt to reappear
* if the registry already has been created([[#How to create the registry in Domain/OS|see below]]), restart the emulation, start Domain/OS and fix the registry
** make sure that rgyd is not running (use ps and kill command, if neccessary)
** start rgyd with the new node ID
 
    $ /etc/server -p /etc/rgyd -restore_master&
 
** remove the old registry
 
    $ /etc/rgy_admin
              Default object: rgy  default host: dds:dn3500
              State: in service  master  replica list is writable
    rgy_admin: lrep -state
              dds:#0.12345    *** not communicating ****     
    (master)  dds:dn3500      state: in service        2012/04/20.09:35:38   
    rgy_admin: delrep dds:#0.12345 -force
    rgy_admin: quit
* stop the emulation and eventually save a copy of the disk image file
* use this disk image file to run the Apollo emulation with the chosen node ID
 
=== How to create the registry in Domain/OS ===
 
After installing Domain/OS SR10
* login as user with empty password and start the local location broker (a.k.a RPC daemon)
 
$ touch /etc/daemons/llbd
 
* reboot, login as user with empty password and start the global location broker (first time)
 
$ /etc/server /etc/ncs/glbd -create -first -family dds -listen dds &
$ touch /etc/daemons/glbd
 
* reboot, login as user with empty password and create the registry
 
$ /install/tools/rgy_create
$ touch /etc/daemons/rgyd
 
* reboot and log-in as root with password -apollo-
 
== Networking ==
 
=== How to set the network capabilities ===
 
To access the the TUN/TAP Ethernet interface of the Linux host, MAME must be either run as root (not recommended) or the network capabilities must be set for MAME.
 
To set the network capabilities for MAME in openSUSE Leap 42.1:
* install Linux package libcap-progs and libpcap1 e.g. with
* set and check the capabilities of ./mame64
 
$ sudo setcap cap_net_raw,cap_net_admin=eip ./mame64
$ sudo getcap ./mame64
mame = cap_net_admin,cap_net_raw+eip
 
* run MAME with option -log and verify that the file error.log does NOT contain the following line
 
... 3c505: apollo_eth_init: Operation not permitted - Ethernet access disabled
 
=== How to use the MAME Network Device ===
 
On a Linux host the MAME Network Device provides TCP/IP networking
between the MAME Apollo emulation and the host PC.
 
To run MAME with Network Device
* set the network capabilities for MAME ([[#How to set the network capabilities|see before]])
* Get taputil.sh either from the latest MAME source distribution or from github.com
wget https://github.com/bji/libmame/blob/master/src/osd/sdl/taputil.sh
chmod 755 taputil.sh
 
* Run taputil.sh as root with option -d to delete or option -c to create the tap/tun device
 
TAP=tap-mess-${UID}-0
IP_ADDR_HOST=192.168.2.99
IP_ADDR=192.168.2.30
sudo -s ./taputil.sh -d $USER
sudo -s ./taputil.sh -c $USER $IP_ADDR $IP_ADDR_HOST -
 
* start the MAME Apollo emulation and execute Domain/OS
* configure and start TCP/IP in Domain/OS ([[#How to start TCP/IP in Domain/OS|see below]])
 
=== How to start TCP/IP in Domain/OS ===
 
Before proceeding see also
* [[#How to set the network capabilities]]
* [[#How to use the MAME Network Device]]
 
Note: The following assumes that linux1 is the hostname of the Linux PC where the emulation is running and linux2 is the hostname of a second Linux PC connected with Ethernet to linux1.
 
* start the Apollo emulation and log in as user root (with password -apollo-)
* check and eventually set or change the node name (e.g. to dn3500)
 
# /etc/lcnode
# /etc/uctnode node_12345
# /etc/ctnode dn3500 12345
# /etc/lcnode
 
* setup to start the TCP daemons
 
# touch /etc/daemons/tcpd
# touch /etc/daemons/inetd
# touch /etc/daemons/syslogd
 
* setup /etc/hosts for your Apollo node dn3500 and the Linux PCs:
 
# cat /etc/hosts
127.0.0.1      localhost
192.168.2.30    dn3500
192.168.2.99    linux1
192.168.2.25    linux2
 
* add the Linux PCs to ~/.rhosts (substitute user ost with your Linux user name):
 
# echo "linux1 root" >>.rhosts
# echo "linux2 root" >>.rhosts
# echo "linux1 ost" >>.rhosts
# echo "linux2 ost" >>.rhosts
# chown root .rhosts
# chmod 600 .rhosts
 
* check that pseudo ttys exit; if not create them:
 
# ls -l /dev/ttyp*
# /etc/mkdev /dev pty
 
* add some pseudo ttys to /etc/ttys
 
# echo "ttyp0 none dumb off secure" >> /etc/ttys
# echo "ttyp1 none dumb off secure" >> /etc/ttys
 
* reboot Domain/OS, log-in as user (with password -apollo-) and check networking
 
$ netstat -i
$ netstat -a
$ /etc/ping linux1 100 5
 
* at the Linux PCs
** login as user root
** eventually install package rsh
** enter the commands (with password -apollo-)
 
$ ping 192.168.2.30
$ rlogin 192.168.2.30 -l root
$ rcp /etc/hosts root@192.168.2.30:/tmp/hosts_from_linux
$ rsh 192.168.2.30 -l root ls -l /tmp/hosts_from_linux
 
=== How to setup Apollo Domain Networking ===
 
The MAME Apollo emulation may be setup to provide full Apollo
Domain services to all Apollo nodes connected to the Ethernet
interface eth0 of the MAME host PC.
 
* Get taputil.sh either from the latest MAME source distribution or from github.com
wget https://github.com/bji/libmame/blob/master/src/osd/sdl/taputil.sh
chmod 755 taputil.sh
 
Append the following lines at the end of taputil.sh
 
# disable ip-forward and proxy_arp
echo 0 > /proc/sys/net/ipv4/ip_forward
echo 0 > /proc/sys/net/ipv4/conf/all/proxy_arp
# duplicate $(TAP) traffic at eth0 and vice versa (i.e. bridge)
socat INTERFACE:$(TAP) INTERFACE:eth0 &
 
Install the Linux package socat
 
Run taputil.sh as root with option -d to delete or option -c to create the tap/tun device
 
TAP=tap-mess-${UID}-0
IP_ADDR_HOST=192.168.2.99
IP_ADDR=192.168.2.30
sudo -s ./taputil.sh -d $USER
sudo -s ./taputil.sh -c $USER $IP_ADDR $IP_ADDR_HOST -
 
Connect the Ethernet cable from the Apollo workstation(s) to
the Ethernet connector of the MAME host PC, set the network
capabilities ([[#How to set the network capabilities|see before]]),
start the MAME Apollo emulation and verify the
Domain Networking operation with the lcnode command:
 
$ /com/lcnode
 
The node ID of this node is 12345.
1 other node responded.
 
Node ID      Boot time          Current time        Entry Directory
12345  1993/05/12 16:25:08  1993/05/12 16:30:34  //dn3500
1AEA5  1993/05/12 16:21:10  1993/05/12 16:30:33  *** node not catalogued ***
$ /com/ctnode -update
$ /com/lvolfs 1AEA5
  # free  # total  % free        node ID  entry directory
    80752    329388      25          1AEA5  //zorro
$
 
Notes:
* a second Linux PC running the MAME Apollo emulation (with a different node ID) maybe used instead of a real Apollo workstation to create a Domain network.
* an HP Apollo 9000 Series 400 running Domain/OS may be used instead of (resp. additional to) Apollo workstations
 
== Creating Image Files on a real Apollo ==
 
=== How to create a floppy disk image ===
 
On a DN3x00 with a floppy disk drive (and ethernet controller):
* invol floppy (and run calendar)
* mount floppy (mtvol f)
* add files and directories as needed
* unmount floppy (dmtvol f)
* copy floppy to a disk image file (e.g. /tmp/floppy.afd) with:
 
$ /bin/cp /dev/dsk/F0d0s1 /tmp/floppy.afd
 
* copy the disk image file (i.e. /tmp/floppy.afd) with rcp to your Linux system
Notes:
* suffix .afd is suggested (for Apollo Floppy Disk)
* /systest/ssr_util/cpflp should work as well, but has not been tested.
* the following command can be used to create a new floppy disk image file on a Unix system:
 
$ dd if=/dev/zero of=/tmp/floppy.afd ibs=16384 count=77
 
=== How to create a cartridge tape image ===
 
On an Apollo DN3x00 with a cartridge tape drive
* read file /systest/ssr_util/cptape.hlp
* insert your (write-protected!) cartridge into the cartridge tape drive
* make sure that you have 60 MB free space
* enter the following command to create a tape image file (e.g. in /tmp/tape.act)
 
$ /systest/ssr_util/cptape -r /tmp/tape.act
 
* copy the tape image file to your Linux system and run MAME with option -ct /tmp/tape.act
 
To create a cartridge tape image using the MAME Apollo emulator, start the emulator with a non-existing tape image file, e.g.
 
$ ./mame64 dn3500 -disk1 <pathname>.awd -ct /tmp/new_tape.act
 
* boot Domain/OS, login as root and run the following commands to save e.g. /sau7 into the tape image file
 
# cpboot /sys -dev ct
# wbak -dev ct -f 1 -sysboot /sau7
# rbak -dev ct -f 1 -index -all
 
* shutdown Domain/OS and save a copy of the cartridge tape image file
Notes:
* suffix .act is suggested (for Apollo Cartridge Tape)
* For older cartridges the tension belt inside the cartridge tends to break or start slipping nowadays - hopefully your cartridge tapes are still readable.

Revision as of 01:45, 8 July 2017

MAME Apollo Howto

Notes:

  • This manual applies to MAME 0.186 and later
  • This manual only covers MAME features essential for running the Apollo emulation.
  • See the MAME Documentation for a full description of all MAME features.


Running the Emulation

How to run the Apollo emulation

MAME will emulate one of the following Apollo workstations and servers:

MAME System Apollo Display
dn3500 DN3500 Color or 15" Monochrome
dn3500_19i DN3500 19" Monochrome
dsp3500 DSP3500 Terminal
dn3000 DN3000 Color or 15" Monochrome
dn3000_19i DN3000 19" Monochrome
dsp3000 DSP3000 Terminal
dn5500 DN5500 Color or 15" Monochrome
dn5500_19i DN5500 19" Monochrome
dsp5500 DSP5500 Terminal

To run an emulation start MAME with one system and additional command line options, e.g.

$ ./mame64 dn3500 -window -nomax -mouse -log -disk1 <pathname>.awd -flop <pathname>.afd

Useful command line options:

Option Description
-window run MAME in a window (i.e. not in full screen mode)
-nomax don't set the MAME window initially to the maximum supported size
-mouse grab mouse input (for acceptable mouse emulation; use this option only for the DN3x00 emulation)
-sound none turn off the keyboard beeper
-log error messages will be logged in error.log
-disk1 <pathname>.awd specify a Winchester disk image file
-disk2 <pathname>.awd specify a second Winchester disk image file (i.e. w0:1)
-flop <pathname>.afd specify a floppy disk image file
-ctape <pathname>.act specify a cartridge tape image file
-ni <pathname>.ani specify a node ID image file

Notes:

  • The boot ROMs must have been setup, before the Apollo emulation may be run (see below).
  • A disk image file with Domain/OS is essential for running the Apollo emulation (see below)
  • Make sure you understand how to ungrab the mouse before running MAME with option mouse (see below)
  • The DN3x00 emulation may be run without option -mouse (i.e. without grabbing the mouse), if you are willing to move the cursor with the arrow keys of the keyboard (works quite good, once you get used to it)
  • DN3x00 is being used as shorthand for DN3000 or DN3500 or DN5500; same for DSP3x00

see also MAME Commandline Usage and OS-Specific Configuration

How to run config

The Apollo emulation should be configured for proper operation.

To run config

  • switch the Apollo emulation into Service Mode (see below) and reset or restart the emulation
  • press Return (in the MAME window or in the Terminal window) until the MD version and prompt (">") are shown
  • enter ex config and wait
  • the current configuration will be shown; expect something similar to:
Config - Offline(7), revision 10.4, December 2, 1991  7:29:50 pm

       Current configuration

Memory:
       Board #  Size in megabytes
            1              4
            2              4
            3              4
            4              4
       Total configured memory: 16 megabytes

Node-id:       12345
Display type: DISP8C -- 1024x800x8 color display    
Peripheral devices: 
       FPU5 -- MC68881/MC68882
       FLP7 -- Floppy disk
       WINCHESTER CONTROLLER TYPE --  SMS/Omti                       
          WIN7 -- Winchester (controller 0  unit 0):  380MB--FA                
       CTAPE7 -- Cartridge Tape (QIC-II)
       ETH802.3_AT -- 802.3 Network Controller-AT (unit 0)

       Principal network: ETH802.3_AT -- 802.3 Network Controller-AT (unit 0)


Would you like to reconfigure this node (Y/N)?
  • enter n to quit or y to modify the configuration; the configuration will be saved in the NVRAM of the emulation.

How to run calendar

If the Winchester disk image hasn't been used for some time (14 days), it may be necessary to run calendar.

To run calendar

  • switch the Apollo emulation into Service Mode (see below) and reset or restart the emulation
  • press Return (in the MAME window or in the Terminal window) until the MD version and prompt (">") are shown
  • enter ex calendar and wait
  • enter w to select the Winchester disk
  • check and eventually change the timezone
  • check and eventually change date and time
  • confirm questions as appropriate and wait for the MD prompt to reappear

How to run salvol

If Domain/OS has crashed or has been aborted, it may be necessary to salvage the disk.

To run salvol

  • switch the Apollo emulation into Service Mode (see below) and reset or restart the emulation
  • press Return (in the MAME window or in the Terminal window) until the MD version and prompt (">") are shown
  • enter ex salvol and wait
  • enter w to select the Winchester disk
  • enter return to start salvaging of logical volume 1 with default options
  • confirm Anything more to do? with n and wait for the MD prompt to reappear

How to run dex

The Diagnostic EXecutive (dex) is a comprehensive diagnostic control system for diagnostic products in the offline environment.

To run dex

  • switch the Apollo emulation into Service Mode and set all other Driver Configuration values to Off (see below)
  • reset or restart the emulation
  • press Return until the MD version and prompt (">") are shown (in the MAME window or in the Terminal window)
  • enter ex dex and wait
  • enter help for more info
  • enter auto for full test (confirm errors with C or N); expect the following tests to fail
    • mem.dex Test 140: Parity Checker Test (emulation won't allow more the 40 parity error tests)
    • cpu.dex Test 302: SIO keyboard port test (behavior is ok for DSP3x00, run test with option -nokb)
    • disp.dex Test 20: Video SYNC Gen. Add. Test (not emulated for Monochrome graphics)
    • win.dex Test 103: Format Bad Track Test (not emulated)
    • win.dex Test 104: Assign Alternate Track Test may fail (not implemented)
    • fpu.dex Test 2: General Instruction (many FPU operations and operands are not yet emulated)

How to run Domain/OS in the DN3x00 emulation

  • start the MAME emulation for dn3500 or dn3000 (resp. dn3500_19i or dn3000_19i) with option -mouse
  • make sure you understand how to ungrab the mouse (see below)
  • if Apollo emulation has been set to Normal Mode Domain/OS will boot without user intervention
  • if Apollo emulation has been set to Service Mode perform the following steps
    • in the MAME window press Return until the MD version and prompt (">") are shown
    • enter ex aegis (or ex domain_os) and wait until the bootshell prompt ")" appears
    • enter go to load as in normal mode (or help for more info)
  • wait until the DM has been started and the DM screen is shown
  • login as user user with empty password (or -apollo- if the registry already has been created)
  • wait for the first pad to appear and then enter shell commands ...
  • see below for the mapping of the Apollo keyboard keys to the PC keyboard function keys
  • to logout press key [F1] to move the cursor into the command window and enter lo
  • to shutdown Domain/OS press key [F1] to move the cursor into the command window and enter shut

How to run Domain/OS in the DSP3x00 emulation

  • start the MAME emulation for dsp3500 or dsp3000 (w/o option -mouse)
  • if Apollo emulation has been set to Normal Mode Domain/OS will boot without user intervention
  • if Apollo emulation has been set to Service Mode perform the following steps
    • in the MAME window or in the Terminal window press Return until the MD version and prompt (">") are shown
    • enter ex aegis (or ex domain_os) and wait until the bootshell prompt ")" appears
    • enter go to load as in normal mode (or help for more info)
  • wait until SPM and MBX Helper have been started
  • enter sh to start the login shell (or help for more info)
  • login as user user with empty password (or -apollo- if the registry already has been created)
  • wait for the shell prompt "$" and then enter shell commands ...
  • enter exit as shell command to logout
  • enter shut to shutdown Domain/OS

MAME Basics

How to stop the emulation

  • in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
  • press [Esc] to stop the emulation

see also Default Keys

How to reset the emulation

  • in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
  • press [F3] to reset the emulation

see also Default Keys

How to restart the emulation

  • stop the emulation (see before) and restart the emulation from the command line, or
  • in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
  • press [Shift] and [F3] to restart the emulation

see also Default Keys

How to suspend the emulation

  • in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
  • press button [P] to pause the emulation
  • press button [P] once again to resume the emulation
  • eventually delete the extra character p in the emulation
  • eventually press [ScrLock] to switch your keyboard back to fully emulated keyboard mode

see also Default Keys

How to ungrab the mouse

If the emulation has been started with option -mouse, the mouse will be grabbed as long as the emulation is running.

Suspend the emulation (see before) to ungrab the mouse. The mouse will be grabbed again, if the emulation is resumed (see before).

How to grab the mouse at runtime

In fullscreen mode the mouse will always be grabbed. This may be used to toggle at runtime between

  • window mode with ungrabbed mouse and
  • fullscreen mode with grabbed mouse

Start the Apollo emulation for DN3x00 with options -window -nomax -nomouse -nounevenstretch and (while MAME is running) press [Alt][Return] to toggle between both modes.

Configuration

MAME Options

The following options in mame.ini or as command line option are useful for running the Apollo emulation:

Option mame.ini command line
unevenstretch 0 -nounevenstretch
window 1 -window
maximize 0 -nomaximize
sound none -sound none
skip_gameinfo 1 -skip_gameinfo

If file mame.ini does not yet exist, run the following command to create a new mame.ini file with default configuration settings:

./mame64 -createconfig

refer to SDL-Specific Commandline Options

Service Mode/Normal Mode

To switch the Apollo emulation between Service Mode and Normal Mode

  • open the Apollo Machine Configuration menu (see below)
  • select and change the value of entry Service/Normal
  • close the menus and reset the emulation (see before)

Apollo Machine Configuration

To check or modify the Apollo Machine Configuration

  • start the emulation for DN3500, DN3000, DSP3500 or DSP3000
  • in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
  • press [Tab] to enter the Internal User Interface
  • press [Cursor Down] to select Machine Configuration and press [Return] to open the Machine Configuration menu
  • the Apollo Machine Configuration menu has the following entries
Entry Description
Service/Normal select Service mode or Normal mode
Graphics Controller select 8-Plane Color, 4-Plane Color or 15" Monochrome graphics controller
(for dn3x00 only, will be ignored for dn3x0_19i and dsp3x00)
German Keyboard select German Apollo keyboard
20 Years Ago ... set default date in the RTC back by 20 years to omit the Nov 2, 1997 problem
of Domain/OS software releases before SR 10.4.1
25 Years Ago ... set default date in the RTC back by 25 years to omit the Nov 2, 1997 problem
of Domain/OS software releases before SR 10.4.1
Node ID from Disk set node ID to value from the logical volume label of the first logical disk volume;
without this option either the node ID from command line option -ni
or the default node ID 12345 will be used
Trap Trace trace all Domain/OS SVC traps in the error log file
FPU Trace trace all FPU operations in the error log file
Disk Trace trace disk I/O in the error log file (obsolete)
Network Trace trace network packets in the error log file (obsolete)
  • press [Cursor Down] or [Cursor Up] to select the proper menu entry
  • press [Cursor Right] or [Cursor Left] to select the proper value
  • press button [Tab] to close the menu
  • press button [F3] to restart the emulation using the new settings
  • press [ScrLock] to switch your keyboard back to in full emulation mode

Notes:

  • the new Machine Configuration setting won't be used unless the emulation has been reset or restarted
  • each system (i.e. DN3500, DN3000, DSP3500 or DSP3000) has its own Machine Configuration settings
  • Warning: entering character p in partial emulation mode will pause (i.e. freeze) the emulation (e.g. for "r cpu")
  • see also Default Keys

Dip Switches

To check or modify the Apollo Dip Switches

  • start the emulation for DN3500, DN3000, DSP3500 or DSP3000
  • in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
  • press [Tab] to enter the Internal User Interface
  • press [Cursor Down] to select Dip Switches and press [Return] to open the Dip Switches menu
  • the following Dip Switches should be shown:
SMS OMTI 8621 disk controller [root:isa1:wdc]
ESDI I/O base 01A0h
Floppy I/O base 03F0h
BIOS control Disabled
BIOS base 0C8000h
Archive Cartridge tape controller SC-499 [root:isa2:ctape]
SC499 I/O base (jumpers A3-A9) 0200h
SC499 IRQ (jumpers IRQ2-IRQ7) IRQ 5
SC499 DMA (jumpers DRQ1-DRQ3) DRQ 1
3COM 3C505 Ethernet Controller [root:isa3:3c505]
3C505 I/O base (jumpers A3-A9) 0300h
3C505 IRQ IRQ 10
3C505 DMA DRQ 6
ROM control Enabled
ROM base 80000h
  • press [Cursor Down] or [Cursor Up] to select a DIP switch
  • press [Cursor Right] or [Cursor Left] to change the value
  • press [Return] to set an entry back to the default value
  • press button [Tab] to close the menu
  • press [ScrLock] to switch your keyboard back to in full emulation mode

Notes:

  • The default DIP switch settings are apropriate for the Apollo emulation. Don't change them.

Keyboard Mapping

The additional special keys of the Apollo keyboard are mapped to the function keys (and some other keys) of the PC keyboard.

Function Keys

F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
SHELL CUT UNDO MOVE INS LINE CHAR SAVE ABORT HELP
CMD COPY PASTE GROW MARK DEL DEL AGAIN READ EDIT EXIT HOLD

Set Num Lock to use the Function keys F1 - F9 and F10 = F0 without Apollo mapping.

Other Keys

PC Keyboard Apollo Keyboard
Insert NEXT WINDOW
Delete POP
Right Window NEXT WINDOW
Menu POP

Cursor keys and Pad scroll keys have been mapped to the numeric keypad too.

How to emulate the German Apollo keyboard

The Multinational Apollo keyboard has some additional keys, a slightly modified layout and some different key labels. To emulate the German Apollo keyboard

  • use a German PC keyboard at your Linux system
  • verify that the file keymaps/km_de_LINUX.map exists (as a copy from the mame source distribution)
  • verify and evenutally correct the following two entries in mame.ini:
keymap      0
keymap_file keymaps/km_de_LINUX.map
  • in the MAME Apollo emulation set the Apollo Machine Configuration German Keyboard to ON and restart the emulation (see before)
  • in DM pads use the left ALT key (or Shift/ALT) to select national characters
  • Note: the MD and the standalone utilities expect a US keyboard (Y and Z must be swapped, other keys may have to be estimated)

Key mapping (German Keyboard):

PC Keyboard Apollo Keyboard
Key Shift Alt Key Shift Alt Shift
3 ß 3 @ 3 @
? \ ? ~ ?
+ * ~ + * + *
¸ } ]
÷ ˆ ÷ I \
ƒ ƒ { [
< > I < > < >

Note: in table read I as |

How to run Domain/OS on a small screen

The Apollo emulation expects a screen size of 1024x800 pixel (for dn3000 and dn3500) resp. 1280x1024 pixel (for dn3000_19i and dn3500_19i) plus around 100 more pixel vertical to display the keyboard mapping, LEDs and the window manager title line.

If your host PC has one of the following screen sizes

  • WXGA Screen (1280x800)
  • XGA Screen (1024x768)
  • SXGA Screen (1280x1024)

it may be preferable to run the emulation in full-screen mode and to select an appropriate view without keyboard mapping and LED display.

To run the emulation in fullscreen mode set option window in mame.ini to 0 or run the emulation with option -nowindow.

To select the appropriate view from the command line run MAME with option -view, e.g.

PC screen Size MAME command line
XGA Screen 1024x768 ./mame64 dn3500 -nowindow -view xga ...
WXGA Screen 1280x800 ./mame64 dn3500 -nowindow -view wxga ...
SXGA Screen 1280x1024 ./mame64 dn3500_19i -nowindow -view sxga ...
SXGA+ Screen 1400x1050 ./mame64 dn3500_19i -view sxga ...

To configure the appropriate view

  • start the emulation for dn3x00 resp. dn3x00_19i
  • in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
  • press [Tab] to enter the Internal User Interface
  • press [Cursor Down] to select Video Options and press [Return] to open the Video Options menu
  • for dn3x00 select WXGA or XGA from the options:
    • Apollo (1024x800)
    • WXGA Screen (1280x800)
    • XGA Screen (1024x768)
  • for dn3x00_19i select SXGA from the options:
    • Apollo 19" Monochrome
    • SXGA Screen (1280x1024)
  • press [Return] to select the entry
  • press [Tab] to close the menu
  • press [ScrLock] to switch your keyboard back to in full emulation mode
  • start Domain/OS and check the display

Software Installation

How to setup the boot ROMs

The boot ROM images for the Apollo emulation reside either in the zip file roms/dn3500.zip or in the directory roms/dn3500).

  • make directory roms/dn3500
  • copy the following files from http://bitsavers.org/bits/Apollo/firmware to roms/dn3500:
    • 3500_BOOT_12191_7.bin
    • 3000_BOOT_8475_7.bin
    • 3000_3C505_010728-00.bin
    • 3000_OMTI_8621_102640-B.bin
    • 5500_BOOT_A1631-80046_1-30-92.bin
    • 2500_BOOT_16182_8.bin
  • and create the zip file with
$ (cd roms/dn3500 && zip -r ../dn3500.zip *)
  • or (if no zip file shall be used) convert the file names in roms/dn3500 to lowercase, i.e.
    • 3500_boot_12191_7.bin
    • 3000_boot_8475_7.bin
    • 3000_3c505_010728-00.bin
    • 3000_omti_8621_102640-b.bin
    • 5500_boot_a1631-80046_1-30-92.bin
    • 2500_boot_16182_8.bin

How to install Domain/OS SR10.4 in a new disk image file

Note: cartridge tape access is very slow (same as the real cartridge tape), be patient when executing software from cartridge tape

$ ls -log /tmp/*.ct
-r--r--r-- 1 53678592 Feb 20  2005 /tmp/019593-001.CRTG_STD_SFW_BOOT_1-REV.A.ct
-r--r--r-- 1 58403328 Feb 20  2005 /tmp/019594-001.CRTG_STD_SFW_1.ct
-r--r--r-- 1 61564928 Feb 20  2005 /tmp/019594-002.CRTG_STD_SFW_2.ct
-r--r--r-- 1 56568320 Feb 20  2005 /tmp/019594-003.CRTG_STD_SFW_3.ct
-r--r--r-- 1 57844224 Feb 20  2005 /tmp/019594-004.CRTG_STD_SFW_4.ct
$
  • start the emulation with a non-existing disk image file and the boot tape image, e.g.
$ rm -f /tmp/dn3500_sr10.4.awd
$ ./mame64 dn3500 -mouse -disk1 /tmp/dn3500_sr10.4.awd -ctape /tmp/019593-001.CRTG_STD_SFW_BOOT_1-REV.A.ct 
  • Note: the mouse will be grabbed; make sure you understand how to ungrab the mouse (see before)
  • open the Apollo Machine Configuration window and set option 25 Years Ago ... to On, all other options to Off and reset or restart the emulation
  • run invol from the boot tape image with options
    • 7 - initialize physical badspot list,
    • 1 - initialize virgin physical volume and
    • 8 - create or modify an os paging file.
> re
> di c
> ex invol
  • run calendar from the boot tape image to set the timezone and check date and time on the disk image file
> re
> di c
> ex calendar
  • run domain_os to start the installation from the boot tape image
> re
> di c
> ex domain_os
 :
Restore complete.
Apollo Phase II Environment   Revision 10.4 RBAK version  Jan 25, 1992  12:58:22 pm

) go
  • enter sh to start a login shell (DSP3x00 only), login with name user and empty password and run minst
sh
login: user
Password: 
$ /install/tools/minst
  • MINST can be run in either of two modes; select Novice mode if unsure
  • select default for all other questions
  • select the appropriate cartridge tape image file, e.g. /tmp/019594-001.CRTG_STD_SFW_1.ct (see #How to use multiple cartridge tape images)
  • proceed for all 4 cartridge tape image files
  • MINST will ask to select a template; enter 11 (i.e. large) to install all
  • MINST may ask Do you wish to select Domain/OS version 10.4 or quit from minst?; confirm with s to install Domain/OS
  • if installation is done, enter shut in the command window to shutdown (resp. CTRL/D and then shut for DSP3500)
  • stop the emulation and save a copy of the new disk image file (gzipped image file will be ~70 MB)
  • proceed with

see also

How to create a new disk image file

  • to create a new 348 MB disk image file start the emulation with a non-existing disk image file
$ rm -f /tmp/new_disk.awd
$ ./mame64 dn3500 -disk1 /tmp/new_disk.awd ...
  • to create a new 156 MB disk image file use the UNIX tool dd and start the emulation
$ dd if=/dev/zero of=/tmp/new_disk.awd bs=1056 count=147312
$ ./mame64 dn3500 -disk1 /tmp/new_disk.awd ...
  • open the Apollo Machine Configuration window and set option 25 Years Ago ... to On, all other options to Off and reset or restart the emulation
  • execute invol (from net, disk, ctape or floppy)
    • for SR10.2 run options
      • 1 - initialize virgin physical volume (will fail, never mind),
      • 7 - initialize physical badspot list,
      • 9 - add to existing badspot list (don't add any entries),
      • 1 - initialize virgin physical volume (once again, will now succeed) and
      • 8 - create or modify an os paging file.
    • for SR10.3 or SR10.4 run options
      • 7 - initialize physical badspot list,
      • 1 - initialize virgin physical volume and
      • 8 - create or modify an os paging file.
  • quit invol, stop the emulation, verify the size of the new disk file image and eventually save a copy (gzipped image file will be ~ 400 kB).

How to use multiple cartridge tape images

To select a different cartridge tape image while the emulation is running

  • if changing the cartridge tape is not requested by software, enter
    • "rbak -dev ct -rewind" in Domain/OS or
    • "RE" in the MD to deselect the current tape image
  • in the MAME window press [ScrLock] to switch your keyboard in partial emulation mode
  • press [Tab] to enter the Internal User Interface
  • select the File Manager and press Return
  • select ctape (ct) and press Return
  • select the appropriate file and press Return
  • close the menu

Administration

How to change the Apollo node ID

The node ID of the Apollo emulation will be be taken from the logical volume label of the first logical disk volume, if option Node ID from Disk has been set in the Apollo configuration (see before). Otherwise the node ID will be taken either from the command line option -ni or default to 12345.

To change the node ID of the Apollo emulation

- the option Node ID from Disk must be set in the Apollo configuration
- the node ID of the Apollo disk image must be changed

To change the node ID of the Apollo disk image

  • start the emulation with a copy of the disk image file
  • switch the Apollo emulation into Service Mode and reset or restart the emulation
  • press Return (in the MAME window or in the Terminal window) until the MD version and prompt (">") are shown
  • enter ex chuvol and wait
  • enter w to select the disk
  • enter the new node ID
  • confirm the value to be used as "original" node ID and wait until chuvol is done
  • confirm Anything more to do? with n and wait for the MD prompt to reappear
  • if the registry already has been created(see below), restart the emulation, start Domain/OS and fix the registry
    • make sure that rgyd is not running (use ps and kill command, if neccessary)
    • start rgyd with the new node ID
    $ /etc/server -p /etc/rgyd -restore_master&
    • remove the old registry
    $ /etc/rgy_admin
              Default object: rgy  default host: dds:dn3500
              State: in service  master  replica list is writable
    rgy_admin: lrep -state
              dds:#0.12345    *** not communicating ****       
    (master)  dds:dn3500      state: in service        2012/04/20.09:35:38    
    rgy_admin: delrep dds:#0.12345 -force
    rgy_admin: quit

  • stop the emulation and eventually save a copy of the disk image file
  • use this disk image file to run the Apollo emulation with the chosen node ID

How to create the registry in Domain/OS

After installing Domain/OS SR10

  • login as user with empty password and start the local location broker (a.k.a RPC daemon)
$ touch /etc/daemons/llbd
  • reboot, login as user with empty password and start the global location broker (first time)
$ /etc/server /etc/ncs/glbd -create -first -family dds -listen dds &
$ touch /etc/daemons/glbd
  • reboot, login as user with empty password and create the registry
$ /install/tools/rgy_create 
$ touch /etc/daemons/rgyd
  • reboot and log-in as root with password -apollo-

Networking

How to set the network capabilities

To access the the TUN/TAP Ethernet interface of the Linux host, MAME must be either run as root (not recommended) or the network capabilities must be set for MAME.

To set the network capabilities for MAME in openSUSE Leap 42.1:

  • install Linux package libcap-progs and libpcap1 e.g. with
  • set and check the capabilities of ./mame64
$ sudo setcap cap_net_raw,cap_net_admin=eip ./mame64
$ sudo getcap ./mame64
mame = cap_net_admin,cap_net_raw+eip
  • run MAME with option -log and verify that the file error.log does NOT contain the following line
... 3c505: apollo_eth_init: Operation not permitted - Ethernet access disabled

How to use the MAME Network Device

On a Linux host the MAME Network Device provides TCP/IP networking between the MAME Apollo emulation and the host PC.

To run MAME with Network Device

  • set the network capabilities for MAME (see before)
  • Get taputil.sh either from the latest MAME source distribution or from github.com
wget https://github.com/bji/libmame/blob/master/src/osd/sdl/taputil.sh
chmod 755 taputil.sh
  • Run taputil.sh as root with option -d to delete or option -c to create the tap/tun device
TAP=tap-mess-${UID}-0
IP_ADDR_HOST=192.168.2.99
IP_ADDR=192.168.2.30

sudo -s ./taputil.sh -d $USER
sudo -s ./taputil.sh -c $USER $IP_ADDR $IP_ADDR_HOST -
  • start the MAME Apollo emulation and execute Domain/OS
  • configure and start TCP/IP in Domain/OS (see below)

How to start TCP/IP in Domain/OS

Before proceeding see also

Note: The following assumes that linux1 is the hostname of the Linux PC where the emulation is running and linux2 is the hostname of a second Linux PC connected with Ethernet to linux1.

  • start the Apollo emulation and log in as user root (with password -apollo-)
  • check and eventually set or change the node name (e.g. to dn3500)
# /etc/lcnode
# /etc/uctnode node_12345
# /etc/ctnode dn3500 12345
# /etc/lcnode
  • setup to start the TCP daemons
# touch /etc/daemons/tcpd
# touch /etc/daemons/inetd 
# touch /etc/daemons/syslogd
  • setup /etc/hosts for your Apollo node dn3500 and the Linux PCs:
# cat /etc/hosts 
127.0.0.1       localhost
192.168.2.30    dn3500
192.168.2.99    linux1
192.168.2.25    linux2
  • add the Linux PCs to ~/.rhosts (substitute user ost with your Linux user name):
# echo "linux1 root" >>.rhosts
# echo "linux2 root" >>.rhosts
# echo "linux1 ost" >>.rhosts
# echo "linux2 ost" >>.rhosts
# chown root .rhosts
# chmod 600 .rhosts
  • check that pseudo ttys exit; if not create them:
# ls -l /dev/ttyp*
# /etc/mkdev /dev pty
  • add some pseudo ttys to /etc/ttys
# echo "ttyp0 none dumb off secure" >> /etc/ttys 
# echo "ttyp1 none dumb off secure" >> /etc/ttys
  • reboot Domain/OS, log-in as user (with password -apollo-) and check networking
$ netstat -i
$ netstat -a
$ /etc/ping linux1 100 5
  • at the Linux PCs
    • login as user root
    • eventually install package rsh
    • enter the commands (with password -apollo-)
$ ping 192.168.2.30
$ rlogin 192.168.2.30 -l root
$ rcp /etc/hosts root@192.168.2.30:/tmp/hosts_from_linux
$ rsh 192.168.2.30 -l root ls -l /tmp/hosts_from_linux

How to setup Apollo Domain Networking

The MAME Apollo emulation may be setup to provide full Apollo Domain services to all Apollo nodes connected to the Ethernet interface eth0 of the MAME host PC.

  • Get taputil.sh either from the latest MAME source distribution or from github.com
wget https://github.com/bji/libmame/blob/master/src/osd/sdl/taputil.sh
chmod 755 taputil.sh

Append the following lines at the end of taputil.sh

# disable ip-forward and proxy_arp
echo 0 > /proc/sys/net/ipv4/ip_forward
echo 0 > /proc/sys/net/ipv4/conf/all/proxy_arp

# duplicate $(TAP) traffic at eth0 and vice versa (i.e. bridge)
socat INTERFACE:$(TAP) INTERFACE:eth0 &

Install the Linux package socat

Run taputil.sh as root with option -d to delete or option -c to create the tap/tun device

TAP=tap-mess-${UID}-0
IP_ADDR_HOST=192.168.2.99
IP_ADDR=192.168.2.30

sudo -s ./taputil.sh -d $USER
sudo -s ./taputil.sh -c $USER $IP_ADDR $IP_ADDR_HOST -

Connect the Ethernet cable from the Apollo workstation(s) to the Ethernet connector of the MAME host PC, set the network capabilities (see before), start the MAME Apollo emulation and verify the Domain Networking operation with the lcnode command:

$ /com/lcnode
 
The node ID of this node is 12345.
1 other node responded.
 
Node ID      Boot time           Current time         Entry Directory

12345   1993/05/12 16:25:08   1993/05/12 16:30:34  //dn3500
1AEA5   1993/05/12 16:21:10   1993/05/12 16:30:33  *** node not catalogued ***

$ /com/ctnode -update
$ /com/lvolfs 1AEA5

  # free   # total   % free         node ID  entry directory
   80752    329388       25           1AEA5   //zorro
$

Notes:

  • a second Linux PC running the MAME Apollo emulation (with a different node ID) maybe used instead of a real Apollo workstation to create a Domain network.
  • an HP Apollo 9000 Series 400 running Domain/OS may be used instead of (resp. additional to) Apollo workstations

Creating Image Files on a real Apollo

How to create a floppy disk image

On a DN3x00 with a floppy disk drive (and ethernet controller):

  • invol floppy (and run calendar)
  • mount floppy (mtvol f)
  • add files and directories as needed
  • unmount floppy (dmtvol f)
  • copy floppy to a disk image file (e.g. /tmp/floppy.afd) with:
$ /bin/cp /dev/dsk/F0d0s1 /tmp/floppy.afd
  • copy the disk image file (i.e. /tmp/floppy.afd) with rcp to your Linux system

Notes:

  • suffix .afd is suggested (for Apollo Floppy Disk)
  • /systest/ssr_util/cpflp should work as well, but has not been tested.
  • the following command can be used to create a new floppy disk image file on a Unix system:
$ dd if=/dev/zero of=/tmp/floppy.afd ibs=16384 count=77

How to create a cartridge tape image

On an Apollo DN3x00 with a cartridge tape drive

  • read file /systest/ssr_util/cptape.hlp
  • insert your (write-protected!) cartridge into the cartridge tape drive
  • make sure that you have 60 MB free space
  • enter the following command to create a tape image file (e.g. in /tmp/tape.act)
$ /systest/ssr_util/cptape -r /tmp/tape.act
  • copy the tape image file to your Linux system and run MAME with option -ct /tmp/tape.act

To create a cartridge tape image using the MAME Apollo emulator, start the emulator with a non-existing tape image file, e.g.

$ ./mame64 dn3500 -disk1 <pathname>.awd -ct /tmp/new_tape.act
  • boot Domain/OS, login as root and run the following commands to save e.g. /sau7 into the tape image file
# cpboot /sys -dev ct
# wbak -dev ct -f 1 -sysboot /sau7
# rbak -dev ct -f 1 -index -all
  • shutdown Domain/OS and save a copy of the cartridge tape image file

Notes:

  • suffix .act is suggested (for Apollo Cartridge Tape)
  • For older cartridges the tension belt inside the cartridge tends to break or start slipping nowadays - hopefully your cartridge tapes are still readable.