====== Apollo FAQ ======

===== Software Installation =====

==== How to setup the boot ROMs ====

  * The boot ROM images for the Apollo emulation reside in the directory roms/dn3500 (if ''rompath'' is set to ''roms'' in mess.ini). 
  * Make directory roms/dn3500
  * copy the following files from http://www.bitsavers.org/bits/Apollo/firmware to roms/dn3500:
    * 3500_BOOT_12191_7.BIN
    * 3000_BOOT_8475_7.BIN
    * 3000_3C505_010728-00.BIN
    * 5500_BOOT_A1631-80046_1-30-92.bin
  * and 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
    * 5500_boot_a1631-80046_1-30-92.bin

==== How to setup the netserver directory tree ====

  * use the following commands to backup the necessary files on your Apollo workstation:

  # cd /
  # tar cf /tmp/netserver-files.tar sau7 sau8 sau14 sau_sys sys/net/netboot sysboot sysboot.m68k

  * copy the backup file /tmp/netserver-files.tar to your Linux system (e.g. with rcp)
  * on your Linux system, create the directory roms/apollo and untar the files, i.e.

  $ cd <your emulation directory>
  $ mkdir -p roms/apollo
  $ (cd roms/apollo && tar xf /tmp/netserver-files.tar)

  * start the DN3x00 emulation in service mode and try the following commands in the MD

  > di e
  > ld
  > ex config
  
Notes:
  * the netserver path name roms/apollo depends on option rompath (e.g. in mess.ini); the trailing directory name apollo is (still) hardcoded in the emulator sources
  * the Domain/OS version of the files in roms/apollo doesn't matter
  * any other Apollo backup file (e.g. an ancient wbak file) may be expanded in roms/apollo (but only SR10.2 and SR10.4 have been tested)

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

Note: cartridge tape access is very slow, 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
  $ ./mess dn3500 -disk1 /tmp/dn3500_sr10.4.awd -ct /tmp/019593-001.CRTG_STD_SFW_BOOT_1-REV.A.ct 

  * open the Apollo Driver Configuration window and set option **20 Years Ago ...** to On 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 below)
  * proceed for all 4 cartridge tape image files
  * MINST will ask to select a template; enter 11 (i.e. large) to install all
  * if installation is done, enter shut in the command window to shutdown (resp. exit 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)

see also
  * http://bitsavers.org/pdf/apollo/008860-A03_Installing_DOMAIN_Software_Mar92.pdf
  * http://www.hunkler.com/aegis.htm

==== 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
  $ ./mess dn3500 -disk1 /tmp/new_disk.awd ...

  * to create a new 156 MB disk image file start the emulation with an empty disk image file

  $ rm -f /tmp/new_disk.awd
  $ touch /tmp/new_disk.awd
  $ ./mess dn3500 -disk1 /tmp/new_disk.awd ...

  * open the Apollo Driver Configuration window and set option **20 Years Ago ...** to On 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.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.

==== 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 MESS 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 Cartridge Tape and press Return
  * select the appropriate file and press Return 
  * close the menu

===== Running the Emulation =====

==== How to run the emulation ====

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

^ System        ^ Apollo  ^ Monitor        ^
| dn3500        | DN3500  | 19" Monochrome |
| dn3500_15i    | DN3500  | 15" Monochrome |
| dsp3500       | DSP3500 | Terminal       |
| dn3000        | DN3000  | 19" Monochrome |
| dn3000_15i    | DN3000  | 15" Monochrome |
| dsp3000       | DSP3000 | Terminal       |
| dn5500        | DN5500  | 19" Monochrome |
| dn5500_15i    | DN5500  | 15" Monochrome |
| dsp5500       | DSP5500 | Terminal       |

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

  $ ./mess dn3000 -mouse -log -disk1 <pathname>.awd -flop <pathname>.afd

Useful command line options:
  * ''-mouse'' - grab mouse input (for acceptable mouse emulation; use this option only for the DN3x00 emulation)
  * ''-nothrottle'' - disable throttling to omit sound problems (in openSUSE 11.3)
  * ''-nosound'' - turn off the keyboard beeper
  * ''-log'' - error messages will be logged in error.log
  * ''-disk1 <pathname>.awd'' - to specify a Winchester disk image file
  * ''-disk2 <pathname>.awd'' - to specify a second Winchester disk image file (i.e. w0:1)
  * ''-flop <pathname>.afd'' - to specify a floppy disk image file
  * ''-ct <pathname>.act'' - to specify a cartridge tape image file

see also http://mess.redump.net/mess:howto#command_line_options

==== How to run config ====

The Apollo emulation must 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 MESS 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.2, August 24, 1989  7:07:28 am
  
         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: NONE                                  
  Peripheral devices: 
         FPU5 -- MC68881/MC68882
         FLP7 -- Floppy disk
         WINCHESTER CONTROLLER TYPE --  SMS/Omti                       
            WIN7 -- Winchester (controller 0  unit 0):  Micropolis 170 MB        
         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.
  * run MD selftest to verify the configuration,  i.e
  > re
  > te

==== 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 MESS 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 MESS 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
  * enter **no** the Anything more to do? and wait for the MD prompt to reappear

==== How to run dex ====

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 MESS window or in Terminal window)
  * enter **ex dex** and wait 
  * enter **help** for more info

==== How to run Domain/OS in the DN3x00 emulation ====

  * start the MESS emulation for dn3500 or dn3000 (resp.  dn3500_15i or dn3000_15i) with 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 MESS 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 if 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 Apollo the keyboard keys to 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 MESS 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 MESS window or in 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 if 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 **exist** as shell command to logout
  * enter **shut** to shutdown Domain/OS 

===== Configuration =====

==== MESS Options ====

Be sure to set the following options in mess.ini or as command line option

^ Option      ^ Value    ^
| video       | opengl   |
| window      | 1        |
| maximize    | 0        |

refer to http://mess.redump.net/mess:howto#command_line_options

==== Service Mode/Normal Mode ====

To switch the Apollo emulation between Service Mode and Normal Mode
  * open the Apollo Driver Configuration menu (see below)
  * select and change the value of entry Service/Normal
  * close the menus and reset the emulation (see before)

==== Apollo Driver Configuration ====

To check or modify the Apollo Driver Configuration
  * start the emulation for dn3500, dn3000, dsp3500 or dsp3000
  * in the MESS window press [ScrLock] to switch your keyboard in partial emulation mode
  * press [Tab] to enter the Internal User Interface
  * press [Cursor Down] twice to select ''Driver Configuration'' and press [Return] to open the Driver Configuration menu
  * the Apollo Driver Configuration menu has the following entries
    * **Service/Normal** Mode (select Service mode or Normal Mode)
    * **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)
    * **Node ID from Disk** (set node ID to value from the logical volume label of the first logical disk volume; without this option the default node ID 12345 is used)
    * **Idle Sleep** (add sleep calls in the Idle Loop of Domain/OS to reduce the CPU usage of the emulation; should be used only for DSP)
    * **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)
    * **Network Trace** (trace network packets in the error log file)
  * 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 Driver 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 Driver 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://mess.redump.net/mess:howto#key_functions

==== Keyboard Mapping ====

== 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 ~/.mess/keymaps/km-de.txt exists (a copy of mess01xx/src/osd/sdl/keymaps/km-de.txt)
  * in ~/.mess/keymaps/km-de.txt the entry for ITEM_ID_EQUALS may have to be changed to:

  ITEM_ID_EQUALS SDLK_WORLD_20 0x15 0xdf '

  * verify and evenutally correct the following two entries in ~/.mess/mess.ini:

  keymap      1
  keymap_file /home/ost/.mess/keymaps/km-de.txt

  * in the MESS Apollo emulation set the Apollo Driver 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 |

===== Creating Image Files on a real Apollo =====

==== How to create a floppy disk image ====

On a real Apollo 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.

==== How to create a cartridge tape image ====

On  a real 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 mess with option -ct /tmp/tape.act

To create a cartridge tape image using the MESS Apollo emulator, start the emulator with a non-existing tape image file, e.g.
  $ ./mess 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.

==== How to create a Winchester disk image ====

You need two Apollo Workstations to create a Winchester disk image:
  * an Apollo DN3x00 (apollo1) with a 156 MB or 348 MB Winchester disk drive to be copied; the disk drive must have no bad blocks.
  * an Apollo workstation or a server (apollo2) with 200 MB (resp. 400 MB) free disk space and an ethernet controller
Steps:
  * boot the Apollo DN3x00 (apollo1) diskless from apollo2
  * if the Winchester disk drive has not yet the desired files,
    * invol the disk drive (and run calendar)
    * mount the disk drive (mtvol w)
    * add files and directories as needed
    * unmount the disk drive (dmtvol w)
  * eventually salvol the disk drive (to be sure that you have a perfect image)
  * copy disk drive data to a disk image file (e.g. /tmp/disk.img) with:
  $ /bin/cp /dev/dsk/W0d0s1 /tmp/disk.img
  * for a 156 MB disk this will take around 1 hour; /tmp/disk.img resides on apollo2
  * copy the disk image file with rcp from apollo2 to your Linux system (on apollo2 the file is /sys/node_data.xxxxx/tmp/disk.img)
  * on the Linux system add the block headers to the disk image files with a java program:
  $ java -jar fixHeader.jar /tmp/disk.img /tmp/disk.awd
  * consider to save a write protected and gzipped copy of /tmp/disk.img and/or /tmp/disk.awd in a save place.
Notes: 
  * suffix .awd is suggested (for Apollo Winchester Disk)
  * /bin/cp /dev/dsk/W0d0s1 ... will abort on the first bad disk block; you need a disk without any bad blocks
  * if /bin/cp fails because of bad block dd with options ''bs=1024 conv=noerror,sync'' will fail as well (bsd4.3 and sys5.3)
  * running fbs on a disk with bad blocks seems to make the disk readable with cp or dd (even if the disk has bad blocks)
  * a disk image tool may be provided in the future, which will copy disk header blocks too and which will handle bad blocks
  * the disk image of a Micropolis or Maxtor 348 MB disk drive may now be used as well

{{tag>sdl mess apollo dn3000 dn3500 dn5500 dn3000_15i dn3500_15i dn5500_15i dsp3000 dsp3500 dsp5500}}

