Generating the system
=====================

Originally the system was developed and built under CP/M, then under RSX180
itself, but nowadays it is cross-generated from Linux using the same CP/M
toolset with a suitable CP/M emulator.

The Makefile in the top-level directory of the project is used to automate
the building process.

Some of the toolset utilities were written for Linux, and the Makefiles
make use of Unix shell commands to e.g. copy, rename and delete files. 
Under Windows you may be able to use e.g. CygWin, but I haven't tried that.


Pre-requisites
--------------

- John Elliott's zxcc CP/M emulator (http://www.seasip.demon.co.uk/Cpm/)

- The CP/M utilities from the Tools/cpm directory:

  * ZSM4 Macro-Assembler V4.7
  * Digital Research's LINK 1.31
  * TKB task builder 2.33
  * Object Code Librarian LBR V2.06

- The Linux utilities from the Tools/linux directory:

  * cksboot
  * sym2inc
  * vol180

- A C compiler (e.g. gcc) to build the Linux utilities.


Steps
-----

1. Compile the Linux tools:

     make linux-tools

2. Install zxcc and copy the CP/M utilities to a place where zxcc can find
   them.

3. Edit the inc/sysconf.inc file to select e.g. type of terminal driver, etc.
   (normally you'll need to change only the TTMPX setting)

4. Ensure all the directories contain the latest version of the include
   files:

     make update-incs

5. Build the kernel image:

     make system

   This command also builds the floppy and hard disk bootstrap programs.

   The kernel image resides on the system partition (first 64K of memory)
   and contains the kernel itself, the system common, the startup code,
   the device drivers, the initialization task, the loader task and the
   filesystem task.

6. Build the system libraries:

     make libs

7. Build MCR and the Indirect Command Processor:

     make cli

8. Build the system utilities:

     make utils

   This will build the MCR external commands, the privileged utilities,
   and PIP, RMD, TED, VDO, ZAP.

   Note: DR Link may complain about an 'Unrecognized Item' while linking
   certain utilities. That's because it does not recognize one particular
   ZSM4 extension (IDENT pseudo-op), and the warning can be safely ignored.

9. Build the program-development applications:

     make progdev

   This will build MAC (ZSM4), TKB, MKT, LBR and BASIC.

10. Optionally, build the test programs and a few simple ASCII games
    (the games require a VT100 or similar):

     make test
     make games

Steps 5 to 10 above can be done with a single 'make all' command.


Creating a bootable floppy image
--------------------------------

1. Create a bare-bone disk image:

     make disk-image

   This creates a 3.5" 1.44M floppy image with several empty directories,
   copies the kernel image and the startup command file to it, installs
   the bootloader, etc.

2. Rename the just-created disk image (not done by the Makefile as a safety
   measure to avoid overwriting any existing image):

     mv new.img floppy.img

3. Copy the system files, utilities, help files and program development
   applications:

     make copy-system
     make copy-utils
     make copy-help
     make copy-progdev

   Note: The vol180 application may output a bunch of 'File not found'
   messages. That is normal, since the copy script tries first to delete
   any existing files before copying the new ones, and at this point the
   disk image is pretty much empty.

4. If desired, copy the test programs, BASIC examples, and the ASCII games:

     make copy-basic
     make copy-test
     make copy-games

5. Configure the system image:

     make sysvmr

The steps 3 and 4 above can be done with a single 'make copy-all' command.

Once the floppy image is ready, it can be copied to a physical floppy disk:

  dd if=floppy.img of=/dev/fd0

For best performance, format the floppy first under CP/M, so the sectors
will have the optimum interleave value for the P112 hardware. Otherwise,
disk accesses will be *really slow*.


Running under an emulator
-------------------------

If you do not own a P112, you can still run RSX180 under Michal Tomek's
z180emu (https://github.com/mtdev79/z180emu) which emulates a number of
Z180-based systems, including the P112.

In addition to the disk image created above, you will need a copy of the
P112 ROM (http://p112.sourceforge.net/index.php?downloads#rom or
http://http://stack180.com/P112%20Downloads.htm).

Following the emulator's instructions, rename the floppy and ROM images,
or create a soft link:

  ln -s floppy.img p112-fdd1.img
  ln -s p112romv58.bin p112rom.bin

Then, start the emulator and *two* copies of the terminal program (the
emulation will only start after both connections are established):

  putty & putty & ./p112

Putty settings for serial port 0:

  Session:
    Host Name:                localhost
    Port:                     10180
    Connection type:          Raw
  Terminal:
    Implicit CR in every LF:  off
    Implicit LF in every CR:  off
    Local echo:               off
    Local line editing:       off

Putty settings for serial port 1:

  Session:
    Host Name:                localhost
    Port:                     10181
    Connection type:          Raw
  Terminal:
    Implicit CR in every LF:  off
    Implicit LF in every CR:  off
    Local echo:               off
    Local line editing:       off

The very first time the emulator is run, the NVRAM of the P112 will contain
invalid data and therefore the floppy disk will not boot. To enter the ROM
setup use the S command ('=' is the P112 ROM prompt):

  =S
  --- DS-1302 RAM invalid, entering config...
  
  
      (D)ouble, (F)ull, (H)alf CPU Speed   [F] : F
      Additional (0..3) Memory Wait States [2] : 2
      Additional (0..3) IO Wait States     [3] : 3
  
      Select rate from:
        0=300 bps,  1=600 bps,  2=1200 bps,  3=2400 bps
        4=4800 bps, 5=9600 bps, 6=19.2 kbps, 7=38.4 kbps
      Choice  [5] : 7
  
      Hardware Flow Control? (Y/N)      [N] : 
  
      Floppy Drive 0:
        Drive Type (0=8", 1=5"/40Trk, 2=5"/80Trk, 3=3.5")  [3] : 3
        High-Density Drive? (Y/N)      [Y] : Y
        Motor Control Needed? (Y/N)    [Y] : Y
        Head Load Time in mS (4..60)   [4] : 
        Drive Step Rate in mS (1..15)  [3] : 
  
      Floppy Drive 1:
        Drive Type (0=8", 1=5"/40Trk, 2=5"/80Trk, 3=3.5")  [3] : 3
        High-Density Drive? (Y/N)      [Y] : Y
        Motor Control Needed? (Y/N)    [Y] : Y
        Head Load Time in mS (4..60)   [4] : 
        Drive Step Rate in mS (1..15)  [3] : 
  
      Select Hard Drive Type from:
        0=(None)        1=ACB-4000       2=Seagate SCSI
        3=Conner SCSI   4=Quantum SCSI   5=Maxtor SCSI
        6=Syquest SCSI  7=GIDE (IDE/ATA)
      Choice  [7] : 7
      Number of Logical Cylinders       [4096] :
  
      Number of Logical Heads [1..255]  [16] :
  
      Logical Sectors Per Track         [16] :
  
  
      AutoBoot Function:
        0 = None  1=Floppy  2=SCSI  3=GIDE
      Choice  [None] : 1
  
  A. CPU Speed         : Full
  B. Add. Memory Waits : 2
  C. Add. I/O Waits    : 3
  D. Console Data Rate : 38.4 kbps, HFC: N
  E. Floppy Drive 0    : 3.5" HD, DS, Mtr Ctl,
                         4 mS Hd Ld, 3 mS Steps
  F. Floppy Drive 1    : 3.5" HD, DS, Mtr Ctl,
                         4 mS Hd Ld, 3 mS Steps
  G. Hard Drive Type   : GIDE (IDE/ATA)
  H. Logical Cylinders : 4096
  I. Logical Heads     : 16
  J. Logical Sctrs/Trk : 16
  K. AutoBoot Select   : Floppy
  
     RETurn to Exit, ESCape to Set and Restart: <ESC>
  
      (Configuration Complete)

Note that you have to exit with Escape and not with Return for the changes
to be saved. The P112 will reboot and this time will load the system from
the floppy:


  SMC IO chip identified (FDC37C665GT): configuring
  ROM v5.8 Dated: 13 Dec 2016  CPU clock: ??-Unknown-??MHz
  RAM available: 1024kB. From 00000 to FFFFF
          ROM shadowed into 1st 32kB
  
  
  
  P112 1024K RSX180 V6.14
  
  >RED DY0:=LB:
  >RED DY0:=SY:
  >MOU DY0:
  >@SY0:[SYSTEM]STARTUP.CMD
  >tim
  15:22:09 26-Jan-2020
  >set /colog=on
  >set /colog/nocoterm
  >pip [syslog]*.*/pu:5
  >upt
  Up 0 days, 0 hours, 0 minutes and 10.56 seconds.
  >@ <EOF>
  >

You can now login on the second terminal, etc.

The current version uses an account file, and thus a password is required
to login. The pre-built images have the following accounts:

  username  password
  --------  --------
  SYSTEM    rsx180
  USER
  TEST      test
  BASIC     basic
  GAMES     games

Note that user names are case-insensitive, but passwords are not!

To shutdown RSX180, use the SHUTUP program:

  >run $shutup
  RSX180 SHUTDOWN PROGRAM
  
  Enter minutes to wait before shutdown: 0
  OK to shutdown? [Y/N]: y
  
  SHUTUP -- System shutdown initiated -- 26-Jan-2019 16:53:01
  SHUTUP -- All further logins are disabled
  
  26-Jan-2020 16:53:02 System is now shutting down

  >SET /COLOG=OFF
  >DMO DY0:/DEV

  SHUTUP -- Operation complete

Exit the emulator with ^\ so the P112 configuration gets saved.


Installing on a hard disk partition
-----------------------------------

Although RSX-180 can be run from a floppy and still exhibit acceptable
performance, running the system from a hard disk partition will give it the
benefit of faster disk data transfers and access to a large disk space.

If you are running RSX180 under the P112 emulator, then you need to create
first an empty hard disk image, e.g.:

  ./makedisk 4 ide00.dsk

Next, start the emulator, enter the P112 ROM setup and specify the correct
disk geometry (type 4 above has 977 cylinders, 5 heads and 16 sectors).

Steps:

1. Create an empty partition with FDISK. You need to do this under CP/M or
   UZI180, as there is no RSX180 version of FDISK at this point. The partition
   type does not matter, as RSX180 will recognize all hard disk partitions
   (I normally set it to D8, as future versions of the INI utility may enforce
   this). Set the bootable flag of the partition with FDISK if you want to
   boot later RSX180 from that partition.

2. Boot RSX180 from floppy. To prevent the P112 from trying to boot from the
   hard disk, press Return to get the ROM prompt as soon as the corresponding
   message is displayed. Then use the Z 1 command to boot from the floppy:

     =Z 1

     ...

3. Use the INI command to initialize the partition. Be sure to specify the
   correct device name and unit number for the partition you created (DU0:
   for first partition, DU1: for second, etc.), e.g.:

     >ini du2:

4. Use the MOU command to mount the just-created filesystem, e.g.:

     >mou du2:

   At this point it will contain a minimum set of system files and only two
   directories: MASTER and SYSTEM.

5. Use PIP to copy the contents of the SYSTEM directory of the floppy to
   the same directory on the hard disk:

     >pip du2:[system]=sy:[system]*.*/cd

   The /CD switch is used to preserve the file creation date.

6. If you want the partition to be bootable, then you need to copy the system
   image SYSTEM.SYS from the MASTER directory of the floppy disk to the hard
   disk (there may be already an empty SYSTEM.SYS file, delete it first) and
   to configure it accordingly with VMR. Then use the /WB option of the INI
   command to update the boot loader map, e.g.:

     >pip du2:[master]system.sys;*/de
     >pip du2:[master]system.sys=sy:[system]rsx180.sys/cd
     >pip du2:[master]system.sym=sy:[system]rsx180.sym/cd
     >asn du2:=lb:
     >asn du2:=sy:
     >cd system
     >ins vmr
     >vmr @sysvmr
     >ini du2:/wb
     >asn =lb:
     >asn =sy:

   Don't forget to set the bootable flag of the partition with FDISK as
   well as explained in step 1, or else the P112 ROM will not boot from it.

7. Use UFD to create any necessary user directories, e.g.:

     >ufd du2:[help]/owner=[1,2]
     >ufd du2:[basic]/owner=[20,1]
     >ufd du2:[user]/owner=[20,2]
     etc.

To automate the above steps, the distribution floppy image contains a
SYSCOPY.CMD command file in the [SYSTEM] directory that can be used to
duplicate the floppy system on a selected hard disk partition:

  >@syscopy du2:
  >ini du2:"RSX180"
  INI -- All existing data on volume DU2: will be lost, are you sure? [Y/N]: y
  >mou du2:
  >ufd du2:[system]/owner=[1,1]
  >pip du2:[system]=sy:[system]*.*/cd
  >ufd du2:[help]/owner=[1,2]
  >pip du2:[help]=sy:[help]*.*/cd
  >ufd du2:[syslog]/owner=[1,5]
  >ufd du2:[basic]/owner=[20,1]
  >pip du2:[basic]=sy:[basic]*.*/cd
  >ufd du2:[user]/owner=[20,2]
  >pip du2:[user]=sy:[user]*.*/cd
  >ufd du2:[games]/owner=[20,3]
  >pip du2:[games]=sy:[games]*.*/cd
  >ufd du2:[test]/owner=[20,4]
  >pip du2:[test]=sy:[test]*.*/cd
  >ins $vmr
  >asn du2:=sy:
  >asn du2:=lb:
  >set /dir=[system]
  >pip [master]system.sys;*,[master]system.sym;*/de/nm
  >pip [master]system.sys=rsx180.sys/cd
  >pip [master]system.sym=rsx180.sym/cd
  >vmr @sysvmr
  DY0: Loaded
  DY1: Loaded
  DU0: Loaded
  DU1: Loaded
  DU2: Loaded
  DU3: Loaded
  DU4: Loaded
  DU5: Loaded
  DU6: Loaded
  DU7: Loaded
  TT0: Loaded
  TT1: Loaded
  LP0: Loaded
  CT0: Loaded
  CO0: Loaded
  NL0: Loaded
  TI0:
  LB0:
  SY0:
  SYSPAR 5798 00000 10000 MAIN TASK
  LDRPAR 57B0 10000 01000 MAIN TASK
  FCPPAR 5860 11000 03000 MAIN TASK
  GEN    5878 14000 EC000 MAIN SYS
         5920 14000 01000 SUB  (TKTN  )
  LDR... V6.10  57C8 LDRPAR  250 0800 LB0:-00000450 FIXED
  TKTN   02.02  58D8 GEN     250 0E00 LB0:-000001A5 FIXED
  ...RMD V6.14  5D30 GEN     225 3A00 LB0:-000002F4
  SYSFCP V4.1   5890 FCPPAR  200 2600 LB0:-000004F2
  MCR... 02.15  59D0 GEN     160 1400 LB0:-0000016A
  ...MCR 02.19  5A18 GEN     160 3400 LB0:-0000018B
  ...MOU 01.04  5C10 GEN     160 1400 LB0:-00000174
  ...DMO 02.04  5C58 GEN     160 1600 LB0:-00000133
  COT... 01.05  5988 GEN     150 1C00 LB0:-00000505
  SHF... 01.00  5BC8 GEN     105 0400 LB0:-00000543
  ...INS 01.07  5A60 GEN     100 1600 LB0:-0000015F
  ...UFD 01.00  5CA0 GEN     100 1000 LB0:-000001AC
  ...WHO V1.3   5F28 GEN     100 0A00 LB0:-000002EF
  ...CA. 1.65   6120 GEN      90 1A00 LB0:-000002D1
  ...ACS 1.01   5AA8 GEN      70 1200 LB0:-00000518
  ...VDO V3.2   6048 GEN      65 2600 LB0:-00000366
  ...TED 200126 6168 GEN      65 3600 LB0:-00000379
  ...AT. 2.36   5AF0 GEN      64 3C00 LB0:-00000332
  ...INI 02.01  5CE8 GEN      60 2200 LB0:-0000014E
  ...MCE V4.29  5FB8 GEN      60 2C00 LB0:-00000350
  ...HEL 03.04  5B38 GEN      50 2000 LB0:-0000013E
  ...BYE 01.14  5B80 GEN      50 1200 LB0:-0000012A
  ...PIP M0319  5D78 GEN      50 4200 LB0:-00000311
  ...BRO 01.02  5DC0 GEN      50 1800 LB0:-000002C5
  ...MAC ZSM4.1 5E08 GEN      50 6C00 LB0:-0000041A
  ...TKB 2.01   5E50 GEN      50 3E00 LB0:-000003FB
  ...LBR V1.3   5E98 GEN      50 2800 LB0:-000003E1
  ...ZAP V1.1   5EE0 GEN      50 2200 LB0:-00000394
  ...DMP V3.11  5F70 GEN      50 2200 LB0:-00000219
  ...UPT VER1.0 6000 GEN      50 0600 LB0:-000002EC
  ...MOR 4.2    6090 GEN      50 1600 LB0:-000002BA
  ...BAS V02-03 60D8 GEN      50 7800 LB0:-000003A5
  ...MD5 V1.01  61B0 GEN      50 2400 LB0:-0000022A
  ...DCU 01.00  61F8 GEN      50 0C00 LB0:-000002E2
  ...CPU V.2    6240 GEN      50 0800 LB0:-000002DE
  ...CAL V1.00  6288 GEN      50 0C00 LB0:-000001DF
  ...PWD 01.05  62D0 GEN      50 2A00 LB0:-00000454
  POOL=61440:36072:36072
  HOST=P112SBC
  >ini du2:/wb
  >pip [master]system.sym;*/de
  >asn =lb:
  >asn =sy:
  >pip du2:/fr
  
  DU2: has 17553 blocks free, 2927 blocks used out of 20480.
  Largest contiguous space = 17547 blocks.
  2318 index file entries are free, 242 entries used out of 2560.
  
  >dmo du2:
  >@ <EOF>
  >

It takes several minutes to copy the floppy disk contents to the hard disk
partition.

Meanwhile, you can monitor the copy operation from the second terminal. Just
login as any user (e.g. SYSTEM, TEST, BASIC or USER) and enter 'rmd' at the
command prompt. Once RMD is running, press T to switch to the Task Header
screen, then hit Escape to get the RMD command prompt. At the prompt, type
'task=...pip' to monitor the PIP task:

  COMMAND > task=...pip

Back to the Task Header screen, the LUN table information displayed on the
bottom half shows dynamically which file is currently being processed by PIP.

