FreeBSD 2.x.x Cyclades Cyclom Z Driver

1.14   Beta Release 2/21/98


/* Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. The name of the contributors may not be used to endorse or promote 
 *    products derived from this software without specific prior written 
 *    permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *

Author's Notes

	- This driver uses __FreeBSD_version < 300000 to recognize 2.x
	  systems, and otherwise assumes that its a 3.X box. As of
	  3.0-971022-SNAP, this hasn't been changed from 225000 in 
          osreldate. Personally, I think this is wrong. But, I'm not in 
          charge. Anyhow, be aware of this in case you have problems
          compiling.

	- This driver is not usable in systems that have both Z- and Y-
	  style Cyclades cards, as the cy and cz driver use the same 
	  major number. This may be fixed by altering the major device
	  number in lcz.h. Look for CDEV_MAJOR. Make sure
	  it doesn't conflict with anything else.

	- This driver has been in use to test modems for almost 11 months
	  now. So far, its worked well, and a baud rate of 115200 really
	  will send up to 115200 to the modem across multiple ports (tested
	  to 32 ports at 115200 in a pentium pro 200, up to 64 should still be
	  ok). For known problems, see BUGS, below.

	- This device has been tested with modems through 115200. If anyone 
	  knows of any modems that to > 115200 on their DTE port, let me know.
	  I'd love to try the faster speeds. Serial connections of up to 920K
	  have been achieved and sustained.

Limitations
	- The driver should support up to the number of cz devices specified
	  in your config file. The maximum number of boards allowed is over
	  8000. The maximum number of ports per board is 256. The number
	  of boards will be dynamic in some future release.

	- Most programs don't support 230K, 460K, and 920K DTE speeds. With 
	  this driver, select 50 baud for 230K, 75 baud for 460K, and 150 
	  baud for 920K. 50, 75, and 150 baud (true speed) is not made
	  available for this card. (Besides, who the hell is going to dump 
          a few hundred dollars on a serial card, then run the ports at 
	  150 baud?) 

BUGS
	- Currently, no major bugs are known.


DEVICES USED
		ttyCXYY		-	Call in device
		ttyCiXYY	- 	Call in initial state device
		ttyClXYY	-	Call in lock state device
		cuaCXYY		- 	Call out device
		cuaCiXYY	- 	Call out initial state device
		cuaClXYY	-	Call out lock state device



OPTIONS IN KERNEL CONFIGURATION

		options CZINT     - will run the driver in interrupt mode.
				    Note: The boards are shipped from Cyclades
				    in polled I/O mode by default. Use 
				    cyctest.exe (provided by Cyclades) to 
				    change this. System performance differences
				    between polled I/O mode and interrupt 
				    mode are minimal on fast machines when 
				    the card(s) are busy. When the card is 
				    not fully utilized, polled I/O mode will 
				    waste CPU cycles probing the board for 
				    work to do.
				
Support / Bug reporting / Distribution
	
	All bugs should be submitted to the author (mcgovern@spoon.beta.com).
Bugs will be addressed as time permits. If you manage to find and fix a 
problem, submit diffs, or a very long email describing your changes, and why
you think it needs to be changed, to the above addresses. Changes, or
modifications of the changes, should be incorporated in to the next
release of the driver.

	If you've managed to lay your hands on the Release Notes, but don't
have the driver, it can be found at ftp://www.beta.com/pub/cz.tgz

	You may also wish to try the Cyclades site, at ftp://ftp.cyclades.com/.

Extra Utilities
	An extra utility, fwbuild, has been provided for
assisting in the upkeep of the driver. It is built using the provided
Makefile, which supports the "all" and "clean" tags. It's purpose and usage
is described below.

Fwbuild Utility

	fwbuild.c has been provided in order to allow the user to upgrade the
version of firmware used by their Cyclades Cyclom-Z card(s). This program will
create an include file that can then be compiled in to the kernel (with
the driver), and loaded at the next boot. Typically, one would replace the
zlogic.cyz file, then type "fwbuild zlogic.cyz zfirm.h z_fw". This will
create the file zfirm.h, using the firmware from zlogic.cyz, and storing
it statically as the variable z_fw, which is the default variable used by
the driver for the firmware image.
	By generating multiple .h files with different variable names, it
is possible to include some or all of the images in the driver. Currently,
however, the driver will only used the image stored as z_fw. In the future,
the driver may have a mechanism for supporting multiple images.

INSTALLATION NOTES

Some people have complained that recent installation notes have been poor
or nonexistent. This is because that recent releases are supposed to have
been rolled in to the FreeBSD main tree, so a typical user isn't supposed
to have to install it themselves.

However, if you find yourself in this boat, you must:

Add the contents MAKEDEV.ADD someplace in /dev/MAKEDEV. I usually put it
after the line which reads "ttyc?)" , but anyplace after the line which reads:
"wt*)" should be ok.

Add the contents of files.i386.ADD to /usr/src/sys/i386/conf/files.i386. This
can go almost anywhere in the file. I usually put it just before the line that
reads:

i386/scsi/93cx6.c		optional	ahc	device-driver

With both files, location can vary, so long as you don't put it someplace
unintelligent, like between two or more lines that are supposed to be together.

After that, copy cz.4.gz in to /usr/share/man/man4. Then, read the man page
to continue the installation.

Thank should be it!
