1.\" pnp(4) - manual page for the scanner device driver `asc' 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$ 32.\" 33.Dd September 7, 1997 34.Dt PNP 4 i386 35.Os FreeBSD 36.Sh NAME 37.Nm pnp 38.Nd support for PnP devices 39.Sh SYNOPSIS 40.Cd controller pnp0 41.Sh DESCRIPTION 42Support for PnP devices in 43.Fx 44allows the user to override the 45configuration of PnP cards, and device drivers to fetch/modify 46parameters in the card's configuration space. 47.Pp 48The manual override mechanism requires the kernel to be compiled with 49.Cd options USERCONFIG. 50In this case, the kernel keeps a table of fixed size (20 entries as a 51default) where configuration data are held for PnP devices. 52Each 53PnP card can contain several independent devices (5 or 6 is not 54unusual). 55.Pp 56By booting the kernel with the 57.Dq Fl c 58flag, commands are available to 59modify the configuration of PnP cards. 60Commands start with the 61sequence: 62.Dl pnp CSN LDN 63where CSN and LDN are the Card Select Number and Logical Device Number 64associated to the device. 65Following this sequence any combination of 66the following commands can be used: 67 68.Bl -tag -width "mmmmmmmmmm"" 69.It Dv irqN line 70Sets the irq line for interrupt 0 or 1 on the card. 71Line=0 means the line 72is unused. 73.It Dv drqN n 74Sets the drq channel used for DMA 0 or 1 on the card. 75Channel=4 means 76the channel is unused. 77.It Dv portN address 78Sets the base address for the N-th port's range (N=0..7). address=0 79means that the port is not used. 80.It Dv memN address 81Sets the base address for the N-th memory's range (N=0..3). address=0 82means that the memory range is not used. 83.It Dv bios 84Makes the PnP device use the configuration set by the BIOS. 85This 86is the default, and is generally ok if your BIOS has PnP support. 87If BIOS is used, then other parameters are ignored except "flags". 88.It Dv os 89Makes the PnP device to use the configuration specified in this entry. 90.It Dv enable 91Enables the PnP device. 92.It Dv disable 93Disables the PnP device. 94.It Dv delete 95Frees the entry used for the device, so that it can be used for 96another device with a different CSN/LDN pair. 97.It Dv flags 98Sets the value of a 32-bit flags entry which is passed to the device 99driver. 100This can be used to set special operation modes (e.g. SB vs. WSS 101emulation on some sound cards, etc.). 102.El 103.Pp 104The current content of the table can be printed using the 105.Ic ls 106command in userconfig. 107In addition to modifications done by the user, 108the table contains an entry for 109all logical devices accessed by a PnP device driver. 110.Pp 111Modifications to 112the table will be saved to the boot image on the filesystem by the 113.Xr kget 8 114command. 115.Pp 116.Sh DEVICE DRIVER SUPPORT FOR PnP 117PnP devices are automatically recognized and configured by the kernel. 118A PnP device is identified by the following data structure: 119.Bd -literal 120struct pnp_device { 121 char *pd_name; 122 char *(*pd_probe ) (u_long csn, u_long vendor_id); 123 void (*pd_attach ) (u_long csn, u_long vend_id, char * name, 124 struct isa_device *dev); 125 u_long *pd_count; 126 u_int *imask; 127 struct isa_device dev; 128}; 129.Ed 130.Pp 131The probe routine must check that the vendor_id passed is a 132recognized one, that any necessary devices on the card are enabled, 133and returns a NULL value in case of failure or a non-NULL value 134(generally a pointer to the device name) unpon success. In the probe 135routine, the function 136.Fn read_pnp_parms 137can be used to check that the logical devices are enabled. 138.Pp 139The attach routine should do all the necessary initialization, enable 140the PnP card to ISA accesses, fetch the configuration, and call the ISA 141driver for the device. 142.Pp 143The following routines and data structures can be used: 144.Bl -tag -width "xxxxxxxxxx" 145.It Dv struct pnp_cinfo 146This data structure (defined in /sys/i386/isa/pnp.h) contains all 147informations related to a PnP logical device. 148.It Fn read_pnp_parms "struct pnp_cinfo *d" "int ldn" 149This function returns the configuration of the requested 150logical device. 151It is not possible to specify a CSN since this function 152is only meant to be used during probe and attach routines 153.It Fn write_pnp_parms "struct pnp_cinfo *d" "int ldn" 154This function sets the parameters of the requested logical device. 155At 156the same time, it updates the entry in the kernel override table. 157Device drivers in general should 158.Em not 159modify the configuration of a device, since either the BIOS or the user 160(through userconfig) should know better what to do. 161In particular, 162device driver 163.Em should not enable 164a logical device which has 165been found disabled, 166since this would defeat the override mechanism in userconfig. 167Device 168drivers may disable a logical device, or a port range, etc, but should 169do so only that particular device or parameter is known to cause 170troubles. 171.It Fn enable_pnp_card void 172This function 173.Em must 174be used in the attach routine 175.Em only , 176before accessing the card's ISA ports/memory address ranges. 177.El 178.Pp 179.Sh SEE ALSO 180.Xr kget 8 181.Sh BUGS 182There is no support for visual configuration of PnP devices. 183It would be nice to have commands in userconfig to fetch the 184configuration of PnP devices. 185.Sh AUTHORS 186.An -nosplit 187PnP support was written by 188.An Luigi Rizzo , 189based on initial work done by 190.An Sujal Patel . 191.Sh HISTORY 192The 193.Nm 194driver first appeared in 195.Fx 2.2.5 . 196