Improve the documentation for the various tunables. Document how to

force ISA routing of interrupts.  Warn the user that with ISA routing
of interrupts for PCI devices with more than one slot, polling mode is
in order.  Minor markup fixes as well and some white space/sentence
break changes (I did these as one commit since this file has been in
the tree only 4 days and I doubt that translation has begun).

1 files changed, 65 insertions, 12 deletions

diff --git a/share/man/man4/pcic.4 b/share/man/man4/pcic.4
index c55e386..e466f3b 100644
--- a/share/man/man4/pcic.4
+++ b/share/man/man4/pcic.4
@@ -24,7 +24,7 @@
 .\"
 .\"	$FreeBSD$
 .\"
-.Dd August 21, 2001
+.Dd August 25, 2001
 .Dt PCIC 4
 .Os FreeBSD
 .Sh NAME
@@ -46,6 +46,13 @@ devices attach to either
 or
 .Tn PCI
 bus.
+The
+.Nm
+driver does not support the so called TCIC controllers made by
+databook.
+Nor does it support the MECIA chipset found in some early PC98
+NOTE PC machines.
+The mecia driver now supports that bridge.
 .Pp
 The following
 .Tn ISA
@@ -84,12 +91,14 @@ control system.
 .Tn IBM
 clone of the original i82365sl part, with its own id register value.
 Has no 3.3V ability.
-.Tn IBM KING
+.It IBM KING
 .Tn IBM
 A strange clone of i82365sl.
 This part has many restrictions not found in the i82365sl, plus some
-strange power control.  It has not been tested in ages, but is
-believed to work.
+strange power control.
+It has not been tested in ages, but is believed to work.
+Its use is believed to be confined to model of ISA card, available
+only in Japan.
 .El
 .Pp
 Many other vendors made parts in this arena, but most of them were
@@ -147,19 +156,34 @@ Character device for the
 .Nm
 driver.
 .El
+.Sh MODES OF OPERATION
+The ISA device supports routing ISA interrupts only.
+You cannot share ISA interrupts.
+Every interrupt must be unique.
+.Pp
+The PCI device supports routing ISA or PCI interrupts.
+PCI interrupts are sharable.
+ISA interrupts are not sharable.
+PCI interrupts should be used unless your machine has a specific problem using
+them.
+.Pp
+PCI interrupt routing is the default for PCI devices.
+Some older laptops require ISA interrupt routing to work properly.
+To enable ISA interrupt routing, you must set the tunable
+hw.pcic.intr_path=1 in /boot/loader.conf.
+For the present, unless you have a one slot machine, you should set
+hw.pcic.irq=0 to force polling mode.
+Two slot machines have minor issues with using an ISA interrupt for the
+CSC interrupt.
 .Sh TUNABLES
 .Bl -tag -width 0123456789 -compact
-.It hw.pcic.irq
-Offerrides the IRQ to use for ISA interrupt routing.
 .It hw.pcic.ignore_function_1
 Needed for some, improperly manufacturered pci cards made by orinoco.
 It disables function 1 completely.
 Set to 0 to enable function 1.
 Set to 1 to disable function 1.
-.It hw.pcic.intr_path
-Should pci pcic devices route interrupts via ISA or PCI.
-A value of 1 means default via ISA.
-A value of 2 means route via PCI.
+This tunable generally should not be needed on laptops.
+The default is 0.
 .It hw.pcic.init_routing
 Some machines can tolerate interrupt routing selection at the cardbus
 bridge level.
@@ -168,9 +192,38 @@ Set to 1 to force the chipset to route via parallel pci interrupts (as
 well as a few other little things).
 Set to 0, the default, forces the code to leave these registers as the 
 code finds them.
+Most laptops will not need to set this tunable.
+Many pci cards with cardbus chips on them are believed to need this
+tunable set to 1.
+The default is 0.
+.It hw.pcic.intr_path
+Should pci pcic devices route interrupts via ISA or PCI.
+A value of 1 means route via ISA.
+A value of 2 means route via PCI.
+This is ignored for the ISA device.
+Many older laptops do not have PCI BIOS implementaitons that
+.Fx
+can use to route interrupts properly.
+These laptops may need to set this to 1 and hw.pcic.irq to a value
+(or 0 for polling).
+The default is 2.
+.It hw.pcic.irq
+Overrides the IRQ to use for ISA interrupt routing of the CSC or
+management interrupt.
+If you are using the ISA device, you can set this tunable, or use the
+irq N clause in config file.
+If you are using a PCI device in ISA interrupt mode (see
+hw.pcic.intr_path), then you must set the interrupt with this
+sysctl, or polling mode will be used.
+Due to limitations in the tunable system, only one interrupt can be selected
+for all cards.
+Systems with multiple PCI bridges that need to use ISA routing are encouraged
+to use polling mode on each of the cards.
+The default is 0.
 .Sh HISTORY
 Too long to detail in the man page.
-.Sh AUTHORS
-.An M. Warner Losh Aq imp@FreeBSD.ORG
 .Sh BUGS
 Too many to list.
+Some are the fault of the standard.
+Some are the fault of bad standard compliance.
+Some are Warner's fault.