Deleted Added
sdiff udiff text old ( 59093 ) new ( 131988 )
full compact
device_if.m (59093) device_if.m (131988)
1#
1#
2# Copyright (c) 1998 Doug Rabson
2# Copyright (c) 1998,2004 Doug Rabson
3# All rights reserved.
4#
5# Redistribution and use in source and binary forms, with or without
6# modification, are permitted provided that the following conditions
7# are met:
8# 1. Redistributions of source code must retain the above copyright
9# notice, this list of conditions and the following disclaimer.
10# 2. Redistributions in binary form must reproduce the above copyright

--- 7 unchanged lines hidden (view full) ---

18# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24# SUCH DAMAGE.
25#
3# All rights reserved.
4#
5# Redistribution and use in source and binary forms, with or without
6# modification, are permitted provided that the following conditions
7# are met:
8# 1. Redistributions of source code must retain the above copyright
9# notice, this list of conditions and the following disclaimer.
10# 2. Redistributions in binary form must reproduce the above copyright

--- 7 unchanged lines hidden (view full) ---

18# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24# SUCH DAMAGE.
25#
26# $FreeBSD: head/sys/kern/device_if.m 59093 2000-04-08 14:17:18Z dfr $
26# $FreeBSD: head/sys/kern/device_if.m 131988 2004-07-11 16:17:42Z dfr $
27#
28
29#include <sys/bus.h>
30
27#
28
29#include <sys/bus.h>
30
31/**
32 * @defgroup DEVICE device - KObj methods for all device drivers
33 * @brief A basic set of methods required for all device drivers.
34 *
35 * The device interface is used to match devices to drivers during
36 * autoconfiguration and provides methods to allow drivers to handle
37 * system-wide events such as suspend, resume or shutdown.
38 * @{
39 */
31INTERFACE device;
32
33#
34# Default implementations of some methods.
35#
36CODE {
37 static int null_shutdown(device_t dev)
38 {

--- 5 unchanged lines hidden (view full) ---

44 return 0;
45 }
46
47 static int null_resume(device_t dev)
48 {
49 return 0;
50 }
51};
40INTERFACE device;
41
42#
43# Default implementations of some methods.
44#
45CODE {
46 static int null_shutdown(device_t dev)
47 {

--- 5 unchanged lines hidden (view full) ---

53 return 0;
54 }
55
56 static int null_resume(device_t dev)
57 {
58 return 0;
59 }
60};
52
53#
54# Probe to see if the device is present. Return 0 if the device exists,
55# ENXIO if it cannot be found. If some other error happens during the
56# probe (such as a memory allocation failure), an appropriate error code
57# should be returned. For cases where more than one driver matches a
58# device, a priority value can be returned. In this case, success codes
59# are values less than or equal to zero with the highest value representing
60# the best match. Failure codes are represented by positive values and
61# the regular unix error codes should be used for the purpose.
62
63# If a driver returns a success code which is less than zero, it must
64# not assume that it will be the same driver which is attached to the
65# device. In particular, it must not assume that any values stored in
66# the softc structure will be available for its attach method and any
67# resources allocated during probe must be released and re-allocated
68# if the attach method is called. If a success code of zero is
69# returned, the driver can assume that it will be the one attached.
70#
71# Devices which implement busses should use this method to probe for
72# the existence of devices attached to the bus and add them as
73# children. If this is combined with the use of bus_generic_attach,
74# the child devices will be automatically probed and attached.
75#
61
62/**
63 * @brief Probe to see if a device matches a driver.
64 *
65 * Users should not call this method directly. Normally, this
66 * is called via device_probe_and_attach() to select a driver
67 * calling the DEVICE_PROBE() of all candidate drivers and attach
68 * the winning driver (if any) to the device.
69 *
70 * This function is used to match devices to device drivers.
71 * Typically, the driver will examine the device to see if
72 * it is suitable for this driver. This might include checking
73 * the values of various device instance variables or reading
74 * hardware registers.
75 *
76 * In some cases, there may be more than one driver available
77 * which can be used for a device (for instance there might
78 * be a generic driver which works for a set of many types of
79 * device and a more specific driver which works for a subset
80 * of devices). Because of this, a driver should not assume
81 * that it will be the driver that attaches to the device even
82 * if it returns a success status from DEVICE_PROBE(). In particular,
83 * a driver must free any resources which it allocated during
84 * the probe before returning. The return value of DEVICE_PROBE()
85 * is used to elect which driver is used - the driver which returns
86 * the largest non-error value wins the election and attaches to
87 * the device.
88 *
89 * If a driver matches the hardware, it should set the device
90 * description string using device_set_desc() or
91 * device_set_desc_copy(). This string is
92 * used to generate an informative message when DEVICE_ATTACH()
93 * is called.
94 *
95 * As a special case, if a driver returns zero, the driver election
96 * is cut short and that driver will attach to the device
97 * immediately.
98 *
99 * For example, a probe method for a pci device driver might look
100 * like this:
101 *
102 * @code
103 * int foo_probe(device_t dev)
104 * {
105 * if (pci_get_vendor(dev) == FOOVENDOR &&
106 * pci_get_device(dev) == FOODEVICE) {
107 * device_set_desc(dev, "Foo device");
108 * return (0);
109 * }
110 * return (ENXIO);
111 * }
112 * @endcode
113 *
114 * To include this method in a device driver, use a line like this
115 * in the driver's method list:
116 *
117 * @code
118 * KOBJMETHOD(device_probe, foo_probe)
119 * @endcode
120 *
121 * @param dev the device to probe
122 *
123 * @retval 0 if the driver strongly matches this device
124 * @retval negative if the driver can match this device - the
125 * least negative value is used to select the
126 * driver
127 * @retval ENXIO if the driver does not match the device
128 * @retval positive if some kind of error was detected during
129 * the probe, a regular unix error code should
130 * be returned to indicate the type of error
131 * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device()
132 */
76METHOD int probe {
77 device_t dev;
78};
79
133METHOD int probe {
134 device_t dev;
135};
136
80#
81# Called by a parent bus to add new devices to the bus.
82#
137/**
138 * @brief Called by a parent device to allow drivers to add new devices to the parent.
139 *
140 * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA bus driver)
141 * to help populate the bus device with a useful set of child devices, normally by
142 * calling the BUS_ADD_CHILD() method of the parent device. For instance,
143 * the ISA bus driver uses several special drivers, including the isahint driver and
144 * the pnp driver to create child devices based on configuration hints and PnP bus
145 * probes respectively.
146 *
147 * Many bus drivers which support true plug-and-play do not need to use this method
148 * at all since child devices can be discovered automatically without help from
149 * child drivers.
150 *
151 * To include this method in a device driver, use a line like this
152 * in the driver's method list:
153 *
154 * @code
155 * KOBJMETHOD(device_identify, foo_identify)
156 * @endcode
157 *
158 * @param driver the driver whose identify method is being called
159 * @param parent the parent device to use when adding new children
160 */
83STATICMETHOD void identify {
84 driver_t *driver;
85 device_t parent;
86};
87
161STATICMETHOD void identify {
162 driver_t *driver;
163 device_t parent;
164};
165
88#
89# Attach a device to the system. The probe method will have been
90# called and will have indicated that the device exists. This routine
91# should initialise the hardware and allocate other system resources
92# (such as devfs entries). Returns 0 on success.
93#
166/**
167 * @brief Attach a device to a device driver
168 *
169 * Normally only called via device_probe_and_attach(), this is called
170 * when a driver has succeeded in probing against a device.
171 * This method should initialise the hardware and allocate other
172 * system resources (e.g. devfs entries) as required.
173 *
174 * To include this method in a device driver, use a line like this
175 * in the driver's method list:
176 *
177 * @code
178 * KOBJMETHOD(device_attach, foo_attach)
179 * @endcode
180 *
181 * @param dev the device to probe
182 *
183 * @retval 0 success
184 * @retval non-zero if some kind of error was detected during
185 * the attach, a regular unix error code should
186 * be returned to indicate the type of error
187 * @see DEVICE_PROBE()
188 */
94METHOD int attach {
95 device_t dev;
96};
97
189METHOD int attach {
190 device_t dev;
191};
192
98#
99# Detach a device. This can be called if the user is replacing the
100# driver software or if a device is about to be physically removed
101# from the system (e.g. for pccard devices). Returns 0 on success.
102#
193/**
194 * @brief Detach a driver from a device.
195 *
196 * This can be called if the user is replacing the
197 * driver software or if a device is about to be physically removed
198 * from the system (e.g. for removable hardware such as USB or PCCARD).
199 *
200 * To include this method in a device driver, use a line like this
201 * in the driver's method list:
202 *
203 * @code
204 * KOBJMETHOD(device_detach, foo_detach)
205 * @endcode
206 *
207 * @param dev the device to detach
208 *
209 * @retval 0 success
210 * @retval non-zero the detach could not be performed, e.g. if the
211 * driver does not support detaching.
212 *
213 * @see DEVICE_ATTACH()
214 */
103METHOD int detach {
104 device_t dev;
105};
106
215METHOD int detach {
216 device_t dev;
217};
218
107#
108# This is called during system shutdown to allow the driver to put the
109# hardware into a consistent state for rebooting the computer.
110#
219/**
220 * @brief Called during system shutdown.
221 *
222 * This method allows drivers to detect when the system is being shut down.
223 * Some drivers need to use this to place their hardware in a consistent
224 * state before rebooting the computer.
225 *
226 * To include this method in a device driver, use a line like this
227 * in the driver's method list:
228 *
229 * @code
230 * KOBJMETHOD(device_shutdown, foo_shutdown)
231 * @endcode
232 */
111METHOD int shutdown {
112 device_t dev;
113} DEFAULT null_shutdown;
114
233METHOD int shutdown {
234 device_t dev;
235} DEFAULT null_shutdown;
236
115#
116# This is called by the power-management subsystem when a suspend has been
117# requested by the user or by some automatic mechanism. This gives
118# drivers a chance to veto the suspend or save their configuration before
119# power is removed.
120#
237/**
238 * @brief This is called by the power-management subsystem when a suspend has been
239 * requested by the user or by some automatic mechanism.
240 *
241 * This gives
242 * drivers a chance to veto the suspend or save their configuration before
243 * power is removed.
244 *
245 * To include this method in a device driver, use a line like this
246 * in the driver's method list:
247 *
248 * @code
249 * KOBJMETHOD(device_suspend, foo_suspend)
250 * @endcode
251 *
252 * @param dev the device being suspended
253 *
254 * @retval 0 success
255 * @retval non-zero an error occurred while attempting to prepare the device
256 * for suspension
257 *
258 * @see DEVICE_RESUME()
259 */
121METHOD int suspend {
122 device_t dev;
123} DEFAULT null_suspend;
124
260METHOD int suspend {
261 device_t dev;
262} DEFAULT null_suspend;
263
264/**
265 * @brief This is called when the system resumes after a suspend.
266 *
267 * To include this method in a device driver, use a line like this
268 * in the driver's method list:
269 *
270 * @code
271 * KOBJMETHOD(device_resume, foo_resume)
272 * @endcode
273 *
274 * @param dev the device being resumed
275 *
276 * @retval 0 success
277 * @retval non-zero an error occurred while attempting to restore the device
278 * from suspension
279 *
280 * @see DEVICE_SUSPEND()
281 */
125METHOD int resume {
126 device_t dev;
127} DEFAULT null_resume;
282METHOD int resume {
283 device_t dev;
284} DEFAULT null_resume;