Subversion Repositories w11

# $Id: w11a_os_guide.txt 547 2013-12-29 13:10:07Z mueller $

Guide to run operating system images on w11a systems

  Table of content:

    1.  I/O emulation setup
    2.  FPGA Board setup
    3.  Rlink and Backend Server setup
    4.  simh simulator setup
    5.  oskits
        a. Unix systems
        b. DEC operating systems

1. I/O emulation setup ----------------------------------------------------

   All UNIBUS peripherals which exchange data (currently DL11, LP11, PC11, RK11)
   are currently emulated via a backend process. The communication between 
   FPGA board and backend server can be via

   - Direct USB connection using a Cypress FX2 USB controller
     - is supported on the nexys2 and nexys3 FPGA boards
     - much faster than serial port connections (see below)
     - also allows to configure the FPGA over the same USB connection

   - Serial port
     - via direct (/dev/ttySx) or via a USB-RS232 adapter. A direct connection
       is limited to 115k Baud on most PCs, while a connection via a USB-RS232 
       adapter was tested up to 460k Baud. A USB-RS232 adapter is thus highly 
       recommended
     - via integrated USB-RS232 adapter, like on nexys3 board. This is much 
       faster, allows bitrates up to 2 M Baud.
    
     Notes: - A USB-RS232 cable with a FTDI FT232R chip, like the cable offered
              by FTDI as US232R-100 works fine.
            - A USB-RS232 cable with a Prolific Technology PL2303 chip simply
              never gave reliable connections for higher Baud rates.
            - The rest assumes that a USB-RS232 cable with FTDI chip is used
            - A 460k Baud connection gives in practice a disk throughput of 
              about 20 kB/s. This allows to test the system but is a bit slow 
              to real usage.  In an OS with good disk caching like 2.11BSD the 
              impact of such a 'slow disk' is actually smaller than the bare 
              numbers suggest.
            - On older linux kernels (prior 2.6.32) it is essential to set the
              latency timer for the FTDI USB-RS232 cable to 1 ms (from the 
              power up default of 16 ms), e.g. with
                sudo $RETROBASE/tools/bin/set_ftdi_lat USB0 1
              For linux kernel 2.6.32 or newer the default is 1 ms already.

2. FPGA Board setup -------------------------------------------------------

   - Using Cypress FX2 USB controller for configuration and rlink communication
     - for nexys2
       - connect USB cable to mini-USB connector (between RS232 and PS/2 port)
     - for nexys3
       - connect USB cable to micro-USB connector labeled 'USB PROG'

   - Using serial port for rlink communication
     - for s3board and nexys2
       - connect the USB-RS232 cable to the RS232 port
     - for nexys3
       - connect USB cable to the micro-USB connector 'UART' 
         (next to the 5 buttons)
     - connect a JTAG programmer (e.g. Xilinx USB Cable II) to JTAG pins

   - Configure the FPGA
     - if Cypress FX2 port is connected load design with
         make <sys>.jconfig
     - otherwise use impact with
         make <sys>.iconfig

3. Rlink and Backend Server setup -----------------------------------------

   All examples below use the same basic setup

   - setup vt100 emulator windows

       cd $RETROBASE/tools/oskit/<oskit-name>
       telnet_starter -d DL0 &
       telnet_starter -d DL1 &

   - setup rlink connection using ti_rri backend server via the ti_w11 
     quick start wrapper script. Ensure that all 8 switches on the board
     are in the indicated positions (SWI=...). The concrete boot script
     name <boot-script> is given in the following sections

     [for n2,n3 over fx2:]
       SWI = 00000100
       ti_w11 -u     @<oskit-name>_boot.tcl

     [for s3,n2 over serial:]
       SWI = 00000010
       ti_w11 -tu0,460k,break,xon   @<oskit-name>_boot.tcl
     [for n3 over serial:]
       SWI = 00000010
       ti_w11 -tu0,2M,break,xon     @<oskit-name>_boot.tcl
   
4. simh simulator setup ---------------------------------------------------

   Sometimes it is good to compare the w11a behaviour with the PDP-11 software
   emulator from the simh project (see http://simh.trailing-edge.com/).

   Under $RETROBASE/tools/simh two setup files are provided with configure
   simh to reflect the w11a setup as close as possible:
   - setup_w11a_min.scmd
     Very close the current w11a state when it runs on an S3BOARD
     - processor: 11/70, no FPP, 1 Mbyte
     - periphery:   2 DL11, LP11, RK11, PC11
   - setup_w11a_max.scmd
     Planned configuration for the w11a, in addition
     - processor: 4 Mbyte memory (as on Nexys2, Nexys3,...)
     - periphery: DZ11, RL11/RL02, RK70/RP06, TM11/TU10

   Startup scripts are provided with each oskit. They call the w11a_max
   configuration, so will show in the emulator what w11a can do when
   finished.

   All examples below use the same basic setup

   - setup vt100 emulator window for 2nd DL11

       cd $RETROBASE/tools/oskit/<oskit-name>
       telnet_starter -s -d DL1 &

       {Note: the -s ensures that the port numbers used by simh are taken!}

   - start the simulator

     pdp11 <oskit-name>_boot.scmd

5. oskits -----------------------------------------------------------------

   Ready to be used 'oskits' are provided under
     $RETROBASE/tools/oskit/<oskit-name>

   The tarballs with the disk images are provided from a web server
   and have to be installed separately.

5a. Unix systems -----------------------------------------------------

   Legal and license issues:

     Ancient UNIX systems for the PDP-11 can now be freely used under the
     'Caldera license'. 2.11BSD was released 1992 under the 4 clause BSD 
     license. Taken together

       - Unix V1 to V7
       - all BSD Unix versions for PDP-11

     can be freely distributed and used for non-commercial purposes.   

   Two oskits are currently provided:

     - unix-v5_rk: Unix V5 System on RK05
     - 211bsd_rk:  2.11BSD system on RK05
   
   For further details consult the README_<oskit-name>set.txt file in the
   oskit directory.

5b. DEC operating systems --------------------------------------------
   
   Legal and license issues:

     Unfortunately there is no general hobbyist license for DEC operating 
     systems for PDP-11 computers. The 'Mentec license' commonly understood 
     to cover the some older versions of DEC operating systems, for example
       - RT-11 V5.3 or prior
       - RSX-11M V4.3 or prior
       - RSX-11M PLUS V3.0 or prior
     on software simulators, most notably on the 'simh' suite. 

     HOWEVER: THIS LICENSE DOES NOT COVER THE USAGE OF THESE HISTORIC DEC 
              OPERATING SYSTEMS ON ANY 'REAL HARDWARE' IMPLEMENTATION OF A 
              PDP-11. SO USAGE ON THE W11 IS *NOT* COVERED BY THE 
              'Mentec-license'. 

   Some oskits are provided with systems sysgen'ed to run on a configuration 
   like the w11a.

   - Feel free to explore them with the simh simulator.
     The boot scripts for simh are included ( <kit>.simh )
   
   - In case you happen to have a valid license feel free to try them
     out the W11A and let the author know whether is works as it should.
     For convenience the boot scripts are also included ( <kit>.tcl ).

   Three oskits are currently provided

     - rsx11m-31_rk: RSX-11M V3.1 on RK05
     - rsx11m-40_rk: RSX-11M V4.0 on RK05
     - rt11-40_rk:   RT-11 V4.0   on RK05

   For further details consult the README_<oskit-name>set.txt file in the
   oskit directory.