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