share/man/man4/man4.i386/pnp.4

   1 .\" pnp(4) - manual page for PnP device support
   2 .\"
   3 .\"
   4 .\" Copyright (c) 1997 Luigi Rizzo
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgements:
  16 .\"     This product includes software developed by Luigi Rizzo.
  17 .\" 4. The name of the author may not be used to endorse or promote products
  18 .\"    derived from this software without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  21 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  22 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  25 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  29 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .\" $FreeBSD: src/share/man/man4/man4.i386/pnp.4,v 1.5.2.7 2001/09/25 23:40:30 yokota Exp $
  32 .\"
  33 .Dd September 7, 1997
  34 .Dt PNP 4 i386
  35 .Os
  36 .Sh NAME
  37 .Nm pnp
  38 .Nd support for PnP devices
  39 .Sh SYNOPSIS
  40 .Cd controller pnp0
  41 .Sh DESCRIPTION
  42 Support for PnP devices in
  43 .Fx
  44 allows the user to override the
  45 configuration of PnP cards, and device drivers to fetch/modify
  46 parameters in the card's configuration space.
  47 .Pp
  48 The manual override mechanism requires the kernel to be compiled with
  49 .Cd options USERCONFIG .
  50 In this case, the kernel keeps a table of fixed size (20 entries as a
  51 default) where configuration data are held for PnP devices.
  52 Each
  53 PnP card can contain several independent devices (5 or 6 is not
  54 unusual).
  55 .Pp
  56 By booting the kernel with the
  57 .Dq Fl c
  58 flag, commands are available to
  59 modify the configuration of PnP cards.
  60 Commands start with the
  61 sequence:
  62 .Dl pnp CSN LDN
  63 where CSN and LDN are the Card Select Number and Logical Device Number
  64 associated to the device.
  65 Following this sequence any combination of
  66 the following commands can be used:
  67 .Bl -tag -width "mmmmmmmmmm""
  68 .It Dv irqN line
  69 Sets the irq line for interrupt 0 or 1 on the card.
  70 Line=0 means the line
  71 is unused.
  72 .It Dv drqN n
  73 Sets the drq channel used for DMA 0 or 1 on the card.
  74 Channel=4 means
  75 the channel is unused.
  76 .It Dv portN address
  77 Sets the base address for the N-th port's range (N=0..7). address=0
  78 means that the port is not used.
  79 .It Dv memN address
  80 Sets the base address for the N-th memory's range (N=0..3). address=0
  81 means that the memory range is not used.
  82 .It Dv bios
  83 Makes the PnP device use the configuration set by the BIOS.
  84 This
  85 is the default, and is generally ok if your BIOS has PnP support.
  86 If BIOS is used, then other parameters are ignored except "flags".
  87 .It Dv os
  88 Makes the PnP device to use the configuration specified in this entry.
  89 .It Dv enable
  90 Enables the PnP device.
  91 .It Dv disable
  92 Disables the PnP device.
  93 .It Dv delete
  94 Frees the entry used for the device, so that it can be used for
  95 another device with a different CSN/LDN pair.
  96 .It Dv flags
  97 Sets the value of a 32-bit flags entry which is passed to the device
  98 driver.
  99 This can be used to set special operation modes (e.g. SB vs. WSS
 100 emulation on some sound cards, etc.).
 101 .El
 102 .Pp
 103 The current content of the table can be printed using the
 104 .Ic ls
 105 command in userconfig.
 106 In addition to modifications done by the user,
 107 the table contains an entry for
 108 all logical devices accessed by a PnP device driver.
 109 .Pp
 110 Modifications to
 111 the table will be saved to the boot image on the filesystem by the
 112 .Xr kget 8
 113 command.
 114 .Sh DEVICE DRIVER SUPPORT FOR PnP
 115 PnP devices are automatically recognized and configured by the kernel.
 116 A PnP device is identified by the following data structure:
 117 .Bd -literal
 118 struct pnp_device {
 119         char    *pd_name;
 120         char    *(*pd_probe ) (u_long csn, u_long vendor_id);
 121         void    (*pd_attach ) (u_long csn, u_long vend_id, char * name,
 122                     struct isa_device *dev);
 123         u_long  *pd_count;
 124         u_int   *imask;
 125         struct  isa_device dev;
 126 };
 127 .Ed
 128 .Pp
 129 The probe routine must check that the vendor_id passed is a
 130 recognized one, that any necessary devices on the card are enabled,
 131 and returns a NULL value in case of failure or a non-NULL value
 132 (generally a pointer to the device name) unpon success.  In the probe
 133 routine, the function
 134 .Fn read_pnp_parms
 135 can be used to check that the logical devices are enabled.
 136 .Pp
 137 The attach routine should do all the necessary initialization, enable
 138 the PnP card to ISA accesses, fetch the configuration, and call the ISA
 139 driver for the device.
 140 .Pp
 141 The following routines and data structures can be used:
 142 .Bl -tag -width "xxxxxxxxxx"
 143 .It Dv struct pnp_cinfo
 144 This data structure (defined in /sys/i386/isa/pnp.h) contains all
 145 informations related to a PnP logical device.
 146 .It Fn read_pnp_parms "struct pnp_cinfo *d" "int ldn"
 147 This function returns the configuration of the requested
 148 logical device.
 149 It is not possible to specify a CSN since this function
 150 is only meant to be used during probe and attach routines
 151 .It Fn write_pnp_parms "struct pnp_cinfo *d" "int ldn"
 152 This function sets the parameters of the requested logical device.
 153 At
 154 the same time, it updates the entry in the kernel override table.
 155 Device drivers in general should
 156 .Em not
 157 modify the configuration of a device, since either the BIOS or the user
 158 (through userconfig) should know better what to do.
 159 In particular,
 160 device driver
 161 .Em should not enable
 162 a logical device which has
 163 been found disabled,
 164 since this would defeat the override mechanism in userconfig.
 165 Device
 166 drivers may disable a logical device, or a port range, etc, but should
 167 do so only that particular device or parameter is known to cause
 168 troubles.
 169 .It Fn enable_pnp_card void
 170 This function
 171 .Em must
 172 be used in the attach routine
 173 .Em only ,
 174 before accessing the card's ISA ports/memory address ranges.
 175 .El
 176 .Sh SEE ALSO
 177 .Xr kget 8
 178 .Sh BUGS
 179 There is no support for visual configuration of PnP devices.
 180 It would be nice to have commands in userconfig to fetch the
 181 configuration of PnP devices.
 182 .Sh AUTHORS
 183 .An -nosplit
 184 PnP support was written by
 185 .An Luigi Rizzo ,
 186 based on initial work done by
 187 .An Sujal Patel .
 188 .Sh HISTORY
 189 The
 190 .Nm
 191 driver first appeared in
 192 .Fx 2.2.5 .