  This document written 1994/09/19 by Kenneth R. Kress
  and edited 1994/11/03 and 1994/11/15 by Randolph Bentson,
  and on 1994/11/13 by Marcio Saito
  Initial software by Randolph Bentson

  This document contains installation information for the Cyclades
  Cyclom-8Y 8-port and Cyclom-16Y serial extenders.  This version
  applies to kernel distribution 1.1.50 and other similar versions.
  (Reports have been received that they work with 1.1.64 and a change
  has been made to support 1.1.65.)

  1.  Introduction

  The Cyclades makes several serial boards compatible with Linux: the
  Cyclom-8Ys, Cyclom-8Yb, Cyclom-8Yo, and Cyclom-16Y. Each contains
  Cirrus Logic CD-1400 RISC-based chips that take the place of the UARTs
  in more conventional serial-port extenders. It is possible to add 256
  ports to a Linux system using a combination of Cyclom boards.  (It's
  not known how well the rest of the kernel can handle this many ports.)

  This new driver is able to determine the irq used by a board,
  thus relieving the user from one more configuration hassle.
  (By default, the driver looks in four likely places for the
  board, so if you've got one, chances are it'll be found.)

  The setserial program, used to interrogate traditional serial
  ports, provides nearly the same amount of information about
  the Cyclom boards.  (The limit is due to the different IRQ
  handling, the lack of traditional UARTs, etc.)  The program
  can also be used to extend the range of signalling rates up
  to 115 Kbaud.

  2.  Obtaining kernel patches

  The cyclades patches are available by ftp from sunsite.unc.edu under
  /pub/Linux/kernel/patch/serial as cyc.1.33.tgz.  This file contains
        text files:
            README (this file)
            WARNING
            cyclades.lsm
        source files:
            linux/drivers/char/cyclades.c
            linux/include/linux/cyclades.h
        patches for:
            linux/include/linux/serial.h,
            linux/include/linux/interrupt.h
            linux/drivers/char/Makefile
            linux/drivers/char/tty_io.c
            linux/kernel/irq.c
            linux/init/main.c
            linux/config.in
            /dev/MAKEDEV
            and setserial.c

  These have been used to build a kernel for version 1.1.50.  Since the
  changes to the serial character processing has been stable for a while,
  this code should work for other kernel versions as well.  (I encourage
  you to advise me of necessary changes.)

  3.  Applying patches to kernel source files

  Uncompress and untar cyclades.tgz somewhere (such as /tmp):

       ----------------------------------------------------------------------
       > mkdir /tmp/cyc
       > cp cyclades.tgz /tmp/cyc
       > cd /tmp/cyc
       > zcat cyclades.tgz | tar xvf -
       ----------------------------------------------------------------------

  Distribute the new source files.

       ----------------------------------------------------------------------
       > mv cyclades.c /usr/src/linux/drivers/char
       > mv cyclades.h /usr/src/linux/include/linux
       ----------------------------------------------------------------------

  Change to the root of the linux sources ((this is a change from
  the 1.32 and earlier versions)) and make the other changes to
  copies of your kernel files.  (If you have RCS, it is a good
  idea to check in these files.)

       ----------------------------------------------------------------------
       > cd /usr/src/linux
       > patch -p0 < /tmp/cyc/Makefile.pat
       > patch -p0 < /tmp/cyc/tty_io.pat
       > patch -p0 < /tmp/cyc/interrupt.pat
       > patch -p0 < /tmp/cyc/serial.pat
       > patch -p0 < /tmp/cyc/main.pat
       > patch -p0 < /tmp/cyc/irq.pat
       > patch -p0 < /tmp/cyc/config.pat
       ----------------------------------------------------------------------

  Patch the MAKEDEV utility in the /dev directory.

       ----------------------------------------------------------------------
       > cd /dev
       > patch -p0 < /tmp/cyc/MAKEDEV.patch
       ----------------------------------------------------------------------

  Locate the source for setserial and apply the patch.  (If you don't,
  it will report the chip type as "UNKNOWN" but seems to have no other
  problems.  In any case, this step can be deferred until the kernel
  has been rebuilt.)

       ----------------------------------------------------------------------
       > cd "location of setserial source"
       > patch -p0 < /tmp/cyc/setserial.patch
       ----------------------------------------------------------------------


  4.  Making and installing a new kernel

  Move to the /usr/src/linux directory and make a new kernel:

      ----------------------------------------------------------------------
      > cd /usr/src/linux
      > make config
      > make dep
      > make zImage
      ----------------------------------------------------------------------

  Twenty or so minutes later ... copy the zImage to its final resting
  place.

       ----------------------------------------------------------------------
       > mv zImage /
       ----------------------------------------------------------------------

  Edit the /etc/lilo.conf file to support booting this new kernel.  (I
  have LILO pause for 5 seconds, so I can name an alternate boot kernel.
  After 5 seconds, it defaults to /vmlinuz -- instead of zImage).  Do
  not overwrite the /vmlinuz until you're totally satisfied with this
  kernel, and even then keep a backup kernel!

  For example (/etc/lilo.conf):

      ----------------------------------------------------------------------
           # LILO configuration file
           # generated by 'liloconfig'
           #
           # Start LILO global section
           boot = /dev/sda
           delay = 50
           vga = normal    # force sane state
           ramdisk = 0     # paranoia setting
           # End LILO global section
           #
           # Default Linux bootable partition config begins
           image = /vmlinuz
             root = /dev/sda1
             label = linux
           # Linux bootable partition config ends
           #
           # new Cyclades Linux bootable partition config begins
           image = /zImage
             root = /dev/sda1
             label = cyclades
           # Linux bootable partition config ends
           #
           # DOS bootable partition config begins
           # DOS bootable partition config ends
      ----------------------------------------------------------------------

  And install the new LILO configuration with:

      ----------------------------------------------------------------------
      > liloconfig
      ----------------------------------------------------------------------

  5.  Naming devices

  This driver uses minor numbers 32-255 for major device numbers 19 & 20.
  (You can change the major numbers by changing lines 2295 and 2330:
            cy_serial_driver.major = 19 /* TTY_MAJOR */;
            cy_callout_driver.major = 20 /* TTYAUX_MAJOR */;
  the minor number of the first port is set in line 2296
            cy_serial_driver.minor_start = 32;
  and the number of ports can be extended by extending the
  table just before line 243
            struct cyclades_port cy_port[] = {

  You can use the MAKEDEV utility (which was patched in step 3)
  to build the special device files.

       ----------------------------------------------------------------------
       > cd /dev
       > MAKEDEV ttyC0
       ...
       > MAKEDEV ttyC63
       ----------------------------------------------------------------------


  ---OR---
  you can build the character special files with the commands:

       ----------------------------------------------------------------------
       > mknod /dev/ttyC0 c 19 32
       > mknod /dev/ttyC1 c 19 33
       > mknod /dev/ttyC2 c 19 34
       > mknod /dev/ttyC3 c 19 35
       > mknod /dev/ttyC4 c 19 36
       > mknod /dev/ttyC5 c 19 37
       > mknod /dev/ttyC6 c 19 38
       > mknod /dev/ttyC7 c 19 39

       > mknod /dev/cub0 c 20 32
       > mknod /dev/cub1 c 20 33
       > mknod /dev/cub2 c 20 34
       > mknod /dev/cub3 c 20 35
       > mknod /dev/cub4 c 20 36
       > mknod /dev/cub5 c 20 37
       > mknod /dev/cub6 c 20 38
       > mknod /dev/cub7 c 20 39
       ----------------------------------------------------------------------

  Look at /dev/cua0 and /dev/ttyS0 to determine the appropriate
  ownership and permissions to be applied to these device files.
       ----------------------------------------------------------------------
       > chown root:uucp /dev/cub0
       > chown root:tty /dev/ttyC0
             etc.
       ----------------------------------------------------------------------

  The ttyCx files are for incoming calls; cubx are for dialing out.

  6.  Card models, connectors and cables.

  Cyclom-Y is serial multiport card for ISA/EISA bus. 8 and 16-port
  models are available.

  Each Cyclom-Y card uses 1 IRQ (selectable between 9, 10, 11, 12 or
  15) and a 8-kbytes window of memory address. No I/O address required.
  Make sure that there is no hardware conflict between Cyclom-Y and
  other expansion cards. The factory default settings (0xD4000 address,
  IRQ10) will work for most of the configurations. The driver will
  automaticaly detect any board installed in the 0xD0000 segment.

  The Cyclom-Y models are:

  - Cyclom-8Ys  : 8 ports, RJ-12 connectors (6 wires, no RTS signal).
  - Cyclom-8Yb  : 8 ports, DB-25 connectors in a external box (full-modem).
  - Cyclom-8Yo  : 8 ports, DB-25 connectors in a octopus cable (full-modem).
  - Cyclom-16Y  : 16 ports, DB-25 connectors in a external box (full-modem).

  If you have Cyclom-8Yb, -8Yo, or -16Y with DB-25 male connectors, simply
  use a straight-through DB-25 cable to connect modems or a null-modem
  cable to connect terminals. The TxD, RxD, Gnd, RTS, CTS, DTR and DCD
  signals are provided accordingly to the RS-232 standard interface.

       ----------------------------------------------------------------------
       Cyclom-8Yo/8Ys/16Y            Modem
       DB-25                         DB-25

       TxD 2  ---------------------- 2 TxD
       RxD 3  ---------------------- 3 RxD
       Gnd 7  ---------------------- 7 Gnd
       DCD 8  ---------------------- 8 DCD
       RTS 4  ---------------------- 4 RTS
       CTS 5  ---------------------- 5 CTS
       DTR 20 --------------------- 20 DTR
       ----------------------------------------------------------------------

  If you have the Cyclom-8Ys (RJ-12 or "6-wire RJ11"), the RTS signal is
  not present. There are two ways to overcome this shortcoming: change the
  settings in your modem (by configuring it to ignore the RTS signal) or
  connect the RTS signal to the DTR signal in the modem side (which will
  work in almost all configurations).

       ----------------------------------------------------------------------
       Cyclom-8Ys                   Modem              RJ-12 jack
       RJ-12                        DB-25       (board - female/front view) 

       TxD 2 ---------------------- 2 TxD                 +---+
       RxD 5 ---------------------- 3 RxD             +---+   +---+
       Gnd 3 ---------------------- 7 Gnd           +-+           +-+
       DCD 6 ---------------------- 8 DCD           |               |
       CTS 4 ---------------------- 5 CTS           |               |
       DTR 1 ------------------+--- 20 DTR          +--+-+-+-+-+-+--+
                               |                       6 5 4 3 2 1 
                               +--- 4 RTS
       (*) The pinouts for the RJ-12 connectors are different for hardware
           versions before V4.00. Check the hardware version of your board
           (it is printed on the PCB).
       ----------------------------------------------------------------------

  For more information about connectors and cabling, check the Appendix A
  of the "Installation Guide" booklet that comes with the board. The new
  manuals have nice drawings that shows how to assembly the cables.

  DB-25 straight-through or null-modem cables are easy to find. Probably
  you already have them.

  For RJ-12 connectors, there is no standard for pinouts. You can buy
  RJ-12 to DB-25 converters and wire the pins following the diagram
  above. You will not find ready-to-use converters.

  When wiring RJ-12 cables, be aware that telephone company 6-conductor
  cables normally cross-over the wires. Straight-through cables can be
  found at computer stores. You can also buy a crimper and 6-wire
  connectors and make your own.

  7. Testing the board.

  Once the driver is installed, boot the new kernel and create the devices
  in the /dev directory. The next step is to make sure that the board is
  working.

  Check the driver messages at boot time. There should be messages
  similar to "Cyclom Driver revision XXX date YYY" and "Share IRQ N:".

  If you get these messages, the driver is installed, the board is
  working and there are no hardware conflicts.

  If you have a terminal (or PC with a terminal emulation program),
  connect it to the first port using a null-modem cable (the cable
  that you receive with the Cyclom-8Ys is straigh-through, you will
  need a null-modem adapter to connect it to a terminal). Test the
  port by typing:

       ----------------------------------------------------------------------
       date > /dev/cub0
       ----------------------------------------------------------------------

  If the terminal is configured at 9600,8,N,1, the output of the
  'date' command should appear at the terminal screen. If the terminal
  is configured at a different speed, you should get at least some
  garbage.

  If you have a modem, attach it to the first socket of the board using
  the supplied RJ-DB connector and cable (for Cyclom-8Ys) or a straigh-
  through cable (DB-25 connector). Test it with:

       ----------------------------------------------------------------------
       > kermit -l /dev/cub0
       > connect
       > at
       ----------------------------------------------------------------------

  If you don't get any error messages and you don't get a response. Type
  at&v. This should get you a printout of the modem's settings. If
  nothing happens and the modem lights do not flicker, exit back to the
  kermit command line and try another line:

       ----------------------------------------------------------------------
       (CTRL)-\ c
       > set line /dev/cub7
       > connect
       > at
       ----------------------------------------------------------------------

  Assuming the board is installed properly and you've gotten some
  response out of your modem, it's time to make more connectors and
  wires, enabling ports and start using the board.

  8.  Setting up modems

  Setting up a modem is more an art than a science. The following
  describes a working setup of two modems, Taylor UUCP (v1.3) and
  agetty.  Both modems (Zoom and AT&T Dataport), although Hayes-
  compatible, use different command strings. Have your modem manual at
  the ready before proceeding.

       Setting          AT&T Dataport 14.4

       Autoanswer               AT S0=1
       DCD follows data carrier AT &C1
       DTR follows RS-232       AT &D2
       enable RTS/CTS flow      AT \Q3
       enable error correction  AT \N7
       CTS tracks RTS           AT &R0
       Force DSR on             AT &S0
       Hangup signal delay      AT S49=20*

       *-- This seemed to cure WRITE I/O errors I was getting.

  If your Cyclom-Y doesn't have the RTS signal and you can't tie RTS to
  DTR in the connector, then add this to your modem settings:

                            AT&T Dataport 14.4
       Ignore RTS               AT &R1

  save the settings to your default profile:

       AT &W

  verify with:

       AT &V

  Test to make sure you can still talk with the modem. That done, you
  are almost ready to put a getty on the line.

  8.  Troubleshooting

  a) The machine does not boot, the video does not work.

  Remove the Cyclom-Y card from the machine. Check if there is any
  address or IRQ conflict with another expansion card. Remove the
  conflicting hardware or change the address/irq for Cyclom-Y.

  b) Error messages at boot time.

  The command "dmesg|more" will repeat the contents of those
  messages that scrolled by at boot time too fast to be noted.

  If instead of the expected messages, you get something like
  "Could not get board irq" or no card is found by the driver,
  check the dip switches and set one valid configuration (the
  driver will look for the card in the addresses 0xD0000, 0xD2000,
  0xD4000, 0xD6000, 0xD8000, 0xDA000, 0xDC000 and 0xDE000. Look
  for conflicting hardware.

  c) Driver is installed, board is found but nothing go to the terminal.

  Make sure the devices in the /dev directory were correctly created.
  Check the cabling.

  d) Characters are being lost.

  The RS-232 standard describes RTS/CTS in terms of modem-bound
  flow control.  The DTE (Data Terminal Equipment--computer or
  terminal) presents RTS to (Request To Send) and the DTE (Data
  Communication Equipment--modem) responds with CTS.  This was
  commonly used to control half-duplex connections.

  In spite of the standard, many modem manufacturers are now
  using RTS as a reverse-flow-control.  The Cyclom-Y driver
  doesn't do this, but it's worth noting that a fast-enough
  processor won't need this reverse-flow-control.

  There's a modem control option "CRTSCTS" that needs to be set
  before the modem-bound bits will be controlled. Different
  utilities have different methods of setting it.  One can
  do so in gettytab, using stty, etc.  Look for some expression
  of this option in whatever utility you're using for
  establishing your connection.

  You should enable CRTSCTS for that port.  This allows the
  modem to tell the hardware to "stop sending characters for
  a moment."  This can most easily be done in the gettydefs file.

  Design changes to allow use of RTS as reverse-flow-control are
  being considered.

  10.  Performance measurements

  The setserial program can be used with the Cyclom ports to extend the
  range of communication speeds.  When the "spd_hi" option is set, the
  highest speed is mapped to 57600 bits/second and when the "spd_vhi"
  option is set, that speed is mapped to 115200 bits/second.

  Neither the Linux kernel nor the Cyclom boards will permit all of
  the ports to run in both directions at full speed simultaneously,
  according to Bentson. (So don't run out and buy 32 28.8K modems
  tomorrow :-)

  At the 38.4 kbps setting, I've noticed a slight, but significant,
  speed-up in the reception of news batches via UUCP.  My average this
  month is still rising. It is currently 1,696 bps (all bytes
  transfered/total seconds as reported in Taylor Stats file).

  <<<<Note from Bentson:
  The following script was used for testing the earlier driver.  It
  can be expanded pair-wise for each external loopback established.
  If you've got a more complete test, I'd like to try it out.  (Note
  the use of "nice" for the sender.  This appears to help the receiver
  task from being swamped.  As it is, characters are being dropped (or
  the line is throttled) if six or more streams are in simultaneous
  operation.  I don't know if "cat" is using a block read in this
  context, perhaps other programs could perform better.)

    #!/bin/tcsh
    stty 19200 -echo litout cstopb < /dev/ttyC2
    stty 19200 -echo litout cstopb < /dev/ttyC3
    stty 19200 -echo litout cstopb < /dev/ttyC4
    stty 19200 -echo litout cstopb < /dev/ttyC5
    sleep 1
    (cat /dev/ttyC2    > out2; echo 2)&
    (cat /dev/ttyC3    > out3; echo 3)&
    (cat /dev/ttyC4    > out4; echo 4)&
    (cat /dev/ttyC5    > out5; echo 5)&
    date
    (nice +20 cat $1;sleep 1;echo )  > /dev/ttyC2 &
    (nice +20 cat $1;sleep 1;echo )  > /dev/ttyC3 &
    (nice +20 cat $1;sleep 1;echo )  > /dev/ttyC4 &
    (nice +20 cat $1;sleep 1;echo )  > /dev/ttyC5 &
    wait
    date
  >>>>

  11.  Where to turn for help

       Questions? Try:

       Software: Randolph Bentson
                 bentson@grieg.seaslug.org
                +1 206 282 8375

       Document: Ken Kress
                 dsinc!phent!kkress
                 +1 215 345 3119

       Software & Hardware:
                 Marcio Saito
                 Cyclades Corporation
                 cyclades@netcom.com
                 +1 510 770 9727
                 +1 800 347 6601
                 +1 510 770 0355  Fax


