-----------------------------------------------------------------------
PAO-960616 for FreeBSD 2.2-960501-SNAP
Tatsumi Hosokawa <hosokawa@mt.cs.keio.ac.jp>, Tokyo Japan
-----------------------------------------------------------------------

This package contains the device drivers, the manager daemon, and the
maintainance utilities for PCMCIA cards under FreeBSD 2.2-960501-SNAP.

(BTW, have 2.2-960501-SNAP already had PC-card and APM stuff?  Yes.
 Part of OUR package has been incorporated into 2.2-SNAP, but this
 code and /etc files are based on former version of our package, and
 the integration and documentation is still incomplete.  That's why we
 release the new package for latest snapshot release.)

-----------------------------------------------------------------------
			      Attention

This package is alpha-test package.  If you use this package, please
report to <hosokawa@mt.cs.keio.ac.jp> if possible, whether it works or
not, what environment you're using, what problem has happened, how to
avoid this probem, etc.  Patches are more welcome.  Please put
"[pccard-test]" on the head of the "Subject:" to pick it up easily.
If you can drive new cards, please send me the patches and
pccard.conf.  Thanks!
-----------------------------------------------------------------------

I created a web page for this package.  The URL is,

     http://www.mt.cs.keio.ac.jp/person/hosokawa/freebsd-pcmcia/

If you want to know the "current" status of this packge, please check
it!

-----------------------------------------------------------------------

To install:

1. Extract this package at /usr/src

	# cd /usr/src
	# tar xvfz "package directory"/PAO-960616.tar.gz

2. Backup original /sys file if needed

	# cd /usr/src
	# mkdir sys.ORG
	# cd sys.ORG
	# (chdir ../sys ; tar cf - .) | tar xvf -

3. Apply kernel-patch to kernel source tree

	# cd /usr/src
	# patch -p0 < PAO-960616/2.2-960501-SNAP/sys.patch

4. Copy new laptops.h, pccard.h, clock.h and wavelan.h to
   /usr/include/machine

	# cp /usr/src/sys/i386/include/laptops.h /usr/include/machine
	# cp /usr/src/sys/i386/include/pccard.h /usr/include/machine
	# cp /usr/src/sys/i386/include/clock.h /usr/include/machine
	# cp /usr/src/sys/i386/include/wavelan.h /usr/include/machine

5. Modify kernel config file for your environment

   /usr/src/sys/i386/conf/LEINLEIN is sample configuration file I'm
   using on Digital Hinote Ultra CS433

   * Don't remove "controller crd0" and "device pcic0" !

	# cd /usr/src/sys/i386/conf
	# cp LEINLEIN "your config file name"
	# vi "your config file name"

    For some particular machines such as Digital Hinote, ThinkPad
    230Cs, etc. we prepared specific "options".  If your machine is
    one of them, please uncomment the corresponding line.

6. Compile your kernel

	# config "your config file name"
	# cd ../../compile/"your config file name"
	# make depend
	# make
	# make install

7. Compile the manager daemon and the utility and install them

	# cd /usr/src/PAO-960616
	# cd usr.sbin/pccard/pccardd
	# make
	# make install BINDIR=/usr/sbin
	# cd ../pccardc
	# make
	# make install BINDIR=/usr/sbin

8. Create device files for your pccard slots and APM BIOS

	# cd /dev
	# sh MAKEDEV card0
	# sh MAKEDEV card1
	# sh MAKEDEV apm

9. Install PC-card configuration file and modify it for your
   environment

	PAO-960616/2.2-960501-SNAP/etc/pccard.conf.sample is
	sample config file currently I'm using on my laptops.

	# cp /usr/src/PAO-960616/2.2-960501-SNAP/etc/pccard.conf.sample /etc/pccard.conf
	
10. Modify /etc/sysconfig

	# cd /etc
	# mv sysconfig sysconfig.orig
	# cp /usr/src/PAO-960616/2.2-960501-SNAP/etc/sysconfig /etc

11. Install /etc/rc.pccard, /etc/pccard_ether and /etc/pccard_ether_remove

	# cp /usr/src/PAO-960616/2.2-960501-SNAP/etc/rc.pccard /etc
	# cp /usr/src/PAO-960616/2.2-960501-SNAP/etc/pccard_ether /etc
	# cp /usr/src/PAO-960616/2.2-960501-SNAP/etc/pccard_ether_remove /etc

12. Edit /etc/sysconfig

	# vi /etc/sysconfig

FAQs:

* What does PAO stand for?

	PAO *stands* for nomads :-).

* How to configure the variables in /etc/sysconfig?

	1. apm_enable

		If this variable set to YES, you can use /dev/apm
		application interface, and kernel can handle APM
		events (default: NO).

	2. pccard_enable

		If this variable set to YES, PC-card manager daemon
		starts at bootstrap (default: NO).

	3. pccard_mem

		If you want to use scratch memory for PCIC other than
		DEFAULT (0xd0000), set this variable explicitly
		(default: DEFAULT).

	4. pccard_ether

		List all ethernet interfaces configured in your kernel.
		For example, if you use LEINLEIN as the config file,
		appropriate value of this variable is
			    pccard_ether="ed0 ep0 fe0 sn0"
		(default: NO).

	5. ifconfig_"interface name"

		Set arguments for ifconfig corresponding to all
		interfaces listed in "pccard_ether".  If this variable
		set to "DHCP", DHCP (Dynamic Host Configuration
		Protocol) clients is automatically executed for
		correspoinding interface.  If you want to use "DHCP",
		you must install WIDE-DHCP package in ports/packages
		collection and configure BPF (Berkeley Packet Filter)
		in your kernel (LEINLEIN has this definition).  And,
		don't forget to MAKEDEV bpf? devices.

		(example 1)
			pccard_ether="ed0 ep0 fe0 sn0"
			ifconfig_common="10.0.0.1 netmask 0xffffff00"
			ifconfig_ed0=$ifconfig_common
			ifconfig_ep0=$ifconfig_common
			ifconfig_fe0=$ifconfig_common
			ifconfig_sn0=$ifconfig_common

		(example 2)
			pccard_ether="ed0 nep0 fe0 sn0"
			ifconfig_common="DHCP"
			ifconfig_ed0=$ifconfig_common
			ifconfig_ep0=$ifconfig_common
			ifconfig_fe0=$ifconfig_common
			ifconfig_sn0=$ifconfig_common

	6. defaultrouter

		If you set this variable, default router is
		automatically registered into the routing table when
		you inserted the card, and automatically deleted from
		routing table when you removed the card.  This
		variable is ignored when the ifconfig parameter of
		corresponding interface is set to "DHCP". (default:
		NO)

* How to mount Flash ATA disk?

	I think that most popular purpose of Flash ATA disk for
	FreeBSD laptop user, is to share files between FreeBSD machine
	and MS-DOS palmtops like HP-200LX.  For example, MS-DOS
	filesystem of HP-200LX is usually placed at the first fdisk
	partition of Flash ATA disk. So, if you mount this partision
	(this example assumes Flash ATA disk controller was attatched
	as "wdc1" and Flash ATA disk is attached as "wd1", as defined
	in LEINLEIN and pccard.conf.sample), type

		# mount -t msdos /dev/wd1s1 /mnt

	If you want to do it more easily, make directory /flash for
	this purpose, and add a line like

	/dev/wd1s1         /flash        msdos   rw,noauto 0 0

	into your /etc/fstab (don't forget to add "noauto" option).
	You can mount this partition by simply typing

		# mount /flash

	Don't forget to umount filesystem before removing the cards.

* How to mount SCSI CD-ROM?

	Same as desktops.

		# mount -t cd9660 /dev/cd0a /cdrom

	If you add this line

	/dev/cd0a         /cdrom          cd9660  rw,noauto 0 0

	to /etc/fstab, you can mount SCSI CD-ROM by simply typing

		# mount /cdrom

	Don't forget to umount filesystem before removing the cards.

* How to mount SCSI HDD?

	Same as desktops :-).

* Kernel says that my modem is attached as "sio2", but there are no
  /dev/sio2.  Why?

	Use /dev/ttyd2 or /dev/cuaa2 instead (same as desktops).

* This kernel hangs up when it probes APM BIOS.  Why?

	Some implementations of protected mode APM BIOS has serious
	bugs.  At first, confirm that your laptop has the latest BIOS.
	These days, BIOS'es of many laptops has been updated to fix
	these bugs of protected mode APM BIOS because Windows 95 uses
	it.  If the BIOS is not latest one, update it soon.  Even if
	the BIOS is the latest one, you can "cope with" these problems
	by modifying the kernel source.  If you're a hacker, try to
	solve your problem by adding a new entry in
	/usr/src/sys/i386/include/laptops.h corresponding to your
	machine, and try to solve this problem.  If your problem is
	solved, please send us a report about your solution (and of
	course your environment).  If you're not hacker, boot the
	kernel with "kernel -c" and type simply "disable apm0" :-).

* Failed to probe (or probed correctly, but behaves unstable) PCMCIA
  FAX/Modem cards (or other serial cards).  Why?

	Read "function serial" definition in /etc/pccard.conf and try
	alternative definitions.

* I tried to change IRQ and I/O address of PCMCIA cards by using
  "kernel -c", but it has no effect.  Why?

	"kernel -c" and arguments of "device" and "controller"
	definitions in config file (except the definitions of
	"xxxintr") have no effect to PCMCIA cards.  If you want to
	modify these parameters, edit /etc/pccard.conf.

* Failed to use NE-2000 compatible Ethernet cards while the entries of
  /etc/pccard.conf seems to be correct.  Why?

	Some NE-2000 compatible Ethernet card has weired CIS tupples
	about the description of shared memory address (Accton
	EN-2212, etc.). Adding flags 0x10 at the corresponding entry
	of /etc/pccard.conf.  It diables the use of shared memory and
	force the driver to work in program I/O mode.

     card "PCMCIA" "UE2212"
	     config  default "ed0" any 0x10
	     ether   0xff0 00:00:e8

* My X-Jack Ethernet card can't communicate with other machines in my
  local network.  Why?

	Some people reported that X-Jack Ethernet has such problem,
	but it is not problem with FreeBSD X-Jack Ethernet driver.
	This problem happens under Linux, and even under DOS and
	Windows.  X-Jack Ethernet is incompatible with some particular
	HUBs.  I and some Linux users surveyed this problem.

	Incompatible HUBs:
		Alleid Telesis	CentreCOM MR820TR
		OMRON		LT-HB 8
		TDK		CME-1210A
		TDK		CME-1230

	Compatible HUBs:
		Accton		EtherHub-8sa
                Alleid Telesis	CentreCOM MR-815T
		ASANTE		10T Hub/8
		CONTEC		RT-1008E (Ethernet Repeater)
		D-Link		Hubby
		DEC		small 4 port HUB (unknown type name)
		HP		expensive :-) HUB (unknown type name)
		Melco		LHB-S8 (Stackable 8-ports Hub)
		Planet		EH-500
		Planet		another 5 port HUB (older than EH-500)

* My laptop uses I/O address 0x240 for another device, but I can't
  change I/O address even though I modified corresponding device
  declarations in config file.  How can I change I/O ports?

	Value of I/O address in config file is "dummy".  If the card
	is allocated I/O ports from I/O pool, please modify following
	line of /etc/pccard.conf.

	io	0x240-0x2e0 0x300-0x360

	For example, modify it as

	io	0x300-0x360

	it won't use 0x240-0x2e0.  If the card is allocated I/O ports
	according to their CIS tupples, change config index number
	(see "config" declaration in /etc/pccard.conf) to other
	indices.  For example, Ratoc REX-5588 Ethernet card has
	following tupples (dumped by "pccardc dumpcis").

--------------------------------------------------------------------------
Tuple #16, code = 0x1b (Configuration entry), length = 8
    000:  08 08 ea 60 00 01 1f ff
	Config index = 0x8
	Card decodes 10 address lines, full 8/16 Bit I/O
		I/O address # 1: block start = 0x100 block length = 0x20
Tuple #17, code = 0x1b (Configuration entry), length = 8
    000:  09 08 ea 60 20 01 1f ff
	Config index = 0x9
	Card decodes 10 address lines, full 8/16 Bit I/O
		I/O address # 1: block start = 0x120 block length = 0x20
Tuple #18, code = 0x1b (Configuration entry), length = 8
    000:  0a 08 ea 60 40 01 1f ff
	Config index = 0xa
	Card decodes 10 address lines, full 8/16 Bit I/O
		I/O address # 1: block start = 0x140 block length = 0x20
Tuple #19, code = 0x1b (Configuration entry), length = 8
    000:  0b 08 ea 60 60 01 1f ff
	Config index = 0xb
	Card decodes 10 address lines, full 8/16 Bit I/O
		I/O address # 1: block start = 0x160 block length = 0x20
Tuple #20, code = 0x1b (Configuration entry), length = 8
    000:  0c 08 ea 60 80 01 1f ff
	Config index = 0xc
	Card decodes 10 address lines, full 8/16 Bit I/O
		I/O address # 1: block start = 0x180 block length = 0x20

		    ..........repeats............

Tuple #39, code = 0x1b (Configuration entry), length = 8
    000:  1f 08 ea 60 e0 03 1f ff
	Config index = 0x1f
	Card decodes 10 address lines, full 8/16 Bit I/O
		I/O address # 1: block start = 0x3e0 block length = 0x20
--------------------------------------------------------------------------

	This card specifies I/O address explicitly.  For example, if
	you use config index 0xc, I/O address 0x180 is used.  If you
	want to use 0x3e0 as I/O address, you must specify 0x1f as
	config index.  I'm planning to extend pccardd to treat such
	cards automatically, but you must specify config index
	manually with current version of our PC-card package.

* My laptop uses IRQ 10 for another device, but I can't change IRQ
  even though I modified correspondig "device" declaration in config
  file.  How can I change IRQ?

	If the corresponding entries in /etc/pccard.conf specifies IRQ
	explicitly, modify that value.  For example,

	card "PCMCIA LAN MBH10304  ES" "  01"
		config	0x1a "fe0" 5
		ether	0x32c 00:c0:d0

	this entry uses IRQ 5 explicitly.  If you want to use IRQ 7
	for this card, modify "config" declaration as

		config	0x1a "fe0" 7

	If the entry uses dynamic IRQ allocation ("any" for IRQ), the
	IRQ is allocated from free IRQ pool.  Free IRQ pool is defined
	at "irq" declaration of /etc/pccard.conf.  By default, 

	irq	10 11

	is defined as the free IRQ pool.  If your machine uses IRQ 10
	or IRQ 11 for other devices, modify this list.  You must
	declare free IRQs more than the number of slots.  (So, if your
	machine has four PC-card slots, you must prepare more than
	four free IRQs!)

TODO (Please help us!):

1. Qlogic SCSI driver.
2. Future Domain SCSI driver.
3. Multifunction cards.
4. Unstability problems of serial cards on particular machines.
5. Patches to if_ed.c for some quasi-compatible cards (ex. Socket EA 
   Ethernet).
6. Cooperative operation between APM and PC-card driver.

List of Companies that donated their hardware to our project:
* Sumitomo Shouji Co. donated Yamaha Infoshuttle ISDN card.
* Planet Japan Co. donated PCMCIA Ethernet card Smart COM 3500.

List of Companies that gave us information about their products:
* Contec Co. gave us datasheet of Ethernet card C-NET(PC).
* IBM Japan Co. gave us datasheet of IBM King PCIC Chip.
* Yamaha Co. gave us hardware information about Infoshuttle ISDN 
  card.

I'm thankful to these companies for their help and support to our
project.


Thanks to:

Andrew McRae <amcrae@cisco.com> (for the original pccard package)
Nate Williams <nate@sri.MT.net>
Atsuo Ohki <ohki@gssm.otsuka.tsukuba.ac.jp>
Gardner Buchanan <gbuchanan@shl.com> (for sn driver)
Jim Binkley <jrb@cs.pdx.edu> (for wlp driver)
Members of BSD-nomads Mailing List
	Especially,
	Naoki Hamada <nao@tom-yam.or.jp> (for ep driver)
	Hidetoshi Kimura <h-kimura@tokyo.se.fujitsu.co.jp> (for aic driver)
	T. Matsutsuka <matsu@cs.titech.ac.jp> (for spc driver)
	Hidetoshi Kimura <h-kimura@tokyo.se.fujitsu.co.jp> (for fe driver)
	DOTEGUCHI Masahiro <xdote@rp.open.cs.fujitsu.co.jp> (for pccard daemon)
	Akihiro Hirano <hirano@dsp.cl.nec.co.jp>
	Kunikazu Yoda <yoda@ais.kudpc.kyoto-u.ac.jp>
	Toshihisa Eto <eto@ai.cs.fujitsu.co.jp>
	Hajimu UMEMOTO <ume@iabs.hitachi.co.jp>
And many alpha-testers....

Tatsumi Hosokawa
